docs(tplus): 更新客户口径文档与开发计划

tasks/archive/2026-10-27-tplus-sync-plan.md

@@ -0,0 +1,65 @@
+# 下一阶段开发计划：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 无任务时退出或等待；配置缺失、源连接失败、字段不符均写入任务失败记录。
+
+## 实施任务与依赖
+
+1. 核验查询与报告：固化系统枚举、收款方向、带类型的销货/订单关联和歧义统计；真实只读库执行，产出映射 v0.3 和客户确认单。
+2. 元数据迁移：新增批次范围/幂等键/重试关系/核验结果等字段；Alembic、V15 SQL、初始化脚本及模型同步，旧记录可读。
+3. 执行协调：实现队列创建、幂等与重试；共用命名锁、worker 和中断恢复，不修改工资业务表。
+4. 管理查询服务：批次/异常分页、详情和汇总，只返回受控字段；列表不加载核验结果大字段。
+5. 管理 API：管理员认证、请求校验、统一响应、创建/重试审计、源配置关闭时的可操作错误。
+6. 同步管理页面：接入实际接口，展示批次/异常/核验结果；支持选择读取范围、排队、失败重试和刷新，管理员菜单与后端权限一致。
+7. 真实流程验收：用只读副本做一次关联核验和小范围人员重读；浏览器验证筛选、详情、空态、重试、权限及响应式。
+8. 回归与交接：隔离数据库/Redis 验证迁移、服务/API；前端类型检查与构建，更新模块文档、上下文和本清单。
+
+详细验收和执行状态记录在 `tasks/todo.md`。每个任务先完成定点测试，再进入依赖它的任务；本轮不自动提交、推送或部署。
+
+## 验收与保留门槛
+
+- 真实字典和关联数量有可重跑 SQL、源版本与时间证据；遇到多订单、无类型或金额分摊规则未定时明确保留待确认。
+- 相同请求不重复创建任务，同账套不并发执行；失败重试保留原记录并不重复写入相同快照。
+- 管理员可以完成“排队 → worker 执行 → 查看结果/异常 → 重试”流程，非管理员后端 403、前端无菜单。
+- 页面不显示凭据、原始个人信息、SQL 异常或误导性的“业务导入完成”；配置关闭、空态、加载和失败状态可见。
+- 测试只使用隔离的 MySQL/Redis；运行时核验只读 T+ 副本，业务数据表不接入写入。
+- 真正的 2008 R2 环境安装仍缺合法 Windows/SQL Server 安装介质；该项作为后续交付前置，不伪造完成。
+
+## 项目后续路线
+
+完成本轮后，依据客户确认的成本、日期、人员/客户/产品分类、单据有效范围和回款分摊规则，再实施业务表导入。取得合法介质后安装 D 盘虚拟机并执行完整 2008 R2 验收；随后才启用真实增量、每周任务和部署交付。

tasks/archive/2026-10-27-tplus-sync-todo.md

@@ -0,0 +1,52 @@
+# T+ 关联核验与同步管理任务清单
+
+所有任务依照 `tasks/plan.md`。本轮已完成；真正 2008 R2 验收与客户业务确认保留为下一阶段门槛。
+
+## 1. 真实枚举与关联核验
+- [x] 固化 SQL Server 2008 R2 语法的只读核验查询，按单据类型区分销货、费用、期初应收和收入。
+- [x] 对收款行 → 销货单/明细 → 订单进行覆盖、悬空和歧义计数，不按名称/金额拼接。
+- [x] 真实副本执行并生成映射 v0.3、客户确认单；仅记录系统字典和汇总。
+- 验证：源查询实跑，报告无凭据或客户个人信息。依赖：无。预计 3–5 文件。
+
+## 2. 批次元数据迁移
+- [x] 记录实体范围、跳过数量、幂等键、父批次、请求人和核验结果，旧批次可读。
+- [x] 同步 Alembic、V15、初始化脚本和模型；空库迁移及旧库升级通过。
+- 验证：模型与 DDL 测试、隔离库迁移。依赖：无。预计 5 文件。
+
+## 3. 队列、串行执行与重试
+- [x] READ/AUDIT 任务持久化排队；同键同意图复用，同键异意图拒绝。
+- [x] 共用命名锁防并发，worker 支持 once/watch，原 CLI 入口保持可用。
+- [x] 锁定父批次防重复重试；中断记录仅在无执行者时恢复，异常不泄漏源参数。
+- 验证：先失败测试再实现；真实隔离 MySQL 并发与 worker 定点核验。依赖：1、2。分服务/CLI 两批实施。
+
+## 检查点 A
+- [x] 核验、迁移与执行服务定点通过；工资业务表写入仍关闭。
+
+## 4. 管理查询与接口
+- [x] 分页查询批次、详情和异常，列表不加载核验 JSON/原始 payload。
+- [x] 管理员接口与创建/重试审计完成，参数校验和源配置关闭行为明确。
+- [x] 汇总能区分暂存完成与 2008 R2/业务口径待确认。
+- 验证：隔离 API 测试覆盖 401/403/400/404、分页、幂等和重试。依赖：3。分查询层、API 两批实施。
+
+## 5. 同步管理页面
+- [x] 管理员菜单、概况、批次表、异常详情和关联结果接入实际 API。
+- [x] 创建读取/核验、失败重试、刷新与筛选可用；状态均为业务中文。
+- [x] 空态、加载、异常、配置关闭、权限与小屏布局可验证。
+- 验证：Vue 类型检查、生产构建、真实浏览器。依赖：4。分 API/路由、页面两批实施。
+
+## 检查点 B
+- [x] “排队 → 执行 → 查看 → 重试”完整流程有实际运行证据。
+
+## 6. 完整验证与文档
+- [x] 真实副本关联核验与人员重读通过，重复快照不新增；非管理员被拒绝。
+- [x] 定点及必要回归、迁移、Ruff、类型检查、构建和浏览器检查通过。
+- [x] 模块 README、字段确认材料、AI_CONTEXT、PROJECT_PROGRESS 和本清单更新。
+- [x] 完成逐项验收；未完成的 2008 R2 环境和业务确认明确列为交付前置，不计入本轮已完成项。
+- 依赖：1–5。
+
+## 验收证据（2026-10-27）
+
+- 单元 602 项，管理/并发/结构定点 18 项，Ruff、类型检查、构建通过；完整回归中的环境覆盖影响已独立复验。
+- D 盘 reports/management_verification_2026-10-27.json：人员去重、关联检查、六类业务表行数不变。
+- ai-aux/preview/tplus/verification.json：浏览器真实流程与四档宽度；模拟状态另见 state-verification.json。
+- V15 隔离库回滚/升级通过；head=e5f607a8b9c0。运行步骤、映射和客户确认材料均已更新。

tasks/plan.md

@@ -0,0 +1,56 @@
+# 下一阶段开发计划：T+ 数据导入与同版本验收
+
+日期：2026-10-28。基于关联核验与同步管理轮次完成后的实际情况制定；上一轮计划与任务清单已归档至 `tasks/archive/2026-10-27-tplus-sync-*.md`。
+
+## 当前实际状况
+
+- 同步管理已完成：批次/异常/重试/锁/页面验收通过；staging 累计 933,203 行，六类工资业务表尚未接入写入。
+- 口径进展：澄清清单 24 项答复基本到齐；对照表 v2 已裁决经理个人户（#7）、协助 25%（#6/#15）、信息员（#9）、企业户 3‰（#20）等冲突。9.8 方案中蓝色字体标注的原方案算法作废，毛利润率按不含运费口径执行。
+- 仍未确认：含税取数、预收/保证金/代收、二次分配三项、三级角色职权，连同 T+ 口径 13 项与环境接入 5 项，已整理于 `docs/待确认事项清单_2026-10-28_v2.xlsx`（L1–L7）。
+- 经理个人户：微信沟通确定按 9.8 方案执行、不计个人户部分，客户群确认中；系统参数已预留，确认后调整参数即可，无需开发。
+- 环境差距：合法 Windows 与 SQL Server 2008 R2 安装介质未到位，D 盘虚拟机仅有外壳；当前分支约 65 个文件未提交。
+
+## 目标与顺序
+
+先收口工程，再并行推进同版本环境验收与客户口径确认；口径闭环后实施 staging 到工资业务表的导入，最后交付托管与部署。
+
+### P0 工程收口（无外部依赖，立即执行）
+
+1. 将本轮 T+ 同步管理成果按迁移、后端服务、前端页面、文档拆分为规范提交；合入前本地构建与测试通过。
+
+### 轨道 A：同版本验收环境（外部依赖：安装介质）
+
+- A1 先行细化 `docs/SQLServer2008R2测试环境.md`：装机步骤、恢复步骤，以及驱动、只读权限、六类查询、中文/日期/金额、断连超时、重复同步的验收清单。
+- A2 取得合法介质后，在 `D:\work\app\tplus-vm` 完成系统与数据库安装。
+- A3 恢复原始备份并执行完整验收，产出报告，关闭同版本兼容 PENDING 状态。
+
+### 轨道 B：业务口径确认（外部依赖：客户填写）
+
+- B1 发送 v2 清单：客户填「客户确认单-精简版」，IT/服务商填材料项；L1（含税取数）、L2（预收等）与确认单 #1/#3/#6 一并答复，避免重复提问。
+- B2 跟进客户群对经理个人户的反馈，回填 L6。
+- B3 答复回收后更新字段映射文档与暂定口径记录：二次分配三项（L3–L5）追认、三级角色职权（L7）在页面验收时核对。
+
+### 轨道 C：T+ 数据导入开发（依赖轨道 B 闭环；设计可先行）
+
+- C1 先行起草「staging → 业务表写入」设计：表映射、金额精度（金额用 Decimal、比例和日斜率用 Fraction）、幂等与重算授权留痕、人工字段保护（回款/发货批次由系统人工指定，业务归属变更不回溯历史）、事务边界；明确标注等待确认的差异点，口径闭环后评审定稿。
+- C2 主数据导入（人员、客户、产品）：依赖 #9、#10、#11。
+- C3 订单 → 发货 → 回款导入：依赖 #1–#8、#13（成本、日期、分摊、核销、初始化）。
+- C4 负向事件处理（退货、红冲、负绩效）：依赖 #8；口径已定为负绩效照公式出数、不归零。
+- C5 增量变更发现：依赖 #13；收付款表无 `updated` 字段，需验证 rowversion 与删除/作废的发现方式，在此之前时间水位保持禁用。
+
+### 轨道 D：交付收尾（依赖 A3 与轨道 C 完成）
+
+- D1 `tplus-worker` 服务托管（Windows 服务方案）。
+- D2 每周同步任务编排与失败告警。
+- D3 客户内网独立部署与最终验收。
+
+## 验收与保留门槛
+
+- 未确认项不进入正式核算；确认单未闭环前不实施业务表写入。
+- 导入保护人工字段；每笔回款只核算一次；重算须授权并留痕。
+- 2008 R2 验收未完成前，2022 恢复副本的结果不作为同版本兼容证据。
+- 每个任务先完成定点测试再进入依赖任务；回归使用隔离的 MySQL/Redis。
+
+## 项目后续路线
+
+轨道 C 完成、A3 通过后进入轨道 D；部署验收通过即转入运维期（每周同步、参数调整走系统设置与版本管理）。

tasks/todo.md

@@ -0,0 +1,38 @@
+# T+ 数据导入与同版本验收任务清单
+
+依照 `tasks/plan.md`（2026-10-28）。上一轮清单已归档至 `tasks/archive/2026-10-27-tplus-sync-todo.md`。
+
+## P0 工程收口
+- [ ] 拆分提交本轮 T+ 同步管理成果（迁移、后端、前端、文档）；提交前 Ruff、单元测试、前端类型检查与构建通过。
+依赖：无。
+
+## 轨道 A：同版本验收环境
+- [ ] A1 细化 2008 R2 测试环境与验收手册（无介质可先做）。
+- [ ] A2 取得合法介质并完成虚拟机安装。
+- [ ] A3 恢复原始备份并执行完整验收，产出报告。
+依赖：A2 等介质到位；A3 依赖 A2。
+
+## 轨道 B：业务口径确认
+- [ ] B1 发送 `docs/待确认事项清单_2026-10-28_v2.xlsx` 并跟进填写。
+- [ ] B2 回填经理个人户客户群反馈结果（L6）。
+- [ ] B3 答复回收后更新映射与暂定口径记录。
+依赖：无；B1 立即可发。
+
+## 轨道 C：T+ 数据导入开发
+- [ ] C1 起草 staging → 业务表写入设计，标注等待确认的差异点。
+- [ ] C2 主数据导入实现与测试。
+- [ ] C3 订单/发货/回款导入实现与测试。
+- [ ] C4 负向事件处理实现与测试。
+- [ ] C5 增量变更发现方案与验证。
+依赖：C1 无前置，可先行；C2–C5 依赖轨道 B 闭环与 C1 评审。
+
+## 轨道 D：交付收尾
+- [ ] D1 worker 服务托管。
+- [ ] D2 每周同步任务与失败告警。
+- [ ] D3 客户内网部署验收。
+依赖：A3 与轨道 C 完成。
+
+## 检查点
+- [ ] 检查点 A：口径确认全部闭环（确认单 13 项 + 材料 5 项 + L1–L7）。
+- [ ] 检查点 B：主数据导入通过，业务表首次写入可回滚。
+- [ ] 检查点 C：全量导入与 2008 R2 验收通过，进入轨道 D。