# 一期批次1总体设计 —— 技术可行性与开发任务拆解（hr-web）

- 版本：v2.0（批次1设计定稿；v2.0 变更：对齐 SRS v3.1 —— 范围扩入编制(F16)/项目式(F17)、新增降级项任务、部署任务与开放接口桩任务；任务编号 T01~T27，可直接用于 develop 角色创建开发任务）
- 状态：**设计定稿（批次1评审修订版）**
- 基线：`docs/01-design/architecture.md`（架构）+ `database-design.md`（49 表）+ `api-design.md`（端点清单）+ `ui-design.md`（页面结构）
- 需求基线：`docs/00-requirement/requirement-spec.md`（SRS v3.1）+ `iteration1-function-detail.md`（F01~F15，81 条）+ approved-features.md（FEAT-B1-01~12）

## 1. 技术可行性说明

### 1.1 技术栈成熟度（ocai 规范）

| 能力诉求 | ocai 设施 | 成熟度结论 |
|---|---|---|
| 声明式 CRUD 页面 | json/*.json + xls2ui 自动生成 DataViewer/Form/Tree | 成熟（产线既有模式）；批次1约 25 个 CRUD 页面零手写 |
| 组织树/架构图 | Tree widget + org_unit parent_id 自引用 + as_of 历史查询 | 可行；历史架构按 effective_date/expire_date + org_unit_change 回放 |
| 自定义字段（花名册/组织） | EAV 双表 + field_def 元数据驱动表单渲染 | 可行；列表页"主表分页+值表批量拼装"规避 EAV 性能问题 |
| 审批引擎 | flow_def/node_def JSON 配置 + flow_instance/task 状态机 | 可行；一期仅串行节点 + any/all 通过规则，不做并行分支（满足 F10 验收）；四类人事流程模板 init/data.json 预置 |
| 审批通过自动回写 | biz_type+biz_id 关联 + ServerEnv 注册回调 hook | 可行；roster_writeback 唯一入口，回写后联动 headcount_check 与 timeline |
| 批量导入导出 | ahserver 后台任务 + openpyxl + files/ 结果文件 | 可行；500 行 ≤30s 指标（NFR-1）在 100 人量级轻松满足 |
| 数据范围权限 | rbac 路径级 + sys_data_scope（组织/字段双维度）查询叠加 | 可行；查询/报表/导出三处强制叠加 |
| 脱敏/审计 | roster_field_def.sensitive + sys_audit_log 前后 JSON | 可行 |
| 图表报表 | bricks Chart widgets | 可行；聚合 SQL 只读查询，≤3s 指标满足 |
| 提醒推送 | cron 扫描 remind_scan + sys_message 站内消息 | 可行；≥6 场景；短信/邮件 send_channel 预留 |
| 编制实时计数 | 异动事件触发重算 + headcount_snapshot 快照 | 可行；100 人规模事件内同步重算满足"1 分钟内刷新" |
| 项目式组织 | org_project 自引用 + org_project_post 关联表 | 可行；横向职务复用 org_job(job_category=horizontal) |
| 入职登记链接/二维码 | token + tmpl 页面 + qrcode 图片生成（files/） | 可行；内网 token 鉴权免登录 |
| 合同文本生成 | openpyxl/python-docx 模板占位符替换 | 可行；一期 docx/pdf 打印下载，电子签二期 |

### 1.2 规模与性能

100 人账号、单实例部署（ahserver:9182 + MariaDB(hrs) + Redis）。最大表量级：花名册 2000 行（含离职）、字段值 ≤2000×100=20 万行、审计日志年级 ≤10 万行、编制快照 365×细分项数。全部查询在索引覆盖下远低于 500ms 指标。

### 1.3 主要风险与对策

| 风险 | 等级 | 对策 |
|---|---|---|
| EAV 自定义字段在列表页的筛选/排序复杂度 | 中 | 筛选支持"主表字段 + 至多 3 个自定义字段等值匹配"，排序仅主表字段；已知限制写入 UAT 说明 |
| 审批引擎配置化过度导致返工 | 中 | 锁定"串行节点、any/all、字段权限、抄送"能力边界；并行/条件分支留 flow_node_def JSON 扩展位 |
| staff-mgr 旧数据语义差异（status/加密算法） | 中 | 迁移脚本内置映射表 + 核对报告 + UAT 双库比对；迁移范围待 PM 确认（SRS Q3），脚本支持 --scope 参数 |
| 6 模块并行开发契约漂移 | 中 | T01 先行冻结表定义 models JSON 与 api-design 端点签名，变更走设计评审 |
| 提醒场景字段依赖（健康证/社保等花名册字段未建） | 低 | init/data.json 预置 REMIND_SCENE 对应字段定义，remind_scan 按 field_def 取数 |
| 编制占编范围条件表达力 | 低 | scope_json 采用 {conds:[{field,op,value}]} 结构，支持等值/包含；复杂表达式二期扩展 |

### 1.4 降级项任务落点（SRS §9，批次1相关）

| 降级项 | 一期落点任务 |
|---|---|
| D1 身份证读卡→手工录入 | T06（证件字段组）/T13（入职表单证件分组）/T15（档案证件展示脱敏） |
| 扫码入职→内网登记链接/二维码 | T13（entry_register 页面+token+二维码） |
| D3 钉钉交接→占位项 | T17（交接项 dingtalk_resource 类型手工登记） |
| D4 电子签→模板文本+桩 | T19（contract_text_gen + esign_stub） |
| D9 短信→站内兜底 | T16（send_channel=site；sms/email 枚举预留） |
| 考勤/绩效/工资条桩位 | T10（attendance_* 表单桩）/T21（工作台桩位卡片） |
| API 开放接口预留 | T26（sys_openapp 表 + /openapi/v1/ping 桩） |

## 2. 开发任务拆解（T01~T27，契约先行）

> 依赖关系：T01~T02 为契约冻结阶段，全量先行；其后按模块并行。工作量单位：人日（估算，供 PM 排期）。每个任务含验收对照（F#/FEAT 编号），develop 角色可直接按任务建卡。

### 阶段0 契约与脚手架
| 编号 | 任务 | 内容/产出 | 验收对照 | 依赖 | 估时 |
|---|---|---|---|---|---|
| T01 | 数据契约冻结 | 6 模块仓库建仓（hr_org/hr_roster/hr_flow/hr_contract/hr_report，hr-system 复用既有仓）；**49 张** models/*.json 全量提交；json2ddl 生成 DDL 导入 hrs 库验证；init/data.json 字典（含 HEADCOUNT_CYCLE/PROJECT_STATUS/ID_SOURCE 等新增字典） | database-design §4 全表 | — | 5 |
| T02 | 应用脚手架 | hr-web 应用仓（app/hr_web.py、conf/config.json 含 processors/indexes/session/databases.hrs、build.sh、systemd unit）；appbase/rbac 加载验证；登录走通；内置 admin+四角色初始化 | SRS §5.2-4 | T01 | 2 |

### 阶段1 主数据与底座（可并行）
| 编号 | 任务 | 内容/产出 | 验收对照 | 依赖 | 估时 |
|---|---|---|---|---|---|
| T03 | hr-org 组织管理 | org_unit CRUD/树/停用/移动（子树+员工联动）、org_field_def 自定义字段、org_unit_change 时间轴、org_import（≥200行）、org_tree.ui/org_chart.ui（as_of+导出）、合同公司 company CRUD | F01 全 6 项 + FEAT-B1-02 | T01,T02 | 5 |
| T04 | hr-org 职位职级 | org_job(含 job_category 横向位)/position/sequence/grade_level/grade_rank CRUD + 停用启用联动 + 导入导出 + options 端点 | F02 全 5 项 + FEAT-B1-03 | T03 | 3 |
| T05 | hr-roster 字段体系 | roster_field_group/field_def/type_rule/empno_rule 配置页与端点、工号生成器（多规则+冲突报错）、field_config.ui 拖拽排序 | F03 验收 1/3/6 | T01,T02 | 4 |
| T06 | hr-roster 花名册主体 | roster_employee CRUD（**含证件字段组手工录入 D1**）、EAV 值表读写、roster_list/employee_detail/timeline、脱敏与字段可见、自助修改+审核、复职 prev_employee_id 关联 | F03 验收 2/4/5/7 + F04-4/5 + SRS §2.2-4 | T05,T03,T04 | 6 |
| T07 | hr-roster 导入导出 | roster_import（新增/修改，≥500 行含更新匹配）、模板生成（按字段定义+类型规则）、roster_export（字段/顺序/as_of，强制数据范围） | F03 验收 8 | T06 | 3 |
| T08 | hr-system 权限底座 | 角色/管理员/数据范围（sys_data_scope 双维度叠加）、get_data_scope 注册、各模块查询/报表/导出叠加、role_admin.ui/data_scope.ui | F11 全 4 项 + SRS §2.2-1/2/3 | T02 | 4 |
| T09 | hr-system 审计底座 | write_audit_log（全量写操作含导入导出/审批/登录，前后值+IP）+ audit_log_list.ui 详情对比 | F12 全 4 项 + SRS §2.2-5 | T02 | 2 |

### 阶段2 审批引擎（关键路径）
| 编号 | 任务 | 内容/产出 | 验收对照 | 依赖 | 估时 |
|---|---|---|---|---|---|
| T10 | hr-flow 引擎核心 | flow_form_def/flow_def/flow_node_def/flow_role 配置（含考勤桩位 attendance_*）、flow_start 状态机、task 生成与流转、flow_match、回调 hook 机制、init 预置人事四类流程模板 | F10 验收 1/2/3 + FEAT-B1-01 ①②③ | T02,T08 | 6 |
| T11 | hr-flow 审批界面 | todo/done/mine/received 列表、inst_detail 动态表单渲染（节点字段权限）、approve/reject/forward/withdraw、inst_print A4 | F10 验收 6/7 + F14-4 | T10 | 4 |
| T12 | hr-flow 查询导出 | inst_query/inst_export、审批角色数据范围生效验证 | F10 验收 3/6 + FEAT-B1-01 ④ | T10,T08 | 2 |

### 阶段3 入转调离与合同（依赖 T10 回调，可部分并行）
| 编号 | 任务 | 内容/产出 | 验收对照 | 依赖 | 估时 |
|---|---|---|---|---|---|
| T13 | 入职管理 | entry_approval（含证件手工录入）/entry_manual（批量）/**登记表邀请：token+二维码+entry_register.tmpl（扫码入职降级）**/entry_register_submit/黑名单校验与高亮/入职通知/复职匹配 | F04 全 7 项 + FEAT-B1-05 | T10,T06 | 6 |
| T14 | 转正管理 | regular_apply（自助/代发）/regular_manual/回写花名册（状态+转正日期）/转正提醒接入（probation_end_date 提前 7 天可配） | F05 全 4 项 + FEAT-B1-06 转正 | T10,T06,T16 | 3 |
| T15 | 调动管理 | transfer_apply（批量 ≥20 人明细）/transfer_cancel/回写档案+时间轴/调动查询（状态/类型/日期）/编制联动提醒接入 | F06 全 4 项 + FEAT-B1-06 调动 | T10,T06 | 4 |
| T16 | 提醒引擎 | sys_remind_rule（≥6 场景）/care_config（生日/周年文案）/remind_scan（转正/合同/生日/周年/退休/离职生效扫描）+ sys_message（send_channel=site，sms/email 预留 D9） | F15 提醒类验收 1/4/5 | T02 | 3 |
| T17 | 离职管理 | leave_apply/leave_manual/交接项（**含 dingtalk_resource 占位手工登记 D3**）/到期自动生效（leave_effect）/离职证明 PDF 生成下载/一键黑名单/离职员工信息存储可查可改 | F07 全 7 项 + FEAT-B1-07 | T10,T06,T16 | 5 |
| T18 | 兼岗管理 | concurrent_apply/兼岗记录维护/审批通过自动同步（状态 active，供薪酬引用） | F08 全 3 项 + FEAT-B1-04 兼岗 | T10,T06 | 2 |
| T19 | 合同台账 | contract_type/template/info CRUD + 批量导入 + 合同审批（新签/续签/变更/终止）+ **contract_text_gen 模板生成文本（D4 打印下载）** + 到期提醒规则（误差 ≤1 天）+ esign_stub/esign_status 预留 | F09 全 6 项 + FEAT-B1-08 | T10,T06,T16 | 4 |

### 阶段4 编制/项目式/报表/工作台/服务与收尾
| 编号 | 任务 | 内容/产出 | 验收对照 | 依赖 | 估时 |
|---|---|---|---|---|---|
| T20 | 编制管理 | headcount_scheme/item CRUD + scope_json 占编范围编辑器 + headcount_check 异动联动（提醒不硬拦截）+ snapshot 快照/历史回溯 + headcount_board/config.ui | F16 全 6 项 + FEAT-B1-10 | T06,T13~T18 | 4 |
| T21 | 项目式组织 | org_project/org_project_post CRUD + project_tree.ui + 横向职务(job_category=horizontal)维护与 options + 到期自动标识 | F17 全 3 项 + FEAT-B1-11 | T04,T06 | 3 |
| T22 | 人事报表 | roster/entry/regular/transfer/leave 五类分析端点（维度可配置）+ report_board.ui 图表 + report_export（与页面一致）+ 全程数据范围 | F13 全 6 项 + FEAT-B1-12 | T06,T13~T18 | 4 |
| T23 | 工作台 | workbench_employee/manager/admin 聚合端点与三页面（**工资条/绩效/考勤桩位卡片**）+ 消息铃铛 | F14 全 5 项 + FEAT-B1-09 工作台 | T10,T11,T16 | 3 |
| T24 | 员工服务 | 公告/政策发布与查询（查阅范围/下载权限）、关怀文案配置、message_list | F15 服务类验收 1~3 + FEAT-B1-09 服务 | T16 | 2 |
| T25 | staff-mgr 迁移 | migrate_staff_mgr.py（映射/解密重加密/幂等/--scope 参数/核对报告总数+抽样）、UAT 双库比对、切换演练 | NFR-8 + SRS §11-Q3 参数化 | T06,T09 | 3 |
| T26 | API 开放预留与部署 | sys_openapp 表 + /openapi/v1/ping 桩端点；部署脚本（systemd/备份 crontab/监控探活脚本，9182 端口测试+生产）；HTTPS 升级路径文档 | FEAT-B1-01 ⑦ + SRS §8 + NFR-3/5 | T02 | 3 |
| T27 | 集成联调与验收 | F01~F17 共 **90 条**验收项端到端回归；性能抽测（列表 ≤500ms/报表 ≤3s/导入 500 行 ≤30s）；权限与脱敏抽测（SRS §10-2）；load_path 全路径注册核查；降级项 D1/D3/D4/D9/扫码登记 专项验证 | SRS §10 验收总纲 | 全部 | 5 |

**合计估算：约 92 人日**（不含 PM 排期缓冲）。关键路径：T01→T02→T10→T11→T13/T15/T17→T20/T22→T27。

## 3. 交付与验收定义

- 每个 T 任务交付：模块仓代码（models/json/wwwroot/init/scripts/skill/SKILL.md）+ 对应功能验收项自测记录。
- 契约变更（表结构/端点签名）必须回改 docs/01-design 四份文档并评审。
- T27 通过标准：90 条验收项全部通过；P0（FEAT-B1-01~05）100% 通过；降级项按 SRS §9 验证桩位与降级方案生效（D1 手工录入+脱敏、D3 交接占位、D4 模板文本+NOT_ENABLED 桩、D9 站内兜底、扫码登记内网闭环）；性能/权限/脱敏抽测记录齐备（SRS §10）。
- 批次1完成即满足批次2（薪酬）进入条件：花名册/组织/流程/报表基线 + 权限日志基线 + 消息通道（SRS §1.4）。