## 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`