133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
# 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** 任务创建时冻结筛选条件、时间范围与可见资产范围，归属列按执行时当前归属补充
|