hr-system/docs/01-design/api-design.md

# 一期批次1总体设计 —— API/接口设计（hr-web，ocai 口径）

- 版本：v3.0（批次1设计定稿；v3.0 变更：对齐 SRS v3.1 —— 新增编制管理(F16)/项目式组织(F17)端点、入职登记链接与二维码端点（扫码入职降级）、合同文本生成端点（D4）、证件手工录入字段契约（D1）、开放接口桩端点、错误码扩充）
- 状态：**设计定稿（批次1评审修订版）**
- 规范依据：ocai 技能集 module-development-spec、dspy-file-implementation-spec、crud-definition-spec；架构基线 `docs/01-design/architecture.md`

## 1. 接口范式与通用约定

1. **端点形态**：全部接口为 `.dspy` 端点（受控 Python），路径 `/{module}/api/{name}.dspy`，由 ahserver wwwroot 自动路由，无需注册；GET query 与 POST body 统一解析进 `params_kw`。dspy 必须显式 `return`，且不得在 `async with db.sqlorContext` 块内 return（NoneType 陷阱）。
2. **鉴权**：session cookie（Redis 会话）+ rbac 路径级角色控制；每条路径经各模块 `scripts/load_path.py` 注册，角色：`admin / hr / manager / employee / logined`；未注册路径默认拒绝（SRS §2.2-1）。不使用 JWT。
3. **数据范围**：查询、报表、**导出**类接口强制叠加 `get_data_scope(user_id)`（hr-system 提供），范围外数据不可见、不可导出（SRS §2.2-2）。
4. **CRUD 列表/表单接口**：由 json/*.json 经 xls2ui 自动生成（列表查询、add/update/delete 包装 dspy），不在本文逐一列出；本文列出业务自定义端点。CRUD 自动生成部分约定 `new_data_url/update_data_url/delete_data_url` 位于 params 顶层。
5. **统一响应结构**：
   - 列表：`{"status":"success","data":{"rows":[...],"total":N}}`（DataViewer 强制格式）
   - 业务：`{"status":"success"|"error","message":"...","data":{...}}`
   - 错误返回 HTTP 200 + status=error（bricks 前端惯例），鉴权失败由框架返回 401/403。
6. **错误码规范**（status=error 时 data.code）：

| code | 含义 | 典型场景 |
|---|---|---|
| PARAM_INVALID | 参数缺失/格式错误 | 必填项为空、日期格式错 |
| NOT_FOUND | 对象不存在 | id 无效 |
| DUPLICATE | 唯一冲突 | 工号/组织编码/项目编码重复 |
| NO_PERMISSION | 数据范围外/角色不足 | 越权访问他人档案 |
| BLACKLIST_HIT | 黑名单命中 | 入职校验拦截（F04-6） |
| STATUS_CONFLICT | 状态不允许 | 已离职再调动、重复审批 |
| FLOW_NOT_MATCH | 无匹配审批流 | 该员工类型/部门未配置流程 |
| HEADCOUNT_OVER | 编制超编提醒（不硬拦截） | 入转调联动编制校验（F16，SRS 验收"提醒不硬拦截"） |
| NOT_ENABLED | 功能未启用（桩位） | esign_stub / openapi ping（降级项） |
| REGISTER_EXPIRED | 登记表链接过期 | 入职登记二维码超时 |
| INTERNAL_ERROR | 服务异常 | 兜底 |

7. **审计**：所有写接口成功后调用 `write_audit_log(module,target_type,target_id,op,before,after)`（hr-system）。
8. **敏感字段**：响应中身份证一律脱敏（前3后3）、手机（前3后4）、sensitive=1 字段按角色矩阵过滤，服务端处理后返回。

## 2. 端点清单（按模块）

> 角色列：A=admin，H=hr，M=manager，E=employee，L=任意登录。数据范围=是 表示叠加数据范围过滤。
> CRUD 列：该表的标准增删改查由 json/*.json 自动生成，路径为 `/{module}/{tblname}_list`(页面) + `add_/update_/delete_{tblname}.dspy`。

### 2.1 hr-org（/hrorg，F01/F02/F04~F08/F16/F17）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 | CRUD |
|---|---|---|---|---|---|---|
| /hrorg/api/org_tree.dspy | GET | 组织树（支持 as_of 历史日期、status 过滤） | as_of?, status?, keyword? | 树形节点数组(id,name,parent_id,children,status,leader_name) | L | — |
| /hrorg/api/org_unit_create.dspy | POST | 新建组织（编码唯一校验、写 org_unit_change、触发编制校验） | org_code,org_name,parent_id,org_type,leader_id,effective_date,自定义字段kv | {id} | A,H | org_unit |
| /hrorg/api/org_unit_update.dspy | POST | 编辑组织（留痕） | id,... | {} | A,H | org_unit |
| /hrorg/api/org_unit_move.dspy | POST | 移动组织（变更上级，子树整体迁移，员工任职部门联动） | id,new_parent_id,effective_date | {} | A,H | — |
| /hrorg/api/org_unit_disable.dspy | POST | 停用组织（校验无在职员工引用） | id | {} | A,H | — |
| /hrorg/api/org_change_timeline.dspy | GET | 组织时间轴 | org_id | {rows:[{change_type,before_json,after_json,operator,created_at}]} | L | — |
| /hrorg/api/org_import.dspy | POST | Excel 批量导入组织（后台任务+结果文件；≥200 行成功率 100%，错误行回报） | file(上传) | {task_id} | A,H | — |
| /hrorg/api/org_import_result.dspy | GET | 导入结果（成功/失败行下载） | task_id | {rows,total,error_file} | A,H | — |
| /hrorg/api/org_chart_export.dspy | GET | 架构图导出（按 as_of 日期） | as_of?, root_id?, fmt=png/xmind | 文件下载 | A,H | — |
| /hrorg/api/org_field_def_save.dspy | POST | 组织字段自定义 | fields[] | {} | A,H | org_field_def |
| /hrorg/api/company_save.dspy | POST | 合同公司维护（供合同/入职引用） | company_code,company_name,credit_code,... | {id} | A,H | org_contract_company |
| /hrorg/api/job_import.dspy / job_export.dspy | POST/GET | 职务批量导入导出 | file / 筛选条件 | {task_id} / 文件 | A,H | org_job |
| /hrorg/api/position_import.dspy / position_export.dspy | POST/GET | 职位批量导入导出 | file / dept_id?,status? | {task_id} / 文件 | A,H | org_position |
| /hrorg/api/job_options.dspy / position_options.dspy / grade_options.dspy / rank_options.dspy / sequence_options.dspy / org_options.dspy / company_options.dspy | GET | 主数据下拉选项（状态=active；供花名册/异动/薪酬引用） | 无/keyword | {rows:[{id,name}]} | L | org_job 等 |
| /hrorg/api/entry_approval.dspy | POST | 发起入职审批（单个，匹配审批流；含证件字段组手工录入 D1） | name,id_type,id_number,id_valid_from,id_valid_to,id_authority,employee_type,org_id,position_id,company_id,work_location,hire_date,... | {instance_id} 或 BLACKLIST_HIT/FLOW_NOT_MATCH | A,H | org_entry |
| /hrorg/api/entry_manual.dspy | POST | 手动入职（批量，直接入花名册或待入职） | entries[]:{...}, to=pending/roster | {entered:[],pending:[],blocked:[]} | A,H | — |
| /hrorg/api/entry_invite_register.dspy | POST | 批量邀请待入职填写登记表（生成 register_token/url/二维码图片，站内消息发送） | entry_ids[],expire_days? | {} | A,H | — |
| /hrorg/api/entry_register_page.dspy | GET | 登记表渲染页（按 flow_form_def biz_type=entry 表单定义动态渲染；**内网可访问，免登录 token 鉴权**） | token | 表单结构 JSON | 匿名(token) | — |
| /hrorg/api/entry_register_submit.dspy | POST | 待入职员工提交登记表（校验 token 有效期） | token,字段kv | {} 或 REGISTER_EXPIRED | 匿名(token) | — |
| /hrorg/api/entry_qrcode.dspy | GET | 入职登记二维码图片获取/重新生成 | entry_id | {qrcode_file,url,expire} | A,H | — |
| /hrorg/api/entry_blacklist_check.dspy | GET | 黑名单校验 | id_number 或 name | {hit:bool,blacklist_id?} | A,H | — |
| /hrorg/api/entry_notify.dspy | POST | 入职通知/欢迎（模板填充发送，站内渠道） | entry_ids[],template_id | {} | A,H | — |
| /hrorg/api/entry_rehire_match.dspy | GET | 复职匹配（按证件号哈希查历史档案） | id_number | {matched:bool,prev_employee_id?,last_org?,last_position?} | A,H | — |
| /hrorg/api/regular_apply.dspy | POST | 发起转正审批（自助/代发） | employee_id,regular_date | {instance_id} | E(自助),H,M | org_regularization |
| /hrorg/api/regular_manual.dspy | POST | 手动转正（直接更新花名册） | employee_id,regular_date | {} | A,H | — |
| /hrorg/api/transfer_apply.dspy | POST | 发起调动审批（支持批量人员 ≥20 人） | transfer_type,effective_date,details[]:{employee_id,to_org_id,to_position_id,to_grade_level_id} | {instance_id} | A,H,M | org_transfer |
| /hrorg/api/transfer_cancel.dspy | POST | 取消调动（保留历史不改现职） | transfer_id | {} | A,H | — |
| /hrorg/api/leave_apply.dspy | POST | 发起离职审批（自助/代发） | employee_id,leave_type,leave_reason,leave_date | {instance_id} | E(自助),H,M | org_leave |
| /hrorg/api/leave_manual.dspy | POST | 手动离职（直接入待离职/已离职） | employee_id,leave_date,leave_reason | {} | A,H | — |
| /hrorg/api/leave_handover_save.dspy | POST | 离职交接项保存（含 dingtalk_resource 占位项，手工登记内容） | leave_id,items[]:{item_type,item_content,handover_to_id} | {} | A,H,M | org_leave_handover |
| /hrorg/api/leave_effect.dspy | 内部 | 离职生效处理（离职日期到达状态转离职，remind_scan 触发） | employee_id | {} | 服务内 | — |
| /hrorg/api/leave_certificate.dspy | GET | 离职证明生成下载（按模板 PDF） | employee_id | 文件 | E(本人),A,H | — |
| /hrorg/api/blacklist_add.dspy | POST | 一键加入黑名单 | leave_id 或 id_number_hash,reason | {} | A,H | org_blacklist |
| /hrorg/api/concurrent_apply.dspy | POST | 发起兼岗审批 | employee_id,org_id,position_id,start_date,end_date | {instance_id} | A,H,M | org_concurrent_post |
| /hrorg/api/headcount_scheme_save.dspy | POST | 编制方案创建/编辑（多套方案并行） | scheme_name,cycle_type,cycle_start,cycle_end | {id} | A,H | org_headcount_scheme |
| /hrorg/api/headcount_item_save.dspy | POST | 编制细分项维护（占编范围条件+细分+数量） | scheme_id,items[]:{scope_json,seg_json,head_limit} | {} | A,H | headcount_item |
| /hrorg/api/headcount_status.dspy | GET | 编制状态看板（超编/缺编+细分实时数） | scheme_id?,as_of? | {rows:[{item,head_limit,used,over,gap}]} | A,H,M(范围) | — |
| /hrorg/api/headcount_history.dspy | GET | 历史编制查询（任意时间点快照） | scheme_id,as_of | {rows:[{snap_date,used_count,over_count}]} | A,H | — |
| /hrorg/api/headcount_check.dspy | 内部 | 异动联动编制校验（入转调回写后调用，超编写提醒消息，不拦截） | employee_id,event_type | {over:bool,scheme_id?} | 服务内 | — |
| /hrorg/api/project_save.dspy | POST | 项目式组织创建/维护（多层级/属性/负责人/时间范围；到期自动标识 expired） | project_code,project_name,parent_id,owner_id,start_date,end_date,attrs_json | {id} | A,H | org_project |
| /hrorg/api/project_tree.dspy | GET | 项目组织树 | keyword?,status? | 树形节点数组 | L | — |
| /hrorg/api/project_post_save.dspy | POST | 项目任职维护（员工挂横向项目+横向职务） | project_id,employee_id,job_id,start_date,end_date | {id} | A,H | org_project_post |
| /hrorg/api/horizontal_job_options.dspy | GET | 横向职务选项（org_job.job_category=horizontal，供花名册/薪酬引用） | keyword | {rows:[{id,name}]} | L | — |
| /hrorg/api/workbench_transfer.dspy | GET | 工作台入转调离汇总（经理/管理员视图） | scope=team/all | {entry_n,regular_n,transfer_n,leave_n,rows} | M,H,A | — |

### 2.2 hr-roster（/hrroster，F03）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 | CRUD |
|---|---|---|---|---|---|---|
| /hrroster/api/roster_list.dspy | GET | 花名册列表（主表条件分页 + EAV 拼装 + 范围过滤 + 脱敏） | keyword?,org_id?,status?,type?,field_filters?(≤3 自定义字段等值),page,size | {rows,total} | A,H(范围),M(团队) | roster_employee |
| /hrroster/api/roster_employee_create.dspy | POST | 新增员工（工号规则自动生成、写时间轴；含证件字段组手工录入 D1：id_type/id_number/id_valid_from/id_valid_to/id_authority，id_source='manual'） | 主档字段+证件字段组+自定义字段kv | {id,employee_no} | A,H | roster_employee |
| /hrroster/api/roster_employee_update.dspy | POST | 更新员工（含自助修改路径：editable_self 范围校验+need_audit 走审批；二期读卡器回填证件同字段） | id,字段kv | {} 或 {need_audit:true,instance_id} | A,H,E(本人受限) | roster_employee |
| /hrroster/api/employee_detail.dspy | GET | 员工档案详情（主档+分组字段+兼岗+合同摘要+项目任职，按角色脱敏/字段可见） | id | {main,groups:[{group_name,fields:[...]}],concurrent,contracts,projects} | L(按范围) | — |
| /hrroster/api/roster_field_def_save.dspy | POST | 字段定义维护（类型/必填/敏感/自助/审核/适用类型/排序，即时生效于列表/详情/导入导出） | fields[] | {} | A,H | roster_field_def |
| /hrroster/api/roster_field_group_save.dspy | POST | 分组维护（含拖拽排序持久化） | groups[] | {} | A,H | roster_field_group |
| /hrroster/api/roster_type_rule_save.dspy | POST | 员工类型字段规则（正式/临时等必填差异） | employee_type,field_rules_json | {} | A,H | roster_type_rule |
| /hrroster/api/empno_rule_save.dspy | POST | 工号规则维护（多规则，如子公司独立前缀） | rules[]:{rule_name,prefix,match_field,match_value,seq_length} | {} | A,H | roster_empno_rule |
| /hrroster/api/check_employee_no.dspy | GET | 工号查重 | employee_no,exclude_id? | {exists} | A,H | — |
| /hrroster/api/roster_import.dspy | POST | 自定义导入（批量新增/批量修改，≥500 行正确；模板按当前字段定义+类型规则生成） | file,mode=new/update | {task_id} | A,H | — |
| /hrroster/api/roster_import_template.dspy | GET | 导入模板下载（按字段定义+类型规则） | employee_type? | 文件 | A,H | — |
| /hrroster/api/roster_export.dspy | GET | 自定义导出（指定数据日期/字段/顺序，拖拽排序；强制数据范围） | as_of?,field_ids[],filters | {task_id}→文件 | A,H | — |
| /hrroster/api/timeline.dspy | GET | 员工时间轴（全周期记录，可编辑） | employee_id,event_type? | {rows:[{event_type,event_date,title,content_json}]} | L(按范围) | — |
| /hrroster/api/timeline_add.dspy | POST | 时间轴记录编辑 | employee_id,event_type,event_date,title,content | {} | A,H | — |
| /hrroster/api/file_preview_url.dspy | GET | 附件在线预览 URL（files/ 受控访问） | file_id | {url} | L(按范围) | — |
| /hrroster/api/roster_writeback.dspy | 内部 | 异动回写唯一入口（仅 hr-org/hr-flow 服务内调用，注册于 ServerEnv，不注册 HTTP 路径；回写后触发 headcount_check 与 timeline） | biz_type,biz_id,instance_id | {} | 服务内 | — |

### 2.3 hr-flow（/hrflow，F10）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 | CRUD |
|---|---|---|---|---|---|---|
| /hrflow/api/form_def_save.dspy | POST | 表单定义维护（引用花名册字段；含考勤类桩位表单 attendance_*） | form_code,form_name,biz_type,fields_json | {id} | A,H | flow_form_def |
| /hrflow/api/flow_def_save.dspy | POST | 流程定义（匹配条件、版本；预置人事四类模板初始化） | flow_code,form_id,biz_type,match_cond_json | {id} | A,H | flow_def |
| /hrflow/api/flow_node_save.dspy | POST | 节点维护（审批人/通过规则 any/all/字段权限/抄送） | flow_id,nodes[] | {} | A,H | flow_node_def |
| /hrflow/api/flow_role_save.dspy | POST | 审批角色（流程范围/操作权限/数据查看三维配置） | role_name,flow_scope_json,op_perm_json,data_scope_json | {id} | A | flow_role |
| /hrflow/api/flow_match.dspy | GET | 按员工类型/部门匹配流程 | biz_type,employee_type,org_id | {flow_id,flow_name} 或 FLOW_NOT_MATCH | 服务内/HR | — |
| /hrflow/api/flow_start.dspy | POST | 发起审批（通用：业务模块统一入口） | biz_type,biz_id,form_data_json | {instance_id,inst_no} | L | — |
| /hrflow/api/task_todo.dspy | GET | 我的待办 | page,size | {rows,total} | L | — |
| /hrflow/api/task_done.dspy | GET | 已办 | page,size | {rows,total} | L | — |
| /hrflow/api/inst_mine.dspy | GET | 我发起的 | status?,page,size | {rows,total} | L | — |
| /hrflow/api/inst_received.dspy | GET | 我收到的（抄送/知会） | page,size | {rows,total} | L | — |
| /hrflow/api/inst_detail.dspy | GET | 审批单详情（表单数据+流转记录+字段权限） | instance_id | {form_data,nodes:[{op,operator,time,comment}],status} | L(参与者) | — |
| /hrflow/api/task_approve.dspy | POST | 同意（末节点通过触发完成回调回写业务） | task_id,comment? | {} | L(任务归属) | — |
| /hrflow/api/task_reject.dspy | POST | 驳回 | task_id,comment | {} | L(任务归属) | — |
| /hrflow/api/task_forward.dspy | POST | 转交 | task_id,to_user_id | {} | L(任务归属) | — |
| /hrflow/api/inst_withdraw.dspy | POST | 撤回（发起人，仅首节点未处理） | instance_id | {} | L(发起人) | — |
| /hrflow/api/inst_query.dspy | GET | 审批数据查询（表单/状态/发起人/编号/时间多条件） | form_name?,status?,initiator?,inst_no?,date_range | {rows,total} | A,H | — |
| /hrflow/api/inst_export.dspy | GET | 审批数据导出 | 同上 | 文件 | A,H | — |
| /hrflow/api/inst_print.dspy | GET | 审批单打印视图（A4 版式） | instance_id | 打印 HTML | L(参与者) | — |

### 2.4 hr-contract（/hrcontract，F09）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 | CRUD |
|---|---|---|---|---|---|---|
| /hrcontract/api/contract_list.dspy | GET | 合同台账列表（范围过滤） | employee_id?,status?,type_id?,end_before? | {rows,total} | A,H | contract_info |
| /hrcontract/api/contract_create.dspy | POST | 新增合同（关联员工+合同公司+模板） | employee_id,type_id,company_id,template_id?,start_date,end_date,file | {id} | A,H | contract_info |
| /hrcontract/api/contract_import.dspy | POST | 批量导入 | file | {task_id} | A,H | — |
| /hrcontract/api/contract_apply.dspy | POST | 合同审批（新签/续签/变更/终止四类） | contract_id?,biz_type=contract_sign/renew/change/stop,form_data_json | {instance_id} | A,H | — |
| /hrcontract/api/contract_text_gen.dspy | GET | 按模板生成合同文本（占位符填充，docx/pdf 供打印下载；电子签二期 D4） | contract_id,template_id?,fmt=docx/pdf | 文件 | A,H | — |
| /hrcontract/api/contract_remind_rule_save.dspy | POST | 到期提醒规则（提前天数/提醒对象本人或管理人员） | rule_name,days_before,target_role,content_template | {id} | A,H | contract_remind_rule |
| /hrcontract/api/contract_template_save.dspy | POST | 模板维护 | template_name,type_id,file,field_marks_json | {id} | A,H | contract_template |
| /hrcontract/api/contract_expire_soon.dspy | GET | 即将到期列表（工作台/提醒；误差 ≤1 天） | days | {rows} | A,H | — |
| /hrcontract/api/esign_stub.dspy | POST | 电子签预留桩（D4：返回未启用，验证路由可达） | contract_id | {status:'error',data:{code:'NOT_ENABLED'}} | A,H | — |

### 2.5 hr-report（/hrreport，F13，全部只读）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 |
|---|---|---|---|---|---|
| /hrreport/api/roster_analysis.dspy | GET | 花名册多维分布（维度可自定义，含自定义字段） | dim=type/status/age/edu/location/gender/custom_field_id | {rows:[{dim_value,count}],total} | A,H,M(范围) |
| /hrreport/api/entry_analysis.dspy | GET | 入职数量与趋势（部门/地区/岗位） | dim=org/location/position,period=month/quarter | {trend:[],rows:[]} | A,H,M |
| /hrreport/api/regular_analysis.dspy | GET | 转正分析（趋势+近期待转正） | period? | {trend:[],upcoming:[]} | A,H,M |
| /hrreport/api/transfer_analysis.dspy | GET | 近期调动分析 | date_range? | {rows:[{type,count}]} | A,H,M |
| /hrreport/api/leave_analysis.dspy | GET | 离职分析（待离职数/原因/离职率/同环比） | period? | {pending_n,reasons:[],rate:{cur,yoy,mom}} | A,H,M |
| /hrreport/api/report_export.dspy | GET | 报表数据导出（与页面数据一致，强制数据范围） | report_code,同各分析参数 | 文件 | A,H,M |
| /hrreport/api/team_stats.dspy | GET | 团队人事统计（经理工作台卡片） | org_id? | {headcount,entry_n,leave_n,...} | M,H,A |

### 2.6 hr-system（/hrsystem，F11/F12/F14/F15）

| 端点 | 方法 | 功能 | 关键请求参数 | 响应 data | 角色 | CRUD |
|---|---|---|---|---|---|---|
| /hrsystem/api/role_save.dspy | POST | 管理角色创建与权限设置（rbac 角色+路径） | role_name,paths[] | {id} | A | sys_role(rbac) |
| /hrsystem/api/data_scope_save.dspy | POST | 人员范围（组织维度含子树/花名册字段维度，可叠加） | admin_user_id,scope_type,org_ids[]/field_ids[] | {} | A | sys_data_scope |
| /hrsystem/api/admin_save.dspy | POST | 管理员管理（创建管理员并授权角色与数据范围） | user_id,roles[],scope | {} | A | — |
| /hrsystem/api/get_data_scope.dspy | 内部 | 数据范围查询（ServerEnv 注册，供各模块查询叠加） | user_id | {scope_type,org_ids,field_ids} | 服务内 | — |
| /hrsystem/api/audit_log_list.dspy | GET | 操作日志查询（时间/类型/模块） | module?,operation?,date_range,target? | {rows,total} | A | sys_audit_log |
| /hrsystem/api/audit_log_detail.dspy | GET | 日志详情（前后值对比） | id | {before_json,after_json,operator,ip,time} | A | — |
| /hrsystem/api/workbench_employee.dspy | GET | 员工工作台聚合（档案摘要/工资条入口桩/绩效桩/待办数/可发起流程） | — | {profile,todo_n,flows:[...],salary_stub:null,perf_stub:null} | E | — |
| /hrsystem/api/workbench_manager.dspy | GET | 经理工作台聚合（团队统计/待审批/关怀提醒；考勤/团队绩效桩位） | — | {stats,todos:[],care:[...],attendance_stub:null} | M | — |
| /hrsystem/api/workbench_admin.dspy | GET | 管理员工作台聚合（人事统计/合同到期/提醒） | — | {stats,contracts:[],care:[...]} | A,H | — |
| /hrsystem/api/remind_rule_save.dspy | POST | 通用提醒规则（≥6 场景自定义内容与时间） | scene_code,rule_name,days_before,content_template,target_role | {id} | A,H | sys_remind_rule |
| /hrsystem/api/care_config_save.dspy | POST | 生日/周年关怀文案配置 | care_type,template,enable | {} | A,H | sys_care_config |
| /hrsystem/api/announcement_save.dspy | POST | 公告发布（在线查询预览） | title,content,publish_scope_json | {id} | A,H | sys_announcement |
| /hrsystem/api/policy_save.dspy | POST | 政策发布（适用范围/查阅范围/下载权限） | title,file,view_scope_json,downloadable | {id} | A,H | sys_policy |
| /hrsystem/api/policy_download.dspy | GET | 政策文件下载（校验 downloadable 与查阅范围） | id | 文件 或 NO_PERMISSION | L(按范围) | — |
| /hrsystem/api/message_list.dspy | GET | 我的站内消息 | is_read?,msg_type? | {rows,total} | L | — |
| /hrsystem/api/message_read.dspy | POST | 标记已读 | ids[] | {} | L | — |
| /hrsystem/api/message_unread_count.dspy | GET | 未读数（全局铃铛） | — | {n} | L | — |
| /hrsystem/api/remind_scan.dspy | 内部 | 提醒扫描（cron 每日+启动补扫：转正/合同/生日/周年/退休/健康证等到期推送；离职日期到达触发 leave_effect） | — | {sent_n} | 服务内 | — |
| /openapi/v1/ping.dspy | GET | API 开放接口桩（一期仅验证路由/鉴权框架，返回 NOT_ENABLED；规范见 architecture.md §9） | — | {status:'error',data:{code:'NOT_ENABLED'}} | 匿名(桩) | — |

### 2.7 appbase/rbac 沿用（不自研）

登录/登出、用户管理、字典 appcodes 维护、rbac 角色路径绑定由 appbase/rbac 包自带页面与端点承载（`/appbase/*`、`/rbac/*`），批次1仅在各模块 init/data.json 中初始化字典、角色与四类流程模板。

## 3. 典型调用链示例

### 3.1 转正审批（F05）
1. `POST /hrorg/api/regular_apply.dspy` {employee_id, regular_date} → hr-org 校验员工状态（probation）；
2. 内部调用 `flow_match(biz_type=regular, employee_type, org_id)` → `POST /hrflow/api/flow_start.dspy` {biz_type:'regular', biz_id:regularization_id, form_data_json} → 生成 flow_instance + 首节点 flow_task，发站内消息给审批人；
3. 审批人 `POST /hrflow/api/task_approve.dspy` → 全部节点通过 → flow_instance.inst_status=approved；
4. hr-flow 完成回调 → hr-org `regular_confirm` → hr-roster `roster_writeback`：roster_employee.employee_status=regular、regular_date 更新，写 roster_timeline → `headcount_check`（编制联动提醒）；
5. 各步均写 sys_audit_log；转正提醒由 `remind_scan` 按 probation_end_date 提前（默认 7 天可配）推送管理员与直属主管。

### 3.2 花名册列表（F03）
`GET /hrroster/api/roster_list.dspy?keyword=张&org_id=..&status=regular&page=1&size=50` → 权限校验（数据范围 org_ids/field_ids）→ 主表条件分页 → 值表批量拼装显示字段 → 敏感字段按角色脱敏 → `{"status":"success","data":{"rows":[...],"total":N}}`。

### 3.3 入职黑名单拦截（F04-6）
`POST /hrorg/api/entry_approval.dspy` → id_number 哈希匹配 org_blacklist → 命中返回 `{"status":"error","data":{"code":"BLACKLIST_HIT"}}`，前端待入职列表高亮标注；手动入职返回 blocked 名单。

### 3.4 入职登记表邀请（扫码入职降级）
1. HR 在待入职列表选中记录 → `POST entry_invite_register.dspy` → 生成 register_token/register_url + 二维码图片（files/），站内消息发送邀请；
2. 候选人（内网）扫码访问 `entry_register_page.dspy?token=..` → 按表单定义渲染登记表（字段可配置、必填校验）；
3. 提交 `entry_register_submit.dspy` → register_status=filled，数据写入 org_entry/扩展字段 → 进入入职审批流或直接待入职。

### 3.5 离职全流程（F07）
`leave_apply/leave_manual` → 待离职名单（status=pending_leave）→ `leave_handover_save`（含 dingtalk_resource 占位项手工登记）→ remind_scan 到期触发 `leave_effect`（状态 left、写时间轴）→ `leave_certificate` 生成证明 → 可选 `blacklist_add`。

### 3.6 编制联动（F16）
入职/调动/离职回写成功 → `headcount_check(employee_id, event)` → 按 scope_json 匹配编制细分项重算 used_count → 写 headcount_snapshot（当日）→ 超编时向 hr/admin 发 sys_message（提醒不硬拦截）→ `headcount_status`/`headcount_history` 展示。

## 4. 与 v1 接口的替代关系（衔接 staff-mgr）

| v1 端点（JWT RESTful） | 一期替代 |
|---|---|
| POST /api/v1/staff | /hrorg/api/entry_manual.dspy 或 /hrroster/api/roster_employee_create.dspy |
| GET /api/v1/staff | /hrroster/api/roster_list.dspy（+ CRUD 列表页） |
| GET /api/v1/staff/{id} | /hrroster/api/employee_detail.dspy |
| PUT /api/v1/staff/{id} | /hrroster/api/roster_employee_update.dspy |
| DELETE /api/v1/staff/{id}、batch-delete | 离职流程 /hrorg/api/leave_manual.dspy（一期不做删除语义） |
| GET /api/v1/staff/{id}/change-logs | /hrroster/api/timeline.dspy |
| GET /api/v1/staff/audit-logs | /hrsystem/api/audit_log_list.dspy |
| GET /api/v1/staff/check/employee-no | /hrroster/api/check_employee_no.dspy |
| GET /api/v1/staff/departments | /hrorg/api/org_tree.dspy |

## 5. 降级项桩端点汇总（二期恢复入口）

| 降级项 | 一期端点/字段 | 二期恢复方式 |
|---|---|---|
| D1 身份证读卡 | roster_employee/org_entry 证件字段组手工录入（id_source=manual） | 读卡硬件接入后经 roster_employee_update 回填同字段，id_source=card_reader |
| D3 钉钉交接 | leave_handover_save（item_type=dingtalk_resource 手工登记） | 钉钉开放平台对接后该类型项自动拉取资源清单 |
| D4 电子签 | esign_stub.dspy（NOT_ENABLED）+ contract_text_gen.dspy 打印下载 | 对接电子签平台，esign_status 状态机流转 |
| D9 短信渠道 | sys_message.send_channel=site 兜底 | 短信网关接入扩展发送器，send_channel=sms 生效 |
| 扫码入职 | entry_register_page/entry_register_submit/entry_qrcode（内网 token） | 对外渠道启用后 register_url 切公网域名 |
| API 开放 | /openapi/v1/ping.dspy（NOT_ENABLED）+ sys_openapp 表 | 按 architecture.md §9 规范启用签名鉴权 |
| 考勤/绩效桩位 | flow_form_def biz_type=attendance_*；workbench_*_stub 字段 | 二期绩效/考勤系统接入后填充 |

## 6. 安全设计要点

1. 所有路径 load_path.py 注册；未注册即拒绝（含 .css/.js 静态资源）。
2. 敏感字段（身份证全角色脱敏前3后3；手机前3后4；职级/薪资类字段仅 admin/hr）由 roster_field_def.sensitive + 角色矩阵驱动，服务端脱敏后返回。
3. 全部 SQL 经 sqlor 绑定参数（`${var}$` 占位），禁止拼接用户输入。
4. 审批操作校验任务归属人；员工自助类接口校验本人（或白名单字段）；登记表接口以一次性 token 鉴权并校验过期时间。
5. 导入导出、登录、权限变更全量写 sys_audit_log（含 IP）。
6. 开放接口桩不注册业务处理；二期启用时按签名鉴权 + 数据出口授权管控。