# 应填报工时文档重构 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`

- [x] **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。

- [x] **Step 2: 创建项目与归档目录**

Run:

```bash
mkdir -p '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档'
```

Expected: 目录存在，不影响阿科德斯其他业务文档。

- [x] **Step 3: 使用 mv 归档月度计算原稿**

Run:

```bash
mv '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时月度计算.md' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/归档/2026-07-15-单文件原稿.md'
```

Expected: 原稿完整保存在归档目录。

- [x] **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`

- [x] **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；本次重复与离职逻辑尚未部署。
```

- [x] **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`

- [x] **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 时不生成记录。
- 重复清理排除离职后记录，无法形成可靠键的记录保留。

- [x] **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`

- [x] **Step 1: 整理表单与字段映射**

Use `apply_patch`，只保留当前有效字段：人员、人员属性、员工编号、部门、归属公司、是否 CF、离职日期、在职状态、应填报日期、应填报工时和 Manager。系统令牌只写“通过配置或环境提供”，不得记录值。

- [x] **Step 2: 按模块整理类与方法职责**

文档必须覆盖：

- `WHConf`
- `WorkHoursCalcService`
- `WorkHoursDuplicateResolver`
- `WorkHoursController`
- `WorkHoursCalcTimer`
- `ProjectChangeSyncTimer`

- [x] **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`，文档示例不使用省略参数的危险写法。

- [x] **Step 4: 整理数据格式与性能实现**

保留员工字段数组、部门 ID 数组、日期 epoch 毫秒、日期查询区间格式；记录分月扫描、100 条批量删除、10 线程、20 QPS 和重试退避。

### Task 5: 创建运维验证与数据治理文档

**Files:**

- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/03-运维验证与数据治理.md`
- Source: 两份归档原稿

- [x] **Step 1: 写本地隔离服务操作流程**

必须使用独立端口，明确关闭：

```text
--enable.scheduling=false
--workhours.projectChangeSyncEnabled=false
--spring.task.scheduling.enabled=false
```

说明旧定时器未全部受统一开关控制，因此操作完成后立即停止本地服务。

- [x] **Step 2: 写数据治理安全流程**

顺序固定为：

1. dry-run 获取精确数量和样本。
2. 复述目标表、保留规则和待删除数量。
3. 用户明确确认。
4. 显式 `dryRun=false` 正式执行。
5. 重复、离职后、未来日期三项 dry-run 复查。

- [x] **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。

- [x] **Step 4: 写测试、打包和部署流程**

说明 16 项聚焦测试通过、JAR 不含 H2、部署必须备份旧 JAR并重启生产服务；当前状态仍为待部署，不能写成已上线。

### Task 6: 创建变更记录

**Files:**

- Create: `/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/04-变更记录.md`
- Source: 两份归档原稿

- [x] **Step 1: 迁移功能变更历史**

按日期保留 2026-04-08 至 2026-07-15 的重要变更。每行只写变更摘要、验证结果和关联提交，不复制操作步骤。

- [x] **Step 2: 迁移重要故障修复**

只保留仍有诊断价值的问题：日期查询数组格式、部门 ID、组件扫描、分月绕过 30,000、QPS 限流、未来数据、空源值、定时开关、重复和离职后治理。

- [x] **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`

- [x] **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 个专题文档和兼容入口存在；临时原路径不存在。

- [x] **Step 2: 检查 Markdown 相对链接目标**

逐个核对兼容入口和 README 的 9 个链接目标均存在，不使用 `file://` 或失效的临时路径。

- [x] **Step 3: 检查当前状态与关键业务规则**

Run:

```bash
rg -n '离职当天保留|次日起不再写入|dryRun=true|待部署|43020|35|796' '/Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时'
```

Expected: 当前规则、数据结果和待部署状态在对应单一职责文档中存在。

- [x] **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 中标记为仅限追溯。

- [x] **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`

- [x] **Step 1: 更新设计状态**

把设计文档状态改为“文档拆分完成，生产部署仍暂停”，并记录临时原路径已清理、归档目标存在。

- [x] **Step 2: 勾选实际完成步骤并执行差异检查**

Run:

```bash
git diff --check
git status --short
```

Expected: 仅设计与计划状态发生仓库内变更，业务代码无变化。

- [x] **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，不部署。