92 lines
10 KiB
Markdown
92 lines
10 KiB
Markdown
# 一期批次1组织人事底座（F01~F15，定稿范围 F01~F17）设计评审与定稿记录
|
||
|
||
- 文档：design-review-record.md（agent.develop 阶段归档）
|
||
- 评审对象：`docs/01-design/` 下 architecture.md / database-design.md / api-design.md / ui-design.md / feature-list.md / iteration1-task-breakdown.md
|
||
- 需求基线：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
|
||
- 定稿状态：**设计基线冻结（PM 已复核验收通过）**；后续契约变更须走设计评审
|
||
|
||
## 1. 评审组织
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 评审阶段 | agent.develop（设计评审定稿 → 开发基线） |
|
||
| 上游输入 | agent.design 产出的 4 份设计草稿 + agent.requirement 产出的 SRS v3.1/追溯矩阵/81 条验收项明细 |
|
||
| 评审方式 | 文档走查 + 与 SRS v3.1 逐章比对（实体模型、表数量、端点、页面、权限矩阵、降级项）+ 实测核验（wc -c / git log / git status） |
|
||
| 定稿版本 | architecture.md v2.0、database-design.md v3.0、api-design.md v3.0、ui-design.md v3.0、feature-list.md v2.1、iteration1-task-breakdown.md v2.0，合计 143,521B |
|
||
|
||
## 2. 评审范围覆盖核对（可量化追溯）
|
||
|
||
| 检查维度 | 定量结果 | 核验方式 | 结论 |
|
||
|---|---|---|---|
|
||
| 功能覆盖 | F01~F15（81 条验收项）全部覆盖，并按 SRS v3.1 §1.4 扩入 F16 编制管理（6 条）、F17 项目式组织（3 条），合计 90 条 | feature-list.md §1 映射表，6+5+8+7+4+4+7+3+6+7+4+4+6+5+5+6+3=90 | ✅ 全覆盖 |
|
||
| 数据库 | 49 张业务表（org_ 23 / roster_ 7 / flow_ 7 / contract_ 4 / sys_ 8），含字段、索引、关系约束、models JSON、DDL 等价示例 | database-design.md §4 表清单逐行计数 = 49；§5 DDL 示例 | ✅ |
|
||
| API | 112 个业务端点（hrorg 44 / hrroster 16 / hrflow 18 / hrcontract 9 / hrreport 7 / hrsystem 18）+ 1 个开放接口桩（openapi ping），含请求/响应契约、11 类错误码、角色与数据范围标注、6 条典型调用链 | api-design.md §2 端点行计数 = 113 | ✅ |
|
||
| UI | 32 条路由、12 组页面组件树、交互时序、设计规范、页面-接口追溯、四角色权限矩阵 | ui-design.md §2 路由行计数 = 32 | ✅ |
|
||
| 降级项 | D1 身份证手工录入 / D3 钉钉交接占位 / D4 合同模板文本+esign_stub / D9 站内消息兜底 / 扫码入职内网链接二维码 / 考勤绩效桩位，均有一期方案 + 二期预留接口 | architecture.md §10；api-design.md §5 桩端点表 | ✅ |
|
||
| staff-mgr 迁移 | v1→hrs 迁移策略（字段映射/解密重加密/幂等/核对报告） | database-design.md §8；architecture.md §6 | ✅ |
|
||
| 任务拆解 | T01~T27（约 92 人日），契约先行（base → org/roster/flow/contract/system 并行 → T27 集成自测），每任务含验收对照 | iteration1-task-breakdown.md §2，行数计数 = 27 | ✅ |
|
||
| 技术口径 | 端口 9182（测试+生产）、MariaDB 库 hrs、systemd 管理、mysqldump 每日备份 ≥30 天 | architecture.md §7 环境矩阵 | ✅ |
|
||
|
||
## 3. 评审问题清单与闭环（design → develop 修订）
|
||
|
||
| # | 评审发现问题 | 严重级 | 修订动作 | 落点 | 状态 |
|
||
|---|---|---|---|---|---|
|
||
| R1 | 批次1范围草稿仅 F01~F15（81 条），缺 SRS v3.1 新增的编制管理/项目式组织 | 高 | 新增 F16（6 条）、F17（3 条），验收项 81→90 | feature-list.md §1；architecture.md §0 | 已闭环 |
|
||
| R2 | 表数量口径 43 张与 SRS v3.1 不符，缺编制/项目式/开放接口预留表 | 高 | 扩为 49 张，新增 org_headcount_scheme/headcount_item/headcount_snapshot/org_project/org_project_post/sys_openapp | database-design.md §4 | 已闭环 |
|
||
| R3 | 部署口径残留旧值（dev:9080/prod:443/库 hr） | 中 | 统一 9182/MariaDB 库 hrs/systemd；v1.1 口径作废声明 | architecture.md §7 | 已闭环 |
|
||
| R4 | 降级项 D1/D3/D4/D9 只有需求描述，无设计落点与二期预留 | 高 | 新增降级项设计专章 §10 + 桩端点汇总表（字段契约/桩端点/二期恢复方式三列） | architecture.md §10；api-design.md §5 | 已闭环 |
|
||
| R5 | F01~F15 与 FEAT-B1 编号无映射，验收追溯断链 | 中 | 建立 F01~F17 ↔ FEAT-B1-01~12 映射表与逐项计数 | feature-list.md §1 | 已闭环 |
|
||
| R6 | API 开放接口（FEAT-B1-01⑦）无规范 | 中 | 新增开放接口规范 §9（签名鉴权/sys_openapp/openapi ping 桩） | architecture.md §9 | 已闭环 |
|
||
| R7 | 缺现有 staff-mgr 模块衔接与数据迁移设计（NFR-8） | 高 | 新增 v1→hrs 迁移方案（映射/解密重加密/幂等/核对报告/回滚） | database-design.md §8；architecture.md §6 | 已闭环 |
|
||
| R8 | 任务拆解颗粒度不足，无依赖与估时 | 中 | 重排 T01~T27（约 92 人日），契约先行、含降级项落点表与集成验收标准 | iteration1-task-breakdown.md | 已闭环 |
|
||
| R9 | 设计文档曾被误提交为截断占位（commit bfc1003） | 高 | 自完整版本恢复 6 份文档 143,521B，wc -c 逐一核验一致，PM 复核闭环 | git 857c1fd/049e63c/75d9ba3 | 已闭环 |
|
||
|
||
## 4. QC 退回意见逐条响应（agent.qc → agent.develop）
|
||
|
||
| QC 意见 | 响应与证据 |
|
||
|---|---|
|
||
| 1. 缺失 agent.develop 阶段交付件 | 本记录 + `deliverables/agent.develop/` 全套归档（6 份设计正本副本 + 评审记录 + QC 响应 + 开发记录 + 追溯索引）已落盘 |
|
||
| 2. deliverables/agent.develop 目录为空 | 已补齐：design-review-record.md / qc-response-and-index.md / dev-notes.md / docs/01-design/*.md（6 份副本，与仓内正本 md5 一致） |
|
||
| 3. 未提供 F01~F15 设计内容，无法确认范围完整性 | feature-list.md：F01~F15 共 81 条验收项全覆盖（另按 SRS v3.1 扩入 F16/F17 共 90 条）；§2 功能→模块→表落点完整 |
|
||
| 4. 未提供 docs/ 目录规范符合证据 | 设计文档归档于仓内 `docs/01-design/`、开发记录 `docs/02-develop/dev-notes.md`，命名/路径/格式遵循 SDLC 规范；`git ls-files` 可查 |
|
||
| 5/4(QC2)/4(QC3). 无 git 提交记录/过程痕迹 | git 提交链完整：e6b266f→bfc1003→857c1fd→8e0a767→5a96df5→049e63c→043916b→d801859→75d9ba3→（本提交），远端 git@git.opencomputing.cn:yumoqing/hr-system.git 已推送 |
|
||
| 6. 无数据库表结构/字段/索引/关系约束 | database-design.md：49 表清单（字段+索引）+ §5 核心表 DDL 等价示例（主外键/唯一约束/索引）+ models JSON + 数据字典 |
|
||
| 7. 无 API 清单/请求响应/错误码/权限 | api-design.md：112+1 端点（方法/关键请求参数/响应 data/角色/数据范围/CRUD 标注）+ 11 类错误码 + 6 条调用链 + 安全要点 |
|
||
| 8. 无 UI/交互设计 | ui-design.md：32 条路由 + 12 组页面组件树 + 核心交互时序 + 设计规范 + 页面-接口追溯 |
|
||
| 9. 无设计评审记录/问题闭环/定稿结论 | 本文档 §3 问题闭环表（R1~R9 全部闭环）+ §5 定稿结论；QC 响应即本表 |
|
||
| 10/QC3-5/QC2-6. 质量门禁不满足 | 补齐后交付件满足：真实落盘（工作区文件=完整正文，md5 可验）、可量化（90 验收项/49 表/113 端点/32 路由/27 任务）、可追溯（F→FEAT→模块→表→端点→页面双向映射）、过程合规（git 提交链） |
|
||
|
||
## 5. 定稿结论
|
||
|
||
1. **设计定稿通过，批次1设计基线冻结。** 6 份设计文档与 SRS v3.1 完全对齐：F01~F17 / 90 条验收项、49 张业务表、112+1 个端点、32 条路由、降级项 D1/D3/D4/D9/扫码/考勤桩位方案与二期预留、staff-mgr 迁移方案、T01~T27 任务拆解。
|
||
2. 技术口径（ahserver / bricks+dspy / sqlor-MariaDB hrs / 9182 / systemd）符合 ocai 规范，方案可落地；PM 已派发开发任务：base（契约+脚手架+DDL）→ org/roster/flow/system/web/migration 并行 → T27 集成自测。
|
||
3. 变更控制：表结构、端点签名、路由、权限矩阵任何变更须走设计评审（修订 4+2 份文档并更新本记录）。
|
||
4. 集成验收标准（T27）：90 条验收项全过；P0（FEAT-B1-01~05）100%；降级项专项验证；性能抽测（列表 ≤500ms、报表 ≤3s、导入 500 行 ≤30s）；权限与脱敏抽测（SRS §10）。
|
||
|
||
## 6. 版本记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|---|---|---|
|
||
| v1.0 | 定稿日 | agent.develop 评审定稿记录初版（响应 QC 三轮退回意见，补齐评审记录与问题闭环） |
|
||
|
||
## 7. 第四轮 agent.qc 意见响应（补录）
|
||
|
||
第四轮 QC 共 31 条（10+10+6+5），系针对此前失败运行（deliverables/agent.develop 仅 23B 占位文件）的退回；经实测，全部缺失项已补齐。逐条响应与证据总表归档于 `deliverables/agent.develop/qc4-response-final.md`，要点如下：
|
||
|
||
| 缺失项类别 | 补齐证据 |
|
||
|---|---|
|
||
| deliverables/agent.develop 为空 | 实测 ≥12 文件：batch1-design-finalization（24,592B）/qc-response-and-index（6,872B）/dev-notes/docs-01-design 7 份副本（md5 与仓内正本逐一一致）/qc4-response-final.md |
|
||
| docs/ 标准路径/命名/格式 | docs/01-design/ 6 份 + docs/02-develop/dev-notes.md，kebab-case、markdown、版本化（v2.0/v3.0/v2.1） |
|
||
| 架构/数据库/API/UI 设计 | architecture.md 29,403B / database-design.md 40,259B（49 表+DDL+models JSON 49 份）/ api-design.md 29,356B（113 端点+错误码+权限）/ ui-design.md 23,929B（32 路由+12 组组件树） |
|
||
| 开发过程合规证据 | repos/hr-system 真实 git 仓，提交链见 §4，HEAD=origin/main 同步 |
|
||
| 测试/验证材料 | 定量核验（90 验收项映射/49 表/113 端点/32 路由/27 任务计数 + wc -c/md5）；集成验收标准定稿于 iteration1-task-breakdown.md §3 |
|
||
| 部署/配置 | architecture.md §7（9182/MariaDB hrs/systemd/mysqldump ≥30 天）+ apps/hr-web.md |
|
||
| 定稿结论 | 设计定稿通过、基线冻结（PM 复核验收通过），已派发 7 个开发任务 |
|
||
|
||
## 8. 版本记录（续）
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|---|---|---|
|
||
| v1.1 | 定稿日 | 补录第四轮 QC 意见响应（§7），归档 qc4-response-final.md |
|