# 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 模块、类型、权限编码均为增量