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

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

负责人：ai16 更新日期：2026-07-14 关联：nextstep.md v1、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 更新状态。