## 目标结构

`DDClient_Contacts` 内部按子模块分段，同一文件内保持阅读连贯性（不拆成 `_Contacts_User` / `_Contacts_Dept`）：

```java
public interface DDClient_Contacts {
    // ========== 用户管理 User ==========
    Map createUser(...);          // 旧, 保留
    Map createUser_v2(...);       // 新对齐
    Map updateUser(...);          // 新增（旧无此方法）
    ...

    // ========== 部门管理 Department ==========
    Map createDepartment(...);
    Map createDepartment_v2(...);
    ...

    // ========== 角色管理 Role ==========
    Map addRole(...);             // 新增
    Map listRoles(...);
    ...

    // ========== 员工字段管理 EmployeeField ==========
    Map hideEmployeeField(...);
    ...
}
```

## v2 命名约定

同一个 endpoint 若**旧方法签名不规范**（参数缺漏、命名不统一），新方法用 `_v2` 后缀：

- `createUser` (旧) 不删
- `createUser_v2` (新) 按 §3.4.2 规范，所有 body_ext 字段 javadoc 列全

若**旧方法不存在**（真正新增），直接用正常名字 `updateUser`，无需 `_v2`。

## 覆盖度矩阵（任务 0 填写模板）

| 官方 endpoint | 当前方法 | 对齐行动 |
|--------------|---------|---------|
| POST /topapi/v2/user/create | `createUser` | 新增 `createUser_v2` |
| POST /topapi/v2/user/update | ❌ 缺 | 新增 `updateUser` |
| POST /topapi/v2/user/delete | `deleteUser` | 不动（签名已规范） |
| POST /topapi/v2/user/get | `getUserInfoById` | 新增 `getUser_v2`（命名统一） |
| POST /topapi/v2/user/getbymobile | `getUserInfoByMobile` | 新增 `getUserByMobile_v2` |
| POST /topapi/user/listsimple | ❌ 缺 | 新增 `listUsersSimple` |
| POST /topapi/v2/user/list | 部分（`listSubDepartmentDetail`？）| 新增 `listDeptUserDetail_v2` |
| GET /topapi/user/listid | `listDepartmentUserId` | 不动 |
| POST /topapi/inactive/user/v2/get | ❌ 缺 | 新增 `listInactiveUsers` |
| POST /topapi/user/getbyunionid | ❌ 缺 | 新增 `getUserByUnionId` |
| POST /topapi/user/get_admin | ❌ 缺 | 新增 `listAdmins` |
| POST /topapi/smartwork/hrm/employee/listdimission | `getLeaveEmployeeRecords` | 新增 `listDimissionEmployees_v2` |
| POST /topapi/v2/department/create | `createDepartment` | 新增 `createDepartment_v2` |
| POST /topapi/v2/department/update | ❌ 缺 | 新增 `updateDepartment` |
| POST /topapi/v2/department/delete | ❌ 缺 | 新增 `deleteDepartment` |
| POST /topapi/v2/department/get | `getDepartmentInfo` | 新增 `getDepartment_v2` |
| POST /topapi/v2/department/listsubid | `listSubDepartmentId` | 不动 |
| POST /topapi/v2/department/listparentbyuser | `listParentByUser` | 不动 |
| POST /topapi/v2/department/listparentbydept | ❌ 缺 | 新增 `listParentByDept` |
| POST /topapi/v2/department/listsub | `listSubDepartmentDetail` | 新增 `listSubDepartments_v2` |
| POST /topapi/v2/role/add_role | ❌ 缺 | 新增 `addRole` |
| POST /topapi/v2/role/addrolesforemps | ❌ 缺 | 新增 `addRolesForEmps` |
| POST /topapi/v2/role/removerolesforemps | ❌ 缺 | 新增 `removeRolesForEmps` |
| POST /topapi/v2/role/update_role | ❌ 缺 | 新增 `updateRole` |
| POST /topapi/v2/role/list | ❌ 缺 | 新增 `listRoles` |
| POST /topapi/v2/role/getrole | ❌ 缺 | 新增 `getRole` |
| POST /topapi/v2/role/simplelist | ❌ 缺 | 新增 `listRoleEmployees` |
| POST /topapi/hide_field/add_or_update | ❌ 缺 | 新增 `upsertHideField` |
| POST /topapi/hide_field/remove | ❌ 缺 | 新增 `removeHideField` |
| POST /topapi/hide_field/query | ❌ 缺 | 新增 `listHideFields` |

总计：**~30 个方法**，其中 **~17 个新增**，**~8 个 v2 对齐**，**~5 个保持不动**。

## 方法签名模板

```java
/**
 * 创建用户（v2 对齐版）
 * @apiNote https://open.dingtalk.com/document/orgapp/user-information-creation
 *
 * @param access_token  钉钉 accessToken（非企业内部应用按文档约定）
 * @param name          员工姓名（必填）
 * @param mobile        手机号（必填，同一企业内不重复）
 * @param dept_id_list  所属部门 ID 列表（必填，至少 1 个）
 * @param body_ext 可选参数:
 *   - userid (String): 自定义 userid，不传则自动生成
 *   - hired_date (Long): 入职时间毫秒时间戳
 *   - job_number (String): 工号
 *   - title (String): 职位
 *   - work_place (String): 办公地点
 *   - remark (String): 备注
 *   - email (String): 邮箱（应用需有通讯录读写权限）
 *   - org_email (String): 企业邮箱
 *   - org_email_type (String): profession / premium
 *   - extension (String): 扩展属性 JSON 字符串
 *   - senior_mode (Boolean): 是否高管模式
 *   - hide_mobile (Boolean): 是否隐藏手机号
 *   - telephone (String): 分机号
 *   - dept_order_list (List<Map>): 部门内排序
 *   - dept_title_list (List<Map>): 部门内职位
 *   - login_email (String): 企业账号登录邮箱
 *   - exclusive_account (Boolean): 是否专属账号
 *   - exclusive_account_type (String): sso/custom
 *   - exclusive_mobile (String): 专属账号手机号
 *   - ...（完整清单见官方文档，最后同步日期 2026-04-18）
 * @return Map 包含 userid、isLeaderInDepts 等
 */
Map createUser_v2(String access_token, String name, String mobile,
                  List<String> dept_id_list, Map<String, Object> body_ext);
```

## 风险与缓解

| 风险 | 缓解 |
|------|------|
| body_ext javadoc 随官方文档变动脱节 | javadoc 末尾强制写"最后同步日期"，下次对齐时更新 |
| 新旧方法并存造成调用方选择困惑 | README 加明确指引"新项目用 _v2 / 无后缀版本；历史项目原地不动" |
| 新增方法数量大（~17 个）导致 PR 过重 | 按用户 / 部门 / 角色 / 员工字段四个子模块拆 4 个 PR |