# 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 更新状态。**
