Edu/apps/admin-portal/docs/nextstep.md

admin-portal 下游工作清单（Next Steps）

负责人：ai16 更新日期：2026-07-13 关联：admin-portal_contract.md、admin-portal_workline.md

---

1. 概述

admin-portal 前端已全部完成（P2-P6 + §7 差距分析 4 批次 + Vitest 测试），Docker 镜像构建成功并在本地 Docker Desktop 验证通过。但真实后端集成需要下游服务补齐以下工作。

本地 Docker 测试结果（2026-07-13）：

• ✅ 镜像构建成功（edu/admin-portal:test）
• ✅ 容器启动正常（端口 4003）
• ✅ /api/health 返回 200
• ✅ /api/ready 返回 200（gateway 可达）
• ✅ /login 页面返回 200
• ✅ /admin/dashboard 页面返回 200
• ❌ /api/admin/graphql 返回 500（api-gateway 返回 404，路由未配置）

---

2. 下游阻塞项

2.1 api-gateway（ai01 负责）

阻塞级别：P0（必须完成才能端到端联调）

#	工作项	详情
1	新增 /api/admin/graphql 路由	当前 api-gateway 仅有 /api/v1/* 路由组，无 /api/admin/* 路由。需新增 POST /api/admin/graphql 代理到 teacher-bff :3003/graphql
2	admin 角色强制校验中间件	在 /api/admin/* 路由组上添加 admin 角色门禁，拒绝非 admin 角色访问
3	路径对齐契约 §2.3	契约要求 POST /api/admin/graphql 为唯一入口，当前 api-gateway 无此路由

相关文件：

• services/api-gateway/main.go（L69-104，路由注册）
• services/api-gateway/internal/middleware/auth.go（鉴权中间件）
• services/api-gateway/internal/proxy/proxy.go（反向代理）
• services/api-gateway/internal/config/config.go（配置）

2.2 teacher-bff（ai03 负责）

阻塞级别：P0（必须完成才能端到端联调）

2.2.1 缺失的 Query（16 个）

#	契约 Query	当前状态	备注
1	adminPermissions	❌ 未实现	权限点列表
2	adminViewports(scope)	❌ 未实现	视口配置，需 scope 参数
3	adminClasses	❌ 未实现	班级全局管理
4	adminTeachers	❌ 未实现	教师全局管理
5	adminStudents	❌ 未实现	学生全局管理
6	adminDashboard	❌ 未实现	管理仪表盘聚合数据
7	adminSchools	❌ 未实现	多学校列表（当前仅有单数 school）
8	adminGrades	❌ 未实现	年级管理
9	adminDepartments	❌ 未实现	部门/教研组管理
10	adminAcademicYears	❌ 未实现	学年学期管理
11	adminAnnouncements	❌ 未实现	公告列表
12	adminInvitationCodes	❌ 未实现	邀请码列表
13	adminFiles	❌ 未实现	文件列表
14	adminFileStats	❌ 未实现	文件统计
15	aiProviders	❌ 未实现	AI Provider 列表
16	aiUsage	❌ 未实现	AI 用量统计

2.2.2 缺失的 Mutation（11 个）

#	契约 Mutation	当前状态	备注
1	toggleUserStatus	❌ 未实现	用户启用/禁用/锁定
2	updateRolePermissions	❌ 未实现	角色权限矩阵更新
3	updateViewport	❌ 未实现	视口配置更新
4	createAnnouncement	❌ 未实现	创建公告
5	publishAnnouncement	❌ 未实现	发布公告
6	archiveAnnouncement	❌ 未实现	归档公告
7	toggleAnnouncementPin	❌ 未实现	公告置顶切换
8	generateInvitationCodes	❌ 未实现	批量生成邀请码
9	deleteInvitationCodes	❌ 未实现	删除邀请码
10	deleteFiles	❌ 未实现	批量删除文件
11	updateAiProvider	❌ 未实现	更新 AI Provider 配置

2.2.3 已实现但需对齐的项

#	工作项	详情
1	命名规范对齐	契约用扁平命名 adminUsers/adminRoles，实际实现用命名空间 admin { users }。需 ai03 与 ai16 协调统一
2	auditLogs 补 filter 参数	当前仅 page/pageSize，需补 action/userId/dateRange 等 filter
3	adminOrganization 补 parentId 参数	当前无参数，需支持 parentId 筛选子节点
4	用户/角色 CRUD 接入真实 iam gRPC	当前返回 mock 数据

相关文件：

• services/teacher-bff/src/admin/admin.resolver.ts
• services/teacher-bff/src/admin/admin.service.ts
• services/teacher-bff/src/admin/admin.module.ts
• services/teacher-bff/src/graphql/graphql.controller.ts
• services/teacher-bff/src/graphql/graphql.module.ts
• packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql

2.3 iam 服务（ai06 负责，间接影响）

阻塞级别：P1（影响 admin 用户管理真实性）

#	工作项	详情
1	补 BatchGetUsers RPC	admin 用户列表需要批量获取用户信息
2	补 CreateUser/UpdateUser/DeleteUser RPC	admin 用户 CRUD 需要 iam 支持

---

3. admin-portal 前端待办（非阻塞）

以下工作不阻塞当前部署，但需在下游就绪后完成：

#	工作项	触发条件
1	GraphQL query 字符串对齐命名规范	ai03 与 ai16 协调命名后
2	移除 MSW mock 依赖（生产构建已移除）	api-gateway + teacher-bff 就绪后
3	MF 模式集成测试（NEXT_PUBLIC_MF_ENABLED=true）	teacher-portal Shell 就绪后
4	OTel trace 上报联调	otel-collector 就绪后
5	WebSocket 实时通知联调	push-gateway 就绪后

---

4. 已完成项汇总

工作项	状态	验证方式
P2 MF Remote 骨架	✅	arch:scan + typecheck
P3 用户/角色权限管理	✅	typecheck + lint + vitest
P4 组织/学校/全局实体	✅	typecheck + lint + vitest
P5 审计日志/实时通知	✅	typecheck + lint + vitest
P6 硬化（A11y/Web Vitals/测试/Dockerfile）	✅	vitest 69/69 + Docker 构建成功
§7 差距分析 4 批次补齐	✅	typecheck + lint + vitest
Docker 镜像构建	✅	edu/admin-portal:test 构建成功
Docker 容器运行	✅	/api/health + /api/ready + /login + /admin/dashboard 全部 200
docker-compose.deploy.yml 服务定义	✅	admin-portal 服务已添加
next.config.js output: standalone	✅	Docker 构建产物正确
.env.local 关闭 mock	✅	NEXT_PUBLIC_API_MOCKING=disabled

---

5. 联调顺序建议

1. ai01 完成 api-gateway /api/admin/graphql 路由 + admin 角色校验
2. ai03 完成 teacher-bff admin Query/Mutation 补齐 + 命名规范对齐
3. ai06 完成 iam gRPC 补齐（BatchGetUsers 等）
4. ai16 前端 GraphQL query 字符串对齐命名规范
5. 端到端联调（admin-portal → api-gateway → teacher-bff → iam/classes/core-edu）

---

本文件由 ai16 维护，下游工作项请各负责 AI 完成后通知 ai16 更新状态。