迭代方案确认

2026-07-17 16:39:41 +08:00
parent bcf3e31db6
commit d022cc8788
36 changed files with 3104 additions and 6882 deletions
--- a/docs/7月迭代/7月迭代技术方案-标准评审稿.md
+++ b/docs/7月迭代/7月迭代技术方案-标准评审稿.md
@@ -1,13 +1,13 @@
 # 7月迭代技术方案（标准评审稿）

 > 状态：待评审  
-> 最后更新：2026-07-15  
+> 最后更新：2026-07-17
 > 分支：`Iteration/7-11`  
 > 系统：`junhong_cmp_fiber` 及配套后台、代理端、C 端前端  
 > 负责人：待指定  
 > 评审人：后端、前端、产品、验收负责人、运维  
-> 关联需求：7月迭代需求 01～22（需求16已移出）及新增的数据同步、企微审批、站内通知、全局审计、代理钱包扫码充值  
-> 说明：本文是技术评审主文档；完整版和专项文档保留为设计素材，不作为会议逐页评审内容。
+> 关联需求：7月迭代需求 01～22（需求16已移出）、禅道补充需求 #43/#86/#96/#97/#98，以及新增的数据同步、企微审批、站内通知、全局审计、代理钱包扫码充值
+> 说明：本文是唯一技术评审主文档；`独立方案/` 和 `来源材料/` 仅用于实施细节与方案溯源。

 ---

@@ -17,7 +17,7 @@

 当前退款、线下充值审批各自维护，卡实名、流量和网络状态又被轮询、手动刷新及业务操作分别写入，容易出现同一业务动作只更新部分状态。现有账号和资产审计也没有统一模型，无法按人员、资源、请求、资金链路和外部交互追踪。复杂资金和状态业务仍集中在旧 Service 中，配置、批量任务、通知和导出权限缺少统一契约。

-本次评审覆盖原需求 01～22（需求16移出）及五项新增技术需求，主要解决以下问题：
+本次评审覆盖原需求 01～22（需求16移出）、禅道补充需求 #43/#86/#96/#97/#98 及五项新增技术需求，主要解决以下问题：

 - 退款和平台员工线下充值直接接入企业微信审批，本系统只维护业务快照、审批状态镜像和终态处理。
 - 将卡实名、流量和网络状态写入收口到统一 DDD 用例，以轮询兜底、业务事件阶梯触发和运营商回调提高同步及时性。
@@ -25,6 +25,7 @@
 - 补齐代理后台微信/支付宝扫码充值，在线支付成功后直接幂等入代理主钱包，不进入审批。
 - 将信用额度、批量订购、退款和充值中的资金规则收敛为可并发校验的不变量。
 - 补齐异步任务、站内消息、动态配置、导出字段权限和 Gateway 限速等基础能力。
+- 补齐换货归属继承与资产换货链、店铺业务员、固定余额预警和代理系列套餐批量授权。
 - 统一后台、代理端和 C 端的页面状态、异步反馈和异常展示。
 - 在不一次性重构旧系统的前提下，按完整用例渐进迁移 DDD。

@@ -40,6 +41,7 @@
 - 后端提供 Excel 模板下载接口；模板由前端静态资源随版本发布。
 - 微信/支付宝自动退款，以及基于套餐规则的自动限速。
 - 运营商解除实名后自动回滚本地实名状态；第一版只保留防腐层入口和集成记录。
+- 禅道草稿 #41“代理查询限制”和 #51“不同品类资产换货”；草稿不进入本期开发、工时和验收。

 ### 1.3 已确认决策

@@ -58,12 +60,18 @@
 | D-11 | 采用停机发布，同时切换数据库、API、Worker 和前端，旧审批接口同步下线 | 20、21 |
 | D-12 | 企微模板 ID 和控件 ID 均按不可变版本映射；编辑模板前暂停场景，发布新映射后原子切换 | 企微审批 |
 | D-13 | 设备批量分配代理与套餐系列拆为两个独立命令 | 08 |
-| D-14 | 排队套餐使用购买时长快照推算预计最后到期时间；临期页面实时查询，定时任务仅发送通知 | 06、22 |
+| D-14 | 排队套餐使用购买时长快照推算预计最终到期时间；资产详情、临期和导出共用实时 Query，定时任务仅发送通知 | 06、11、22 |
 | D-15 | 行业卡是否需要实名由运营商 `realname_link_type` 决定，`card_category` 不参与实名、复机和轮询判断 | 01、02、数据同步 |
 | D-16 | 数据同步保留轮询兜底，关键业务事件按立即、3 分钟、5 分钟触发；超频不建立退避状态 | 数据同步 |
 | D-17 | 企微账号由已登录平台员工扫码自助绑定，普通运营不录入 `userid` | 企微审批 |
 | D-18 | 全系统审计本次一次性切换到 Audit Event + Integration Log，多视角 API 和前端同时发布 | 全局 |
 | D-19 | 代理在线充值最低 100 元，支持微信 Native 和支付宝 PreCreate，支付成功直接入主钱包且不审批 | 21、新增充值 |
+| D-20 | 资产层只展示一个预计最终到期时间；当前套餐和全部排队主套餐共同参与推算，临期也使用同一结果 | 06、11、22 |
+| D-21 | 换货完成时新资产自动继承旧资产店铺；旧资产保留原店铺用于历史查询和权限追踪 | 禅道 #98 |
+| D-22 | 店铺可选绑定一个平台业务员；该字段只表达业务归属，不恢复需求16的分销和佣金关系 | 禅道 #96 |
+| D-23 | 代理主钱包现金可用余额降至 100 元及以下时，向代理主账号和店铺业务员发送一次站内通知；信用额度不参与预警计算 | 禅道 #97 |
+| D-24 | 客户角色只提供新建店铺的默认信用配置；修改角色配置不更新任何已有店铺，已有店铺额度只能单独调整 | 17 |
+| D-25 | 代理系列套餐授权复用现有批量接口；前端批量选择，已授权套餐明确标记并置灰 | 禅道 #43 |

 ### 1.4 本期边界

@@ -115,9 +123,9 @@ flowchart LR

 | 场景 | 选择 | 判断依据 |
 |------|------|----------|
-| 钱包扣款、授信、卡状态应用、退款状态转换 | Domain | 有不变量、状态机、并发或跨表一致性 |
-| 单字段修改、简单开关、局部 CRUD | Application 事务脚本 | 规则少且不会形成复杂状态 |
-| 列表、报表、导出、跨聚合详情 | Query | 只读、字段多、需要 JOIN/聚合/分页 |
+| 钱包扣款、授信、换货完成、卡状态应用、退款状态转换 | Domain | 有不变量、状态机、并发或跨表一致性 |
+| 店铺业务员、角色默认额度、简单开关、局部 CRUD | Application 事务脚本 | 规则少且不会形成复杂状态 |
+| 系列套餐候选、换货链、列表、报表、导出、跨聚合详情 | Query | 只读、字段多、需要 JOIN/聚合/分页 |
 | 未被本次用例触碰的旧逻辑 | 保持旧架构 | 避免扩大认知和回归范围 |

 站内消息只是幂等写入和已读状态管理，采用轻量 Application/Infrastructure 即可，不为满足目录形式强行创建空洞聚合。
@@ -529,6 +537,10 @@ POST /api/admin/audit/exports
 | 站内消息 | `/notifications` | 未读数、列表、已读和受控业务跳转 |
 | 全局审计 | `/operations/audit` | 全局、人员、资源、链路、资金、风险和外部集成多视角 |
 | 系统配置 | `/settings/system-config` | 受控单选、复选和开关 |
+| 店铺管理 | 现有店铺创建、编辑、列表和详情 | 平台业务员绑定、业务员筛选和信用额度来源展示 |
+| 代理资金概况 | 现有资金页面 | 固定 100 元余额预警、角色默认额度和店铺单独调额 |
+| 代理系列授权 | 现有系列授权创建和详情页 | 套餐候选批量选择、已授权标记和不可重复选择 |
+| 资产详情 | 现有卡/设备详情页 | 预计最终到期时间、换货前代/后代标识和受控跳转 |
 | 异步任务 | 复用各业务页面 | 导入、批量订购、导出进度和失败明细 |

 全局状态只保存登录用户、权限和通知未读数。列表、详情和表单草稿保留在页面或模块级状态，避免复制服务端状态后长期失真。
@@ -606,9 +618,8 @@ stateDiagram-v2
 | 需求 01 行业卡复机 | 是否要求实名只看运营商 `realname_link_type`；`none` 可未实名复机，`template/gateway` 仍需实名 | 删除按 `card_category=industry` 放行或跳过实名的逻辑，复用卡状态领域规则 | 验证同为行业卡但不同运营商实名能力时行为不同，卡类别不再影响结果 |
 | 需求 03 联系电话搜索 | 店铺联系电话 11 位精确查询 | 店铺列表 Query 增加 `contact_phone` | 增加搜索框；空参数不影响原查询，非法号码返回参数错误 |
 | 需求 04 退款中禁止换货 | 企微审批中、历史已退回、企微已通过但退款终态未完成的资产禁止换货；已拒绝、已撤销或退款完成后放行 | 创建换货前批量校验活跃退款，返回“该资产存在退款申请” | 前端直接展示后端错误，不自行判断退款状态 |
-| 需求 06 最后到期时间 | 返回当前生效及排队主套餐全部接续后的预计最终到期时间 | 资产详情 Query 按队列顺序使用购买时长快照推演；无套餐返回 `null` | 文案使用“预计最后到期时间”，实时查询，不保存冗余结果 |
+| 需求 06/11 套餐到期时间 | 资产层只展示当前生效及排队主套餐全部接续后的预计最终到期时间；当前套餐自身到期时间只保留在套餐明细 | 资产详情 Query 按队列顺序使用购买时长快照推演；无套餐返回 `null`，等待未知实名激活时返回不可预计状态 | 文案使用“预计套餐到期时间”；高亮和临期统一使用最终剩余天数，不维护第二套资产汇总字段 |
 | 需求 07 实名筛选 | 卡按自身实名状态；设备任一有效绑定卡实名即视为设备实名 | 设备增加 `real_name_status` 快照；实名变化、绑定、解绑、换卡均刷新旧/新设备 | 卡和设备列表增加全部/已实名/未实名筛选 |
-| 需求 11 当前套餐到期 | 统一并入需求 22 的剩余天数和颜色规则 | 不再单独维护第二套计算 | 资产详情直接使用需求 22 字段 |
 | 需求 12 换货显示与搜索 | 卡的新旧资产标识统一快照 ICCID；设备维持设备号；历史数据不回填 | 创建快照逻辑修正；列表增加 `old_asset_keyword/new_asset_keyword`，支持 ICCID、接入号、虚拟号 | 搜索框拆为旧资产和新资产；验收大结果集查询性能 |
 | 需求 13 列表字段 | 提交人写业务快照；企微审批摘要动态读取 | 换货、退款、充值增加 `submitter_name`；按本页企微实例批量查询状态和审批人摘要，禁止 N+1 | 展示企微状态、当前审批人摘要、处理状态和历史审批标识 |
 | 需求 15 下架套餐续费 | 禁用套餐始终不可购买；下架套餐只允许资产所有人基于有效历史使用记录续费，禁止代理代购 | 复用统一套餐可售策略；后端根据资产和登录主体判定续费资格 | C 端当前套餐旁展示“续费”，复用购买流程；新购入口隐藏，后台代购禁用 |
@@ -802,23 +813,24 @@ PUT /api/admin/roles/{role_id}/export-fields
 - Count 和 Fetch 必须使用相同权限及查询条件。
 - 退款和充值审批摘要按本批实例批量查询，禁止 N+1。
 - 导出审批附件只输出数量，不输出对象 Key 或永久 URL。
+- `scene=iot_card` 支持按预计最终到期时间筛选 30 天内资产；该导出条件独立于页面 15 天临期定义，复用需求 06/11/22 的最终到期 Query。

 ### 5.8 需求 22：套餐临期提醒

-临期定义：按 `Asia/Shanghai` 自然日计算，当前生效套餐剩余 `0～15` 天，且资产没有可接续排队套餐。已过期资产不按 0 天计入临期。需求 06、11、22 共用查询侧日期计算，但需求06另行推算排队套餐接续后的预计最后到期时间。
+临期定义：按 `Asia/Shanghai` 自然日计算，资产当前生效主套餐与全部排队主套餐连续接续后的**预计最终剩余天数**为 `0～15` 天。已过期资产不按 0 天计入临期；没有生效套餐且队首仍等待无法确定时间的实名激活时，不伪造到期日期，也不进入临期。需求 06、11、22 共用同一个最终到期 Query。

 | 剩余天数 | 展示颜色 | 通知节点 |
 |----------|----------|----------|
 | 8～15 天 | 粉红色 | 15 天 |
 | 4～7 天 | 紫色 | 7 天 |
-| 0～3 天 | 黄色 | 3 天 |
+| 0～3 天 | 红色 | 3 天 |

 ```mermaid
 flowchart TD
-    Schedule[每日定时任务] --> Query[批量查询实时临期候选]
-    Query --> Queue{存在排队套餐?}
-    Queue -->|是| Skip[不临期、不通知]
-    Queue -->|否| Days[计算剩余自然日]
+    Schedule[每日定时任务] --> Query[计算预计最终到期时间]
+    Query --> Predictable{可以推算?}
+    Predictable -->|否| Skip[不临期、不通知]
+    Predictable -->|是| Days[计算最终剩余自然日]
    Days --> Node{存在最近未发送阈值?}
    Node -->|是| Notify[按使用记录+节点+接收人幂等通知]
    Node -->|否| End[结束]
@@ -826,13 +838,87 @@ flowchart TD

 后端：

- 卡/设备列表和详情增加 `days_until_expiry`、`is_expiring`。
+- 卡/设备列表和详情增加 `estimated_final_expires_at`、`days_until_final_expiry`、`expiry_estimate_status`、`is_expiring`。
 - 列表、详情、临期页、代理首页和 C 端均实时 SQL 计算，不读取每日任务快照，也不需要前端轮询临期状态。
 - 新增 `GET /api/admin/expiring-assets`，支持资产、套餐、店铺、到期范围和剩余天数筛选。
+- 临期独立列表固定将 `0～3` 天资产置顶，再按预计最终到期时间升序；普通卡/设备列表只高亮，不改变原排序。
 - 代理首页增加临期卡/设备数量。
 - C 端 `GET /api/c/v1/asset/info` 增加临期字段并提供续费入口。
 - 临期导出复用 `scene=expiring_asset`。
 - `tb_expiry_push_record` 从本期起按 `package_usage_id + recipient + channel + node` 防重；漏跑后只补发当前最近且尚未发送的阈值，避免一次补发多条旧通知。
+- 本期只发送站内通知，不发送企业微信临期消息；店铺业务员通过系统账号接收站内通知。
+
+### 5.9 禅道补充需求：换货、业务员、余额预警和系列授权
+
+#### 5.9.1 #98 换货新资产归属
+
+- 新资产允许处于平台库存或已经属于旧资产店铺；如果已经属于其他店铺则拒绝换货。
+- 换货完成事务内先将新资产 `shop_id`、租户标签和资产分配记录切换为旧资产店铺，再迁移客户绑定、钱包/套餐资料并更新新旧资产状态。
+- 旧资产保留原 `shop_id`，状态改为已换货，确保原店铺仍可查看历史订单、退款和换货链。
+- 前端选择新资产后展示“完成后将归属：{旧资产店铺}”，不增加人工选择目标店铺的控件。
+- 换货完成是跨资产、客户绑定、钱包、套餐和状态的一致性用例，迁移到 `exchange` Domain；旧 Service 不再保留第二套完成逻辑。
+
+#### 5.9.2 #86 资产详情换货标识
+
+资产详情 Query 基于已完成换货单返回：
+
+```json
+{
+  "exchange_trace": {
+    "previous_asset": null,
+    "next_asset": {
+      "asset_type": "iot_card",
+      "asset_id": 2002,
+      "identifier": "89860...",
+      "exchange_no": "EXC202607170001"
+    }
+  }
+}
+```
+
+- 存在 `previous_asset` 时显示“换货新资产”；存在 `next_asset` 时显示“已换出旧资产”。链路中间资产可以同时存在前代和后代。
+- 关联资产仍需通过后端数据权限校验；无权限时只显示标识，不返回可跳转的资产 ID。
+- 复用 `tb_exchange_order`，不新建换货关系表；补充旧资产查询已完成换货和新资产查询索引。
+
+#### 5.9.3 #96 店铺业务员
+
+- `tb_shop` 增加可空 `business_owner_account_id`，只允许绑定启用的平台账号。
+- 创建、编辑、列表、详情和筛选接口返回业务员 ID、账号名和手机号摘要。
+- 业务员仅表示店铺业务归属和通知接收关系，不参与店铺层级、数据权限、佣金或分销关系计算。
+- 业务员停用或删除后保留店铺字段和历史审计，通知时跳过不可用账号；运营可重新绑定。
+
+#### 5.9.4 #97 固定 100 元钱包余额预警
+
+预警阈值固定为 `10000` 分，不提供系统配置、角色配置或店铺配置：
+
+```text
+cash_available = balance - frozen_balance
+变动前 cash_available > 10000
+变动后 cash_available <= 10000
+=> 发送一次低余额站内通知
+```
+
+- 信用额度不参与余额预警，避免授信掩盖代理现金不足。
+- 接收人是店铺主账号和可用的店铺业务员；站内通知使用稳定业务键防重。
+- 余额回升到 100 元以上后重新布防，再次跌破时可重新通知；持续低于阈值的连续扣款不重复提醒。
+- 资金概况只展示“现金余额不足 100 元”状态，不提供阈值编辑控件。
+- 钱包聚合在余额变更后产生低余额领域事件，事务内写 Outbox；通知失败不能回滚资金事务。
+
+#### 5.9.5 #43 代理系列套餐批量授权
+
+现有 `PUT /api/admin/shop-series-grants/{id}/packages` 已接受套餐数组，继续作为批量写接口。新增套餐候选 Query：
+
+```text
+GET /api/admin/shop-series-grants/{id}/package-options
+```
+
+返回 `package_id`、名称、编码、公司成本价、当前代理授权成本价、建议售价和 `is_authorized`。首次授权系列和后续管理套餐都使用同一候选列表：
+
+- 已授权套餐显示“已授权”并置灰，不可重复选择。
+- 未授权套餐支持复选框多选并一次提交。
+- 后端对重复套餐按幂等处理，不能依赖前端置灰保证一致性。
+- `company_cost_price`、`authorized_cost_price` 和 `suggested_retail_price` 分字段返回，禁止继续使用含义不明确的单一 `cost_price` 展示。
+- 套餐候选属于 Query，批量授权属于轻量 Application 事务脚本，不为此创建空洞聚合。

 ---

@@ -842,13 +928,20 @@ flowchart TD

 > 状态：2026-07-14 移出 7 月迭代

-本期不建设分销码、H5 代理申请、代理申请审批、自动开店、发展人关系和佣金提现材料。本需求后续独立立项时重新评审数据模型、H5 安全、审批接入、开店幂等、提现材料和工时。
+本期不建设分销码、H5 代理申请、代理申请审批、自动开店、分销发展关系和佣金提现材料。禅道 #96 新增的店铺业务员字段只用于业务归属、筛选和通知，不产生分销层级或佣金关系。本需求后续独立立项时重新评审数据模型、H5 安全、审批接入、开店幂等、提现材料和工时。

 本期审批流仅接入退款和平台员工线下充值；迁移、API、前端、发布及工时均不包含需求 16。

 ### 6.2 需求 17：代理主钱包信用额度

-平台员工不是结算和负债主体，不建立员工钱包或信用额度。角色只表达权限，不能承载财务余额和债务。
+平台员工不是结算和负债主体，不建立员工钱包或信用额度。客户角色可以保存新建店铺的默认信用模板，但不能成为债务主体；真正参与资金计算的信用额度始终写入代理主钱包。
+
+角色默认规则：
+
+- 新建店铺时读取 `default_role_id` 的默认信用配置并初始化主钱包。
+- 修改角色默认信用配置只影响以后新建的店铺，不更新任何已有店铺。
+- 已有店铺通过独立资金接口直接修改实际额度，之后也不跟随角色变化。
+- 店铺后续增加其他角色不改变钱包信用额度，避免多角色组合影响资金事实。

 #### 不变量

@@ -873,6 +966,15 @@ credit_enabled BOOLEAN NOT NULL DEFAULT FALSE
 credit_limit   BIGINT  NOT NULL DEFAULT 0
 ```

+`tb_role` 增加：
+
+```text
+default_credit_enabled BOOLEAN NOT NULL DEFAULT FALSE
+default_credit_limit   BIGINT  NOT NULL DEFAULT 0
+```
+
+角色字段仅允许客户角色使用。平台角色固定关闭；运行时扣款不 JOIN 角色表。
+
 数据库 CHECK 至少保证：

 ```sql
@@ -894,17 +996,20 @@ CHECK (

 | 用例 | 规则 |
 |------|------|
+| 修改角色默认额度 | 只更新角色模板和审计，不扫描、不修改任何已有店铺钱包 |
+| 创建店铺 | 在创建事务中读取默认角色模板并初始化代理主钱包实际额度 |
 | 修改额度 | 校验权限、加载主钱包、校验新可用金额、按 `version` 条件更新、写信用变更审计 |
 | 钱包扣款 | 使用有效额度计算可用金额，同事务更新余额、版本和资金流水 |
 | 查询/导出 | Query 返回 `credit_enabled`、`credit_limit`、`available_balance`、`is_in_debt`、`debt_amount` |

 ```text
 POST /api/admin/shops                         创建代理时可初始化信用配置
+PUT  /api/admin/roles/{id}/default-credit    修改新建店铺默认信用模板
 PUT  /api/admin/shops/{id}/credit-limit      独立调整信用额度
 GET  /api/admin/shops/fund-summary           返回信用和可用金额
 ```

-前端只展示接口返回的可用金额，不自行重新计算。额度调整弹框显示修改前后金额预览；并发冲突时刷新最新钱包版本。
+角色页面显示“新建代理默认信用额度”，并明确提示“修改后不会影响已有店铺”。店铺资金页面独立显示和修改实际信用额度。前端只展示接口返回的可用金额，不自行重新计算；额度调整弹框显示修改前后金额预览，并发冲突时刷新最新钱包版本。

 ### 6.3 需求 18：多人审批业务映射

@@ -1129,8 +1234,11 @@ POST /api/admin/agent-recharges/{id}/reject
 | 修改 | `tb_polling_config` | 收口为全局活跃/不活跃间隔，不再按卡类别形成轮询资格 |
 | 修改 | `tb_iot_card.iccid_19` | 未删除数据范围 Partial Unique Index |
 | 修改 | `tb_shop_package_allocation`、`tb_package_usage` | 生效条件、周期和时长快照 |
-| 修改 | `tb_exchange_order` | 提交人快照；新建记录修正资产标识快照 |
-| 修改 | `tb_agent_wallet` | 信用开关、额度和 CHECK 约束 |
+| 修改 | `tb_exchange_order` | 提交人快照、资产标识快照和新旧资产查询索引 |
+| 修改 | `tb_iot_card`、`tb_device` | 换货完成时新资产继承旧资产店铺和租户标签 |
+| 修改 | `tb_shop` | 可空平台业务员字段 `business_owner_account_id` |
+| 修改 | `tb_role` | 新建店铺默认信用开关和额度模板 |
+| 修改 | `tb_agent_wallet` | 实际信用开关、额度和 CHECK 约束 |
 | 修改 | `tb_refund_request` | 提交人、企微实例轮次、撤销状态和终态处理结果 |
 | 修改 | `tb_agent_recharge_record` | 提交人、企微实例、支付状态和入账处理结果 |
 | 修改 | `tb_payment` | 支持 `order_type=agent_recharge` 和创建时支付配置快照 |
@@ -1196,6 +1304,10 @@ flowchart LR
 | C-15 | 企微账号只允许扫码绑定；一个 `userid` 不能覆盖绑定到第二个系统账号。 |
 | C-16 | 代理在线充值最低 100 元，支付成功直接入主钱包，不因金额大进入审批。 |
 | C-17 | 全局审计本次停止旧表新写入；历史只读投影，不双写、不在线回填。 |
+| C-18 | 角色默认信用配置只作用于以后新建的店铺；修改角色不更新已有店铺。 |
+| C-19 | 钱包预警阈值固定 100 元，按 `balance - frozen_balance` 判断，不包含信用额度。 |
+| C-20 | 临期只发站内通知；3 天内使用红色，且只在临期独立列表置顶。 |
+| C-21 | 换货新资产继承旧资产店铺；旧资产保留原归属，已属于其他店铺的新资产不得换入。 |

 Gateway 的取消限速具体报文不是产品决策：上线前由上游接口契约确定，业务层始终只传 `speed_kbps=0`。

@@ -1217,6 +1329,9 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
 | 限速对象错误 | 设备无当前卡或错误把 IMEI 当卡号 | 统一解析当前卡 ICCID；无卡拒绝调用并记录审计 |
 | 导出敏感字段泄露 | 权限缺失或 Worker 回退全字段 | 服务端字段交集、任务快照、失败关闭 |
 | 临期重复通知 | 定时任务重试 | 稳定事件 ID 和接收人维度唯一约束 |
+| 余额预警刷屏 | 钱包持续低于 100 元并发生多次扣款 | 仅跨越阈值时发送，回升后才重新布防 |
+| 换货归属越权 | 新资产已属于其他店铺或关联资产无查看权限 | 事务内归属校验；关联跳转继续执行后端数据权限 |
+| 角色额度误改存量 | 管理员修改角色默认额度 | API 只更新角色模板，不批量更新钱包；页面明确影响范围 |

 ---

@@ -1247,12 +1362,16 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
 | 数据同步 | 活跃调频、0/3/5 阶梯、同场景合并、单卡互斥、超频不退避、19/20位回调、解除实名忽略、旧入口收口 |
 | 全局审计 | 关键事务失败回滚、人员/资源/请求/资金/风险/集成视角、历史投影、脱敏、旧表停止新写入 |
 | 钱包 | 普通余额扣款、信用扣款、额度降低失败、并发版本冲突、负余额回充 |
+| 角色默认额度 | 新建店铺继承默认值、修改角色不影响已有店铺、店铺独立调额 |
+| 余额预警 | 现金余额跨越 100 元阈值、持续低余额不重复、回升后再次跌破、代理和业务员接收通知 |
 | 批量订购 | 钱包/线下两种支付、部分成功、重复提交、Worker 重试、失败明细、模板错误 |
 | 退款 | 金额发起时固定、财务人工退款企微确认、代理钱包回退原主钱包、个人资产钱包不误入、通过后撤销不冲正 |
 | 充值 | 微信/支付宝最低100元扫码、重复回调不重复入账、已支付恢复、在线不审批、线下企微通过自动入账且无操作密码 |
 | 导出 | 普通角色、敏感字段角色、超级管理员、权限为空、审批摘要批量查询 |
 | 限速 | 单卡、设备当前卡、无当前卡、设置、取消、Gateway 失败和审计记录 |
-| 临期 | 有/无排队套餐、15/7/3 天、漏跑补发、重复定时任务、不同接收人、列表/详情/C端一致 |
+| 临期 | 当前与排队套餐最终到期推算、等待实名不可预计、15/7/3 天、3天红色和临期页置顶、漏跑补发、列表/详情/C端一致 |
+| 换货补充 | 新资产继承店铺、其他店铺资产拒绝、旧资产保留归属、前代/后代标识和受控跳转 |
+| 系列授权 | 首次和后续批量选择、已授权置灰、重复提交幂等、三类价格含义正确 |
 | 发布 | 存量退款和充值回填、历史 `legacy`、旧路由不可访问、Worker 暂停后恢复 |

 验收使用接口调用、PostgreSQL 数据核对、日志检查和页面操作，不以自动化测试作为本项目交付前提。
@@ -1267,8 +1386,8 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
 3. 卡状态领域、轮询活跃调频、事件阶梯和运营商回调防腐层
 4. 企微连接、模板版本、账号扫码绑定、提交/回调/轮询
 5. 退款和平台员工线下充值接入企微，代理微信/支付宝扫码充值
-6. 钱包信用额度、批量订购、导出权限、设备批量分配、限速和临期提醒
-7. 其他查询、字段和显示修复、存量回填和停机发布演练
+6. 钱包信用额度、业务员和余额预警、批量订购、导出权限、设备批量分配、系列套餐批量授权、限速和临期提醒
+7. 换货归属与换货链、其他查询和显示修复、存量回填及停机发布演练
 ```

 每个复杂用例按“迁移 → Application/Domain → Infrastructure → Handler → 前端 → 人工验收”形成完整闭环，不在同一任务中顺带重构未触碰模块。
@@ -1280,7 +1399,7 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
 ### 11.1 估算口径

 - 1 人日按 8 小时计算。
- 当前固定投入为 1 名后端和 1 名前端，两人并行开发，目标自然周期为 11～15 个工作日。
+- 当前固定投入为 1 名后端和 1 名前端，两人并行开发，正常目标为 12～15 个工作日，风险上限为 16 个工作日。
 - 包含本期企业微信审批、数据同步重构、全局审计一次性切换、代理微信/支付宝扫码充值及原 7 月迭代范围。
 - 不包含套餐临期企业微信消息推送、自动第三方退款、运营商解除实名回滚和需求16。
 - 包含后端、前端、第三方联调、人工接口验证、PostgreSQL 数据核对、存量回填和停机发布；不单独预留长期缓冲。
@@ -1293,28 +1412,28 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口

 | 工作包 | 后端人日 | 前端人日 | 快速交付说明 |
 |--------|----------|----------|--------------|
-| 迁移、Outbox、全局审计和站内通知 | 2 | 2 | 复用现有日志、列表和抽屉组件，先完成核心多视角 |
-| 数据同步领域收口、活跃轮询和运营商回调 | 2～3 | 1 | 后端为主，前端只补状态和审计跳转 |
-| 企微模板、扫码绑定、提交/回调/轮询 | 2～3 | 2～3 | 复用企微官方页面和现有业务详情布局 |
-| 退款、线下充值终态和代理扫码充值 | 2～3 | 2～3 | 复用现有钱包、支付回调和充值页面 |
-| 信用、批量、导出、限速、临期及其他需求 | 2～2.5 | 2～3 | 多个小需求并行处理，避免额外抽象 |
-| 联调、数据核对、回填和停机发布 | 1～1.5 | 1～2 | 随开发持续联调，最后集中验证核心链路 |
-| **合计投入** | **11～15** | **10～14** | **总投入约 21～29 人日，两人并行 11～15 个工作日** |
+| 迁移、Outbox、全局审计和站内通知 | 2 | 1.5～2 | 复用现有日志、列表和抽屉组件，先完成核心多视角 |
+| 数据同步领域收口、活跃轮询和运营商回调 | 2～3 | 0.5～1 | 后端为主，前端只补状态和审计跳转 |
+| 企微模板、扫码绑定、提交/回调/轮询 | 2～3 | 1.5～2 | 复用企微官方页面和现有业务详情布局 |
+| 退款、线下充值终态和代理扫码充值 | 2～3 | 1.5～2 | 复用现有钱包、支付回调和充值页面 |
+| 信用、业务员预警、换货、系列授权、批量、导出、限速和临期 | 2.5～3.5 | 2.5～3 | 系列授权和换货链已有后端基础，只补增量能力 |
+| 联调、数据核对、回填和停机发布 | 1～1.5 | 0.5～1 | 随开发持续联调，最后集中验证核心链路 |
+| **合计投入** | **约 12～16** | **约 8～12** | **总投入约 19～28 人日，两人并行正常 12～15 个工作日，风险上限 16 天** |

-排期基线按 **13 个工作日**，对外承诺范围为 **11～15 个工作日**。如真实企微/支付配置无法按时提供、生产 ICCID 或审计旧入口存在大量异常，问题记录为外部阻塞，不在开发阶段扩展额外重构范围。
+排期基线按 **14 个工作日**，正常范围为 **12～15 个工作日**。如换货归属需要补齐超出预期的租户标签表、真实企微/支付配置无法按时提供、生产 ICCID 或审计旧入口存在大量异常，风险上限为第 16 个工作日，不在开发阶段扩展额外重构范围。

 ### 11.3 当前团队排期

-当前团队固定为 **1 后端 + 1 前端**，两人从第一天开始并行，预计 **11～15 个工作日**。推荐节奏：
+当前团队固定为 **1 后端 + 1 前端**，两人从第一天开始并行，正常预计 **12～15 个工作日**，风险上限 **16 个工作日**。推荐节奏：

 ```text
 第 1～2 天：迁移、Outbox、审计/通知骨架，前端同步搭建页面框架
 第 3～5 天：数据同步收口、活跃轮询、回调防腐层和审计外部集成视角
 第 4～7 天：企微模板、扫码绑定、审批提交/回调/轮询及前端配置页面
 第 6～9 天：退款、线下充值终态、代理微信/支付宝扫码充值
-第 8～11 天：信用、批量、导出、限速、临期和其他小需求
-第 11～13 天：全链路联调、数据核对、旧入口清理和存量回填演练
-第 14～15 天：问题修复和停机发布缓冲；进度稳定时可提前
+第 8～12 天：信用、业务员预警、换货归属与标识、系列批量授权、批量、导出、限速和临期
+第 12～14 天：全链路联调、数据核对、旧入口清理和存量回填演练
+第 15 天：问题修复和停机发布；换货租户标签或历史数据超预期时使用第 16 天风险缓冲
 ```

 ---