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

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

> 负责人：ai16
> 更新日期：2026-07-14
> 关联：[nextstep.md v1](./nextstep.md)、[admin-portal_contract.md](../../docs/architecture/issues/contracts/admin-portal_contract.md)
> 核查方式：源码审查 + 端点测试 + 编译验证

---

## 1. 核查结论

**v1 中声称"已完成"的下游工作存在严重不符。** 经源码审查和端点测试，3 个下游模块均未真正完成：

| 模块                 | v1 声称   | v2 实际                 | 严重程度 |
| -------------------- | --------- | ----------------------- | -------- |
| api-gateway          | ✅ 已完成 | ❌ **未实现**           | P0 阻塞  |
| teacher-bff resolver | —         | ✅ **已完成**           | 无       |
| teacher-bff schema   | —         | ❌ **未同步**           | P0 阻塞  |
| iam proto            | —         | ❌ **契约缺失**         | P1 阻塞  |
| admin-portal 前端    | —         | ✅ **与 resolver 一致** | 无       |

---

## 2. 未完成项详情

### 2.1 api-gateway（ai01 负责）— P0 阻塞

**核查方法：** 源码审查 + `go vet` 编译 + curl 端点测试

| #   | v1 声称                           | 实际状态                | 证据                                                                                        |
| --- | --------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| 1   | ✅ 新增 `/api/admin/graphql` 路由 | ❌ **未实现**           | `main.go` L68-104 仅有 `/api/v1` 路由组，无 `/api/admin` 路由组                             |
| 2   | ✅ admin 角色强制校验中间件       | ⚠️ **代码存在但未注册** | `internal/middleware/admin_role.go` 已实现 `AdminRoleMiddleware()`，但 `main.go` 中从未调用 |
| 3   | ✅ NewProxyRewrite 代理函数       | ❌ **未实现**           | `internal/proxy/proxy.go` 只有 `NewProxy`，无 `NewProxyRewrite`                             |
| 4   | ✅ registerBffProxy               | ❌ **未实现**           | `main.go` 中无此函数                                                                        |

**编译验证：**

- `go build ./...` → 通过（不编译测试文件）
- `go vet ./...` → **失败**，5 处 `undefined: NewProxyRewrite`（测试文件引用了不存在的函数）

**端点测试：**

- `POST http://localhost:8080/api/admin/graphql` → **404 Not Found**

**需完成的工作：**

1. 在 `main.go` 中注册 `/api/admin/graphql` 路由，代理到 teacher-bff :3003/graphql
2. 在该路由上挂载 `AdminRoleMiddleware()`
3. 实现 `NewProxyRewrite` 函数（或删除引用它的测试文件）
4. 修复 `go vet` 编译错误

### 2.2 teacher-bff schema（ai03 负责）— P0 阻塞

**核查方法：** 源码审查 + GraphQL 端点测试

**问题：** resolver 已用扁平命名（`adminUsers`、`adminRoles` 等），但 schema 文件仍是旧的命名空间模式。

**文件：** `packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql`

| #   | 问题                   | 详情                                                                        |
| --- | ---------------------- | --------------------------------------------------------------------------- |
| 1   | schema 命名模式不一致  | schema 用 `type Query { admin: AdminQuery! }`，resolver 用扁平 `adminUsers` |
| 2   | AdminQuery 字段缺失    | schema L317-335 仅 7 个字段，缺 16 个新 Query                               |
| 3   | AdminMutation 字段缺失 | schema L336+ 仅 10 个 Mutation，缺 11 个新 Mutation                         |
| 4   | 输入类型缺失           | `AdminUserFilterInput`、`CreateUserInput`、`UpdateUserInput` 等未定义       |

**端点测试：**

- `POST http://localhost:3003/graphql` with `{ adminUsers(filter:{page:1,pageSize:10}){ items{ id } } }` → **500**（schema 校验失败）

**需完成的工作：**

1. 将 schema 从命名空间模式改为扁平模式（`type Query { adminUsers: ...! }`）
2. 添加所有 16 个新 Query 的字段定义
3. 添加所有 11 个新 Mutation 的字段定义
4. 添加所有输入类型定义（`AdminUserFilterInput`、`CreateUserInput` 等）
5. 删除旧的 `AdminQuery`/`AdminMutation` 类型（或标记为 deprecated）

### 2.3 iam proto 契约（ai06 负责）— P1 阻塞

**核查方法：** proto 文件审查 + 实现代码审查

**文件：** `packages/shared-proto/proto/iam.proto`

| #   | 工作项              | Proto 定义         | 实现代码                              | 状态     |
| --- | ------------------- | ------------------ | ------------------------------------- | -------- |
| 1   | `BatchGetUsers` RPC | ❌ **无 rpc 声明** | ✅ `iam.grpc.controller.ts:62` 已实现 | 契约缺失 |
| 2   | `CreateUser` RPC    | ❌ 未定义          | ❌ 仅 REST 实现                       | 未实现   |
| 3   | `UpdateUser` RPC    | ❌ 未定义          | ❌ 仅 REST 实现                       | 未实现   |
| 4   | `DeleteUser` RPC    | ❌ 未定义          | ❌ 未实现                             | 未实现   |

**注意：** iam.proto L66-72 定义了 `BatchGetUsersRequest`/`BatchGetUsersResponse` 消息，但 `service IamService` 中**没有** `rpc BatchGetUsers`。gRPC 客户端无法发现该服务。

**需完成的工作：**

1. 在 `service IamService` 中添加 `rpc BatchGetUsers(BatchGetUsersRequest) returns (BatchGetUsersResponse);`
2. 添加 `CreateUser`/`UpdateUser`/`DeleteUser` RPC 定义和实现（如果 teacher-bff 需要 gRPC 调用）

---

## 3. admin-portal 前端状态

### 3.1 已完成项

| 工作项                         | 状态 | 验证方式                                                      |
| ------------------------------ | ---- | ------------------------------------------------------------- |
| 43 个 GraphQL operation 字符串 | ✅   | 与 resolver 扁平命名一致                                      |
| Docker 镜像构建                | ✅   | `edu/admin-portal:test` 构建成功                              |
| Docker 容器运行                | ✅   | /api/health + /api/ready + /login + /admin/dashboard 全部 200 |
| typecheck + lint               | ✅   | 零错误                                                        |
| vitest                         | ✅   | 69/69 通过                                                    |

### 3.2 前端无需修改

admin-portal 前端代码与 teacher-bff resolver 完全一致（扁平命名），**不需要修改前端代码**。所有阻塞项都在下游服务。

---

## 4. 端到端联调测试结果

| 测试项                            | 结果   | 原因                               |
| --------------------------------- | ------ | ---------------------------------- |
| admin-portal → /login             | ✅ 200 | 前端独立工作                       |
| admin-portal → /api/health        | ✅ 200 | 前端独立工作                       |
| admin-portal → /api/ready         | ✅ 200 | api-gateway :8080 可达             |
| admin-portal → /api/admin/graphql | ❌ 500 | api-gateway 返回 404（路由未注册） |
| teacher-bff → /graphql (扁平命名) | ❌ 500 | schema 未同步（命名空间模式）      |

**结论：** 端到端联调无法进行，需下游服务修复后重新测试。

---

## 5. 联调顺序（更新）

1. **ai03** 修复 teacher-bff schema（改为扁平命名，补齐字段）— P0
2. **ai01** 修复 api-gateway 路由（注册 `/api/admin/graphql`，挂载中间件）— P0
3. **ai06** 修复 iam proto（添加 BatchGetUsers rpc 声明）— P1
4. **ai16** 重新构建 admin-portal Docker 镜像并端到端测试
5. 全链路联调：admin-portal → api-gateway → teacher-bff → iam/classes/core-edu

---

## 6. v1 与 v2 差异说明

| v1 声称             | v2 实际                         | 差异原因                            |
| ------------------- | ------------------------------- | ----------------------------------- |
| api-gateway ✅ 完成 | ❌ 未实现                       | v1 核查不充分，未实际测试端点和编译 |
| teacher-bff ✅ 完成 | ⚠️ resolver 完成，schema 未同步 | v1 未区分 resolver 和 schema        |
| iam ✅ 完成         | ❌ proto 缺 rpc 声明            | v1 未审查 proto 文件                |

**教训：** 下游工作完成声明必须通过以下方式验证：

1. 源码审查（不仅看文档声明）
2. 编译验证（`go vet`/`tsc`/`ruff`）
3. 端点测试（curl/Invoke-WebRequest）
4. 集成测试（端到端调用）

---

**本文件由 ai16 维护，v1 中的虚假完成声明已在此 v2 版本中修正。请各负责 AI 按 §5 联调顺序修复后通知 ai16 更新状态。**