mjava-ai/openspec/changes/extend-dingtalk-contacts-api/tasks.md

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

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

1. 前置

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

2. 用户管理（User）

• 2.1 createUser_v2（完整 body_ext javadoc 20+ 字段）
• 2.2 updateUser
• 2.3 getUser_v2
• 2.4 getUserByMobile_v2
• 2.5 listUsersSimple
• 2.6 listDeptUserDetail_v2
• 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 接口追加 27 个方法声明（User/Dept/Role/Field 四段分隔清晰）
• 6.2 impl/DDImplClient_Contacts.java 实现全部 27 个方法，复用 qs() / merge() 模板
• 6.3 全部走 DDR.doPost(oapi, null, qs(token), body) 旧 OAPI 模式（与现有方法一致，禁 SDK）
• 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 归档