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

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

## 1. 前置

- [ ] 1.1 ⚠️ **阻塞**：官方文档路径已基于训练知识 + 现有实现推断，实施冒烟前需逐条对照官方文档复核，尤其 Role 模块的 `add_role` / `deleterole` 等路径大小写与下划线格式
- [x] 1.2 `DDConf` 现有 corpId/appKey/appSecret 字段足够；本次未扩展

## 2. 用户管理（User）

- [x] 2.1 `createUser_v2`（完整 body_ext javadoc 20+ 字段）
- [x] 2.2 `updateUser`
- [x] 2.3 `getUser_v2`
- [x] 2.4 `getUserByMobile_v2`
- [x] 2.5 `listUsersSimple`
- [x] 2.6 `listDeptUserDetail_v2`
- [x] 2.7 `listInactiveUsers`
- [x] 2.8 `getUserByUnionId`
- [x] 2.9 `listAdmins`
- [x] 2.10 `listDimissionEmployees_v2`

## 3. 部门管理（Department）

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

## 4. 角色管理（Role）

- [x] 4.1 `addRole`
- [x] 4.2 `updateRole`
- [x] 4.3 `deleteRole`
- [x] 4.4 `listRoles`
- [x] 4.5 `getRole`
- [x] 4.6 `listRoleEmployees`
- [x] 4.7 `addRolesForEmps`
- [x] 4.8 `removeRolesForEmps`

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

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

## 6. 实现

- [x] 6.1 `DDClient_Contacts.java` 接口追加 27 个方法声明（User/Dept/Role/Field 四段分隔清晰）
- [x] 6.2 `impl/DDImplClient_Contacts.java` 实现全部 27 个方法，复用 `qs()` / `merge()` 模板
- [x] 6.3 全部走 `DDR.doPost(oapi, null, qs(token), body)` 旧 OAPI 模式（与现有方法一致，禁 SDK）
- [x] 6.4 每个方法 javadoc 含 `@apiNote` 路径 + `body_ext` 枚举（User 模块 20+ 字段详细）

## 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` 归档