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

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