mjava-ai/openspec/changes/add-integration-user-api/tasks.md

0. 文档抓取（前置）

已完成：apifox 公开站抓 5 个接口字段详情，结果固化在 design.md 覆盖度矩阵 + 风险章节。 风险：apifox 文档可能与生产 API 漂移，实施冒烟时需联调验证。

1. 配置类与 yml 段

• 1.1 新建 mjava/src/main/java/com/malk/service/integration/IntpConf.java，@ConfigurationProperties("integration")，字段 baseUrl / clientId / clientSecret
• 1.2 mjava/src/main/resources/application-prod.yml.example 加 integration: 段
• 1.3 mjava-mcli / mjava-shunfeng / mjava-guangming 三个 application-prod.yml.example 加 integration: 段
• 1.4 三个客户已有 application-dev.yml（不是 .example）按需自行加段，本 change 不动真实 yml

2. Client 接口与实现

• 2.1 新建 service/integration/IntpClient.java（接口），方法：
  • McR createUser(String accessToken, String username, String password, Map<String,Object> body_ext)
  • McR updateUser(String accessToken, String username, Map<String,Object> body_ext)
  • McR deleteUsers(String accessToken, List<String> usernames)
  • McR queryUsers(String accessToken, Map<String,Object> query)
• 2.2 javadoc 完整枚举 body_ext 与 query 的可选字段（见 design.md / spec.md）
• 2.3 新建 service/integration/impl/IntpClientImpl.java，依赖 UtilHttp + UtilToken + IntpConf
• 2.4 实现内部 getAccessToken()：缓存命中直接返回；miss 调 POST {baseUrl}/iam/token 走 form body 拿 token，TTL=expires_in - 60
• 2.5 4 个对外方法实现：拼 URL + Header Authorization: Bearer {accessToken} + 调 UtilHttp.doPost/doPatch/doGet + unwrap {result, error, error_description, data} → McR

3. 验证

• 3.1 mvn -pl mjava -am clean compile 通过
• 3.2 mvn -pl mjava-mcli -am clean package -Dmaven.test.skip=true 通过（确保配置类不会让客户子模块启动失败）
• 3.3 联调冒烟（任选一个客户环境）：
  • 拿 clientId/clientSecret 配进 dev yml
  • 写一个临时 Controller 调 createUser("test_user", "Pwd@123", null)
  • 验证服务端真实创建一条记录 + 返回数据正确
  • 重复调用验证 token 缓存命中（不再发 /iam/token 请求）
• 3.4 openspec validate add-integration-user-api --strict 通过

4. 归档

• 4.1 /opsx:archive add-integration-user-api → 移到 openspec/changes/archive/2026-04-XX-add-integration-user-api/
• 4.2 spec 合并到 openspec/specs/integration-user-api/
• 4.3 BACKLOG.md 标 ✅；mjava-baseline.md vendor 表加一行 integration

5. 后续 change（不在本期范围）

• 集成平台 org / 部门管理（/iam/api/orgs/*）
• 集成平台 角色管理（/iam/api/tags/*）
• 集成平台 启用/禁用用户 + 改密码（/iam/api/users/status / /iam/api/users/password）
• Webhook 接收（/iam/api/open/event/...）
• mjava-pro 多租户 DynamicIntpService