proposal.md 2.6 KB
状态（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/...）/ 员工字段隐藏设置 等。 - 命名不一致：
getUserInfoByIdvsgetDepartmentInfo动词选择混乱，新方法应统一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 方法）