117 lines
2.5 KiB
Markdown
117 lines
2.5 KiB
Markdown
# 数据库设计
|
||
|
||
**文档版本**: 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): 初始化模板
|