9.0 KiB
9.0 KiB
迭代1总体设计 —— 技术可行性与开发任务拆解（hr-web）
- 版本：v1.0（迭代1-总体设计配套文档）
- 状态：评审通过（主agent评审，基线冻结）
- 基线：
docs/01-design/architecture.md（架构）+database-design.md（43 表）+api-design.md（端点清单）+ui-design.md（页面结构） - 需求基线：
docs/00-requirement/requirement-spec.md（SRS v2）+iteration1-function-detail.md（F01~F15，81 条验收项）
1. 技术可行性说明
1.1 技术栈成熟度（ocai 规范）
| 能力诉求 | ocai 设施 | 成熟度结论 |
|---|---|---|
| 声明式 CRUD 页面 | json/*.json + xls2ui 自动生成 DataViewer/Form/Tree | 成熟（产线既有模式）；迭代1约 20 个 CRUD 页面零手写 |
| 组织树/架构图 | Tree widget + org_unit parent_id 自引用 + as_of 历史查询 | 可行；历史架构靠 org_unit_change 时间轴回放/有效期区间过滤 |
| 自定义字段（花名册/组织） | EAV 双表 + field_def 元数据驱动表单渲染 | 可行；列表页采用"主表分页+值表批量拼装"规避 EAV 性能问题 |
| 审批引擎 | flow_def/node_def JSON 配置 + flow_instance/task 状态机 | 可行；迭代1仅串行节点 + any/all 通过规则，不做并行分支（满足 F10 验收） |
| 审批通过自动回写 | biz_type+biz_id 关联 + ServerEnv 注册回调 hook | 可行；模块宿主无关原则下经 load_xxx() 注册函数互调 |
| 批量导入导出 | ahserver 后台任务 + openpyxl + files/ 结果文件 | 可行；100 人量级同步/准同步处理即可 |
| 数据范围权限 | rbac 路径级 + sys_data_scope（组织/字段双维度）查询叠加 | 可行；复用 rbac-permission-initialization-pattern |
| 脱敏/审计 | roster_field_def.sensitive + sys_audit_log 前后 JSON | 可行；替代 staff-mgr 硬编码 MaskUtil |
| 图表报表 | bricks Chart widgets（bricks-chart-widgets 技能） | 可行；聚合 SQL 只读查询 |
| 提醒推送 | cron 扫描 remind_scan + sys_message 站内消息 | 可行；短信/邮件通道预留 send_channel 字段 |
1.2 规模与性能
100 人账号、单实例部署（nginx + ahserver + MySQL + Redis）。最大表量级：花名册 100 行、字段值 ≤100×100=1 万行、审计日志年级 ≤10 万行。全部查询在索引覆盖下远低于 500ms 指标；组织树/主数据全量加载无分页压力。导入导出 100 人 × 50 字段 openpyxl 秒级完成。
1.3 主要风险与对策
| 风险 | 等级 | 对策 |
|---|---|---|
| EAV 自定义字段在列表页的筛选/排序复杂度 | 中 | 迭代1筛选支持"主表字段 + 至多 3 个自定义字段等值匹配"，排序仅主表字段；超出部分作为已知限制写入 UAT 说明 |
| 审批引擎配置化过度导致返工 | 中 | 迭代1锁定"串行节点、any/all、字段权限、抄送"能力边界；并行/条件分支留 flow_node_def JSON 扩展位 |
| staff-mgr 旧数据语义差异（status/加密算法） | 中 | 迁移脚本内置映射表 + 核对报告 + UAT 双库比对（见 database-design.md §7） |
| 6 模块并行开发契约漂移 | 中 | 本文 T01 先行冻结表定义 models JSON 与 api-design 端点签名，变更走设计评审 |
| 提醒场景字段依赖（健康证/社保等花名册字段未建） | 低 | init/data.json 预置 REMIND_SCENE 对应字段定义，remind_scan 按 field_def 取数 |
1.4 已裁决口径（对 baseline-decision 遗留问题）
- Q1 双口径：统一 ocai（本设计全套）。
- Q6 删除语义：迭代1员工/组织不做物理删除与逻辑删除标记，统一走停用/离职流程（database-design.md §1.3、api-design.md §4）。
- 其余 Q2~Q5/Q7 以本设计为评审结论：自定义字段排序限主表字段（1.3）、审批引擎能力边界（1.3）、迁移幂等策略（db §7）。
2. 开发任务拆解（T01~T24，契约先行）
依赖关系：T01~T02 为契约冻结阶段，全量先行；其后按模块并行。工作量单位：人日（估算，供 PM 排期）。
阶段0 契约与脚手架
| 编号 | 任务 | 内容/产出 | 依赖 | 估时 |
|---|---|---|---|---|
| T01 | 数据契约冻结 | 6 模块仓库建仓（hr_org/hr_roster/hr_flow/hr_contract/hr_report，hr-system 复用既有空仓）；43 张 models/*.json 全量提交；json2ddl 生成 DDL 验证 | — | 4 |
| T02 | 应用脚手架 | hr-web 应用仓（app/hr_web.py、conf/config.json 含 processors/indexes/session、build.sh、.env）；appbase/rbac 加载验证；登录走通 | T01 | 2 |
阶段1 主数据与底座（可并行）
| 编号 | 任务 | 内容/产出 | 依赖 | 估时 |
|---|---|---|---|---|
| T03 | hr-org 组织管理 | org_unit CRUD/树/停用/移动、org_field_def 自定义字段、org_unit_change 时间轴、org_tree/org_import 端点、org_tree.ui/org_chart.ui（F01） | T01,T02 | 5 |
| T04 | hr-org 职位职级 | org_job/position/sequence/grade_level/grade_rank CRUD + 导入导出 + options 端点（F02） | T03 | 3 |
| T05 | hr-roster 字段体系 | roster_field_group/field_def/type_rule/empno_rule 配置页与端点、工号生成器（F03 搭建类验收 1/2/3/6） | T01,T02 | 4 |
| T06 | hr-roster 花名册主体 | roster_employee CRUD、EAV 值表读写、roster_list/employee_detail/timeline、脱敏与字段可见（F03 验收 4/5/7） | T05,T03,T04 | 6 |
| T07 | hr-roster 导入导出 | roster_import（新增/修改）、模板生成、roster_export（字段/顺序/as_of）（F03 验收 8） | T06 | 3 |
| T08 | hr-system 权限底座 | 角色/管理员/数据范围（sys_data_scope 双维度）、get_data_scope 注册、各模块查询叠加（F11） | T02 | 4 |
| T09 | hr-system 审计底座 | write_audit_log + sys_audit_log 查询/详情对比页（F12） | T02 | 2 |
阶段2 审批引擎（关键路径）
| 编号 | 任务 | 内容/产出 | 依赖 | 估时 |
|---|---|---|---|---|
| T10 | hr-flow 引擎核心 | flow_form_def/flow_def/flow_node_def/flow_role 配置、flow_start 状态机、task 生成与流转、flow_match、回调 hook 机制（F10 验收 1/2/3） | T02,T08 | 6 |
| T11 | hr-flow 审批界面 | todo/done/mine/received 列表、inst_detail 动态表单渲染、approve/reject/forward/withdraw、打印（F10 验收 5/6） | T10 | 4 |
| T12 | hr-flow 查询导出 | inst_query/inst_export、审批角色数据范围生效验证（F10 验收 3/5） | T10,T08 | 2 |
阶段3 入转调离与合同（依赖 T10 回调，可部分并行）
| 编号 | 任务 | 内容/产出 | 依赖 | 估时 |
|---|---|---|---|---|
| T13 | 入职管理 | entry_approval/entry_manual（批量）/登记表邀请与提交/黑名单校验与高亮/入职通知/复职关联（F04 全 7 项） | T10,T06 | 5 |
| T14 | 转正管理 | regular_apply（自助/代发）/regular_manual/回写花名册/转正提醒接入（F05 全 4 项） | T10,T06,T16 | 3 |
| T15 | 调动管理 | transfer_apply（含批量明细）/transfer_cancel/回写档案与花名册/调动查询（F06 全 4 项） | T10,T06 | 4 |
| T16 | 提醒引擎 | sys_remind_rule/care_config/remind_scan（转正/合同/生日/周年等场景）+ sys_message（F15 提醒类验收） | T02 | 3 |
| T17 | 离职管理 | leave_apply/leave_manual/交接项/办理离职/离职证明生成下载/一键黑名单/信息存储（F07 全 7 项，钉钉交接留扩展点） | T10,T06 | 5 |
| T18 | 兼岗管理 | concurrent_apply/兼岗记录维护/审批通过同步花名册（F08 全 3 项） | T10,T06 | 2 |
| T19 | 合同台账 | contract_type/template/info CRUD + 批量导入 + 合同审批（新签/续签/变更/终止）+ 到期提醒规则 + esign_stub 预留（F09 全 6 项） | T10,T06,T16 | 4 |
阶段4 报表、工作台、员工服务与收尾
| 编号 | 任务 | 内容/产出 | 依赖 | 估时 |
|---|---|---|---|---|
| T20 | 人事报表 | roster/entry/regular/transfer/leave 五类分析端点 + report_board.ui 图表（F13 全 6 项，数据范围受控） | T06,T13~T17 | 4 |
| T21 | 工作台 | workbench_employee/manager/admin 聚合端点与三页面（F14 全 5 项，绩效/考勤占位预留） | T10,T11,T16 | 3 |
| T22 | 员工服务 | 公告/政策发布与查询（查阅范围/下载权限）、关怀文案配置（F15 服务类验收 1~3） | T16 | 2 |
| T23 | staff-mgr 迁移 | migrate_staff_mgr.py（映射/解密重加密/幂等/核对报告）、UAT 双库比对、切换演练 | T06,T09 | 3 |
| T24 | 集成联调与验收 | F01~F15 共 81 条验收项端到端回归；性能验证（列表 ≤500ms）；load_path 全路径注册核查；部署脚本验证（dev/test） | 全部 | 4 |
合计估算：约 84 人日（不含 PM 排期缓冲）。关键路径：T01→T02→T10→T11→T13/T15/T17→T20/T21→T24。
3. 交付与验收定义
- 每个 T 任务交付：模块仓代码（models/json/wwwroot/init/scripts/skill/SKILL.md）+ 对应功能验收项自测记录。
- 契约变更（表结构/端点签名）必须回改 docs/01-design 四份文档并评审。
- T24 通过标准：81 条验收项全部通过或经 PM 确认降级项（扫码入职、身份证读取、钉钉交接、电子签为既定范围外/降级项）。