# iam 对接契约

> 负责人：ai06
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)

---

## §1 我提供什么（对外接口）

### 1.1 gRPC 接口（如有）

| Service    | RPC                     | 请求                           | 响应                         | 端口  |
| ---------- | ----------------------- | ------------------------------ | ---------------------------- | ----- |
| IamService | Register                | RegisterRequest                | AuthResponse                 | 50052 |
| IamService | Login                   | LoginRequest                   | AuthResponse                 | 50052 |
| IamService | RefreshToken            | RefreshTokenRequest            | TokenPair                    | 50052 |
| IamService | Logout                  | LogoutRequest                  | LogoutResponse               | 50052 |
| IamService | GetUserInfo             | GetUserInfoRequest             | UserInfo                     | 50052 |
| IamService | BatchGetUsers           | BatchGetUsersRequest           | BatchGetUsersResponse        | 50052 |
| IamService | GetEffectivePermissions | GetEffectivePermissionsRequest | EffectivePermissionsResponse | 50052 |
| IamService | GetEffectiveAccess      | GetEffectiveAccessRequest      | EffectiveAccessResponse      | 50052 |
| IamService | GetEffectiveDataScope   | GetEffectiveDataScopeRequest   | DataScopeResponse            | 50052 |
| IamService | GetViewports            | GetViewportsRequest            | ViewportsResponse            | 50052 |
| IamService | GetPublicKey            | GetPublicKeyRequest            | PublicKeyResponse            | 50052 |
| IamService | GetChildrenByParent     | GetChildrenByParentRequest     | ChildrenResponse             | 50052 |

### 1.2 HTTP 端点（如有）

无对外 HTTP 端点，仅 gRPC。

### 1.3 GraphQL schema（如 BFF）

不适用。

### 1.4 Kafka 事件发布（如有）

| Topic                 | Event                                                                     | 消费方                                                    |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------- |
| edu.iam.user.events   | UserEvent（action: created/updated/deleted/role_changed）                 | core-edu / msg / push-gateway / teacher-bff / student-bff |
| edu.iam.role.events   | RoleEvent（action: created/updated）                                      | core-edu / teacher-bff                                    |
| edu.iam.audit.created | AuditEvent（action: create/update/delete/login/logout/permission_change） | admin-portal                                              |

### 1.5 错误码前缀

`IAM_`（如 IAM_UNAUTHORIZED、IAM_USER_NOT_FOUND、IAM_PERMISSION_DENIED）

---

## §2 我消费什么（依赖上游）

### 2.1 gRPC 调用（同步）

无。iam 是身份根服务，不依赖其他业务服务。

### 2.2 Kafka 事件订阅（异步）

无。

### 2.3 HTTP 调用（如有）

无。

---

## §3 就绪信号

### 3.1 我依赖的上游就绪标志

无上游依赖。

### 3.2 我的就绪标志（供下游消费）

- [ ] iam gRPC 50052 启用（HealthService.Check 返回 SERVING）
- [ ] IamService.Register/Login/RefreshToken/Logout 可调用（返回 AuthResponse/TokenPair）
- [ ] IamService.GetPublicKey 可用（返回 RS256 PEM 公钥，供 api-gateway 验签）
- [ ] IamService.GetChildrenByParent 可用（供 parent-bff 查孩子列表）
- [ ] edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created topic 可发布
- [ ] JWT RS256 签发链路打通（access_token + refresh_token）

---

## §4 Mock 策略

### 4.1 我提供的 mock

在 iam 真实服务就绪前，为下游（api-gateway / 各 BFF）提供以下 mock：

- **gRPC mock**：使用 grpc-mock 拦截 50052 端口，Register/Login 返回固定 AuthResponse（user.id="mock-user-001", tokens.access_token="mock-access-token"）
- **GetPublicKey mock**：返回固定 RS256 公钥 PEM（与 mock 私钥配对），供 api-gateway 验签 mock JWT
- **GetChildrenByParent mock**：返回固定 ChildInfo 列表（2 个孩子）
- **Kafka mock**：iam 服务就绪前不发布真实事件，下游订阅方使用本地 stub

### 4.2 我消费的 mock

不适用（无上游依赖）。