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

feat(portal-shell): 学生域全页面迁移与规范合规修复

Browse Source 
- 学生域 32 页全量迁移(含作答/自动保存/提交/诊断)

- 补齐 4 个 MSW mock 缺口,修 diagnostic case 名

- 修 4 处 Tailwind 任意值;新增共享组件与路由
This commit is contained in:
SpecialX
2026-08-31 11:25:21 +08:00
parent 039db5efdd
commit 04b7a40bdc
493 changed files with 70985 additions and 2112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

880
apps/portal-shell/docs/needtodo/admin-NeedTodo.md
View File

@@ -1,582 +1,486 @@
# 管理域（Admin）待完成功能分析
# 管理域（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 契约
> 当前项目：`e:\Desktop\Edu\apps\portal-shell\src\app\shell\admin\`（49 个 page.tsx）
> 规划依据：`apps\portal-shell\ARCHITECTURE.md` §9.4（管理域 24 页顶层入口，B5 批次）
> 核查日期：2026-08-04
> 核查方式：逐个读取 49 个 page.tsx + 44 个 features/admin/*-client.tsx + lib/api/admin.ts(973 行) + lib/api/admin-p5.ts(3371 行) + mocks/graphql-data.ts(9867 行)，结合 ARCH §9.4 契约判断实现完整性
---
## 〇、方法论与对比基线
1. CICD 单体（Next.js App Router + Server Actions + Drizzle）作为**功能基线**，反映"老版单体已实现"的管理员功能完整态。
2. portal-shell 作为**目标态**，遵循 ARCH §9.4 的契约与批次规划（B5，24 页）。
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 中独立设计。
4. ARCH §9.4 规划 24 页顶层入口 = 1 仪表盘 + 23 管理子页；portal-shell 在此基础上补充了详情/编辑/创建子页与 redirect 入口，实际落地 **49 个 page.tsx**。
5. 判断口径（任务约束）：
- **✅ 完整实现**：page.tsx 引入 `@/features/admin/*-client.tsx` 并渲染（client 组件承担业务逻辑，调用 lib/api hooks，处理三态）；或 page.tsx 为有意的 `redirect()` 入口跳转。
- **🟡 占位空态**：page.tsx 仅用 ListPageShell/FormPageShell/DetailPageShell 直接渲染空态，无 children 业务内容。
- **❌ 缺失**：page.tsx 文件不存在。
6. 核查覆盖维度：page.tsx 入口 + features/admin/*-client.tsx 业务组件 + lib/api hooks + mocks/graphql-data.ts 兜底数据，四层齐全方视为完整实现。
---
## 一、页面完成度总览
| 状态 | 数量 | 说明 |
| --------------------------------- | ---- | ---------------------------------------------------------------------------------------------- |
| ✅ 已完成且功能完整 | 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` 已有契约 ✅） |
| 状态 | 数量 | 说明 |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ 完整实现（业务页） | 46 | page.tsx 引入对应 `features/admin/*-client.tsx` 并在 `<Suspense>` 中渲染；client 组件调用 lib/api hooks，处理 loading/error/empty 三态 |
| ✅ 完整实现（重定向） | 3 | page.tsx 为有意的 `redirect()` 入口跳转（classes / scheduling / school 三个模块根路径） |
| 🟡 占位空态 | 0 | 无 |
| ❌ 缺失 | 0 | 无 |
| **合计** | **49** | **管理员域 49/49 page.tsx 全部落地** |
### ✅ 已完成且功能完整（1 页）
### ✅ 完整实现（46 业务页 + 3 重定向页 = 49 页）
| 模块 | 页面 | 备注 |
| --------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dashboard | `/shell/admin/page.tsx` | 客户端组件，`useAdminDashboard` hook 接 data-ana `adminDashboard` 真实契约；4 StatCard（教师/学生/班级/全校平均分）+ 近期预警 + AI 用量；含 loading/error 兜底；引用 ARCH §7.1 / §10 P1-2 |
所有 49 个 page.tsx 均已存在且非占位。46 个业务页统一采用 Server Component 入口 + Suspense 边界 + Client Component 业务的架构；3 个重定向页为有意的入口跳转，避免空白入口。
业务页架构样例（以 `/shell/admin/ai-settings/page.tsx` 为例）：
```tsx
import { Suspense } from "react";
import { AiSettingsClient } from "@/features/admin/ai-settings/ai-settings-client";
import { ListPageSkeleton } from "@/shared/components/page-templates";
export default function AiSettingsPage(): React.ReactElement {
return (
<Suspense fallback={<ListPageSkeleton rows={5} />}>
<AiSettingsClient />
</Suspense>
);
}
```
重定向页架构样例（以 `/shell/admin/school/page.tsx` 为例）：
```tsx
import { redirect } from "next/navigation";
export default function SchoolAdminIndexPage(): never {
redirect("/shell/admin/school/schools");
}
```
---
## 二、缺失页面清单（按 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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
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 关键代码片段**：
```ts
const [files, stats] = await Promise.all([
getFileAttachmentsWithFilters({ limit: 200 }),
getFileStats(),
]);
```
## 二、已实现页面清单（按模块分组，49 页）
### 2.9 ai-settings 模块（1 页缺失）
> 状态标识：✅ 完整业务实现 / ↪️ 重定向入口 / 🟡 占位 / ❌ 缺失
> 三态规范：所有 ✅ 业务页的 client 组件均处理 loading（Skeleton）/ error（局部降级）/ empty（EmptyState）三态（ARCH §11.3 DoD）
#### 2.9.1 `/shell/admin/ai-settings`（AI 配置）
### 2.1 dashboard 模块（1 页）
- **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 页缺失）
| 页面路径 | 状态 | 实现要点 |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/shell/admin` | ✅ | "use client" + useAdminDashboard() hook 接 data-ana adminDashboard 真实契约；4 StatCard（教师/学生/班级/全校平均分）+ 近期预警 + AI 用量；含 loading/error 兜底；引用 ARCH §7.1 / §10 P1-2 |
#### 2.10.1 `/shell/admin/system`（系统设置）
### 2.2 ai-settings 模块（1 页）
- **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`）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------ | ---- | ---------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| /shell/admin/ai-settings | ✅ | ai-settings-client.tsx | 522 | useAiProviders / useCreateAiProvider / useUpdateAiProvider / useDeleteAiProvider / useTestAiProvider / useAiUsageDashboard | ❌ schema 未就绪 → MSW 兜底 |
### 2.11 viewports 模块（1 页缺失，ARCH 新建）
### 2.3 announcements 模块（3 页）
#### 2.11.1 `/shell/admin/viewports`（视口配置）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------------------ | ---- | ------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/announcements | ✅ | announcements-list-client.tsx | 469 | useAdminAnnouncements / useDeleteAnnouncement / useArchiveAnnouncement / usePinAnnouncement / usePublishAnnouncement | ❌ → MSW 兜底 |
| /shell/admin/announcements/[id] | ✅ | announcement-detail-client.tsx | 289 | useAdminAnnouncement | ❌ → MSW 兜底 |
| /shell/admin/announcements/[id]/edit | ✅ | announcement-edit-client.tsx | 266 | useAdminAnnouncement / useUpdateAnnouncement | ❌ → MSW 兜底 |
- **CICD 参考实现**：**无**（CICD 未实现）
- **功能描述**：对齐 004 §5.4 视口配置（BFF/Service 层 viewport 路由策略可视化）
- **技术栈**：未知，需依据 004 §5.4 设计
- **ARCHITECTURE.md 契约**：❌（B5）
### 2.4 attendance 模块（1 页）
### 2.12 plugins 模块（1 页，契约已就绪 ✅）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------- | ---- | --------------------------- | ---- | ----------------------------------------------------------------------------------- | ------------- |
| /shell/admin/attendance | ✅ | admin-attendance-client.tsx | 340 | useAdminAttendanceStats / useAdminAttendanceRecords / useAttendanceGradeCorrelation | ❌ → MSW 兜底 |
#### 2.12.1 `/shell/admin/plugins`（插件管理）
### 2.5 audit-logs 模块（4 页）
- **CICD 参考实现**：**无**（CICD 未实现）
- **功能描述**：现有 portal-shell `plugin-manager` 升级整页
- **技术栈**：依据 portal-shell 已有 plugin-manager 演化
- **ARCHITECTURE.md 契约**：✅ `config-service`（已就绪，可优先实现）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------------------ | ---- | -------------------------- | ---- | ----------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/audit-logs | ✅ | audit-logs-list-client.tsx | 461 | useAuditLogs / useAuditModuleOptions / useExportAuditLogs | ❌ → MSW 兜底 |
| /shell/admin/audit-logs/data-changes | ✅ | data-changes-client.tsx | 472 | useDataChangeLogs / useDataChangeTableOptions / useDataChangeStats / useExportDataChanges | ❌ → MSW 兜底 |
| /shell/admin/audit-logs/login-logs | ✅ | login-logs-client.tsx | 325 | useLoginLogs / useExportLoginLogs | ❌ → MSW 兜底 |
| /shell/admin/audit-logs/overview | ✅ | audit-overview-client.tsx | 386 | useAuditOverviewStats / useAuditTrend / useDataChangeActionStats | ❌ → MSW 兜底 |
### 2.13 ARCH §9.4 规划但 CICD 无源的"新建"页面（3 页）
### 2.6 classes 模块（1 页，重定向）
#### 2.13.1 `/shell/admin/students`（学生管理）
| 页面路径 | 状态 | 实现要点 |
| -------------------- | ---- | ----------------------------------------------------------------------------------------------- |
| /shell/admin/classes | ↪️ | redirect("/shell/admin/school/classes")：班级管理归属于 school 限界上下文，避免空白入口重复实现 |
- **CICD 参考实现**：**无**
- **ARCHITECTURE.md 契约**：❌（B5）
- **建议**：参照 CICD 中 `admin/school/classes` 等管理页设计，作学生维度聚合视图。
### 2.7 course-plans 模块（4 页）
#### 2.13.2 `/shell/admin/teachers`（教师管理）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------------------- | ---- | ----------------------------- | ---- | ------------------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/course-plans | ✅ | course-plans-list-client.tsx | 339 | useAdminCoursePlans | ❌ → MSW 兜底 |
| /shell/admin/course-plans/create | ✅ | course-plan-create-client.tsx | 415 | useAdminClasses / useCreateCoursePlanItem 系列 | ❌ → MSW 兜底 |
| /shell/admin/course-plans/[id] | ✅ | course-plan-detail-client.tsx | 644 | useAdminCoursePlan / useUpdateCoursePlanItem / useReorderCoursePlanItems / useBulkToggleCoursePlanItems | ❌ → MSW 兜底 |
| /shell/admin/course-plans/[id]/edit | ✅ | course-plan-edit-client.tsx | 562 | useAdminCoursePlan / useUpdateCoursePlanItem 系列 | ❌ → MSW 兜底 |
- **CICD 参考实现**：**无**
- **ARCHITECTURE.md 契约**：❌（B5）
- **建议**：参照 CICD 中 `admin/users` + `getStaffOptions()` 演化。
### 2.8 curriculum-map 模块（1 页）
#### 2.13.3 `/shell/admin/organization`（组织管理）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| --------------------------- | ---- | ------------------------- | ---- | ------------------------------------------------------ | ------------- |
| /shell/admin/curriculum-map | ✅ | curriculum-map-client.tsx | 256 | useStandardsCoverageHeatmap / useGlobalLessonPlanStats | ❌ → MSW 兜底 |
- **CICD 参考实现**：**无**
- **ARCHITECTURE.md 契约**：❌（B5）
- **建议**：合并 `school/departments` + `school/grades` + 师生维度，作组织架构视图。
### 2.9 elective 模块（4 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------------- | ---- | -------------------------- | ---- | ----------------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/elective | ✅ | elective-list-client.tsx | 545 | useAdminElectives / useGetElectiveOverviewStats / useDeleteElective | ❌ → MSW 兜底 |
| /shell/admin/elective/create | ✅ | elective-create-client.tsx | 381 | useAdminCreateElective | ❌ → MSW 兜底 |
| /shell/admin/elective/[id] | ✅ | elective-detail-client.tsx | 385 | useAdminElective | ❌ → MSW 兜底 |
| /shell/admin/elective/[id]/edit | ✅ | elective-edit-client.tsx | 464 | useAdminUpdateElective / useOpenElectiveSelection / useCloseElectiveSelection / useRunElectiveLottery | ❌ → MSW 兜底 |
### 2.10 error-book 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------- | ---- | --------------------- | ---- | ---------------------------------------------- | ------------- |
| /shell/admin/error-book | ✅ | error-book-client.tsx | 738 | useAdminErrorBookStats / useExportErrorBookCsv | ❌ → MSW 兜底 |
### 2.11 files 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------ | ---- | --------------------- | ---- | ----------------------------------------------------------------------- | ------------- |
| /shell/admin/files | ✅ | files-list-client.tsx | 377 | useFileAttachments / useFileStats / useUploadFile / useBatchDeleteFiles | ❌ → MSW 兜底 |
### 2.12 invitation-codes 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------------- | ---- | -------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| /shell/admin/invitation-codes | ✅ | invitation-codes-list-client.tsx | 542 | useInvitationCodes / useCreateInvitationCode / useRevokeInvitationCode / useGenerateInvitationCodes / useDeleteInvitationCodes | ❌ → MSW 兜底 |
### 2.13 lesson-plans 模块（2 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| --------------------------------------- | ---- | ---------------------------- | ---- | -------------------------------------------- | ------------- |
| /shell/admin/lesson-plans | ✅ | lesson-plans-list-client.tsx | 489 | useAdminLessonPlans | ❌ → MSW 兜底 |
| /shell/admin/lesson-plans/[planId]/view | ✅ | lesson-plan-view-client.tsx | 205 | useAdminLessonPlan / useSoftDeleteLessonPlan | ❌ → MSW 兜底 |
### 2.14 organization 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------- | ---- | ---------------------------- | ---- | ------------------- | ------------- |
| /shell/admin/organization | ✅ | organization-tree-client.tsx | 245 | useOrganizationTree | ❌ → MSW 兜底 |
### 2.15 permissions 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------ | ---- | --------------------------- | ---- | ---------------------------------------- | ------------- |
| /shell/admin/permissions | ✅ | permissions-list-client.tsx | 216 | usePermissions / usePermissionRoleCounts | ❌ → MSW 兜底 |
### 2.16 plugins 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| -------------------- | ---- | ------------------ | ---- | ------------------------------------------- | ---------------------------------- |
| /shell/admin/plugins | ✅ | plugins-client.tsx | 402 | usePluginRegistry / useUpdatePluginRegistry | ✅ schema 已就绪（config-service） |
### 2.17 questions 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ---------------------- | ---- | ------------------------- | ---- | ------------------------------------ | ------------- |
| /shell/admin/questions | ✅ | questions-list-client.tsx | 537 | useAdminQuestions / useAdminQuestion | ❌ → MSW 兜底 |
### 2.18 roles 模块（2 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------- | ---- | ---------------------- | ---- | --------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/roles | ✅ | roles-list-client.tsx | 411 | useRoles / useCreateRole / useDeleteRole / useToggleRoleEnabled | ❌ → MSW 兜底 |
| /shell/admin/roles/[id] | ✅ | role-detail-client.tsx | 165 | useRole / useUpdateRole / useDeleteRole / useRolePermissions / useUpdateRolePermissionActions | ❌ → MSW 兜底 |
### 2.19 scheduling 模块（4 页，含 1 重定向）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------------- | ---- | ----------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------ | ------------- |
| /shell/admin/scheduling | ↪️ | redirect("/shell/admin/scheduling/changes")：避免空白入口，默认进入变更审批页 | — | — | — |
| /shell/admin/scheduling/auto | ✅ | auto-schedule-client.tsx | 270 | useAutoSchedule | ❌ → MSW 兜底 |
| /shell/admin/scheduling/changes | ✅ | schedule-changes-client.tsx | 471 | useAdminScheduleChanges / useAdminScheduleEntries / useApproveScheduleChange / useRejectScheduleChange | ❌ → MSW 兜底 |
| /shell/admin/scheduling/rules | ✅ | scheduling-rules-client.tsx | 401 | useAdminSchedulingRules / useUpdateSchedulingRules | ❌ → MSW 兜底 |
### 2.20 school 模块（7 页，含 1 重定向）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/school | ↪️ | redirect("/shell/admin/school/schools")：避免空白入口，默认进入学校列表页 | — | — | — |
| /shell/admin/school/academic-year | ✅ | academic-year-client.tsx | 601 | useAcademicYears / useCreateAcademicYear / useUpdateAcademicYear / useDeleteAcademicYear | ❌ → MSW 兜底 |
| /shell/admin/school/classes | ✅ | admin-classes-client.tsx | 598 | useAdminClasses / useTeacherOptions / useStaffOptions / useCreateAdminClass / useUpdateAdminClass / useDeleteAdminClass | ❌ → MSW 兜底 |
| /shell/admin/school/departments | ✅ | departments-client.tsx | 444 | useDepartments / useCreateDepartment / useUpdateDepartment / useDeleteDepartment | ❌ → MSW 兜底 |
| /shell/admin/school/grades | ✅ | grades-client.tsx | 688 | useGrades / useGradeOverviewStats / useAdminCreateGrade / useUpdateGrade / useDeleteGrade | ❌ → MSW 兜底 |
| /shell/admin/school/grades/insights | ✅ | grade-insights-client.tsx | 495 | useGradeOverviewStats 系列 | ❌ → MSW 兜底 |
| /shell/admin/school/schools | ✅ | schools-client.tsx | 509 | useSchools / useCreateSchool / useAdminUpdateSchool / useDeleteSchool | ❌ → MSW 兜底 |
### 2.21 students 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| --------------------- | ---- | ------------------------ | ---- | ---------------- | ------------- |
| /shell/admin/students | ✅ | students-list-client.tsx | 387 | useAdminStudents | ❌ → MSW 兜底 |
### 2.22 system 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------- | ---- | -------------------------- | ---- | ------------------------------------------- | ------------- |
| /shell/admin/system | ✅ | system-settings-client.tsx | 566 | useSystemSettings / useUpdateSystemSettings | ❌ → MSW 兜底 |
### 2.23 teachers 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| --------------------- | ---- | ------------------------ | ---- | ---------------- | ------------- |
| /shell/admin/teachers | ✅ | teachers-list-client.tsx | 269 | useAdminTeachers | ❌ → MSW 兜底 |
### 2.24 users 模块（3 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ------------------------- | ---- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------- | ------------- |
| /shell/admin/users | ✅ | users-list-client.tsx | 538 | useUsers / useUpdateUserStatus / useUpdateUserRole / useDeleteUser / useAssignUserRoles / useUpdateUser | ❌ → MSW 兜底 |
| /shell/admin/users/import | ✅ | users-import-client.tsx | 414 | useImportUsers | ❌ → MSW 兜底 |
| /shell/admin/users/[id] | ✅ | user-detail-client.tsx | 404 | useUser / useUpdateUser / useAssignUserRoles | ❌ → MSW 兜底 |
### 2.25 viewports 模块（1 页）
| 页面路径 | 状态 | client 组件 | 行数 | lib/api hooks | 契约状态 |
| ---------------------- | ---- | -------------------- | ---- | -------------------------------- | ------------- |
| /shell/admin/viewports | ✅ | viewports-client.tsx | 383 | useViewports / useUpdateViewport | ❌ → MSW 兜底 |
---
## 三、按 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 ❌** |
| 模块 | ARCH §9.4 规划页数 | portal-shell 已实现 | 缺失 | 契约状态 |
| ---------------- | --------------------------------- | --------------------- | ----- | ---------------------------- |
| dashboard | 1 | 1 | 0 | ✅ adminDashboard |
| users | 1（+1 import +1 详情） | 3 | 0 | ❌ → MSW 兜底 |
| roles | 1（+1 详情） | 2 | 0 | ❌ → MSW 兜底 |
| permissions | 1 | 1 | 0 | ❌ → MSW 兜底 |
| audit-logs | 4 | 4 | 0 | ❌ → MSW 兜底 |
| invitation-codes | 1 | 1 | 0 | ❌ → MSW 兜底 |
| school | 6（+redirect） | 7（+grades/insights） | 0 | ❌ → MSW 兜底 |
| classes | 1（与 school/classes 同源） | 1（redirect） | 0 | — |
| students | 1 | 1 | 0 | ❌ → MSW 兜底 |
| teachers | 1 | 1 | 0 | ❌ → MSW 兜底 |
| organization | 1 | 1 | 0 | ❌ → MSW 兜底 |
| announcements | 1（+2 子页） | 3 | 0 | ❌ → MSW 兜底 |
| files | 1 | 1 | 0 | ❌ → MSW 兜底 |
| ai-settings | 1 | 1 | 0 | ❌ → MSW 兜底 |
| system | 1 | 1 | 0 | ❌ → MSW 兜底 |
| viewports | 1 | 1 | 0 | ❌ → MSW 兜底 |
| plugins | 1 | 1 | 0 | ✅ config-service |
| course-plans | §四补充（4 页） | 4 | 0 | ❌ → MSW 兜底 |
| curriculum-map | §四补充（1 页） | 1 | 0 | ❌ → MSW 兜底 |
| elective | §四补充（4 页） | 4 | 0 | ❌ → MSW 兜底 |
| questions | §四补充（1 页） | 1 | 0 | ❌ → MSW 兜底 |
| lesson-plans | §四补充（2 页） | 2 | 0 | ❌ → MSW 兜底 |
| error-book | §四补充（1 页） | 1 | 0 | ❌ → MSW 兜底 |
| scheduling | §四补充（3+redirect） | 4 | 0 | ❌ → MSW 兜底 |
| attendance | §四补充（1 页） | 1 | 0 | ❌ → MSW 兜底 |
| **合计** | **~24（顶层）+ ~25（子页/补充）** | **49** | **0** | **2 ✅ / 47 ❌（MSW 兜底）** |
> **批次**：全部 B5；契约就绪优先级：`plugins` ✅ > `dashboard` ✅（已完成）> 其余 ❌ 需 MSW 兜底先行。
> **批次**：全部 B5（含 §四补充批次，已全部落地）；契约就绪：plugins ✅ + dashboard ✅；其余 47 页 schema 未就绪，前端用 MSW 兜底先行（@contract-pending 标注）。
---
## 四、CICD 中存在但 ARCH §9.4 未规划的管理员页面（21 页，B5 后期候选）
## 四、CICD 中存在但 ARCH §9.4 未规划的管理员页面（已全部实现）
> 这些页面在 CICD 中属于"管理员视角的跨班聚合/全局只读"功能，是教师域功能在管理员层级的复用。ARCH §9.4 未将其纳入 24 页规划，但作为完整管理员工作台仍具迁移价值。建议作为 B5 末或 B6 补充批次候选，按需取用。
> 这些页面在 CICD 中属于"管理员视角的跨班聚合/全局只读"功能，是教师域功能在管理员层级的复用。ARCH §9.4 未将其纳入 24 页顶层规划，但 portal-shell 已全部实现（含详情/编辑/创建子页），共 25 页。
### 4.1 course-plans 模块（4 页）
### 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"` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ----------------------------------- | ---- | ----------------------------- | ---- |
| /shell/admin/course-plans | ✅ | course-plans-list-client.tsx | 339 |
| /shell/admin/course-plans/create | ✅ | course-plan-create-client.tsx | 415 |
| /shell/admin/course-plans/[id] | ✅ | course-plan-detail-client.tsx | 644 |
| /shell/admin/course-plans/[id]/edit | ✅ | course-plan-edit-client.tsx | 562 |
### 4.2 curriculum-map 模块（1 页）
### 4.2 curriculum-map 模块（1 页，已实现）
| CICD 路径 | 功能 | 技术栈 |
| ------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `admin/curriculum-map/page.tsx` | 课程地图（标准覆盖热图 + 5 张统计卡：教师/教案/已发布/已提交/已关联标准数） | Server Component + `requirePermission(Permissions.LESSON_PLAN_READ)` + `getStandardsCoverageHeatmapAction()` + `getGlobalLessonPlanStatsAction()` + `CurriculumMapView` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| --------------------------- | ---- | ------------------------- | ---- |
| /shell/admin/curriculum-map | ✅ | curriculum-map-client.tsx | 256 |
### 4.3 elective 模块（4 页）
### 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"` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ------------------------------- | ---- | -------------------------- | ---- |
| /shell/admin/elective | ✅ | elective-list-client.tsx | 545 |
| /shell/admin/elective/create | ✅ | elective-create-client.tsx | 381 |
| /shell/admin/elective/[id] | ✅ | elective-detail-client.tsx | 385 |
| /shell/admin/elective/[id]/edit | ✅ | elective-edit-client.tsx | 464 |
### 4.4 questions 模块（1 页）
### 4.4 questions 模块（1 页，已实现）
| CICD 路径 | 功能 | 技术栈 |
| -------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `admin/questions/page.tsx` | 题库管理（筛选 + 导入导出 + 创建） | Server Component + `requirePermission(Permissions.QUESTION_READ)` + `getQuestions({...})` + `QuestionFilters`（Suspense） + `QuestionBankResultsClient` + `ImportExportButtons` + `CreateQuestionButton` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ---------------------- | ---- | ------------------------- | ---- |
| /shell/admin/questions | ✅ | questions-list-client.tsx | 537 |
### 4.5 lesson-plans 模块（2 页）
### 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` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| --------------------------------------- | ---- | ---------------------------- | ---- |
| /shell/admin/lesson-plans | ✅ | lesson-plans-list-client.tsx | 489 |
| /shell/admin/lesson-plans/[planId]/view | ✅ | lesson-plan-view-client.tsx | 205 |
### 4.6 error-book 模块（1 页）
### 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` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ----------------------- | ---- | --------------------- | ---- |
| /shell/admin/error-book | ✅ | error-book-client.tsx | 738 |
### 4.7 scheduling 模块（3 页）
### 4.7 scheduling 模块（3 页 + redirect，已实现）
| 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` |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ------------------------------- | ---- | ------------------------------ | ---- |
| /shell/admin/scheduling | ↪️ | redirect → /scheduling/changes | — |
| /shell/admin/scheduling/auto | ✅ | auto-schedule-client.tsx | 270 |
| /shell/admin/scheduling/changes | ✅ | schedule-changes-client.tsx | 471 |
| /shell/admin/scheduling/rules | ✅ | scheduling-rules-client.tsx | 401 |
### 4.8 attendance 模块（1 页）
### 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 筛选） |
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ----------------------- | ---- | --------------------------- | ---- |
| /shell/admin/attendance | ✅ | admin-attendance-client.tsx | 340 |
> **附注**：CICD `admin/attendance/admin-attendance-filters.tsx` 是页内私有 Client Component，封装 `FilterBar + Select + Input`，使用 `ATTENDANCE_STATUS_OPTIONS` 常量。迁移时此类"页内 filters 组件"模式应保持。
### 4.9 announcements 详情/编辑（2 页，已实现）
### 4.9 announcements 详情/编辑（2 页）
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ------------------------------------ | ---- | ------------------------------ | ---- |
| /shell/admin/announcements/[id] | ✅ | announcement-detail-client.tsx | 289 |
| /shell/admin/announcements/[id]/edit | ✅ | announcement-edit-client.tsx | 266 |
| 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 + users/[id] 子页（2 页，已实现）
### 4.10 users/import 子页（1 页）
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ------------------------- | ---- | ----------------------- | ---- |
| /shell/admin/users/import | ✅ | users-import-client.tsx | 414 |
| /shell/admin/users/[id] | ✅ | user-detail-client.tsx | 404 |
已在 §2.2.2 列入 ARCH 规划口径（与 `users` 工单合并），此处不重复。
### 4.11 roles/[id] 详情（1 页，已实现）
### 4.11 roles/[id] 详情（1 页）
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ----------------------- | ---- | ---------------------- | ---- |
| /shell/admin/roles/[id] | ✅ | role-detail-client.tsx | 165 |
| 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 页，已实现）
### 4.12 school/grades/insights（1 页）
已在 §2.6 附注中提及，不重复。
| portal-shell 路径 | 状态 | client 组件 | 行数 |
| ----------------------------------- | ---- | ------------------------- | ---- |
| /shell/admin/school/grades/insights | ✅ | grade-insights-client.tsx | 495 |
---
## 五、迁移注意事项
### 5.1 架构迁移要点
### 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 层保留服务抽象。
1. **管理员权限校验**：portal-shell 采用 Client Component + BFF 模式，权限校验由 route-permissions.ts 在路由层 EXACT/PREFIX 表登记（如 /shell/admin/* → ["admin"]），与 CICD 的 Server Component + requirePermission 模式不同但等价。
2. **DataScope 上下文**：portal-shell 在 BFF 层注入数据范围上下文，client 组件通过 lib/api hooks 消费，无需 page.tsx 显式传递。
3. **Server Action + router.refresh 模式**：portal-shell 改用 Apollo Client mutation + useQuery refetch / notify 通知，等价于 CICD 的 Server Action + router.refresh()。
4. **导出功能**：audit-logs 三页 + error-book 的 CSV 导出，已通过 useExportAuditLogs / useExportLoginLogs / useExportDataChanges / useExportErrorBookCsv hooks 封装，等待后端契约就绪后接真实端点。
5. **服务注入**：audit-logs/overview 在 portal-shell 中改为 client 组件直接调用 useAuditOverviewStats / useAuditTrend / useDataChangeActionStats 三个 hook 并行查询，等价于 CICD 的 AuditServiceProvider + adminAuditService 模式。
### 5.2 模块复杂度风险
### 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 聚合端点 |
| 模块 | 风险点 | 当前缓解 | 待办 |
| ---------------------- | --------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| audit-logs（4 页） | 审计核心，多维筛选 + 导出 + 概览统计 + 数据变更统计 | 前端 4 页 UI 已完成（共 1644 行 client 代码），MSW 兜底 | 后端契约工单：auditLogs / loginLogs / dataChangeLogs / auditOverviewStats / 导出端点 |
| school（7 页） | 体系复杂，6 业务子页 + 1 redirect，跨表关联 | 前端 7 页 UI 已完成（共 3335 行 client 代码），MSW 兜底 | 后端契约工单：schools / departments / academicYears / grades / adminClasses / gradeOverviewStats |
| scheduling（4 页） | 自动排课算法 + 冲突检测 + 审批流 | 前端 4 页 UI 已完成（共 1142 行 client 代码），MSW 兜底 | 后端契约工单：autoSchedule / scheduleChanges / scheduleEntries / schedulingRules + 排课算法服务 |
| error-book（1 页） | 5 统计卡 + 4 图表 + Top 50 学生 + Top 10 错题 | 前端 1 页 UI 已完成（738 行 client 代码，最复杂单页），MSW 兜底 | 后端契约工单：adminErrorBookStats + CSV 导出端点 |
| attendance（1 页） | 7 统计 + 班级对比 + 考勤-成绩关联分析 | 前端 1 页 UI 已完成（340 行 client 代码），MSW 兜底 | 后端契约工单：adminAttendanceStats / adminAttendanceRecords / attendanceGradeCorrelation |
| curriculum-map（1 页） | 标准覆盖热图 + 5 张统计卡 | 前端 1 页 UI 已完成（256 行 client 代码），MSW 兜底 | 后端契约工单：standardsCoverageHeatmap / globalLessonPlanStats |
| ai-settings（1 页） | 双权限 + Provider 配置 + Usage 仪表盘 | 前端 1 页 UI 已完成（522 行 client 代码），MSW 兜底 | 后端契约工单：aiProviders / aiUsageDashboard + Provider CRUD 端点 |
| users（3 页） | 用户列表 + 批量导入 + 详情，关联角色分配 | 前端 3 页 UI 已完成（共 1356 行 client 代码），MSW 兜底 | 后端契约工单：users 列表 + importUsers mutation |
| course-plans（4 页） | 课程计划 CRUD + 子项 reorder + 批量切换 | 前端 4 页 UI 已完成（共 1960 行 client 代码），MSW 兜底 | 后端契约工单：adminCoursePlans / adminCoursePlan + 子项 CRUD mutations |
| elective（4 页） | 选修课 CRUD + 抽签 + 选课开关 | 前端 4 页 UI 已完成（共 1775 行 client 代码），MSW 兜底 | 后端契约工单：adminElectives / adminElective + 抽签 mutation |
### 5.3 契约就绪优先级建议
### 5.3 契约就绪优先级（用于后端工单排期）
按 ARCH §9.4 节奏原则（契约就绪页先行，❌ 页用 MSW 先上 UI）：
前端 49 页已全部落地，瓶颈在后端 GraphQL schema 就绪。按业务价值与依赖关系排期：
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 页
1. **优先级 1（契约 ✅，已完成真实查询）**：/shell/admin（adminDashboard ✅）+ /shell/admin/plugins（config-service ✅）
2. **优先级 2（高价值 RBAC 核心，需后端契约工单）**：users（3 页）+ roles（2 页）+ permissions（1 页）+ invitation-codes（1 页）= 7 页；后端契约：users / roles / permissions / permissionRoleCounts / invitationCodes + 相关 mutations
3. **优先级 3（高频运营功能，需后端契约工单）**：announcements（3 页）+ files（1 页）+ ai-settings（1 页）+ system（1 页）= 6 页；后端契约：adminAnnouncements / fileAttachments / aiProviders / aiUsageDashboard / systemSettings
4. **优先级 4（审计与组织管理，高复杂度）**：audit-logs（4 页）+ school（7 页）+ organization（1 页）+ students（1 页）+ teachers（1 页）+ viewports（1 页）= 15 页；后端契约：审计 4 类查询 + 导出端点；school 6 类实体 CRUD；organizationTree / adminStudents / adminTeachers / viewports
5. **优先级 5（§四补充批次，教师域聚合视图）**：course-plans（4 页）+ curriculum-map（1 页）+ elective（4 页）+ questions（1 页）+ lesson-plans（2 页）+ error-book（1 页）+ scheduling（4 页）+ attendance（1 页）= 18 页；后端契约：均为教师域聚合查询在 admin scope 下的复用
### 5.4 CICD admin/layout.tsx 迁移说明
CICD `admin/layout.tsx` 仅 `return <>{children}</>`，**无独立侧边栏/权限逻辑**（侧边栏由 `(dashboard)/layout.tsx` 统一处理，权限由各 page 调 `requirePermission`）。
CICD admin/layout.tsx 仅 return <>{children}</>，**无独立侧边栏/权限逻辑**（侧边栏由 (dashboard)/layout.tsx 统一处理，权限由各 page 调 requirePermission）。
portal-shell 同样无需在 `shell/admin/layout.tsx` 实现额外逻辑，保持 passthrough 即可；侧边栏与权限校验由 `shell/layout.tsx` 与各 page.tsx 分担。
portal-shell 同样无需在 shell/admin/layout.tsx 实现额外逻辑，保持 passthrough 即可；侧边栏与权限校验由 shell/layout.tsx 与 route-permissions.ts 分担。
### 5.5 三层支撑完整度核查
| 支撑层 | 文件 | 行数 | 覆盖情况 |
| --------------- | ---------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page.tsx 入口 | src/app/shell/admin/**/page.tsx | 49 文件 | 49/49 全部存在，46 业务页 + 3 redirect 页 |
| client 业务组件 | src/features/admin/**/*-client.tsx | 44 文件 | 44/44 全部实现，165-738 行/文件，均调用 lib/api hooks，处理三态 |
| lib/api hooks | src/lib/api/admin.ts + admin-p5.ts | 973 + 3371 = 4344 行 | 全覆盖：users/roles/permissions/audit-logs/invitation-codes/school/announcements/files/ai-settings/system/viewports/students/teachers/organization/course-plans/curriculum-map/elective/questions/lesson-plans/error-book/scheduling/attendance/plugins |
| mocks 兜底数据 | src/mocks/graphql-data.ts | 9867 行 | 全覆盖：mockAdminDashboard / mockUsers / mockAdminPermissions / mockSchools / mockDepartments / mockAcademicYears / mockAdminGrades / mockAdminClasses / mockAdminAnnouncements / mockInvitationCodes / mockFileAttachments / mockAiProviders / mockSystemSettings / mockViewports / mockAdminStudents / mockAdminTeachers / mockOrganizationTree / mockAdminCoursePlans / mockAdminLessonPlans / mockAdminElectives / mockAdminQuestions / mockAdminScheduleChanges / mockSchedulingRules / mockAdminAttendanceRecords / mockLoginLogs / mockDataChangeLogs 等 |
---
## 六、附录：CICD admin/page.tsx 完整清单（41 个）
## 六、附录：CICD admin/page.tsx 完整清单（41 个）+ ARCH 新建（5 个）= 46 项对照
| # | 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 规划） |
| # | CICD 路径 | ARCH §9.4 归属 | portal-shell 状态（2026-08-04） |
| --- | ----------------------------------------- | ----------------------------- | --------------------------------------------------------------- |
| 1 | admin/dashboard/page.tsx | §9.4 第 1 行 ✅ | ✅ /shell/admin/page.tsx（真实契约 adminDashboard） |
| 2 | admin/users/page.tsx | §9.4 第 2 行 ❌ | ✅ /shell/admin/users/page.tsx（MSW 兜底） |
| 3 | admin/users/import/page.tsx | §9.4 第 2 行 ❌（合并） | ✅ /shell/admin/users/import/page.tsx（MSW 兜底） |
| 4 | admin/roles/page.tsx | §9.4 第 3 行 ❌ | ✅ /shell/admin/roles/page.tsx（MSW 兜底） |
| 5 | admin/roles/[id]/page.tsx | §四补充批次 | ✅ /shell/admin/roles/[id]/page.tsx（MSW 兜底） |
| 6 | admin/permissions/page.tsx | §9.4 第 3 行 ❌ | ✅ /shell/admin/permissions/page.tsx（MSW 兜底） |
| 7 | admin/audit-logs/page.tsx | §9.4 第 4 行 ❌ | ✅ /shell/admin/audit-logs/page.tsx（MSW 兜底） |
| 8 | admin/audit-logs/overview/page.tsx | §9.4 第 4 行 ❌ | ✅ /shell/admin/audit-logs/overview/page.tsx（MSW 兜底） |
| 9 | admin/audit-logs/login-logs/page.tsx | §9.4 第 4 行 ❌ | ✅ /shell/admin/audit-logs/login-logs/page.tsx（MSW 兜底） |
| 10 | admin/audit-logs/data-changes/page.tsx | §9.4 第 4 行 ❌ | ✅ /shell/admin/audit-logs/data-changes/page.tsx（MSW 兜底） |
| 11 | admin/invitation-codes/page.tsx | §9.4 第 5 行 ❌ | ✅ /shell/admin/invitation-codes/page.tsx（MSW 兜底） |
| 12 | admin/school/page.tsx（redirect） | §9.4 第 6 行 ❌ | ↪️ /shell/admin/school/page.tsx → /school/schools |
| 13 | admin/school/schools/page.tsx | §9.4 第 6 行 ❌ | ✅ /shell/admin/school/schools/page.tsx（MSW 兜底） |
| 14 | admin/school/classes/page.tsx | §9.4 第 6/7 行 ❌ | ✅ /shell/admin/school/classes/page.tsx（MSW 兜底） |
| 15 | admin/school/departments/page.tsx | §9.4 第 6 行 ❌ | ✅ /shell/admin/school/departments/page.tsx（MSW 兜底） |
| 16 | admin/school/academic-year/page.tsx | §9.4 第 6 行 ❌ | ✅ /shell/admin/school/academic-year/page.tsx（MSW 兜底） |
| 17 | admin/school/grades/page.tsx | §9.4 第 6 行 ❌ | ✅ /shell/admin/school/grades/page.tsx（MSW 兜底） |
| 18 | admin/school/grades/insights/page.tsx | §四补充批次 | ✅ /shell/admin/school/grades/insights/page.tsx（MSW 兜底） |
| 19 | admin/announcements/page.tsx | §9.4 第 10 行 ❌ | ✅ /shell/admin/announcements/page.tsx（MSW 兜底） |
| 20 | admin/announcements/[id]/page.tsx | §四补充批次 | ✅ /shell/admin/announcements/[id]/page.tsx（MSW 兜底） |
| 21 | admin/announcements/[id]/edit/page.tsx | §四补充批次 | ✅ /shell/admin/announcements/[id]/edit/page.tsx（MSW 兜底） |
| 22 | admin/files/page.tsx | §9.4 第 11 行 ❌ | ✅ /shell/admin/files/page.tsx（MSW 兜底） |
| 23 | admin/ai-settings/page.tsx | §9.4 第 12 行 ❌ | ✅ /shell/admin/ai-settings/page.tsx（MSW 兜底） |
| 24 | admin/settings/page.tsx | §9.4 第 13 行 ❌（→ /system） | ✅ /shell/admin/system/page.tsx（MSW 兜底） |
| 25 | admin/course-plans/page.tsx | §四补充批次 | ✅ /shell/admin/course-plans/page.tsx（MSW 兜底） |
| 26 | admin/course-plans/create/page.tsx | §四补充批次 | ✅ /shell/admin/course-plans/create/page.tsx（MSW 兜底） |
| 27 | admin/course-plans/[id]/page.tsx | §四补充批次 | ✅ /shell/admin/course-plans/[id]/page.tsx（MSW 兜底） |
| 28 | admin/course-plans/[id]/edit/page.tsx | §四补充批次 | ✅ /shell/admin/course-plans/[id]/edit/page.tsx（MSW 兜底） |
| 29 | admin/curriculum-map/page.tsx | §四补充批次 | ✅ /shell/admin/curriculum-map/page.tsx（MSW 兜底） |
| 30 | admin/elective/page.tsx | §四补充批次 | ✅ /shell/admin/elective/page.tsx（MSW 兜底） |
| 31 | admin/elective/create/page.tsx | §四补充批次 | ✅ /shell/admin/elective/create/page.tsx（MSW 兜底） |
| 32 | admin/elective/[id]/page.tsx | §四补充批次 | ✅ /shell/admin/elective/[id]/page.tsx（MSW 兜底） |
| 33 | admin/elective/[id]/edit/page.tsx | §四补充批次 | ✅ /shell/admin/elective/[id]/edit/page.tsx（MSW 兜底） |
| 34 | admin/questions/page.tsx | §四补充批次 | ✅ /shell/admin/questions/page.tsx（MSW 兜底） |
| 35 | admin/lesson-plans/page.tsx | §四补充批次 | ✅ /shell/admin/lesson-plans/page.tsx（MSW 兜底） |
| 36 | admin/lesson-plans/[planId]/view/page.tsx | §四补充批次 | ✅ /shell/admin/lesson-plans/[planId]/view/page.tsx（MSW 兜底） |
| 37 | admin/error-book/page.tsx | §四补充批次 | ✅ /shell/admin/error-book/page.tsx（MSW 兜底） |
| 38 | admin/scheduling/auto/page.tsx | §四补充批次 | ✅ /shell/admin/scheduling/auto/page.tsx（MSW 兜底） |
| 39 | admin/scheduling/changes/page.tsx | §四补充批次 | ✅ /shell/admin/scheduling/changes/page.tsx（MSW 兜底） |
| 40 | admin/scheduling/rules/page.tsx | §四补充批次 | ✅ /shell/admin/scheduling/rules/page.tsx（MSW 兜底） |
| 41 | admin/attendance/page.tsx | §四补充批次 | ✅ /shell/admin/attendance/page.tsx（MSW 兜底） |
**ARCH §9.4 规划但 CICD 无源（5 页）**：
**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` |
| # | ARCH 目标路由 | 说明 | 契约 | portal-shell 状态（2026-08-04） |
| --- | ------------------------- | -------------------------------- | ----------------- | -------------------------------------------- |
| A | /shell/admin/students | ARCH 新建，CICD 无 | ❌ → MSW 兜底 | ✅ /shell/admin/students/page.tsx |
| B | /shell/admin/teachers | ARCH 新建，CICD 无 | ❌ → MSW 兜底 | ✅ /shell/admin/teachers/page.tsx |
| C | /shell/admin/organization | ARCH 新建，CICD 无 | ❌ → MSW 兜底 | ✅ /shell/admin/organization/page.tsx |
| D | /shell/admin/viewports | ARCH 新建，对齐 004 §5.4 | ❌ → MSW 兜底 | ✅ /shell/admin/viewports/page.tsx |
| E | /shell/admin/plugins | ARCH 新建（plugin-manager 升级） | ✅ config-service | ✅ /shell/admin/plugins/page.tsx（真实契约） |
---
**portal-shell 额外新增（3 项 redirect 入口）**：
## 七、关键结论
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 页。
| # | portal-shell 路由 | 说明 |
| --- | ----------------------- | ------------------------------------------ |
| α | /shell/admin/classes | redirect → /shell/admin/school/classes |
| β | /shell/admin/scheduling | redirect → /shell/admin/scheduling/changes |
| γ | /shell/admin/school | redirect → /shell/admin/school/schools |