# 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、时间。