# 数据库设计

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

---

## 1. 概述

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

### 1.1 设计原则

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

---

## 2. 服务端数据库

### 2.1 ER 图

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

### 2.2 表结构详细定义

<!-- 按以下模板为每个表编写定义 -->

#### <!-- 表名 -->（<!-- 表说明 -->）

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| `id` | TEXT | PK | UUID v4 |
| <!-- 字段 --> | <!-- 类型 --> | <!-- 约束 --> | <!-- 说明 --> |

### 2.3 索引设计

| 表名 | 索引名 | 字段 | 类型 |
|------|--------|------|------|
| <!-- 表 --> | <!-- 索引 --> | <!-- 字段 --> | <!-- 类型 --> |

### 2.4 SQLite DDL 参考

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

---

## 3. 客户端本地数据库

### 3.1 ER 图

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

### 3.2 表结构详细定义

<!-- 按服务端模板格式填写 -->

---

## 4. 数据版本迁移策略

### 4.1 Schema 版本管理

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

```sql
-- 获取当前版本
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): 初始化模板