Module Update

docs/architecture/002_role_based_routing.md

@@ -0,0 +1,115 @@
+# 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" (混合路由)** 策略：
+1.  **Explicit Dashboard Routing**: Dashboards are separated by role in the file structure (e.g., `/teacher/dashboard`).
+2.  **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`**
+
+```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)
+```
+
+## 4. 路由与导航配置 (Navigation Config)
+
+`src/modules/layout/config/navigation.ts` 已经配置好了基于角色的菜单。
+*   当用户访问 `/dashboard` 时，根据角色看到不同的 Dashboard 组件。
+*   点击侧边栏菜单（如 "Exams"）时，跳转到显式路径 `/teacher/exams`。
+
+## 5. 优势 (Benefits)
+1.  **Security**: 可以在 Middleware 或 Layout 层级轻松对 `/admin/*` 路径实施权限控制。
+2.  **Clarity**: 开发者清楚知道“教师的试卷列表页”应该放在 `src/app/(dashboard)/teacher/exams/page.tsx`。
+3.  **Decoupling**: 教师端和学生端的逻辑完全解耦，互不影响。
+
+---
+
+## 6. Action Items (执行计划)
+
+1.  **Refactor Dashboard**: 将 `src/app/(dashboard)/dashboard/page.tsx` 重构为 Dispatcher。
+2.  **Create Role Directories**: 在 `src/app/(dashboard)` 下创建 `teacher`, `student`, `admin` 目录。
+3.  **Move Components**: 确保 `src/modules` 结构清晰。