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

目标结构

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

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 个保持不动。

方法签名模板

/**
 * 创建用户（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