Module Update

docs/design/003_textbooks_module_implementation.md

@@ -0,0 +1,98 @@
+# Textbooks Module Implementation Details
+
+**Date**: 2025-12-23
+**Author**: DevOps Architect
+**Module**: Textbooks (`src/modules/textbooks`)
+
+---
+
+## 1. 概述 (Overview)
+
+本文档记录了教材模块 (`Textbooks Module`) 的全栈实现细节。该模块负责教材、章节结构及知识点映射的数字化管理，采用了 **Vertical Slice Architecture** 和 **Immersive Workbench** 交互设计。
+
+## 2. 架构设计 (Architecture)
+
+### 2.1 目录结构
+所有教材相关的业务逻辑、数据访问和组件均封装在 `src/modules/textbooks` 下，实现了高度的模块化和隔离。
+
+```
+src/
+├── app/
+│   └── (dashboard)/
+│       └── teacher/
+│           └── textbooks/          # 路由层 (Server Components)
+│               ├── page.tsx        # 列表页
+│               ├── loading.tsx     # 列表骨架屏
+│               └── [id]/           # 详情页
+│                   ├── page.tsx
+│                   └── loading.tsx
+│
+├── modules/
+│   └── textbooks/                  # 业务模块
+│       ├── actions.ts              # Server Actions (增删改)
+│       ├── data-access.ts          # 数据访问层 (Mock/DB)
+│       ├── types.ts                # 类型定义 (Schema-aligned)
+│       └── components/             # 模块私有组件
+│           ├── textbook-content-layout.tsx # [核心] 三栏布局工作台
+│           ├── chapter-sidebar-list.tsx    # 递归章节树
+│           ├── knowledge-point-panel.tsx   # 知识点管理面板
+│           ├── create-chapter-dialog.tsx   # 章节创建弹窗
+│           └── ... (其他交互组件)
+```
+
+### 2.2 渲染策略
+*   **Server Components**: 页面入口 (`page.tsx`) 负责初始数据获取 (Data Fetching)，利用 `Promise.all` 并行拉取教材、章节和知识点数据，实现 "Render-as-you-fetch"。
+*   **Client Components**: 工作台布局 (`textbook-content-layout.tsx`) 标记为 `'use client'`，接管后续的所有交互逻辑（状态管理、局部更新、弹窗控制），提供类似 SPA 的流畅体验。
+
+## 3. UI/UX 细节
+
+### 3.1 布局 (Layout)
+采用 **Immersive Workbench (沉浸式工作台)** 三栏设计：
+*   **左侧 (Navigation)**:
+    *   展示递归的章节树 (`Recursive Tree`)。
+    *   支持折叠/展开，清晰展示教材结构。
+    *   顶部提供 "+" 按钮快速创建新章节。
+*   **中间 (Content)**:
+    *   **阅读模式**: 渲染 Markdown 格式的章节正文。
+    *   **编辑模式**: 提供 `Textarea` 进行内容创作，支持实时保存。
+*   **右侧 (Context)**:
+    *   **上下文感知**: 仅显示当前选中章节的关联知识点。
+    *   提供知识点的快速添加 (`Dialog`) 和删除操作。
+
+### 3.2 交互 (Interactions)
+*   **Selection State**: 点击左侧章节，中间和右侧区域即时更新，无需页面跳转。
+*   **Optimistic UI**: 虽然使用 Server Actions，但通过本地状态 (`useState`) 实现了操作的即时反馈（如保存正文后立即退出编辑模式）。
+*   **Feedback**: 使用 `sonner` (`toast`) 提供操作成功或失败的提示。
+
+## 4. 数据流与逻辑 (Data Flow)
+
+### 4.1 Server Actions
+所有数据变更操作均通过 `src/modules/textbooks/actions.ts` 定义的 Server Actions 处理：
+*   `createChapterAction`: 创建章节（支持嵌套）。
+*   `updateChapterContentAction`: 更新正文内容。
+*   `createKnowledgePointAction`: 创建知识点并自动关联当前章节。
+*   `updateTextbookAction`: 更新教材元数据（Title, Subject, Grade, Publisher）。
+*   `deleteTextbookAction`: 删除教材及其关联数据。
+*   `delete...Action`: 处理删除逻辑。
+
+### 4.2 数据访问层 (Data Access)
+*   **Mock Implementation**: 目前在 `data-access.ts` 中使用内存数组模拟数据库操作，并人为增加了延迟 (`setTimeout`) 以测试 Loading 状态。
+*   **Type Safety**: 定义了严格的 TypeScript 类型 (`Chapter`, `KnowledgePoint`, `UpdateTextbookInput`)，确保前后端数据契约一致。
+
+## 5. 组件复用
+*   使用了 `src/shared/components/ui` 中的 Shadcn 组件：
+    *   `Dialog`, `ScrollArea`, `Card`, `Button`, `Input`, `Textarea`, `Select`.
+    *   `Collapsible` 用于实现递归章节树。
+*   图标库统一使用 `lucide-react`.
+
+## 6. Settings 功能实现 (New)
+*   **入口**: 详情页右上角的 "Settings" 按钮。
+*   **组件**: `TextbookSettingsDialog`。
+*   **功能**:
+    *   **Edit**: 修改教材的基本信息。
+    *   **Delete**: 提供红色删除按钮，二次确认后执行删除并跳转回列表页。
+
+## 7. 后续计划 (Next Steps)
+*   [ ] **富文本编辑器**: 集成 Tiptap 替换现有的 Markdown Textarea，支持更丰富的格式。
+*   [ ] **拖拽排序**: 实现章节树的拖拽排序 (`dnd-kit`)。
+*   [ ] **数据库对接**: 将 `data-access.ts` 中的 Mock 逻辑替换为真实的 `drizzle-orm` 数据库调用。