break
5ed6b39deb
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Has been cancelled
- 新增六对成对迁移 000232–000237：H5 弹窗类型、退款结算标识与申请人备注、优先轮询事实字段与两个新终态、通道阈值命中留痕、手机号最近解绑人、提现资格校验留痕 - 退款：原因必填与申请人备注、来源支付与渠道流水冻结、线下处理流水号补录审计、按订单查询可选退款方式、企微审批材料补齐且新增字段缺失映射即明确失败 - 优先轮询：人工关闭、有效期到期独立周期任务、失败与过期人工重触发、事实字段与异常重试查询、资产解析端点只读投影 - 通道阈值：命中事实同事务留痕与命中记录查询；员工账单：列表筛选与详情投影；商户池：列表投影与统计周期语义；H5：弹窗类型与类别排序 - 手机号：有效关联数量与最近解绑人、短信验证码失败次数限制；导出：佣金明细十五列与报表序号列 - 时间筛选：三处新增筛选纳入统一严格解析契约，员工账单产生时间参数改名 - 同步 12 份主 Spec 需求、两端点与异步任务证据链，门禁 context-health 与 OpenSpec 校验通过
92 lines
7.3 KiB
Markdown
92 lines
7.3 KiB
Markdown
# carrier-channel-traffic-threshold Specification
|
||
|
||
## Purpose
|
||
|
||
按运营商通道自身计费周期和累计流量控制停复机，独立于套餐真流量预警。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 通道阈值配置、权限与审计
|
||
仅超级管理员和平台用户 SHALL 在运营商通道新建或编辑时配置流量阈值开关、阈值数值和流量单位；阈值数值必须为正，流量单位必须为系统支持的 MB 或 GB，统计周期为通道既有的上游流量重置日（1～28，上海时区），不另行配置周期。阈值字段仅对平台账号可见：列表与详情响应对非平台账号不返回阈值字段，非平台账号提交包含阈值字段的创建或编辑请求必须被拒绝；不改变通道其余字段的既有可见性与可编辑范围。新增、修改、启用、停用均必须并入通道更新审计的操作者、修改前后字段与时间记录，不另建独立审计动作。停用仅停止后续新锁创建：已持锁卡当前周期继续拒绝复机，新周期解锁与条件复机照常；停用不得删除当前周期锁或历史任务结果。
|
||
|
||
#### Scenario: 越权修改通道阈值
|
||
- **WHEN** 非超级管理员、非平台用户请求创建、编辑或启停通道阈值
|
||
- **THEN** 系统拒绝请求，不修改配置且不产生审计成功事实
|
||
|
||
#### Scenario: 停用后已持锁卡进入新周期
|
||
- **WHEN** 通道阈值停用后，曾达量持锁的卡进入新计费周期
|
||
- **THEN** 系统不再创建新锁，且该卡按新周期规则正常解锁并按条件复机，历史锁与任务结果保留
|
||
|
||
### Requirement: 通道阈值停机与周期恢复
|
||
系统 SHALL 为每个已启用运营商通道按通道既有的上游流量重置日（与网关计数器清零同一事实，上海时区周期边界）判断运营商回传的每张卡当前周期累计流量，累计流量仅取网关累计读数换算，不使用本地用量统计或套餐真流量；每张卡独立判断，不扩散到设备维度，不进入既有停复机的设备扩散路径。达到或超过阈值时，系统为当前周期创建通道阈值停机锁并创建可靠停机任务；同一周期重复判定、并发或任务重放不得重复创建锁或重复发起停机。改阈值不生效于当前周期已持锁卡：当前周期维持拒绝复机，新周期按新阈值判断。
|
||
|
||
持锁卡在当前周期内 MUST 拒绝一切复机，包括自动复机、手动复机、保护期强制复机和机卡分离复机；拒绝时保留锁并记录拒绝事实。停机调用失败或结果未知时保留锁与任务状态，由本能力新增的恢复扫描处理：只查询运营商状态回填、确认成功后补写卡状态；自提交起超过约定窗口仍无法确认结果的，标记异常并转人工处理，不自动删除锁。本能力新增停因 `channel_threshold`，不参与既有自动复机判定，复机仅由周期处理发起。
|
||
|
||
新周期开始时，系统 SHALL 对仍持锁卡解除通道锁；仅存在有效主套餐、流量未耗尽、实名满足、不存在风险停机、销户或其他停机锁时创建自动复机任务，任一条件不满足时只解锁不调用运营商。其他停机锁指卡停机原因为非空且非通道阈值的其他停因，或网关扩展状态为风险停机、销户。复机失败或结果未知同样由恢复扫描处理。卡更换运营商后，旧周期锁保留，新周期按新运营商的重置日计算。
|
||
|
||
#### Scenario: 达量后人工复机
|
||
- **WHEN** 当前计费周期内持有通道阈值停机锁的卡请求复机
|
||
- **THEN** 系统拒绝复机且保留该锁
|
||
|
||
#### Scenario: 新周期仍有其他停机锁
|
||
- **WHEN** 新周期开始的持锁卡没有风险停机但存在其他停机锁
|
||
- **THEN** 系统解除通道阈值锁但不调用运营商复机
|
||
|
||
#### Scenario: 达量后强制复机被拒
|
||
- **WHEN** 当前计费周期内的持锁卡触发保护期强制复机或机卡分离复机
|
||
- **THEN** 系统拒绝复机、保留该锁并记录拒绝事实
|
||
|
||
#### Scenario: 停机结果未知恢复确认
|
||
- **WHEN** 通道阈值停机调用后结果未知，恢复扫描向运营商查询确认卡已停机
|
||
- **THEN** 系统补写卡停机状态并将任务结果记为已确认
|
||
|
||
#### Scenario: 停机结果未知超期转人工
|
||
- **WHEN** 通道阈值停机任务自提交起超过约定窗口仍无法确认结果
|
||
- **THEN** 系统标记异常并留存安全失败原因转人工处理，不自动删除锁
|
||
|
||
#### Scenario: 换运营商后周期归属
|
||
- **WHEN** 持锁卡更换运营商后到达新计费周期
|
||
- **THEN** 旧周期锁保留，新周期按新运营商的上游流量重置日计算并处理
|
||
|
||
|
||
### Requirement: 通道阈值命中事实留痕与查询
|
||
|
||
系统 SHALL 在创建通道阈值停机锁的同一事务内持久化该次命中事实，至少包含：触发时该卡当前计费周期的累计流量读数、本次判定的阈值数值与单位、计费周期起点、判定时间与触发来源（自动判定或重放）。累计流量 MUST 取与停机判定相同的网关累计读数换算值，MUST NOT 使用本地用量统计或套餐真流量；阈值 MUST 取该次判定实际生效的通道配置值（含改阈值前的历史值），使历史命中在配置变更后仍可解释。
|
||
|
||
周期恢复 SHALL 同步记录解锁时间与复机结果（未发起复机时的跳过原因、发起后的确认结果或转人工标记），MUST NOT 覆盖停机时的命中事实。本次上线前已存在的锁行 SHALL 保留其创建时间作为判定时间，命中数值与阈值 MAY 为空（历史读数不可重建），读侧 MUST 按「无」展示而不阻断查询。系统 MUST 提供受既有权限控制的命中记录查询，支持按运营商通道、卡、计费周期与判定时间范围筛选，并返回上述字段；查询 MUST 受数据范围约束，越权与不存在 MUST 不可区分，MUST NOT 返回凭证或上游响应原文。留痕与查询 MUST NOT 改变既有达量判定、停机调用、持锁拒绝复机与新周期解锁语义，MUST NOT 因留痕失败而放行或延迟停机。
|
||
|
||
#### Scenario: 达量命中留下数字证据
|
||
|
||
- **WHEN** 某卡当前周期累计流量达到通道阈值并创建停机锁
|
||
- **THEN** 命中事实保存该次判定的累计流量、阈值、单位、周期起点与判定时间，可按卡与周期查询
|
||
|
||
#### Scenario: 改阈值后历史命中仍可解释
|
||
|
||
- **GIVEN** 某卡已按旧阈值命中并持锁
|
||
- **WHEN** 通道阈值随后被修改
|
||
- **THEN** 该次命中事实仍返回命中时的阈值与单位，不被新配置改写
|
||
|
||
#### Scenario: 新周期恢复留痕
|
||
|
||
- **WHEN** 新计费周期处理持锁卡并按其条件解锁或复机
|
||
- **THEN** 记录解锁时间与复机结果或跳过原因，停机命中事实保持不变
|
||
|
||
#### Scenario: 越权查询命中记录
|
||
|
||
- **WHEN** 调用者查询其数据范围外卡的命中记录
|
||
- **THEN** 响应与记录不存在不可区分
|
||
|
||
#### Scenario: 留痕不影响停机语义
|
||
|
||
- **GIVEN** 命中事实写入遇到异常
|
||
- **WHEN** 达量判定与停机任务执行
|
||
- **THEN** 系统按既有可靠机制处理停机，MUST NOT 因留痕失败而放行或延迟停机
|
||
|
||
## 可达操作索引
|
||
|
||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||
|
||
### 运营商通道阈值命中
|
||
|
||
`GET /api/admin/carrier-traffic-threshold-hits`（查询通道阈值命中记录）。
|