'CLAUDE更新'

CLAUDE.md

@@ -4,7 +4,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 项目概述
 
-CJYDocs 是一个基于 Node.js + Express 的轻量级 Markdown 文档管理和渲染系统，采用前后端分离架构。核心特点是通过解析 `docs/index.md` 配置文件实现文档的层级化管理。
+CJYDocs 是一个基于 Node.js + Express 的轻量级 Markdown 文档管理和渲染系统，采用前后端分离架构。核心特点包括：
+- 通过解析 `docs/index.md` 配置文件实现文档的层级化管理
+- 支持在线编辑功能，智能光标定位
+- 全文搜索、TOC 目录、响应式设计
+- 高性能优化：DOM 缓存、事件委托、IntersectionObserver
 
 ## 开发命令
 
@@ -48,7 +52,7 @@ npm install
 2.2: 子文档名.md
 ```
 
-**解析逻辑** (`server.js:200-236`):
+**解析逻辑** (`server.js:247-282`):
 - `[分类名]` → 对应 `docs/` 下的目录名
 - `编号: 文档名.md` → 文档项，支持多级编号（如 1.1.1）
 - `level` 通过点号数量计算：`1` = level 0, `1.1` = level 1, `1.1.1` = level 2
@@ -61,7 +65,7 @@ npm install
 
 ### 前端架构
 
-**DOM 缓存策略** (`reader.js:5-13`):
+**DOM 缓存策略** (`reader.js:8-22`):
 ```javascript
 const DOM = {
     loading: null,
@@ -69,11 +73,15 @@ const DOM = {
     docNav: null,
     toc: null,
     leftSidebar: null,
-    rightSidebar: null
+    rightSidebar: null,
+    editBtn: null,
+    editorContainer: null,
+    markdownEditor: null,
+    // ... 更多元素
 };
 ```
 
-所有频繁访问的 DOM 元素都通过此对象缓存，避免重复查询。
+所有频繁访问的 DOM 元素都通过此对象缓存，避免重复查询。缓存采用懒加载策略：首次使用时查询并缓存，后续直接使用。
 
 **事件委托模式**:
 - 导航点击：在 `#doc-nav` 父元素上监听，而非每个导航项
@@ -84,29 +92,34 @@ const DOM = {
 
 所有 API 都在 `server.js` 中定义：
 
-- `GET /api/structure` - 获取完整文档结构（解析 index.md）
+- `GET /api/structure` - 获取完整文档结构（解析 index.md，带5秒缓存）
 - `GET /api/category/:category` - 获取指定分类信息
 - `GET /api/doc/:category/:docName` - 获取文档内容
+- `PUT /api/doc/:category/:docName` - 保存文档内容（在线编辑）
 - `GET /api/search/:category?q=xxx&currentDoc=yyy` - 搜索文档
 
 **安全机制**：
 所有用户输入都经过 `sanitizePath()` 清理和 `validatePath()` 验证，防止路径遍历攻击。
 
+**缓存策略**：
+`index.md` 解析结果缓存5秒（`server.js:9-12`），减少文件系统读取频率。
+
 ### 关键功能实现
 
 #### 1. Markdown 渲染
-使用 `marked.js` + `highlight.js`，配置在 `reader.js:15-29`
+使用 `marked.js` + `highlight.js`，配置在 `reader.js:25-38`
 
 #### 2. TOC 自动生成
-`reader.js:176-231` - 遍历渲染后的 HTML，提取所有 h1-h6 标题，使用 `IntersectionObserver` 实现滚动监听
+`reader.js:190-270` - 遍历渲染后的 HTML，提取所有 h1-h6 标题，使用 `IntersectionObserver` 实现滚动监听
 
 #### 3. 搜索功能
-- 后端：逐行扫描所有 `.md` 文件，返回匹配的行号和上下文片段
-- 前端：使用 `TreeWalker` API 精确定位到匹配的文本节点并滚动
+- 后端：`server.js:159-244` - 逐行扫描所有 `.md` 文件，返回匹配的行号和上下文片段（最多5个）
+- 前端：`reader.js:443-785` - 使用 `TreeWalker` API 精确定位到匹配的文本节点并滚动
 - 搜索历史保存在 `localStorage`，按分类隔离
+- 搜索防抖 500ms，点击搜索结果后自动关闭搜索框和侧边栏
 
 #### 4. 移动端侧边栏交互
-`reader.js:314-355` - 移动端侧边栏管理逻辑：
+`reader.js:359-440` - 移动端侧边栏管理逻辑：
 - **互斥展开**：点击一侧目录按钮时，自动隐藏另一侧已展开的目录，确保同一时间最多只有一个侧边栏展开
 - **点击外部关闭**：点击文档内容区域或其他目录以外的地方时，所有展开的侧边栏自动隐藏
 - **响应式行为**：此功能仅在移动端和平板（≤1024px）上启用，桌面端不受影响
@@ -118,22 +131,65 @@ const DOM = {
 - 搜索防抖：500ms，减少 40% 的 API 请求
 - `IntersectionObserver`：替代 scroll 事件，性能提升 20-30%
 
+#### 6. 在线编辑功能
+`reader.js:820-1095` + `server.js:113-156` - 完整的在线文档编辑系统：
+
+**编辑器特性**：
+- **智能光标定位** (`reader.js:869-988`)：根据当前阅读位置（标题、段落）在编辑器中自动定位到对应的 markdown 源码行
+- **无缝模式切换**：编辑/预览模式切换时保持滚动位置，自动隐藏渲染内容并显示编辑器
+- **实时保存**：通过 `PUT /api/doc/:category/:docName` 保存到服务器，保存后自动重新渲染并更新 TOC
+
+**编辑流程**：
+```
+点击编辑按钮 → 进入编辑模式
+    ↓
+findVisibleElement() - 找到视口中可见的元素
+    ↓
+positionCursorByElement() - 在编辑器中定位到对应行
+    ↓
+用户编辑内容
+    ↓
+saveDocument() → PUT /api/doc/:category/:docName
+    ↓
+服务器验证路径 + 保存文件
+    ↓
+前端重新渲染 + 退出编辑模式
+```
+
+**安全验证**：
+- 文件必须已存在（不能创建新文件）
+- 内容类型必须为字符串
+- 所有路径经过 `sanitizePath()` 和 `validatePath()` 验证
+
+**用户体验细节**：
+- 浮动编辑按钮（右下角）
+- 防重复提交（保存时禁用按钮）
+- 成功提示 Toast（2秒后自动消失）
+- 完整的错误处理和提示
+
 ## 文件结构
 
 ```
 cjydocs/
-├── server.js              # Express 后端，包含所有 API 和 index.md 解析逻辑
+├── server.js              # Express 后端（288行）
+│                          # - 所有 API 端点（GET/PUT）
+│                          # - index.md 解析逻辑（带5秒缓存）
+│                          # - 安全验证函数（sanitizePath, validatePath）
+│                          # - 搜索引擎实现
 ├── docs/
 │   ├── index.md          # 文档结构配置文件（核心）
 │   └── 分类名/
-│       └── 文档.md       # 实际文档内容
+│       └── 文档.md       # 实际文档内容（可通过在线编辑修改）
 └── public/
-    ├── index.html        # 首页（显示分类列表）
-    ├── reader.html       # 阅读器页面（三栏布局）
+    ├── index.html        # 首页（显示分类列表）35行
+    ├── reader.html       # 阅读器页面（三栏布局+编辑器）129行
     ├── css/style.css     # 统一样式
     └── js/
-        ├── index.js      # 首页逻辑
-        └── reader.js     # 阅读器逻辑（DOM缓存、事件委托、搜索）
+        ├── index.js      # 首页逻辑（70行）
+        └── reader.js     # 阅读器核心逻辑（1113行）
+                          # - DOM缓存、事件委托
+                          # - 搜索、TOC、侧边栏交互
+                          # - 在线编辑器（智能光标定位）
 ```
 
 ## 代码修改指南
@@ -157,6 +213,13 @@ cjydocs/
 2. 在对应目录下创建/删除 `.md` 文件
 3. 无需重启服务器，刷新页面即可
 
+### 修改/扩展编辑功能
+1. 所有文档保存操作必须通过 PUT API，并经过安全验证
+2. 编辑器光标定位依赖 `findVisibleElement()` 和 `positionCursorByElement()` 函数
+3. 修改编辑行为时注意保持 `currentMarkdownContent` 和 `savedScrollPosition` 的同步
+4. 编辑模式切换时需要正确管理 DOM 显示/隐藏状态
+5. 不要允许编辑功能创建新文件，只能编辑已存在的文档
+
 ## 安全注意事项
 
 **路径遍历防护**：
@@ -215,6 +278,13 @@ if (!validatePath(docPath, docsDir)) {
 2. 是否频繁查询 DOM（应使用 `DOM` 缓存对象）
 3. 是否对搜索等高频操作使用了防抖
 
+### 编辑功能无法保存
+检查：
+1. 文件是否存在（编辑功能不能创建新文件）
+2. 浏览器控制台是否有 PUT API 错误
+3. 服务器是否返回 403（路径验证失败）或 400（数据格式错误）
+4. 文件权限是否允许服务器写入
+
 ## 技术栈版本
 
 - Node.js: v14+