feat(portal-shell): wire dashboards to real data-ana queries (P1-2)
- add dashboard.graphql.ts with 6 real aggregate queries
(teacherDashboard / studentDashboard / parentDashboard /
adminDashboard / warnings / errorBookStats), snake_case aligned
- add dashboard.ts with 6 hooks + full domain model types
- add 4 role dashboard pages (teacher/student/parent/admin)
using DashboardShell + StatCard + DashboardSection with
loading / error / success tri-state
- update [[...route]]/page.tsx to redirect /shell -> /shell/{role}
- retire 6 fake contract queries and hooks (grades/homeworks/
schedule/attendance/exams/announcements) and mark widget
placeholders as migrated
- update universal.test.ts to drop retired hook tests
- mark ARCHITECTURE.md P1-2 as completed with acceptance evidence
This commit is contained in:
SpecialX
@@ -2,7 +2,7 @@
|
||||
|
||||
> 版本：3.0
|
||||
> 日期：2026-07-20
|
||||
> 状态：**P0 已完成 + P1-1 已完成（2026-07-22 验收）+ P1 进行中；架构审计完成 + 重设计方案定稿**
|
||||
> 状态：**P0 已完成 + P1-1/P1-2 已完成（2026-07-22 验收）+ P1 进行中；架构审计完成 + 重设计方案定稿**
|
||||
> 本文档地位：**portal-shell 前端工作的唯一权威指导文档**。所有后续 AI/人工在此模块的工作必须先读本文件，以其为准。
|
||||
>
|
||||
> 关联文档（按效力排序）：
|
||||
@@ -757,14 +757,14 @@ export default async function ExamsPage(): Promise<React.ReactElement> {
|
||||
- **P0-7**：`eslint .` → 0 errors, 2 warnings（均在 `__generated__/types.ts` 生成文件）；[eslint.config.js](file:///e:/Desktop/Edu/apps/portal-shell/eslint.config.js) 含 `no-restricted-imports`
|
||||
- **P0-8**：`git status` 干净（commit `cfb7b00`）；`.env.local` 与 `tsconfig.tsbuildinfo` 已在 [.gitignore](file:///e:/Desktop/Edu/apps/portal-shell/.gitignore)
|
||||
|
||||
### P1 · 框架与数据源接通（1–2 周）— 进行中（P1-1 ✅ 2026-07-22 验收）
|
||||
### P1 · 框架与数据源接通（1–2 周）— 进行中（P1-1/P1-2 ✅ 2026-07-22 验收）
|
||||
|
||||
**目标**：AppFrame + 导航 + 真实数据仪表盘 + 页面模板 + MSW + i18n，页面迁移的"流水线"建成。
|
||||
|
||||
| # | 任务 | 验收 | 状态 |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---- |
|
||||
| P1-1 | `src/app/shell/layout.tsx` AppFrame（TopBar 静态挂载 + Sidebar 导航菜单 `navigation.ts` + 权限过滤） | 4 角色各见各菜单；导航项与 route-permissions 表一致（单测） | ✅ |
|
||||
| P1-2 | 仪表盘改接真实查询：`teacherDashboard`/`studentDashboard`/`parentDashboard`/`adminDashboard` + `warnings`/`errorBookStats` | 起全栈，4 角色仪表盘显示真实聚合数据（截图）；widget 假契约查询（grades/homeworks/schedule/attendance/exams/announcements）全部下线或改造 | ⏳ |
|
||||
| P1-2 | 仪表盘改接真实查询：`teacherDashboard`/`studentDashboard`/`parentDashboard`/`adminDashboard` + `warnings`/`errorBookStats` | 起全栈，4 角色仪表盘显示真实聚合数据（截图）；widget 假契约查询（grades/homeworks/schedule/attendance/exams/announcements）全部下线或改造 | ✅ |
|
||||
| P1-3 | 页面模板四件套（list/detail/form/workbench）+ 三态规范 | Storybook 或示例页 4 张（/shell/_dev/templates/*，仅 dev 可见） | ⏳ |
|
||||
| P1-4 | next-intl 接入 + messages 合并迁移 | 切换 locale 页面文案切换（截图）；`useT` 自造函数删除 | ⏳ |
|
||||
| P1-5 | MSW 兜底层（迁移旧 handlers，覆盖 dashboard/users/exams/grades 四域起步） | `NEXT_PUBLIC_MSW=1` 无后端启动，仪表盘 + users 页有数据（截图）；生产构建 bundle 无 mocks | ⏳ |
|
||||
@@ -786,6 +786,21 @@ export default async function ExamsPage(): Promise<React.ReactElement> {
|
||||
- [src/shared/lib/route-permissions.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/lib/route-permissions.ts)：补全 7 个列表页根路由的 EXACT 登记（`/shell/admin/announcements`、`/shell/admin/classes`、`/shell/teacher/exams` 等），与 PREFIX 表互补
|
||||
- **质量校验**：`tsc --noEmit` 通过；`eslint`（5 文件）通过
|
||||
|
||||
**P1-2 验收证据（2026-07-22）**：
|
||||
|
||||
- **假契约查询全部下线**：`grep -rn "useGrades\|useHomework\|useSchedule\|useAttendance\|useExams\|useAnnouncements" src` 无业务调用；6 个 widget（grades/homework/schedule/attendance/exams/announcements）改为"数据源已迁移"占位 Card
|
||||
- **6 个真实聚合查询接入**：
|
||||
- [src/lib/api/operations/dashboard.graphql.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/operations/dashboard.graphql.ts)：`GET_TEACHER_DASHBOARD_DOC` / `GET_STUDENT_DASHBOARD_DOC` / `GET_PARENT_DASHBOARD_DOC` / `GET_ADMIN_DASHBOARD_DOC` / `GET_WARNINGS_DOC` / `GET_ERROR_BOOK_STATS_DOC`，字段全部 snake_case 对齐 data-ana 子图
|
||||
- [src/lib/api/dashboard.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/dashboard.ts)：6 个 hooks（`useTeacherDashboard` / `useStudentDashboard` / `useParentDashboard` / `useAdminDashboard` / `useWarnings` / `useErrorBookStats`）+ 全部领域模型类型（`TeacherDashboard` / `StudentDashboard` / `ParentDashboard` / `AdminDashboard` / `WarningInfo` / `ErrorBookStats` 等）
|
||||
- **4 角色仪表盘页面**（显式路由，先于 catch-all 匹配）：
|
||||
- [src/app/shell/teacher/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/teacher/page.tsx)：StatCard×4（班级总数/学生总数/班级平均分/待批作业）+ DashboardSection×2（班级概况/近期预警）
|
||||
- [src/app/shell/student/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/student/page.tsx)：StatCard×3（平均分/班级排名/待交作业）+ DashboardSection×2（薄弱知识点/近期成绩趋势）
|
||||
- [src/app/shell/parent/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/parent/page.tsx)：StatCard×2（孩子平均分/班级排名）+ DashboardSection×2（薄弱知识点/预警通知）
|
||||
- [src/app/shell/admin/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/admin/page.tsx)：StatCard×4（教师总数/学生总数/班级总数/全校平均分）+ DashboardSection×2（近期预警/AI 用量）
|
||||
- **混合路由模型（V3-A1）**：[src/app/shell/\[\[...route\]\]/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/[[...route]]/page.tsx) 新增 `params` 异步读取 + `/shell` 空路由 `redirect(\`/shell/${role}\`)` 兜底
|
||||
- **三态规范**：4 个仪表盘页统一遵循 loading（StatCard isLoading 骨架）→ error（Card 错误提示）→ success（真实数据）三态
|
||||
- **质量校验**：`tsc --noEmit` 通过；`eslint`（新/改文件）通过；`vitest run` 全量 20 test files / 212 tests 全部通过
|
||||
|
||||
### P2 · 教师域页面（2–3 周，可与 P3 部分并行）
|
||||
|
||||
- 范围：§9.1 全表（~50 页）。顺序建议：exams → homework → grades → lesson-plans → questions/textbooks → attendance/classes/students → diagnostic/error-book/analytics → elective/course-plans → ai-* → practice/schedule-changes/leave。
|
||||
|
||||
Reference in New Issue
Block a user