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.设计规格文档
4.4 KiB
4.4 KiB
iam 对接契约
负责人：ai06 关联：matrix.md、iam.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
不适用（无上游依赖）。