# 7月迭代技术方案总览

> 状态：待评审
> 负责人：待指定
> 评审人：后端、前端、产品、验收负责人、运维待指定
> 讨论日期：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 中除需求16外的本系统和 Gateway 能力 | 必须形成站内闭环、人工可追踪和可回滚的后台流程 |
| Phase 2 | 需求 18 APR-009、需求 22 EXP-003 | 企业微信审批/推送与状态同步，单独评审外部 API、安全和补偿策略 |

Phase 1 不建设 BPMN 全规范、拖拽流程设计器、任意回退、子流程和复杂规则引擎。

---

## 六、需求总览

### 6.1 简单改动

| # | 需求 | 文档 | 实现要点 |
|---|------|------|----------|
| 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列表字段新增) | 审批人改为动态摘要 |

简单改动不要求单独绘制系统图；涉及条件分支时用短流程图或规则表即可。

### 6.2 标准方案

| # | 需求 | 文档 | 关键评审点 |
|---|------|------|------------|
| 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 天规则、去重、三端展示 |

### 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 月迭代 | 独立立项，重新评审范围、技术方案和工时 |

---

## 七、跨需求技术决策

- 架构迁移按完整用例触碰式进行，禁止一次性重构旧模块。
- 管理端 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. 发布前进入维护模式，停止创建订单、退款、充值和审批操作。
2. 维护窗口内执行数据库迁移，并同时发布 API、Worker/Relay 和前端静态资源。
3. 初始化并发布 `refund_approval`、`recharge_approval`，完成业务绑定后再验证。
4. 使用一次性 Application 命令为存量待审批退款和员工线下充值创建流程实例；历史终态记录保持只读，不伪造审批时间线。
5. 旧退款业务单审批接口和线下充值 `offline-pay/reject` 在新版本中不再注册，不保留兼容门面。
6. 人工验证发起审批、存量审批、任务处理、业务回调、通知和查询后再开放访问。
7. 开放前验证失败可回滚应用版本和可逆迁移；已经形成的审批历史、资金流水、Outbox 和审计日志不得通过清表回滚。
8. Worker 暂停时保留 Outbox 事件，恢复后继续消费。

---

## 十、可观测性与人工验收

关键日志和查询维度：

- `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. 其他中小需求
```

每个评审批次独立形成结论，未通过的复杂需求不阻塞已经闭环的简单需求实施。