break
370fd3e67f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 10m49s
39 lines
3.5 KiB
Markdown
39 lines
3.5 KiB
Markdown
## Context
|
||
|
||
套餐商品已有 `real_data_mb`，套餐使用记录承载真实用量；现有通知以事件投递并按接收人隔离。预警必须是套餐级观测，不能复用运营商通道阈值停机锁。
|
||
|
||
## Decisions
|
||
|
||
- 新增套餐规则和预警表；规则以套餐唯一，预警以套餐使用记录+阈值快照唯一，保存触发时流量、资产/卡/设备、套餐和店铺/业务员快照。
|
||
- 扫描查询当前有效使用记录，按资产汇总真实用量与额度，并选出主套餐规则；用唯一约束和事务创建预警及通知事件，扫描可安全重跑。
|
||
- 不向未来业务员补发：接收人仅在预警创建事务中解析。读侧以资产范围过滤，导出复用现有快照任务。
|
||
|
||
## 管理、扫描与查询动作契约
|
||
|
||
### 规则维护
|
||
|
||
- `POST /package-traffic-alert-rules`：仅超级管理员、平台用户；请求 `package_id`、`threshold_percent`（大于等于 1、小于等于 100，允许小数）、`enabled`、`remark`（最多 500 字符）。套餐必须存在且 `real_data_mb > 0`；同套餐已有规则返回“套餐已存在真流量预警规则”。
|
||
- `PUT /package-traffic-alert-rules/:id`：允许修改阈值、启停、备注；不修改已产生预警快照。停用后扫描不建新预警；启用或降低阈值后不主动回填，仅由下一次扫描按当前有效套餐判断。
|
||
- `GET /package-traffic-alert-rules` 返回套餐、真流量总额度、阈值、启用状态、备注和更新时间。所有成功写操作记录操作者、前后值和时间。
|
||
|
||
### 扫描与预警创建
|
||
|
||
- Worker 只读取当前有效套餐使用记录；按同一资产聚合这些记录的真实已用量与套餐 `real_data_mb`，不读取虚流量、展示流量或运营商通道累计值。主套餐不存在有效规则、总额度不大于零或比例未达阈值时跳过。
|
||
- 对命中主套餐规则的套餐使用记录，在事务中写预警唯一键 `(package_usage_id, threshold_percent_snapshot)`，同时冻结套餐、资产、卡、当前设备、店铺、业务员、真实用量、额度、比例、阈值和触发时间。唯一冲突视为已处理，不重复投递通知。
|
||
- 创建时仅解析当前资产所属店铺的有效业务员；存在时在同一可靠事件链创建一条站内通知，保存预警 ID 作为幂等键；不存在时只保存预警。通知失败进入既有可靠投递恢复，不能删除预警或重新计算快照。
|
||
|
||
### 列表、详情与导出
|
||
|
||
- `GET /package-traffic-alerts`：仅超级管理员、平台用户，先应用既有资产数据范围；支持套餐、店铺、业务员、资产/卡标识、阈值、触发时间和通知投递状态筛选、分页。返回冻结快照与通知结果，当前归属变化不得改写预警事实。
|
||
- `GET /package-traffic-alerts/:id`：同一数据范围校验后返回完整预警快照和通知投递历史；越权与不存在统一按既有资源不可见处理。
|
||
- `POST /package-traffic-alerts/export`：复用异步导出；创建时冻结操作者、筛选、时间范围和可见资产范围。每行对应一条预警，执行时不得扩大范围或重算已冻结流量字段。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 流量数据延迟 → 下次扫描补建，不回写已冻结预警。
|
||
- 多卡设备 → 以使用记录资产归属聚合，不从当前设备反推流量。
|
||
- 扫描并发 → 唯一索引处理同一命中重复创建。
|
||
|
||
## Migration Plan
|
||
|
||
新增成对迁移和索引；隔离环境验证规则启停/降阈值、有效套餐汇总、去重、无业务员、权限导出和 up/down/up。 |