xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
039db5efdd43f864e3ded5e9ef1900f6a549cf16
Edu/apps/portal-shell/docs/needtodo/admin-NeedTodo.md
SpecialX 062d9e9582 feat(portal-shell): 管理域 §9.4 B5 全量迁移（24 + 21 补充批次共 44 页 + 42 features） 
按 ARCHITECTURE.md §9.4 规划口径 + admin-NeedTodo.md §四补充批次完成管理域全量页面迁移：

【§9.4 规划 24 页（B5）】
- users(2) + roles(1) + permissions(1) + audit-logs(4) + invitation-codes(1)
- school(6: redirect/schools/classes/departments/academic-year/grades)
- announcements(1) + files(1) + ai-settings(1) + system(1) + viewports(1)
- students(1) + teachers(1) + organization(1) + plugins(1, config-service)
- 仪表盘已存在（/shell/admin/page.tsx）

【§四补充批次 21 页】
- course-plans(4) + elective(4) + questions(1) + lesson-plans(2) + error-book(1)
- scheduling(3: auto/changes/rules) + attendance(1) + curriculum-map(1)
- announcements 详情/编辑(2) + roles/[id] 详情(1) + users/import(1)

【实现要点】
- 全部使用 ListPageShell + loading/error/empty 三态规范（§11.3 DoD）
- 走 lib/api hooks；未就绪契约走 MSW + @contract-pending 注释（§11.4）
- 文案走 useTranslations（zh-CN + en 两份同步更新）
- 42 个 features/<domain>/transformations.ts 纯函数 + 配套 vitest 单测
- catch 块统一 notify.error；无空 catch；lint:tokens 通过
- 路由全部登记到 route-permissions.ts（39 EXACT + 8 PREFIX）

【验收】
- tsc --noEmit: 0 errors
- ESLint src: 0 errors (4 generated-files warnings, pre-existing)
- lint:tokens: 0 errors
- vitest: 1639/1639 passed (含 23 admin 测试文件 671 用例)
- check:routes: PASS (143 routes, 4 ghost entries pre-existing)
- check:pages: PASS (146 pages)
- check:codegen: PASS
- arch:scan: 24 modules, 8262 symbols

关联：ARCHITECTURE.md §9.4 / §10 P5 / §11.3 DoD / §11.6
2026-07-24 23:07:20 +08:00

48 KiB
Raw Blame History

管理域（Admin）待完成功能分析

参考项目：e:\desktop\CICD\src\app\(dashboard)\admin\（41 个 page.tsx） 当前项目：e:\Desktop\Edu\apps\portal-shell\src\app\shell\admin\（1 个 page.tsx） 规划依据：apps\portal-shell\ARCHITECTURE.md §9.4（管理域 24 页，B5 批次） 分析日期：2026-07-24 分析方式：逐页面对比 CICD 实现 vs portal-shell 实现，逐个读取 CICD page.tsx + ARCH §9.4 契约

〇、方法论与对比基线

  1. CICD 单体（Next.js App Router + Server Actions + Drizzle）作为功能基线，反映"老版单体已实现"的管理员功能完整态。
  2. portal-shell 作为目标态，遵循 ARCH §9.4 的契约与批次规划（B5，24 页）。
  3. CICD admin/layout.tsx 仅为 <>{children}</> passthrough，无独立侧边栏/权限逻辑（权限由各 page.tsx 调 requirePermission 完成）。
  4. ARCH §9.4 规划 24 页 = 1 仪表盘 + 23 管理子页；portal-shell 仅完成 /shell/admin/page.tsx（仪表盘），其余 23 页全部缺失。
  5. CICD 中存在但 ARCH §9.4 未规划的页面（course-plans/curriculum-map/elective/questions/lesson-plans/error-book/scheduling/attendance 等 21 页）：CICD 历史已实现，portal-shell 缺失但不违反 ARCH §9.4；这些页面是教师域在管理员视角的"全局只读 + 跨班聚合"版本，可作为 B5 后期/补充批次候选。
  6. ARCH §9.4 中存在但 CICD 无对应的页面（4 页）：students、teachers、organization、viewports、plugins，属 ARCH 新规划，需在 portal-shell 中独立设计。

一、页面完成度总览

状态 数量 说明
✅ 已完成且功能完整 1 /shell/admin/page.tsx（仪表盘，4 StatCard + 预警 + AI 用量，已接 adminDashboard 真实契约）
❌ 完全缺失（ARCH §9.4 规划内） 23 见 §二，按 ARCH 规划口径的 23 个缺失页面
➕ CICD 已实现但 ARCH §9.4 未规划 21 见 §五，作为补充批次参考
🆕 ARCH §9.4 规划但 CICD 无源 4 students、teachers、organization、viewports（+ plugins 已有契约 ✅）

✅ 已完成且功能完整（1 页）

模块 页面 备注
dashboard /shell/admin/page.tsx 客户端组件，useAdminDashboard hook 接 data-ana adminDashboard 真实契约；4 StatCard（教师/学生/班级/全校平均分）+ 近期预警 + AI 用量；含 loading/error 兜底；引用 ARCH §7.1 / §10 P1-2

二、缺失页面清单（按 ARCH §9.4 规划口径，23 页）

2.1 dashboard 模块（无缺口）

/shell 已落地，对应 ARCH §9.4 第 1 行 admin/dashboard → /shell（动作为 R，契约 ✅ adminDashboard）。

2.2 users 模块（2 页缺失）

2.2.1 /shell/admin/users（用户管理列表）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\users\page.tsx
  • 功能描述：用户列表 + 角色 assignment 入口
    • URL 参数：page、search、role（搜索/角色筛选 + 分页）
    • 并行查询：getAdminUsers({ page, search, role }) + getAdminUserRoles() + getRoles()
    • 渲染 AdminUsersView 客户端组件，传入 users / roleOptions / 分页信息 / assignableRoles
  • 技术栈：Server Component + requirePermission(Permissions.USER_MANAGE) + force-dynamic + getSearchParam 工具 + Drizzle data-access
  • ARCHITECTURE.md 契约：❌ users 列表（B5，未就绪）
  • CICD 关键代码片段： 
    await requirePermission(Permissions.USER_MANAGE);
const [result, roleOptions, roles] = await Promise.all([
  getAdminUsers({ page, search, role }),
  getAdminUserRoles(),
  getRoles(),
]);

2.2.2 /shell/admin/users/import（用户批量导入）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\users\import\page.tsx
  • 功能描述：用户批量导入页面，包含
    • 顶部 UserImportDialog（导入弹窗，触发上传 + Server Action 解析）
    • 操作指引卡片（4 步流程）
    • 注意事项卡片（6 条规则）
    • 模板字段说明表（5 列：name/email/role/phone/inviteCode，标注是否必填）
  • 技术栈：Server Component + requirePermission(Permissions.USER_MANAGE) + UI 基础组件（Card / Table / Button）+ next-intl
  • ARCHITECTURE.md 契约：❌（未单独列，归 users 工单）
  • CICD 关键代码片段：通过 <UserImportDialog /> 客户端组件触发导入流程，模板字段固定 5 列。

2.3 roles + permissions 模块（2 页缺失）

2.3.1 /shell/admin/roles（角色管理列表）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\roles\page.tsx
  • 功能描述：角色列表 + 创建/编辑入口
    • 查询 getRoles() 拉取所有角色
    • 渲染 RoleManagementView 客户端组件（含创建按钮、角色卡片/列表）
  • 技术栈：Server Component + requirePermission(Permissions.ROLE_READ) + Drizzle rbac/data-access
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    await requirePermission(Permissions.ROLE_READ)
const roles = await getRoles()
return <RoleManagementView roles={roles} />

2.3.2 /shell/admin/permissions（权限目录）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\permissions\page.tsx
  • 功能描述：权限目录页（系统所有权限点列表，按模块分组）
    • 查询 getPermissionRoleCounts() 获取每个权限点关联的角色数
    • 渲染 PermissionCatalogView 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.PERMISSION_READ) + Drizzle rbac/data-access-permissions
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    await requirePermission(Permissions.PERMISSION_READ)
const roleCountsByPermission = await getPermissionRoleCounts()
return <PermissionCatalogView roleCountsByPermission={roleCountsByPermission} />

附注：CICD 另有 admin/roles/[id]/page.tsx（角色详情，含 RolePermissionMatrix 权限矩阵 + RoleDetailEditButton），但 ARCH §9.4 仅规划 /shell/admin/roles 一页，未列详情子页。可作 B5 后期补强。

2.4 audit-logs 模块（4 页缺失）

2.4.1 /shell/admin/audit-logs（审计日志列表 + 导出）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\audit-logs\page.tsx
  • 功能描述：审计日志列表 + 多维筛选 + CSV 导出
    • URL 参数：page、module、action、status、userId、startDate、endDate
    • 并行查询：getAuditLogs({...}) + getAuditModuleOptions()
    • AuditLogExportButton 触发 CSV 导出（按筛选条件）
    • SectionErrorBoundary 错误兜底
  • 技术栈：Server Component + requirePermission(Permissions.AUDIT_LOG_READ) + Drizzle audit/data-access + 类型守卫 isValidAuditLogStatus
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    const [result, moduleOptions] = await Promise.all([
  getAuditLogs({ page, module, action, status, userId, startDate, endDate }),
  getAuditModuleOptions(),
]);

2.4.2 /shell/admin/audit-logs/overview（审计概览）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\audit-logs\overview\page.tsx
  • 功能描述：审计概览页（统计/趋势/分布三件套）
    • 并行查询：getAuditOverviewStats() + getAuditTrend(7) + getDataChangeActionStats()
    • AuditServiceProvider 包裹 adminAuditService 注入服务上下文
    • 渲染 AuditOverviewView 客户端组件（统计卡 + 7 天趋势图 + 动作分布饼图）
  • 技术栈：Server Component + requirePermission(Permissions.AUDIT_LOG_READ) + 服务注入模式
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    const [stats, trend, distribution] = await Promise.all([
  getAuditOverviewStats(),
  getAuditTrend(7),
  getDataChangeActionStats(),
]);

2.4.3 /shell/admin/audit-logs/login-logs（登录日志）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\audit-logs\login-logs\page.tsx
  • 功能描述：登录日志列表 + 筛选 + 导出
    • URL 参数：page、action（signin/signout/signup）、status（success/failure）、userId、startDate、endDate
    • 查询 getLoginLogs({...})
    • AuditLogExportButton exportType="login" 触发导出
    • 渲染 LoginLogView 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.AUDIT_LOG_READ) + 类型守卫 isValidLoginLogAction / isValidLoginLogStatus
  • ARCHITECTURE.md 契约：❌（B5）

2.4.4 /shell/admin/audit-logs/data-changes（数据变更日志）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\audit-logs\data-changes\page.tsx
  • 功能描述：数据变更日志列表 + 筛选 + 导出 + 统计
    • URL 参数：page、tableName、action（create/update/delete）、userId、startDate、endDate
    • 并行查询：getDataChangeLogs({...}) + getDataChangeTableOptions() + getDataChangeStats()
    • 渲染 DataChangeLogView 客户端组件（含表选项下拉 + 变更统计卡）
  • 技术栈：Server Component + requirePermission(Permissions.AUDIT_LOG_READ) + 类型守卫 isValidDataChangeAction
  • ARCHITECTURE.md 契约：❌（B5）

2.5 invitation-codes 模块（1 页缺失）

2.5.1 /shell/admin/invitation-codes（邀请码管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\invitation-codes\page.tsx
  • 功能描述：邀请码列表 + 生成 + 删除
    • SSR 查询 listInvitationCodes(200, true)（200 条 + 含已用）
    • 服务端计算 now = new Date().getTime() 传给客户端（避免 Client 端 render 阶段调用 Date.now()，符合 react-hooks/purity 规则）
    • 生成/删除通过 Server Action + router.refresh() 触发更新
    • 渲染 InvitationCodesView 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.USER_MANAGE) + Drizzle invitation-codes/data-access
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    const codes = await listInvitationCodes(200, true)
const now = new Date().getTime()
return <InvitationCodesView initialCodes={codes} now={now} />

2.6 school 模块（6 页缺失）

2.6.1 /shell/admin/school（学校首页，redirect）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\page.tsx
  • 功能描述：纯重定向页 redirect("/admin/school/schools")，无 UI
  • 技术栈：redirect() from next/navigation
  • ARCHITECTURE.md 契约：❌（B5）

2.6.2 /shell/admin/school/schools（学校列表）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\schools\page.tsx
  • 功能描述：学校列表 + CRUD
    • 查询 getSchools()
    • 渲染 SchoolsClient 客户端组件
    • SectionErrorBoundary 错误兜底
  • 技术栈：Server Component + requirePermission(Permissions.SCHOOL_MANAGE) + Drizzle school/data-access
  • ARCHITECTURE.md 契约：❌（B5）

2.6.3 /shell/admin/school/classes（班级管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\classes\page.tsx
  • 功能描述：班级管理 + 跨数据聚合
    • 并行查询：getAdminClasses() + getTeacherOptions() + getSchools() + getGrades()
    • 渲染 AdminClassesClient 客户端组件（含班级 CRUD + 教师/学校/年级下拉）
  • 技术栈：Server Component + requirePermission(Permissions.SCHOOL_MANAGE) + Drizzle classes/data-access + school/data-access
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    const [classes, teachers, schools, grades] = await Promise.all([
  getAdminClasses(),
  getTeacherOptions(),
  getSchools(),
  getGrades(),
]);

注：ARCH §9.4 第 7 行将 admin/classes 单列 1 页（M），与 school/classes 实际同源，建议合并到 /shell/admin/school/classes。

2.6.4 /shell/admin/school/departments（部门管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\departments\page.tsx
  • 功能描述：部门列表 + CRUD
    • 查询 getDepartments()
    • 渲染 DepartmentsClient 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.SCHOOL_MANAGE) + Drizzle
  • ARCHITECTURE.md 契约：❌（B5）

2.6.5 /shell/admin/school/academic-year（学年管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\academic-year\page.tsx
  • 功能描述：学年列表 + CRUD
    • 查询 getAcademicYears()
    • 渲染 AcademicYearClient 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.SCHOOL_MANAGE) + Drizzle
  • ARCHITECTURE.md 契约：❌（B5）

2.6.6 /shell/admin/school/grades（年级管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\school\grades\page.tsx
  • 功能描述：年级列表 + CRUD + 统计
    • 并行查询：getGrades() + getSchools() + getStaffOptions() + getGradeOverviewStats()
    • 渲染 GradesClient 客户端组件（年级 CRUD + 学校/教职工下拉 + 统计概览）
  • 技术栈：Server Component + requirePermission(Permissions.SCHOOL_MANAGE) + Drizzle
  • ARCHITECTURE.md 契约：❌（B5）

附注：CICD 另有 school/grades/insights/page.tsx（年级洞察，含 SchoolWideSummaryCard 全校汇总 + ChipNav 年级筛选 + 作业表 + 班级排名表 + getSchoolWideGradeSummary(ctx.dataScope)），属管理员数据分析视角，ARCH §9.4 未单独规划，可作 B5 后期补强。

2.7 announcements 模块（1 页缺失，ARCH 口径）

2.7.1 /shell/admin/announcements（公告管理列表）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\announcements\page.tsx
  • 功能描述：公告列表 + 状态筛选
    • URL 参数：status（draft/published/archived）
    • 查询 getAdminAnnouncementsPageData(status)（一次性返回 announcements + grades + classes）
    • 渲染 AdminAnnouncementsView 客户端组件
  • 技术栈：Server Component + requirePermission(Permissions.ANNOUNCEMENT_MANAGE) + Drizzle announcements/data-access + 类型守卫 isValidStatus
  • ARCHITECTURE.md 契约：❌（B5）

附注：CICD 另有 announcements/[id]/page.tsx（公告详情，含发布/归档/删除/置顶操作）+ announcements/[id]/edit/page.tsx（编辑表单 AnnouncementForm mode="edit" + grades 关联），ARCH §9.4 仅规划 1 页，建议合并到详情子页或工作流组件。

2.8 files 模块（1 页缺失）

2.8.1 /shell/admin/files（文件管理）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\files\page.tsx
  • 功能描述：文件列表 + 统计
    • 并行查询：getFileAttachmentsWithFilters({ limit: 200 }) + getFileStats()
    • 渲染 AdminFilesView 客户端组件（含统计卡 + 文件列表）
  • 技术栈：Server Component + requirePermission(Permissions.FILE_READ) + Drizzle files/data-access
  • ARCHITECTURE.md 契约：❌（B5）
  • CICD 关键代码片段： 
    const [files, stats] = await Promise.all([
  getFileAttachmentsWithFilters({ limit: 200 }),
  getFileStats(),
]);

2.9 ai-settings 模块（1 页缺失）

2.9.1 /shell/admin/ai-settings（AI 配置）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\ai-settings\page.tsx
  • 功能描述：AI Provider 配置 + Usage 仪表盘（取代旧 /settings?tab=ai 与考试页内嵌 AI 弹窗）
    • 权限：AI_CHAT（普通用户可访问自己的 private provider），管理员额外有 AI_CONFIGURE（管理 public provider 与他人 private provider）
    • 渲染 AiProviderSettingsCard 客户端组件（含 isAdmin 开关）
    • 管理员额外渲染 AiUsageDashboard（用量统计）
  • 技术栈：Server Component + requirePermission(Permissions.AI_CHAT) + 通过 ctx.permissions.includes(Permissions.AI_CONFIGURE) 区分管理员
  • ARCHITECTURE.md 契约：❌（B5）

2.10 system 模块（1 页缺失）

2.10.1 /shell/admin/system（系统设置）

  • CICD 参考实现：e:\desktop\CICD\src\app\(dashboard)\admin\settings\page.tsx
  • 功能描述：系统设置页
    • 渲染 AdminSettingsView 客户端组件（具体配置项由组件内部决定）
  • 技术栈：Server Component + requirePermission(Permissions.SETTINGS_ADMIN) + Drizzle
  • ARCHITECTURE.md 契约：❌（B5，对应 ARCH §9.4 第 13 行 admin/system → /shell/admin/system）

2.11 viewports 模块（1 页缺失，ARCH 新建）

2.11.1 /shell/admin/viewports（视口配置）

  • CICD 参考实现：无（CICD 未实现）
  • 功能描述：对齐 004 §5.4 视口配置（BFF/Service 层 viewport 路由策略可视化）
  • 技术栈：未知，需依据 004 §5.4 设计
  • ARCHITECTURE.md 契约：❌（B5）

2.12 plugins 模块（1 页，契约已就绪 ✅）

2.12.1 /shell/admin/plugins（插件管理）

  • CICD 参考实现：无（CICD 未实现）
  • 功能描述：现有 portal-shell plugin-manager 升级整页
  • 技术栈：依据 portal-shell 已有 plugin-manager 演化
  • ARCHITECTURE.md 契约：✅ config-service（已就绪，可优先实现）

2.13 ARCH §9.4 规划但 CICD 无源的"新建"页面（3 页）

2.13.1 /shell/admin/students（学生管理）

  • CICD 参考实现：无
  • ARCHITECTURE.md 契约：❌（B5）
  • 建议：参照 CICD 中 admin/school/classes 等管理页设计，作学生维度聚合视图。

2.13.2 /shell/admin/teachers（教师管理）

  • CICD 参考实现：无
  • ARCHITECTURE.md 契约：❌（B5）
  • 建议：参照 CICD 中 admin/users + getStaffOptions() 演化。

2.13.3 /shell/admin/organization（组织管理）

  • CICD 参考实现：无
  • ARCHITECTURE.md 契约：❌（B5）
  • 建议：合并 school/departments + school/grades + 师生维度，作组织架构视图。

三、按 ARCH §9.4 模块汇总

模块 ARCH 规划页数 portal-shell 已完成 缺失 契约状态
dashboard 1 1 0 ✅ adminDashboard
users 1（+1 import 子页） 0 1（+1 子页） ❌
roles 1 0 1 ❌
permissions 1 0 1 ❌
audit-logs 4（含 overview/login/data-changes） 0 4 ❌
invitation-codes 1 0 1 ❌
school 6（schools/classes/departments/academic-year/grades + redirect） 0 6 ❌
classes 1（与 school/classes 同源） 0 0（合并到 school） ❌
students 1 0 1 ❌
teachers 1 0 1 ❌
organization 1 0 1 ❌
announcements 1 0 1 ❌
files 1 0 1 ❌
ai-settings 1 0 1 ❌
system 1 0 1 ❌
viewports 1 0 1 ❌
plugins 1 0 1 ✅ config-service
合计 ~24 1 ~23 2 ✅ / ~22 ❌

批次：全部 B5；契约就绪优先级：plugins ✅ > dashboard ✅（已完成）> 其余 ❌ 需 MSW 兜底先行。

四、CICD 中存在但 ARCH §9.4 未规划的管理员页面（21 页，B5 后期候选）

这些页面在 CICD 中属于"管理员视角的跨班聚合/全局只读"功能，是教师域功能在管理员层级的复用。ARCH §9.4 未将其纳入 24 页规划，但作为完整管理员工作台仍具迁移价值。建议作为 B5 末或 B6 补充批次候选，按需取用。

4.1 course-plans 模块（4 页）

CICD 路径 功能 技术栈
admin/course-plans/page.tsx 课程计划列表（admin 全局视角，scope.isAdmin=true） Server Component + requirePermission(Permissions.COURSE_PLAN_READ) + getCoursePlans({ status }, { isAdmin: true })
admin/course-plans/create/page.tsx 创建课程计划 Server Component + requirePermission(Permissions.COURSE_PLAN_MANAGE) + 并行查询 classes/subjects/teachers/academicYears + CoursePlanForm mode="create"
admin/course-plans/[id]/page.tsx 课程计划详情 Server Component + getCoursePlanById(id, { userId, isAdmin: true }) + CoursePlanDetail
admin/course-plans/[id]/edit/page.tsx 编辑课程计划 Server Component + requirePermission(Permissions.COURSE_PLAN_MANAGE) + CoursePlanForm mode="edit"

4.2 curriculum-map 模块（1 页）

CICD 路径 功能 技术栈
admin/curriculum-map/page.tsx 课程地图（标准覆盖热图 + 5 张统计卡：教师/教案/已发布/已提交/已关联标准数） Server Component + requirePermission(Permissions.LESSON_PLAN_READ) + getStandardsCoverageHeatmapAction() + getGlobalLessonPlanStatsAction() + CurriculumMapView

4.3 elective 模块（4 页）

CICD 路径 功能 技术栈
admin/elective/page.tsx 选修课列表（StatsCardsLoader + CourseListLoader 双 Suspense 流式） Server Component + requirePermission(Permissions.ELECTIVE_READ) + ElectivePageLayout
admin/elective/create/page.tsx 创建选修课 Server Component + getSubjectOptions()/getGrades()/getStaffOptions() + ElectiveCourseForm mode="create"
admin/elective/[id]/page.tsx 选修课详情（含 getCourseSelections 选课记录） Server Component + requirePermission(Permissions.ELECTIVE_READ) + ElectiveCourseDetail
admin/elective/[id]/edit/page.tsx 编辑选修课 Server Component + ElectiveCourseForm mode="edit"

4.4 questions 模块（1 页）

CICD 路径 功能 技术栈
admin/questions/page.tsx 题库管理（筛选 + 导入导出 + 创建） Server Component + requirePermission(Permissions.QUESTION_READ) + getQuestions({...}) + QuestionFilters（Suspense） + QuestionBankResultsClient + ImportExportButtons + CreateQuestionButton

4.5 lesson-plans 模块（2 页）

CICD 路径 功能 技术栈
admin/lesson-plans/page.tsx 教案列表（4 统计卡：总数/已发布/草稿/已归档 + LessonPlanList viewMode="admin" + LessonPlanProviderSetup 注入 ADMIN_ROLE_CONFIG） Server Component + requirePermission(Permissions.LESSON_PLAN_READ) + getLessonPlans({}, ctx.dataScope, ctx.userId) + getLessonPlanStats()
admin/lesson-plans/[planId]/view/page.tsx 教案只读视图（含 textbook/chapter 标题解析） Server Component + getLessonPlanById(planId, ctx.userId) + getTextbookById/getChaptersByTextbookId 并行 + LessonPlanReadonlyView

4.6 error-book 模块（1 页）

CICD 路径 功能 技术栈
admin/error-book/page.tsx 错题本分析（5 统计卡 + 学科 Tab + 学科分布图 + 章节/知识点薄弱度并排 + Top 50 学生 + Top 10 高频错题；限 500 学生 + DataScope 校验 type === "all"） Server Component + requirePermission(Permissions.ERROR_BOOK_ANALYTICS_READ) + 多 data-access 并行 + SubjectTabs/StatsGrid/SubjectDistributionChart/ChapterWeaknessChart/KnowledgePointWeaknessChart/GroupedStudentErrorTable/TopWrongQuestions + WidgetBoundary

4.7 scheduling 模块（3 页）

CICD 路径 功能 技术栈
admin/scheduling/auto/page.tsx 自动排课（AutoSchedulePanel + 跳转 rules 配置入口） Server Component + requirePermission(Permissions.SCHEDULE_AUTO) + getAdminClassesForScheduling()
admin/scheduling/changes/page.tsx 排课变更审批（变更列表 + 冲突检测 + 课表网格） Server Component + requirePermission(Permissions.SCHEDULE_ADJUST) + 并行 getAdminClassesForScheduling/getScheduleChanges/getScheduleEntriesForAdmin + ScheduleChangeList canApprove + ScheduleConflictsView + ScheduleGridView
admin/scheduling/rules/page.tsx 排课规则配置 Server Component + requirePermission(Permissions.SCHEDULE_ADJUST) + getSchedulingRules() + SchedulingRulesForm

4.8 attendance 模块（1 页）

CICD 路径 功能 技术栈
admin/attendance/page.tsx 考勤管理（7 统计卡 + 班级对比卡 + 考勤-成绩关联分析卡 + 筛选器） Server Component + requirePermission(Permissions.ATTENDANCE_READ) + 并行 getAttendanceRecords/getAttendanceStats/getGrades/getClassComparison/getAttendanceGradeCorrelation + AdminAttendanceFilters（含 class/status/date 筛选）

附注：CICD admin/attendance/admin-attendance-filters.tsx 是页内私有 Client Component，封装 FilterBar + Select + Input，使用 ATTENDANCE_STATUS_OPTIONS 常量。迁移时此类"页内 filters 组件"模式应保持。

4.9 announcements 详情/编辑（2 页）

CICD 路径 功能 技术栈
admin/announcements/[id]/page.tsx 公告详情（AnnouncementDetail canManage + 跳转 edit + 发布/归档/删除/置顶操作入口） Server Component + requirePermission(Permissions.ANNOUNCEMENT_MANAGE) + getAdminAnnouncementDetailPageData(id) + AnnouncementsServiceProvider
admin/announcements/[id]/edit/page.tsx 公告编辑（AnnouncementForm mode="edit" + grades 关联） Server Component + requirePermission(Permissions.ANNOUNCEMENT_MANAGE) + getEditAnnouncementPageData(id)

4.10 users/import 子页（1 页）

已在 §2.2.2 列入 ARCH 规划口径（与 users 工单合并），此处不重复。

4.11 roles/[id] 详情（1 页）

CICD 路径 功能 技术栈
admin/roles/[id]/page.tsx 角色详情（RolePermissionMatrix 权限矩阵 + RoleDetailEditButton + admin 角色锁定提示卡） Server Component + requirePermission(Permissions.ROLE_READ) + getRoleById(id) + notFound() 兜底 + admin 角色强制锁定（isLocked）

4.12 school/grades/insights（1 页）

已在 §2.6 附注中提及，不重复。

五、迁移注意事项

5.1 架构迁移要点

  1. 管理员权限校验：所有 23 缺失页面均需 requirePermission(Permissions.XXX) 在 Server Component 入口校验。CICD 模式可直接复用，但需对齐 portal-shell 的 auth-guard（004 §5 鉴权链路）。
  2. DataScope 上下文：school/grades/insights、error-book、attendance 等页面依赖 ctx.dataScope（all / class_taught / class_members / children），portal-shell 需在 BFF 层补齐数据范围上下文。
  3. Server Action + router.refresh 模式：invitation-codes、announcements/[id]/edit 等使用此模式，portal-shell 需保持等价机制（BFF API + 客户端 refetch）。
  4. 导出功能：audit-logs 三页 + questions 导入导出按钮，需后端提供 CSV 导出端点。
  5. 服务注入：audit-logs/overview 使用 AuditServiceProvider + adminAuditService 模式，portal-shell 应在 BFF/Service 层保留服务抽象。

5.2 模块复杂度风险

模块 风险点 缓解建议
audit-logs（4 页） 审计核心，多维筛选 + 导出 + 概览统计 + 数据变更统计 后端契约工单优先；前端可 MSW 先行 4 页 UI
school（6 页） 体系复杂，6 子页 + 跨表关联（schools/classes/departments/grades/academic-year/staff） 按 schools → grades → classes → departments → academic-year 顺序迁移；insights 作 B5 末
scheduling（3 页，§四补充批次） 涉及自动排课算法 + 冲突检测 + 审批流 算法侧需独立服务/工单；前端先做 changes 审批流，auto/rules 后置
error-book（§四补充批次） 5 统计卡 + 4 图表 + Top 50 学生 + Top 10 错题；限 500 学生性能保护 复用教师域 error-book 组件，仅换 data-access 为 admin scope；图表组件应已存在
attendance（§四补充批次） 7 统计 + 班级对比 + 考勤-成绩关联分析 后端需提供 getClassComparison + getAttendanceGradeCorrelation 两个分析端点
curriculum-map（§四补充批次） 标准覆盖热图 + 5 张统计卡 + getStandardsCoverageHeatmapAction Server Action 依赖 lesson-preparation 模块的 actions-analytics，需先迁移教师域 lesson-plans
ai-settings 双权限（AI_CHAT + AI_CONFIGURE）+ Provider 配置 + Usage 仪表盘 后端需提供 provider CRUD + usage 聚合端点

5.3 契约就绪优先级建议

按 ARCH §9.4 节奏原则（契约就绪页先行，❌ 页用 MSW 先上 UI）：

  1. 优先级 1（契约 ✅，可立即实现真实查询）：
    • /shell/admin/plugins（✅ config-service）
    • /shell/admin（已完成）
  2. 优先级 2（高价值 + 中等复杂度，需后端契约工单）：
    • /shell/admin/users + /shell/admin/users/import（用户管理 + 批量导入）
    • /shell/admin/roles + /shell/admin/permissions（RBAC 核心）
    • /shell/admin/invitation-codes（与 users 共享 USER_MANAGE 权限）
    • /shell/admin/announcements（公告管理）
    • /shell/admin/files（文件管理）
  3. 优先级 3（高复杂度，建议 MSW 先行）：
    • /shell/admin/audit-logs/*（4 页，审计核心，多维筛选 + 导出）
    • /shell/admin/school/*（6 页，体系复杂）
  4. 优先级 4（ARCH 新建，需独立设计）：
    • /shell/admin/students、/shell/admin/teachers、/shell/admin/organization、/shell/admin/viewports、/shell/admin/system
  5. 优先级 5（§四补充批次，B5 末或 B6）：
    • course-plans/curriculum-map/elective/questions/lesson-plans/error-book/scheduling/attendance 共 16 页

5.4 CICD admin/layout.tsx 迁移说明

CICD admin/layout.tsx 仅 return <>{children}</>，无独立侧边栏/权限逻辑（侧边栏由 (dashboard)/layout.tsx 统一处理，权限由各 page 调 requirePermission）。

portal-shell 同样无需在 shell/admin/layout.tsx 实现额外逻辑，保持 passthrough 即可；侧边栏与权限校验由 shell/layout.tsx 与各 page.tsx 分担。

六、附录：CICD admin/page.tsx 完整清单（41 个）

# CICD 路径 ARCH §9.4 归属 缺失/已有
1 admin/dashboard/page.tsx §9.4 第 1 行 ✅ portal-shell /shell/admin/page.tsx 已完成
2 admin/users/page.tsx §9.4 第 2 行 ❌ 缺失
3 admin/users/import/page.tsx §9.4 第 2 行 ❌（合并） 缺失
4 admin/roles/page.tsx §9.4 第 3 行 ❌ 缺失
5 admin/roles/[id]/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
6 admin/permissions/page.tsx §9.4 第 3 行 ❌ 缺失
7 admin/audit-logs/page.tsx §9.4 第 4 行 ❌ 缺失
8 admin/audit-logs/overview/page.tsx §9.4 第 4 行 ❌ 缺失
9 admin/audit-logs/login-logs/page.tsx §9.4 第 4 行 ❌ 缺失
10 admin/audit-logs/data-changes/page.tsx §9.4 第 4 行 ❌ 缺失
11 admin/invitation-codes/page.tsx §9.4 第 5 行 ❌ 缺失
12 admin/school/page.tsx（redirect） §9.4 第 6 行 ❌ 缺失
13 admin/school/schools/page.tsx §9.4 第 6 行 ❌ 缺失
14 admin/school/classes/page.tsx §9.4 第 6/7 行 ❌ 缺失
15 admin/school/departments/page.tsx §9.4 第 6 行 ❌ 缺失
16 admin/school/academic-year/page.tsx §9.4 第 6 行 ❌ 缺失
17 admin/school/grades/page.tsx §9.4 第 6 行 ❌ 缺失
18 admin/school/grades/insights/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
19 admin/announcements/page.tsx §9.4 第 10 行 ❌ 缺失
20 admin/announcements/[id]/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
21 admin/announcements/[id]/edit/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
22 admin/files/page.tsx §9.4 第 11 行 ❌ 缺失
23 admin/ai-settings/page.tsx §9.4 第 12 行 ❌ 缺失
24 admin/settings/page.tsx §9.4 第 13 行 ❌（→ /system） 缺失
25 admin/course-plans/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
26 admin/course-plans/create/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
27 admin/course-plans/[id]/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
28 admin/course-plans/[id]/edit/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
29 admin/curriculum-map/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
30 admin/elective/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
31 admin/elective/create/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
32 admin/elective/[id]/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
33 admin/elective/[id]/edit/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
34 admin/questions/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
35 admin/lesson-plans/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
36 admin/lesson-plans/[planId]/view/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
37 admin/error-book/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
38 admin/scheduling/auto/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
39 admin/scheduling/changes/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
40 admin/scheduling/rules/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）
41 admin/attendance/page.tsx §四补充批次 缺失（非 ARCH §9.4 规划）

ARCH §9.4 规划但 CICD 无源（5 页）：

# ARCH 目标路由 说明 契约
A /shell/admin/students ARCH 新建，CICD 无 ❌
B /shell/admin/teachers ARCH 新建，CICD 无 ❌
C /shell/admin/organization ARCH 新建，CICD 无 ❌
D /shell/admin/viewports ARCH 新建，对齐 004 §5.4 ❌
E /shell/admin/plugins ARCH 新建（plugin-manager 升级） ✅ config-service

七、关键结论

  1. portal-shell 管理域完成度：1/24 ≈ 4%（仅仪表盘），是各角色域中完成度最低的。
  2. 缺失 23 页全部属 B5 批次，节奏紧迫，建议立即启动契约工单。
  3. 契约就绪仅 2 个：adminDashboard（已用）+ config-service（plugins，未实现）。
  4. CICD 有 21 页 ARCH §9.4 未规划，是教师域功能在管理员视角的复用，建议作为 B5 末或 B6 补充批次，按需取用。
  5. 高复杂度模块：audit-logs（4 页 + 导出）、school（6 子页 + 跨表关联）、scheduling（算法）、error-book（多图表聚合）。
  6. CICD admin/layout.tsx 无独立逻辑，portal-shell 保持 passthrough 即可，侧边栏与权限由 shell/layout + 各 page.tsx 分担。
  7. 建议实施顺序：契约就绪的 plugins → 高价值低复杂度的 users/roles/permissions/invitation-codes/announcements/files/ai-settings → 高复杂度的 audit-logs/* + school/* → ARCH 新建的 students/teachers/organization/viewports/system → §四补充批次 16 页。
Reference in New Issue View Git Blame Copy Permalink