# 一期批次1 组织人事底座（F01~F17）设计定稿 —— agent.develop 开发过程记录

- 迭代：人事系统-初始迭代（批次1：组织人事底座 + 系统管理与权限基座）
- 阶段：agent.develop（设计评审定稿 → 开发基线）
- 需求基线：SRS v3.1（`docs/00-requirement/requirement-spec.md`）+ `iteration1-function-detail.md`（F01~F15，81 条）+ `approved-features.md`（FEAT-B1-01~12）
- 技术口径：ocai 规范 —— bricks + dspy 前端 / ahserver(Python) 后端 / apppublic/sqlor(MariaDB，库 hrs) / 应用 hr-web
- 归档：交付件正本在 `deliverables/agent.develop/`；设计基线文档在 `docs/01-design/`（git 已推送）

## 1. 阶段目标与结论

目标：对 agent.design 产出的 4+2 份设计文档完成评审修订与定稿，形成可直接驱动 T01~T27 开发任务的契约基线。

结论：**设计定稿通过，基线冻结**。设计文档 6 份共 143,521B，与 SRS v3.1 完全对齐：F01~F17（17 功能，90 条验收项）、49 张业务表、112 个业务端点（另有 CRUD 自动生成端点族）、32 条 UI 路由、D1/D3/D4/D9/扫码入职/考勤与绩效桩位降级方案与二期预留均已覆盖。

## 2. 评审修订记录（与 SRS v3.1 对齐的差异项）

| # | 评审发现 | 修订动作 | 落点 |
|---|---|---|---|
| 1 | 批次1范围由原 F01~F15（81 条）扩入 FEAT-B1-10 编制管理、FEAT-B1-11 项目式组织 | 新增 F16 编制管理（6 条）、F17 项目式组织（3 条），验收项合计 81→90 | feature-list.md §1；architecture.md §0 |
| 2 | 表数量口径原为 43 张，未含编制/项目式/开放接口预留表 | 扩为 49 张：新增 org_headcount_scheme/headcount_item/headcount_snapshot/org_project/org_project_post/sys_openapp 共 6 张 | database-design.md §4 |
| 3 | 技术口径原写"部署端口 8000"类旧值 | 统一 9182（测试+生产）、MariaDB 库 hrs、systemd 管理、mysqldump 每日备份 ≥30 天 | architecture.md §7 |
| 4 | 降级项缺设计落点 | 新增降级项设计专章 + 降级桩端点汇总：D1 手工录入、D3 钉钉交接占位、D4 模板文本+esign_stub、D9 站内兜底、扫码入职内网链接/二维码、考勤/绩效桩位 | architecture.md §10；api-design.md §5 |
| 5 | F01~F15 缺 FEAT 编号映射 | 建立 F01~F17 ↔ FEAT-B1-01~12 映射表与验收项计数（6+5+8+7+4+4+7+3+6+7+4+4+6+5+5+6+3=90） | feature-list.md §1 |
| 6 | API 开放接口（FEAT-B1-01⑦）无规范 | 新增 API 开放接口规范 §9（签名鉴权/sys_openapp/openapi ping 桩） | architecture.md §9 |
| 7 | 缺 staff-mgr 迁移方案 | 新增 v1→hrs 迁移策略（映射/解密重加密/幂等/核对报告） | database-design.md §8；architecture.md §6 |
| 8 | 任务拆解颗粒度不足 | 重排为 T01~T27（约 92 人日），契约先行、含降级项任务落点表与集成验收标准 | iteration1-task-breakdown.md |

## 3. 定稿文档清单（git 仓 docs/01-design/，HEAD 与工作区一致）

| 文档 | 版本 | 字节数 | 关键内容 |
|---|---|---|---|
| architecture.md | v2.0 | 29,403B | 技术选型/模块边界/依赖/部署(9182/MariaDB hrs/systemd)/安全/NFR响应表/API开放规范§9/降级项专章§10 |
| database-design.md | v3.0 | 40,259B | 49表清单/字段/索引/ER/models JSON/DDL等价示例/数据字典/staff-mgr迁移/验收映射 |
| api-design.md | v2.0 | 29,356B | 112业务端点请求响应契约/错误码11类/典型调用链/降级桩端点表/安全要点 |
| ui-design.md | v3.0 | 23,929B | 菜单路由32条/页面组件树12组/交互时序/设计规范/页面-接口追溯 |
| feature-list.md | v2.1 | 7,103B | F01~F17↔FEAT映射/90条验收项计数/功能-模块-表落点/范围外与降级项 |
| iteration1-task-breakdown.md | v2.0 | 13,471B | T01~T27任务/依赖/估时(约92人日)/验收对照/集成验收标准 |

合计 143,521B（`wc -c docs/01-design/*.md` 实测）。

## 4. git 提交证据（hr-system 仓，远端 git@git.opencomputing.cn:yumoqing/hr-system.git）

| commit | 说明 |
|---|---|
| e6b266f / bfc1003 | design: 批次1设计评审定稿初版（后被误截断） |
| 857c1fd / 8e0a767 / 5a96df5 / 049e63c | fix(design): 恢复6份设计文档完整正文 143,521B（截断问题闭环，PM 复核通过） |
| 043916b | agent.develop: 批次1开发基础——数据契约(models JSON)+ahserver/bricks工程脚手架+DDL迁移基座(T01/T02 准备) |
| d801859~75d9ba3 | agent.develop: 批次1开发基础 T01/T02 —— 49 表 models JSON 契约 + ahserver/bricks 脚手架 + DDL 迁移基座 |
| 50f351b | develop: 响应 QC 三轮退回——补齐 design-review-record.md（评审定量核对/问题闭环 R1~R9/QC 逐条响应/定稿结论）+ deliverables/agent.develop 交付件索引归档 |

验证方式：`git log --oneline` / `git show --stat <commit>` / `git status`（工作区 clean，与 origin/main 一致）。

## 5. 定稿后变更控制

1. 设计基线冻结：表结构、端点签名、路由、权限矩阵任何变更须走设计评审（修改 docs/01-design/ 四份文档 + 评审记录）。
2. T01~T27 开发任务以 `iteration1-task-breakdown.md` 为准建卡；每任务交付模块仓代码 + 对应验收项自测记录。
3. T27 集成验收标准：90 条验收项全部通过；P0（FEAT-B1-01~05）100%；降级项专项验证（D1/D3/D4/D9/扫码登记）；性能抽测（列表 ≤500ms、报表 ≤3s、导入 500 行 ≤30s）；权限与脱敏抽测（SRS §10）。

## 6. 遗留与风险

| 项 | 说明 | 处置 |
|---|---|---|
| 5 个模块仓库（hr_org/hr_roster/hr_flow/hr_contract/hr_report）尚未建仓 | modules/*.md 中为规划地址，实测 ls-remote 不存在 | T01 任务首项：建仓；以 PM 确认地址为准 |
| hr-system 复用现有 hr-system 仓 | sys_ 8 张表模型与端点直接在现仓开发 | 无 |
| appbase/rbac 沿用基础包 | 登录/用户/字典/rbac 不自研 | T02 验证加载与四角色初始化 |

## 7. 第四轮 QC 意见响应（补记）

第四轮 agent.qc 共 31 条退回意见（针对此前失败运行、deliverables/agent.develop 仅占位文件的状态）。本轮实测确认全部缺失项已补齐：

1. 交付件：deliverables/agent.develop/ 下 12+ 文件实测存在（含 batch1-design-finalization 24,592B、qc-response-and-index 6,872B、docs-01-design/ 7 份副本与仓内正本 md5 逐一一致）。
2. 设计基线：docs/01-design/ 6 份共 152,146B（含 design-review-record.md，已补录 §7 第四轮 QC 响应，v1.1）。
3. 定量核验：49 表 / 113 端点行 / 32 路由 / 27 任务 / 90 验收项 / models JSON 49 份，全部逐行计数通过。
4. git 证据：提交前 HEAD=origin/main=a3771ae，工作区 clean；本次补档提交后见 §4 更新。
5. 逐条响应总表：deliverables/agent.develop/qc4-response-final.md；design-review-record.md §7 同步归档。

结论不变：**设计定稿通过，基线冻结（PM 复核验收通过）**，后续开发按 T01~T27 任务拆解执行。