# 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 (集群)
  ↓
长期: 分库分表 + 读写分离
```