update

openspec/changes/add-package-real-usage-alerts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/add-package-real-usage-alerts/design.md

@@ -0,0 +1,39 @@
+## 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。

openspec/changes/add-package-real-usage-alerts/proposal.md

@@ -0,0 +1,27 @@
+## Scope
+
+- 迭代编号：`AUG26-004`。
+
+## Why
+
+运营需要在套餐真实流量达量时通知资产所属店铺的有效业务员；现有套餐和通知能力没有规则、去重预警事实或可导出的触发快照。
+
+## What Changes
+
+- 为每个套餐商品维护至多一条 1%～100% 真流量预警规则；规则变更只影响后续扫描，既有预警冻结快照。
+- 扫描同一资产全部当前有效套餐的真流量汇总，以实际消耗流量的套餐记录关联资产和主套餐规则判断达量。
+- 为同一套餐使用记录和阈值仅建一条预警，通知当时有效业务员，并提供权限受控列表与异步导出。
+
+## Capabilities
+
+### New Capabilities
+
+- `package-traffic-alert`: 真流量规则、预警事实、通知和导出。
+
+### Modified Capabilities
+
+- 无。既有套餐状态与通知接收人隔离规则保持不变。
+
+## Impact
+
+影响套餐配置、套餐使用/流量扫描任务、资产投影、通知事件、导出、审计和新增 Schema。

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

@@ -0,0 +1,32 @@
+## Purpose
+
+按套餐真实流量和当前有效套餐事实生成一次性达量预警，向资产所属店铺当时有效业务员投递可追溯通知，而不将通道级停复机控制或虚流量混入套餐预警。
+
+## ADDED Requirements
+
+### Requirement: 真流量预警规则
+系统 SHALL 为每个套餐商品维护至多一条当前真流量预警规则，阈值为 1% 至 100% 的小数百分比。规则启用、修改或降低阈值只影响后续扫描；既有预警 MUST 保留触发时的套餐、阈值、流量和资产快照。规则停用后停止创建新预警；重新启用或降低阈值后，下次扫描发现已有有效套餐达量时必须补建符合条件的预警。
+
+#### Scenario: 降低阈值后补建
+- **WHEN** 管理员降低一个启用规则的阈值，下一次扫描发现其有效套餐已达到新阈值
+- **THEN** 系统创建预警并冻结新阈值，不修改既有预警快照
+
+### Requirement: 汇总口径、去重与通知
+系统 SHALL 以同一资产全部当前有效套餐的 `真流量使用量 / 真流量总额度` 汇总比例判断达量，并使用该资产主套餐的规则。实际消耗流量的套餐使用记录所关联资产是权威归属；插拔卡时预警同时展示卡和当前关联设备，但 MUST NOT 汇总多张卡。虚流量、已失效/过期/非当前有效套餐不得计入。
+
+同一套餐使用记录和同一命中阈值 MUST 至多创建一条预警。预警创建时仅向资产所属店铺当时有效业务员创建站内通知；无有效业务员时仍保留预警事实但不补发给未来新增业务员。通知和预警均须幂等，重复扫描不得重复创建。
+
+#### Scenario: 多个有效套餐共同达量
+- **WHEN** 某资产的多个当前有效套餐真流量汇总达到其主套餐规则阈值
+- **THEN** 系统为命中套餐使用记录创建唯一预警，并只向扫描时该资产所属店铺的有效业务员投递通知
+
+#### Scenario: 重复扫描
+- **WHEN** 相同套餐使用记录和相同阈值被重复扫描命中
+- **THEN** 系统保留原预警和通知，不创建重复记录
+
+### Requirement: 预警查询与导出
+超级管理员和平台用户 SHALL 在既有资产数据范围内查询和导出预警；列表和导出返回资产、卡、当前设备、套餐使用记录、真流量用量/额度/比例、阈值快照、触发时间及通知投递结果。导出必须使用既有异步任务并冻结创建时操作者、筛选条件和可见范围。
+
+#### Scenario: 受限导出
+- **WHEN** 平台用户在其资产数据范围内创建预警导出
+- **THEN** 导出仅包含创建时可见预警，即使任务执行期间店铺归属发生变化

openspec/changes/add-package-real-usage-alerts/tasks.md

@@ -0,0 +1,16 @@
+## 1. 数据与规则
+
+- [ ] 1.1 追踪套餐使用有效态、真流量字段、资产/卡/设备关联、有效业务员、通知事件及异步导出调用链。
+- [ ] 1.2 新增成对迁移、模型和约束：套餐唯一规则、预警快照、使用记录+阈值唯一去重、查询/导出索引。
+- [ ] 1.3 实现规则 CRUD、1%～100% 校验、启停和审计；更新套餐管理 OpenAPI。
+
+## 2. 扫描与读侧
+
+- [ ] 2.1 实现可重跑扫描：按资产汇总当前有效套餐真流量、选择主套餐规则、排除虚流量/失效记录，并原子创建预警与通知事件。
+- [ ] 2.2 接入既有任务调度和通知投递，确保无有效业务员仍建预警、重复扫描不重复通知。
+- [ ] 2.3 实现受资产数据范围保护的预警列表/详情和异步导出，冻结导出筛选与可见范围。
+
+## 3. 验证
+
+- [ ] 3.1 在隔离数据库验证迁移 up/down/up、规则变化补建、有效套餐汇总、重复扫描、插拔卡展示、通知接收人和导出权限。
+- [ ] 3.2 运行 `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。