docs(workhours): 制定文档收敛执行计划

docs/superpowers/plans/2026-07-15-workhours-docs-restructure.md

@@ -0,0 +1,379 @@
+# 应填报工时文档重构 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把应填报工时的业务规则、程序逻辑、运维治理和变更记录收敛到一个项目目录，同时保留原月度文档路径作为兼容入口，并清理临时目录中的交接文件。
+
+**Architecture:** 使用一个总入口 README 和四份单一职责专题文档。两个原始长文档通过 `mv` 放入项目内归档目录，当前有效内容按职责提取到专题文档；根目录原路径只保留简短索引，临时目录原路径不再保留。
+
+**Tech Stack:** Markdown、CommonMark、Shell `mkdir`/`mv`/`test`、Codex `apply_patch`
+
+---
+
+## 文件结构与职责
+
+**创建：**
+
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/README.md`：唯一项目入口、状态摘要和导航。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/01-业务规则与同步流程.md`：唯一业务口径与程序主流程。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/02-字段接口与程序实现.md`：字段、类、方法、接口和数据格式。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/03-运维验证与数据治理.md`：本地运行、dry-run、删除确认、复查、测试和部署。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/04-变更记录.md`：功能历史、故障修复和数据治理结果。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-单文件原稿.md`：月度计算原始长文档。
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-Claude交接与修复原稿.md`：临时交接原稿。
+
+**重建：**
+
+- `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md`：原路径兼容索引，不再维护正文。
+
+**移除原路径：**
+
+- `/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md`：使用 `mv` 归档后原路径自然消失。
+
+### Task 1: 建立项目目录并归档两个原稿
+
+**Files:**
+
+- Create directory: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档`
+- Move: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md`
+- Move: `/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md`
+
+- [ ] **Step 1: 确认两个源文件存在且目标文件不存在**
+
+Run:
+
+```bash
+test -f '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md'
+test -f '/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md'
+test ! -e '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-单文件原稿.md'
+test ! -e '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-Claude交接与修复原稿.md'
+```
+
+Expected: 四条命令退出码均为 0。
+
+- [ ] **Step 2: 创建项目与归档目录**
+
+Run:
+
+```bash
+mkdir -p '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档'
+```
+
+Expected: 目录存在，不影响阿科德斯其他业务文档。
+
+- [ ] **Step 3: 使用 mv 归档月度计算原稿**
+
+Run:
+
+```bash
+mv '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-单文件原稿.md'
+```
+
+Expected: 原稿完整保存在归档目录。
+
+- [ ] **Step 4: 使用 mv 归档临时交接原稿**
+
+Run:
+
+```bash
+mv '/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-Claude交接与修复原稿.md'
+```
+
+Expected: 临时目录原路径不存在，归档副本存在。
+
+### Task 2: 创建项目总入口和兼容入口
+
+**Files:**
+
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/README.md`
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md`
+
+- [ ] **Step 1: 创建 README 项目总入口**
+
+Use `apply_patch`。README 必须包含以下确定内容：
+
+```markdown
+# 阿科德斯 · 应填报工时
+
+> 更新日期：2026-07-15
+> 唯一维护入口：本目录
+> 当前状态：数据治理完成，本次重复与离职逻辑待生产部署
+
+## 当前结论
+
+- 月度全量只生成 `workDay <= today` 的记录。
+- 每日 03:30、12:45 执行近 3 天工作日补漏，每次重新读取全量人员档案和离职日期。
+- 离职当天保留，离职日之后不再写入。
+- 重复键为员工+日期，清理时保留业务字段最完整的一条。
+- 2026-07-15 已删除重复 35 条、离职后 796 条；重复、离职后、未来日期复查均为 0。
+- 项目变更同步开关保持关闭。
+
+## 文档导航
+
+- [业务规则与同步流程](01-业务规则与同步流程.md)
+- [字段接口与程序实现](02-字段接口与程序实现.md)
+- [运维验证与数据治理](03-运维验证与数据治理.md)
+- [变更记录](04-变更记录.md)
+- [历史原稿](归档/)
+
+## 代码状态
+
+- 仓库：`/Users/malk/server/cur/akds-codex-workhours-20260715`
+- 分支：`codex/akds-workhours-20260715`
+- 文档重构前最新提交：`4c1e037`
+- 未 push；本次重复与离职逻辑尚未部署。
+```
+
+- [ ] **Step 2: 重建原路径兼容入口**
+
+Use `apply_patch`，内容保持一页内：
+
+```markdown
+# 应填报工时月度计算
+
+本文档已拆分，后续统一维护在 [应填报工时项目目录](应填报工时/README.md)。
+
+## 快速入口
+
+- [业务规则与同步流程](应填报工时/01-业务规则与同步流程.md)
+- [字段接口与程序实现](应填报工时/02-字段接口与程序实现.md)
+- [运维验证与数据治理](应填报工时/03-运维验证与数据治理.md)
+- [变更记录](应填报工时/04-变更记录.md)
+
+> 当前状态：2026-07-15 数据治理完成；重复与离职逻辑待生产部署。历史原稿仅用于追溯，不再作为操作依据。
+```
+
+### Task 3: 创建业务规则与同步流程文档
+
+**Files:**
+
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/01-业务规则与同步流程.md`
+- Source: `归档/2026-07-15-单文件原稿.md`
+
+- [ ] **Step 1: 按程序调用链整理当前业务规则**
+
+Use `apply_patch`，文档章节固定为：
+
+```markdown
+# 业务规则与同步流程
+
+## 1. 业务目标
+## 2. 当前有效规则
+## 3. 月度全量同步
+## 4. 每日增量补漏
+## 5. 工作日计算
+## 6. Manager 计算
+## 7. 未来日期与离职日期过滤
+## 8. 重复记录治理
+## 9. 规则边界与保留逻辑
+```
+
+必须明确：
+
+- `calculateAndSyncMonthlyHours` 和 `incrementalSync` 都调用 `queryAllPersonnelDetails`。
+- `incrementalSync(3)` 是近 3 个自然日内的工作日补漏，已有键直接跳过。
+- `workDay > today` 跳过。
+- `workDay > offlineDate` 跳过，离职当天保留。
+- 状态离职但离职日期为空时整人防御跳过；当前没有此类数据。
+- 外部员工当天无有效 PM 时不生成记录。
+- 重复清理排除离职后记录，无法形成可靠键的记录保留。
+
+- [ ] **Step 2: 对照 Java 源码核验方法名和边界**
+
+Run:
+
+```bash
+rg -n 'calculateAndSyncMonthlyHours|incrementalSync|queryAllPersonnelDetails|isAfterOfflineDate|cleanupDuplicateHours|cleanupAfterOffline|computeDailyPms' '/Users/malk/server/cur/akds-codex-workhours-20260715/mjava-akdsbeisen/src/main/java/com/malk/service/workhours/WorkHoursCalcService.java'
+```
+
+Expected: 文档使用的方法名均能在源码中命中，离职边界为严格大于。
+
+### Task 4: 创建字段接口与程序实现文档
+
+**Files:**
+
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/02-字段接口与程序实现.md`
+- Source: `归档/2026-07-15-单文件原稿.md`
+
+- [ ] **Step 1: 整理表单与字段映射**
+
+Use `apply_patch`，只保留当前有效字段：人员、人员属性、员工编号、部门、归属公司、是否 CF、离职日期、在职状态、应填报日期、应填报工时和 Manager。系统令牌只写“通过配置或环境提供”，不得记录值。
+
+- [ ] **Step 2: 按模块整理类与方法职责**
+
+文档必须覆盖：
+
+- `WHConf`
+- `WorkHoursCalcService`
+- `WorkHoursDuplicateResolver`
+- `WorkHoursController`
+- `WorkHoursCalcTimer`
+- `ProjectChangeSyncTimer`
+
+- [ ] **Step 3: 整理 HTTP 接口与安全默认值**
+
+接口表至少包含：
+
+- `/workhours/sync`
+- `/workhours/sync-one`
+- `/workhours/sync-batch`
+- `/workhours/backfill-cf`
+- `/workhours/backfill-company-attr`
+- `/workhours/cleanup-future`
+- `/workhours/cleanup-after-offline`
+- `/workhours/cleanup-duplicates`
+- `/workhours/sync-project-changes`
+
+必须注明 `/cleanup-duplicates` 默认 `dryRun=true`，其他删除接口正式执行时必须显式写 `dryRun=false`，文档示例不使用省略参数的危险写法。
+
+- [ ] **Step 4: 整理数据格式与性能实现**
+
+保留员工字段数组、部门 ID 数组、日期 epoch 毫秒、日期查询区间格式；记录分月扫描、100 条批量删除、10 线程、20 QPS 和重试退避。
+
+### Task 5: 创建运维验证与数据治理文档
+
+**Files:**
+
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/03-运维验证与数据治理.md`
+- Source: 两份归档原稿
+
+- [ ] **Step 1: 写本地隔离服务操作流程**
+
+必须使用独立端口，明确关闭：
+
+```text
+--enable.scheduling=false
+--workhours.projectChangeSyncEnabled=false
+--spring.task.scheduling.enabled=false
+```
+
+说明旧定时器未全部受统一开关控制，因此操作完成后立即停止本地服务。
+
+- [ ] **Step 2: 写数据治理安全流程**
+
+顺序固定为：
+
+1. dry-run 获取精确数量和样本。
+2. 复述目标表、保留规则和待删除数量。
+3. 用户明确确认。
+4. 显式 `dryRun=false` 正式执行。
+5. 重复、离职后、未来日期三项 dry-run 复查。
+
+- [ ] **Step 3: 写 2026-07-15 实际结果**
+
+记录：
+
+- 重复 dry-run：43,851 条、35 组、70 条重复、待删 35、离职后排除 796。
+- 重复正式删除：35，失败 0。
+- 离职后正式删除：796，失败 0。
+- 复查：现存 43,020、唯一键 43,020、三项 `toDelete=0`。
+- 未来日期复查截止 2026-07-15，扫描 6,908。
+
+- [ ] **Step 4: 写测试、打包和部署流程**
+
+说明 16 项聚焦测试通过、JAR 不含 H2、部署必须备份旧 JAR并重启生产服务；当前状态仍为待部署，不能写成已上线。
+
+### Task 6: 创建变更记录
+
+**Files:**
+
+- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/04-变更记录.md`
+- Source: 两份归档原稿
+
+- [ ] **Step 1: 迁移功能变更历史**
+
+按日期保留 2026-04-08 至 2026-07-15 的重要变更。每行只写变更摘要、验证结果和关联提交，不复制操作步骤。
+
+- [ ] **Step 2: 迁移重要故障修复**
+
+只保留仍有诊断价值的问题：日期查询数组格式、部门 ID、组件扫描、分月绕过 30,000、QPS 限流、未来数据、空源值、定时开关、重复和离职后治理。
+
+- [ ] **Step 3: 标明历史与当前状态边界**
+
+文档顶部写明：“历史记录只用于追溯，当前规则以 `01-业务规则与同步流程.md` 为准，当前操作以 `03-运维验证与数据治理.md` 为准。”
+
+### Task 7: 验证目录、链接、内容和敏感信息
+
+**Files:**
+
+- Verify all files under: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时`
+- Verify compatibility index: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md`
+
+- [ ] **Step 1: 检查目录结构和原路径状态**
+
+Run:
+
+```bash
+find '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时' -maxdepth 2 -type f -print | sort
+test -f '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md'
+test ! -e '/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md'
+```
+
+Expected: 2 个归档文件、README、4 个专题文档和兼容入口存在；临时原路径不存在。
+
+- [ ] **Step 2: 检查 Markdown 相对链接目标**
+
+逐个核对兼容入口和 README 的 9 个链接目标均存在，不使用 `file://` 或失效的临时路径。
+
+- [ ] **Step 3: 检查当前状态与关键业务规则**
+
+Run:
+
+```bash
+rg -n '离职当天保留|次日起不再写入|dryRun=true|待部署|43020|35|796' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时'
+```
+
+Expected: 当前规则、数据结果和待部署状态在对应单一职责文档中存在。
+
+- [ ] **Step 4: 检查敏感信息**
+
+Run:
+
+```bash
+rg -n -i 'systemToken\s*[:=]\s*[A-Za-z0-9]|access[_-]?token\s*[:=]\s*[A-Za-z0-9]|password\s*[:=]\s*[^$]' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时' -g '*.md' -g '!归档/**'
+```
+
+Expected: 当前维护文档不命中真实凭据；归档原稿不做内容输出，并在 README 中标记为仅限追溯。
+
+- [ ] **Step 5: 检查文件长度与职责边界**
+
+Run:
+
+```bash
+wc -l '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/'*.md
+```
+
+Expected: README 和兼容入口简短；四份专题文档不再把全部职责集中到单文件。
+
+### Task 8: 更新设计状态并提交计划与状态
+
+**Files:**
+
+- Modify: `docs/superpowers/specs/2026-07-15-workhours-docs-restructure-design.md`
+- Modify: `docs/superpowers/plans/2026-07-15-workhours-docs-restructure.md`
+
+- [ ] **Step 1: 更新设计状态**
+
+把设计文档状态改为“文档拆分完成，生产部署仍暂停”，并记录临时原路径已清理、归档目标存在。
+
+- [ ] **Step 2: 勾选实际完成步骤并执行差异检查**
+
+Run:
+
+```bash
+git diff --check
+git status --short
+```
+
+Expected: 仅设计与计划状态发生仓库内变更，业务代码无变化。
+
+- [ ] **Step 3: 提交仓库内状态更新**
+
+Run:
+
+```bash
+git add docs/superpowers/specs/2026-07-15-workhours-docs-restructure-design.md docs/superpowers/plans/2026-07-15-workhours-docs-restructure.md
+git commit -m "docs(workhours): 完成应填报工时文档收敛"
+```
+
+Expected: 提交成功，不 push，不部署。