# admin-portal 对接契约

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

---

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

### 1.1 gRPC 接口（如有）

无。admin-portal 是前端微前端 Remote。

### 1.2 HTTP 端点（如有）

| Method | Path        | 用途             | 认证                  |
| ------ | ----------- | ---------------- | --------------------- |
| GET    | /           | 管理后台首页     | JWT 必需 + admin 角色 |
| GET    | /users      | 用户管理         | JWT 必需 + admin      |
| GET    | /roles      | 角色权限管理     | JWT 必需 + admin      |
| GET    | /classes    | 班级管理（全局） | JWT 必需 + admin      |
| GET    | /teachers   | 教师管理         | JWT 必需 + admin      |
| GET    | /students   | 学生管理         | JWT 必需 + admin      |
| GET    | /audit-logs | 审计日志         | JWT 必需 + admin      |
| GET    | /dashboard  | 管理员仪表盘     | JWT 必需 + admin      |
| GET    | /system     | 系统配置         | JWT 必需 + admin      |

### 1.3 GraphQL schema（如 BFF）

不适用。admin-portal 消费 teacher-bff GraphQL admin namespace，自身不提供 schema。

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

无。

### 1.5 错误码前缀

无（前端不定义错误码前缀，透传 BFF 错误码）。

### 1.6 微前端架构（补充）

| 角色                   | 说明                                            |
| ---------------------- | ----------------------------------------------- |
| MF Remote              | 管理后台是微前端远程模块                        |
| 暴露的 remote 模块     | AdminApp（管理后台完整应用）、shared 管理端组件 |
| module federation 配置 | `apps/admin-portal/module-federation.config.ts` |

---

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

### 2.1 gRPC 调用（同步）

无。前端不直接调 gRPC。

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

无。前端不直接订阅 Kafka（审计日志通过 GraphQL 查询，非直接订阅）。

### 2.3 HTTP 调用（如有）

| 被调用方            | Method.Path             | 用途                                                          | mock 策略                                                         |
| ------------------- | ----------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01)  | POST /api/admin/graphql | 管理 GraphQL 查询（经网关代理到 teacher-bff admin namespace） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01)  | POST /api/auth/login    | 管理员登录                                                    | api-gateway 就绪前使用 MSW 返回固定 JWT（admin 角色）             |
| push-gateway (ai02) | GET /ws                 | WebSocket 实时通知                                            | push-gateway 就绪前使用 mock-socket 模拟 WS 推送                  |

### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff admin namespace）

| Query/Mutation                                    | 用途                            | mock 策略                                                                           |
| ------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| currentUser                                       | 当前管理员信息                  | MSW 返回固定管理员（admin 角色）                                                    |
| adminUsers / createUser / updateUser / deleteUser | 用户管理                        | MSW 返回固定 50 个用户 + CRUD success                                               |
| adminRoles / updateRolePermissions                | 角色权限管理                    | MSW 返回固定 5 个角色 + 权限矩阵                                                    |
| adminClasses                                      | 班级管理（全局）                | MSW 返回固定 20 个班级                                                              |
| adminTeachers                                     | 教师管理                        | MSW 返回固定 50 个教师                                                              |
| adminStudents                                     | 学生管理                        | MSW 返回固定 1200 个学生                                                            |
| auditLogs                                         | 审计日志（聚合 iam AuditEvent） | MSW 返回固定 100 条审计日志                                                         |
| adminDashboard                                    | 管理员仪表盘                    | MSW 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0） |

---

## §3 就绪信号

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

- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口 + admin 角色校验
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— admin namespace 可用
- [ ] iam gRPC 50052 启用（ai06）—— 用户/角色/审计日志数据来源
- [ ] edu.iam.audit.created topic 有事件发布（ai06）—— 审计日志来源
- [ ] data-ana gRPC 50055 启用（ai11）—— adminDashboard 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知

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

- [ ] admin-portal dev server :4003 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 AdminApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫 + admin 角色校验）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT，前端校验 admin 角色）
- [ ] GraphQL 查询可执行（currentUser / adminDashboard / auditLogs 返回数据）
- [ ] 用户/角色 CRUD 可执行（createUser / updateRolePermissions）
- [ ] WebSocket 通知可接收

---

## §4 Mock 策略

### 4.1 我提供的 mock

admin-portal 是前端，无下游消费方。但对开发体验提供：

- **Storybook**：各组件独立 story（含权限矩阵编辑器、审计日志表格等复杂组件）
- **MSW handlers**：`apps/admin-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求

### 4.2 我消费的 mock

在真实上游就绪前，admin-portal 使用以下 mock：

- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
  - POST /api/auth/login → 返回固定 JWT + UserInfo（admin 角色，permissions=["*"]）
  - POST /api/admin/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff admin namespace mock 数据一致）
  - auditLogs mock 返回固定 100 条审计日志（含 action: create/update/delete/login/logout/permission_change）
  - adminDashboard mock 返回固定全校统计仪表盘
  - 所有 mock 响应定义在 `apps/admin-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
  - 连接后每 30 秒推送 1 条 mock 系统通知
- **JWT mock**：使用固定 mock JWT（admin 角色），存入 httpOnly cookie
- **权限矩阵 mock**：内置固定 5 个角色 + 完整权限矩阵（teacher/student/parent/admin/super_admin）
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`