Merge worktree branch merge-15-modules-to-main-5ug5xJ

2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 deletions
--- a/docs/architecture/issues/contracts/iam_contract.md
+++ b/docs/architecture/issues/contracts/iam_contract.md
@@ -2,35 +2,57 @@

 > 负责人：ai06
 > 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
+> 裁决依据：[coord-final-decisions](../../coord-final-decisions.md) I1-I8、[president-final-rulings](../../president-final-rulings.md) §2.15/§2.16/§5.5

 ---

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

-### 1.1 gRPC 接口（如有）
+> **双入口策略**（president §2.16）：REST 供 gateway 透传 + admin-portal 直连，gRPC 供 BFF 聚合调用。同一 Application Service 同时被 REST Controller + gRPC Controller 调用，业务逻辑不重复。gateway 保持 HTTP 透传（不改为 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.1 gRPC 接口（供 BFF 聚合调用）

-### 1.2 HTTP 端点（如有）
+> 端口 50052，P2 即启用（I1 裁决）。⚠️ 当前 iam.proto 仅 4 RPC，待 coord 补全至 12 RPC（ISSUE-005）。

-无对外 HTTP 端点，仅 gRPC。
+| Service    | RPC                     | 请求                           | 响应                         | 端口  | 消费方                                   |
+| ---------- | ----------------------- | ------------------------------ | ---------------------------- | ----- | ---------------------------------------- |
+| IamService | Register                | RegisterRequest                | AuthResponse                 | 50052 | api-gateway（REST 透传）/ admin-portal   |
+| IamService | Login                   | LoginRequest                   | AuthResponse                 | 50052 | api-gateway（REST 透传）/ admin-portal   |
+| IamService | RefreshToken            | RefreshTokenRequest            | TokenPair                    | 50052 | api-gateway（REST 透传）                 |
+| IamService | Logout                  | LogoutRequest                  | LogoutResponse               | 50052 | api-gateway（REST 透传）                 |
+| IamService | GetUserInfo             | GetUserInfoRequest             | UserInfo                     | 50052 | teacher-bff / student-bff / parent-bff  |
+| IamService | BatchGetUsers           | BatchGetUsersRequest           | BatchGetUsersResponse        | 50052 | teacher-bff / admin-portal               |
+| IamService | GetEffectivePermissions | GetEffectivePermissionsRequest | EffectivePermissionsResponse | 50052 | teacher-bff / student-bff / parent-bff  |
+| IamService | GetEffectiveAccess      | GetEffectiveAccessRequest      | EffectiveAccessResponse      | 50052 | teacher-bff / student-bff / parent-bff  |
+| IamService | GetEffectiveDataScope   | GetEffectiveDataScopeRequest   | DataScopeResponse            | 50052 | teacher-bff / data-ana                   |
+| IamService | GetViewports            | GetViewportsRequest            | ViewportsResponse            | 50052 | teacher-bff / student-bff / parent-bff  |
+| IamService | GetPublicKey            | GetPublicKeyRequest            | PublicKeyResponse            | 50052 | api-gateway（JWKS 验签）                 |
+| IamService | GetChildrenByParent     | GetChildrenByParentRequest     | ChildrenResponse             | 50052 | parent-bff                               |
+
+### 1.2 HTTP 端点（供 gateway 透传 + admin-portal 直连）
+
+> REST 与 gRPC 双入口并存（president §2.16）。REST 路径统一加 `/v1` 前缀（I7 裁决）。gateway 路由 `/iam/v1/*` → iam 服务 `/v1/iam/*`（透传不改路径）。
+
+| Method | Path                              | 权限              | 说明                                   | 消费方               |
+| ------ | --------------------------------- | ----------------- | -------------------------------------- | -------------------- |
+| POST   | `/iam/v1/register`                | 公开              | 注册 + 自动分配 teacher 角色           | api-gateway / admin  |
+| POST   | `/iam/v1/login`                   | 公开              | 登录，返回 accessToken + refreshToken  | api-gateway          |
+| POST   | `/iam/v1/refresh`                 | 公开              | 刷新令牌（轮换 + 旧 token 黑名单）     | api-gateway          |
+| POST   | `/iam/v1/logout`                  | `IAM_USER_READ`   | 登出（refresh token 加黑名单）         | api-gateway          |
+| GET    | `/iam/v1/me`                      | `IAM_USER_READ`   | 当前用户信息                           | api-gateway / admin  |
+| GET    | `/iam/v1/viewports`               | `IAM_USER_READ`   | 当前用户视口（L1 导航）                | api-gateway          |
+| GET    | `/iam/v1/permissions/effective`   | `IAM_USER_READ`   | 当前用户有效权限（I8 统一路径）        | api-gateway          |
+| GET    | `/iam/v1/.well-known/jwks.json`   | 公开              | RS256 公钥 JWK Set（Gateway 拉取验签） | api-gateway          |
+| GET    | `/iam/v1/children`                | `IAM_USER_READ`   | 当前家长的孩子列表（I6 裁决）          | api-gateway / parent |
+| GET    | `/iam/v1/roles`                   | `IAM_ROLE_MANAGE` | 角色列表（管理端）                     | admin-portal         |
+| GET    | `/iam/v1/permissions`             | `IAM_ROLE_MANAGE` | 权限点列表（管理端）                   | admin-portal         |
+| GET    | `/healthz`                        | 无                | liveness                               | k8s / 监控           |
+| GET    | `/readyz`                         | 无                | readiness（5 依赖检查）                | k8s / 监控           |
+| GET    | `/metrics`                        | 无                | Prometheus 指标                        | Prometheus           |

 ### 1.3 GraphQL schema（如 BFF）

-不适用。
+不适用。iam 是业务服务，不暴露 GraphQL（GraphQL 由 BFF 层提供）。

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

@@ -66,16 +88,23 @@

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

-无上游依赖。
+iam 是身份根服务，无业务上游依赖。但依赖以下基础设施契约（coord 提供）：
+
+| 依赖项 | 提供方 | 就绪标志 | 状态 |
+| ------ | ------ | -------- | ---- |
+| iam.proto 补全至 12 RPC | coord | proto 含 12 RPC + 全部 message | ❌ 仅 4 RPC（ISSUE-005） |
+| events.proto 补全 UserEvent/RoleEvent/AuditEvent | coord | proto 含 3 个 message | ❌ 缺失（ISSUE-002） |
+| shared-ts Outbox 工具包 | coord | outbox.service.ts 可导入 | ✅ 已就绪 |

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

 - [ ] iam gRPC 50052 启用（HealthService.Check 返回 SERVING）
- [ ] IamService.Register/Login/RefreshToken/Logout 可调用（返回 AuthResponse/TokenPair）
+- [ ] IamService 12 RPC 全部可调用（Register/Login/RefreshToken/Logout/GetUserInfo/BatchGetUsers/GetEffectivePermissions/GetEffectiveAccess/GetEffectiveDataScope/GetViewports/GetPublicKey/GetChildrenByParent）
 - [ ] 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）
+- [ ] JWT RS256 签发链路打通（access_token 15min + refresh_token 7day 轮换）
+- [ ] /iam/v1/* REST 端点可用（供 gateway 透传 + admin-portal 直连，双入口策略）

 ---

@@ -83,13 +112,15 @@

 ### 4.1 我提供的 mock

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

- **gRPC mock**：使用 grpc-mock 拦截 50052 端口，Register/Login 返回固定 AuthResponse（user.id="mock-user-001", tokens.access_token="mock-access-token"）
+- **gRPC mock**（供 BFF）：使用 grpc-mock 拦截 50052 端口，Register/Login 返回固定 AuthResponse（user.id="mock-user-001", tokens.access_token="mock-access-token"）
+- **REST mock**（供 gateway / admin-portal）：MSW 或 express mock 拦截 /iam/v1/* 路径，返回与 gRPC mock 一致的结构
 - **GetPublicKey mock**：返回固定 RS256 公钥 PEM（与 mock 私钥配对），供 api-gateway 验签 mock JWT
 - **GetChildrenByParent mock**：返回固定 ChildInfo 列表（2 个孩子）
+- **JWKS mock**：GET /iam/v1/.well-known/jwks.json 返回固定 JWK Set
 - **Kafka mock**：iam 服务就绪前不发布真实事件，下游订阅方使用本地 stub

 ### 4.2 我消费的 mock

-不适用（无上游依赖）。
+不适用（iam 是身份根服务，无业务上游依赖）。