配置: 初始化 ISOS Agent Teams 软件研发模板

docs/08-数据库设计.md

@@ -0,0 +1,116 @@
+# 数据库设计
+
+**文档版本**: 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): 初始化模板