break
d5bcda94fe
新增 000228 迁移：规则表 tb_package_traffic_alert_rule（每套餐商品至多一条，无软删除，package_id 非部分唯一约束）、达量预警快照表 tb_package_traffic_alert（以主套餐使用记录 + 阈值快照为唯一键， 触发时冻结用量、额度、比例、阈值、到期时间、归属与资产快照），并为 tb_package_usage 新增扫描 范围部分索引 idx_package_usage_alert_scope；down 在预警表存在数据时阻断回滚。 新增规则维护接口 GET/POST/PUT /api/admin/package-traffic-alert-rules（仅超级管理员与平台账号）： 创建校验套餐存在且真流量额度大于零，阈值为 1%～100% 的两位小数；修改只影响后续扫描，不回填也 不改写既有预警快照；全部写操作记录操作者、前后值与时间。 新增每日 06:00（Asia/Shanghai）扫描任务 package:traffic:alert:scan，与套餐临期扫描共用 data_cleanup 队列：按资产汇总当前有效套餐的真流量，分子取使用记录真已用量、分母取使用记录真总量快照，命中 主套餐规则阈值时在同一事务创建预警与可靠通知事件；重复执行以唯一冲突视为已处理，不重复投递， 不建停机锁、不调用运营商。 新增预警列表、详情与异步导出 GET /api/admin/package-traffic-alerts、GET /api/admin/package-traffic-alerts/:id、 POST /api/admin/package-traffic-alerts/export，列表与详情一律读冻结快照；新增通知类型 package.traffic.alert 与受控目标 package_traffic_alert_detail，目标解析仅对超级管理员与平台账号 返回可跳转，越权与不存在统一按资源不可见处理。 同步 OpenAPI（cmd/gendocs、cmd/api/docs.go、pkg/openapi/handlers.go）、审计动作与资源注册、上下文 健康检查证据；归档变更并同步 package-traffic-alert 主 Spec。
3.4 KiB
3.4 KiB
1. 数据与规则
- 1.1 追踪套餐使用有效态、真流量字段、资产/卡/设备关联、有效业务员、通知事件及异步导出调用链。
- 1.2 新增成对迁移、模型和约束：套餐唯一规则、预警快照、使用记录+阈值快照唯一去重、查询/导出索引。
- 1.3 实现规则 CRUD、1%～100% 校验（分母为使用记录真总量快照，规则启用校验商品真流量额度大于零）、启停和审计；更新套餐管理 OpenAPI。
2. 扫描与通知
- 2.1 实现可重跑扫描：按资产汇总当前有效套餐（
status IN (1,2) AND refund_id IS NULL）真流量，分子取使用记录真已用量、分母取使用记录真总量快照，排除虚流量/展示量/卡级累计/通道累计与失效记录。 - 2.2 选择主套餐规则（
master_usage_id IS NULL，多条按priority ASC, activated_at ASC, id ASC取第一条），主套餐无规则或总额度不大于零时跳过。 - 2.3 原子创建预警（唯一键
(package_usage_id, threshold_percent_snapshot)）与通知事件；事实与事件同一事务，唯一冲突视为已处理。 - 2.4 接入既有任务调度（照抄临期扫描的 Cron 加单例注册，不使用
asynq.Unique、不新增启动补偿、不新增手工触发入口）与既有通知投递。 - 2.5 注册通知类型常量
package.traffic.alert、注册表 Definition（类别沿用expiry）、仅业务员解析路径（business_owner_account_id指向启用平台账号）与受控目标定义；无有效业务员只建预警、幂等键内嵌使用记录与阈值快照。
3. 读侧与导出
- 3.1 实现受资产数据范围保护的预警列表/详情（仅超管与平台，越权与不存在统一不可见）。
- 3.2 按 PRD §2.16 落地导出列：资产类型、资产标识、对应标识符、卡标识、设备类型、设备型号、套餐名称、真流量已用量、真流量额度、比例、阈值快照、到期时间、剩余天数、触发时间、店铺、业务员、用户组、通知投递结果（不含运营商通道列）。
- 3.3 在五处注册点接入导出场景：场景常量、
DataSource实现、注册中心实例化、场景白名单、导出 DTOoneof两处；表头在 dispatch 阶段冻结。 - 3.4 导出使用导出侧范围过滤（空范围拒绝，不得用请求上下文版）；创建时冻结操作者、筛选、时间范围与可见资产范围；流量与阈值用触发快照，店铺/业务员/用户组按执行时当前归属补充，用户组按既有实时推导。
4. 验证
- 4.1 在隔离数据库验证迁移 up/down/up、规则启停/降阈值补建、有效套餐汇总、重复扫描、插拔卡展示、通知接收人和导出权限。
- 4.2 验证商品改价后重跑比例与预警不因商品当前值变化；已过期或已失效记录不计入。
- 4.3 验证唯一冲突不重复通知、无有效业务员只建预警、通知在账户侧可见/未读正确/可跳转受控目标。
- 4.4 验证导出归属为执行时当前归属、流量与阈值为触发快照且不超创建时范围；越权与不存在统一不可见；数据范围冻结语义成立。
- 4.5 运行
gofmt -w、go build ./cmd/api ./cmd/worker、go run cmd/gendocs/main.go、openspec validate add-package-real-usage-alerts --strict、openspec doctor --json和./scripts/context-health.sh；自动化测试按项目决策为 N/A。