# admin-portal 下游工作清单（Next Steps） > 负责人：ai16 > 更新日期：2026-07-13 > 关联：[admin-portal_contract.md](../../docs/architecture/issues/contracts/admin-portal_contract.md)、[admin-portal_workline.md](../../docs/architecture/issues/worklines/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 更新状态。**