docs(项目): 更新需求文档与开发记录

- 收录 2026-11-02 需求补齐计划、验收记录与业务口径时间线
- 新增授权使用、监控运维与产品提取操作说明
- 归档 T+ 前置计划与待确认事项，清理过期临时文档
- README 同步当前进度与权限改造说明

影响范围：仅文档，无代码变更

tasks/plan.md

@@ -1,72 +1,159 @@
-# 下一阶段开发计划：评审收口、交付设计与同版本验收
+# 当前计划：完整权限管理与操作体验（2026-11-02）
 
-日期：2026-10-28。基于关联核验与同步管理轮次完成后的实际情况制定；上一轮计划与任务清单已归档至 `tasks/archive/2026-10-27-tplus-sync-*.md`。
+按用户后续明确选择更新：角色管理配置权限，用户管理分配角色，取消个人覆盖与全局制作人绑定；管理员拥有全部功能权限，月份锁、实际经办人和审核节点保护保留；轻动效尊重减少动态效果。
 
-## 当前实际状况
+1. 权限目录与数据：复用 RBAC 表与授权版本锁；V22／V25 已应用，本轮隔离库升级 V26，本地 V26 由并行角色改造任务继续应用。
+2. 授权闭环：角色分模块配置、用户分配角色、只读继承预览、修改摘要与审计，移除重复授权入口。
+3. 后端接入：所有接口默认拒绝未登记权限，查询/写入/导出/元数据/后台任务均检查，保留工资业务约束。
+4. 前端接入：菜单/路由/按钮共用权限，提供详情与只读提示，撤权无需重新登录，避免无权限重定向循环。
+5. 验收交付：管理员、只读、区域角色、工资角色四类账号真实浏览器 6 项通过；完整单元 893 项、隔离专项 31＋52 项、Ruff、类型／构建通过，使用说明同步。
 
-- 同步管理已完成：批次/异常/重试/锁/页面验收通过；staging 累计 933,203 行，六类工资业务表尚未接入写入。
-- 口径进展：澄清清单 24 项答复基本到齐；对照表 v2 已裁决经理个人户（#7）、协助 25%（#6/#15）、信息员（#9）、企业户 3‰（#20）等冲突。9.8 方案中蓝色字体标注的原方案算法作废，毛利润率按不含运费口径执行。
-- 当前确认入口：`docs/客户待确认事项表_2026-10-28_客户版.xlsx`。业务与对接问题按 B01–B08、T01–T09 归并，环境及验收为 E01–E04，本轮增加 S1；F 列保留客户答复。旧 v2 表按用户决定删除，旧编号对应关系见 C1 第 10 节。
-- 经理个人户：微信沟通确定按 9.8 方案执行、不计个人户部分，客户群确认中；系统参数已预留，确认后调整参数即可，无需开发。
-- 工程收口：原有迁移、后端、前端与文档已拆分提交并推送；此前完整回归 990 项通过。
-- 环境基准：按用户最新决定，先以备份源 SQL Server 2008 R2 10.50.1600 推进开发验收，生产地址、账号和部署信息后补。合法介质与真实同版本实测仍待完成。
+旧计划及外部验收项保留如下；本轮不提交或推送、不启用生产或源自动采集、不生成真实工资。当前账号授权不再以绑定全局制作人为前置条件；客户环境授权仍须单独配置。
 
-## 目标与顺序
+---
 
-先完成 P0.5 连接修复、运行手册与安全决策记录，再补 D1/D2 设计和 C1 回填清单。当前继续本地开发与隔离测试；业务答复回收后按清单更新设计，再实施导入。生产环境信息不阻塞本阶段设计工作。
+# 历史计划：同步运维自动化与真实样本验收（2026-10-30）
 
-### P0 工程收口（已完成）
+> 2026-11-02 规则来源更新：先读 `docs/业务规则时间线与当前口径_2026-11-02.md`。客户第 03 项已按第二版具体场景及聊天接受方案确认；旧“讨论后答复”已被后续内容补齐。内部实现与验证、实际资料及部署验收分别跟踪，不将泛化多原单分摊或任意日期覆盖列为当前客户前置条件。
 
-1. 将本轮 T+ 同步管理成果按迁移、后端服务、前端页面、文档拆分为规范提交；合入前本地构建与测试通过。
+依据本轮批准的 T1～T6 实施；下方正式工资及历史计划保留，当前状态以本节和开发记录为准。
 
-### P0.5 评审收口（本轮）
+1. T1 已形成恢复库只读样本核对包，源单据、有效凭证、工号、候选期初与费用证据可追溯；2017 年初始化不直接当 2026 年切换余额。
+2. T2／T3 已实现每周九类原始采集、同周防重、手动协调、停机补最近一周、5／15 分钟最多两次明确断连重试、独立心跳和站内提示；生产自动化默认关闭。
+3. T4 已交付 Windows 计划托管包、预演、账号／ACL 校验、检查及停用；本机隔离进程验证通过，客户账号、实际注册、开机及三次恢复留待专用目标环境验收。
+4. T5 保持待资料：用户明确没有该样本人工指导成本；不替换为源成本或零成本，不重复索要同一资料。分类、费用、期初／历史及分管只核对本组，普通运维开发继续。
+5. T6 已完成 784 项单元、405 项完整隔离集成、V21 迁移往返及 16 项专项、Ruff、类型构建及合成接口真实浏览器验证。自动化开发、真实金额验收和生产启用分别记录。
 
-- 兼容性脚本复用应用的连接文件校验与 SQLAlchemy URL，消除手工连接串拼接；应用 URL 已有方言转义，不重复造一套转义器。
-- 默认启用加密；隔离开发环境仅允许显式回退并记录原因，不自动降级、不代填私有配置。真实旧版 TLS 兼容留待 A3。
-- 补齐 `docs/T+本地恢复与同步开发手册.md`，区分容器恢复脚本与 Windows 来宾恢复步骤。
-- 确认表新增 S1：用户已同意当前开发阶段暂不单独加密或掩码，生产保护、保留期与备份访问范围仍待统一确认；本轮不改敏感数据。
-- 定点验证连接特殊字符、默认 TLS、显式回退、错误脱敏和备份源版本判定，再在隔离 MySQL/Redis 执行完整回归。通过后分代码与文档提交推送。
+当前迁移 head 为 `21f2a3b4c5d6`，新增 V20／V21，不重写已应用迁移；仅隔离库执行。操作说明：`scripts/windows/README.md`；详细证据：`docs/同步运维自动化与样本核对开发记录_2026-10-30.md`。
 
-本轮验证结果：19 项定点、1001 项完整回归与 Ruff 通过；临时测试容器及卷已清理。确认表保留原业务答复与引文，环境材料与 S1 已更新；D1/D2 为设计交付，实际托管和告警未启用。
+后续跟踪已确认更正场景的配对／排除校验、前端选择及完整流程验证，以及 2008 R2 实机、目标环境恢复链及生产安装启用。通用多原单自动分摊和任意日期覆盖不作为当前客户待答复任务；未来实际出现未覆盖场景时再核实。既有节点 5 实现记录不替代当前缺口验证，未完成事项不因历史测试通过而勾选完成。
 
-### 轨道 A：同版本验收环境（外部依赖：安装介质）
+---
 
-- A1 先行细化 `docs/SQLServer2008R2测试环境.md`：装机步骤、恢复步骤，以及驱动、只读权限、六类查询、中文/日期/金额、断连超时、重复同步的验收清单。
-- A2 取得合法介质后，在 `D:\work\app\tplus-vm` 完成备份源 10.50.1600 环境安装；当前不是已完成状态。
-- A3 恢复原始备份并执行完整验收，产出报告，关闭同版本兼容 PENDING 状态。
+## 前一阶段计划与证据（保留）
 
-### 轨道 B：业务口径确认（外部依赖：客户填写）
+# 当前计划：正式工资闭环与项目收尾（2026-10-30）
 
-- B1 后续发送当前客户版：客户在 F 列填写业务答复，IT/服务商补充 E01–E03 的资料；同一例单可复用，已确认规则不重复提问。
-- B2 跟进客户群对经理个人户的反馈，回填 L6。
-- B3 答复回收后更新字段映射文档与暂定口径记录：二次分配三项（L3–L5）追认、三级角色职权（L7）在页面验收时核对。
+## 本次分节点执行计划与状态
 
-任务 B1–B3 是工作编号；当前客户版使用 B01/T01/E01 等编号，C1 中的旧编号仅供追溯。发送确认单是后续人工事项，本轮不代发消息。
+### 节点 1：基线与范围确认（已完成）
 
-### 轨道 C：T+ 数据导入开发（依赖轨道 B 闭环；设计可先行）
+- [x] 接续既有 `tasks/plan.md`、`tasks/todo.md` 和 `.ai/` 上下文，不覆盖未完成计划。
+- [x] 核对当前代码、迁移、测试与部署脚本，区分仓库内可完成项和必须依赖客户/目标环境的验收项。
 
-- C1 先行起草「staging → 业务表写入」设计：表映射、金额精度（金额用 Decimal、比例和日斜率用 Fraction）、幂等与重算授权留痕、人工字段保护（回款/发货批次由系统人工指定，业务归属变更不回溯历史）、事务边界；明确标注等待确认的差异点，口径闭环后评审定稿。
-- C2 主数据导入（人员、客户、产品）：依赖 #9、#10、#11。
-- C3 订单 → 发货 → 回款导入：依赖 #1–#8、#13（成本、日期、分摊、核销、初始化）。
-- C4 负向事件处理（退货、红冲、负绩效）：依赖 #8；口径已定为负绩效照公式出数、不归零。
-- C5 增量变更发现：依赖 #13；收付款表无 `updated` 字段，需验证 rowversion 与删除/作废的发现方式，在此之前时间水位保持禁用。
+### 节点 2：正式工资与 T+ 正式衔接（已完成）
 
-### 轨道 D：交付收尾（依赖 A3 与轨道 C 完成）
+- [x] 正式业务导入写入来源关联、输入版本和幂等保护，并衔接发货、回款与正式 `PayrollInput`。
+- [x] 正式 FIFO 逐段分配、期初先冲、预收、起付比例、重算级联、固化分管/交接和经理本人排除已落地。
+- [x] 月份首次生成锁、实际制作人限制、审批默认关闭、已生成工资走当月调整单已落地。
 
-- 本轮前置产出 `docs/T+交付部署设计_2026-10-28.md`：首期推荐任务计划程序，明确排队、进程恢复和业务重试的区别；周任务、阈值为设计默认，外部告警通道待确认。
-- D1 `tplus-worker` 托管（首期采用 Windows 任务计划程序）。
-- D2 每周同步任务编排与失败告警。
-- D3 客户内网独立部署与最终验收。
+### 节点 3：运维交付能力（已完成）
 
-## 验收与保留门槛
+- [x] 每周自动排队、有限重试、心跳、停止标记和异常概况已实现。
+- [x] Windows 托管任务安装/管理/启动器及隔离运行验证已通过，默认禁用且不写入凭据。
+- [x] 全量与增量备份脚本改为永久留存口径，恢复演练脚本覆盖全业务表并对查询失败判为失败。
 
-- 未确认项不进入正式核算；确认单未闭环前不实施业务表写入。
-- 导入保护人工字段；每笔回款只核算一次；重算须授权并留痕。
-- 2008 R2 验收未完成前，2022 恢复副本的结果不作为同版本兼容证据。
-- 每个任务先完成定点测试再进入依赖任务；回归使用隔离的 MySQL/Redis。
-- C1 尾部按 #1–#13、L1–L7、B1–B5/M1–M5、S1 列出答复回填顺序。业务答复、字段存在、同版本实测和生产部署分别验收，不能互相代替。
-- S1 的暂缓加密是用户批准的当前开发阶段例外；生产敏感字段策略仍是上线前待确认项。
+### 节点 4：最终验证与证据（已完成）
 
-## 项目后续路线
+- [x] 后端单元测试：`786 passed`。
+- [x] 隔离数据库集成测试：`406 passed`，失败 0、跳过 0。
+- [x] Ruff、前端 `vue-tsc`、Vite 生产构建和托管脚本隔离验证通过。
+- [x] 保留 Starlette/httpx 既有弃用提醒和 Vite 大包体积提示，均不影响本次功能验收。
 
-轨道 C 完成、A3 通过后进入轨道 D；部署验收通过即转入运维期（每周同步、参数调整走系统设置与版本管理）。
+### 节点 5：更正场景收口（已完成）
+
+- [x] 新增版本化 `CORRECTION` 事实，校验一正一负配对标识。
+- [x] 更正发货保留源快照并在预演/正式导入中排除绩效；跨客户回款按原业务标识归入，并在原客户侧自动排除。
+- [x] 补充前端事实录入、FIFO 单元测试和事实校验测试；客户确认的示例处理已落地。
+
+### 节点 6：外部验收交接（待外部条件）
+
+- [ ] 真实样本补齐分类、指导成本、运费、期初/历史已处理金额和归属依据后，完成逐笔金额核对并扩大到整月。
+- [ ] 绑定目标环境实际工资制作人账号并验证生产权限；当前不使用测试账号代替生产授权。
+- [ ] 在 SQL Server 2008 R2 `10.50.1600` 目标环境完成连接、查询和兼容性实测。
+- [ ] 在客户目标环境完成周同步、服务托管、告警与全量/增量恢复演练。
+
+节点 6 依赖客户资料、目标数据库和部署授权，不能用本地测试结果代替；其余仓库内开发任务已完成并进入交付等待。
+
+用户已批准实施四阶段计划；以下原 Docker 预演计划及未完成项保留，最新业务约束以本节及客户新回执为准。
+
+1. 权限与隔离：实际账号绑定制作人；测试库名称、显式标记和真实引擎目标同时校验；月结草稿首次成功生成即锁定该月分配，生成失败不锁，审批不解锁。
+2. 正式导入：复用源快照、稳定源身份、队列及预览指纹；新增 BUSINESS_PREVIEW／BUSINESS_APPLY。重复导入跳过，新增单据追加输入版本，旧金额／日期变化保留冲突。
+3. 正式核算：共享 FIFO 内核、期初先冲、预收待发货、60%起付与 R×R；正式台账逐段计提／应付差额独立记录；从指定月起可级联重算尚未生成工资的后续月份，已生成工资走当月调整。
+4. 归属与输出：每次发货对应业务员与当时分管经理，离职承接未发部分；经理本人业务排除。月结、报表与导出使用固化依据，调整单结构化关联原台账及分管。
+
+## 新回执对计划的修订
+
+来源：`docs/客户补充回执核对_2026-10-30.md` 与原回执副本。
+
+- 第01项已明确：同一 T+ 发货客户名头下的合同合并为一笔业务平账。正式导入按账套内客户身份聚合，保留发货层的人员／分管／交接；不再要求每合同单独平账。
+- 第02项已明确：固定取发货月份指导成本，录入完成后封存，后续跨月回款不变价。
+- 第03项已确认一正一负更正单排除绩效、跨客户回款归入原业务；多原单金额分配与通用日期更正仍只阻塞相关特殊分支。
+- 第04项为“不涉及”：不新增保证金、代收款计提。
+- 第05项最新截图已明确：保留审核能力但默认关闭；关闭时工资生成即完成且不留审批痕迹，开启时使用原财务／领导流程。
+
+## 验收与交付
+
+新增 V18/V19 迁移、输入版本、FIFO明细与生成锁；迁移只能在隔离库验证，正式目标环境执行另按授权边界。已实现不等于已验收：完整单元、隔离集成、类型／构建及浏览器检查的最终结果统一记在开发记录。真实样本尚缺实际资料，不填默认成本、余额或虚假验收结果。
+
+后续保留：多原单更正、SQL Server2008R2兼容、自动周同步、服务托管、告警、目标环境全量／增量恢复演练。备份文件不再按旧30天默认自动清理；本轮未运行清理或恢复脚本，不启用生产连接，不提交／推送。
+
+---
+
+## 上一阶段计划与原验收记录（保留）
+
+# 下一阶段开发计划：Docker 基础导入与核算预演
+
+日期：2026-10-29。按本轮用户批准计划实施。此前计划原文保留在 [历史计划](archive/2026-10-28-tplus-pre-docker-plan.md)，已有未提交内容一并保存。
+
+## 本轮目标
+
+恢复原 Docker 数据环境，先完成有依据的基础数据导入，再提供可追溯、可重跑的核算预演。预演不进入正式工资、月结、审批和发放。SQL Server 2008 R2 10.50.1600 兼容验收后置；虚拟机安装和屏幕控制不在关键路径。
+
+## 已确认的开发约束
+
+- 发货、到账日期取销货单、收款单的单据日期；销售和指导成本均含税，销售额剔除运费。
+- 绩效成本使用人工月度指导价，T+ 成本只留源快照，不导入绩效成本。
+- 回款采用明确分组内的 FIFO，不再强制合同关联；组范围、期初及历史已发款未明确时分别待补。
+- 人员按18人回执核对，工号保留前导零；不自动指定直属经理，不按姓名合并。
+- 仅导入客户性质往来单位，客户和产品核算分类允许人工维护，不做单位换算。
+- 经理本人业务排除；交接与经理分管保存独立事实，不覆盖当前人员关系推算历史。
+- 特殊抵顶继续线下；不创建清理任务，不新增生产账号或权限。
+- 全量读取、主键分页、哈希去重继续复用，时间增量关闭。源账号无写权限。
+
+## 实施顺序与验收
+
+| 阶段 | 已实施内容 | 验收信号与仍缺条件 |
+|---|---|---|
+| P1 环境及基线 | 原三容器恢复、九类源数据读取、当前指针、只读权限核验 | 当前源933203行；新增103359个历史版本来自补读单位、客户属性及凭证关联字段。2026-10-30原生ODBC连接、九类抽样和原worker重读已验证通过 |
+| P2 规则与字段 | 日期、含税、客户性质、单位、人员名单核对；业务答复与字段证据分列 | 已核实收款到总账凭证的关联；13107张已有有效凭证、75张无关联不纳入本次预演，不以审核状态代替生成 |
+| P3 基础导入 | 预览、执行、唯一源关联、人工字段保护、指纹失效、异常重试 | 实际17人导入，工号101124待核实；产品分类、客户属性不足的行保留待补 |
+| P4 FIFO与预演 | 期初先冲、预收、逐段分配、冻结重跑、交接、经理排除、页面与CSV | 功能验证与客户验收分开；真实指导价、分组和历史资料不足，不能宣称整月工资对账通过 |
+
+## 最小数据与接口
+
+V16/V17新增五张工作区表，head为 `07b8c9d0e1f2`。复用现有 `/api/v1/system/tplus` 和worker，新增事实及历史、源编号选择、工作区任务、分页明细和报告。正式核算表与预演表分开保存；原快照重跑不读取后来的成本、分类和参数。
+
+## 业务并行事项
+
+1. 平账范围：同客户统一还是按项目分开。
+2. 指导价：单位或总成本、发货月或回款月、历史处理。
+3. 历史承接：2026-02-28分组应收、已核算及已发款、8月参数。
+4. 交接及经理分管：时间、业务范围、双方人员与发货归属。
+5. 其他更正及特殊款：日期更正、保证金与其他职责；B04已于2026-10-30明确月度工资生成前可改、仅制作人可改、差额归调整单生成当月，不再追问。
+6. 逐笔复核：先以一个资料完整的平账组核对，再扩到整月。
+
+未决条件只阻塞相关分支；已明确的日期、含税、指导成本与工号不重复询问。客户表见 `docs/核算预演补充确认清单_2026-10-29.xlsx`。
+
+## 首轮结束标准
+
+真实数据可导入，逐笔过程可核对，缺口能定位。完成定点、受影响模块、隔离迁移/集成回归、前端类型/构建和浏览器检查后交付。客户逐笔验收、原生驱动、2008R2兼容与生产部署分别记录，不混为完成。
+
+验证细节见 `docs/T+基础导入与核算预演开发记录_2026-10-29.md`；任务状态见 `tasks/todo.md`。本轮不提交或推送，保留既有修改。
+
+## 2026-10-30首轮样本与新回复
+
+- 用户已授权按推荐选样本：辽阳精诚物业管理有限公司，2026-03，销货SA-2026-03-0034与收款SK-2026-03-0016各1125元；一个产品、一位业务员，关联凭证0035。
+- 已登记候选平账组pilot-9395-202603并运行待补预演；未确认开关保持关闭，未填默认指导成本、分类或期初余额。
+- B04新答复记录见docs/二次分配修改规则确认_2026-10-30.md；更正示例另按 `CORRECTION` 事实实现，不自动扩大至任意日期更正。正式工资入口按该规则的实现与验收已列节点 2、节点 5。
+- 真实字段核查纠正：SA_SaleDelivery.isCancel为结清状态枚举（428未结清、180已结清），不是作废布尔值；预演改按voucherState生效与实际红冲标志判断。