6.0 KiB
下一阶段开发计划：T+ 关联核验与同步管理
日期：2026-10-27。用户已选择“关联核验与同步管理”，并授权按计划实施。
本轮目标与当前证据
已有 933,203 条九类源数据快照，两轮去重通过；同步仍只有命令行入口。管理员需要查看批次、进度和异常，并能发起读取、关联核验和失败重试。
本轮补齐这条管理流程，同时用真实只读账套确认枚举和关联覆盖。工资业务表写入、退货计提、成本/日期口径及时间增量继续等待业务确认；不把本轮完成解释为整个项目已可交付。
设计决定
- 沿用 FastAPI、同步 SQLAlchemy、MySQL、Vue 3 和现有样式；不引入队列依赖。
- HTTP 只创建持久化 QUEUED 任务并立即返回；独立 CLI worker 处理长任务，避免请求等待大量数据读取，也避免依赖进程内 BackgroundTasks。
- 同一账套的读取和核验由 MySQL 连接级命名锁串行执行；CLI 直接读取与 worker 共用锁。进程中断留下的 RUNNING 记录只有在取得锁、确认无执行者后才可判失败并恢复。
- 新批次记录实体范围、重复条数、来源重试批次、请求幂等键、请求人和核验结果。历史缺失元数据保持未知，不从名称/金额猜测。
- 关联核验从 SM_VoucherType/eap_EnumItem 读取类型和状态，按单据类型关联收款明细与销货单、销售订单；不按客户名称或金额拼接，不自动分摊回款。
- 只存系统字典、结构和数量汇总，不向页面返回 staging 的原始 payload、源连接参数或原始异常 SQL。
- 连接默认关闭。可显式指定 D 盘的本地只读连接文件，不把凭据复制进项目配置或 HTTP 请求。
- SQL Server 2008 R2（10.50.x）仍是交付目标；源查询保持旧版语法，2022 PoC 不能通过同版本验收。Docker 磁盘镜像位置保持不变。
接口合同
统一前缀 /api/v1/system/tplus，全部要求管理员，响应沿用 {code,message,data}；业务字段用蛇形，分页用 pageNum/pageSize 与 list/total/pageNum/pageSize。
| 接口 | 用途 |
|---|---|
GET /overview |
配置可用性、任务数量、累计新增快照、最近关联核验概要；不查询源库 |
GET /batches |
批次分页，按状态/任务类型筛选，按 id 倒序 |
GET /batches/{batch_no} |
批次详情，含执行范围、重试关系和已脱敏核验结果 |
GET /batches/{batch_no}/errors |
本批异常分页，可按实体筛选；不返回原始 payload |
POST /batches |
创建 READ 或 AUDIT 任务；READ 指定白名单实体，AUDIT 不接受实体范围 |
POST /batches/{batch_no}/retry |
仅重试 FAILED/PARTIAL；创建新批次并保留原批次，无法确定范围的历史记录需重新选择范围 |
创建/重试请求携带 UUID request_key。数据库唯一约束原子保护；同键同意图返回原批次，同键不同意图返回 400。重试锁定父批次；同请求键复用已有任务，不同请求键遇到已有 QUEUED/RUNNING 重试时返回明确的 400，防止重复排队且不混淆幂等意图。
任务状态为 QUEUED/RUNNING/SUCCEEDED/PARTIAL/FAILED。成功/失败计数只反映原始读取，不伪造业务导入成功。重试依靠全量快照去重，时间水位保持禁用。
CLI 提供 tplus-worker --once/--watch，可处理读取和核验；原 tplus-stage 保持可用。worker 无任务时退出或等待；配置缺失、源连接失败、字段不符均写入任务失败记录。
实施任务与依赖
- 核验查询与报告：固化系统枚举、收款方向、带类型的销货/订单关联和歧义统计；真实只读库执行，产出映射 v0.3 和客户确认单。
- 元数据迁移：新增批次范围/幂等键/重试关系/核验结果等字段；Alembic、V15 SQL、初始化脚本及模型同步，旧记录可读。
- 执行协调：实现队列创建、幂等与重试；共用命名锁、worker 和中断恢复，不修改工资业务表。
- 管理查询服务：批次/异常分页、详情和汇总，只返回受控字段；列表不加载核验结果大字段。
- 管理 API：管理员认证、请求校验、统一响应、创建/重试审计、源配置关闭时的可操作错误。
- 同步管理页面：接入实际接口，展示批次/异常/核验结果；支持选择读取范围、排队、失败重试和刷新，管理员菜单与后端权限一致。
- 真实流程验收：用只读副本做一次关联核验和小范围人员重读；浏览器验证筛选、详情、空态、重试、权限及响应式。
- 回归与交接：隔离数据库/Redis 验证迁移、服务/API；前端类型检查与构建，更新模块文档、上下文和本清单。
详细验收和执行状态记录在 tasks/todo.md。每个任务先完成定点测试，再进入依赖它的任务；本轮不自动提交、推送或部署。
验收与保留门槛
- 真实字典和关联数量有可重跑 SQL、源版本与时间证据；遇到多订单、无类型或金额分摊规则未定时明确保留待确认。
- 相同请求不重复创建任务，同账套不并发执行；失败重试保留原记录并不重复写入相同快照。
- 管理员可以完成“排队 → worker 执行 → 查看结果/异常 → 重试”流程，非管理员后端 403、前端无菜单。
- 页面不显示凭据、原始个人信息、SQL 异常或误导性的“业务导入完成”；配置关闭、空态、加载和失败状态可见。
- 测试只使用隔离的 MySQL/Redis；运行时核验只读 T+ 副本，业务数据表不接入写入。
- 真正的 2008 R2 环境安装仍缺合法 Windows/SQL Server 安装介质；该项作为后续交付前置，不伪造完成。
项目后续路线
完成本轮后，依据客户确认的成本、日期、人员/客户/产品分类、单据有效范围和回款分摊规则，再实施业务表导入。取得合法介质后安装 D 盘虚拟机并执行完整 2008 R2 验收；随后才启用真实增量、每周任务和部署交付。