# 数据库文档结构重组

> **日期**: 2026-02-03  
> **类型**: 文档重组  
> **影响范围**: 所有后端服务数据库文档

---

## 变更概述

对 `docs/requirements/backend/04-services/` 目录下的数据库初始化文档进行了全面重组，创建了统一的总览文档，并清理了临时文件和重复内容。

---

## 变更详情

### 新增文件

1. **database-init-overview.md** - 数据库初始化总览文档
   - 提供所有 4 个服务（User、Resource、AI、Project）的统一入口
   - 包含 31 张表的完整索引
   - 跨服务表关联说明
   - 初始化顺序和脚本

2. **README.md** - 服务文档目录说明
   - 文档结构导航
   - 使用指南
   - 维护规范

### 重命名文件

- `database-init.md` → `database-init-user-backup.md`
  - 原因：顶层文件实际是 User 服务内容，与 `user/database-init.md` 重复
  - 状态：标记为待清理

### 删除文件

1. `project/database-init-part2.md` - 临时文件（已合并到主文档）
2. `project/database-init-remaining.md` - 临时文件（已合并到主文档）

### 保持不变

以下文件保持独立，作为各服务的详细设计文档：

- `user/database-init.md` - User 服务（10 张表）
- `resource/database-init.md` - Resource 服务（2 张表）
- `ai/database-init.md` - AI 服务（3 张表）
- `project/database-init.md` - Project 服务（16 张表）

---

## 新文档结构

```
04-services/
├── README.md                          # 📖 文档导航（新增）
├── database-init-overview.md          # 🎯 总览文档（新增）
├── database-init-user-backup.md       # ⚠️ 待清理
│
├── user/
│   └── database-init.md               # User 服务详细设计
│
├── resource/
│   └── database-init.md               # Resource 服务详细设计
│
├── ai/
│   └── database-init.md               # AI 服务详细设计
│
└── project/
    └── database-init.md               # Project 服务详细设计
```

---

## 文档特性

### database-init-overview.md 包含

1. **服务模块概览** - 4 个服务的表数量、功能、关键特性
2. **全局表结构索引** - 31 张表按功能分类和服务分组
3. **跨服务表关联** - 5 类跨服务关联关系和验证规则
4. **技术栈规范** - 9 项全局规范（UUID v7、TIMESTAMPTZ、SMALLINT 枚举等）
5. **初始化顺序** - 分阶段初始化脚本和完整 bash 脚本
6. **维护指南** - 添加新服务、修改表结构、文档同步的流程

### README.md 包含

1. **文档结构** - 清晰的目录树
2. **快速导航** - 所有文档的链接表格
3. **使用指南** - 查看文档和执行初始化的步骤
4. **文档维护** - 修改设计和添加服务的流程
5. **文档规范** - 必须包含的章节和命名规范

---

## 使用方式

### 查看数据库设计

**推荐流程**:

1. 先看总览: `database-init-overview.md`
2. 再看详情: 对应服务的 `database-init.md`

### 执行初始化

```bash
# 按推荐顺序初始化
docker exec jointo-server-app python scripts/db_migrate.py upgrade --service user
docker exec jointo-server-app python scripts/db_migrate.py upgrade --service resource
docker exec jointo-server-app python scripts/db_migrate.py upgrade --service ai
docker exec jointo-server-app python scripts/db_migrate.py upgrade --service project
```

---

## 优势

### 1. 统一入口

- 一个文档查看所有服务的表结构
- 快速了解系统整体数据库设计
- 方便跨服务查询和对比

### 2. 保持独立

- 各服务详细文档独立维护
- 避免单个文件过大
- 便于服务团队独立更新

### 3. 清晰导航

- README 提供完整的文档地图
- 快速定位需要的文档
- 明确的使用指南

### 4. 避免重复

- 删除临时文件和重复内容
- 标记待清理的历史文件
- 保持文档结构清晰

---

## 后续工作

### 待清理

- [ ] 确认 `database-init-user-backup.md` 可以删除后清理

### 待完善

- [ ] 在总览文档中添加表关系 ER 图
- [ ] 补充各服务的数据量预估和性能指标
- [ ] 添加数据库监控和告警建议

---

## 影响评估

### 对开发的影响

- ✅ **正面影响**: 更容易查找和理解数据库设计
- ✅ **正面影响**: 初始化顺序更清晰
- ⚠️ **需要注意**: 更新文档链接（如有引用旧路径）

### 对文档维护的影响

- ✅ **正面影响**: 文档结构更清晰
- ✅ **正面影响**: 维护流程更规范
- ✅ **正面影响**: 减少重复内容

---

## 相关文档

- [database-init-overview.md](../../requirements/backend/04-services/database-init-overview.md)
- [04-services/README.md](../../requirements/backend/04-services/README.md)
- [Project 服务数据库初始化](./2026-02-03-project-service-database-init.md)
- [AI 服务数据库初始化](./2026-02-03-ai-service-database-init.md)
- [Resource 服务数据库初始化](./2026-02-03-resource-service-database-init.md)

---

**变更人**: 后端架构团队  
**审核人**: 技术负责人  
**状态**: ✅ 已完成