Accueil Explorer Aide
Connexion
cloudpure
/
akds
Suivre 5
Voter 0
Fork 0
Fichiers Tickets 0 Pull Requests 0 Wiki
Aborescence: e175e235b4
Branches Tags
akds
/
docs
/
superpowers
/
plans
/
2026-07-15-workhours-docs-restructure.md

2026-07-15-workhours-docs-restructure.md 14 KB
Historique Raw

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

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:

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

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

  • Step 3: 使用 mv 归档月度计算原稿

Run:

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

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

  • Step 4: 使用 mv 归档临时交接原稿

Run:

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 必须包含以下确定内容：

# 阿科德斯 · 应填报工时

> 更新日期：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，内容保持一页内：

# 应填报工时月度计算

本文档已拆分，后续统一维护在 [应填报工时项目目录](应填报工时/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，文档章节固定为：

# 业务规则与同步流程

## 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:

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。系统令牌只写“通过配置或环境提供”，不得记录值。

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

  • Step 4: 整理数据格式与性能实现

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

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

Files:

  • Create: /Users/malk/Desktop/Tech/claude/后端/阿科德斯/应填报工时/03-运维验证与数据治理.md

  • Source: 两份归档原稿

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

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

--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。

  • [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 的重要变更。每行只写变更摘要、验证结果和关联提交，不复制操作步骤。

  • 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

  • [x] Step 1: 检查目录结构和原路径状态

Run:

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:

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

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

  • Step 4: 检查敏感信息

Run:

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:

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: 更新设计状态

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

  • Step 2: 勾选实际完成步骤并执行差异检查

Run:

git diff --check
git status --short

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

  • Step 3: 提交仓库内状态更新

Run:

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，不部署。