NextEdu/docs/architecture/audit/permissions-audit-report.md

# 用户权限模块审计报告

> 审计范围：用户权限（RBAC）模块，包括 `shared/types/permissions.ts`、`shared/lib/permissions.ts`、`shared/lib/auth-guard.ts`、`shared/hooks/use-permission.ts`、`shared/lib/role-utils.ts`、`shared/lib/session.ts`、`auth.ts`、`modules/rbac/*`、`modules/users/*`（权限相关部分）、`app/(dashboard)/admin/{roles,permissions,users}/*`。
> 审计时间：2026-06-24
> 审计依据：项目规则 `.trae/rules/project_rules.md`、架构影响地图 `004/005`。

---

## 一、现有实现概要

### 1.1 文件分布与行数

| 层 | 文件 | 行数 | 职责 |
|---|---|---|---|
| shared/types | `permissions.ts` | 223 | 67 个权限点常量 + `Role`/`BuiltinRole`/`Permission`/`DataScope`/`AuthContext` 类型 |
| shared/lib | `permissions.ts` | 301 | `ROLE_PERMISSIONS_SEED`（6 内置角色种子）+ `resolvePermissions()`（DB 查询 + 种子兜底） |
| shared/lib | `auth-guard.ts` | 176 | `getAuthContext()` / `requirePermission()` / `checkPermission()` / `resolveDataScope()` / `requireAuth()` |
| shared/lib | `role-utils.ts` | 34 | `normalizeRole()` / `resolvePrimaryRole()` 纯函数 |
| shared/lib | `session.ts` | 35 | `getSession()`（动态 import `@/auth` 避免循环依赖） |
| shared/hooks | `use-permission.ts` | 53 | 客户端 `usePermission()` Hook（`hasPermission`/`hasAnyPermission`/`hasAllPermissions`/`hasRole`） |
| app/root | `auth.ts` | 234 | NextAuth v5 配置（Credentials + JWT + Session 回调 + 登录事件） |
| modules/rbac | `data-access.ts` | 215 | 角色 CRUD + `getRolePermissions`/`setRolePermissions` + `ADMIN_ROLE_NAME` 常量 |
| modules/rbac | `data-access-assignments.ts` | 161 | 用户-角色分配（`getUserRoleNames`/`assignRolesToUser`/`getUserRoleAssignments`） |
| modules/rbac | `actions.ts` | 382 | 8 个 Server Action（含 `requirePermission` + Zod + 审计日志） |
| modules/rbac | `schema.ts` | 42 | 4 个 Zod schema |
| modules/rbac | `types.ts` | 56 | `RoleRecord`/`RoleWithStats`/`RoleDetail`/`CreateRoleInput`/`UpdateRoleInput`/`UserRoleAssignment`/`PaginatedResult` |
| modules/rbac/lib | `permission-catalog.ts` | 268 | `PERMISSION_CATALOG`（24 分组）+ `getAllPermissionMetas`/`getPermissionMeta` |
| modules/rbac/components | 7 个文件 | ~600 | `RoleList`/`RoleFormDialog`/`RolePermissionMatrix`/`PermissionCatalogView`/`UserRoleAssignDialog`/`RoleManagementView`/`RoleDetailEditButton` |
| modules/users | `data-access.ts` | 424 | 用户查询 + `getCurrentStudentUser` + `getAdminUsers`/`getAdminUserRoles` |
| modules/users | `actions.ts` | 218 | `updateUserProfile`/`importUsersAction`/`exportUsersAction`/`updateUserRoleAction`（空实现）/`deleteUserAction` |
| app/(dashboard)/admin | 4 个 page.tsx | ~200 | 角色列表/角色详情/权限目录/用户管理页面 |

### 1.2 数据流

```
登录 (auth.ts authorize)
  └─▶ db.query.users → 校验密码 → 查询 usersToRoles → resolvePrimaryRole
  └─▶ JWT callback: resolvePermissions(allRoles) → 写入 token.permissions
  └─▶ Session callback: 透传到 session.user.permissions

请求 (Server Component / Server Action)
  └─▶ getAuthContext() → getSession() → resolveDataScope(userId, roles) → AuthContext
  └─▶ requirePermission(p) → 校验 ctx.permissions.includes(p)

客户端 (Client Component)
  └─▶ usePermission() → useSession() → hasPermission(p)
```

### 1.3 架构图记录情况

架构影响地图 `004` 和数据 JSON `005` 已记录 `rbac` 模块（JSON 第 16204-16603 行），包含：
- 8 个 actions、11 个 data-access 函数、3 个 lib 常量/函数、8 个组件
- 依赖关系：`shared/db`、`shared/types/permissions`、`shared/lib/auth-guard`、`shared/lib/audit-logger`、`shared/lib/change-logger`
- 被使用方：`admin/roles`、`admin/permissions`、`admin/users`、`modules/users`
- i18n 命名空间 `rbac`，文件 `zh-CN/rbac.json` + `en/rbac.json`

**架构图遗漏**：
- `shared/lib/permissions.ts`（`resolvePermissions`）未在 rbac 模块依赖中显式列出（实际被 `auth.ts` 使用）
- `shared/lib/auth-guard.ts` 的 `resolveDataScope` 内部直接查询 `classes`/`classEnrollments`/`classSubjectTeachers`/`grades`/`parentStudentRelations` 表，属于跨模块数据访问，未在架构图中标注
- `modules/users/data-access.ts` 的 `getCurrentStudentUser` 直接调用 `auth()` 而非 `getAuthContext()`，未在架构图中标注此异常依赖
- `app/(dashboard)/admin/permissions/page.tsx` 直接查询 `rolePermissions`/`roles` 表，未走 data-access，架构图未标注此违规
- `modules/users/actions.ts` 的 `deleteUserAction` 直接 `db.delete(users)`，未走 data-access，架构图未标注
- `app/(dashboard)/admin/roles`、`admin/permissions`、`admin/users`（非 import 子目录）缺少 `loading.tsx`/`error.tsx`，架构图未标注

---

## 二、现存问题与原因分析

### 2.1 架构分层违规（P0）

#### 问题 2.1.1 — `app/` 直接访问数据库
- **位置**：[admin/permissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/admin/permissions/page.tsx) 第 28-32 行
- **问题**：页面组件直接 `db.select(...).from(rolePermissions).innerJoin(roles, ...)` 查询数据库，绕过 data-access 层。
- **违反规则**：`app/ 只能调用 modules/ 的 Server Actions 和 data-access，不直接访问数据库`（项目规则「架构分层规则」）。
- **后果**：权限统计查询逻辑散落在页面中，无法复用、无法测试、无法统一加缓存；若 `rolePermissions` 表结构变更需修改多处。

#### 问题 2.1.2 — Server Action 直接访问数据库
- **位置**：[users/actions.ts](file:///e:/Desktop/CICD/src/modules/users/actions.ts) 第 208 行 `await db.delete(users).where(eq(users.id, userId))`
- **问题**：`deleteUserAction` 直接在 actions 层执行 DB 删除，未下沉到 data-access。
- **违反规则**：`app/ 只能调用 modules/ 的 Server Actions 和 data-access` + `严格三层架构，依赖方向单向`（项目规则「架构分层规则」）。
- **后果**：删除用户逻辑（应包含级联清理 sessions、usersToRoles、passwordSecurity 等）散落在 actions 层，易遗漏级联清理，造成孤儿数据。

#### 问题 2.1.3 — 客户端组件直接调用 fetch API
- **位置**：[admin-users-view.tsx](file:///e:/Desktop/CICD/src/modules/users/components/admin-users-view.tsx) 第 120 行 `fetch("/api/admin/users/" + deleteUserId, { method: "DELETE" })`
- **问题**：客户端组件通过 `fetch` 调用 API 路由删除用户，而非调用 Server Action。
- **违反规则**：`app/ 只能调用 modules/ 的 Server Actions 和 data-access`（项目规则「架构分层规则」）。
- **后果**：绕过 Server Action 的权限校验、Zod 验证、审计日志；存在未授权调用风险；删除逻辑出现两套（Server Action + API 路由）。

#### 问题 2.1.4 — `getCurrentStudentUser` 使用 `auth()` 而非 `getAuthContext()`
- **位置**：[users/data-access.ts](file:///e:/Desktop/CICD/src/modules/users/data-access.ts) 第 232 行 `const session = await auth()`
- **问题**：直接调用 `auth()` 获取 session，而非使用项目统一的 `getAuthContext()`。
- **违反规则**：`Authentication must use getAuthContext() and getCurrentStudentUser(); avoid mixing with other auth methods`（项目记忆 Hard Constraints）。
- **后果**：认证入口不统一，`getAuthContext` 提供的 `dataScope` 等上下文信息丢失；后续若在 session 校验逻辑中增加 IP 限制、租户隔离等，此处不会自动生效。

#### 问题 2.1.5 — `resolveDataScope` 跨模块直接查询数据库表
- **位置**：[auth-guard.ts](file:///e:/Desktop/CICD/src/shared/lib/auth-guard.ts) 第 70-163 行
- **问题**：`resolveDataScope` 直接查询 `classes`、`classEnrollments`、`classSubjectTeachers`、`grades`、`parentStudentRelations` 表，这些表属于 `school`、`classes`、`parent` 等模块。
- **违反规则**：`模块间只能通过对方 data-access 通信，禁止跨模块直接查询数据库表`（项目规则「架构分层规则」）。
- **后果**：`shared/lib` 反向依赖业务模块的表结构；若 `classes` 模块重构表结构，`auth-guard` 会编译报错；`shared/` 不得反向依赖业务模块的硬约束被破坏。

### 2.2 权限校验缺失或硬编码（P0/P1）

#### 问题 2.2.1 — `updateUserRoleAction` 是空实现
- **位置**：[users/actions.ts](file:///e:/Desktop/CICD/src/modules/users/actions.ts) 第 177-196 行
- **问题**：`updateUserRoleAction` 接收 `userId` 和 `role` 参数后，仅 `void userId; void role;` 直接返回成功，未执行任何实际操作。
- **违反规则**：`所有 Server Action 必须调用 requirePermission() 进行权限校验`（虽已调用 `requirePermission`，但逻辑为空）+ 功能完整性。
- **后果**：管理员在用户管理页点击「编辑」试图修改角色时，系统提示成功但实际未变更，属于功能性 Bug。

#### 问题 2.2.2 — `resolveDataScope` 角色硬编码
- **位置**：[auth-guard.ts](file:///e:/Desktop/CICD/src/shared/lib/auth-guard.ts) 第 64、69、81、113、136 行
- **问题**：使用 `roleNames.includes("admin")`、`roleNames.includes("grade_head")`、`roleNames.includes("teacher")`、`roleNames.includes("student")`、`roleNames.includes("parent")` 硬编码角色名。
- **违反规则**：`前端权限判断统一使用 usePermission().hasPermission()，严禁出现 role === "xxx" 硬编码`（项目规则虽针对前端，但服务端 DataScope 解析也应避免硬编码角色名，以支持动态角色）。
- **后果**：新增自定义角色无法正确解析 DataScope；`grade_head`/`teaching_head` 被合并处理，无法差异化授权。

#### 问题 2.2.3 — `role-utils.ts` 将 `grade_head`/`teaching_head` 折叠为 `teacher`
- **位置**：[role-utils.ts](file:///e:/Desktop/CICD/src/shared/lib/role-utils.ts) 第 17 行
- **问题**：`normalizeRole` 将 `grade_head`/`teaching_head` 映射为 `teacher`，丢失了角色差异。
- **后果**：`auth.ts` JWT 回调中 `token.role = resolvePrimaryRole(allRoles)` 后，年级主任/教务主任的 `session.user.role` 变为 `teacher`，前端若依赖 `role` 字段做路由跳转会丢失差异。

### 2.3 国际化遗漏（P1）

#### 问题 2.3.1 — RBAC 组件大量硬编码英文
- **位置**：
  - [role-list.tsx](file:///e:/Desktop/CICD/src/modules/rbac/components/role-list.tsx) 第 84、88、98、102、140、151、153、173、179、190、216、227 行（"No roles yet"、"Create Role"、"Roles"、"System"、"Custom"、"Enabled"、"Disabled"、"Edit"、"Enable"、"Disable"、"Delete"、"Deleting..."）
  - [role-form-dialog.tsx](file:///e:/Desktop/CICD/src/modules/rbac/components/role-form-dialog.tsx) 第 74、78-79、89、99、109、125 行（"Create new role"、"Edit role"、"Role name"、"Description"、"Cancel"、"Saving..."）
  - [user-role-assign-dialog.tsx](file:///e:/Desktop/CICD/src/modules/rbac/components/user-role-assign-dialog.tsx) 第 102、104-107、113、137、151、153、173 行（"Assign roles"、"Save roles"、"Cancel"、"Saving..."）
  - [permission-catalog-view.tsx](file:///e:/Desktop/CICD/src/modules/rbac/components/permission-catalog-view.tsx) 第 35、44 行（"Permission Catalog"、"All permission points..."）
  - [admin/roles/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/admin/roles/page.tsx) 第 28-31 行
  - [admin/roles/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/admin/roles/[id]/page.tsx) 第 53、56、63、65、78-80 行
  - [admin/permissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/admin/permissions/page.tsx) 第 43-44 行
- **违反规则**：`所有用户可见文本必须适配 i18n（使用 next-intl），提取翻译键`（项目规则「安全规范」+ 项目记忆 Hard Constraints）。
- **后果**：中文用户看到英文界面，体验不一致；无法切换语言。

#### 问题 2.3.2 — `admin-users-view.tsx` 大量硬编码中文
- **位置**：[admin-users-view.tsx](file:///e:/Desktop/CICD/src/modules/users/components/admin-users-view.tsx) 第 142、148、159、169、172、180、190、203、211-216、222、227、247、252、260、273、284、291、305、307、311、317 行
- **问题**：与 2.3.1 相反，此处全部硬编码中文（"用户管理"、"批量导入"、"搜索姓名或邮箱..."、"所有角色"、"搜索"、"重置"、"暂无用户"、"姓名"、"邮箱"、"角色"、"手机"、"注册时间"、"操作"、"编辑"、"分配角色"、"删除"、"确认删除用户？"等）。
- **违反规则**：同 2.3.1。
- **后果**：英文用户看到中文界面；与 RBAC 其他组件语言不一致（一半英文一半中文）。

#### 问题 2.3.3 — `rbac.json` 缺少权限点标签
- **位置**：[zh-CN/rbac.json](file:///e:/Desktop/CICD/src/shared/i18n/messages/zh-CN/rbac.json) + [en/rbac.json](file:///e:/Desktop/CICD/src/shared/i18n/messages/en/rbac.json)
- **问题**：`PERMISSION_CATALOG` 中每个权限点都定义了 `labelKey`（如 `rbac:permissions.exam.create`）和 `descriptionKey`，但 i18n 文件中只有 `permissions.group.*` 分组标签，缺少 `permissions.exam.create`、`permissions.exam.create.desc` 等具体权限点的翻译。
- **后果**：`RolePermissionMatrix` 和 `PermissionCatalogView` 中 `t.has(labelKey) ? t(labelKey) : perm.key` 回退到显示原始 key（如 `EXAM_CREATE`），用户无法理解权限含义。

### 2.4 TypeScript 类型不安全（P1）

#### 问题 2.4.1 — `as` 断言违规
- **位置**：
  - [permissions.ts](file:///e:/Desktop/CICD/src/shared/lib/permissions.ts) 第 279、296 行 `row.permission as Permission`
  - [auth-guard.ts](file:///e:/Desktop/CICD/src/shared/lib/auth-guard.ts) 第 27-28 行 `session.user.roles as Role[]`、`session.user.permissions as Permission[]`
  - [auth.ts](file:///e:/Desktop/CICD/src/auth.ts) 第 146 行 `user as { id: string; ... }`、第 196 行 `token.permissions as typeof token.permissions`、第 217-223 行 `message as { ... }`
  - [data-access.ts](file:///e:/Desktop/CICD/src/modules/rbac/data-access.ts) 第 81、186 行 `row.permission as Permission`
  - [data-access-assignments.ts](file:///e:/Desktop/CICD/src/modules/rbac/data-access-assignments.ts) 第 149 行 `params.role as string`
  - [admin/permissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/admin/permissions/page.tsx) 第 36 行 `row.permission as Permission`
  - [users/actions.ts](file:///e:/Desktop/CICD/src/modules/users/actions.ts) 第 183-184、207 行 `formData.get(...) as string`
  - [admin-users-view.tsx](file:///e:/Desktop/CICD/src/modules/users/components/admin-users-view.tsx) 第 128 行 `e as Error`
- **违反规则**：`禁止 as 断言（除非从 unknown 转换或测试中，需注释原因）`（项目规则「TypeScript 规则」）。
- **后果**：类型安全被绕过，若 DB schema 或 session 结构变更，编译期不报错，运行时才暴露。

### 2.5 错误处理与边界缺失（P1）

#### 问题 2.5.1 — 缺少 `loading.tsx` / `error.tsx`
- **位置**：
  - `app/(dashboard)/admin/roles/` — 无 `loading.tsx`、`error.tsx`
  - `app/(dashboard)/admin/roles/[id]/` — 无 `loading.tsx`、`error.tsx`
  - `app/(dashboard)/admin/permissions/` — 无 `loading.tsx`、`error.tsx`
  - `app/(dashboard)/admin/users/` — 无 `loading.tsx`、`error.tsx`（仅 `users/import/` 有）
- **违反规则**：`All student routes must include loading.tsx and error.tsx for error boundaries`（项目记忆 Hard Constraints，虽针对 student 路由，但 admin 路由也应遵循）。
- **后果**：页面加载时无骨架屏，体验差；`requirePermission` 抛出 `PermissionDeniedError` 时无友好错误页，显示 Next.js 默认错误。

#### 问题 2.5.2 — 无 React Error Boundary 包裹独立数据区块
- **位置**：所有 RBAC 组件
- **问题**：`RoleList`、`RolePermissionMatrix`、`PermissionCatalogView` 等组件未用 Error Boundary 包裹，单个组件抛错会导致整页崩溃。
- **后果**：权限矩阵加载失败时，角色列表也无法显示。

#### 问题 2.5.3 — 无空数据/无权限/网络异常边界状态
- **位置**：
  - `RolePermissionMatrix` 无空权限组处理
  - `UserRoleAssignDialog` 无网络异常重试
  - `PermissionCatalogView` 无加载骨架
- **后果**：异常状态下用户看到空白或卡顿。

### 2.6 组件不可复用 / 逻辑未抽取（P2）

#### 问题 2.6.1 — `admin-users-view.tsx` 与 RBAC 组件重复实现
- **位置**：[admin-users-view.tsx](file:///e:/Desktop/CICD/src/modules/users/components/admin-users-view.tsx)
- **问题**：`AdminUsersView` 自行实现了删除确认对话框、分页、搜索、角色筛选，未复用 RBAC 模块的 `EmptyState`、分页组件等；同时硬编码了 `UserRoleAssignDialog` 的调用。
- **后果**：UI 不一致，维护成本高。

#### 问题 2.6.2 — `admin-users-view.tsx` 包含死代码
- **位置**：第 246-248 行「编辑」菜单项
- **问题**：`DropdownMenuItem` 点击无任何行为，未绑定 `onClick`。
- **后果**：用户点击「编辑」无反应，体验差。

#### 问题 2.6.3 — 纯逻辑与 UI 未分离
- **位置**：`RolePermissionMatrix` 中的 `setsEqual` 函数、选中状态计算逻辑
- **问题**：`setsEqual` 工具函数内联在组件文件底部，未抽取到 hooks 或 utils；选中状态 diff 逻辑未抽取。
- **后果**：无法单测，无法复用。

### 2.7 可访问性缺失（P2）

#### 问题 2.7.1 — 缺少 ARIA 属性与键盘导航
- **位置**：所有 RBAC 组件
- **问题**：
  - `RoleList` 表格无 `<caption>` 描述
  - `RolePermissionMatrix` 的 checkbox 分组无 `fieldset`/`legend` 语义
  - `UserRoleAssignDialog` 的角色列表无 `role="list"`
  - 图标按钮（如 `MoreHorizontal` 触发器）虽有 `sr-only` 但无 `aria-label`
- **违反规则**：`可访问性（a11y）：语义化标签、ARIA 属性、键盘导航`（项目规则「企业级补充」）。
- **后果**：屏幕阅读器用户无法理解页面结构；键盘用户操作困难。

### 2.8 性能与监控缺失（P2）

#### 问题 2.8.1 — 无 React Server Components 流式渲染
- **位置**：所有 admin 页面
- **问题**：页面使用 `export const dynamic = "force-dynamic"` 但未使用 `loading.tsx` 或 Suspense 流式渲染，整页阻塞等待所有数据。
- **后果**：首屏白屏时间长。

#### 问题 2.8.2 — 无关键操作埋点
- **位置**：`assignUserRolesAction`、`setRolePermissionsAction`
- **问题**：虽有 `logAudit` 审计日志，但无前端交互埋点（如权限变更成功率、耗时、失败原因分布）。
- **后果**：无法监控权限管理操作的健康度。

### 2.9 安全性隐患（P1）

#### 问题 2.9.1 — `deleteUserAction` 未校验目标用户是否为内置角色持有者
- **位置**：[users/actions.ts](file:///e:/Desktop/CICD/src/modules/users/actions.ts) 第 201-217 行
- **问题**：删除用户时未检查该用户是否为最后一个 admin 角色持有者，可能导致系统无管理员。
- **后果**：管理员误删后无法恢复。

#### 问题 2.9.2 — `assignRolesToUser` 未校验角色是否为内置且未禁用
- **位置**：[data-access-assignments.ts](file:///e:/Desktop/CICD/src/modules/rbac/data-access-assignments.ts) 第 42-73 行
- **问题**：`assignRolesToUser` 仅校验角色名存在，未校验角色是否 `isEnabled`，可将禁用角色分配给用户（虽 `resolvePermissions` 会过滤禁用角色，但数据不一致）。
- **后果**：用户被分配禁用角色后，UI 显示已分配但实际无权限，造成困惑。

---

## 三、行业差距对比

### 3.1 权限模型维度

| 能力 | 行业优秀实践（如 PowerSchool、Veracross、Alma） | 当前实现 | 差距影响 |
|---|---|---|---|
| 权限继承 | 支持权限继承（如 admin 继承 teacher 所有权限） | 扁平权限，无继承 | 新增角色需手动勾选所有权限，易遗漏 |
| 权限模板 | 提供角色模板（如「班主任」「学科组长」）一键创建 | 无模板，从零配置 | 管理员配置成本高 |
| 权限预览 | 保存前预览「该角色将获得哪些菜单/操作」 | 仅显示权限点列表 | 管理员无法直观理解权限效果 |
| 权限差异对比 | 对比两个角色的权限差异 | 无 | 无法评估角色调整影响 |
| 权限使用统计 | 统计每个权限点被多少角色/用户使用 | `PermissionCatalogView` 仅统计角色数，未统计用户数 | 无法识别「僵尸权限」 |
| 数据范围权限 | 支持「只能看自己班级」「只能看本年级」等行级权限 | `DataScope` 已实现但硬编码角色 | 自定义角色无法配置数据范围 |
| 权限生效时间 | 支持权限定时生效/过期 | 无 | 临时授权需手动撤销 |

### 3.2 UI/UX 维度

| 能力 | 行业优秀实践 | 当前实现 | 差距影响 |
|---|---|---|---|
| 权限矩阵搜索 | 支持按权限名/模块搜索过滤 | 无搜索，67 个权限点全展示 | 管理员查找特定权限困难 |
| 权限分组折叠 | 支持折叠/展开权限分组 | 分组固定展开 | 页面过长，滚动疲劳 |
| 批量角色分配 | 支持批量给多个用户分配角色 | 仅单个用户 | 批量入职时效率低 |
| 角色克隆 | 复制现有角色创建新角色 | 无 | 相似角色需重新勾选 |
| 权限变更审计可视化 | 时间轴展示角色权限变更历史 | 仅审计日志文本 | 无法直观追溯权限演进 |
| 权限影响范围分析 | 显示「修改此角色将影响 N 个用户」 | `RoleList` 显示 userCount 但编辑时不提示 | 管理员不知修改影响范围 |
| 实时权限校验 | 前端实时显示当前用户是否有权限操作 | `usePermission` 已实现但未在 UI 普遍使用 | 用户点击后才报无权限 |

### 3.3 多角色支持维度

| 能力 | 行业优秀实践 | 当前实现 | 差距影响 |
|---|---|---|---|
| 多角色叠加 | 用户多角色权限取并集 | `resolvePermissions` 已合并 | ✅ 已实现 |
| 主角色判定 | 支持配置主角色（用于路由/默认视图） | `resolvePrimaryRole` 硬编码优先级 | 无法自定义主角色 |
| 角色冲突检测 | 检测互斥角色（如 teacher + student） | 无 | 用户可同时拥有冲突角色 |
| 角色有效期 | 角色分配支持起止时间 | 无 | 临时角色无法自动撤销 |

### 3.4 安全合规维度

| 能力 | 行业优秀实践 | 当前实现 | 差距影响 |
|---|---|---|---|
| 最小权限原则校验 | 提示「该角色权限过大」 | 无 | 易授予过度权限 |
| 敏感权限二次确认 | 修改 admin/删除角色需二次确认 | `RoleList` 有删除确认，但改权限无 | 误操作风险 |
| 权限变更通知 | 权限变更通知受影响用户 | 无 | 用户不知权限被调整 |
| 权限分离审计 | 审计日志记录操作者 IP/UA | `logAudit` 未记录 IP/UA | 无法追溯操作来源 |

---

## 四、改进优先级建议

### P0 — 紧急（安全/架构违规，必须立即修复）

| 编号 | 问题 | 改进方向 |
|---|---|---|
| P0-1 | `admin/permissions/page.tsx` 直查 DB（问题 2.1.1） | 将权限统计查询下沉到 `modules/rbac/data-access.ts`，新增 `getPermissionRoleCounts()` 函数 |
| P0-2 | `deleteUserAction` 直查 DB（问题 2.1.2） | 将删除逻辑下沉到 `modules/users/data-access.ts`，新增 `deleteUserById()` 并处理级联清理 |
| P0-3 | `admin-users-view.tsx` 用 fetch 删除用户（问题 2.1.3） | 改为调用 `deleteUserAction` Server Action |
| P0-4 | `getCurrentStudentUser` 用 `auth()`（问题 2.1.4） | 改为调用 `getAuthContext()` 获取 userId |
| P0-5 | `updateUserRoleAction` 空实现（问题 2.2.1） | 删除此死代码，角色分配统一走 `rbac/actions.ts` 的 `assignUserRolesAction` |
| P0-6 | 缺少 `loading.tsx`/`error.tsx`（问题 2.5.1） | 为 `admin/roles`、`admin/roles/[id]`、`admin/permissions`、`admin/users` 新增 |

### P1 — 高优先级（i18n/类型安全/错误处理）

| 编号 | 问题 | 改进方向 |
|---|---|---|
| P1-1 | RBAC 组件硬编码英文（问题 2.3.1） | 提取翻译键到 `rbac.json`，组件改用 `useTranslations` |
| P1-2 | `admin-users-view.tsx` 硬编码中文（问题 2.3.2） | 提取翻译键到 `users.json` |
| P1-3 | `rbac.json` 缺权限点标签（问题 2.3.3） | 补全 67 个权限点的 `label` + `desc` 翻译 |
| P1-4 | `as` 断言违规（问题 2.4.1） | 用类型守卫替代，如 `isPermission(value): value is Permission` |
| P1-5 | `resolveDataScope` 跨模块查表（问题 2.1.5） | 改为调用 `classes/data-access`、`parent/data-access` 等模块的查询函数 |
| P1-6 | `resolveDataScope` 角色硬编码（问题 2.2.2） | 改为基于权限点判断（如 `hasPermission(DASHBOARD_ADMIN_READ)` → `all` scope）或配置驱动 |
| P1-7 | 无 Error Boundary（问题 2.5.2） | 为 `RoleList`、`RolePermissionMatrix`、`PermissionCatalogView` 包裹 Error Boundary |
| P1-8 | `deleteUserAction` 未保护最后 admin（问题 2.9.1） | 删除前校验目标用户是否为最后一个 admin |
| P1-9 | `assignRolesToUser` 未校验角色启用状态（问题 2.9.2） | 分配前过滤 `isEnabled = false` 的角色 |

### P2 — 中长期（体验/性能/可扩展性）

| 编号 | 问题 | 改进方向 |
|---|---|---|
| P2-1 | 权限矩阵无搜索/折叠 | 新增搜索框 + 分组折叠交互 |
| P2-2 | 无角色模板 | 预置「班主任」「学科组长」等模板 |
| P2-3 | 无权限变更影响提示 | 编辑权限时显示「将影响 N 个用户」 |
| P2-4 | 无权限使用统计 | `PermissionCatalogView` 增加用户数统计 |
| P2-5 | 无 a11y 属性 | 补充 ARIA、`caption`、`fieldset` |
| P2-6 | 无 RSC 流式渲染 | 引入 Suspense + 骨架屏 |
| P2-7 | 无关键操作埋点 | 预留 `trackPermissionChange()` 接口 |
| P2-8 | `role-utils.ts` 折叠角色（问题 2.2.3） | 保留 `grade_head`/`teaching_head` 差异 |
| P2-9 | 无权限继承 | 支持角色继承父角色权限 |
| P2-10 | 无权限变更通知 | 权限变更后通知受影响用户 |

---

## 五、架构图同步说明

本次审计发现架构图存在以下遗漏/不一致，需同步更新：

### 5.1 `004_architecture_impact_map.md` 需补充

1. **`shared/lib/auth-guard.ts` 的 `resolveDataScope` 跨模块依赖**：
   - 当前依赖 `classes`、`classEnrollments`、`classSubjectTeachers`、`grades`、`parentStudentRelations` 表
   - 应标注为「待重构：改为调用各模块 data-access」

2. **`modules/users/data-access.ts` 的 `getCurrentStudentUser` 异常依赖**：
   - 直接调用 `auth()` 而非 `getAuthContext()`
   - 应标注为「待修复：P0-4」

3. **`app/(dashboard)/admin/permissions/page.tsx` 直查 DB 违规**：
   - 应标注为「待修复：P0-1」

4. **`modules/users/actions.ts` 的 `deleteUserAction` 直查 DB**：
   - 应标注为「待修复：P0-2」

5. **缺失的 `loading.tsx`/`error.tsx`**：
   - `admin/roles`、`admin/roles/[id]`、`admin/permissions`、`admin/users` 四个路由

### 5.2 `005_architecture_data.json` 需补充

1. `modules.rbac.dependencies.dependsOn` 增加 `shared/lib/permissions`（`resolvePermissions` 被 `auth.ts` 使用，但 rbac 模块本身不直接依赖，需在 `auth` 节点标注）
2. `modules.rbac.exports.dataAccess` 增加 `getPermissionRoleCounts`（P0-1 新增函数）
3. `modules.users.exports.dataAccess` 增加 `deleteUserById`（P0-2 新增函数）
4. `modules.users.exports.actions` 标注 `updateUserRoleAction` 为 deprecated/删除
5. `app` 路由节点增加缺失的 `loading.tsx`/`error.tsx` 文件

---

## 六、重构方案设计

### 6.1 目标架构

```
app/(dashboard)/admin/
├─ roles/
│  ├─ page.tsx              # RSC: 调用 rbac/data-access.getRoles()
│  ├─ loading.tsx          # 骨架屏
│  ├─ error.tsx            # 错误边界
│  └─ [id]/
│     ├─ page.tsx           # RSC: 调用 rbac/data-access.getRoleById()
│     ├─ loading.tsx
│     └─ error.tsx
├─ permissions/
│  ├─ page.tsx              # RSC: 调用 rbac/data-access.getPermissionRoleCounts()
│  ├─ loading.tsx
│  └─ error.tsx
└─ users/
   ├─ page.tsx              # RSC: 调用 users/data-access.getAdminUsers()
   ├─ loading.tsx
   └─ error.tsx

modules/rbac/
├─ actions.ts               # Server Actions（编排层）
├─ data-access.ts           # 角色 CRUD + 权限统计
├─ data-access-assignments.ts # 用户-角色分配
├─ data-access-permissions.ts # 权限查询（新增 getPermissionRoleCounts）
├─ schema.ts                # Zod 验证
├─ types.ts                 # 类型定义
├─ lib/
│  ├─ permission-catalog.ts # 权限目录常量
│  └─ permission-diff.ts    # 权限差异计算纯函数（新增）
├─ hooks/
│  ├─ use-role-permissions.ts # 选中状态管理 Hook（新增）
│  └─ use-permission-search.ts # 权限搜索过滤 Hook（新增）
└─ components/
   ├─ role-list.tsx
   ├─ role-form-dialog.tsx
   ├─ role-permission-matrix.tsx
   ├─ permission-catalog-view.tsx
   ├─ user-role-assign-dialog.tsx
   ├─ role-management-view.tsx
   ├─ role-detail-edit-button.tsx
   ├─ permission-search-bar.tsx  # 新增
   ├─ permission-impact-badge.tsx # 新增：显示影响用户数
   └─ error-boundary.tsx        # 新增：RBAC 专用错误边界

modules/users/
├─ actions.ts               # 删除 updateUserRoleAction，deleteUserAction 改调 data-access
├─ data-access.ts           # 新增 deleteUserById
└─ components/
   └─ admin-users-view.tsx  # i18n 化，改用 Server Action

shared/lib/
├─ auth-guard.ts            # resolveDataScope 改调各模块 data-access
├─ permissions.ts           # 用类型守卫替代 as
├─ role-utils.ts            # 保留 grade_head/teaching_head 差异
└─ type-guards.ts           # 新增 isPermission/isRole 类型守卫
```

### 6.2 数据服务接口抽象（解耦）

```typescript
// modules/rbac/types.ts 新增

/** 角色数据服务接口 — 供依赖注入使用 */
export interface RoleDataService {
  getRoles(): Promise<RoleWithStats[]>
  getRoleById(id: string): Promise<RoleDetail | null>
  createRole(input: CreateRoleInput): Promise<RoleRecord>
  updateRole(id: string, input: UpdateRoleInput): Promise<RoleRecord>
  deleteRole(id: string): Promise<void>
  setRoleEnabled(id: string, enabled: boolean): Promise<RoleRecord>
  getRolePermissions(roleId: string): Promise<Permission[]>
  setRolePermissions(roleId: string, permissions: Permission[]): Promise<void>
  getPermissionRoleCounts(): Promise<Record<string, number>>
}

/** 用户-角色分配数据服务接口 */
export interface UserRoleAssignmentService {
  getUserRoleNames(userId: string): Promise<string[]>
  assignRolesToUser(userId: string, roleNames: string[]): Promise<void>
  getUserRoleAssignments(params?: {
    page?: number
    pageSize?: number
    search?: string
    role?: string
  }): Promise<PaginatedResult<UserRoleAssignment>>
}

// modules/rbac/data-access.ts 实现 RoleDataService
// modules/rbac/data-access-assignments.ts 实现 UserRoleAssignmentService
```

### 6.3 组合优先的 UI 设计

```tsx
// modules/rbac/components/role-permission-matrix.tsx 重构后

"use client"

import { useRolePermissions } from "../hooks/use-role-permissions"
import { usePermissionSearch } from "../hooks/use-permission-search"
import { PermissionSearchBar } from "./permission-search-bar"
import { PermissionImpactBadge } from "./permission-impact-badge"
import { ErrorBoundary } from "./error-boundary"

interface RolePermissionMatrixProps {
  roleId: string
  roleName: string
  currentPermissions: Permission[]
  userCount: number  // 新增：用于影响提示
  isLocked: boolean
}

export function RolePermissionMatrix({
  roleId,
  roleName,
  currentPermissions,
  userCount,
  isLocked,
}: RolePermissionMatrixProps) {
  const { selected, hasChanges, toggle, toggleGroup, reset } = useRolePermissions(currentPermissions)
  const { query, filteredCatalog, setQuery } = usePermissionSearch(PERMISSION_CATALOG)

  return (
    <ErrorBoundary fallback={<PermissionMatrixError />}>
      <Card>
        <CardHeader>
          <PermissionMatrixHeader
            roleName={roleName}
            isLocked={isLocked}
            selectedCount={selected.size}
            hasChanges={hasChanges}
            userCount={userCount}
          />
          {!isLocked && hasChanges && (
            <PermissionImpactBadge count={userCount} />
          )}
        </CardHeader>
        <CardContent>
          <PermissionSearchBar value={query} onChange={setQuery} />
          <PermissionGroups
            catalog={filteredCatalog}
            selected={selected}
            isLocked={isLocked}
            onToggle={toggle}
            onToggleGroup={toggleGroup}
          />
          <PermissionMatrixActions
            isLocked={isLocked}
            hasChanges={hasChanges}
            onReset={reset}
            onSave={() => handleSave(roleId, selected)}
          />
        </CardContent>
      </Card>
    </ErrorBoundary>
  )
}
```

### 6.4 i18n 翻译文件结构

```json
// shared/i18n/messages/zh-CN/rbac.json（补全后）
{
  "roles": { ... },
  "permissions": {
    "title": "权限目录",
    "description": "系统中定义的所有权限点，按模块分组。",
    "group": { ... },
    "exam": {
      "create": { "label": "创建考试", "desc": "允许创建新考试" },
      "read": { "label": "查看考试", "desc": "允许查看考试列表和详情" }
      // ... 67 个权限点
    }
  },
  "matrix": {
    "search": "搜索权限...",
    "selected": "已选 {count} 项",
    "impact": "修改将影响 {count} 个用户",
    "save": "保存更改",
    "reset": "重置"
  },
  "errors": {
    "loadFailed": "加载失败，请重试",
    "saveFailed": "保存失败：{message}"
  }
}
```

### 6.5 错误与边界处理

```tsx
// modules/rbac/components/error-boundary.tsx

"use client"

import { Component, type ReactNode } from "react"
import { Button } from "@/shared/components/ui/button"
import { AlertCircle } from "lucide-react"

interface Props {
  children: ReactNode
  fallback?: ReactNode
}

interface State {
  hasError: boolean
  error?: Error
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error }
  }

  render(): ReactNode {
    if (this.state.hasError) {
      return this.props.fallback ?? <DefaultErrorFallback error={this.state.error} />
    }
    return this.props.children
  }
}

function DefaultErrorFallback({ error }: { error?: Error }): ReactNode {
  return (
    <div role="alert" className="rounded-md border border-destructive/50 p-4">
      <AlertCircle className="h-5 w-5 text-destructive" aria-hidden="true" />
      <p className="mt-2 text-sm text-destructive">
        {error?.message ?? "加载失败"}
      </p>
      <Button variant="outline" size="sm" className="mt-2" onClick={() => window.location.reload()}>
        重试
      </Button>
    </div>
  )
}
```

```tsx
// app/(dashboard)/admin/roles/loading.tsx

import { Skeleton } from "@/shared/components/ui/skeleton"

export default function Loading(): JSX.Element {
  return (
    <div className="flex h-full flex-col space-y-6 p-8">
      <div className="space-y-2">
        <Skeleton className="h-8 w-48" />
        <Skeleton className="h-4 w-72" />
      </div>
      <Skeleton className="h-96 w-full" />
    </div>
  )
}
```

```tsx
// app/(dashboard)/admin/roles/error.tsx

"use client"

import { useEffect } from "react"
import { Button } from "@/shared/components/ui/button"
import { ShieldAlert } from "lucide-react"

export default function Error({ error, reset }: {
  error: Error & { digest?: string }
  reset: () => void
}): JSX.Element {
  useEffect(() => {
    console.error("Roles page error:", error)
  }, [error])

  return (
    <div className="flex h-full flex-col items-center justify-center space-y-4 p-8">
      <ShieldAlert className="h-12 w-12 text-destructive" aria-hidden="true" />
      <h2 className="text-xl font-semibold">角色管理加载失败</h2>
      <p className="text-sm text-muted-foreground">{error.message}</p>
      <Button onClick={reset}>重试</Button>
    </div>
  )
}
```

### 6.6 可测试性设计

```typescript
// modules/rbac/lib/permission-diff.ts（纯函数，可单测）

import type { Permission } from "@/shared/types/permissions"

export interface PermissionDiff {
  added: Permission[]
  removed: Permission[]
  unchanged: Permission[]
}

export function diffPermissions(
  before: Permission[],
  after: Permission[]
): PermissionDiff {
  const beforeSet = new Set(before)
  const afterSet = new Set(after)

  return {
    added: after.filter((p) => !beforeSet.has(p)),
    removed: before.filter((p) => !afterSet.has(p)),
    unchanged: after.filter((p) => beforeSet.has(p)),
  }
}

export function arePermissionsEqual(
  a: Permission[],
  b: Permission[]
): boolean {
  if (a.length !== b.length) return false
  const set = new Set(a)
  return b.every((p) => set.has(p))
}
```

```typescript
// modules/rbac/hooks/use-role-permissions.ts（纯逻辑 Hook）

"use client"

import { useCallback, useMemo, useState } from "react"
import type { Permission } from "@/shared/types/permissions"
import { arePermissionsEqual } from "../lib/permission-diff"

export function useRolePermissions(initial: Permission[]) {
  const [selected, setSelected] = useState<Set<string>>(new Set(initial))

  const hasChanges = useMemo(
    () => !setsEqual(selected, new Set(initial)),
    [selected, initial]
  )

  const toggle = useCallback((permission: string, checked: boolean) => {
    setSelected((prev) => {
      const next = new Set(prev)
      if (checked) next.add(permission)
      else next.delete(permission)
      return next
    })
  }, [])

  const toggleGroup = useCallback((permissions: string[], checked: boolean) => {
    setSelected((prev) => {
      const next = new Set(prev)
      for (const p of permissions) {
        if (checked) next.add(p)
        else next.delete(p)
      }
      return next
    })
  }, [])

  const reset = useCallback(() => setSelected(new Set(initial)), [initial])

  return { selected, hasChanges, toggle, toggleGroup, reset }
}

function setsEqual<T>(a: Set<T>, b: Set<T>): boolean {
  if (a.size !== b.size) return false
  for (const v of a) if (!b.has(v)) return false
  return true
}
```

### 6.7 配置驱动的可扩展设计

```typescript
// modules/rbac/lib/role-templates.ts（新增）

import type { Permission } from "@/shared/types/permissions"
import { Permissions } from "@/shared/types/permissions"

export interface RoleTemplate {
  id: string
  nameKey: string
  descriptionKey: string
  permissions: Permission[]
}

export const ROLE_TEMPLATES: RoleTemplate[] = [
  {
    id: "homeroom_teacher",
    nameKey: "rbac:templates.homeroom_teacher.name",
    descriptionKey: "rbac:templates.homeroom_teacher.desc",
    permissions: [
      Permissions.EXAM_READ,
      Permissions.HOMEWORK_CREATE,
      Permissions.HOMEWORK_GRADE,
      Permissions.CLASS_READ,
      Permissions.ATTENDANCE_MANAGE,
      Permissions.MESSAGE_SEND,
      Permissions.DASHBOARD_TEACHER_READ,
    ],
  },
  {
    id: "subject_teacher",
    nameKey: "rbac:templates.subject_teacher.name",
    descriptionKey: "rbac:templates.subject_teacher.desc",
    permissions: [
      Permissions.EXAM_CREATE,
      Permissions.QUESTION_CREATE,
      Permissions.HOMEWORK_GRADE,
      Permissions.GRADE_RECORD_MANAGE,
    ],
  },
  // ... 更多模板
]
```

### 6.8 监控埋点接口

```typescript
// shared/lib/analytics.ts（预留接口）

export interface PermissionChangeMetrics {
  action: "role.create" | "role.update" | "role.delete" | "role.set_permissions" | "user.assign_roles"
  targetId: string
  targetType: "role" | "user"
  changes?: {
    added?: number
    removed?: number
  }
  affectedUsers?: number
  durationMs: number
  success: boolean
  errorMessage?: string
}

export async function trackPermissionChange(metrics: PermissionChangeMetrics): Promise<void> {
  // 预留实现：可接入 Sentry / PostHog / 自建埋点
  if (process.env.NODE_ENV === "development") {
    console.log("[permission-change]", metrics)
  }
}
```

---

## 七、实施计划

### 7.1 第一阶段（P0 — 立即修复）

1. **P0-1**：`admin/permissions/page.tsx` 改用 data-access
   - 在 `modules/rbac/data-access-permissions.ts` 新增 `getPermissionRoleCounts()`
   - 页面改为 `import { getPermissionRoleCounts } from "@/modules/rbac/data-access-permissions"`

2. **P0-2**：`deleteUserAction` 改用 data-access
   - 在 `modules/users/data-access.ts` 新增 `deleteUserById(userId: string): Promise<void>`
   - 包含级联清理 sessions、usersToRoles、passwordSecurity
   - actions.ts 改调 `deleteUserById`

3. **P0-3**：`admin-users-view.tsx` 改用 Server Action
   - 删除 `fetch("/api/admin/users/...")` 逻辑
   - 改用 `useActionMutation` + `deleteUserAction`

4. **P0-4**：`getCurrentStudentUser` 改用 `getAuthContext()`
   - `const ctx = await getAuthContext()` → `ctx.userId`

5. **P0-5**：删除 `updateUserRoleAction` 空实现

6. **P0-6**：新增 `loading.tsx`/`error.tsx`
   - 4 个路由各 2 个文件，共 8 个文件

### 7.2 第二阶段（P1 — i18n + 类型安全）

1. **P1-1/P1-2/P1-3**：i18n 化
   - 补全 `rbac.json` 的 67 个权限点标签
   - RBAC 组件改用 `useTranslations`
   - `admin-users-view.tsx` 改用 `useTranslations`

2. **P1-4**：类型守卫
   - `shared/lib/type-guards.ts` 新增 `isPermission(value: unknown): value is Permission`
   - 替换所有 `as Permission` 断言

3. **P1-5**：`resolveDataScope` 改调模块 data-access
   - `classes` 模块新增 `getClassIdsForTeacher(userId)`、`getClassIdsForStudent(userId)`
   - `parent` 模块新增 `getChildrenIdsForParent(userId)`
   - `school` 模块新增 `getGradeIdsForHead(userId)`

4. **P1-6**：`resolveDataScope` 改为配置驱动
   - 新增 `shared/lib/data-scope-resolver.ts`
   - 基于权限点而非角色名判断 scope

5. **P1-7**：Error Boundary
   - 新增 `modules/rbac/components/error-boundary.tsx`
   - 包裹 `RoleList`、`RolePermissionMatrix`、`PermissionCatalogView`

6. **P1-8/P1-9**：安全性增强
   - `deleteUserAction` 校验最后 admin
   - `assignRolesToUser` 过滤禁用角色

### 7.3 第三阶段（P2 — 体验/性能/可扩展）

1. **P2-1**：权限矩阵搜索 + 折叠
2. **P2-2**：角色模板
3. **P2-3**：权限变更影响提示
4. **P2-4**：权限使用统计
5. **P2-5**：a11y 增强
6. **P2-6**：Suspense 流式渲染
7. **P2-7**：监控埋点
8. **P2-8**：`role-utils.ts` 保留角色差异
9. **P2-9**：权限继承
10. **P2-10**：权限变更通知

---

## 八、合规性检查

| 约束 | 当前状态 | 重构后 |
|---|---|---|
| 三层架构 `app → modules → shared` | ❌ app 直查 DB | ✅ 全部走 data-access |
| `app/` 不直接访问数据库 | ❌ 3 处违规 | ✅ 修复 |
| 模块间通过 data-access 通信 | ❌ `auth-guard` 跨模块查表 | ✅ 改调 data-access |
| Server Action 调用 `requirePermission()` | ✅ 已实现 | ✅ 保持 |
| 前端用 `usePermission().hasPermission()` | ✅ 已实现 | ✅ 保持 |
| i18n 适配 | ❌ 大量硬编码 | ✅ 全部提取翻译键 |
| TypeScript 严格模式（无 `any`/`as`） | ❌ 多处 `as` | ✅ 用类型守卫替代 |
| 单文件行数 ≤ 500/800/1000 | ✅ 当前均未超标 | ✅ 保持 |
| `loading.tsx`/`error.tsx` | ❌ 缺失 | ✅ 补全 |
| 架构图同步 | ❌ 有遗漏 | ✅ 同步更新 |

---

## 九、结论

用户权限模块的核心基础设施（`Permissions` 常量、`resolvePermissions`、`requirePermission`、`usePermission`）设计合理，RBAC 模块的 actions/data-access 分层清晰。但存在 **6 个 P0 级架构违规**（app 直查 DB、Server Action 直查 DB、客户端 fetch、认证入口不统一、空实现 Action、缺 loading/error）、**9 个 P1 级问题**（i18n 遗漏、类型断言、跨模块查表、角色硬编码、错误边界缺失、安全隐患）和 **10 个 P2 级改进**（搜索/模板/统计/a11y/性能/监控等）。

建议按 P0 → P1 → P2 顺序实施，P0 必须立即修复以消除安全与架构风险，P1 在本迭代内完成，P2 纳入后续迭代规划。