docs(tplus): 完成交付设计并统一客户确认表与同版本基准

docs/SQLServer2008R2测试环境.md

@@ -4,49 +4,53 @@
 
 ## 1. 背景与当前状态（2026-10-28）
 
-- 客户源备份 `ceshi20261026.bak` 版本为 10.50.1600；生产库具体版本待客户提供（确认单 B3）。
+- 客户源备份 `ceshi20261026.bak` 版本为 10.50.1600。按用户 2026-10-28 决定，先以该版本搭建开发验收环境；生产完整版本号后补，有差异时再核验（客户版 E01/E03）。
 - 本地 Docker 已用 SQL Server 2022 副本完成恢复 PoC：完整 CHECKDB 通过、只读账号可用、六类查询两轮核验 933,203 行无失败。该副本只用于结构核验与开发，**不能替代同版本验收**。
-- Hyper-V 虚拟机外壳已建于 `D:\work\app\tplus-vm`，处于关机、断网状态；Windows 与 SQL Server 2008 R2 安装介质尚未到位（确认单 B5）。
+- Hyper-V 虚拟机外壳已建于 `D:\work\app\tplus-vm`，处于关机、断网状态；Windows 与 SQL Server 2008 R2 安装介质尚未到位（客户版 E03）。
 
 ## 2. 环境约定
 
 | 项目 | 约定 |
 | --- | --- |
 | 虚拟机目录 | `D:\work\app\tplus-vm` |
-| SQL Server 数据与日志 | `D:\work\app\tplus-sqlserver`（绑定目录，不入项目仓库） |
-| 备份文件 | `D:\work\app\tplus-backup`（先校验 SHA-256 再使用） |
+| SQL Server 数据与日志 | 2022 PoC 使用 `D:\work\app\tplus-sqlserver\data` 和 `log`；2008 R2 使用 D 盘虚拟磁盘内的来宾目录，恢复时确认实际路径 |
+| 备份文件 | 现有脚本使用 `D:\work\app\tplus-sqlserver\backup`；复制到虚拟机前后核对 SHA-256 |
 | 虚拟机网络 | 安装与验收期间保持仅主机或内网隔离，不接入公网 |
 | 凭据 | 只读账号凭据走双方认可的私密渠道交接；不写入本文档、代码或 Git |
 | 项目依赖脚本 | `scripts/tplus/`（工作区准备、备份检查、恢复、只读账号、结构盘点） |
 
+客户版 E01 先使用本地恢复实例的连接信息和专用只读账号，E02 先用现有开发主机与网络，生产信息后补。E03 的目标版本已确定，但合法介质尚未到位，不能据此把安装或验收标为完成。
+
 ## 3. 装机步骤（依赖介质，介质到位后执行）
 
-1. 运行 `scripts/tplus/prepare_sql2008r2_vm.ps1` 核对虚拟机外壳与磁盘位置；确认网卡保持断开。
-2. 挂载 Windows 安装介质，安装操作系统；完成后安装集成服务与全部安全更新，重新启用受限网络。
-3. 挂载 SQL Server 2008 R2 安装介质，安装数据库引擎实例；版本不低于 10.50.1600（RTM 即可还原源备份），实例排序规则与源备份一致（默认 Chinese_PRC_CI_AS）。
-4. 安装 SQL Server 2008 R2 的 SP3 与后续补丁（可选）；补丁不影响 10.50 主版本兼容性。
-5. 在虚拟机内安装 `ODBC Driver 17 for SQL Server`（pyodbc 依赖；Driver 17 支持连接 2008 R2）。
+1. 通过 Hyper-V 管理器核对已有虚拟机与 D 盘磁盘位置，保持网络隔离。`prepare_sql2008r2_vm.ps1` 是创建脚本，已有同名虚拟机时拒绝覆盖，不用于状态检查。
+2. 准备适配 SQL Server 2008 R2 的合法 Windows 介质，安装来宾系统。记录系统版本及补丁，不把来宾系统版本当作未来工资部署主机的要求。
+3. 安装 SQL Server 2008 R2，基准锁定为 `10.50.1600`。排序规则从备份元数据或恢复库核验，不能凭文档默认值猜测。
+4. 首轮保留该基准；如后续需要测试 SP3 等其他补丁，另记版本和结果，不覆盖基准验收记录。
+5. 在运行后端/worker 的电脑上准备 ODBC 驱动。驱动、Windows 和 TLS 的实际组合须实测后记录，不能只根据驱动名称认定兼容。默认启用加密，隔离环境的显式回退步骤见本地开发手册。
 
 ## 4. 备份恢复步骤
 
-1. `scripts/tplus/inspect_sqlserver_backup.ps1`：对 `ceshi20261026.bak` 执行 VERIFYONLY 与 FILELISTONLY，确认备份完整并列出数据/日志文件逻辑名。
-2. `scripts/tplus/restore_sqlserver_backup.ps1`：执行 RESTORE DATABASE，文件落位 `D:\work\app\tplus-sqlserver`；恢复模式按脚本默认。
-3. 恢复完成后执行 `DBCC CHECKDB` 全库检查，结果留档。
-4. `scripts/tplus/create_tplus_readonly_login.ps1`：创建专用只读登录与数据库用户，仅授予 `db_datareader`；凭据按第 2 节约定交接。
-5. `scripts/tplus/inventory_tplus_database.ps1`：盘点核心表结构与行数，与 Docker 副本的结构核验结果比对。
+现有备份检查、恢复、创建只读账号及盘点脚本调用 Docker 容器，使用容器内路径，仅适用于 2022 PoC。2008 R2 在虚拟机中按以下步骤操作，不直接套用容器脚本。
+
+1. 在来宾系统中复制原始备份，核对文件哈希；由测试环境管理员通过数据库管理工具执行备份验证并读取文件列表，记录实际数据/日志逻辑名。
+2. 恢复到新的测试数据库，在恢复界面为每个逻辑文件指定来宾磁盘路径；确认目标库不存在，不覆盖其他数据库。
+3. 恢复后执行完整数据库一致性检查并留档；记录版本、排序规则和恢复数据库名。
+4. 创建仅用于该测试库的登录和用户，授予读取权限，核对角色、显式授权和禁止写入的结果。恢复/建账号使用管理员，应用始终使用专用只读账号。
+5. 对照 `db/queries/tplus/` 的九类实体查询和关联核验查询盘点结构、行数及汇总金额；保留差异原因。报告不包含凭据或个人明细。
 
 ## 5. 同版本验收清单（逐项通过后关闭 PENDING）
 
 | # | 验收项 | 通过标准 |
 | --- | --- | --- |
-| 1 | 版本确认 | `SELECT @@VERSION` 返回 10.50.x，与源备份主版本一致 |
-| 2 | 驱动连接 | 后端配置指向该实例，pyodbc + ODBC Driver 17 连接成功 |
+| 1 | 版本确认 | `SERVERPROPERTY('ProductVersion')` 为 10.50.1600（末尾 .0 等价）；其他 10.50 补丁版本单独记录，不能冒充基准通过 |
+| 2 | 驱动连接 | 从实际运行后端的电脑连接成功，记录驱动名称、版本与加密/证书设置 |
 | 3 | 只读权限 | 用只读账号执行六类查询成功；执行任何写操作被拒绝 |
 | 4 | 六类查询 | 人员、客户、产品、订单、发货、收付款九个白名单 SQL 全部返回，行数与 Docker 副本一致 |
 | 5 | 中文数据 | 姓名、客户名、产品名等中文字段读取无乱码（只读账号仅验证读取） |
 | 6 | 日期字段 | 凭证日期、审核日期、到账日期等候选字段格式与空值表现正常 |
 | 7 | 金额精度 | 金额字段以 Decimal 读取，小数位与源数据一致 |
-| 8 | 断连超时 | 人为断网/停实例，同步错误进入 `tplus_sync_errors`，不静默丢数据 |
+| 8 | 断连超时 | 仅在隔离测试实例模拟断连；批次不得误报成功，批次失败或行级错误可追溯，恢复后可重试 |
 | 9 | 重复同步 | 同一备份重复 staging，相同行哈希全部去重跳过，行数不变 |
 | 10 | 关联核验 | `relationship_audit` 数量统计与 Docker 副本结果一致 |
 
@@ -54,10 +58,11 @@
 
 - 验收通过后产出报告（含上表逐项结果与 `@@VERSION` 输出），归档至 `.ai/archive/ai-aux/`；项目文档更新结论为「2008 R2 验收通过」。
 - 同步更新 `.ai/AI_CONTEXT.md` 与 `.ai/PROJECT_PROGRESS.md`。
-- 验收中发现的字段差异回到 `docs/待确认事项清单_2026-10-28_v2.xlsx` 对应编号，不直接改代码。
+- `check_compatibility.py` 默认核对 10.50.1600，复用应用连接策略；它的脚本检查通过不能替代本表中的断连、重复同步及完整权限验收。
+- 验收中发现的字段差异回到 `docs/客户待确认事项表_2026-10-28_客户版.xlsx` 对应编号，不直接改代码。
 
 ## 7. 明确边界
 
-- 本环境仅验收 T+ 源库只读访问；工资系统生产部署（确认单 B4）另行确认。
+- 本环境仅验收 T+ 源库只读访问；工资系统生产部署（客户版 E02）另行确认。
 - 客户生产 T+ 原库不升级、不改动；2022 副本不回迁。
 - 时间增量（确认单 #13）不在本手册范围内，待 rowversion 验证方案另行评审。

docs/T+交付部署设计_2026-10-28.md

@@ -0,0 +1,40 @@
+# T+ 交付部署设计（2026-10-28）
+
+状态：设计稿。本文约定后续 D1/D2 的实现方向；本轮没有安装服务、创建计划任务或发送告警。
+
+## 托管方案
+
+| 方案 | 适用方式 | 本项目取舍 |
+| --- | --- | --- |
+| Windows 任务计划程序 | 启动时运行现有 worker，设置失败重启和禁止重复实例 | 首期推荐；复用现有 CLI，不增加第三方服务包装依赖 |
+| NSSM | 将长驻进程包装为 Windows 服务 | 如客户要求服务管理器统一管理，再评审安装来源与版本；本轮不引入 |
+| 原生 Windows 服务包装 | 开发服务生命周期、停止信号和恢复逻辑 | 当前缺少此实现，首期维护成本较高，暂不选用 |
+
+开发环境先围绕备份源 `10.50.1600` 验证连接；工资后端继续使用现有开发主机与 Python 环境。数据库来宾 Windows 的版本不能用来推断工资部署主机的版本。生产主机、服务账号与目录由 客户版 E02 回填后确定。
+
+后续托管任务采用启动触发，工作目录指向部署包 `backend/`，直接运行部署虚拟环境中的 `python.exe -m app.cli tplus-worker --watch`。不要在托管任务启动时执行依赖升级。账号仅授予所需目录、日志和私有配置访问权限；凭据不作为任务命令行参数。
+
+建议恢复参数：进程异常退出后间隔 1 分钟重启，最多 3 次；同一任务已有实例时忽略重复启动；持续运行的 worker 不设通用执行时长上限。三次失败后转人工处理。以上是设计默认值，未写入客户环境。
+
+## 每周排队与重试
+
+拟新增单独的排队命令，调用现有 `task_service.create_task`。每周一 02:00（Asia/Shanghai）排队一次全量暂存，时间待业务方确认；尚未验收的时间增量保持关闭。worker 仍只消费队列，两者职责分开。
+
+排队命令按“源账套 + ISO 周 + 任务类型”生成稳定 UUID 请求键，重复触发复用同一任务；排队时若同账套有活动任务，先记录本周待补状态，结束后再补排，避免队列堆积。停机后补跑一次，不逐周补发过期任务。
+
+业务任务失败与进程退出分别处理。暂定仅对可确认的断连、连接超时重试，间隔 5 分钟、15 分钟，最多 2 次；每次调用现有重试接口，保留父批次。配置错误、版本不符、字段缺失、类型未确认及 PARTIAL 转人工处理。当前错误码可能合并为 `EXECUTION_ERROR`，D2 实现时先补可测试的错误分类，不能据此宽泛自动重试。
+
+## 告警与观察
+
+管理员同步页面与脱敏日志作为首期查看入口。拟对 FAILED/PARTIAL、连续 3 次进程重启失败、QUEUED 超过 15 分钟以及超过 8 天没有成功同步提示异常。运行时长阈值需在同版本首轮全量耗时实测后确定。
+
+外部邮件或企业消息通道、接收人、网络出口待 客户版 E02 与客户答复，当前不配置也不发送。通知内容限批次号、状态、时间、错误码和处理入口，不包含凭据、手机号或原始 JSON。相同根批次和错误码 30 分钟内合并通知，恢复成功发一次恢复通知；投递失败保留记录，不改变同步批次结果。
+
+## 实施与验收顺序
+
+1. 先完成备份源同版本 A3；确认业务规则并完成 C2–C5 后，再启用正式托管和自动排队。开发阶段可用隔离数据库模拟调度行为。
+2. D1 验证重启后启动、异常退出恢复、重复触发单实例、受限账号读配置、停止后不领取新任务、升级与回退均能重新取得锁。
+3. D2 验证重复周任务、停机补跑、断连重试次数、PARTIAL 人工处理、通知去重与投递失败。不得用模拟成功代替真实同版本验收。
+4. 发布时先手动单批运行并对账，再启用周任务。异常时停用排队与 worker，保留批次和原始数据，回退应用版本；不清空业务数据。
+
+待填内容：客户版 E01 的生产连接、账号和版本差异，E02 的部署主机、网络、同步时段和通知方式，E03 的同版本介质，E04 的工资验收例单，以及 S1 的生产敏感字段策略。没有这些答复时继续文档与隔离开发验证，不虚构生产配置。

docs/T+数据导入设计_staging到业务表_2026-10-28.md

@@ -1,6 +1,6 @@
 # T+ 数据导入设计：staging → 工资业务表（2026-10-28）
 
-> 状态：设计稿，未实现。客户确认单（`docs/待确认事项清单_2026-10-28_v2.xlsx`）13 项业务口径闭环前，不启动本文档对应代码开发。文中「预留参数」按编号挂到系统设置模块，客户答复后先更新清单、再回填参数、最后实现导入。
+> 状态：设计稿，未实现。客户确认单（`docs/客户待确认事项表_2026-10-28_客户版.xlsx`）业务口径答复齐全并完成设计评审后，再实现导入。「预留参数」在本稿中表示待确认决策，不代表已建系统设置项；字段映射、流程规则、部署配置须分别回填。
 
 ## 1. 目标与边界
 
@@ -55,6 +55,8 @@ staging PENDING
 
 ## 7. 预留参数清单（等待客户答复）
 
+本节保留旧编号供开发追溯。当前对外文件为《客户待确认事项表_2026-10-28_客户版.xlsx》，旧表已按用户决定删除；回填时按第 10 节对应关系查找，不重复询问已经确定的规则。
+
 | 编号 | 预留参数 | 等待内容 |
 | --- | --- | --- |
 | #1 | 成本取值 | 订单 LatestCost 与销货 costPrice/costAmount 的取舍（含税 L1 一并确认） |
@@ -70,9 +72,11 @@ staging PENDING
 | #11 | 产品口径 | 单位换算、价格类型、计提分类维护方 |
 | #12 | 收款方式 | 结算方式枚举与以物抵顶差异 |
 | #13 | 初始化与增量 | 起始日期、历史已结算款识别、rowversion 验证 |
-| L2–L5 | 二次分配三项 | 追认后回填分摊参数 |
+| L2 | 特殊款项 | 预收、保证金、代收，与 #3/#6 一并确认 |
+| L3–L5 | 二次分配三项 | 追认后回填分配标的、余额归属、协助关系 |
 | L7 | 三级角色职权 | 页面验收时核对 |
-| B1–B5 | 环境接入与介质 | 主机地址、只读账号、版本号、部署条件、合法安装介质（写到部署配置，不进代码） |
+| B1–B5 | 环境接入与介质 | 先用本地备份恢复环境，版本基准 10.50.1600；生产信息后补，介质仍需落实，凭据不入文档和 Git |
+| S1 | 敏感字段策略 | 当前开发阶段暂接受未单独加密的风险；生产保留、保护和备份范围仍待确认 |
 
 ## 8. 字段核验备注
 
@@ -85,6 +89,60 @@ staging PENDING
 
 ## 9. 实现触发条件
 
-1. 确认单 13 项 + 材料 5 项 + L1–L7 全部闭环（检查点 A）。
+1. 当前客户版的业务答复足以确定导入规则，并完成对应设计评审（检查点 A）；生产地址等资料可在正式联调前补齐。
 2. 本设计按答复修订并评审定稿。
 3. 先实现主数据导入并通过可回滚验收（检查点 B），再进入交易数据与负向事件。
+
+开发设计与隔离测试不等待生产地址/账号。备份源同版本环境仍须实际安装和验收；正式上线须补齐生产环境信息并完成 S1 决策。
+
+## 10. 口径答复回填清单
+
+所有答复先写入当前客户版 F 列，记录答复人、日期、例单或来源，再修订本稿。技术字段存在只能证明可取数，不能代替业务方选择计提口径。旧表问题已归并为下表编号，旧编号仅供内部追溯。
+
+| 原编号 | 当前客户版编号 |
+| --- | --- |
+| #1、L1 | B02 成本取法、B01 含税口径 |
+| #2、#3 | T01 发货日、T02 到账日 |
+| #4、#5 | T03 回款归属与跨单分摊 |
+| #6、L2 | B08 特殊款项 |
+| #7、#8、#12 | T04 状态、T05 负向事件、T06 抵顶方式 |
+| #9、#10、#11 | T07 人员、T08 客户、T09 产品 |
+| #13 | B07 启用与历史承接；增量发现属于开发设计 |
+| L3–L5 | B03 分配规则；修改窗口另见 B04 |
+| L6、L7 | B05 经理本人业务、B06 岗位权限 |
+| B1/M1、B2/M2、B3/M3 | E01 生产连接，E03 备份源版本验收 |
+| B4/M4、B5/M5 | E02 部署与同步，E03 同版本介质 |
+| S1 | S1 敏感字段策略 |
+
+客户版 E04 另列实际工资结果核对：先单笔、再个人与部门月结，复用已提供例单并逐笔解释差异。它是正式交付验收项，不能由技术测试代替。
+
+| 编号 | 设计回填位置与核验重点 | 定稿后的实现顺序 |
+| --- | --- | --- |
+| #1 / L1 | 销售额、成本字段，含税口径；用成本调整例单核对 | C3 明细映射与金额校验 |
+| #2 | 发货日期及缺失处理，核对 SendDate 实际存在性 | C3 发货导入 |
+| #3 / L2 | 到账日期与预收转正式回款；arrivalDate 字典为到期日，不默认作到账日 | C3 回款导入 |
+| #4 | 无订单关联数据的人工补录或排除规则 | C3 关联异常处理 |
+| #5 | 多单分摊、金额合计、尾差规则 | C3 分摊与对账 |
+| #6 / L2 | 期初、保证金、代收和历史已核算款的纳入范围 | C3 回款过滤 |
+| #7 | 生效、核销、作废的真实状态对应关系 | C3 有效性校验 |
+| #8 | 原单追溯、冲减月份、已结算调整和防重复 | C4 负向事件 |
+| #9 | 人员工号、范围、经理关系，保护人工岗位字段 | C2 人员导入 |
+| #10 | 客户筛选、改名合并和源 ID 追溯 | C2 客户导入 |
+| #11 | 单位换算、价格、指导价与计提分类维护方 | C2 产品导入 |
+| #12 | 结算方式枚举与以物抵顶的核算差异 | C3 回款方式 |
+| #13 | 初始化起点、历史核算识别、变更/作废/删除发现 | C5 增量方案，验证前不启用时间水位 |
+| L3 | 二次分配标的与现有拆行实现的差异 | 校准已有分配逻辑并回归 |
+| L4 | 不足 100% 的余额归属与留存方式 | 与 L3 一并校准 |
+| L5 | 协助仅记录、不计提的追认 | 核对独立二次分配机制 |
+| L6 | 经理个人户客户确认结果 | 核对生效日期后调整既有参数并复核例单 |
+| L7 | 角色名称、人员和可操作项 | 权限配置及页面验收 |
+| B1/M1、B2/M2 | 开发先用本地只读连接；生产地址和凭据单独交接 | 部署前配置及最小权限检查 |
+| B3/M3 | 先按备份源 10.50.1600；生产完整版本后补 | A3 基准验收，再验证生产差异 |
+| B4/M4 | 开发现有主机先行；生产系统和网络后补 | D1/D2 托管与告警配置 |
+| B5/M5 | 合法介质来源、版本与可用性 | A2 安装后进入 A3 |
+| S1 | 人员表、暂存表和备份的保护、访问、保留期 | 全库策略确认后另行实施，上线前验收 |
+
+- [ ] 核对每项答复与原始附件，冲突仍标待确认，不填猜测默认值。
+- [ ] 补齐源字段到目标字段、空值处理、人工字段保护和幂等映射，评审后定稿。
+- [ ] 按 C2 → C3 → C4/C5 顺序实施，先定点测试与对账，再做隔离回归。
+- [ ] 业务清单、设计、实现和验收结论同步更新；未答复项保留原编号。

docs/T+本地恢复与同步开发手册.md

@@ -0,0 +1,64 @@
+# T+ 本地恢复与同步开发手册
+
+日期：2026-10-28。当前程序把 T+ 原始数据写入 MySQL 暂存表，管理员可排队、查看结果和手动重试；工资业务表导入、自动周任务和告警投递尚未实现。
+
+## 环境与版本
+
+按用户本轮决定，先以备份源 SQL Server 2008 R2 `10.50.1600` 搭建开发验收环境。开发连接使用本地恢复实例的地址、端口和专用只读账号；客户生产信息到位后另行回填。现有 SQL Server 2022 恢复副本可继续用于开发，但不能证明备份源同版本兼容。安装和恢复步骤见 [2008 R2 测试环境](SQLServer2008R2测试环境.md)。
+
+`scripts/tplus/inspect_sqlserver_backup.ps1`、`restore_sqlserver_backup.ps1`、`create_tplus_readonly_login.ps1` 使用 Docker 容器路径，只用于现有 2022 PoC。不能把这些脚本原样用于 Windows 虚拟机。已有虚拟机不重复运行创建脚本。
+
+## 连接配置
+
+在 `backend/` 运行应用与 worker，两者使用同一套 MySQL 和 T+ 账套配置。参考 `backend/.env.example` 填写本机私有配置：
+
+| 配置项 | 用途 |
+| --- | --- |
+| `T_PLUS_ENABLED` | 默认 false；准备好只读数据源后显式启用 |
+| `T_PLUS_CONNECTION_FILE` | 项目外的本地 JSON 文件路径；管理页面不接收此路径 |
+| `T_PLUS_HOST/PORT/DATABASE/USER/PASSWORD/ODBC_DRIVER` | 未使用连接文件时填写；驱动名称必须与运行后端的电脑上已安装、实测过的驱动一致 |
+| `T_PLUS_ENCRYPT` | 默认 true；连接失败不会自动退回明文 |
+| `T_PLUS_TRUST_SERVER_CERTIFICATE` | 默认 true，适用于当前自签证书开发配置；不校验证书身份，部署可信证书后应设为 false |
+| `T_PLUS_CONNECT_TIMEOUT/QUERY_TIMEOUT` | 默认 10/120 秒；查询超时范围 1–600 秒 |
+| `T_PLUS_QUERY_DIR` | 留空使用仓库 `db/queries/tplus/`；部署时须交付查询文件 |
+
+连接文件只接受 `host`、`port`（整数）、`database`、`user`、`password`、`driver` 六个键，最大 16 KB；拒绝 `sa` 和额外配置项。文件覆盖源库连接字段，TLS 和超时仍取应用配置。连接文件、真实密码与完整连接串不入 Git、不贴到确认单或报告。
+
+默认加密可能使旧驱动或未配置 TLS 的实例连接失败。先核对驱动与服务端能力；确需临时回退时，仅在隔离开发环境显式设置 `T_PLUS_ENCRYPT=false`，记录原因、范围和复测结果。此次变更只更新代码默认值与模板，既有私有配置不会自动被覆盖。真实 10.50.1600 的 TLS 兼容仍待实测。
+
+## 启动与排队
+
+依赖安装使用项目锁文件；已有环境无需重新安装。需要 T+ 驱动依赖时，在 `backend/` 执行 `uv sync --extra tplus`，ODBC 系统驱动另按实际环境准备。
+
+```powershell
+# 在 backend/ 目录执行，先完成本机私有配置
+uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
+# 另开终端，在 backend/ 目录消费已排队任务
+uv run python -m app.cli tplus-worker --watch
+# 单次消费队列中的一个任务
+uv run python -m app.cli tplus-worker --once
+```
+
+管理员在 `/system/tplus` 创建读取或关联核验任务。HTTP 只入队，worker 负责执行；启动 worker 本身不会创建定时任务。`--connection-file` 可显式指定本地连接文件，后端仍需配置相同账套。
+
+```powershell
+# 直接暂存一个实体；不会写工资业务表
+uv run python -m app.cli tplus-stage --entity personnel
+# 只读兼容检查；报告写入忽略目录，默认基准 10.50.1600
+uv run python ../scripts/tplus/check_compatibility.py --connection-file "D:\work\app\tplus-sqlserver\reader.local.json" --report "../.ai/tplus-compatibility.json"
+```
+
+兼容脚本与应用共用配置入口。退出码 0 表示脚本覆盖的检查通过，2 表示不通过；完整验收还需权限审计、断连、重跑和对账。只有经确认需要验证其他补丁版本时才使用 `--expected-version`，报告中的版本不能冒充默认基准通过。
+
+## 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 页面显示未配置 | 核对开关、连接文件权限、只读账号与驱动；配置就绪不等于连通 |
+| 批次停在 QUEUED | 核对 worker 是否运行，以及它与后端的 MySQL 配置是否一致 |
+| 批次 FAILED/PARTIAL | 查看脱敏错误码；排除原因后在页面重试，保留原批次，勿直接改终态 |
+| 进程中断后留有 RUNNING | worker 下次取得执行锁后恢复中断状态；确认原因后重试 |
+| 加密连接失败 | 按上文核对 TLS；程序不自动关闭加密 |
+| 版本检查不通过 | 核对报告实际版本；2022 或其他补丁版本都不算 10.50.1600 同版本通过 |
+
+当前暂存 JSON 可能包含手机号。本轮按用户批准的计划暂不加密或掩码，已在确认清单 S1 记录开发阶段风险接受；这不代表客户已批准生产保留。数据库访问、备份范围和全库敏感字段策略仍需统一确认。