faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# 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
|
||
|
||
不适用（无上游依赖）。
|