akds/docs/superpowers/specs/2026-07-15-workhours-docs-restructure-design.md

应填报工时文档重构设计

日期：2026-07-15 状态：目录与拆分方案已确认，等待设计文档审核后执行

目标

把分散、重复且同时承载多种职责的应填报工时文档，收敛为一个项目目录。后续业务规则、程序逻辑、数据治理和变更记录统一在该目录维护。

本次只整理文档，不修改程序代码，不执行部署。

当前问题

应填报工时月度计算.md 已超过 480 行，同时包含：

• 当前业务规则与同步流程
• 宜搭字段、接口和程序实现
• 本地运行、数据删除和验证操作
• 多阶段变更历史与故障修复记录
• 一次性数据修复结果

临时目录中的 阿科德斯-应报工时修复-2026-07-15.md 又重复记录了执行结果、交接过程和过期恢复步骤。两份文档存在重复和历史口径混入当前流程的风险。

目标目录

后端/阿科德斯/
├── 应填报工时月度计算.md
└── 应填报工时/
    ├── README.md
    ├── 01-业务规则与同步流程.md
    ├── 02-字段接口与程序实现.md
    ├── 03-运维验证与数据治理.md
    ├── 04-变更记录.md
    └── 归档/
        ├── 2026-07-15-单文件原稿.md
        └── 2026-07-15-Claude交接与修复原稿.md

文件职责

兼容入口：应填报工时月度计算.md

保留原路径，改为不超过一页的兼容索引：

• 标明唯一维护入口为 应填报工时/README.md
• 展示当前数据与部署状态
• 链接各专题文档
• 不再复制字段表、接口表和历史记录

README.md

作为项目总入口，仅保留：

• 项目目标和当前有效结论
• 当前代码分支、提交与部署状态
• 数据修复最终结果
• 文档导航
• 尚未启用的项目变更同步等后续项

01-业务规则与同步流程.md

维护唯一的业务口径和程序主流程：

• 月度全量同步
• 每日增量补漏
• 工作日计算
• 内部/外部员工 Manager 规则
• 未来日期过滤
• 离职日期边界
• 重复记录判定与保留规则

02-字段接口与程序实现.md

维护实现细节：

• 表单与字段映射
• Java 模块、类和方法职责
• Controller 接口
• 宜搭请求和字段格式
• 分页、限流、并发与重试策略

03-运维验证与数据治理.md

维护操作流程和安全门槛：

• 本地隔离服务启动与停止
• dry-run 优先规则
• 回填、重复、离职后和未来数据清理
• 正式删除前确认要求
• 删除后复查清单
• 测试、打包和生产部署流程
• 敏感日志与定时任务注意事项

04-变更记录.md

维护按日期排序的变化与结果：

• 功能变更历史
• 重要故障及修复
• 2026-07-15 数据治理实际数量
• 关联提交和部署状态

历史记录只描述当时情况，不再承担当前操作指引。

原文件处理

月度计算单文件

1. 使用 mv 把当前完整原稿移动到 应填报工时/归档/2026-07-15-单文件原稿.md。
2. 在原路径新建简短兼容索引。
3. 从归档原稿提取内容，按职责写入 4 份专题文档。

临时修复交接文件

目标文件：

/Users/malk/Desktop/Tech/claude/临时/阿科德斯-应报工时修复-2026-07-15.md

处理方式：

1. 把当前有效的执行结果、代码状态和待部署状态收敛到 README.md、03-运维验证与数据治理.md、04-变更记录.md。
2. 历史 Claude 交接、过期恢复步骤和原始疑问不进入当前流程文档。
3. 使用 mv 将完整原稿移到 应填报工时/归档/2026-07-15-Claude交接与修复原稿.md。
4. 原临时路径不再保留文件，后续不从临时目录维护应填报工时逻辑。

采用移动归档而非不可恢复删除，既满足原路径清理，也保留必要追溯能力。

内容去重规则

• 当前规则只在 01 维护，其他文档通过链接引用。
• 字段和接口只在 02 维护。
• 可执行操作和安全要求只在 03 维护。
• 时间线和历史数据只在 04 维护。
• README 和兼容入口只写摘要，不复制大段正文。
• 归档文件只用于追溯，不作为当前操作依据。

验证标准

整理完成后检查：

1. 原兼容入口存在且所有链接有效。
2. 应填报工时/ 下每份专题文档职责单一。
3. 临时目录中的原交接文件已不存在，归档副本存在。
4. 当前有效规则与 Java 程序逻辑一致：每日读取离职日期、离职当天保留、次日起不写、重复清理默认 dry-run。
5. 数据结果一致：重复删除 35、离职后删除 796，三项复查 toDelete=0。
6. 本次部署状态明确为“待部署”，不误写为已上线。
7. 文档不记录系统令牌、访问令牌、Cookie 或密码。

不在本次范围

• 不修改 Java 程序和配置。
• 不执行生产部署。
• 不处理项目变更审批 Manager 回算功能。
• 不重组阿科德斯目录下其他业务文档。