|
|
@@ -0,0 +1,157 @@
|
|
|
+# 应填报工时文档重构设计
|
|
|
+
|
|
|
+> 日期：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 回算功能。
|
|
|
+- 不重组阿科德斯目录下其他业务文档。
|
