docs(审查): 记录体检修复与备份恢复验证结果

记录审查问题、修复范围、验收证据及仍待目标环境验证的边界。

docs/代码审查修复记录_2026-11-03.md

@@ -0,0 +1,61 @@
+# 代码审查修复记录（2026-11-03）
+
+依据 `chinese-code-review` 审查当前工作区，并按
+`chinese-commit-conventions` 整理中文约定式提交。
+已复核的前期 11 项问题见 [项目体检修复记录](项目体检修复记录_2026-11-03.md)。
+本轮提交范围为体检修复、备份恢复及后端镜像遗漏的迁移依赖；其他并行的
+T+ 业务、生产编排和界面改动继续保留在工作区。
+
+## 新增发现与修复
+
+| 级别 | 问题 | 修复 |
+| --- | --- | --- |
+| 必须修复 | binlog 轮转与读取末位点之间存在事务时，原脚本跳过这些事务却推进续接位点 | 同时归档末文件至该位点，后续从已归档边界续接 |
+| 必须修复 | 同实例其他数据库的 binlog 可能被重放到只恢复单库的环境 | `mysqlbinlog` 显式限定备份数据库 |
+| 必须修复 | 官方 MySQL 镜像初始化时的临时 socket 服务可能被误判为就绪 | MySQL 检查通过回环 TCP 连接，等待正式服务启动 |
+| 必须修复 | 备份检查未校验数据库名，同实例的其他数据库可能被误报为已备份 | 检查清单中的数据库名与目标配置一致 |
+| 必须修复 | Windows 备份任务安装器在 PowerShell 5 中存在编码和默认路径错误；花括号路径被当作格式串 | 使用 UTF-8 BOM，在脚本主体解析默认路径，按参数拼装动作 |
+| 必须修复 | V28 迁移从文件读取 SQL，后端镜像及构建白名单却未携带此文件 | 将迁移 SQL 纳入构建上下文并复制到运行时对应路径 |
+| 建议修改 | 新增备份程序存在 10 处 Ruff 错误 | 使用 `datetime.UTC`，保留既有检查规则 |
+
+## 备份工具使用
+
+需要 Python 3.12、Docker，以及运行中的源 MySQL 容器。
+默认容器为 `ys-mysql-dev`，数据库为 `payroll`；其他实例通过
+`--container`、`--database` 显式指定。
+
+```powershell
+backend/.venv/Scripts/python.exe scripts/payroll_backup.py full --directory D:/PayrollBackups
+backend/.venv/Scripts/python.exe scripts/payroll_backup.py incremental --directory D:/PayrollBackups
+backend/.venv/Scripts/python.exe scripts/payroll_backup.py check --directory D:/PayrollBackups
+docker build -f docker/Dockerfile.backup -t payroll-mysql-backup:8.0.46 .
+backend/.venv/Scripts/python.exe scripts/payroll_backup.py restore-drill --directory D:/PayrollBackups
+```
+
+旧四个 Bash 文件转发到相应 Python 命令；可通过 `PYTHON` 指定解释器。
+全量数据、清单、状态和增量文件必须放在同一受限持久目录。
+旧备份格式不能直接续接，首次使用需建立新全量基线。
+恢复只使用独立容器和命名卷，结束后停止并保留供复查。
+
+Windows 定时安装器默认仅预览；使用实际 Python 和备份目录路径调用，
+核对目标环境后显式使用 `-Apply` 注册。默认每天 02:30 全量、每 15 分钟
+检查增量、每天 07:30 检查备份；Interactive 任务需要用户保持登录。
+
+## 验证
+
+- 完整单元基线 950 项通过；增加 TCP 就绪及检查目标校验后，备份专项 9 项通过。
+- Ruff、前端类型检查和生产构建通过；通过 npm 官方审计接口检查生产依赖，无已知漏洞。
+- 全部 Windows 脚本通过 PowerShell 5 解析；备份安装器默认路径、空格和花括号路径预览通过。
+- Windows 托管隔离运行通过，覆盖隐藏子进程、停止标记、退出码与日志轮转。
+- 独立 MySQL 全量加两轮增量恢复通过：两次在轮转窗口插入的事务均逐值恢复；无更新返回 UNCHANGED。
+- 第三段增量同时包含目标库和其他库的写入，限定数据库重放后目标库四行逐值一致，其他库未被创建。
+- 空库升级至 V28 后，登录、系统设置、岗位、正式工资、参数和 T+ 工作区 75 项真实 MySQL 集成回归通过。
+- 后端镜像新增迁移 SQL 的路径及构建白名单通过静态核验。
+  `docker build --check` 因 Docker Hub 认证服务连接超时未完成，未重建应用镜像；不将静态核验记为镜像构建通过。
+
+备份重放证据位于 `.ai/payroll-backup-test-e2a9f6f5febc-541aae/`：
+`proof.json` 记录两轮竞态事务恢复，`filter-proof.json` 记录第三段的跨库隔离。
+演练容器在验证结束后停止，数据保留供复核。
+
+保留前端构建的大分块提示和 Starlette 测试客户端弃用提示；未降低检查规则。
+客户现场的生产连接、迁移、定时任务启用和真实工资金额仍需目标环境验收。

docs/项目体检修复记录_2026-11-03.md

@@ -0,0 +1,43 @@
+# 项目体检修复记录（2026-11-03）
+
+本次按全仓体检的 11 条问题修复代码和配置。保留工作目录中并行的核算、模板、T+ 更正及部署改动；未提交 Git。
+
+| 原编号 | 修复 | 生效范围 |
+| --- | --- | --- |
+| 1 | 恢复 V28 的建表及五条模板种子，移除误写入的 npm 缓存内容与 NUL 字节 | 新库及升级到 V28 的数据库；已通过初始化脚本建好的表继续沿用 |
+| 2 | 开发 Compose 的 MySQL、Redis 仅绑定 `127.0.0.1` | 容器下次重建时生效；本轮未重建正在使用的容器 |
+| 3 | 修正三份迁移中的 12 处 Ruff 问题，保持原检查规则 | 只调整等价字典写法及未使用变量名，不修改迁移 SQL 语义 |
+| 4 | 登录失败计数与 TTL 用 Redis 事务同时提交 | 后端加载新代码后生效 |
+| 5 | 测试运行器自动清理本次成功创建的库和账号，新增 `--keep`；复用库只清新账号 | 不清理历史隔离库；创建冲突时不删除已有对象；保持测试退出码 |
+| 6 | T+ 默认校验服务器证书，配置模板同步为 `false` | 既有环境变量的显式值继续优先；生产证书及连接另行验收 |
+| 7 | Windows 托管日志按角色保留当前及上一次 stdout/stderr，避免每分钟无限新增文件 | 后续启动使用新脚本；不清理已有历史日志 |
+| 8 | 不存在的账号也执行相同成本的 bcrypt 校验，并明确拒绝不存在的账号 | 不改变正常登录和权限规则 |
+| 9 | 移除登录 E2E 中的管理员默认口令，缺配置即退出 | 必须提供 `E2E_ADMIN_PASSWORD` |
+| 10 | ECharts 升至 6.1.0，axios 升至 1.21.0，传递依赖 follow-redirects 升至 1.16.2 | 已同步 pnpm 锁文件 |
+| 11 | logo 提交失败时删除本次新文件或恢复同名旧内容，并保留原始失败异常 | 上传失败可恢复原文件状态 |
+
+## 验证
+
+- 后端完整单元测试：936 项通过；新增账号校验、logo 回滚、运行器退出码和清理边界用例。
+- 空库 Alembic 升级至 V28 成功；登录、系统设置、岗位及正式工资 44 项隔离集成测试通过。
+- 只读核对本轮三个新建库及对应账号，剩余数量均为 0。
+- 后端及测试运行器 Ruff 检查通过，未增加规则忽略。
+- 前端 `pnpm build` 通过（包括类型检查）；生产依赖审计 0 项告警。
+- Edge 独立测试上下文验证实际监控组件及工作台图表选项：6 个 SVG 正常绘制；空状态、断点、600/1280 宽度通过，无控制台错误。使用固定测试数据，不代表真实业务数据的端到端验收。
+- Windows PowerShell 5 隔离托管验证通过：含空格路径、隐藏启动、停止标记、失败码传递及连续运行日志轮转。
+- 开发 Compose 配置校验通过，`git diff --check` 通过。
+
+## 生效步骤及边界
+
+端口限制需要重建 MySQL/Redis 容器；操作会短暂中断连接，应在确认的维护窗口执行，使用既有命名卷，不删除数据卷。本轮只交付配置，未重建容器、修改业务库或清理历史测试库。
+
+T+ 证书默认值不会覆盖现有环境变量，客户环境需先部署可信证书再验收连接。Windows 托管脚本需在下次启动时加载。真实工资金额、客户 T+ 生产连接、完整浏览器业务流程不属于本轮验证。
+
+前端仍有大于 500 kB 的构建分块提示；本次未为消除提示调整打包策略。
+
+
+## 用户授权后的端口重建（2026-11-03）
+
+已暂停并恢复原开发托管任务，使用原镜像和命名卷重建 MySQL、Redis。两个容器均为 healthy，端口仅绑定 127.0.0.1:3306 和 127.0.0.1:6379。重建前后 10 个业务表记录数一致，后端 /api/health 的 app/db/redis 均为 true。
+
+维护前已生成约 938 MB 的 MySQL 备份、Redis 快照和 SHA-256 清单；核验记录位于 `.ai/container-port-rebuild-20261103-160920/`，该目录不纳入版本管理。未删除原数据卷，未修改登录凭据，未升级镜像。