# package-traffic-alert Specification

## Purpose

按套餐真实流量和当前有效套餐事实生成一次性达量预警，向资产所属店铺当时有效业务员投递可追溯通知，而不将通道级停复机控制或虚流量混入套餐预警。

## Requirements

### Requirement: 真流量预警规则

系统 SHALL 为每个套餐商品维护至多一条当前真流量预警规则，阈值为 1% 至 100% 的小数百分比。规则启用、修改或降低阈值只影响后续扫描；既有预警 MUST 保留触发时的套餐、阈值、流量和资产快照。规则停用后停止创建新预警；重新启用或降低阈值后，下次扫描发现已有有效套餐达量时必须补建符合条件的预警。

#### Scenario: 降低阈值后补建

- **WHEN** 管理员降低一个启用规则的阈值，下一次扫描发现其有效套餐已达到新阈值
- **THEN** 系统创建预警并冻结新阈值，不修改既有预警快照

#### Scenario: 套餐无真流量额度不可启用

- **WHEN** 管理员为真流量商品额度不大于零的套餐启用规则
- **THEN** 系统拒绝并保持该套餐无有效规则

### Requirement: 有效套餐与汇总口径

系统 SHALL 以同一资产全部当前有效套餐的真流量汇总比例判断达量，比例分子为套餐使用记录真已用量，分母为套餐使用记录真总量快照，并使用该资产主套餐的规则。当前有效套餐 MUST 为 `status IN (1,2) AND refund_id IS NULL` 的使用记录，含加油包；系统 MUST 排除待生效、已过期与已失效记录，且判定过期 MUST 只依据状态，不得仅用到期时间。实际消耗流量的套餐使用记录所关联资产是权威归属；插拔卡时预警同时展示卡与当前关联设备，但 MUST NOT 汇总多张卡。虚流量、展示量、卡级累计与运营商通道累计值 MUST NOT 计入。主套餐 MUST 为 `master_usage_id IS NULL` 的使用记录，存在多条时按优先级、生效时间、编号依次取第一条。

#### Scenario: 多个有效套餐共同达量

- **WHEN** 某资产的多个当前有效套餐真流量汇总达到其主套餐规则阈值
- **THEN** 系统为命中套餐使用记录创建唯一预警，并只向扫描时该资产所属店铺的有效业务员投递通知

#### Scenario: 商品改价后重跑

- **WHEN** 管理员修改套餐商品的当前真流量配置值，同一使用记录被再次扫描
- **THEN** 汇总比例与预警结果不因商品当前值变化

#### Scenario: 已过期或已失效记录不计入

- **WHEN** 资产的某条套餐使用记录状态为已过期或已失效
- **THEN** 系统不将该记录的真已用量与真总量计入汇总

### Requirement: 去重与补建

系统 SHALL 以套餐使用记录和命中阈值快照的组合作为预警唯一键。同一组合 MUST 至多创建一条预警；唯一冲突 MUST 视为已处理且不重复投递通知。降低阈值后对同一使用记录产生新阈值快照的预警 MUST 视为预期补建，不受既有预警阻塞。

#### Scenario: 重复扫描

- **WHEN** 相同套餐使用记录和相同阈值被重复扫描命中
- **THEN** 系统保留原预警和通知，不创建重复记录

### Requirement: 预警通知

系统 SHALL 在预警创建事务内向资产所属店铺当时有效业务员创建站内通知。预警类别 MUST 沿用 `expiry`，并 MUST 注册通知类型 `package.traffic.alert` 的模板定义。有效业务员 MUST 为店铺 `business_owner_account_id` 指向的启用平台账号，系统 MUST NOT 向店铺代理账号补发。无有效业务员时系统 MUST 只保留预警，且 MUST NOT 补发给未来业务员。通知 MUST 幂等，幂等键 MUST 内嵌使用记录与阈值快照，且 MUST 注册指向预警详情的受控目标，不返回 URL。

#### Scenario: 存在有效业务员

- **WHEN** 资产所属店铺在扫描时存在有效业务员
- **THEN** 系统在同一事务创建预警与一条站内通知，通知在账户侧可见、未读数正确并可跳转受控目标

#### Scenario: 无有效业务员

- **WHEN** 资产所属店铺在扫描时无有效业务员
- **THEN** 系统只保存预警，不创建通知且不向未来业务员补发

### Requirement: 预警查询与导出

超级管理员和平台用户 SHALL 在既有资产数据范围内查询和导出预警；先应用既有资产数据范围，该范围当前对超级管理员与平台无实际过滤，保留为冻结语义与未来放开的前置。越权与不存在 MUST 统一按既有的资源不可见处理。导出 MUST 复用既有异步任务并在创建时冻结操作者、筛选、时间范围与可见资产范围，执行期间归属变化 MUST NOT 扩大范围，且 MUST 按触发时间筛选。列表、详情与导出 MUST 返回资产类型、资产标识、对应标识符、卡标识、设备类型、设备型号、套餐名称、真流量已用量、真流量额度、比例、阈值快照、到期时间、剩余天数、触发时间、店铺、业务员、用户组与通知投递结果，且 MUST NOT 包含运营商通道列。导出中套餐、用量、总量、阈值与到期时间 MUST 使用触发快照，店铺、业务员与用户组 MUST 按执行时当前归属补充；预警行仍冻结店铺与业务员快照供列表、详情与追溯，两种口径 MUST NOT 混用；用户组 MUST NOT 写入店铺表，按既有实时推导。

#### Scenario: 受限导出

- **WHEN** 平台用户在其资产数据范围内创建预警导出
- **THEN** 导出仅包含创建时可见预警，即使任务执行期间店铺归属发生变化

#### Scenario: 归属变更后导出

- **WHEN** 预警记录创建后资产所属店铺或业务员变更，再执行已创建导出任务
- **THEN** 套餐、用量、总量、阈值与到期时间仍使用触发快照，店铺、业务员与用户组使用执行时当前归属，且不超出任务创建时冻结的可见范围

#### Scenario: 越权或不存在

- **WHEN** 调用者读取不在其可见范围内的预警详情
- **THEN** 系统按资源不可见处理，不区分越权、不存在与已删除

### Requirement: 与运营商通道阈值分离

系统 SHALL 将本能力与运营商通道阈值控制严格分离。达量预警 MUST NOT 创建停机锁、调用运营商、执行停复机，MUST NOT 读取通道计费周期或通道累计流量。

#### Scenario: 达量预警不触发通道动作

- **WHEN** 系统为某资产创建真流量达量预警
- **THEN** 系统不写入任何停机锁、不调用运营商接口且不改变卡停机状态

## 接口

接口：`GET /api/admin/package-traffic-alert-rules`（查询套餐真流量预警规则列表）；`POST /api/admin/package-traffic-alert-rules`（创建套餐真流量预警规则）；`PUT /api/admin/package-traffic-alert-rules/{id}`（修改套餐真流量预警规则）；`GET /api/admin/package-traffic-alerts`（查询套餐真流量达量预警列表）；`GET /api/admin/package-traffic-alerts/{id}`（查询套餐真流量达量预警详情）；`POST /api/admin/package-traffic-alerts/export`（导出套餐真流量达量预警）。