# admin-portal 工作排期

> 负责人：ai16
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)、[ai-allocation.md §5 ai16](../../ai-allocation.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 说明：本排期基于 GraphQL（ARB-001 admin 命名空间）+ 端口 4003 + ai16 归属，已对齐 [matrix.md](../matrix.md) 与 ai-allocation.md。01/02 文档中 REST/3003/ai07 表述待 coord 仲裁后修订（见 [objections/admin-portal_issue.md](../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](../contracts/admin-portal_contract.md)），上游就绪后逐项切换真实。

---

## §2 全阶段甘特图（P2-P6）

```mermaid
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                             | ⏳        |

---

## §6 工作进度更新（2026-07-13）

### 6.1 P2-P6 完成状态

| 阶段 | 任务                                        | 状态                                                                                   |
| ---- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| P2   | 16.1 MF Remote 骨架                         | ✅ 完成                                                                                |
| P2   | 16.2 MSW handlers + fixtures + mock JWT     | ✅ 完成                                                                                |
| P2   | 16.3 接入 Shell 共享                        | ✅ 完成                                                                                |
| P3   | 16.4 用户管理页                             | ✅ 完成                                                                                |
| P3   | 16.5 角色权限矩阵                           | ✅ 完成                                                                                |
| P3   | 16.6 权限点管理 + 视口配置                  | ✅ 完成                                                                                |
| P4   | 16.7 组织树管理                             | ✅ 完成                                                                                |
| P4   | 16.8 学校设置                               | ✅ 完成                                                                                |
| P4   | 16.9 班级/教师/学生全局管理                 | ✅ 完成                                                                                |
| P5   | 16.10 审计日志页                            | ✅ 完成                                                                                |
| P5   | 16.11 WebSocket 实时通知                    | ✅ 完成                                                                                |
| P5   | 16.12 管理仪表盘                            | ✅ 完成                                                                                |
| P6   | 16.13 A11y WCAG 2.2 AA                      | ✅ 完成                                                                                |
| P6   | 16.14 Web Vitals                            | ✅ 完成                                                                                |
| P6   | 16.15 Vitest 单测                           | ✅ 完成（5 测试文件 / 69 用例全过：setup + permissions + i18n + auth + ui + fixtures） |
| P6   | 16.16 Dockerfile + /api/health + /api/ready | ✅ 完成                                                                                |

### 6.2 coord 仲裁状态

- ARB-021 全部 7 项 ISSUE 已裁决（ISSUE-001~007），无新仲裁待处理
- ARB-022（api-gateway）影响 admin-portal 路由配置（`/api/admin/*` → teacher-bff），已确认

### 6.3 ISSUE 状态

| ISSUE     | 内容                                  | 状态      |
| --------- | ------------------------------------- | --------- |
| ISSUE-001 | 01/02 模块文档归属错误（ai07 → ai16） | ✅ 已裁决 |
| ISSUE-002 | 01/02 端口错误（3003 → 4003）         | ✅ 已裁决 |
| ISSUE-003 | 01/02 通信协议 REST → GraphQL         | ✅ 已裁决 |
| ISSUE-004 | 01/02 遗漏审计日志与学校设置          | ✅ 已裁决 |
| ISSUE-005 | teacher-bff admin 命名空间 schema     | ✅ 已裁决 |
| ISSUE-006 | 推送策略轮询 → WebSocket              | ✅ 已裁决 |
| ISSUE-007 | matrix.md Kafka 直消费方修正          | ✅ 已裁决 |

---

## §7 参考项目差距分析（2026-07-13）

> 参考项目：`e:\Desktop\CICD\`（单体 Next_Edu 教育平台），admin 页面位于 `src/app/(dashboard)/admin/`

### 7.1 参考项目 Admin 页面全览（19 个功能模块）

| #   | 参考路由                | 功能                                                                            | 领域判定                    | Edu admin-portal 现状                          |
| --- | ----------------------- | ------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------- |
| 1   | /admin/dashboard        | 管理仪表盘                                                                      | 管理域                      | ✅ 已有                                        |
| 2   | /admin/users            | 用户管理                                                                        | 管理域                      | ✅ 已有                                        |
| 3   | /admin/roles            | 角色管理                                                                        | 管理域                      | ✅ 已有                                        |
| 4   | /admin/permissions      | 权限管理                                                                        | 管理域                      | ✅ 已有                                        |
| 5   | /admin/audit-logs       | 审计日志（含 overview/data-changes/login-logs）                                 | 管理域                      | ⚠️ 仅有单一操作日志，缺子模块                  |
| 6   | /admin/school           | 学校管理（含 schools/grades/departments/academic-year/grades/insights/classes） | 管理域                      | ⚠️ 仅有粗粒度 organization，缺子模块           |
| 7   | /admin/settings         | 系统设置（安全策略/文件上传/通知/品牌）                                         | 管理域                      | ⚠️ 仅有基础学校信息，缺安全/文件/通知/品牌配置 |
| 8   | /admin/announcements    | 公告管理                                                                        | 管理域                      | ❌ 缺失                                        |
| 9   | /admin/files            | 文件管理                                                                        | 管理域                      | ❌ 缺失                                        |
| 10  | /admin/invitation-codes | 邀请码管理                                                                      | 管理域                      | ❌ 缺失                                        |
| 11  | /admin/ai-settings      | AI 配置                                                                         | 管理域                      | ❌ 缺失                                        |
| 12  | /admin/attendance       | 考勤管理                                                                        | 教学域（归 teacher-portal） | N/A                                            |
| 13  | /admin/course-plans     | 课程计划                                                                        | 教学域（归 teacher-portal） | N/A                                            |
| 14  | /admin/curriculum-map   | 课程图谱                                                                        | 教学域（归 teacher-portal） | N/A                                            |
| 15  | /admin/elective         | 选课管理                                                                        | 教学域（归 teacher-portal） | N/A                                            |
| 16  | /admin/error-book       | 错题本                                                                          | 教学域（归 teacher-portal） | N/A                                            |
| 17  | /admin/lesson-plans     | 备课管理                                                                        | 教学域（归 teacher-portal） | N/A                                            |
| 18  | /admin/questions        | 题库                                                                            | 教学域（归 teacher-portal） | N/A                                            |
| 19  | /admin/scheduling       | 排课                                                                            | 教学域（归 teacher-portal） | N/A                                            |

### 7.2 缺失功能分类与实现优先级

#### P0 — 审计日志子模块增强

现有 `/admin/audit-logs` 仅有单一操作日志页面，需增加：

- `/admin/audit-logs/overview` — 审计总览（操作趋势图、数据变更分布、统计条）
- `/admin/audit-logs/data-changes` — 数据变更日志（按表名/动作筛选 + 分页 + 导出）
- `/admin/audit-logs/login-logs` — 登录日志（signin/signout/signup 成败记录）

#### P0 — 学校组织管理细化

现有 `/admin/organization` 仅有树形组织视图，需增加子页面：

- `/admin/school/schools` — 多学校/校区列表管理
- `/admin/school/grades` — 年级管理（含年级主任分配 + 概览统计）
- `/admin/school/grades/insights` — 年级洞察（全校成绩汇总 + 作业时间线 + 班级排名）
- `/admin/school/departments` — 部门/教研组管理
- `/admin/school/academic-year` — 学年/学期管理

#### P1 — 系统设置增强

现有 `/admin/system` 仅有基础学校信息 + 学期 + 时区/语言，需增加：

- 安全策略 Card（密码复杂度/会话超时/强制改密）
- 文件上传配置 Card（最大体积/允许类型）
- 通知配置 Card（新用户/调课/公告通知开关）
- 品牌配置 Card（Logo/主题色）

#### P1 — 公告管理（新增）

- `/admin/announcements` — 公告发布/归档/置顶、多受众 fan-out 通知、已读回执、状态机（draft→published→archived）

#### P1 — 邀请码管理（新增）

- `/admin/invitation-codes` — 批量生成邀请码、角色/班级/邮箱绑定、事务消费、批次审计

#### P2 — 文件管理（新增）

- `/admin/files` — 全局文件附件治理、跨业务实体筛选、批量删除、存储统计、预览

#### P2 — AI 配置（新增）

- `/admin/ai-settings` — AI Provider 凭据管理、用量仪表盘、public/private provider 分治

### 7.3 实现计划

| 批次   | 内容                                                                                                                      | 优先级  |
| ------ | ------------------------------------------------------------------------------------------------------------------------- | ------- |
| 批次 1 | 审计日志子模块（overview/data-changes/login-logs）+ 学校组织管理细化（schools/grades/departments/academic-year/insights） | P0      |
| 批次 2 | 系统设置增强 + 公告管理 + 邀请码管理                                                                                      | P1      |
| 批次 3 | 文件管理 + AI 配置                                                                                                        | P2      |
| 批次 4 | 测试文件补充（vitest setup + test cases ≥80%）                                                                            | P6 补齐 |

---

## §8 差距闭环完成总结（2026-07-13）

### 8.1 全部 4 批次已交付

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

### 8.2 新增文件清单

**Hooks（7 个）**：

- `src/hooks/use-audit-overview.ts` — 审计总览统计 + 7 日趋势
- `src/hooks/use-data-change-logs.ts` — 数据变更日志 + CSV 导出
- `src/hooks/use-login-logs.ts` — 登录日志查询
- `src/hooks/use-school.ts` — 学校/年级/部门/学年/年级洞察
- `src/hooks/use-announcements.ts` — 公告 CRUD + 状态机
- `src/hooks/use-invitation-codes.ts` — 邀请码批量生成/删除
- `src/hooks/use-files.ts` — 文件列表/统计/批量删除
- `src/hooks/use-ai-settings.ts` — AI Provider + 用量

**Pages（13 个新建 + 2 个修改）**：

- 审计子模块：`audit-logs/overview/page.tsx`、`audit-logs/data-changes/page.tsx`、`audit-logs/login-logs/page.tsx`、`audit-logs/page.tsx`（修改加 Tabs）
- 学校组织：`school/layout.tsx`、`school/page.tsx`（重定向）、`school/schools/page.tsx`、`school/grades/page.tsx`、`school/grades/insights/page.tsx`、`school/departments/page.tsx`、`school/academic-year/page.tsx`
- 公告/邀请码：`announcements/page.tsx`、`invitation-codes/page.tsx`
- 文件/AI：`files/page.tsx`、`ai-settings/page.tsx`
- 系统设置（修改）：`system/page.tsx` 增加 4 Card

**共享组件**：`src/components/audit-logs-tabs.tsx`

**测试文件（5 个）**：

- `src/test/setup.ts` — 全局环境（jest-dom + localStorage + fetch mock）
- `src/lib/permissions.test.ts` — 8 用例
- `src/lib/i18n.test.ts` — 9 用例
- `src/lib/auth.test.ts` — 9 用例
- `src/components/ui.test.tsx` — 27 用例（PaperCard/PageHeader/Button/Input/Select/Badge/Table/EmptyState/LoadingState/ErrorState/Pagination）
- `src/mocks/fixtures.test.ts` — 16 用例

### 8.3 共享基础设施扩展

| 文件                             | 增量                                 |
| -------------------------------- | ------------------------------------ |
| `src/lib/permissions.ts`         | 新增 11 个权限点 + 14 条路由权限映射 |
| `src/types/view-models.ts`       | 新增 ~20 个 ViewModel 接口           |
| `src/lib/i18n.ts`                | 新增 ~100 个 i18n key                |
| `src/lib/graphql-client.ts`      | 新增 ~25 个 GraphQL operation        |
| `src/mocks/fixtures.ts`          | 新增 ~15 个 mock 数据集合            |
| `src/mocks/handlers.ts`          | 新增 ~20 个 operation handler        |
| `src/components/admin-shell.tsx` | NAV_ITEMS 11 → 16 项                 |

### 8.4 质量校验

- ✅ `pnpm run typecheck`：零错误
- ✅ `pnpm run lint`：零错误
- ✅ `pnpm run test`：5 文件 / 69 用例全过（11.76s）
- ✅ `pnpm run arch:scan`：arch.db 已更新（TS 20 模块 / 2045 符号）

### 8.5 ARB-021 全 7 项 ISSUE 状态

全部已裁决，无新 coord 仲裁（最新为 ARB-022 §24，属 api-gateway 模块）。

### 8.6 模块完成度

admin-portal 全部 P2-P6 任务（16 项）+ §7 差距分析 4 批次补齐全部完成，模块工作收口。