## ADDED Requirements

### Requirement: 用户管理完整覆盖

`DDClient_Contacts` SHALL 提供对钉钉官方通讯录用户管理 endpoint 的完整对齐。所有方法 MUST 遵守 `mjava-baseline §3.4.2` 的签名规则。

#### Scenario: 创建用户（完整字段）

- **WHEN** 调用 `createUser_v2(access_token, name, mobile, dept_id_list, body_ext)`
- **THEN** `body_ext` 必须支持官方文档列出的所有可选字段（userid / hired_date / job_number / title / email / senior_mode / extension / ...）
- **AND** javadoc 必须枚举这些字段并注明类型

#### Scenario: 更新用户

- **WHEN** 调用 `updateUser(access_token, userid, body_ext)`
- **THEN** `userid` 必填，其他字段全部通过 `body_ext` 传入
- **AND** 不传的字段保持钉钉侧原值不变

#### Scenario: 按 unionId 查询

- **WHEN** 调用 `getUserByUnionId(access_token, union_id)`
- **THEN** 返回 userid（二次调用 `getUser_v2` 获取详情）

#### Scenario: 查询管理员

- **WHEN** 调用 `listAdmins(access_token)`
- **THEN** 返回管理员 userid 列表，含主管理员与子管理员区分字段

#### Scenario: 查询未激活员工

- **WHEN** 调用 `listInactiveUsers(access_token, is_active, offset, size, body_ext)`
- **THEN** 支持按激活状态过滤

### Requirement: 部门管理完整覆盖

`DDClient_Contacts` SHALL 提供部门 CRUD 与层级查询的完整对齐。所有方法 MUST 对应钉钉官方部门管理 endpoint。

#### Scenario: 部门 CRUD

- **WHEN** 依次调用 `createDepartment_v2` / `updateDepartment` / `deleteDepartment` / `getDepartment_v2`
- **THEN** 每个方法参数完整对齐官方文档
- **AND** `body_ext` 支持 `hide_dept` / `dept_permits` / `user_permits` / `outer_dept` / `source_identifier` 等全部可选项

#### Scenario: 父部门链查询

- **WHEN** 调用 `listParentByDept(access_token, dept_id)`
- **THEN** 返回目标部门到根部门的父链

### Requirement: 角色管理

`DDClient_Contacts` SHALL 提供角色的增删改查与批量员工授权能力。

#### Scenario: 新增角色

- **WHEN** 调用 `addRole(access_token, roleName, groupId)`
- **THEN** 返回 roleId

#### Scenario: 批量分配角色

- **WHEN** 调用 `addRolesForEmps(access_token, roleIds, userIds)`
- **THEN** 一次调用同时为多员工授权多角色

#### Scenario: 查询角色成员

- **WHEN** 调用 `listRoleEmployees(access_token, role_id, size, offset)`
- **THEN** 分页返回角色下员工列表

### Requirement: 员工字段可见性

`DDClient_Contacts` SHALL 提供员工档案字段隐藏规则的管理能力。

#### Scenario: 隐藏字段设置

- **WHEN** 调用 `upsertHideField(access_token, name, field, userIds, deptIds)`
- **THEN** 对指定员工或部门隐藏指定员工档案字段

#### Scenario: 查询隐藏字段

- **WHEN** 调用 `listHideFields(access_token, size, offset)`
- **THEN** 返回企业当前生效的字段隐藏规则列表

### Requirement: 参数透传约束

本 capability 所有方法 MUST 满足官方可选参数完整透传与文档化要求，不得因 Java 侧建模省事而过滤字段。

#### Scenario: body_ext 不得过滤官方可选参数

- **WHEN** 调用方通过 `body_ext` 传入官方文档支持的任意可选字段
- **THEN** 实现必须原样透传到 HTTP 请求体，不得删除或改写
- **AND** 方法 javadoc 必须列出所有已知 body_ext key 并注明类型

#### Scenario: 方法必须有 apiNote

- **WHEN** 新增任一 Client 方法
- **THEN** javadoc 必须含 `@apiNote` 链到该 endpoint 的钉钉官方文档页