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

feat(admin-portal): 完成参考项目差距闭环 - 4 批次补齐 + Vitest 测试

Browse Source 
差距分析闭环（workline §7-§8）：
- P0：审计子模块 3 页 + 学校组织 7 页
- P1：系统设置 4 Card + 公告管理 + 邀请码管理
- P2：文件管理 + AI 配置
- P6：5 测试文件 / 69 用例全过

共享基础设施：
- permissions +11 权限点 +14 路由
- view-models +20 接口
- i18n +100 key
- graphql-client +25 operation
- fixtures/handlers +15 mock +20 handler

质量：typecheck + lint 零错误，vitest 69/69 通过，arch.db 已更新
This commit is contained in:
SpecialX
2026-07-13 13:05:29 +08:00
parent fad6e43b47
commit 7cf9aec20e
40 changed files with 6707 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
docs/architecture/issues/worklines/admin-portal_workline.md
View File

@@ -238,9 +238,207 @@ gantt
## §5 风险跟踪
| 风险 | 影响 | 缓解 | 状态 |
| ---- | ---- | ---- | ---- |
| teacher-bff admin namespace schema 缺失（ISSUE-005） | P3+ 全部业务页阻塞 | 提请 coord 仲裁 ai03 在 P3 启动前补齐；P2 用 MSW mock 推进 | ⏳ 待仲裁 |
| 01/02 文档 REST/3003/ai07 与仲裁不一致 | 误导实现 | 已提 7 项异议（ISSUE-001~007），以 contract.md 为修订基准 | ⏳ 待仲裁 |
| Shell 延迟暴露 GraphQLProvider | P2 骨架阻塞 | P2 用独立壳 + mock providers，Shell 就绪后切换 | ⏳ |
| MF SSR 对齐复杂 | Remote SSR 上下文依赖 Shell | 优先 CSR，SSR 仅首屏 dashboard | ⏳ |
| 风险 | 影响 | 缓解 | 状态 |
| ---------------------------------------------------- | --------------------------- | ---------------------------------------------------------- | --------- |
| teacher-bff admin namespace schema 缺失（ISSUE-005） | P3+ 全部业务页阻塞 | 提请 coord 仲裁 ai03 在 P3 启动前补齐；P2 用 MSW mock 推进 | ⏳ 待仲裁 |
| 01/02 文档 REST/3003/ai07 与仲裁不一致 | 误导实现 | 已提 7 项异议（ISSUE-001~007），以 contract.md 为修订基准 | ⏳ 待仲裁 |
| Shell 延迟暴露 GraphQLProvider | P2 骨架阻塞 | P2 用独立壳 + mock providers，Shell 就绪后切换 | ⏳ |
| MF SSR 对齐复杂 | Remote SSR 上下文依赖 Shell | 优先 CSR，SSR 仅首屏 dashboard | ⏳ |
---
## §6 工作进度更新（2026-07-13）
### 6.1 P2-P6 完成状态
| 阶段 | 任务 | 状态 |
| ---- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| P2 | 16.1 MF Remote 骨架 | ✅ 完成 |
| P2 | 16.2 MSW handlers + fixtures + mock JWT | ✅ 完成 |
| P2 | 16.3 接入 Shell 共享 | ✅ 完成 |
| P3 | 16.4 用户管理页 | ✅ 完成 |
| P3 | 16.5 角色权限矩阵 | ✅ 完成 |
| P3 | 16.6 权限点管理 + 视口配置 | ✅ 完成 |
| P4 | 16.7 组织树管理 | ✅ 完成 |
| P4 | 16.8 学校设置 | ✅ 完成 |
| P4 | 16.9 班级/教师/学生全局管理 | ✅ 完成 |
| P5 | 16.10 审计日志页 | ✅ 完成 |
| P5 | 16.11 WebSocket 实时通知 | ✅ 完成 |
| P5 | 16.12 管理仪表盘 | ✅ 完成 |
| P6 | 16.13 A11y WCAG 2.2 AA | ✅ 完成 |
| P6 | 16.14 Web Vitals | ✅ 完成 |
| P6 | 16.15 Vitest 单测 | ✅ 完成（5 测试文件 / 69 用例全过：setup + permissions + i18n + auth + ui + fixtures） |
| P6 | 16.16 Dockerfile + /api/health + /api/ready | ✅ 完成 |
### 6.2 coord 仲裁状态
- ARB-021 全部 7 项 ISSUE 已裁决（ISSUE-001~007），无新仲裁待处理
- ARB-022（api-gateway）影响 admin-portal 路由配置（`/api/admin/*` → teacher-bff），已确认
### 6.3 ISSUE 状态
| ISSUE | 内容 | 状态 |
| --------- | ------------------------------------- | --------- |
| ISSUE-001 | 01/02 模块文档归属错误（ai07 → ai16） | ✅ 已裁决 |
| ISSUE-002 | 01/02 端口错误（3003 → 4003） | ✅ 已裁决 |
| ISSUE-003 | 01/02 通信协议 REST → GraphQL | ✅ 已裁决 |
| ISSUE-004 | 01/02 遗漏审计日志与学校设置 | ✅ 已裁决 |
| ISSUE-005 | teacher-bff admin 命名空间 schema | ✅ 已裁决 |
| ISSUE-006 | 推送策略轮询 → WebSocket | ✅ 已裁决 |
| ISSUE-007 | matrix.md Kafka 直消费方修正 | ✅ 已裁决 |
---
## §7 参考项目差距分析（2026-07-13）
> 参考项目：`e:\Desktop\CICD\`（单体 Next_Edu 教育平台），admin 页面位于 `src/app/(dashboard)/admin/`
### 7.1 参考项目 Admin 页面全览（19 个功能模块）
| # | 参考路由 | 功能 | 领域判定 | Edu admin-portal 现状 |
| --- | ----------------------- | ------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------- |
| 1 | /admin/dashboard | 管理仪表盘 | 管理域 | ✅ 已有 |
| 2 | /admin/users | 用户管理 | 管理域 | ✅ 已有 |
| 3 | /admin/roles | 角色管理 | 管理域 | ✅ 已有 |
| 4 | /admin/permissions | 权限管理 | 管理域 | ✅ 已有 |
| 5 | /admin/audit-logs | 审计日志（含 overview/data-changes/login-logs） | 管理域 | ⚠️ 仅有单一操作日志，缺子模块 |
| 6 | /admin/school | 学校管理（含 schools/grades/departments/academic-year/grades/insights/classes） | 管理域 | ⚠️ 仅有粗粒度 organization，缺子模块 |
| 7 | /admin/settings | 系统设置（安全策略/文件上传/通知/品牌） | 管理域 | ⚠️ 仅有基础学校信息，缺安全/文件/通知/品牌配置 |
| 8 | /admin/announcements | 公告管理 | 管理域 | ❌ 缺失 |
| 9 | /admin/files | 文件管理 | 管理域 | ❌ 缺失 |
| 10 | /admin/invitation-codes | 邀请码管理 | 管理域 | ❌ 缺失 |
| 11 | /admin/ai-settings | AI 配置 | 管理域 | ❌ 缺失 |
| 12 | /admin/attendance | 考勤管理 | 教学域（归 teacher-portal） | N/A |
| 13 | /admin/course-plans | 课程计划 | 教学域（归 teacher-portal） | N/A |
| 14 | /admin/curriculum-map | 课程图谱 | 教学域（归 teacher-portal） | N/A |
| 15 | /admin/elective | 选课管理 | 教学域（归 teacher-portal） | N/A |
| 16 | /admin/error-book | 错题本 | 教学域（归 teacher-portal） | N/A |
| 17 | /admin/lesson-plans | 备课管理 | 教学域（归 teacher-portal） | N/A |
| 18 | /admin/questions | 题库 | 教学域（归 teacher-portal） | N/A |
| 19 | /admin/scheduling | 排课 | 教学域（归 teacher-portal） | N/A |
### 7.2 缺失功能分类与实现优先级
#### P0 — 审计日志子模块增强
现有 `/admin/audit-logs` 仅有单一操作日志页面，需增加：
- `/admin/audit-logs/overview` — 审计总览（操作趋势图、数据变更分布、统计条）
- `/admin/audit-logs/data-changes` — 数据变更日志（按表名/动作筛选 + 分页 + 导出）
- `/admin/audit-logs/login-logs` — 登录日志（signin/signout/signup 成败记录）
#### P0 — 学校组织管理细化
现有 `/admin/organization` 仅有树形组织视图，需增加子页面：
- `/admin/school/schools` — 多学校/校区列表管理
- `/admin/school/grades` — 年级管理（含年级主任分配 + 概览统计）
- `/admin/school/grades/insights` — 年级洞察（全校成绩汇总 + 作业时间线 + 班级排名）
- `/admin/school/departments` — 部门/教研组管理
- `/admin/school/academic-year` — 学年/学期管理
#### P1 — 系统设置增强
现有 `/admin/system` 仅有基础学校信息 + 学期 + 时区/语言，需增加：
- 安全策略 Card（密码复杂度/会话超时/强制改密）
- 文件上传配置 Card（最大体积/允许类型）
- 通知配置 Card（新用户/调课/公告通知开关）
- 品牌配置 Card（Logo/主题色）
#### P1 — 公告管理（新增）
- `/admin/announcements` — 公告发布/归档/置顶、多受众 fan-out 通知、已读回执、状态机（draft→published→archived）
#### P1 — 邀请码管理（新增）
- `/admin/invitation-codes` — 批量生成邀请码、角色/班级/邮箱绑定、事务消费、批次审计
#### P2 — 文件管理（新增）
- `/admin/files` — 全局文件附件治理、跨业务实体筛选、批量删除、存储统计、预览
#### P2 — AI 配置（新增）
- `/admin/ai-settings` — AI Provider 凭据管理、用量仪表盘、public/private provider 分治
### 7.3 实现计划
| 批次 | 内容 | 优先级 |
| ------ | ------------------------------------------------------------------------------------------------------------------------- | ------- |
| 批次 1 | 审计日志子模块（overview/data-changes/login-logs）+ 学校组织管理细化（schools/grades/departments/academic-year/insights） | P0 |
| 批次 2 | 系统设置增强 + 公告管理 + 邀请码管理 | P1 |
| 批次 3 | 文件管理 + AI 配置 | P2 |
| 批次 4 | 测试文件补充（vitest setup + test cases ≥80%） | P6 补齐 |
---
## §8 差距闭环完成总结（2026-07-13）
### 8.1 全部 4 批次已交付
| 批次 | 交付内容 | 状态 |
| ----------------- | ------------------------------------------------------------------------------ | ------- |
| 批次 1（P0） | 审计子模块 3 页 + 学校组织 7 页（含 insights） | ✅ 完成 |
| 批次 2（P1） | 系统设置 4 Card 增强 + 公告管理 + 邀请码管理 | ✅ 完成 |
| 批次 3（P2） | 文件管理 + AI 配置 | ✅ 完成 |
| 批次 4（P6 补齐） | 5 个测试文件（setup + permissions + i18n + auth + ui + fixtures），69 用例全过 | ✅ 完成 |
### 8.2 新增文件清单
**Hooks（7 个）**：
- `src/hooks/use-audit-overview.ts` — 审计总览统计 + 7 日趋势
- `src/hooks/use-data-change-logs.ts` — 数据变更日志 + CSV 导出
- `src/hooks/use-login-logs.ts` — 登录日志查询
- `src/hooks/use-school.ts` — 学校/年级/部门/学年/年级洞察
- `src/hooks/use-announcements.ts` — 公告 CRUD + 状态机
- `src/hooks/use-invitation-codes.ts` — 邀请码批量生成/删除
- `src/hooks/use-files.ts` — 文件列表/统计/批量删除
- `src/hooks/use-ai-settings.ts` — AI Provider + 用量
**Pages（13 个新建 + 2 个修改）**：
- 审计子模块：`audit-logs/overview/page.tsx`、`audit-logs/data-changes/page.tsx`、`audit-logs/login-logs/page.tsx`、`audit-logs/page.tsx`（修改加 Tabs）
- 学校组织：`school/layout.tsx`、`school/page.tsx`（重定向）、`school/schools/page.tsx`、`school/grades/page.tsx`、`school/grades/insights/page.tsx`、`school/departments/page.tsx`、`school/academic-year/page.tsx`
- 公告/邀请码：`announcements/page.tsx`、`invitation-codes/page.tsx`
- 文件/AI：`files/page.tsx`、`ai-settings/page.tsx`
- 系统设置（修改）：`system/page.tsx` 增加 4 Card
**共享组件**：`src/components/audit-logs-tabs.tsx`
**测试文件（5 个）**：
- `src/test/setup.ts` — 全局环境（jest-dom + localStorage + fetch mock）
- `src/lib/permissions.test.ts` — 8 用例
- `src/lib/i18n.test.ts` — 9 用例
- `src/lib/auth.test.ts` — 9 用例
- `src/components/ui.test.tsx` — 27 用例（PaperCard/PageHeader/Button/Input/Select/Badge/Table/EmptyState/LoadingState/ErrorState/Pagination）
- `src/mocks/fixtures.test.ts` — 16 用例
### 8.3 共享基础设施扩展
| 文件 | 增量 |
| -------------------------------- | ------------------------------------ |
| `src/lib/permissions.ts` | 新增 11 个权限点 + 14 条路由权限映射 |
| `src/types/view-models.ts` | 新增 ~20 个 ViewModel 接口 |
| `src/lib/i18n.ts` | 新增 ~100 个 i18n key |
| `src/lib/graphql-client.ts` | 新增 ~25 个 GraphQL operation |
| `src/mocks/fixtures.ts` | 新增 ~15 个 mock 数据集合 |
| `src/mocks/handlers.ts` | 新增 ~20 个 operation handler |
| `src/components/admin-shell.tsx` | NAV_ITEMS 11 → 16 项 |
### 8.4 质量校验
- ✅ `pnpm run typecheck`：零错误
- ✅ `pnpm run lint`：零错误
- ✅ `pnpm run test`：5 文件 / 69 用例全过（11.76s）
- ✅ `pnpm run arch:scan`：arch.db 已更新（TS 20 模块 / 2045 符号）
### 8.5 ARB-021 全 7 项 ISSUE 状态
全部已裁决，无新 coord 仲裁（最新为 ARB-022 §24，属 api-gateway 模块）。
### 8.6 模块完成度
admin-portal 全部 P2-P6 任务（16 项）+ §7 差距分析 4 批次补齐全部完成，模块工作收口。