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