迭代计划准备

docs/7月迭代/00-总览.md

@@ -1,91 +1,254 @@
 # 7月迭代技术方案总览
 
-> 讨论日期：2026-07-11  
-> 分支：Iteration/7-11  
-> 系统：junhong_cmp_fiber（已上线，迭代阶段）
+> 状态：待评审
+> 负责人：待指定
+> 评审人：后端、前端、产品、验收负责人、运维待指定
+> 讨论日期：2026-07-11
+> 最后更新：2026-07-14
+> 分支：Iteration/7-11
+> 系统：junhong_cmp_fiber（已上线，渐进迭代）
 
 ---
 
-## 阶段划分
+## 一、评审结论
+
+当前方案的技术方向没有跑偏：渐进式 DDD、通用审批流、Outbox、异步任务复用和查询侧独立都符合当前系统约束。
+
+此前版本缺少流程图、前端方案、发布方案和若干关键业务决策。本轮已经补齐这些评审材料，并确认以下口径：
+
+- 平台员工不建立信用额度；信用额度只属于代理主钱包。
+- 批量订购的支付方式按整批统一，Excel 不携带支付方式。
+- 角色级导出字段配置属于本期必做能力。
+- Gateway 限速只面向卡号，设备场景先解析当前卡再调用 `cardNo`；本期仅人工设置/取消，不做套餐自动限速。
+- 需求 16“代理分销码与佣金提现”已移出 7 月迭代，后续独立立项。
+- 审批结论与退款、充值等业务处理结果分别建模和展示。
+- 审批详情必须展示业务快照、业务资料、历史意见和审批附件；业务资料与审批附件分开存储和展示。
+- 非代理钱包退款由财务人工处理；代理钱包退款仅回退原扣款代理主钱包。
+- 本次采用停机发布，不保留旧审批接口兼容窗口。
+
+本目录按 [技术方案评审规范](../技术方案评审规范.md) 整理。当前范围为 21 项实施需求，需求 16 仅保留移出记录。评审建议按“基础设施 → 资金与审批 → 批量任务 → 展示类需求”分组。
+
+---
+
+## 二、评审材料导航
+
+| 材料 | 作用 |
+|------|------|
+| [DDD 规范](./DDD规范.md) | 判断复杂写、简单写和 Query 通道，以及旧模块如何渐进迁移 |
+| [前端技术方案](./前端技术方案.md) | 跨需求的页面、状态、轮询、权限和停机发布约定 |
+| [审批流](./基础设施/审批流.md) | 流程定义、实例、任务、状态机、并发、事件和业务接入 |
+| [站内消息](./基础设施/站内消息.md) | 审批和临期提醒的站内通知基础设施 |
+| [系统配置](./基础设施/系统配置.md) | C 端支付方式的受控动态配置 |
+| 各需求专项文档 | 业务规则、接口、数据改动和专项前端差异 |
+
+---
+
+## 三、系统上下文
+
+```mermaid
+flowchart LR
+    Admin[后台管理端] --> API[Junhong API]
+    Client[C端 H5/公众号] --> API
+    API --> PG[(PostgreSQL)]
+    API --> Redis[(Redis)]
+    API --> Gateway[Gateway]
+    API --> Outbox[(Outbox)]
+    Relay[Outbox Relay] --> Outbox
+    Relay --> Asynq[Asynq]
+    Asynq --> Worker[Worker]
+    Worker --> Notification[站内消息]
+    Worker --> Business[退款/充值/临期等业务处理器]
+    Worker -. Phase 2 .-> WeCom[企业微信]
+```
+
+关键边界：
+
+- API 负责同步校验、事务提交和返回可追踪的业务状态。
+- Worker 负责通知、导出、批量任务和审批后的业务处理。
+- Gateway 是本迭代唯一已确认可以直接接入的外部业务系统。
+- 企业微信相关能力属于 Phase 2，不得阻塞 Phase 1 的站内审批闭环。
+
+---
+
+## 四、依赖关系
+
+```mermaid
+flowchart TD
+    DDD[渐进式 DDD 规范]
+    Config[系统配置]
+    Notice[站内消息]
+    Approval[通用审批流]
+    Export[统一导出任务]
+
+    DDD --> Approval
+    Notice --> Approval
+    Approval --> R18[需求18 多人审批]
+    Approval --> R20[需求20 退款审批]
+    Approval --> R21[需求21 充值审批]
+    Config --> R09[需求09 支付限制]
+    Notice --> R22[需求22 临期提醒]
+    Export --> R14[需求14 导出]
+    Approval --> R14
+```
+
+---
+
+## 五、阶段划分
 
 | 阶段 | 范围 | 说明 |
 |------|------|------|
-| **Phase 1（本迭代）** | 需求 1-22（除企微对接） | Gateway 接口已有，全部可做 |
-| **Phase 2（下次迭代）** | 需求 18（APR-009）/22（EXP-003）的企微对接部分 | 仅依赖企业微信审批/推送 API |
+| Phase 1 | 需求 1-22 中除需求16外的本系统和 Gateway 能力 | 必须形成站内闭环、人工可追踪和可回滚的后台流程 |
+| Phase 2 | 需求 18 APR-009、需求 22 EXP-003 | 企业微信审批/推送与状态同步，单独评审外部 API、安全和补偿策略 |
+
+Phase 1 不建设 BPMN 全规范、拖拽流程设计器、任意回退、子流程和复杂规则引擎。
 
 ---
 
-## 需求总览
+## 六、需求总览
 
-### 简单改动（无新表，影响范围小）
+### 6.1 简单改动
 
 | # | 需求 | 文档 | 实现要点 |
-|---|------|------|---------|
-| 1 | 行业卡复机允许未实名 | [需求01](./需求01-复机实名规则.md) | `ManualStartCard` 换用 `isRealnameOK()` |
-| 3 | 店铺列表加联系电话搜索 | [需求03](./需求03-店铺搜索电话.md) | Shop Store 加 contact_phone 过滤 |
-| 4 | 退款中资产禁止换货 | [需求04](./需求04-退款拦截换货.md) | 换货前检查活跃退款单 |
-| 7 | IoT卡/设备加实名筛选 | [需求07](./需求07-实名筛选.md) | 列表接口加 real_name_status filter |
-| 11 | 资产详情-套餐到期时间高亮 | [需求11](./需求11-套餐到期字段高亮.md) | 接口新增字段 + 前端高亮 |
-| 12 | 换货管理显示问题修复 | [需求12](./需求12-换货管理修复.md) | EXC-001~004，字段显示对齐 |
-| 13 | 列表字段新增 | [需求13](./需求13-列表字段新增.md) | 退款/代理充值/换号管理加提交人审批人 |
+|---|------|------|----------|
+| 1 | 行业卡复机允许未实名 | [需求01](./需求01-复机实名规则.md) | 复机规则修正，无新状态 |
+| 3 | 店铺列表加联系电话搜索 | [需求03](./需求03-07-11-12-13-简单改动.md#需求03店铺列表搜索新增联系电话) | Query 增加过滤条件 |
+| 4 | 退款中资产禁止换货 | [需求04](./需求04-06-退款拦截与最后到期时间.md#需求04退款中禁止换货) | 创建换货前校验活跃退款 |
+| 7 | IoT卡/设备加实名筛选 | [需求07](./需求03-07-11-12-13-简单改动.md#需求07iot卡设备管理新增已实名未实名筛选) | 列表筛选和索引评估 |
+| 11 | 当前套餐到期高亮 | [需求11](./需求03-07-11-12-13-简单改动.md#需求11资产详情-套餐到期时间字段--15天高亮) | 复用后端日期字段，前端统一颜色规则 |
+| 12 | 换货显示修复 | [需求12](./需求03-07-11-12-13-简单改动.md#需求12换货管理显示修复) | 字段和检索口径对齐 |
+| 13 | 列表字段新增 | [需求13](./需求03-07-11-12-13-简单改动.md#需求13列表字段新增) | 审批人改为动态摘要 |
 
-### 中等复杂（有新字段或配置机制）
+简单改动不要求单独绘制系统图；涉及条件分支时用短流程图或规则表即可。
 
-| # | 需求 | 文档 | 实现要点 |
-|---|------|------|---------|
-| 2 | H5流程顺序配置化 | [需求02](./需求02-H5流程配置.md) | 依赖[系统配置](./基础设施/系统配置.md) |
-| 5 | 套餐分配生效条件 | [需求05](./需求05-套餐分配生效条件.md) | ShopPackageAllocation 加 expiry_base_override |
-| 6 | 资产最后到期时间 | [需求06](./需求06-资产最后到期时间.md) | 查 PackageUsage 计算 max(expires_at) |
-| 8 | 设备批量分配 Excel | [需求08](./需求08-设备批量分配Excel.md) | 参考现有 Excel 导入体系 |
-| 9 | C端支付方式限制配置化 | [需求09](./需求09-C端支付限制配置化.md) | 恢复已注释代码 + 系统配置 |
-| 10 | 限速规则 | [需求10](./需求10-限速规则.md) | Gateway `SetSpeedLimit` 已有，套餐加限速字段 |
-| 14 | 导出功能 | [需求14](./需求14-导出功能.md) | 6 个模块导出，复用 ExportTask 体系 |
-| 15 | 下架套餐允许续费 | [需求15](./需求15-套餐下架续费.md) | ShelfStatus 判断 + 续费入口 |
+### 6.2 标准方案
 
-### 复杂新模块（DDD 结构）
+| # | 需求 | 文档 | 关键评审点 |
+|---|------|------|------------|
+| 2 | H5流程顺序配置化 | [需求02](./需求02-H5流程配置.md) | 资产视角、配置优先级、C端跳转 |
+| 5 | 套餐分配生效条件 | [需求05](./需求05-套餐分配生效条件.md) | 覆盖值到使用记录的快照链 |
+| 6 | 资产最后到期时间 | [需求06](./需求04-06-退款拦截与最后到期时间.md#需求06资产详情-所有套餐的最后到期时间) | Query 聚合与排队套餐口径 |
+| 8 | 设备批量分配 Excel | [需求08](./需求08-设备批量分配Excel.md) | 异步任务、部分成功、失败明细 |
+| 9 | C端支付限制配置化 | [需求09](./需求09-C端支付限制配置化.md) | 前端隐藏与后端强校验一致 |
+| 10 | 限速规则 | [需求10](./需求10-限速规则.md) | 手动卡限速、`kbps` 单位和 Gateway 审计 |
+| 14 | 导出功能 | [需求14](./需求14-导出功能.md) | 复用 ExportTask、动态字段权限 |
+| 15 | 下架套餐允许续费 | [需求15](./需求15-16-18-19-20-21-复杂需求.md#需求15套餐下架后允许续费) | 续费身份和历史使用判断 |
+| 22 | 套餐临期提醒 | [需求22](./需求22-套餐临期提醒.md) | 15/7/3 天规则、去重、三端展示 |
 
-| # | 需求 | 文档 | 实现要点 |
-|---|------|------|---------|
-| 16 | 代理分销码与佣金提现 | [需求16](./需求16-代理分销码佣金提现.md) | 二维码注册 + 发展人体系 |
-| 17 | 信用额度 | [需求17](./需求17-信用额度.md) | Shop/角色信用字段 + 负余额支持 |
-| 18 | 多人审批 | [需求18](./需求18-多人审批.md) | 依赖[审批流](./基础设施/审批流.md) + [站内消息](./基础设施/站内消息.md) |
-| 19 | 批量订购套餐 | [需求19](./需求19-批量订购.md) | Excel 导入 + 代理余额扣款 |
-| 20 | 退款审批 | [需求20](./需求20-退款审批.md) | 依赖审批流 |
-| 21 | 充值审核流程 | [需求21](./需求21-充值审核流程.md) | 依赖审批流 |
-| 22 | 套餐临期提醒 | [需求22](./需求22-套餐临期提醒.md) | 定时任务 + 站内消息 |
+### 6.3 完整方案
+
+| # | 需求 | 文档 | 关键评审点 |
+|---|------|------|------------|
+| 17 | 信用额度 | [需求17](./需求17-信用额度.md) | 钱包不变量、主体模型、角色权限 |
+| 18 | 多人审批 | [需求18](./需求15-16-18-19-20-21-复杂需求.md#需求18多人审批apr-001009) | 动态审批人、串行节点、通知 |
+| 19 | 批量订购套餐 | [需求19](./需求15-16-18-19-20-21-复杂需求.md#需求19批量订购套餐bpo-001008) | 逐行审计、钱包幂等、部分成功 |
+| 20 | 退款审批 | [需求20](./需求15-16-18-19-20-21-复杂需求.md#需求20退款审批) | 审批与实际退款的最终一致性 |
+| 21 | 充值审批 | [需求21](./需求15-16-18-19-20-21-复杂需求.md#需求21充值审核流程) | 审批与钱包入账分离、停机切换旧接口 |
+
+### 6.4 已移出本期
+
+| # | 需求 | 状态 | 后续处理 |
+|---|------|------|----------|
+| 16 | 代理分销码与佣金提现 | 2026-07-14 移出 7 月迭代 | 独立立项，重新评审范围、技术方案和工时 |
 
 ---
 
-## 基础设施文档
+## 七、跨需求技术决策
 
-| 文档 | 说明 | 被哪些需求依赖 |
-|------|------|--------------|
-| [DDD规范](./DDD规范.md) | 领域模型设计规范、目录结构、代码示例 | 复杂新模块全部 |
-| [系统配置](./基础设施/系统配置.md) | tb_system_config + 管理接口 | 需求 2、9 |
-| [站内消息](./基础设施/站内消息.md) | tb_notification + Asynq 异步分发 | 需求 18、20、21、22 |
-| [审批流](./基础设施/审批流.md) | 通用多级审批引擎 | 需求 18、20、21 |
+- 架构迁移按完整用例触碰式进行，禁止一次性重构旧模块。
+- 管理端 API 使用 `/api/admin/*`，C 端 API 使用 `/api/c/v1/*`。
+- 复杂查询进入 Query 模块，不通过聚合根拼装报表或导出。
+- 审批人只支持角色或指定账号，当前系统不引入部门模型。
+- 审批完成事件使用 Outbox + Asynq，通知和业务处理均按至少一次投递设计。
+- 导入、批量购买和导出必须有服务端任务状态，前端轮询只是展示手段。
+- 资金、审批、导出和敏感配置必须记录操作人和审计信息。
+- 信用额度只属于代理主钱包；平台员工是操作主体，不是结算和负债主体。
+- 批量订购支付方式整批统一；线下支付按整批上传凭证，代理钱包按整批选择代理钱包。
+- 角色管理必须提供导出字段配置，导出请求字段与角色授权字段取交集。
+- 限速最终目标始终是卡，Gateway 请求只传 `cardNo`；设备入口必须解析当前绑定卡，本期仅手动设置或取消。
+- 退款和员工线下充值统一通过任务级审批接口处理。
+- 审批状态与实际退款、钱包入账等处理状态分别返回；审批详情返回业务快照、业务资料和审批时间线。
+- 本次停机发布并同时切换 API、Worker 和前端，不建设旧审批接口兼容门面。
 
 ---
 
-## 执行顺序建议
+## 八、已确认技术决策
 
+| 编号 | 已确认结论 | 影响需求 |
+|------|------------|----------|
+| D-01 | 不实现平台员工信用额度，只保留代理主钱包授信 | 17、19 |
+| D-02 | 角色级导出字段配置本期落地，服务端执行字段授权 | 14 |
+| D-03 | 批量订购支付方式整批统一，不允许 Excel 行级混合支付 | 19 |
+| D-04 | Gateway 限速统一按 `cardNo`；设备套餐取 `tb_device_sim_binding.is_current=true` 对应卡 | 10 |
+| D-05 | 审批结论和实际业务处理状态分离 | 20、21 |
+| D-06 | 采用停机发布，旧退款审批和线下充值直接入账/驳回接口同步下线 | 20、21 |
+| D-07 | 需求16移出本期，不创建相关表、接口、流程和前端页面 | 16 |
+| D-08 | 第三方退款本期由财务人工完成；代理钱包仅回退原扣款代理主钱包，客户资产钱包不走自动回退 | 20 |
+| D-09 | 设备批量分配代理与套餐系列拆为两个命令和两个前端入口 | 8 |
+| D-10 | 当前套餐与排队主套餐按购买时长快照推算预计最后到期时间；临期页面实时查询，定时任务只做通知 | 06、22 |
+
+前端源码不在当前仓库。接口评审后仍需在前端仓库完成路由、权限指令、上传组件、任务轮询组件和动态表格能力的实现映射，但这不再是业务方案决策项。
+
+---
+
+## 九、发布与回滚总策略
+
+```mermaid
+flowchart LR
+    S[进入维护模式并停止写入] --> M[执行数据库迁移]
+    M --> D[同时发布 API、Worker 和前端]
+    D --> C[初始化流程定义和业务绑定]
+    C --> L[回填存量待审批单]
+    L --> V[人工验证核心链路]
+    V --> O[开放系统访问]
 ```
-第一周：基础设施
-  1. tb_system_config + 管理接口
-  2. tb_notification + 任务 handler
-  3. 通用审批流引擎
 
-第二周：简单改动批量完成
-  4. 需求 1/3/4/7/11/12/13（均可并行）
+发布原则：
 
-第三周：中等复杂
-  5. 需求 2/5/6/8/9（依赖基础设施）
-  6. 需求 14/15
+1. 发布前进入维护模式，停止创建订单、退款、充值和审批操作。
+2. 维护窗口内执行数据库迁移，并同时发布 API、Worker/Relay 和前端静态资源。
+3. 初始化并发布 `refund_approval`、`recharge_approval`，完成业务绑定后再验证。
+4. 使用一次性 Application 命令为存量待审批退款和员工线下充值创建流程实例；历史终态记录保持只读，不伪造审批时间线。
+5. 旧退款业务单审批接口和线下充值 `offline-pay/reject` 在新版本中不再注册，不保留兼容门面。
+6. 人工验证发起审批、存量审批、任务处理、业务回调、通知和查询后再开放访问。
+7. 开放前验证失败可回滚应用版本和可逆迁移；已经形成的审批历史、资金流水、Outbox 和审计日志不得通过清表回滚。
+8. Worker 暂停时保留 Outbox 事件，恢复后继续消费。
 
-第四周：复杂新模块
-  7. 需求 17（信用额度）
-  8. 需求 16（分销码）
-  9. 需求 18/20/21（审批流对接）
-  10. 需求 19（批量订购）
-  11. 需求 22（临期提醒）
+---
+
+## 十、可观测性与人工验收
+
+关键日志和查询维度：
+
+- `request_id`、`event_id`、`task_id`、`process_instance_id`、`biz_type`、`biz_id`。
+- Outbox 待投递数量、失败次数和最早积压时间。
+- 审批业务处理失败、批量任务失败和导出任务失败。
+- 钱包扣款前后余额、版本冲突和业务幂等键。
+
+人工验收至少覆盖：
+
+- 正常路径、无权限、重复点击、并发审批、退回重提。
+- Worker 暂停后恢复，事件和任务可继续处理。
+- 维护模式下不能产生新写入；开放前确认 API、Worker 和前端版本一致。
+- 所有仍需审批的存量退款和员工线下充值均已生成流程实例，历史终态记录只读可查。
+- 旧退款审批和线下充值 `offline-pay/reject` 路由不可访问。
+- PostgreSQL 中业务状态、审批状态、任务状态、操作日志和资金流水一致。
+
+---
+
+## 十一、执行顺序建议
+
+```text
+评审批次 A：DDD 边界、系统配置、站内消息、审批流
+评审批次 B：退款、充值、信用额度、批量订购、导出权限
+评审批次 C：H5 流程、限速、临期提醒、批量分配
+评审批次 D：简单字段、筛选和显示修复
+
+实施顺序：
+1. 增量迁移、TxManager/Outbox、系统配置和站内消息
+2. 审批定义、实例、任务和前端待办
+3. 退款和充值接入通用审批
+4. 批量任务、代理信用额度和导出权限
+5. 其他中小需求
 ```
+
+每个评审批次独立形成结论，未通过的复杂需求不阻塞已经闭环的简单需求实施。