xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(admin-portal): 新增 nextstep-v2.md 记录下游核查结果

Browse Source 
v1 声称完成的下游工作经核查实际未完成：
- api-gateway: /api/admin/graphql 路由未注册，go vet 编译失败
- teacher-bff: resolver 已完成但 schema 未同步（命名空间 vs 扁平）
- iam: proto 缺 BatchGetUsers rpc 声明

v2 记录详细核查证据和修复要求
This commit is contained in:
SpecialX
2026-07-14 08:26:27 +08:00
parent 99580fa13a
commit 0b42302a64
42 changed files with 4804 additions and 637 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/architecture/issues/worklines/teacher-portal_workline.md
View File

@@ -135,16 +135,16 @@ gantt
### §4.1 我依赖的上游就绪标志
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | -------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/v1/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | -------------------------------------------------- | -------- | ----------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/v1/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| ai 服务 gRPC（ai12 P5） | generateQuestion/generateLessonPlan 可调 | P5 启动 | ✅ 已就绪（2026-07-13） |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
### §4.2 我的就绪信号（供下游消费）
@@ -184,15 +184,16 @@ gantt
**审核时完成度**（已通过并行实现全部补齐）：
| 阶段 | 审核时 | 实现后 | 本次新增 |
| --- | ------ | ------ | -------- |
| P2 | ~95% | ~95% | — |
| P3 | ~30% | ✅ 100% | 5 mutation/query + 4 新页面 + 批改界面 + 乐观更新 + 多Tab同步 + 成绩统计图表 + settings 编辑 |
| P4 | 0% | ✅ 100% | 知识图谱SVG可视化 + 学情分析仪表盘 + 单生详情页 + parent-portal Remote 组件 |
| P5 | 0% | ✅ 100% | WebSocket通知hook + 通知中心页 + AI出题(SSE模拟) + AI教案 + AI学情报告 |
| P6 | 0% | ✅ 100% | Sentry + WebVitals + OTel + A11y审计 + 性能配置 + Cookie迁移准备 + ObservabilityProvider |
| 阶段 | 审核时 | 实现后 | 本次新增 |
| ---- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| P2 | ~95% | ~95% | — |
| P3 | ~30% | ✅ 100% | 5 mutation/query + 4 新页面 + 批改界面 + 乐观更新 + 多Tab同步 + 成绩统计图表 + settings 编辑 |
| P4 | 0% | ✅ 100% | 知识图谱SVG可视化 + 学情分析仪表盘 + 单生详情页 + parent-portal Remote 组件 |
| P5 | 0% | ✅ 100% | WebSocket通知hook + 通知中心页 + AI出题(SSE模拟) + AI教案 + AI学情报告 |
| P6 | 0% | ✅ 100% | Sentry + WebVitals + OTel + A11y审计 + 性能配置 + Cookie迁移准备 + ObservabilityProvider |
**本次实现新增文件清单**（30+ 文件）：
- P3: graphql.ts 扩展(5操作) + handlers.ts 扩展 + exams/[id] + exams/new + homework/[id] + homework/new + use-cross-tab-sync.ts + fixtures 扩展 + settings/grades 改造
- P4: graphql-p4.ts + handlers-p4.ts + knowledge-graph/page.tsx + KnowledgeGraphView.tsx + analytics/page.tsx + TrendChart.tsx + analytics/[studentId]/page.tsx + ParentPortalRemote.tsx + fixtures(knowledge-graph/analytics)
- P5: graphql-p5.ts + handlers-p5.ts + notifications/page.tsx + ai-assist/page.tsx + ai-lesson-plan/page.tsx + ai-report/page.tsx + use-notifications-websocket.ts + fixtures(notifications/ai) + browser.ts/server.ts 集成
@@ -204,6 +205,7 @@ gantt
**coord 仲裁状态**：无新待处理仲裁。ARB-001/002 已裁决，ISSUE-036~042 全部闭合。上游 ai(ai12) 已就绪 ✅。
**仍需后续处理**：
1. 单元测试（vitest 配置 + 测试文件）
2. 设计令牌硬编码修复（globals.css/tailwind.config.js 的 hsl() 字面量）
3. 字体名硬编码修复（layout.tsx → var(--font-family-*)）
@@ -222,30 +224,31 @@ gantt
### §5.2 差距清单与实现状态
| 模块 | 参考页面数 | 实现前 | 实现后 | 新增页面 |
| ---- | ---------- | ------ | ------ | -------- |
| attendance（考勤） | 4 | 0 | ✅ 4 | list/sheet/stats/report |
| classes（班级详情） | 4 | 1（list） | ✅ 3 新增 | [id]详情、schedule、（students 已有） |
| course-plans（课程计划） | 2 | 0 | ✅ 2 | list、[id]详情 |
| dashboard | 1 | ✅ 已有 | — | — |
| diagnostic（诊断） | 3 | 0 | ✅ 2（[studentId] 由 analytics 覆盖） | list、class/[classId] |
| elective（选修课） | 3 | 0 | ✅ 3 | list、create、[id]/edit |
| error-book（错题本） | 1 | 0 | ✅ 1 | 分析页（7 widget） |
| exams（考试） | 9 | 3 | ✅ 4 新增 | [id]/build、[id]/analytics、[id]/edit-rich、[id]/proctoring |
| grades（成绩） | 5 | 1 | ✅ 4 新增 | entry、stats、analytics、report-card |
| homework（作业） | 7 | 3 | ✅ 3 新增 | submissions、assignments/[id]/submissions、submissions/[submissionId]、submissions/[submissionId]/scan-grading |
| leave（请假） | 1 | 0 | ✅ 1 | 审批列表 |
| lesson-plans（备课） | 6 | 0（仅 ai-lesson-plan） | ✅ 5 | list、new、[planId]/edit、library、calendar、heatmap |
| practice（练习） | 1 | 0 | ✅ 1 | 分析页（6 widget） |
| questions（题库） | 1 | 0 | ✅ 1 | 主页（六维筛选） |
| schedule-changes（调课） | 1 | 0 | ✅ 1 | 申请列表 |
| textbooks（教材） | 2 | 0 | ✅ 2 | list、[id]阅读器 |
| 模块 | 参考页面数 | 实现前 | 实现后 | 新增页面 |
| ------------------------ | ---------- | ---------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| attendance（考勤） | 4 | 0 | ✅ 4 | list/sheet/stats/report |
| classes（班级详情） | 4 | 1（list） | ✅ 3 新增 | [id]详情、schedule、（students 已有） |
| course-plans（课程计划） | 2 | 0 | ✅ 2 | list、[id]详情 |
| dashboard | 1 | ✅ 已有 | — | — |
| diagnostic（诊断） | 3 | 0 | ✅ 2（[studentId] 由 analytics 覆盖） | list、class/[classId] |
| elective（选修课） | 3 | 0 | ✅ 3 | list、create、[id]/edit |
| error-book（错题本） | 1 | 0 | ✅ 1 | 分析页（7 widget） |
| exams（考试） | 9 | 3 | ✅ 4 新增 | [id]/build、[id]/analytics、[id]/edit-rich、[id]/proctoring |
| grades（成绩） | 5 | 1 | ✅ 4 新增 | entry、stats、analytics、report-card |
| homework（作业） | 7 | 3 | ✅ 3 新增 | submissions、assignments/[id]/submissions、submissions/[submissionId]、submissions/[submissionId]/scan-grading |
| leave（请假） | 1 | 0 | ✅ 1 | 审批列表 |
| lesson-plans（备课） | 6 | 0（仅 ai-lesson-plan） | ✅ 5 | list、new、[planId]/edit、library、calendar、heatmap |
| practice（练习） | 1 | 0 | ✅ 1 | 分析页（6 widget） |
| questions（题库） | 1 | 0 | ✅ 1 | 主页（六维筛选） |
| schedule-changes（调课） | 1 | 0 | ✅ 1 | 申请列表 |
| textbooks（教材） | 2 | 0 | ✅ 2 | list、[id]阅读器 |
**总计**：新增 35 个页面 + 修改 grades list（增加录入/统计/分析/报告卡/导出/Excel 导入链接）
### §5.3 新增文件清单（按批次）
**P0-A（grades + homework 批改链路）— 11 个文件**：
- `src/lib/graphql-p7-grades.ts`（9 operations + 类型）
- `src/mocks/handlers-p7-grades.ts`、`src/mocks/fixtures/grades-extended.ts`、`homework-submissions.ts`
- `src/app/(app)/grades/entry/page.tsx`、`grades/stats/page.tsx`、`grades/analytics/page.tsx`、`grades/analytics/charts.tsx`（5 SVG 图表）、`grades/report-card/page.tsx`
@@ -253,6 +256,7 @@ gantt
- 修改：`grades/page.tsx`（增加子模块导航 + CSV 导出 + Excel 导入）
**P0-B（exams + questions + textbooks）— 10 个文件**：
- `src/lib/graphql-p7-exams.ts`（11 operations + 类型）
- `src/mocks/handlers-p7-exams.ts`、`fixtures/textbooks.ts`、`questions.ts`、`exam-analytics.ts`
- `src/app/(app)/exams/[id]/build/page.tsx`、`exams/[id]/analytics/page.tsx`
@@ -260,6 +264,7 @@ gantt
- `src/app/(app)/textbooks/page.tsx`、`textbooks/[id]/page.tsx`
**P0-C（attendance + classes 详情 + leave + schedule-changes）— 13 个文件**：
- `src/lib/graphql-p7-admin.ts`（11 operations + 类型）
- `src/mocks/handlers-p7-admin.ts`、`fixtures/attendance.ts`、`classes-extended.ts`、`leave-requests.ts`
- `src/app/(app)/attendance/page.tsx`、`attendance/sheet/page.tsx`、`attendance/stats/page.tsx`、`attendance/report/page.tsx`
@@ -268,6 +273,7 @@ gantt
- `src/app/(app)/schedule-changes/page.tsx`
**P0-D（lesson-plans + course-plans + diagnostic + error-book + practice）— 18 个文件**：
- `src/lib/graphql-p7-insights.ts`（17 operations + 类型）
- `src/mocks/handlers-p7-insights.ts`、`fixtures/lesson-plans.ts`、`course-plans.ts`、`diagnostic.ts`、`error-book.ts`、`practice.ts`
- `src/app/(app)/lesson-plans/page.tsx`、`lesson-plans/new/page.tsx`、`lesson-plans/[planId]/edit/page.tsx`、`lesson-plans/library/page.tsx`、`lesson-plans/calendar/page.tsx`
@@ -277,6 +283,7 @@ gantt
- `src/app/(app)/practice/page.tsx`
**P2-E（elective + 富文本编辑 + 监考 + 扫描批改 + 热力图）— 10 个文件**：
- `src/lib/graphql-p7-advanced.ts`（13 operations + 类型）
- `src/mocks/handlers-p7-advanced.ts`、`fixtures/elective.ts`、`proctoring.ts`、`scan-grading.ts`、`lesson-plan-heatmap.ts`
- `src/app/(app)/elective/page.tsx`、`elective/create/page.tsx`、`elective/[id]/edit/page.tsx`
@@ -285,6 +292,7 @@ gantt
- `src/app/(app)/lesson-plans/heatmap/page.tsx`
**集成文件（修改）— 3 个**：
- `src/mocks/browser.ts`（注册 5 个 p7 handlers）
- `src/mocks/server.ts`（同上）
- `src/mocks/fixtures/viewports.ts`（新增 11 个导航项：attendance/questions/textbooks/lesson-plans/course-plans/diagnostic/error-book/practice/elective/leave/schedule-changes）
@@ -328,11 +336,11 @@ gantt
**路由验证**：
| 类型 | 通过/总数 | 结果 |
| ---- | --------- | ---- |
| 静态路由 | 27/27 | 全部 HTTP 200 ✅ |
| 动态路由 | 11/11 | 全部 HTTP 200 ✅ |
| GraphQL 端点 | N/A | 服务端代理到 api-gateway（未启动时预期 500） |
| 类型 | 通过/总数 | 结果 |
| ------------ | --------- | -------------------------------------------- |
| 静态路由 | 27/27 | 全部 HTTP 200 ✅ |
| 动态路由 | 11/11 | 全部 HTTP 200 ✅ |
| GraphQL 端点 | N/A | 服务端代理到 api-gateway（未启动时预期 500） |
**已知限制**：