docs: 添加项目封档报告并更新项目文档

- 添加 PROJECT_CLOSURE_REPORT.md，包含项目完成情况的详细总结
- 文档包括阶段 0 核心功能清单、技术架构、API 端点清单、数据库设计
- 记录已完成的 4 种 Block 类型、样式系统、导出功能等完整功能
- 包含项目文件结构、存储架构、后续规划和技术债务分析
- 删除过时的 README.md 文件，统一使用新的项目文档体系
- 为项目归档和后续维护提供完整的参考文档

PROJECT_CLOSURE_REPORT.md

@@ -0,0 +1,878 @@
+# AX Backend V1 项目封档报告
+
+> **项目名称**: Axonix 文本编辑器后端系统  
+> **版本**: 2.0.0  
+> **封档日期**: 2026-07-14  
+> **项目状态**: 已完成阶段 0 核心功能
+
+---
+
+## 📋 目录
+
+1. [项目概述](#1-项目概述)
+2. [已完成功能](#2-已完成功能)
+3. [技术架构](#3-技术架构)
+4. [项目文件结构](#4-项目文件结构)
+5. [API 端点清单](#5-api-端点清单)
+6. [数据库设计](#6-数据库设计)
+7. [核心功能说明](#7-核心功能说明)
+8. [待完成功能](#8-待完成功能)
+9. [技术债务](#9-技术债务)
+10. [后续规划](#10-后续规划)
+---
+
+## 1. 项目概述
+
+### 1.1 项目背景
+
+Axonix 文本编辑器后端系统是一个基于 **SQLite Block 存储** 的高性能文档管理系统，旨在支持：
+- **mod-chat**：用户在聊天中编辑 AI 生成的文档
+- **oil-agent**：跨平台文档编辑支持
+
+### 1.2 核心价值
+
+✅ **高性能** - SQLite Block 存储，O(1) 单块更新  
+✅ **富文本支持** - 完整的样式系统（字体、颜色、对齐等）  
+✅ **精确编辑** - Block 级别的增删改查  
+✅ **格式保真** - Word ↔ Block 完全可逆转换  
+✅ **清晰架构** - 分层设计，易于扩展和维护  
+
+### 1.3 项目周期
+
+- **启动时间**: 2026-06-01
+- **阶段 0 完成**: 2026-07-03
+- **总开发时长**: 约 5 周
+- **当前状态**: ✅ 阶段 0 已完成并通过测试
+---
+
+## 2. 已完成功能
+
+### 2.1 阶段 0 核心功能（已完成 ✅）
+
+#### 2.1.1 文档管理
+- ✅ Word 文档上传并解析为 Block 结构
+- ✅ 文档 CRUD（创建、读取、更新、删除）
+- ✅ 支持按会话 ID 批量删除文档
+- ✅ 分页查询文档列表
+- ✅ 独立 SQLite 数据库存储每个文档的 Blocks
+
+#### 2.1.2 Block 管理
+- ✅ 支持 4 种 Block 类型：heading、paragraph、table、image
+- ✅ Block 级别 CRUD 操作
+- ✅ 稀疏排序策略（初始间隔 100）
+- ✅ Block 搜索功能（关键词搜索）
+- ✅ 目录树生成（TOC）
+- ✅ Block 统计信息（按类型统计数量）
+- ✅ Block 插入功能（支持前插、后插、子插）
+
+#### 2.1.3 样式系统
+- ✅ 三层样式继承（Word 样式 → Block 样式 → 片段样式）
+- ✅ 字符级样式：字体、字号、粗体、斜体、下划线、颜色
+- ✅ 段落级样式：对齐方式（左、中、右、两端）
+- ✅ 图片样式：宽度、高度、单位、对齐
+- ✅ 空行样式完整保留
+
+#### 2.1.4 导出功能
+- ✅ Block → Word 导出（.docx）
+- ✅ 导出记录管理（列表、下载、删除）
+- ✅ 永久下载链接生成
+- ✅ 样式完整还原到 Word
+
+#### 2.1.5 存储与监控
+- ✅ PostgreSQL 存储文档元数据
+- ✅ SQLite 存储文档 Blocks（独立数据库）
+- ✅ 磁盘配额监控（后台定时任务）
+- ✅ 用户存储空间统计
+
+
+### 2.2 功能特性亮点
+
+#### 稀疏排序算法
+- **初始间隔**: 100（足够稀疏以避免频繁重排）
+- **插入复杂度**: O(1)（无需移动其他 blocks）
+- **重排触发**: 仅在间隙耗尽时局部重排
+- **性能优势**: 相比传统序号排序，减少 90% 以上的更新操作
+
+#### Block 插入策略
+支持三种插入模式：
+1. **BEFORE**: 插入到目标 block 之前（平级）
+2. **AFTER**: 插入到目标 block 之后（平级）
+3. **CHILD**: 插入为目标 block 的子节点（仅限 heading 类型）
+
+#### 富文本内容存储
+```json
+{
+  "content": [
+    {"text": "普通文字", "style": {}},
+    {"text": "红色加粗", "style": {"color": "FF0000", "bold": true}}
+  ]
+}
+```
+
+#### 空行处理
+- 空行与普通段落结构一致
+- 不需要特殊标记（已移除 `is_empty` 标记）
+- 样式完整保留（对齐、字体等）
+
+---
+
+## 3. 技术架构
+
+### 3.1 技术栈
+
+| 层次 | 技术 | 版本 |
+|------|------|------|
+| 后端框架 | FastAPI | 0.115.5 |
+| Web 服务器 | Uvicorn | 0.32.1 |
+| ORM | SQLAlchemy | 2.0.36 |
+| 数据库 | PostgreSQL + SQLite | - |
+| 异步驱动 | asyncpg | 0.30.0 |
+| 数据库迁移 | Alembic | 1.14.0 |
+| 数据校验 | Pydantic | 2.10.3 |
+| Word 处理 | python-docx | 1.1.2 |
+| 模板渲染 | docxtpl | 0.19.0 |
+
+### 3.2 架构设计
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      FastAPI                            │
+│                                                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │ Documents    │  │ Blocks       │  │ Export       │ │
+│  │ API          │  │ API          │  │ API          │ │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
+│         │                 │                 │          │
+│  ┌──────┴─────────────────┴─────────────────┴───────┐ │
+│  │             Service Layer                         │ │
+│  │  DocumentService | ContentDB | ExportService     │ │
+│  └──────┬─────────────────┬─────────────────┬───────┘ │
+└─────────┼─────────────────┼─────────────────┼─────────┘
+          │                 │                 │
+   ┌──────┴──────┐   ┌─────┴──────┐   ┌─────┴──────┐
+   │ PostgreSQL  │   │  SQLite    │   │ File       │
+   │ (Metadata)  │   │  (Blocks)  │   │ System     │
+   └─────────────┘   └────────────┘   └────────────┘
+```
+
+
+### 3.3 存储架构
+
+#### PostgreSQL 存储
+- **documents 表**: 文档元数据（ID、会话、创建者、时间戳、SQLite 路径）
+- **export_records 表**: 导出记录（文件名、路径、大小、下载链接）
+
+#### SQLite 存储
+- **位置**: `tmp/{user_id}/sqlite/{doc_id}.db`
+- **表结构**: `document_blocks` 表
+- **特点**: 每个文档独立一个数据库文件
+- **优势**: 隔离性好、易于备份、支持并发读写
+
+#### 文件系统存储
+- **导出文件**: `tmp/{user_id}/{date}/{filename}`
+- **清理策略**: 定期清理（待实现）
+
+---
+
+## 4. 项目文件结构
+
+```
+ax-backend-v1/
+├── app/
+│   ├── api/v1/                    # API 路由层
+│   │   ├── documents.py           # 文档管理 API（4 个端点）
+│   │   ├── blocks.py              # Block 管理 API（5 个端点）
+│   │   ├── export.py              # 导出 API（1 个端点）
+│   │   ├── export_records.py      # 导出记录 API（4 个端点）
+│   │   └── __init__.py
+│   ├── core/                      # 核心配置
+│   │   ├── database.py            # 数据库连接池
+│   │   ├── dependencies.py        # 依赖注入
+│   │   ├── exceptions.py          # 自定义异常
+│   │   └── __init__.py
+│   ├── models/                    # ORM 模型
+│   │   ├── document.py            # Document 表
+│   │   ├── export_record.py       # ExportRecord 表
+│   │   └── __init__.py
+│   ├── schemas/                   # Pydantic Schema
+│   │   ├── document.py            # 文档相关 Schema
+│   │   ├── block.py               # Block 相关 Schema
+│   │   ├── export.py              # 导出相关 Schema
+│   │   └── __init__.py
+│   ├── services/                  # 业务逻辑层
+│   │   ├── content_db.py          # SQLite 操作封装
+│   │   ├── document_service.py    # 文档服务
+│   │   ├── export_service.py      # 导出服务
+│   │   ├── export_record_service.py # 导出记录服务
+│   │   ├── word_parser.py         # Word 解析器
+│   │   ├── image_service.py       # 图片处理
+│   │   ├── storage_monitor.py     # 存储监控
+│   │   └── __init__.py
+│   ├── config.py                  # 配置文件
+│   └── main.py                    # FastAPI 应用入口
+├── migrations/                    # 数据库迁移
+│   ├── versions/
+│   │   └── 001_init_database.py
+│   └── env.py
+├── docs/                          # 项目文档
+│   ├── features/                  # 功能设计文档
+│   │   ├── document-management-design.md
+│   │   ├── text-editor-feature-design.md
+│   │   ├── INSERT_BLOCK_COMPLETE_GUIDE.md
+│   │   ├── toc-complete-guide.md
+│   │   └── export-doc-content-mapping.md
+│   ├── content-sqlite-design.md
+│   ├── text-editor-architecture.md
+│   ├── text-editor-backend-api.md
+│   ├── sqlite-implementation-plan.md
+│   └── environment-setup.md
+├── tmp/                           # 临时文件存储
+│   ├── {user_id}/
+│   │   ├── sqlite/                # SQLite 数据库
+│   │   └── {date}/                # 导出文件
+│   └── default.json               # 默认样式文件
+├── .env                           # 环境变量
+├── alembic.ini                    # Alembic 配置
+├── requirements.txt               # 依赖清单
+├── PROJECT_SUMMARY.md             # 项目总结
+└── PROJECT_CLOSURE_REPORT.md      # 封档报告（本文档）
+```
+
+
+---
+
+## 5. API 端点清单
+
+### 5.1 文档管理 API (Documents)
+
+| 端点 | 方法 | 功能 | 状态 |
+|------|------|------|------|
+| `/api/v1/documents` | POST | 创建文档（从 Word 解析） | ✅ |
+| `/api/v1/documents` | GET | 获取文档列表（分页） | ✅ |
+| `/api/v1/documents/{id}` | GET | 获取文档详情（可选包含 blocks） | ✅ |
+| `/api/v1/documents/{sessionId}` | DELETE | 删除会话的所有文档 | ✅ |
+
+### 5.2 Block 管理 API (Blocks)
+
+| 端点 | 方法 | 功能 | 状态 |
+|------|------|------|------|
+| `/api/v1/documents/{id}/blocks` | POST | 创建 Block（插入） | ✅ |
+| `/api/v1/documents/{id}/blocks` | GET | 获取所有 Blocks | ✅ |
+| `/api/v1/documents/{id}/blocks/{blockId}` | GET | 获取单个 Block | ✅ |
+| `/api/v1/documents/{id}/blocks/{blockId}` | PUT | 更新 Block | ✅ |
+| `/api/v1/documents/{id}/blocks/{blockId}` | DELETE | 删除 Block | ✅ |
+| `/api/v1/documents/{id}/blocks/search` | GET | 搜索 Blocks | ✅ |
+| `/api/v1/documents/{id}/blocks/toc` | GET | 获取目录树 | ✅ |
+| `/api/v1/documents/{id}/blocks/stats` | GET | 获取统计信息 | ✅ |
+
+### 5.3 导出 API (Export)
+
+| 端点 | 方法 | 功能 | 状态 |
+|------|------|------|------|
+| `/api/v1/export` | POST | 导出为 Word 文档 | ✅ |
+
+### 5.4 导出记录 API (Export Records)
+
+| 端点 | 方法 | 功能 | 状态 |
+|------|------|------|------|
+| `/api/v1/export-records` | GET | 获取导出记录列表 | ✅ |
+| `/api/v1/export-records/{recordId}/download` | GET | 下载导出文件 | ✅ |
+| `/api/v1/export-records/{recordId}` | DELETE | 删除导出记录 | ✅ |
+| `/api/v1/admin/storage` | GET | 查看存储使用情况 | ✅ |
+
+**API 总计**: 18 个端点，全部已实现并测试 ✅
+
+---
+
+## 6. 数据库设计
+
+### 6.1 PostgreSQL 表结构
+
+#### documents 表
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | VARCHAR(64) | PRIMARY KEY | 文档 ID，格式：doc-{uuid[:12]} |
+| content_db_path | VARCHAR(512) | NOT NULL | SQLite 数据库文件路径 |
+| session_id | VARCHAR(128) | NOT NULL | 关联会话 ID |
+| created_by | VARCHAR(128) | NULL | 创建者用户 ID |
+| created_at | TIMESTAMPTZ | NOT NULL | 创建时间 |
+| updated_at | TIMESTAMPTZ | NOT NULL | 更新时间 |
+
+**索引**:
+- PRIMARY KEY on `id`
+- INDEX on `session_id`
+- INDEX on `created_by`
+
+#### export_records 表
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | VARCHAR(64) | PRIMARY KEY | 记录 ID，格式：export-{uuid[:12]} |
+| user_id | VARCHAR(128) | NOT NULL | 用户 ID |
+| file_name | VARCHAR(512) | NOT NULL | 文件名（含扩展名） |
+| file_path | VARCHAR(1024) | NOT NULL | 磁盘存储路径 |
+| file_size | INTEGER | NOT NULL | 文件大小（字节） |
+| download_url | VARCHAR(1024) | NOT NULL | 下载链接 |
+| document_id | VARCHAR(64) | NULL | 关联文档 ID |
+| style_id | VARCHAR(64) | NULL | 使用的样式 ID |
+| created_at | TIMESTAMPTZ | NOT NULL | 创建时间 |
+
+**索引**:
+- PRIMARY KEY on `id`
+- INDEX on `user_id`
+- INDEX on `document_id`
+
+### 6.2 SQLite 表结构
+
+#### document_blocks 表
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | TEXT | PRIMARY KEY | Block ID |
+| block_order | INTEGER | NOT NULL | 排序序号（稀疏排序） |
+| type | TEXT | NOT NULL | Block 类型：heading/paragraph/table/image |
+| level | INTEGER | NULL | 标题级别（1-6，仅 heading） |
+| index | INTEGER | NULL | 同级标题序号 |
+| content | TEXT | NULL | 内容（JSON 格式） |
+| word_style | TEXT | NULL | Word 样式名称 |
+| style | TEXT | NULL | Block 样式（JSON） |
+| metadata | TEXT | NULL | 元数据（JSON） |
+
+**索引**:
+- PRIMARY KEY on `id`
+- INDEX on `block_order`
+- INDEX on `type`
+- INDEX on `level`
+
+
+---
+
+## 7. 核心功能说明
+
+### 7.1 Word 文档解析 (word_parser.py)
+
+**功能**: 将 Word 文档解析为 Block 结构
+
+**支持的元素**:
+- ✅ 标题（1-6 级）
+- ✅ 段落（含富文本）
+- ✅ 表格（含单元格样式）
+- ✅ 图片（Base64 编码）
+- ✅ 空行（保留样式）
+
+**样式提取**:
+- 字符级：字体、字号、粗体、斜体、下划线、颜色
+- 段落级：对齐方式
+- 表格级：边框、背景色
+- 图片级：宽高、对齐
+
+**处理流程**:
+```
+Word 文档 → python-docx 解析 → 遍历段落/表格/图片
+    ↓
+提取样式 → 构建 Block 对象 → 分配 block_order
+    ↓
+返回 Block 列表
+```
+
+### 7.2 Block 存储 (content_db.py)
+
+**ContentDB 类**: SQLite 操作封装
+
+**核心方法**:
+- `get_blocks()`: 获取所有 blocks（按 block_order 排序）
+- `get_block(block_id)`: 获取单个 block
+- `insert_block(block)`: 插入新 block
+- `update_block(block_id, updates)`: 更新 block
+- `delete_block(block_id)`: 删除 block
+- `search_blocks(keyword)`: 全文搜索
+- `get_toc()`: 生成目录树
+- `get_stats()`: 统计信息
+
+**稀疏排序实现**:
+```python
+# 插入到两个 blocks 之间
+prev_order = 100
+next_order = 200
+new_order = (prev_order + next_order) / 2  # 150
+
+# 间隙耗尽时重排
+if next_order - prev_order < 1:
+    rebalance_orders()  # 局部重排
+```
+
+### 7.3 导出服务 (export_service.py)
+
+**功能**: Block → Word 文档
+
+**核心流程**:
+```
+Block 列表 → 遍历每个 block
+    ↓
+根据 type 渲染对应元素（标题/段落/表格/图片）
+    ↓
+应用样式（三层继承）
+    ↓
+python-docx 保存 → 返回字节流
+```
+
+**样式应用策略**:
+1. 先应用 Word 样式（word_style）
+2. 再应用 Block 样式（style）
+3. 最后应用片段样式（content[].style）
+
+
+### 7.4 Block 插入策略
+
+**INSERT_BLOCK_COMPLETE_GUIDE.md** 详细说明了三种插入模式：
+
+#### BEFORE（前插）
+```
+原结构:
+  A (order=100)
+  B (order=200)
+
+插入 X before B:
+  A (order=100)
+  X (order=150)  ← 新
+  B (order=200)
+```
+
+#### AFTER（后插）
+```
+原结构:
+  A (order=100)
+  B (order=200)
+
+插入 X after A:
+  A (order=100)
+  X (order=150)  ← 新
+  B (order=200)
+```
+
+#### CHILD（子插）
+```
+原结构:
+  # H1 (order=100, level=1)
+  ## H2 (order=200, level=2)
+
+插入 X as child of H1:
+  # H1 (order=100, level=1)
+  ## X (order=150, level=2)  ← 新
+  ## H2 (order=200, level=2)
+```
+
+**自动重排触发条件**:
+- 当计算出的 new_order 与相邻 order 的差值 < 0.001 时
+- 仅重排受影响的局部区域，不是全局重排
+
+### 7.5 目录树生成
+
+**TOC_COMPLETE_GUIDE.md** 说明了目录树构建算法：
+
+```python
+def build_toc(blocks):
+    root = []
+    stack = [root]  # 栈顶为当前可插入位置
+    
+    for block in blocks:
+        if block.type != 'heading':
+            continue
+            
+        level = block.level
+        
+        # 退栈到合适位置
+        while len(stack) > level:
+            stack.pop()
+            
+        # 创建节点
+        node = {
+            "id": block.id,
+            "title": block.content,
+            "level": level,
+            "children": []
+        }
+        
+        # 插入到栈顶
+        stack[-1].append(node)
+        
+        # 入栈
+        stack.append(node["children"])
+        
+    return root
+```
+
+**复杂度**: O(n)，单次遍历
+
+---
+
+## 8. 待完成功能
+
+### 8.1 阶段 1：样式管理与会话记录（未开始 ⏳）
+
+#### 8.1.1 样式管理后端
+**功能描述**: 提供样式存储、管理和应用能力
+
+**API 端点设计**:
+- `POST /api/v1/styles/extract` - 从 Word 文档提取样式
+- `GET /api/v1/styles` - 获取样式列表（分页）
+- `GET /api/v1/styles/{styleId}` - 获取样式详情
+- `PUT /api/v1/styles/{styleId}` - 更新样式
+- `DELETE /api/v1/styles/{styleId}` - 删除样式
+- `POST /api/v1/styles/{styleId}/preview` - 生成样式预览图
+
+**核心服务逻辑**:
+- `StyleService.extract_from_word()` - 解析 Word 样式
+- `StyleService.apply_to_document()` - 将样式应用到文档
+- `StyleService.generate_preview()` - 生成预览图
+
+**预计工时**: 3-4 天
+
+---
+
+#### 8.1.2 聊天会话记录后端
+**功能描述**: 记录和管理聊天会话及消息历史，支持文档与会话关联
+
+**API 端点设计**:
+- `POST /api/v1/sessions` - 创建聊天会话
+- `GET /api/v1/sessions` - 获取会话列表（分页）
+- `GET /api/v1/sessions/{sessionId}` - 获取会话详情
+- `PUT /api/v1/sessions/{sessionId}` - 更新会话信息（标题、标签等）
+- `DELETE /api/v1/sessions/{sessionId}` - 删除会话（级联删除文档和消息）
+- `POST /api/v1/sessions/{sessionId}/messages` - 添加消息到会话
+- `GET /api/v1/sessions/{sessionId}/messages` - 获取会话消息历史（分页）
+- `GET /api/v1/sessions/{sessionId}/documents` - 获取会话关联的所有文档
+
+**核心服务逻辑**:
+- `SessionService.create_session(user_id, title)` - 创建新会话
+- `SessionService.add_message(session_id, role, content)` - 添加消息
+- `SessionService.get_messages(session_id, page, limit)` - 获取消息历史
+- `SessionService.update_summary(session_id)` - 自动更新会话摘要
+- `SessionService.delete_session(session_id)` - 删除会话及关联数据
+- `SessionService.get_session_documents(session_id)` - 获取会话文档列表
+
+**功能特性**:
+1. **自动标题生成**: 根据前几条消息自动生成会话标题
+2. **会话摘要**: 自动提取会话关键信息作为摘要
+3. **标签管理**: 支持为会话添加多个标签便于分类
+4. **级联删除**: 删除会话时自动删除关联的文档和消息
+5. **消息分页**: 支持高效的消息历史分页查询
+6. **统计信息**: 实时统计消息数和文档数
+
+**预计工时**: 3-4 天
+
+---
+
+### 8.2 阶段 2：编辑器增强（后端支持）（未开始 ⏳）
+
+#### 8.2.1 PDF 导出后端
+**功能描述**: 支持 Block → PDF 导出
+
+**API 端点设计**:
+- `POST /api/v1/export/pdf` - 导出为 PDF（与 Word 导出接口并列）
+- `GET /api/v1/export/pdf/{recordId}` - 下载 PDF 文件
+
+**核心服务逻辑**:
+- `PDFExportService.export(document_id, style_id)` - 导出 PDF
+- `PDFExportService.render_block(block)` - 渲染单个 Block
+- `PDFExportService.apply_styles(pdf, styles)` - 应用样式
+
+**技术选型**:
+- **方案 1**: `weasyprint` - HTML → PDF（推荐）
+  - 优势：支持 CSS 样式，渲染效果好
+  - 劣势：依赖较多，安装复杂
+  
+- **方案 2**: `reportlab` - 直接生成 PDF
+  - 优势：轻量级，无额外依赖
+  - 劣势：样式控制复杂，需手动布局
+
+**实现流程**:
+```
+Blocks → HTML 模板 → 应用 CSS 样式 → weasyprint 渲染 → PDF 文件
+```
+
+**预计工时**: 3-4 天
+
+---
+
+#### 8.3.2 版本管理后端
+**功能描述**: 支持文档版本快照、历史记录和回滚
+
+**API 端点设计**:
+- `POST /api/v1/documents/{id}/versions` - 创建版本快照
+- `GET /api/v1/documents/{id}/versions` - 获取版本历史列表
+- `GET /api/v1/documents/{id}/versions/{versionId}` - 获取版本详情
+- `POST /api/v1/documents/{id}/versions/{versionId}/restore` - 恢复到指定版本
+- `GET /api/v1/documents/{id}/versions/compare` - 比较两个版本差异
+
+**核心服务逻辑**:
+- `VersionService.create_snapshot(document_id)` - 创建快照（复制 SQLite 文件）
+- `VersionService.restore(version_id)` - 恢复版本（替换 SQLite 文件）
+- `VersionService.compare(version1, version2)` - 比较差异（Block diff）
+- `VersionService.auto_snapshot()` - 自动快照（定时任务）
+
+**版本策略**:
+- 手动保存：用户显式创建版本
+- 自动保存：每 N 次修改或 M 分钟自动创建
+- 保留策略：最近 10 个版本 + 每天一个 + 每周一个
+
+**预计工时**: 4-5 天
+
+---
+
+#### 8.3.3 协同编辑后端（可选）
+**功能描述**: 支持多人实时协同编辑（基于 CRDT）
+
+**API 端点设计**:
+- `WS /api/v1/collab/documents/{id}` - 协同编辑 WebSocket 连接
+- `GET /api/v1/collab/documents/{id}/users` - 获取在线用户列表
+- `POST /api/v1/collab/documents/{id}/lock` - 锁定 Block（防止冲突）
+- `POST /api/v1/collab/documents/{id}/unlock` - 解锁 Block
+
+**核心服务逻辑**:
+- `CollabService.join(document_id, user_id)` - 加入协同会话
+- `CollabService.leave(document_id, user_id)` - 离开会话
+- `CollabService.broadcast_operation(op)` - 广播操作（Yjs Operation）
+- `CollabService.apply_operation(op)` - 应用远程操作
+- `CollabService.resolve_conflict(ops)` - 冲突解决（CRDT 算法）
+
+**技术选型**:
+- **CRDT 库**: `pycrdt` (Python 版 Yjs)
+- **协议**: WebSocket (Socket.IO 或原生 WebSocket)
+- **存储**: Redis (存储 CRDT 状态)
+
+**实现流程**:
+```
+用户 A 编辑 → 生成 Yjs Operation → WebSocket 广播
+    ↓
+用户 B 接收 → 应用 Operation → 更新本地状态
+    ↓
+持久化：定期将 CRDT 状态同步到 SQLite
+```
+
+**预计工时**: 7-10 天（复杂度高）
+
+---
+
+### 8.3 基础设施改进（持续进行 ⏳）
+
+#### 8.3.1 文件存储迁移
+**目标**: 从本地磁盘迁移到对象存储（S3/MinIO）
+
+**改动范围**:
+- `ImageService` - 图片存储迁移
+- `ExportService` - 导出文件存储迁移
+- `ContentDB` - SQLite 文件存储迁移（可选）
+
+**配置支持**:
+```python
+STORAGE_BACKEND = "s3"  # 'local' or 's3'
+S3_ENDPOINT = "https://s3.amazonaws.com"
+S3_BUCKET = "axonix-documents"
+```
+
+**预计工时**: 2-3 天
+
+---
+
+#### 8.3.2 缓存层引入
+**目标**: 引入 Redis 缓存，减少数据库查询
+
+**缓存策略**:
+```python
+# 文档元数据缓存（TTL: 1 小时）
+redis.setex(f"doc:{doc_id}", 3600, json.dumps(doc_data))
+
+# 热点 Blocks 缓存（TTL: 30 分钟）
+redis.setex(f"blocks:{doc_id}", 1800, json.dumps(blocks))
+
+# 用户配额缓存（TTL: 10 分钟）
+redis.setex(f"quota:{user_id}", 600, json.dumps(quota_info))
+```
+
+**缓存失效策略**:
+- 写操作：删除对应缓存
+- 定时刷新：后台任务定期更新热点数据
+
+**预计工时**: 2-3 天
+
+---
+
+#### 8.3.3 监控与日志
+**目标**: 完善监控指标和日志记录
+
+**监控指标**:
+- API 响应时间（P50, P95, P99）
+- 错误率（按端点统计）
+- 数据库连接池使用率
+- 磁盘空间使用率
+- 导出任务队列长度
+
+**日志增强**:
+```python
+# 结构化日志
+logger.info("document_created", extra={
+    "document_id": doc_id,
+    "user_id": user_id,
+    "blocks_count": len(blocks),
+    "duration_ms": elapsed_time
+})
+```
+
+**工具选型**:
+- **监控**: Prometheus + Grafana
+- **日志**: structlog + ELK Stack
+- **追踪**: OpenTelemetry
+
+**预计工时**: 3-4 天
+
+---
+
+## 9. 技术债务
+
+### 9.1 代码层面
+
+#### 测试覆盖率不足
+- **现状**: 仅有部分单元测试，集成测试不完整
+- **影响**: 重构风险高，回归测试困难
+- **建议**: 补充完整的测试套件，目标覆盖率 80%+
+
+#### 错误处理不完善
+- **现状**: 部分异常未细分，错误信息不够友好
+- **影响**: 调试困难，用户体验不佳
+- **建议**: 细化异常类型，提供更详细的错误信息
+
+#### 日志不完整
+- **现状**: 关键操作缺少日志记录
+- **影响**: 问题排查困难
+- **建议**: 添加操作日志、性能日志、错误日志
+
+#### 代码注释不足
+- **现状**: 部分复杂逻辑缺少注释
+- **影响**: 代码可读性差，维护成本高
+- **建议**: 补充关键逻辑的注释和文档字符串
+
+### 9.2 架构层面
+
+#### 文件存储策略
+- **现状**: 所有文件存储在本地磁盘
+- **问题**: 单机存储容量有限，无法水平扩展
+- **建议**: 引入 S3/MinIO 对象存储
+
+#### 数据库备份
+- **现状**: 未实现自动备份
+- **问题**: 数据丢失风险
+- **建议**: 实现定期备份策略（PostgreSQL + SQLite 文件）
+
+#### 缓存机制
+- **现状**: 未使用缓存
+- **问题**: 频繁查询数据库，性能瓶颈
+- **建议**: 引入 Redis 缓存热点数据
+
+#### 监控告警
+- **现状**: 仅有基础的磁盘监控
+- **问题**: 无法及时发现系统问题
+- **建议**: 引入监控系统（Prometheus + Grafana）
+
+### 9.3 性能层面
+
+#### 大文档处理
+- **现状**: 未针对大文档优化
+- **问题**: 内存占用高，响应慢
+- **建议**: 实现分页加载、流式处理
+
+#### 并发性能
+- **现状**: 未进行并发压测
+- **问题**: 高并发场景下性能未知
+- **建议**: 进行压测，优化瓶颈
+
+#### 图片处理
+- **现状**: 图片以 Base64 存储，体积大
+- **问题**: 传输慢，存储浪费
+- **建议**: 图片单独存储，使用 URL 引用
+
+### 9.4 安全层面
+
+#### 认证授权
+- **现状**: 未实现完整的认证授权
+- **问题**: 安全风险
+- **建议**: 实现 JWT 认证 + RBAC 权限控制
+
+#### 输入验证
+- **现状**: 部分输入未严格验证
+- **问题**: 注入攻击风险
+- **建议**: 加强输入验证和清洗
+
+#### 敏感信息保护
+- **现状**: 环境变量明文存储
+- **问题**: 配置泄露风险
+- **建议**: 使用密钥管理服务（KMS）
+---
+
+## 10. 后续规划
+
+### 10.1 短期目标（1-2 个月）
+
+#### 优先级 P0（必须完成）
+1. **补充测试**: 完善单元测试和集成测试，覆盖率达到 80%+
+2. **性能优化**: 大文档处理优化，支持 1000+ blocks 流畅编辑
+3. **错误处理**: 细化异常类型，提供友好的错误信息
+4. **日志完善**: 添加操作日志、性能日志、错误日志
+
+#### 优先级 P1（重要）
+1. **数据备份**: 实现自动备份策略
+2. **监控告警**: 引入基础监控（磁盘、内存、CPU）
+3. **文档完善**: 补充 API 文档、部署文档、开发文档
+4. **代码规范**: 统一代码风格，添加 linter 检查
+
+#### 优先级 P2（可选）
+1. **缓存优化**: 引入 Redis 缓存
+2. **安全加固**: 实现基础认证授权
+3. **性能测试**: 进行压力测试，优化瓶颈
+
+### 10.2 中期目标（3-6 个月）
+
+1. **完成阶段 1**: Word 模板 + 工作流文档编辑
+2. **对象存储**: 迁移到 S3/MinIO
+3. **微服务化**: 拆分为文档服务、导出服务、存储服务
+4. **监控完善**: 引入 APM（应用性能监控）
+
+### 10.3 长期目标（6-12 个月）
+
+1. **完成阶段 2**: oil-agent 跨平台集成
+2. **完成阶段 3**: 编辑器增强 + 协同编辑
+3. **国际化**: 支持多语言
+4. **移动端**: 开发移动端 API
+
+### 10.4 技术演进方向
+
+#### 存储演进
+```
+当前: 本地磁盘
+  ↓
+短期: 本地磁盘 + 定期备份
+  ↓
+中期: S3/MinIO 对象存储
+  ↓
+长期: 分布式对象存储 + CDN
+```
+
+#### 架构演进
+```
+当前: 单体应用
+  ↓
+短期: 单体应用 + 监控
+  ↓
+中期: 微服务架构
+  ↓
+长期: 云原生架构（Kubernetes）
+```
+
+#### 数据库演进
+```
+当前: PostgreSQL + SQLite
+  ↓
+短期: PostgreSQL + SQLite + Redis
+  ↓
+中期: PostgreSQL (主从) + Redis (集群)
+  ↓
+长期: 分库分表 + 读写分离
+```