3.4 KiB
hr-roster 花名册字段体系 API 文档 (F03)
服务: hr_roster_field · 端口 9280 · ocai 模式 · 统一 JSON 返回 返回约定:
{"code": 0, "data": ...}成功；{"code": 非0, "message": "..."}失败
1. 字段分组 (roster_field_group)
GET /api/roster/field-groups
字段分组列表（按 sort_order 升序，仅未删除）。
POST /api/roster/field-groups
新增分组。入参: group_code(必填, 唯一), group_name(必填), group_desc, is_builtin, sort_order, is_enabled。
约束: group_code 须匹配 ^[a-zA-Z][a-zA-Z0-9_]{1,63}$，重复报错。
PUT /api/roster/field-groups/{id}
更新分组。支持修改 group_name/group_desc/sort_order/is_enabled。
DELETE /api/roster/field-groups/{id}
删除分组（软删除）。内置分组(is_builtin=1)不可删；分组下有字段时不可删。
2. 字段定义 (roster_field_def)
GET /api/roster/field-defs?group_id=
字段定义列表，支持 group_id 筛选。按 group_id, sort_order 升序。
POST /api/roster/field-defs
新增字段。入参: group_id(必填), field_code(必填唯一), field_name(必填),
field_type(必填, 枚举 text/number/date/datetime/select/multi_select/attachment/bool),
is_required/is_unique/is_sensitive, default_value, options_json, validation_rule,
placeholder/help_text, sort_order, is_enabled。
约束: select/multi_select 必须提供 options_json=[{"label":"","value":""}]。
PUT /api/roster/field-defs/{id}
更新字段定义。
DELETE /api/roster/field-defs/{id}
删除字段定义（软删除）。
POST /api/roster/field-defs/sort
拖拽排序。入参: {"items": [{"id":1,"sort_order":10}, ...]}，批量更新 sort_order。
POST /api/roster/field-defs/toggle
字段启停。入参: {"id":1, "is_enabled": true}。
3. 员工类型规则 (roster_type_rule)
GET /api/roster/type-rules
类型规则列表，required_field_codes 返回为数组。
POST /api/roster/type-rules
新增规则。入参: rule_code(唯一), rule_name, emp_type, required_field_codes(数组), sort_order, is_enabled。
PUT /api/roster/type-rules/{id}
更新规则。
DELETE /api/roster/type-rules/{id}
删除规则（软删除）。
4. 工号生成规则 (roster_empno_rule)
GET /api/roster/empno-rules
工号规则列表（按 sort_order 升序，匹配优先级）。
POST /api/roster/empno-rules
新增规则。入参: rule_code(唯一), rule_name, subsidiary_code, prefix, date_format, seq_length, start_seq, sort_order, is_enabled。
PUT /api/roster/empno-rules/{id}
更新规则。
DELETE /api/roster/empno-rules/{id}
删除规则（软删除）。
POST /api/roster/empno-rules/generate
生成工号。入参: {"rule_code": "empno_subs_a"} 或 {"subsidiary_code": "001"}（无参数取默认规则）。
逻辑: 前缀 + 日期段(按 date_format) + 流水号(seq_length 补零)；流水号原子递增；冲突报错。
5. options 端点（下拉联动）
GET /api/roster/options/{field_code}
返回指定选项型字段的 options 数组，供前端下拉联动。
约束: 字段须存在、启用，且类型为 select/multi_select。
审计
所有写操作（create/update/delete/sort/toggle/generate）均写入 roster_op_log，
记录操作类型、目标表、目标ID、变更前后快照、操作人、IP、时间。