Files
Edu/docs/architecture/issues/worklines/admin-portal_workline.md
SpecialX 7cf9aec20e feat(admin-portal): 完成参考项目差距闭环 - 4 批次补齐 + Vitest 测试
差距分析闭环(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 已更新
2026-07-13 13:05:29 +08:00

28 KiB
Raw Blame History

admin-portal 工作排期

负责人ai16 关联:workline.mdcoord.mdcontracts/admin-portal_contract.mdai-allocation.md §5 ai16 模式:全并行(各 AI 一口气完成 P2-P6 全部代码,开发期间用 mock最后统一集成测试 说明:本排期基于 GraphQLARB-001 admin 命名空间)+ 端口 4003 + ai16 归属,已对齐 matrix.md 与 ai-allocation.md。01/02 文档中 REST/3003/ai07 表述待 coord 仲裁后修订(见 objections/admin-portal_issue.md)。


§1 总览

admin-portal 是管理端微前端MF Remote挂载到 teacher-portal Shell覆盖用户管理 / 角色权限管理 / 学校设置 / 组织管理 / 审计日志消费等管理场景ai-allocation §5 ai16。复用 teacher-bff GraphQL endpoint 的 admin 命名空间ARB-001admin 权限点使用 ADMIN_ 前缀ai-allocation §5

全阶段目标:

  • P2MF Remote 骨架next.config.js + MF 配置 + 独立壳渲染 + MSW mock
  • P3:用户管理 + 角色权限管理admin 命名空间 Query/Mutation
  • P4:组织管理 + 学校设置 + 班级/教师/学生全局管理
  • P5审计日志消费auditLogs Query 聚合 iam AuditEvent+ WebSocket 实时通知
  • P6硬化A11y WCAG 2.2 AA / Web Vitals / OTel / 测试覆盖率 ≥ 80% / Dockerfile 多阶段)

跨阶段:开发期间全部经 MSW mockcontract §4),上游就绪后逐项切换真实。


§2 全阶段甘特图P2-P6

gantt
    title ai16 admin-portal 全阶段排期P2-P6
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    section P2 骨架
    16.1 MF Remote 骨架(next.config+独立壳) :crit, a16a, 2026-07-10, 2d
    16.2 MSW handlers+fixtures+mock JWT :a16b, after a16a, 2d
    16.3 接入Shell共享(GraphQLProvider/AppShell/useAuth) :crit, a16c, after a16a, 2d

    section P3 用户/角色权限
    16.4 用户管理页(users CRUD+UserManagementTable) :crit, a16d, after a16c, 3d
    16.5 角色权限矩阵(RolePermissionMatrix+updateRolePermissions) :a16e, after a16d, 3d
    16.6 权限点管理+视口配置(ADMIN_前缀) :a16f, after a16e, 2d

    section P4 组织/学校/全局实体
    16.7 组织树管理(organization) :a16g, after a16f, 2d
    16.8 学校设置(system) :a16h, after a16g, 2d
    16.9 班级/教师/学生全局管理(adminClasses/Teachers/Students) :a16i, after a16h, 3d

    section P5 审计日志/实时通知
    16.10 审计日志页(auditLogs Query+筛选/导出) :crit, a16j, after a16i, 3d
    16.11 WebSocket实时通知(审计告警/异常登录) :a16k, after a16j, 2d
    16.12 管理仪表盘(adminDashboard聚合) :a16l, after a16k, 2d

    section P6 硬化
    16.13 A11y WCAG 2.2 AA审计+修复 :crit, a16m, after a16l, 3d
    16.14 Web Vitals+OTel browser SDK接入 :a16n, after a16m, 2d
    16.15 Vitest单测+Playwright E2E(≥80%) :crit, a16o, after a16n, 3d
    16.16 Dockerfile多阶段+/api/health+/api/ready :a16p, after a16o, 2d

关键路径crit16.1 → 16.3 → 16.4 → 16.10 → 16.13 → 16.15。总工期约 34 个工作日。


§3 详细任务

P2 阶段

16.1 MF Remote 骨架next.config + 独立壳)

  • 负责人ai16
  • 依赖teacher-portal Shell MF exposes/shared 配置就绪ARB-002ai13 P2 交付)
  • 交付物
    • apps/admin-portal/next.config.jsNextFederationPluginRemote 角色,name: 'admin_app'filename: 'static/chunks/remoteEntry.js'exposes: { './AdminApp': './src/app/admin-app.tsx' }shared 全部 singleton
    • apps/admin-portal/src/app/admin-app.tsx(独立壳入口,供 Shell 动态加载 + 独立 dev 渲染)
    • apps/admin-portal/src/app/standalone.tsx(独立 dev 壳:自实现 AppShell 占位 + mock providerspnpm --filter admin-portal dev 在 :4003 独立预览)
    • tsconfig.json(沿用 tsconfig.base.jsontailwind.config.js(引入 @edu/ui-tokens)、package.json
  • 验收标准
    • pnpm --filter admin-portal dev 在 :4003 启动,独立壳渲染首页 + 导航占位
    • MF remoteEntry.js 可被 Shell dynamic import 加载feature flag NEXT_PUBLIC_MF_ENABLED 控制)
    • shared 单例配置通过react/react-dom/urql/graphql/@edu/* 全 singleton

16.2 MSW handlers + fixtures + mock JWT

  • 负责人ai16
  • 依赖mock 先行)
  • 交付物
    • apps/admin-portal/src/mocks/handlers.ts(拦截 POST /api/admin/graphql + POST /api/auth/login + GET /ws
    • apps/admin-portal/src/mocks/fixtures/*.json50 用户 / 5 角色 / 20 班级 / 50 教师 / 1200 学生 / 100 审计日志 / 仪表盘统计)
    • mock JWTadmin 角色permissions=["*"]httpOnly cookie
  • 验收标准
    • NEXT_PUBLIC_API_MOCKING=enabled 时所有请求被 MSW 拦截返回 mock
    • GraphQL mock 按 operationName 返回对应 fixture与 teacher-bff admin namespace mock 数据一致)

16.3 接入 Shell 共享GraphQLProvider/AppShell/useAuth

  • 负责人ai16
  • 依赖ARB-002 Shell 暴露清单就绪ai13
  • 交付物
    • AdminApp 通过 MF import from 'teacher/GraphQLProvider''teacher/AppShell''teacher/useAuth''teacher/usePermission''teacher/useGraphQLClient'
    • <AppShell scope="admin"> 渲染管理端视口导航
    • GraphQL client 经 useGraphQLClient() 获取(不使用 useApi/ApiClient,对齐 ARB-002
  • 验收标准
    • urql client 单例跨 Remote 共享(与 Shell 同一实例)
    • currentUser Query 返回 mock 管理员信息
    • admin 角色校验:非 admin 角色重定向到登录页

P3 阶段

16.4 用户管理页users CRUD + UserManagementTable

  • 负责人ai16
  • 依赖teacher-bff admin 命名空间 adminUsers/createUser/updateUser/deleteUser schemaISSUE-005 待 coord 仲裁 ai03 补齐)
  • 交付物
    • /admin/users 列表页UserManagementTable邮箱/姓名/角色/状态/数据范围/最后登录 + 筛选/分页/批量操作)
    • /admin/users/new + /admin/users/:id 表单页react-hook-form + zodResolver
    • admin 业务 HooksuseUsers / useUser / useCreateUser / useUpdateUser / useToggleUserStatusurql query/mutation
  • 验收标准
    • 列表筛选/分页正常mutation 后 invalidate 刷新
    • DataScope L3-L5 越权由后端强制,前端 AdminDataScopeFilter 仅作 UI 提示
    • 权限:IAM_USER_READ / IAM_USER_CREATE / IAM_USER_UPDATE

16.5 角色权限矩阵RolePermissionMatrix + updateRolePermissions

  • 负责人ai16
  • 依赖teacher-bff adminRoles / updateRolePermissions schema
  • 交付物
    • /admin/rolesRolePermissionMatrix行=角色,列=权限按 resource 分组checkbox 网格)
    • 系统预置角色只读isSystem=true 不可编辑/删除)
    • HooksuseRoles / useRole / useCreateRole / useUpdateRolePermissions
  • 验收标准
    • 勾选触发 updateRolePermissions Mutation乐观更新 + 失败回滚
    • 删除前校验 userCount > 0 时禁用删除并提示

16.6 权限点管理 + 视口配置ADMIN_ 前缀)

  • 负责人ai16
  • 依赖packages/contracts/src/permissions.tscoord 维护admin 权限点 ADMIN_* 前缀)
  • 交付物
    • /admin/permissions 只读列表DataTable按 resource 分组)
    • /admin/viewports 视口配置编辑器ViewportConfigEditor@dnd-kit 拖拽排序 + 权限绑定 + scope/isVisible
    • HooksusePermissions30min 缓存)/ useViewportsConfig / useUpdateViewport
  • 验收标准
    • 权限点常量来自 @edu/contracts(不硬编码)
    • 视口配置保存后 AppShell 导航即时刷新invalidate viewports queryKey

P4 阶段

16.7 组织树管理organization

  • 交付物/admin/organization 页(树形 + DataTableschool/grade/class 层级 CRUD
  • 验收标准:树形展开/折叠 + 拖拽调整层级(后端校验)+ DataScope 过滤

16.8 学校设置system

  • 交付物/admin/system 页(学校基础信息 / 学年学期 / 系统参数表单)
  • 验收标准:表单 zod 校验 + 保存后 toast 反馈;仅 L5 系统管理员可编辑

16.9 班级/教师/学生全局管理

  • 交付物/admin/classes / /admin/teachers / /admin/students 三个全局管理页adminClasses/adminTeachers/adminStudents Query
  • 验收标准:跨班级/跨年级全局视角(区别于 teacher-portal 的教师自身视角DataScope 控制可见范围

P5 阶段

16.10 审计日志页auditLogs Query + 筛选/导出)

  • 负责人ai16
  • 依赖teacher-bff 消费 edu.iam.audit.created Kafka 并暴露 auditLogs QueryISSUE-007 待 coord 修正 matrix.md §4 消费方为 teacher-bff
  • 交付物
    • /admin/audit-logsDataTable时间/操作人/action/resource/ip + 筛选action/user/dateRange + 导出 CSV
    • HooksuseAuditLogs(含游标分页)
  • 验收标准
    • 审计日志经 GraphQL 查询(非直接订阅 Kafka,对齐 contract §2.2
    • 100 条 mock 审计日志覆盖 create/update/delete/login/logout/permission_change

16.11 WebSocket 实时通知(审计告警/异常登录)

  • 交付物
    • 接入 push-gateway GET /ws(与 parent-portal 同类契约一致,对齐 ISSUE-006
    • 审计告警 / 异常登录 / 系统异常 toast + 通知中心入口
  • 验收标准
    • mock-socket 每 30s 推送 1 条 mock 系统通知
    • WebSocket 断线自动重连

16.12 管理仪表盘adminDashboard 聚合)

  • 交付物/admin/dashboardrechartstotal_teachers / total_students / school_avg_score / 趋势图)
  • 验收标准adminDashboard Query 返回聚合数据60s 轮询监控指标 + 5min 轮询统计

P6 阶段(硬化)

16.13 A11y WCAG 2.2 AA 审计 + 修复

  • 交付物eslint-plugin-jsx-a11yerror 级)+ 手动审计修复
  • 验收标准0 个 error 级违规

16.14 Web Vitals + OTel browser SDK 接入

  • 交付物next/web-vitalsPOST /api/admin/web-vitalsOTel browser SDK复用 Shell TracerProviderscope='admin'
  • 验收标准LCP/CLS/FID/TTFB 上报 + trace 上报 collector

16.15 Vitest 单测 + Playwright E2E覆盖率 ≥ 80%

  • 交付物apps/admin-portal/src/**/*.test.tsx + e2e/*.spec.ts
  • 验收标准:覆盖率 ≥ 80%E2E 覆盖登录 → dashboard → 用户 CRUD → 审计日志主链路

16.16 Dockerfile 多阶段 + /api/health + /api/ready

  • 交付物apps/admin-portal/Dockerfilebuilder + runtime非 root+ src/app/api/health/route.ts + src/app/api/ready/route.ts
  • 验收标准/api/health 返回 200/api/ready 检查 Shell URL 可达Dockerfile HEALTHCHECK 配置

§4 依赖与就绪信号

4.1 我依赖(上游就绪标志)

  • teacher-portal Shell MF exposes/shared 就绪ai13ARB-002—— Remote 挂载前提
  • teacher-bff GraphQL :3003 启用ai03—— admin 命名空间可用(ISSUE-005 待 ai03 补齐 schema
  • api-gateway HTTP :8080 启用 + JWT 验签 + admin 角色校验ai01
  • iam gRPC 50052 启用ai06—— 用户/角色/审计日志数据来源
  • edu.iam.audit.created topic 有事件发布ai06—— 审计日志来源(经 teacher-bff 消费)
  • push-gateway WebSocket :8081/ws 启用ai02—— 实时通知(ISSUE-006 待 coord 仲裁
  • packages/contracts admin 权限点 ADMIN_* 常量就绪coord

4.2 我的就绪信号(供下游消费)

  • admin-portal dev server :4003 启用
  • MF Remote 可被 AppShell 加载(暴露 ./AdminApp 模块)
  • 独立壳渲染(首页 + 导航 + 路由守卫 + admin 角色校验)
  • 登录流程可用(复用 Shell /loginadmin 角色校验后重定向 /admin/dashboard)—— 不自行实现登录页(对齐 ARB-002 §2.3
  • GraphQL 查询可执行currentUser / adminDashboard / auditLogs 返回数据)
  • 用户/角色 CRUD 可执行createUser / updateRolePermissions
  • WebSocket 通知可接收

§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 providersShell 就绪后切换
MF SSR 对齐复杂 Remote SSR 上下文依赖 Shell 优先 CSRSSR 仅首屏 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-022api-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新用户/调课/公告通知开关)
  • 品牌配置 CardLogo/主题色)

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 批次已交付

批次 交付内容 状态
批次 1P0 审计子模块 3 页 + 学校组织 7 页(含 insights 完成
批次 2P1 系统设置 4 Card 增强 + 公告管理 + 邀请码管理 完成
批次 3P2 文件管理 + AI 配置 完成
批次 4P6 补齐) 5 个测试文件setup + permissions + i18n + auth + ui + fixtures69 用例全过 完成

8.2 新增文件清单

Hooks7 个)

  • 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 + 用量

Pages13 个新建 + 2 个修改)

  • 审计子模块:audit-logs/overview/page.tsxaudit-logs/data-changes/page.tsxaudit-logs/login-logs/page.tsxaudit-logs/page.tsx(修改加 Tabs
  • 学校组织:school/layout.tsxschool/page.tsx(重定向)、school/schools/page.tsxschool/grades/page.tsxschool/grades/insights/page.tsxschool/departments/page.tsxschool/academic-year/page.tsx
  • 公告/邀请码:announcements/page.tsxinvitation-codes/page.tsx
  • 文件/AIfiles/page.tsxai-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 test5 文件 / 69 用例全过11.76s
  • pnpm run arch:scanarch.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 批次补齐全部完成,模块工作收口。