fix: some

openspec/changes/add-package-traffic-alert/design.md

@@ -0,0 +1,51 @@
+# Design: 套餐真流量预警前端对接
+
+## 背景
+
+后端已按 `docs/产品迭代8月份/套餐真流量预警_API_前端简版.md` 在测试环境上线 6 个接口（released）。前端需要新增规则配置与预警记录两个页面，并接入既有权限与导出任务体系。本设计记录关键决策。
+
+## 决策
+
+### 1. 页面挂载位置：套餐管理分组
+
+规则数据源是套餐商品（`package_id`），预警记录也按套餐筛选，因此两个页面都挂在既有 `/package-management` 路由分组下，与套餐列表、代理系列授权平级。
+
+- 路由：`/package-management/traffic-alert-rules`、`/package-management/traffic-alerts`
+- 详情：`/package-management/traffic-alerts/detail/:id`（隐藏路由）
+
+### 2. 导出走专用接口 + 专用弹窗，不复用 ExportTaskCreateDialog
+
+既有 `ExportTaskCreateDialog` 调用通用 `POST /api/admin/export-tasks`，而真流量预警导出是专用端点 `POST /api/admin/package-traffic-alerts/export`，请求体为 `format` + 与列表一致的一组筛选参数。因此：
+
+- 新建轻量弹窗（或扩展 `ExportTaskCreateDialog` 支持自定义 submit），展示“基于当前筛选条件全量导出，不仅导出当前分页数据”
+- 提交成功后提示“导出任务已创建”，并提供跳转既有导出任务列表页的入口，下载走既有能力
+- 导出任务列表若按场景过滤，需要新增场景配置；场景枚举值联调时与后端确认后落入 `EXPORT_TASK_SCENE_CONFIG`
+
+### 3. 权限模型
+
+- 遵循八月迭代约定：权限编码集中定义在 `AUGUST_PERMISSIONS.packageTrafficAlert`，页面/按钮通过 `v-permission` + `useAuth().hasAuth` 引用
+- 页面级：`rules_view` / `records_view` 控制菜单与按钮可见性（后端菜单权限同源）
+- 按钮级：规则创建/修改（含启停）、记录详情、导出分别独立编码
+- 403 策略：接口对无权限账号统一返回 403；列表接口 403 时提示“无权限访问”；详情越权按资源不可见处理（复用现有 404 类提示文案），不暴露资源存在性
+
+### 4. 阈值输入校验
+
+- 前端 `ElInputNumber`：`min=1`、`max=100`、`precision=2`
+- 创建时 `threshold_percent` 必填；修改时三字段均可选（后端按传入字段更新）
+- `remark` 创建/修改均限制 500 字符（`maxlength` + 计数器）
+
+### 5. 快照与归属变化展示
+
+- 列表与详情的业务字段均为触发时快照，仅 `business_user_group_names` 为当前值
+- 详情中 `shop_changed_since_trigger` / `owner_changed_since_trigger` 为 `true` 时，用 `ElAlert`（info）提示归属已变化，并展示当前店铺/业务员与快照值
+- 空值约定：无店铺/业务员时字段可能为 `null` 或空数组，统一渲染 `-`（业务员数组 join 展示，空数组显示 `-`）
+
+### 6. 规则列表的 real_data_mb 展示
+
+- `real_data_mb` 为套餐商品当前真流量额度，仅用于配置校验展示（如“按 80% 约对应 x GB”），不作为预警分母
+- 页面以 GB 展示（`/1024`，保留两位小数），避免 MB 数字过长
+
+## 风险
+
+- 记录列表/详情接口字段名未完整给出，联调时以测试环境实际返回为准，类型定义需保留一定弹性（可选字段）
+- 导出任务场景值未给出，若后端未登记场景枚举，导出任务列表页的场景筛选需兼容新值

openspec/changes/add-package-traffic-alert/proposal.md

@@ -0,0 +1,93 @@
+# Change: 新增套餐真流量预警（规则配置 + 预警记录）
+
+## Why
+
+根据 `docs/产品迭代8月份/套餐真流量预警_API_前端简版.md`，后端已在测试环境（`https://cmp-api.boss160.cn`）实现套餐真流量预警能力：套餐商品的真流量使用量达到配置阈值后生成预警记录，并通知对应业务员。共 6 个接口，仅超级管理员/平台账号可访问，其他账号返回 403，通用响应为 `code / data / msg / timestamp`。
+
+当前前端（套餐管理模块）缺少：
+
+1. 真流量预警规则配置入口：查看、创建、修改规则（阈值 1～100 允许两位小数、启停、备注），以及同一套餐商品仅一条规则的限制提示。
+2. 预警记录查看：支持套餐、店铺、业务员、资产类型、资产关键词、阈值、触发时间、通知状态 8 项筛选的列表，触发时快照详情（含归属是否变化提示），以及复用既有异步导出任务体系的记录导出。
+
+此变更完成上述 6 个接口的前端对接。
+
+## What Changes
+
+### 1. API 层
+
+- **新增**: `src/api/modules/packageTrafficAlert.ts`（`PackageTrafficAlertService`，继承 BaseService）
+  - `getAlertRules` — `GET /api/admin/package-traffic-alert-rules`（`package_id`、`enabled`、`page`、`page_size`）
+  - `createAlertRule` — `POST /api/admin/package-traffic-alert-rules`（`package_id`、`threshold_percent`、`enabled`、`remark`）
+  - `updateAlertRule` — `PUT /api/admin/package-traffic-alert-rules/{id}`（`threshold_percent`、`enabled`、`remark`，均为可选）
+  - `getAlertRecords` — `GET /api/admin/package-traffic-alerts`（8 项筛选 + 分页）
+  - `getAlertRecordDetail` — `GET /api/admin/package-traffic-alerts/{id}`
+  - `exportAlertRecords` — `POST /api/admin/package-traffic-alerts/export`（`format` + 与列表一致的筛选参数）
+- **修改**: `src/api/modules/index.ts` — 导出 `PackageTrafficAlertService`
+
+### 2. 类型定义
+
+- **新增**: `src/types/api/packageTrafficAlert.ts` — 规则/记录/导出请求响应类型，字段与接口文档保持 snake_case
+- **修改**: `src/types/api/index.ts` — 导出新类型
+
+### 3. 常量与权限
+
+- **修改**: `src/config/constants/augustIteration.ts` — `AUGUST_PERMISSIONS` 新增 `packageTrafficAlert` 权限组
+  - `trafficAlertRules: 'package_traffic_alert:rules_view'`
+  - `trafficAlertRuleCreate: 'package_traffic_alert:rule_create'`
+  - `trafficAlertRuleUpdate: 'package_traffic_alert:rule_update'`
+  - `trafficAlertRecords: 'package_traffic_alert:records_view'`
+  - `trafficAlertRecordDetail: 'package_traffic_alert:record_detail'`
+  - `trafficAlertExport: 'package_traffic_alert:export'`
+- **新增/修改**: 通知状态枚举常量（1 已通知 / 2 待投递 / 3 投递失败 / 4 未通知（接收人已失效）/ 5 未通知（无有效业务员））及对应 tag 类型映射
+- 若既有导出任务列表需要区分本场景，补充对应导出场景配置（场景值联调时与后端确认）
+
+### 4. 页面
+
+**预警规则页** `src/views/package-management/traffic-alert-rules/index.vue`
+
+- 列表：套餐名称、当前真流量额度（`real_data_mb`，按 GB 展示，仅作参考、不作为预警分母）、阈值百分比、启用状态、备注、更新时间
+- 筛选：套餐（`package_id`）、启用状态（`enabled`，不传查全部）；分页默认 20、最大 100
+- 新增/编辑弹窗：套餐选择器、阈值（1～100，两位小数）、启用开关、备注（最多 500 字符）
+- 约束：同一套餐商品最多一条规则，后端拒绝重复创建时前端展示错误信息
+- 修改规则不影响既有预警快照；停用后扫描不再创建新预警（页面文案说明）
+
+**预警记录页** `src/views/package-management/traffic-alerts/index.vue`
+
+- 筛选：套餐、店铺、业务员、资产类型、资产关键词、阈值（两位小数）、触发时间范围（RFC3339）、通知状态
+- 列表：除 `business_user_group_names` 外均为触发时快照；`notification_status` 按枚举展示
+- 详情：展示快照字段；`shop_changed_since_trigger` / `owner_changed_since_trigger` 为真时提示“触发后店铺/业务员归属已变化”；`null` 或空数组统一显示 `-`
+- 导出：弹窗选择格式（xlsx/csv），携带当前筛选条件调用专用导出接口创建异步任务；创建成功后提示到既有“导出任务列表”下载
+- 越权查询详情：统一按资源不可见处理（与不存在资源一致的提示）
+
+### 5. 路由与菜单
+
+- **修改**: `src/router/routesAlias.ts` — 新增 `TrafficAlertRules`、`TrafficAlerts`、`TrafficAlertDetail` 别名
+- **修改**: `src/router/routes/asyncRoutes.ts` — 套餐管理分组下新增两个子路由（记录详情用隐藏路由）
+- **修改**: `src/locales/langs/zh.json` / `src/locales/langs/en.json` — `menus.packageManagement` 新增 `trafficAlertRules`、`trafficAlerts`、`trafficAlertDetail`
+
+## Impact
+
+### 受影响的规范
+
+- `package-traffic-alert` — 新增能力
+
+### 受影响的代码
+
+- `src/api/modules/packageTrafficAlert.ts`（新增）、`src/api/modules/index.ts`
+- `src/types/api/packageTrafficAlert.ts`（新增）、`src/types/api/index.ts`
+- `src/config/constants/augustIteration.ts`、导出场景/通知状态相关常量
+- `src/views/package-management/traffic-alert-rules/index.vue`（新增）
+- `src/views/package-management/traffic-alerts/index.vue`、`detail.vue`（新增）
+- `src/router/routesAlias.ts`、`src/router/routes/asyncRoutes.ts`
+- `src/locales/langs/zh.json`、`src/locales/langs/en.json`
+
+### 依赖关系
+
+- 依赖后端 6 个接口在测试环境可用（文档标记 released）
+- 复用既有基础设施：`BaseService`/request 封装、`useAuth` + `v-permission`、`PackageSelector`、店铺/业务员选择组件、既有导出任务列表下载能力
+
+### 注意事项
+
+- 文档声明 6 个接口，但简版仅详细给出 4 个（规则列表/创建/修改 + 记录导出）；预警记录列表与详情两个接口以“前端注意事项”的筛选项、快照字段与导出筛选字段为准，字段名在联调时与测试环境核对
+- 全部接口对非超级管理员/平台账号返回 403：菜单可见性由后端菜单权限控制，前端对 403 做友好提示，详情越权按资源不可见处理
+- 无破坏性变更：新增页面、API 模块、类型、权限编码均为增量

openspec/changes/add-package-traffic-alert/specs/package-traffic-alert/spec.md

@@ -0,0 +1,132 @@
+# Package Traffic Alert Specification
+
+## ADDED Requirements
+
+### Requirement: 套餐真流量预警规则列表查询
+
+系统 SHALL 提供套餐真流量预警规则列表查询页面，展示规则与套餐商品关联信息，支持按套餐商品与启用状态筛选和分页。
+
+#### Scenario: 查询全部规则
+
+- **WHEN** 具备权限的用户（超级管理员/平台账号）访问预警规则页面
+- **THEN** 系统调用 `GET /api/admin/package-traffic-alert-rules` 加载规则列表
+- **AND** 列表展示套餐名称、当前真流量额度（`real_data_mb`，按 GB 展示）、阈值百分比、启用状态（含中文状态名）、备注、最近更新时间
+- **AND** 分页默认每页 20 条，最大 100 条
+
+#### Scenario: 按条件筛选
+
+- **WHEN** 用户选择套餐商品或启用状态进行筛选
+- **THEN** 系统携带 `package_id` / `enabled` 查询参数重新加载列表
+- **AND** 不传启用状态时查询全部规则
+
+#### Scenario: 无权限访问
+
+- **WHEN** 非超级管理员/平台账号调用规则接口
+- **THEN** 接口返回 403
+- **AND** 页面展示无权限访问提示，不展示业务数据
+
+### Requirement: 创建套餐真流量预警规则
+
+系统 SHALL 允许管理员为套餐商品创建真流量预警规则，并执行阈值与备注校验；同一套餐商品最多一条规则。
+
+#### Scenario: 成功创建规则
+
+- **WHEN** 用户选择套餐商品，填写阈值百分比（1～100，允许两位小数）
+- **AND** 设置启用状态与备注（最多 500 字符）后提交
+- **THEN** 系统调用 `POST /api/admin/package-traffic-alert-rules` 创建规则
+- **AND** 成功后刷新列表并展示新规则详情（含套餐名称、当前真流量额度、更新时间）
+
+#### Scenario: 阈值校验
+
+- **WHEN** 用户填写的阈值小于 1、大于 100 或超过两位小数
+- **THEN** 前端阻止提交并展示校验错误提示
+
+#### Scenario: 重复规则
+
+- **WHEN** 用户为已存在规则的套餐商品再次创建规则
+- **THEN** 后端拒绝创建
+- **AND** 前端展示后端返回的错误信息，列表保持原状
+
+### Requirement: 修改套餐真流量预警规则
+
+系统 SHALL 允许管理员修改规则的阈值、启用状态与备注；修改不影响既有预警快照，停用后扫描不再创建新预警。
+
+#### Scenario: 修改规则字段
+
+- **WHEN** 用户打开编辑弹窗并修改阈值、启用状态或备注后提交
+- **THEN** 系统调用 `PUT /api/admin/package-traffic-alert-rules/{id}`，仅提交修改的字段
+- **AND** 成功后刷新列表展示最新规则
+
+#### Scenario: 停用规则
+
+- **WHEN** 用户关闭规则的启用开关
+- **THEN** 系统调用修改接口仅提交 `enabled=false`
+- **AND** 页面说明停用后不再产生新预警，既有预警记录保留
+
+#### Scenario: 规则不存在或无权限
+
+- **WHEN** 修改的规则 ID 不存在或用户无权限
+- **THEN** 系统按接口错误处理并展示对应提示
+
+### Requirement: 套餐真流量预警记录列表查询
+
+系统 SHALL 提供预警记录列表页面，支持套餐、店铺、业务员、资产类型、资产关键词、阈值、触发时间范围、通知状态 8 项筛选与分页；列表数据除 `business_user_group_names` 外均为触发时快照。
+
+#### Scenario: 查询预警记录
+
+- **WHEN** 具备权限的用户访问预警记录页面
+- **THEN** 系统调用 `GET /api/admin/package-traffic-alerts` 加载记录列表
+- **AND** 列表展示触发时间、资产信息、套餐、阈值快照、店铺、业务员与通知状态
+
+#### Scenario: 组合筛选
+
+- **WHEN** 用户组合使用任意筛选条件（含两位小数阈值与 RFC3339 触发时间范围）
+- **THEN** 系统携带对应查询参数请求列表，返回满足全部条件的记录
+
+#### Scenario: 通知状态展示
+
+- **WHEN** 记录包含 `notification_status`
+- **THEN** 系统按枚举展示：1 已通知 / 2 待投递 / 3 投递失败 / 4 未通知（接收人已失效）/ 5 未通知（无有效业务员）
+
+#### Scenario: 空值展示
+
+- **WHEN** 记录的店铺或业务员字段为 `null` 或空数组
+- **THEN** 系统统一展示 `-`
+- **AND** `business_user_group_names` 为当前归属值，其余字段保持触发时快照
+
+### Requirement: 查看预警记录详情
+
+系统 SHALL 允许管理员查看单条预警记录的触发时快照详情，并标识触发后店铺/业务员归属是否发生变化；越权查询按资源不可见处理。
+
+#### Scenario: 查看存在的记录
+
+- **WHEN** 用户点击记录打开详情
+- **THEN** 系统调用 `GET /api/admin/package-traffic-alerts/{id}` 展示触发时快照字段
+
+#### Scenario: 归属变化提示
+
+- **WHEN** 详情返回 `shop_changed_since_trigger` 或 `owner_changed_since_trigger` 为 true
+- **THEN** 系统提示触发后店铺/业务员归属已变化
+- **AND** 展示当前归属与触发时快照值的差异
+
+#### Scenario: 越权或不存在
+
+- **WHEN** 用户无权限查看该记录或记录不存在
+- **THEN** 系统统一按资源不可见处理
+- **AND** 展示与记录不存在一致的提示，不暴露资源存在性
+
+### Requirement: 导出套餐真流量达量预警
+
+系统 SHALL 允许管理员按当前筛选条件创建预警记录异步导出任务；导出接口仅创建任务，文件通过既有导出任务列表下载。
+
+#### Scenario: 创建导出任务
+
+- **WHEN** 用户在预警记录页点击导出并选择格式（xlsx/csv）
+- **THEN** 系统携带 `format` 与当前筛选条件调用 `POST /api/admin/package-traffic-alerts/export`
+- **AND** 成功后展示任务信息（`task_id`、`task_no`、状态）并引导用户到既有导出任务列表下载
+
+#### Scenario: 导出范围说明
+
+- **WHEN** 导出弹窗打开
+- **THEN** 系统说明导出基于当前筛选条件全量导出，不仅导出当前分页数据
+- **AND** 任务创建时冻结筛选条件、时间范围与可见资产范围，归属列按执行时当前归属补充

openspec/changes/add-package-traffic-alert/tasks.md

@@ -0,0 +1,40 @@
+# Tasks: 套餐真流量预警前端对接
+
+## 1. API 与类型
+
+- [x] 1.1 新增 `src/types/api/packageTrafficAlert.ts`：规则列表/规则项、创建/修改参数、预警记录列表/记录项、详情、导出请求/响应类型（snake_case，对齐接口文档；记录字段按前端注意事项预留可选）
+- [x] 1.2 `src/types/api/index.ts` 导出新类型
+- [x] 1.3 新增 `src/api/modules/packageTrafficAlert.ts`：`getAlertRules` / `createAlertRule` / `updateAlertRule` / `getAlertRecords` / `getAlertRecordDetail` / `exportAlertRecords` 6 个方法
+- [x] 1.4 `src/api/modules/index.ts` 导出 `PackageTrafficAlertService`
+
+## 2. 常量与权限
+
+- [x] 2.1 `src/config/constants/augustIteration.ts`：`AUGUST_PERMISSIONS` 新增 `packageTrafficAlert` 权限组（rules_view / rule_create / rule_update / records_view / record_detail / export）
+- [x] 2.2 新增通知状态常量：枚举 1-5 文案（已通知/待投递/投递失败/未通知（接收人已失效）/未通知（无有效业务员））及 tag 类型映射
+- [x] 2.3 若导出任务列表需要场景区分，补充真流量预警导出场景配置（场景值与后端确认后更新 `EXPORT_TASK_SCENE_CONFIG` 及 `getExportTaskSceneName`）
+
+## 3. 预警规则页
+
+- [x] 3.1 新增 `src/views/package-management/traffic-alert-rules/index.vue`：筛选栏（套餐选择器、启用状态）、列表（套餐名称、真流量额度 GB、阈值、启用状态、备注、更新时间）、分页（默认 20/最大 100）
+- [x] 3.2 新增/编辑弹窗：套餐选择器（编辑时不可改）、阈值 ElInputNumber（1-100，两位小数，创建必填）、启用开关、备注（≤500 字符带计数）；创建成功提示同一套餐最多一条规则
+- [x] 3.3 启用状态行内开关（调用修改接口，仅传 enabled），文案说明“停用后不再产生新预警，既有预警保留”
+- [x] 3.4 403/错误处理：无权限提示；重复创建等后端错误展示 msg
+
+## 4. 预警记录页
+
+- [x] 4.1 新增 `src/views/package-management/traffic-alerts/index.vue`：筛选栏（套餐、店铺、业务员、资产类型、资产关键词、阈值、触发时间范围、通知状态）、列表（触发时快照字段 + `business_user_group_names` 当前值 + 通知状态 tag）、分页
+- [x] 4.2 新增 `detail.vue`（或详情抽屉）：快照字段展示、`shop_changed_since_trigger` / `owner_changed_since_trigger` 变化提示、空值/空数组显示 `-`、越权按资源不可见处理
+- [x] 4.3 导出弹窗：格式选择（xlsx/csv）+“基于当前筛选条件全量导出”说明，调用 `exportAlertRecords` 携带当前筛选，成功后提示并引导跳转导出任务列表下载
+
+## 5. 路由、菜单与国际化
+
+- [x] 5.1 `src/router/routesAlias.ts`：新增 `TrafficAlertRules` / `TrafficAlerts` / `TrafficAlertDetail`
+- [x] 5.2 `src/router/routes/asyncRoutes.ts`：套餐管理分组下新增规则页、记录页（keepAlive）与隐藏详情路由
+- [x] 5.3 `src/locales/langs/zh.json` / `en.json`：`menus.packageManagement` 新增 `trafficAlertRules` / `trafficAlerts` / `trafficAlertDetail`
+
+## 6. 联调与验收
+
+- [ ] 6.1 测试环境（`https://cmp-api.boss160.cn`）联调 6 个接口，核对记录列表/详情实际字段名并修正类型
+- [ ] 6.2 权限验证：超级管理员/平台账号正常访问；其他账号 403 提示符合预期；详情越权按资源不可见
+- [ ] 6.3 边界验证：阈值 0.99/1/100/100.01 校验、备注 500 字符、同套餐重复创建、空店铺/业务员展示 `-`、导出任务创建后可在导出任务列表下载
+- [x] 6.4 ESLint / Stylelint / `vue-tsc` 类型检查通过