## 0. 覆盖度矩阵（前置，开发者必须对照官方文档最新版填写）

> 见 `design.md` 表格；当前盘点截至 2026-04-18，约 17 项新增 + 8 项 v2 对齐。

## 1. 前置

- [ ] 1.1 对照钉钉官方通讯录文档**当前版本**，逐行复核 `design.md` 覆盖度矩阵，补齐 apiNote 链接
- [ ] 1.2 确认 `DDConf` 是否已含完整的 `corpId` / `appKey` / `appSecret`，按需扩展

## 2. 用户管理（User）

- [ ] 2.1 `createUser_v2`（完整 body_ext javadoc）
- [ ] 2.2 `updateUser`
- [ ] 2.3 `getUser_v2`（取代 `getUserInfoById` 作为新规范入口）
- [ ] 2.4 `getUserByMobile_v2`
- [ ] 2.5 `listUsersSimple`
- [ ] 2.6 `listDeptUserDetail_v2`（分页含详情，取代现有零散 `listSubDepartmentDetail`）
- [ ] 2.7 `listInactiveUsers`
- [ ] 2.8 `getUserByUnionId`
- [ ] 2.9 `listAdmins`
- [ ] 2.10 `listDimissionEmployees_v2`

## 3. 部门管理（Department）

- [ ] 3.1 `createDepartment_v2`
- [ ] 3.2 `updateDepartment`
- [ ] 3.3 `deleteDepartment`
- [ ] 3.4 `getDepartment_v2`
- [ ] 3.5 `listSubDepartments_v2`
- [ ] 3.6 `listParentByDept`

## 4. 角色管理（Role）

- [ ] 4.1 `addRole`
- [ ] 4.2 `updateRole`
- [ ] 4.3 `deleteRole`（若官方有）
- [ ] 4.4 `listRoles`
- [ ] 4.5 `getRole`
- [ ] 4.6 `listRoleEmployees`
- [ ] 4.7 `addRolesForEmps`
- [ ] 4.8 `removeRolesForEmps`

## 5. 员工字段管理（EmployeeField）

- [ ] 5.1 `upsertHideField`
- [ ] 5.2 `removeHideField`
- [ ] 5.3 `listHideFields`

## 6. 实现

- [ ] 6.1 `DDClient_Contacts.java` 接口追加 ~25 个方法声明（按子模块分段注释清晰）
- [ ] 6.2 `impl/DDImplClient_Contacts.java` 实现全部新方法
- [ ] 6.3 所有实现走 `UtilHttp`（禁 SDK）
- [ ] 6.4 每个方法的 javadoc 严格遵守 §3.4.2 模板（必填注释 + body_ext 枚举 + apiNote）

## 7. 文档

- [ ] 7.1 在 mjava-baseline.md §3.4 表格中追加"dingtalk-contacts-v2 已对齐"状态
- [ ] 7.2 PR 描述含官方文档对照矩阵截图

## 8. 验证

- [ ] 8.1 单元测试：每个方法的参数透传（mock UtilHttp 验证 body 完整）
- [ ] 8.2 集成测试：选 5 个关键 endpoint（createUser_v2 / updateUser / listAdmins / addRole / upsertHideField）跑真实钉钉
- [ ] 8.3 `openspec validate extend-dingtalk-contacts-api --strict` 通过
- [ ] 8.4 审视 mjava-guangming / mjava-shunfeng / mjava-mcli 是否需要迁移到新 v2 方法（本次**不强制迁**，只评估）

## 9. 交付

- [ ] 9.1 PR 按子模块拆分（User / Dept / Role / Field 四个）
- [ ] 9.2 走 `/opsx:archive` 归档