xiner/Edu

Files

SpecialX faaaf29f67 docs: ai 协作文档体系重构与多 ai 仲裁结果落地

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.设计规格文档

2026-07-10 12:58:22 +08:00

7.4 KiB

Raw Blame History

admin-portal 对接契约

负责人：ai16 关联：matrix.md、iam.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

7.4 KiB Raw Blame History Unescape Escape