mjava-ai/openspec/changes/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（baseUrl / clientId / clientSecret），配置段 integration.* 与 dingtalk/aliwork 平级
• token 走 UtilToken 缓存，按"过期前刷"策略（OAuth2 返回 expires_in）

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

What Changes

新增 service/integration/ 包，含：

• IntpConf：配置类（baseUrl / clientId / clientSecret）
• IntpClient（接口）：5 个原子方法
  • getAccessToken() → 内部调用，不暴露给业务方
  • createUser(accessToken, username, password, body_ext)
  • updateUser(accessToken, username, body_ext)
  • deleteUsers(accessToken, usernames)
  • queryUsers(accessToken, query) —— 顺手对齐已有 GET 接口，便于校验
• IntpClientImpl：基于 UtilHttp + UtilToken 的实现
• 三个客户子模块的 application-{dev,prod}.yml.example 加 integration: 段占位

不涉及：

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

Capabilities

New Capabilities

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