docs(admin-portal): 新增 nextstep-v2.md 记录下游核查结果
v1 声称完成的下游工作经核查实际未完成： - api-gateway: /api/admin/graphql 路由未注册，go vet 编译失败 - teacher-bff: resolver 已完成但 schema 未同步（命名空间 vs 扁平） - iam: proto 缺 BatchGetUsers rpc 声明 v2 记录详细核查证据和修复要求
This commit is contained in:
SpecialX
161
apps/admin-portal/docs/nextstep-v2.md
Normal file
161
apps/admin-portal/docs/nextstep-v2.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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 更新状态。**
|
||||
Reference in New Issue
Block a user