xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3511910d1f2e1fcf50210edfa9ec030df985a2e
Edu/docs/architecture/issues/worklines/admin-portal_workline.md
SpecialX 02d09c47fa feat: auto committed
2026-07-10 15:05:39 +08:00

13 KiB
Raw Blame History

admin-portal 工作排期

负责人：ai16 关联：workline.md、coord.md、contracts/admin-portal_contract.md、ai-allocation.md §5 ai16 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试） 说明：本排期基于 GraphQL（ARB-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-001），admin 权限点使用 ADMIN_ 前缀（ai-allocation §5）。

全阶段目标：

  • P2：MF 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 mock（见 contract §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

关键路径（crit）：16.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-002，ai13 P2 交付）
  • 交付物：
    • apps/admin-portal/next.config.js（NextFederationPlugin，Remote 角色，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 providers，供 pnpm --filter admin-portal dev 在 :4003 独立预览）
    • tsconfig.json（沿用 tsconfig.base.json）、tailwind.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/*.json（50 用户 / 5 角色 / 20 班级 / 50 教师 / 1200 学生 / 100 审计日志 / 仪表盘统计）
    • mock JWT（admin 角色，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 schema（ISSUE-005 待 coord 仲裁 ai03 补齐）
  • 交付物：
    • /admin/users 列表页（UserManagementTable：邮箱/姓名/角色/状态/数据范围/最后登录 + 筛选/分页/批量操作）
    • /admin/users/new + /admin/users/:id 表单页（react-hook-form + zodResolver）
    • admin 业务 Hooks：useUsers / useUser / useCreateUser / useUpdateUser / useToggleUserStatus（urql 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/roles 页（RolePermissionMatrix：行=角色，列=权限按 resource 分组；checkbox 网格）
    • 系统预置角色只读（isSystem=true 不可编辑/删除）
    • Hooks：useRoles / useRole / useCreateRole / useUpdateRolePermissions
  • 验收标准：
    • 勾选触发 updateRolePermissions Mutation，乐观更新 + 失败回滚
    • 删除前校验 userCount > 0 时禁用删除并提示

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

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

P4 阶段

16.7 组织树管理（organization）

  • 交付物：/admin/organization 页（树形 + DataTable，school/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 Query（ISSUE-007 待 coord 修正 matrix.md §4 消费方为 teacher-bff）
  • 交付物：
    • /admin/audit-logs 页（DataTable：时间/操作人/action/resource/ip + 筛选：action/user/dateRange + 导出 CSV）
    • Hooks：useAuditLogs（含游标分页）
  • 验收标准：
    • 审计日志经 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/dashboard 页（recharts：total_teachers / total_students / school_avg_score / 趋势图）
  • 验收标准：adminDashboard Query 返回聚合数据；60s 轮询监控指标 + 5min 轮询统计

P6 阶段（硬化）

16.13 A11y WCAG 2.2 AA 审计 + 修复

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

16.14 Web Vitals + OTel browser SDK 接入

  • 交付物：next/web-vitals → POST /api/admin/web-vitals；OTel browser SDK（复用 Shell TracerProvider，scope='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/Dockerfile（builder + 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 就绪（ai13，ARB-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 /login，admin 角色校验后重定向 /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 providers，Shell 就绪后切换 ⏳
MF SSR 对齐复杂 Remote SSR 上下文依赖 Shell 优先 CSR，SSR 仅首屏 dashboard ⏳
Reference in New Issue View Git Blame Copy Permalink