mjava-ai/openspec/changes/archive/2026-04-26-add-integration-user-api/proposal.md

状态（2026-04-26 立项）：规则定义阶段 优先级：中（Phase B.1 第三个 vendor 专项） 依赖：基座 UtilHttp / UtilToken / McR 已就绪

Why

后续多个客户项目要调用「集成平台」（IAM / 身份治理产品）的用户管理接口，做"钉钉用户 → 集成平台用户"的同步与对接。集成平台官方接口为 RESTful + OAuth2 client_credentials 模式，与 mjava 现有 vendor（dingtalk/aliwork/...）模式不同，需要：

• 独立的 service/integration/ 包承载；类前缀 INTPClient_* / INTPConf / INTPR（与 dingtalk DD* / aliwork YD* 全大写惯例一致）
• 独立的 IntpConf（baseUrl / clientId / clientSecret），配置段 integration.* 与 dingtalk/aliwork 平级
• token 走 UtilToken 缓存，按"过期前刷"策略（OAuth2 返回 expires_in）

本 change 只覆盖用户域写操作 + 鉴权：getAccessToken / createUser / updateUser / deleteUser。其它能力（org、角色、查询、Webhook、连接器事件）按需另立 change。

What Changes

新增 vendor 包：

• server/integration/INTPConf.java：配置类（baseUrl / clientId / clientSecret）
• server/integration/INTPR.java：响应包装（继承 VenR），字段 result/error/error_description/data + assertSuccess
• service/integration/INTPClient_User.java（接口）：4 个对外原子方法
  • createUser(access_token, username, password, body_ext)
  • updateUser(access_token, username, body_ext)
  • deleteUsers(access_token, usernames)
  • queryUsers(access_token, query) —— 顺手对齐 GET 接口，便于联调校验
• service/integration/impl/INTPImplClient_User.java：基于 INTPR.doPost/doGet/doPatch + UtilToken 缓存 access_token 的实现（getAccessToken() 为 private 方法，不进 Client 接口）
• 三个客户子模块的 application-{dev,prod}.yml.example 加 integration: 段占位

不涉及：

• mjava-pro 多租户化（按用户决策"基座单租户"）
• Service 层业务封装（按用户决策"不需要"）
• 其它 18 个非用户接口（org / 角色 / Webhook / 连接器）

Capabilities

New Capabilities

• integration-user-api：集成平台用户域的鉴权与 CRUD 原子接口集