实施策略
本方案采用分阶段交付、逐步验收的实施策略：
- 风险前置：第一阶段先确认所有接口和字段信息，消除不确定性
- 逐层构建：从适配器层 → 业务流层 → 管理后台层，层层叠加
- 每阶段可验收：每个阶段结束都有可演示的交付物，确保方向正确
- 预留缓冲：关键里程碑前后预留 1–2 天缓冲时间
里程碑总览
| 阶段 | 名称 | 时间 | 关键里程碑 |
|---|---|---|---|
| 1 | 需求确认与资料收集 | Day 1–3 | 接口字段确认表签署 |
| 2 | 适配器开发 | Day 4–7 | 金蝶/旺店通 API 适配器联调通过 |
| 3 | 调拨推送实现 | Day 8–10 | 金蝶调拨 → 旺店通全链路联调通过 |
| 4 | 销售退款回传 | Day 11–13 | 旺店通销售/退款 → 金蝶全链路联调通过 |
| 5 | 动态路由拆分 | Day 14–15 | 源组织 → 多目标组织拆分联调通过 |
| 6 | 月度采购汇总 | Day 16 | 目标组织采购订单生成联调通过 |
| 7 | 管理后台 — 认证与权限 | Day 17–19 | 登录/权限/角色管理全流程验收通过 |
| 8 | 管理后台 — 配置管理与看板 | Day 20–22 | 6 大配置 CRUD + 监控看板验收通过 |
| 9 | 联调、重试与上线 | Day 23–25 | 全链路联调通过 + 管理后台集成测试 + 上线演练 |
总工期：25 个工作日（约 5 周）。管理后台在第 7–8 阶段集中开发，与核心同步引擎开发串行进行，降低并行风险。
第一阶段：需求确认与资料收集
时间：Day 1–3
目标
收集并确认金蝶和旺店通的接口信息、字段定义、状态码和业务规则，消除后续开发中的不确定性。
确认事项
以下事项必须在第一阶段结束前完成确认，否则会阻塞后续开发。
| 序号 | 确认事项 | 负责方 | 产出物 |
|---|---|---|---|
| 1 | 金蝶分布式调出单的实际 formId | 金蝶实施方 | formId 清单 |
| 2 | 金蝶分布式调入单的实际 formId | 金蝶实施方 | formId 清单 |
| 3 | 金蝶赠品补发单的实际 formId | 金蝶实施方 | formId 清单 |
| 4 | 金蝶”客户主体”字段的实际位置与标识 | 金蝶实施方 | 字段路径文档 |
| 5 | 旺店通分布式调出/调入/其他入库写入接口 | 旺店通实施方 | API 文档 |
| 6 | 旺店通销售出库完成状态码 | 旺店通实施方 | 状态码对照表 |
| 7 | 旺店通退还管理已结算状态码、退货退款/退款不退货类型字段 | 旺店通实施方 | 字段对照表 |
| 8 | 金蝶与旺店通仓库编码对应关系 | 业务方 | 仓库映射表 |
| 9 | 金蝶与旺店通货品编码对应关系 | 业务方 | 货品映射表 |
| 10 | 采购订单的供应商、采购价、税率、结算组织取值规则 | 财务方 | 取值规则文档 |
交付物
- 接口字段确认表（含所有 formId、API、字段、状态码）
- 仓库货品映射初始数据
- 采购订单取值规则文档
第二阶段：适配器开发
时间：Day 4–7
目标
开发金蝶和旺店通的读写适配器，建立统一的数据标准化层和配置中心。
工作内容
| 任务 | 说明 | 预计耗时 |
|---|---|---|
| 金蝶读取适配器 | 封装金蝶 API 认证、分页拉取、数据标准化 | 1 天 |
| 金蝶写入适配器 | 封装金蝶 API 写入、组织凭证切换 | 1 天 |
| 旺店通读取适配器 | 封装旺店通 API 认证、分页拉取、数据标准化 | 0.5 天 |
| 旺店通写入适配器 | 封装旺店通 API 写入 | 0.5 天 |
| 配置中心 | 组织配置、路由配置、字段映射、状态映射的 CRUD | 1 天 |
| 幂等控制服务 | 幂等键生成、校验、存储 | 0.5 天 |
| 同步日志服务 | 日志记录、查询、导出 | 0.5 天 |
交付物
- 适配器 API 文档
- 配置中心管理界面
- 幂等控制和日志服务
第三阶段：调拨推送实现
时间：Day 8–10
目标
实现金蝶分布式调拨单推送到旺店通的完整业务流（2 张金蝶源单 → 3 张旺店通目标单）。
工作内容
| 任务 | 说明 |
|---|---|
| 调出单推送 | 金蝶分布式调出单 → 旺店通分布式调出单 |
| 调入单推送 | 金蝶分布式调入单 → 旺店通分布式调入单 |
| 入库单生成 | 金蝶分布式调出单 → 旺店通其他入库单 |
| 仓库货品映射 | 端到端验证仓库和货品编码转换 |
| 联调测试 | 使用测试数据完成全链路联调 |
验收标准
- 金蝶测试环境创建分布式调出单，旺店通测试环境自动生成对应调出单
- 金蝶测试环境创建分布式调入单，旺店通测试环境自动生成对应调入单
- 旺店通自动生成其他入库单，仓库/货品/数量与金蝶源单一致
- 重复推送同一张金蝶源单，旺店通不会生成重复单据（幂等验证）
第四阶段：销售退款回传
时间：Day 11–13
目标
实现旺店通销售出库和退还管理回传金蝶的完整业务流（5 种条件分支）。
工作内容
| 任务 | 说明 |
|---|---|
| 销售出库回传 | 已完成 + 总价 ≠ 0 → 金蝶销售订单 |
| 赠品补发单 | 已完成 + 总价 = 0 → 金蝶赠品补发单 |
| 销售退货单 | 退货退款 + 已结算 + 金额 ≠ 0 → 金蝶销售退货单 |
| 其他出库单 | 退货退款 + 已结算 + 金额 = 0 → 金蝶其他出库单 |
| 应收单（负数） | 退款不退货 + 已结算 → 金蝶应收单（金额为负数） |
| 联调测试 | 使用测试数据覆盖所有 5 种条件分支 |
验收标准
- 旺店通创建已完成销售出库单（总价 ≠ 0），金蝶自动生成销售订单
- 旺店通创建已完成销售出库单（总价 = 0），金蝶自动生成赠品补发单
- 旺店通创建退货退款已结算单（金额 ≠ 0），金蝶自动生成销售退货单
- 旺店通创建退货退款已结算单（金额 = 0），金蝶自动生成其他出库单
- 旺店通创建退款不退货已结算单，金蝶自动生成负数应收单
第五阶段：动态路由拆分
时间：Day 14–15
目标
实现源组织数据按客户主体字段动态拆分到多个目标组织的业务流。
工作内容
| 任务 | 说明 |
|---|---|
| 路由配置管理 | 支持客户主体 → 目标组织的配置维护 |
| 单据拆分逻辑 | 按客户主体字段值匹配路由规则，拆分单据到目标组织 |
| 多组织写入 | 支持同时写入多个金蝶目标组织（不同凭证） |
| 联调测试 | 使用包含多种客户主体的测试数据验证拆分 |
验收标准
- 源组织单据包含客户主体”B”，自动拆分到 B 组织
- 源组织单据包含客户主体”C”，自动拆分到 C 组织
- 源组织单据客户主体未匹配任何规则，保留在源组织
- 新增一条路由配置后，无需重新部署，下次推送自动生效
第六阶段：月度采购汇总
时间：Day 16
目标
实现目标组织按月汇总销售订单和赠品补发单，自动生成采购订单。
工作内容
| 任务 | 说明 |
|---|---|
| 月度汇总任务 | 定时任务按月触发，汇总每个目标组织的数据 |
| 货品数量合并 | 按货品编码合并销售订单和赠品补发单的数量 |
| 采购订单生成 | 为每个目标组织生成一张金蝶采购订单 |
| 联调测试 | 使用模拟月度数据验证汇总和采购订单生成 |
验收标准
- 月度汇总任务正确统计每个目标组织的销售和赠品数据
- 相同货品编码的数量正确合并
- 生成的采购订单包含正确的供应商、采购价、税率
- 无销售数据的目标组织不生成空采购订单
第七阶段：管理后台 — 认证与权限
时间：Day 17–19
目标
搭建管理后台的基础框架，实现用户认证、角色管理和权限控制。
工作内容
| 任务 | 说明 | 预计耗时 |
|---|---|---|
| 后台项目搭建 | Next.js SSR 项目初始化、数据库建表、环境配置 | 0.5 天 |
| 认证系统 | Better Auth 集成、登录页面、Session 管理 | 1 天 |
| 权限系统 | 三级角色模型（admin/operator/viewer）、权限矩阵、中间件拦截 | 1 天 |
| 用户管理页面 | 用户 CRUD、角色分配、批量导入 | 0.5 天 |
验收标准
- 管理员可正常登录/登出，Session 30 分钟超时自动失效
- 三种角色（admin/operator/viewer）权限隔离正确：viewer 无法修改任何配置，operator 无法管理用户
- 用户创建、角色调整、禁用功能正常
- 登录失败 5 次后账号锁定 15 分钟
- CSV 批量导入用户功能正常
交付物
- 管理后台登录页面
- 用户管理 CRUD 界面
- 权限拦截中间件
第八阶段：管理后台 — 配置管理与看板
时间：Day 20–22
目标
实现 6 大配置类型的在线 CRUD 管理、变更审批流和监控看板。
工作内容
| 任务 | 说明 | 预计耗时 |
|---|---|---|
| 配置管理 CRUD | 6 大配置类型的列表、新增、编辑、删除界面 | 1 天 |
| 变更审批流 | 三级审批策略（低/中/高风险）、审批状态机 | 0.5 天 |
| 即时生效机制 | 配置变更事件通知、缓存刷新 | 0.5 天 |
| 监控看板 | 仪表盘、同步日志查看器、异常告警 | 0.5 天 |
| 批量操作 | 导入导出、模板复制、批量启用/停用 | 0.5 天 |
验收标准
- 6 大配置类型均可在线 CRUD，表单校验正确
- 中风险变更需管理员审批，审批通过后即时生效
- 配置变更后同步引擎在 5 秒内加载新配置
- 仪表盘实时展示同步统计数据，每 30 秒刷新
- 同步日志支持多维度筛选和 CSV 导出
- CSV/JSON 导入导出功能正常
交付物
- 配置管理界面（6 大类型）
- 审批流管理界面
- 监控看板仪表盘
- 同步日志查看器
第九阶段：联调、重试与上线
时间：Day 23–25
目标
全链路联调验证（含管理后台集成）、异常重试机制验证、上线演练。
工作内容
| 任务 | 说明 |
|---|---|
| 全链路联调 | 从调拨 → 销售 → 退款 → 拆分 → 采购，端到端验证 |
| 管理后台集成测试 | 通过管理后台修改配置，验证同步引擎行为变更 |
| 异常重试验证 | 模拟网络超时、接口限流、字段校验失败等异常场景 |
| 幂等验证 | 重复推送各种类型的单据，确认不会生成重复目标单 |
| 日志完整性验证 | 检查每笔推送的同步日志是否完整 |
| 监控看板验证 | 验证仪表盘数据与实际同步日志一致 |
| 上线演练 | 在预生产环境执行完整的上线流程 |
| 回滚预案 | 制定上线失败时的回滚步骤 |
验收标准
- 全链路联调通过（调拨 → 销售 → 退款 → 拆分 → 采购）
- 管理后台配置变更后同步引擎行为正确变更
- 异常场景（网络超时、限流、字段错误）正确处理并重试
- 幂等验证通过（重复推送无重复单据）
- 同步日志完整可查
- 仪表盘数据准确，告警通知正常触发
- 上线演练通过
- 回滚预案已制定并评审
交付物
- 上线报告（含联调结果、异常处理结果、性能测试结果）
- 回滚预案文档
- 运维手册（日常监控、告警处理、异常排查）
- 配置管理手册（新增组织、修改映射等操作指南）
- 管理后台用户手册
交付物汇总
| 类别 | 交付物 | 交付阶段 |
|---|---|---|
| 文档 | 接口字段确认表 | 第 1 阶段 |
| 文档 | 适配器 API 文档 | 第 2 阶段 |
| 文档 | 配置管理手册 | 第 9 阶段 |
| 文档 | 运维手册 | 第 9 阶段 |
| 文档 | 上线报告 | 第 9 阶段 |
| 文档 | 回滚预案 | 第 9 阶段 |
| 文档 | 管理后台用户手册 | 第 9 阶段 |
| 代码 | 金蝶/旺店通适配器 | 第 2 阶段 |
| 代码 | 配置中心 | 第 2 阶段 |
| 代码 | 5 大业务流实现 | 第 3–6 阶段 |
| 代码 | 异常重试与幂等控制 | 第 2 阶段 |
| 代码 | 管理后台 — 认证与权限 | 第 7 阶段 |
| 代码 | 管理后台 — 配置管理与看板 | 第 8 阶段 |
| 配置 | 组织配置初始数据 | 第 1 阶段 |
| 配置 | 仓库货品映射初始数据 | 第 1 阶段 |
| 配置 | 字段/状态映射配置 | 第 1 阶段 |
最后更新