docs/v1.0/server/changelogs/2026-02-03-database-docs-reorganization.md

数据库文档结构重组

日期: 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

执行初始化

# 按推荐顺序初始化
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
• 04-services/README.md
• Project 服务数据库初始化
• AI 服务数据库初始化
• Resource 服务数据库初始化

---

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