86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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、时间。
|