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. 开放接口桩不注册业务处理；二期启用时按签名鉴权 + 数据出口授权管控。