Files

SpecialX f8dfd1dddd docs: 全项目架构审查与文档体系重写

- 全项目逐文件审查: 4 份审计报告(shared/core-business/management/new-modules)
- 重写 004 架构影响地图: 图优先 + 模块依赖图 + 数据流 + 调用链 + 问题分级
- 更新 005 结构化数据: 新增 architectureOverview/moduleDependencyGraph/knownIssues/dbTables 节点
- 更新 006 功能清单: 143 项功能标注实现状态, P0 覆盖率 80%->92%
- 更新 007 差距审计: v2->v3, P0 完成 69%->84%, 新增架构技术债章节
- 更新 001 项目概览: 6 角色/54 权限/26 模块/54 表
- 新增 docs/README.md 文档索引
- 归档 11 份过时文档(002x2/003/designx8) 标注
- 更新 work_log

2026-06-17 21:51:32 +08:00

5.1 KiB

Raw Blame History

⚠️ 已归档文档 本文档是 2025-12-23 提出的角色路由 RFC（Status: PROPOSED），描述的是路由策略提案。当前该提案已全部实现——/admin、/teacher、/student、/parent、/management 角色域路由已落地，详见 004 架构影响地图的 routes 章节。保留用于历史参考，不再维护。

Architecture RFC: Role-Based Routing & Directory Structure

Status: PROPOSED Date: 2025-12-23 Context: Next_Edu supports multiple roles (Admin, Teacher, Student, Parent) with distinct UI/UX requirements.

1. 核心问题 (The Problem)

目前项目结构中，页面与角色耦合不清。

/dashboard 目前硬编码为教师视图。
不同角色的功能模块（如“课程”）可能有完全不同的视图和逻辑（教师管理课程 vs 学生学习课程）。
缺乏统一的路由规范指导开发人员“把页面放哪里”。

2. 解决方案：基于角色的路由策略 (Role-Based Routing Strategy)

我们采用 "Hybrid Routing" (混合路由) 策略：

Explicit Dashboard Routing: Dashboards are separated by role in the file structure (e.g., /teacher/dashboard).
Explicit Role Scopes (显式角色域): 具体的业务功能页面放入 /teacher, /student, /admin 专属路径下。

2.1 目录结构 (Directory Structure)

src/app/(dashboard)/
├── layout.tsx                # Shared App Shell (Sidebar, Header)
├── dashboard/
│   └── page.tsx              # [Redirector] Redirects to role-specific dashboard
│
├── teacher/                  # 教师专属路由域
│   ├── dashboard/            # Teacher Dashboard
│   │   └── page.tsx
│   ├── classes/
│   │   └── page.tsx
│   ├── exams/
│   │   └── page.tsx
│   └── textbooks/
│       └── page.tsx
│
├── student/                  # 学生专属路由域
│   ├── dashboard/            # Student Dashboard
│   │   └── page.tsx
│   ├── learning/
│   │   └── page.tsx
│   └── schedule/
│       └── page.tsx
│
└── admin/                    # 管理员专属路由域
    ├── dashboard/            # Admin Dashboard
    │   └── page.tsx
    ├── users/
    └── school/

2.2 Dashboard Routing Logic

/dashboard 页面现在作为一个 Portal (入口) 或 Redirector (重定向器)，而不是直接渲染内容。

Example: src/app/(dashboard)/dashboard/page.tsx

import { redirect } from "next/navigation";
import { auth } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();
  const role = session?.user?.role;

  switch (role) {
    case "teacher":
      redirect("/teacher/dashboard");
    case "student":
      redirect("/student/dashboard");
    case "admin":
      redirect("/admin/dashboard");
    default:
      redirect("/login");
  }
}

3. 模块化组织 (Module Organization)

为了避免 src/app 变得臃肿，具体的业务组件必须存放在 src/modules 中。

src/modules/
├── teacher/                  # 教师业务领域
│   ├── components/           # 仅教师使用的组件 (e.g., GradebookTable)
│   ├── hooks/
│   └── actions.ts
│
├── student/                  # 学生业务领域
│   ├── components/           # (e.g., CourseProgressCard)
│   └── ...
│
├── shared/                   # 跨角色共享
│   ├── components/           # (e.g., CourseCard - if generic)

src/modules/layout/config/navigation.ts 已经配置好了基于角色的菜单。

当用户访问 /dashboard 时，根据角色看到不同的 Dashboard 组件。
点击侧边栏菜单（如 "Exams"）时，跳转到显式路径 /teacher/exams。

5. 优势 (Benefits)

Security: 可以在 Middleware 或 Layout 层级轻松对 /admin/* 路径实施权限控制。
Clarity: 开发者清楚知道“教师的试卷列表页”应该放在 src/app/(dashboard)/teacher/exams/page.tsx。
Decoupling: 教师端和学生端的逻辑完全解耦，互不影响。

6. Action Items (执行计划)

Refactor Dashboard: 将 src/app/(dashboard)/dashboard/page.tsx 重构为 Dispatcher。
Create Role Directories: 在 src/app/(dashboard) 下创建 teacher, student, admin 目录。
Move Components: 确保 src/modules 结构清晰。

7. RBAC 扩展（2026-03-02）

为满足班级维度的权限差异，在教师角色下新增学科粒度的访问控制：

班主任（Class Head Teacher）：可查看班级内所有学科相关的数据与统计。
任课老师（Subject Teacher）：仅可查看自己被分配的学科相关内容。
实现要点：
- 数据访问层通过“会话用户身份”与“学科分配表”联合过滤，防止越权。
- 页面与组件保持不变，由后端/数据访问层保证返回范围正确的聚合数据。

5.1 KiB Raw Blame History Unescape Escape