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

状态（2026-04-18 立项）：规则定义阶段，不做代码改造 优先级：高（Phase B.1 第二个专项） 改造等宜搭专项规则走通后启动

Why

DDClient_Contacts 当前有 ~18 个方法，对齐钉钉通讯录的部分 endpoint，但：

• 参数不完整：createUser(access_token, name, mobile, dept_id_list, body_ext) 只显式暴露了 3 个必填参数，其他如 userid / hired_date / job_number / email / title 全塞在 body_ext 里，javadoc 未枚举，调用方要查官方文档才知道能传什么。
• 缺失 endpoint：钉钉通讯录目前官方提供 30+ 个 endpoint，现有实现只覆盖 18 个，缺 updateUser / listsimpleUser / getUserByUnionId / getAdminList / listInactive / createDepartment_v2 / updateDepartment / listParentByDept / 角色管理（addRole/delRole/listRoles/...）/ 员工字段隐藏设置 等。
• 命名不一致：getUserInfoById vs getDepartmentInfo 动词选择混乱，新方法应统一 get{Resource} / list{Resource} / create{Resource} 三模式。

What Changes

保留 DDClient_Contacts 现有方法（已上线客户依赖），按 mjava-baseline §3.4.4 新增对齐方法：

• 补齐缺失 endpoint（参照钉钉官方通讯录 API 列表）
• 对已有方法做签名对齐新版本（方法名加后缀 _v2 或重载），body_ext 字段在 javadoc 完整枚举
• 按"用户管理 / 部门管理 / 角色管理 / 员工字段管理"四个子模块在同一接口内分段组织
• 后续专项统一把旧方法标 @Deprecated（不在本 change 做）

涉及范围仅钉钉通讯录；考勤 / OA 审批 / 消息 / 群聊等其他 DDClient_{Domain} 模块不在此次提案。

Capabilities

New Capabilities

• dingtalk-contacts-v2：对齐后的通讯录原子接口集（含用户 / 部门 / 角色 / 员工字段）

Modified Capabilities

• dingtalk-contacts-legacy（现有）：标记为后续弃用，保留原有接口

Impact

• 修改文件：DDClient_Contacts.java 追加方法；impl/DDImplClient_Contacts.java 追加实现
• 不改动：旧方法签名
• API 消费者：旧方法继续可用；新方法可按需切换
• 三个生产客户：零影响

Non-Goals

• ❌ 不删或改旧方法
• ❌ 不做考勤 / OA 审批 / 消息 / 群聊等模块（每模块独立 change）
• ❌ 不做企业外部联系人、专属账号的完整覆盖（现有 DDClient_Dedicated 已部分覆盖，按需再评估）
• ❌ 不做新旧 API 自动路由（由调用方显式选择 v2 方法）