CICD/docs/architecture/001_database_schema_design.md

架构决策记录 (ADR): 数据库 Schema 设计方案 v1.0

状态: 已实施 (IMPLEMENTED)
日期: 2025-12-23
作者: 首席系统架构师
背景: Next_Edu 平台 - K12 智慧教育管理系统

---

1. 概述 (Overview)

本文档详细记录了 Next_Edu 平台的数据库 Schema 架构设计。本设计优先考虑 可扩展性 (Scalability)、灵活性 (Flexibility)（针对复杂的嵌套内容）以及 严格的类型安全 (Strict Type Safety)，并完全符合 PRD 中规定的领域驱动设计 (DDD) 原则。

2. 技术栈决策 (Technology Stack Decisions)

组件	选择	理由
数据库	MySQL 8.0+	强大的关系型支持，完善的 JSON 能力，行业标准。
ORM	Drizzle ORM	轻量级，零运行时开销 (Zero-runtime overhead)，业界一流的 TypeScript 类型推断。
ID 策略	CUID2	分布式友好 (k-sortable)，安全（防连续猜测攻击），比 UUID 更短。
认证方案	Auth.js v5	标准化的 OAuth 流程，支持自定义数据库适配器。

---

3. 核心 Schema 领域模型 (Core Schema Domains)

物理文件位于 src/shared/db/schema.ts，逻辑上分为三大领域。

3.1 身份与访问管理 (IAM)

我们采用了 Auth.js 标准表 与 自定义 RBAC 相结合的混合模式。

• 标准表: users, accounts (OAuth), sessions, verificationTokens。
• RBAC 扩展:
  • roles: 定义系统角色（例如：grade_head 年级主任, teacher 老师）。
  • users_to_roles: 多对多关联表。
  • 设计目标: 解决“一人多职”问题（例如：一个老师同时也是年级主任），避免在 users 表中堆砌字段。

3.2 智能题库中心 (Intelligent Question Bank) - 核心

这是最复杂的领域，需要支持无限层级嵌套和富文本内容。

实体定义:

1. questions (题目表):
   • id: CUID2。
   • content: JSON 类型。存储结构化内容（如 SlateJS 节点），支持富文本、图片和公式混排。
   • parentId: 自引用 (Self-Reference)。
     • 若为 NULL: 独立题目 或 “大题干” (Parent)。
     • 若有值: 子题目 (Child)（例如：一篇阅读理解下的第1小题）。
   • type: 枚举 (single_choice, text, composite 等)。
2. knowledge_points (知识点表):
   • 通过 parentId 实现树状结构。
   • 支持无限层级 (学科 -> 章 -> 节 -> 知识点)。
3. questions_to_knowledge_points:
   • 多对多关联。一道题可考察多个知识点；一个知识点可关联数千道题。

3.3 教务教学流 (Academic Teaching Flow)

将物理世界的教学过程映射为数字实体。

• textbooks & chapters: 标准的教材大纲映射。chapters 同样支持通过 parentId 进行嵌套。
• exams: 考试/作业的聚合实体。
• exam_submissions: 代表一名学生的单次答题记录。
• submission_answers: 细粒度的答题详情，记录每道题的答案，支持自动评分 (score) 和人工反馈 (feedback)。

---

4. 关键设计模式 (Key Design Patterns)

4.1 无限嵌套 ("Composite" Pattern)

我们没有为“题干”和“题目”创建单独的表，而是在 questions 表上使用 自引用 (Self-Referencing) 模式。

• 优点:
  • 统一的查询接口 (db.query.questions.findFirst({ with: { children: true } }))。
  • 递归逻辑可统一应用。
  • 当内容结构变化时，迁移更简单。
• 缺点:
  • 需要处理递归查询逻辑（已通过 Drizzle Relations 解决）。

4.2 CUID2 优于 自增 ID

• 安全性: 防止 ID 枚举攻击（猜测下一个用户 ID）。
• 分布式: 支持在客户端或多服务器节点生成，无碰撞风险。
• 性能: k-sortable 特性保证了比随机 UUID v4 更好的索引局部性。

4.3 JSON 存储内容

• 教育内容不仅仅是“文本”。它包含格式、LaTeX 公式和图片引用。
• 使用 JSON 存储允许前端 (Next.js) 直接渲染富组件，无需解析复杂的 HTML 字符串。

---

5. 安全与索引策略 (Security & Indexing Strategy)

索引 (Indexes)

• 外键: 所有外键列 (author_id, parent_id 等) 均显式建立索引。
• 性能:
  • parent_id_idx: 对树形结构的遍历性能至关重要。
  • email_idx: 登录查询的核心索引。

类型安全 (Type Safety)

• 严格的 TypeScript 定义直接从 src/shared/db/schema.ts 导出。
• Zod Schema (待生成) 将与这些 Drizzle 定义保持 1:1 对齐。

---

6. 目录结构 (Directory Structure)

src/shared/db/
├── index.ts       # 单例数据库连接池
├── schema.ts      # 物理表结构定义
└── relations.ts   # 逻辑 Drizzle 关系定义