AX Backend - SQLite Block 存储系统

项目概述

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

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

快速开始

1. 环境配置

# 创建数据库
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. 运行测试

python quick_test.py

3. 启动服务

uvicorn app.main:app --reload
# API 文档: http://localhost:8000/docs

核心功能

存储架构

Word 文档 → Block 列表 → 独立 SQLite 数据库

优势:

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

Block 类型（4种）

heading - 标题（1-6级），支持父子关系
paragraph - 段落（富文本，支持空行）
table - 表格（含单元格样式）
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

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

from app.services.word_parser import parse_word_to_blocks

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

DocumentService

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

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. 富文本支持

{
  "content": [
    {"text": "普通文字", "style": {}},
    {"text": "红色加粗", "style": {"color": "FF0000", "bold": true}}
  ]
}

3. 空行处理

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

4. 样式往返转换

Word → Block: 样式提取完整
Block → Word: 样式应用正确
测试验证: 主要样式属性 100% 保留

文件存储

PostgreSQL

documents.content_db_path  -- SQLite 文件路径

File System

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

SQLite Schema

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: 备份两部分：

PostgreSQL documents 表
tmp/ 目录下的所有 .db 文件

技术栈

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

测试

单元测试

python test_sqlite_migration.py

完整测试

python quick_test.py

样式往返测试

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

PROJECT_SUMMARY.md 8.2 KB Histórico Raw