# 应填报工时文档重构设计

> 日期：2026-07-15
> 状态：文档拆分完成，生产部署仍暂停

## 目标

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

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

执行结果：两份原稿已移动到项目归档目录，原月度文档路径已重建为兼容入口，临时交接文件原路径已清理。

## 当前问题

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

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

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

## 目标目录

```text
后端/阿科德斯/
├── 应填报工时月度计算.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 份专题文档。

### 临时修复交接文件

目标文件：

```text
/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 回算功能。
- 不重组阿科德斯目录下其他业务文档。