13 KiB
13 KiB
7月迭代技术方案总览
状态：待评审 负责人：待指定 评审人：后端、前端、产品、验收负责人、运维待指定 讨论日期：2026-07-11 最后更新：2026-07-14 分支：Iteration/7-11 系统：junhong_cmp_fiber（已上线，渐进迭代）
一、评审结论
当前方案的技术方向没有跑偏：渐进式 DDD、通用审批流、Outbox、异步任务复用和查询侧独立都符合当前系统约束。
此前版本缺少流程图、前端方案、发布方案和若干关键业务决策。本轮已经补齐这些评审材料，并确认以下口径：
- 平台员工不建立信用额度；信用额度只属于代理主钱包。
- 批量订购的支付方式按整批统一，Excel 不携带支付方式。
- 角色级导出字段配置属于本期必做能力。
- Gateway 限速只面向卡号，设备场景先解析当前卡再调用
cardNo；本期仅人工设置/取消，不做套餐自动限速。 - 需求 16“代理分销码与佣金提现”已移出 7 月迭代，后续独立立项。
- 审批结论与退款、充值等业务处理结果分别建模和展示。
- 审批详情必须展示业务快照、业务资料、历史意见和审批附件；业务资料与审批附件分开存储和展示。
- 非代理钱包退款由财务人工处理；代理钱包退款仅回退原扣款代理主钱包。
- 本次采用停机发布，不保留旧审批接口兼容窗口。
本目录按 技术方案评审规范 整理。当前范围为 21 项实施需求，需求 16 仅保留移出记录。评审建议按“基础设施 → 资金与审批 → 批量任务 → 展示类需求”分组。
二、评审材料导航
| 材料 | 作用 |
|---|---|
| DDD 规范 | 判断复杂写、简单写和 Query 通道，以及旧模块如何渐进迁移 |
| 前端技术方案 | 跨需求的页面、状态、轮询、权限和停机发布约定 |
| 审批流 | 流程定义、实例、任务、状态机、并发、事件和业务接入 |
| 站内消息 | 审批和临期提醒的站内通知基础设施 |
| 系统配置 | C 端支付方式的受控动态配置 |
| 各需求专项文档 | 业务规则、接口、数据改动和专项前端差异 |
三、系统上下文
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 的站内审批闭环。
四、依赖关系
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 | 复机规则修正，无新状态 |
| 3 | 店铺列表加联系电话搜索 | 需求03 | Query 增加过滤条件 |
| 4 | 退款中资产禁止换货 | 需求04 | 创建换货前校验活跃退款 |
| 7 | IoT卡/设备加实名筛选 | 需求07 | 列表筛选和索引评估 |
| 11 | 当前套餐到期高亮 | 需求11 | 复用后端日期字段，前端统一颜色规则 |
| 12 | 换货显示修复 | 需求12 | 字段和检索口径对齐 |
| 13 | 列表字段新增 | 需求13 | 审批人改为动态摘要 |
简单改动不要求单独绘制系统图；涉及条件分支时用短流程图或规则表即可。
6.2 标准方案
| # | 需求 | 文档 | 关键评审点 |
|---|---|---|---|
| 2 | H5流程顺序配置化 | 需求02 | 资产视角、配置优先级、C端跳转 |
| 5 | 套餐分配生效条件 | 需求05 | 覆盖值到使用记录的快照链 |
| 6 | 资产最后到期时间 | 需求06 | Query 聚合与排队套餐口径 |
| 8 | 设备批量分配 Excel | 需求08 | 异步任务、部分成功、失败明细 |
| 9 | C端支付限制配置化 | 需求09 | 前端隐藏与后端强校验一致 |
| 10 | 限速规则 | 需求10 | 手动卡限速、kbps 单位和 Gateway 审计 |
| 14 | 导出功能 | 需求14 | 复用 ExportTask、动态字段权限 |
| 15 | 下架套餐允许续费 | 需求15 | 续费身份和历史使用判断 |
| 22 | 套餐临期提醒 | 需求22 | 15/7/3 天规则、去重、三端展示 |
6.3 完整方案
| # | 需求 | 文档 | 关键评审点 |
|---|---|---|---|
| 17 | 信用额度 | 需求17 | 钱包不变量、主体模型、角色权限 |
| 18 | 多人审批 | 需求18 | 动态审批人、串行节点、通知 |
| 19 | 批量订购套餐 | 需求19 | 逐行审计、钱包幂等、部分成功 |
| 20 | 退款审批 | 需求20 | 审批与实际退款的最终一致性 |
| 21 | 充值审批 | 需求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 |
前端源码不在当前仓库。接口评审后仍需在前端仓库完成路由、权限指令、上传组件、任务轮询组件和动态表格能力的实现映射，但这不再是业务方案决策项。
九、发布与回滚总策略
flowchart LR
S[进入维护模式并停止写入] --> M[执行数据库迁移]
M --> D[同时发布 API、Worker 和前端]
D --> C[初始化流程定义和业务绑定]
C --> L[回填存量待审批单]
L --> V[人工验证核心链路]
V --> O[开放系统访问]
发布原则：
- 发布前进入维护模式，停止创建订单、退款、充值和审批操作。
- 维护窗口内执行数据库迁移，并同时发布 API、Worker/Relay 和前端静态资源。
- 初始化并发布
refund_approval、recharge_approval，完成业务绑定后再验证。 - 使用一次性 Application 命令为存量待审批退款和员工线下充值创建流程实例；历史终态记录保持只读，不伪造审批时间线。
- 旧退款业务单审批接口和线下充值
offline-pay/reject在新版本中不再注册，不保留兼容门面。 - 人工验证发起审批、存量审批、任务处理、业务回调、通知和查询后再开放访问。
- 开放前验证失败可回滚应用版本和可逆迁移；已经形成的审批历史、资金流水、Outbox 和审计日志不得通过清表回滚。
- Worker 暂停时保留 Outbox 事件，恢复后继续消费。
十、可观测性与人工验收
关键日志和查询维度：
request_id、event_id、task_id、process_instance_id、biz_type、biz_id。- Outbox 待投递数量、失败次数和最早积压时间。
- 审批业务处理失败、批量任务失败和导出任务失败。
- 钱包扣款前后余额、版本冲突和业务幂等键。
人工验收至少覆盖：
- 正常路径、无权限、重复点击、并发审批、退回重提。
- Worker 暂停后恢复，事件和任务可继续处理。
- 维护模式下不能产生新写入；开放前确认 API、Worker 和前端版本一致。
- 所有仍需审批的存量退款和员工线下充值均已生成流程实例，历史终态记录只读可查。
- 旧退款审批和线下充值
offline-pay/reject路由不可访问。 - PostgreSQL 中业务状态、审批状态、任务状态、操作日志和资金流水一致。
十一、执行顺序建议
评审批次 A：DDD 边界、系统配置、站内消息、审批流
评审批次 B：退款、充值、信用额度、批量订购、导出权限
评审批次 C：H5 流程、限速、临期提醒、批量分配
评审批次 D：简单字段、筛选和显示修复
实施顺序：
1. 增量迁移、TxManager/Outbox、系统配置和站内消息
2. 审批定义、实例、任务和前端待办
3. 退款和充值接入通用审批
4. 批量任务、代理信用额度和导出权限
5. 其他中小需求
每个评审批次独立形成结论，未通过的复杂需求不阻塞已经闭环的简单需求实施。