team/docs/08-数据库设计.md

数据库设计

文档版本: 1.0.0 最后更新: 2026-04-19 维护者: 项目开发团队

---

1. 概述

项目采用模块化数据库架构：各模块各自维护独立的 SQLite 数据库，通过 REST API 通信，禁止跨模块直接访问。

1.1 设计原则

原则	说明
模块独立性	各模块数据库完全隔离，仅通过 API 交换数据
数据安全	敏感数据加密存储
可迁移性	Schema 版本化管理，支持渐进式迁移

---

2. 服务端数据库

2.1 ER 图

erDiagram
    %% 服务端核心实体关系图
    %% EntityA ||--o{ EntityB : "关系描述"
    %% 
    %% EntityA {
    %%     text id PK "主键说明"
    %%     text field1 "字段说明"
    %% }

2.2 表结构详细定义

（）

字段名	类型	约束	说明
id	TEXT	PK	UUID v4

2.3 索引设计

表名	索引名	字段	类型

2.4 SQLite DDL 参考

-- 按以下模板编写建表语句
-- CREATE TABLE TableName (
--     id TEXT PRIMARY KEY,
--     ...
-- );

---

3. 客户端本地数据库

3.1 ER 图

erDiagram
    %% 客户端核心实体关系图

3.2 表结构详细定义

---

4. 数据版本迁移策略

4.1 Schema 版本管理

数据库 Schema 使用 user_version pragma 进行版本管理：

-- 获取当前版本
PRAGMA user_version;

-- 设置版本号（迁移后执行）
PRAGMA user_version = 1;

4.2 迁移脚本规范

迁移脚本位于各模块的 db/migrations/ 目录，按 4 位零填充序号命名。

4.3 迁移执行流程

1. 应用启动时检查 user_version
2. 按 0001、0002... 顺序执行未应用的迁移
3. 每个迁移在事务中执行，失败则回滚
4. 迁移成功后更新 user_version

4.4 向后兼容策略

• 字段添加: 使用 ALTER TABLE ADD COLUMN（带 DEFAULT 值）
• 字段删除: 标记为废弃，保留至少一个大版本
• 表结构变更: 创建新表，数据迁移后删除旧表

---

版本历史:

• v1.0.0 (2026-04-19): 初始化模板