# AX Backend - SQLite Block 存储系统

## 项目概述

基于 **SQLite 结构化 Block 存储** 的高性能文档管理系统，支持 Word 文档的解析、编辑和导出。

**版本**: 2.0.0  
**更新日期**: 2026-07-03

---

## 快速开始

### 1. 环境配置
```bash
# 创建数据库
CREATE DATABASE ax_backend;

# 配置环境变量 (.env)
DATABASE_URL=postgresql://postgres:password@localhost:5432/ax_backend
TEMP_DIR=./tmp

# 安装依赖
pip install -r requirements.txt

# 初始化数据库
alembic upgrade head
```

### 2. 运行测试
```bash
python quick_test.py
```

### 3. 启动服务
```bash
uvicorn app.main:app --reload
# API 文档: http://localhost:8000/docs
```

---

## 核心功能

### 存储架构
```
Word 文档 → Block 列表 → 独立 SQLite 数据库
```

**优势:**
- ✅ 单 Block 更新（O(1) 时间复杂度）
- ✅ 完整的富文本支持
- ✅ 精确的 Block 级编辑
- ✅ 强大的结构化查询
- ✅ 稀疏排序策略（极少触发重排）

### Block 类型（4种）

1. **heading** - 标题（1-6级），支持父子关系
2. **paragraph** - 段落（富文本，支持空行）
3. **table** - 表格（含单元格样式）
4. **image** - 图片（Base64 Data URL）

### 样式系统

三层样式继承：
```
Word 样式 (word_style) → Block 样式 (style) → 片段样式 (content[].style)
```

**支持的样式属性:**
- 字符级: `font_name`, `font_size`, `bold`, `italic`, `underline`, `color`
- 段落级: `align` (left, center, right, justify)
- 图片级: `width`, `height`, `unit`, `align`

---

## API 端点

### Documents
```
POST   /api/v1/documents              # 上传 Word 文档
GET    /api/v1/documents/{id}         # 获取文档（支持 ?includeBlocks=true）
DELETE /api/v1/documents/{id}         # 删除文档
GET    /api/v1/documents              # 列出文档
```

### Blocks
```
GET    /api/v1/documents/{id}/blocks              # 获取所有 blocks
GET    /api/v1/documents/{id}/blocks/{blockId}   # 获取单个 block
PUT    /api/v1/documents/{id}/blocks/{blockId}   # 更新 block
DELETE /api/v1/documents/{id}/blocks/{blockId}   # 删除 block
GET    /api/v1/documents/{id}/blocks/search      # 搜索 blocks
GET    /api/v1/documents/{id}/blocks/toc         # 获取目录树
GET    /api/v1/documents/{id}/blocks/stats       # 获取统计信息
```

### Export
```
POST   /api/v1/export                # 导出 Word 文档
GET    /api/v1/export-records        # 导出记录列表
```

---

## 核心类

### ContentDB
```python
from app.services.content_db import ContentDB

with ContentDB(db_path) as content_db:
    blocks = content_db.get_blocks()
    content_db.update_block(block_id, {"content": "新内容"})
    results = content_db.search_blocks("关键词")
```

### Word Parser
```python
from app.services.word_parser import parse_word_to_blocks

blocks = parse_word_to_blocks(Path("document.docx"))
# 返回 Block 列表
```

### DocumentService
```python
from app.services.document_service import DocumentService

# 创建文档 (Word → Blocks → SQLite)
doc = await svc.create_document(CreateDocumentRequest(...))

# 获取文档（可选加载 blocks）
doc = await svc.get_document(doc_id, include_blocks=True)
```

### ExportService
```python
from app.services.export_service import blocks_to_docx_bytes

# Blocks → Word
docx_bytes = blocks_to_docx_bytes(blocks, style_map, style_data)
```

---

## 项目结构

```
ax-backend-v1/
├── app/
│   ├── api/v1/          # API 路由
│   ├── core/            # 核心配置
│   ├── models/          # 数据库模型
│   ├── schemas/         # Pydantic Schemas
│   └── services/        # 业务逻辑
│       ├── content_db.py       # SQLite 操作
│       ├── word_parser.py      # Word 解析
│       ├── document_service.py # 文档服务
│       └── export_service.py   # 导出服务
├── migrations/          # Alembic 迁移
├── docs/                # 设计文档
├── tmp/                 # SQLite 数据库存储
│   └── {user_id}/sqlite/{doc_id}.db
└── requirements.txt
```

---

## 性能数据

| 操作 | 时间复杂度 | 说明 |
|------|-----------|------|
| 查询单个标题 | O(log n) | 索引查询 |
| 构建目录树 | O(n) | SQL 查询 |
| 更新单个段落 | O(1) | UPDATE 单行 |
| 插入新段落 | O(1) | INSERT 单行 |
| 搜索 blocks | O(log n) | WHERE 查询 |

---

## 重要特性

### 1. 稀疏排序
- 初始间隔：100
- 插入/删除：O(1) 时间复杂度
- 局部重排：仅在间隙耗尽时触发

### 2. 富文本支持
```json
{
  "content": [
    {"text": "普通文字", "style": {}},
    {"text": "红色加粗", "style": {"color": "FF0000", "bold": true}}
  ]
}
```

### 3. 空行处理
- 空行与普通段落结构完全一致
- 不需要特殊标记
- 样式完全保留（对齐、字体等）

### 4. 样式往返转换
- Word → Block: 样式提取完整
- Block → Word: 样式应用正确
- 测试验证: 主要样式属性 100% 保留

---

## 文件存储

### PostgreSQL
```sql
documents.content_db_path  -- SQLite 文件路径
```

### File System
```
tmp/
  └── {user_id}/
      └── sqlite/
          └── {doc_id}.db  -- 独立 SQLite 数据库
```

### SQLite Schema
```sql
CREATE TABLE document_blocks (
    id TEXT PRIMARY KEY,
    block_order INTEGER NOT NULL,
    type TEXT NOT NULL,
    level INTEGER,
    "index" INTEGER,
    content TEXT,
    word_style TEXT,
    style TEXT,
    metadata TEXT
);
```

---

## 常见问题

### Q: SQLite 文件存储在哪里？
**A**: `tmp/{user_id}/sqlite/{doc_id}.db`

### Q: 如何判断空行？
**A**: `block['type'] == 'paragraph' and block['content'] == ''`

### Q: 支持的最大文档大小？
**A**: 理论无限制，SQLite 单文件最大 281 TB

### Q: 如何备份文档？
**A**: 备份两部分：
1. PostgreSQL `documents` 表
2. `tmp/` 目录下的所有 `.db` 文件

---

## 技术栈

- **Python 3.10+**
- **FastAPI** - Web 框架
- **SQLAlchemy** - ORM
- **Alembic** - 数据库迁移
- **python-docx** - Word 文档处理
- **PostgreSQL** - 主数据库
- **SQLite** - Block 存储

---

## 测试

### 单元测试
```bash
python test_sqlite_migration.py
```

### 完整测试
```bash
python quick_test.py
```

### 样式往返测试
```bash
python test_style_extraction.py
python test_empty_lines.py
```

---

## 已修复的问题

### 1. Pydantic 警告
- **问题**: `alias` 参数废弃警告
- **修复**: 使用 `validation_alias` 和 `serialization_alias`
- **影响文件**: `app/schemas/document.py`, `app/schemas/export.py`, `app/schemas/block.py`

### 2. 空行样式丢失
- **问题**: 空行没有应用样式，上下间距不一致
- **修复**: 始终为段落添加 run（即使内容为空）
- **影响文件**: `app/services/export_service.py`

### 3. 空行特殊标记
- **问题**: 空行有 `is_empty` 特殊标记，结构不一致
- **修复**: 移除特殊标记，空行与普通段落结构完全一致
- **影响文件**: `app/services/word_parser.py`

---

## 文档

### 设计文档
- `docs/content-sqlite-design.md` - SQLite 设计文档
- `docs/sqlite-implementation-plan.md` - 实施方案
- `docs/text-editor-backend-api.md` - API 文档

### 技术文档
- `EMPTY_LINE_STRUCTURE_FIX.md` - 空行结构统一修复
- `PYDANTIC_ALIAS_FIX.md` - Pydantic 警告修复
- `ALL_TYPES_SPARSE_SORTING.md` - 稀疏排序实现
- `NUMBERING_FORMAT_SUPPORT.md` - 编号格式支持

---

## 下一步计划

### 阶段 1（可选）
- [ ] 样式管理功能
- [ ] 样式 CRUD API
- [ ] 样式预览功能

### 功能优化（可选）
- [ ] Block 级别权限控制
- [ ] Block 批量操作 API
- [ ] Block 历史版本记录
- [ ] 大文档性能优化（分页加载）
- [ ] SQLite 全文搜索（FTS5）

---

## 总结

✅ **高性能** - SQLite Block 存储，快速查询和更新  
✅ **完整的富文本** - JSON 数组存储格式信息  
✅ **精确编辑** - 单个 Block 更新  
✅ **清晰架构** - 分层设计，易于维护  
✅ **完善测试** - 单元测试和集成测试  
✅ **往返转换** - Word ↔ Block 完全可逆

**项目准备就绪，可以开始使用！** 🚀

---

**维护者**: 后端团队  
**更新日期**: 2026-07-03  
**版本**: 2.0.0