# 后端服务文档总览

> **最后更新**：2026-01-27

---

## ⚠️ 重要架构变更通知

### 数据库设计约束（2026-01-27 更新）

本项目采用以下数据库设计约束，所有服务文档中的表定义已更新以符合这些规范：

#### 1. 禁止物理外键约束

- ❌ **数据库层禁止创建 `FOREIGN KEY` 约束**
- ✅ **所有引用完整性在应用层 Service/Repository 中验证**
- ✅ **所有逻辑关联字段必须手动创建索引**

**原因**：为分库分表做准备、提升写入性能、增强系统扩展性

#### 2. 禁止数据库默认值生成 UUID

- ❌ **禁止使用 `DEFAULT gen_uuid_v7()`**
- ❌ **禁止使用 `server_default=text("gen_uuid_v7()")`**
- ✅ **必须在应用层通过 `default_factory=generate_uuid` 生成**

**原因**：统一 UUID 生成逻辑、便于分布式环境管理

#### 3. 应用层引用完整性保证

移除物理外键约束后，采用三层机制保证数据完整性：

**Repository 层**：提供 `exists()`, `batch_exists()` 等基础验证方法

```python
async def exists(self, id: UUID) -> bool:
    """检查记录是否存在（排除软删除）"""
    query = select(self.model.id).where(
        self.model.id == id,
        self.model.deleted_at.is_(None)
    ).limit(1)
    result = await self.db.execute(query)
    return result.scalar_one_or_none() is not None
```

**Service 层**：在所有操作中验证引用完整性

```python
async def create_project(self, user_id: UUID, data: ProjectCreate):
    # 验证所有外键引用
    if not await self.user_repo.exists(data.owner_id):
        raise NotFoundError("所有者用户不存在")
    
    if data.folder_id:
        if not await self.folder_repo.exists(data.folder_id):
            raise NotFoundError("文件夹不存在")
    
    # 使用事务创建
    async with self.db.begin():
        project = await self.project_repo.create(data)
        # 处理关联数据...
```

**后台任务**：定期检查数据完整性

```python
@shared_task
async def check_orphan_records():
    """检查孤儿记录并告警"""
    # 检查并修复数据完整性问题
```

#### 4. 级联删除处理

删除操作必须在应用层明确处理级联关系：

```python
async def delete_project(self, project_id: UUID, permanent: bool = False):
    """删除项目 - 应用层级联处理"""
    async with self.db.begin():
        if permanent:
            # 物理删除所有关联数据
            await self.project_member_repo.delete_by_project(project_id)
            await self.project_share_repo.delete_by_project(project_id)
            # ... 其他关联数据
            await self.project_repo.delete(project_id)
        else:
            # 软删除
            await self.project_repo.soft_delete(project_id)
            await self.project_member_repo.soft_delete_by_project(project_id)
```

#### 5. 文档说明

- 各服务文档中的表定义**仅供参考**，实际以代码为准（`server/app/models/`）
- 表定义中不再包含 `REFERENCES` 外键约束
- 表定义中不再包含 `DEFAULT gen_uuid_v7()` 数据库默认值
- Python Model 定义中使用 `default_factory=generate_uuid` 生成 UUID

**详细规范**：
- [数据库设计规范](../../../.claude/skills/jointo-tech-stack/references/database.md)
- [服务文档 UUID 定义清理](../../../docs/server/changelogs/2026-01-27-service-docs-uuid-cleanup.md)

---

## 目录结构

本目录按业务领域组织后端服务文档，共分为 4 个子目录：

### 📁 [user/](./user/) - 用户相关服务

用户认证、授权、积分管理、充值支付等服务。

- [用户管理服务](./user/user-service.md)
- [短信验证码服务](./user/sms-service.md)
- [微信登录服务](./user/wechat-service.md)
- [算力积分管理服务](./user/credit-service.md)
- [充值管理服务](./user/recharge-service.md)
- [支付服务](./user/payment-service.md)

### 📁 [project/](./project/) - 项目相关服务

项目管理、文件夹、剧本、分镜、分镜看板、评论等服务。

- [项目管理服务](./project/project-service.md)
- [项目资源服务](./project/project-resource-service.md)
- [文件夹管理服务](./project/folder-service.md)
- [剧本管理服务](./project/screenplay-service.md)
- [分镜管理服务](./project/storyboard-service.md)
- [分镜看板管理服务](./project/storyboard-board-service.md)
- [评论管理服务](./project/comment-service.md)
- [导出服务](./project/export-service.md)

### 📁 [resource/](./resource/) - 资源相关服务

素材资源、附件、文件存储等服务。

- [资源管理服务](./resource/resource-service.md)
- [附件管理服务](./resource/attachment-service.md)
- [文件存储服务](./resource/file-storage-service.md)

### 📁 [ai/](./ai/) - AI 相关服务

AI 生成、视频处理等服务。

- [AI 服务](./ai/ai-service.md)
- [视频服务](./ai/video-service.md)

---

## 服务依赖关系

```
用户服务层
├── user-service (核心)
├── sms-service (依赖: 第三方短信平台)
├── wechat-service (依赖: 微信开放平台)
├── credit-service (依赖: user-service)
├── recharge-service (依赖: credit-service, payment-service)
└── payment-service (依赖: 微信支付、支付宝)

项目服务层
├── project-service (核心)
├── project-resource-service (依赖: project-service, resource-service)
├── folder-service (依赖: project-service)
├── screenplay-service (依赖: project-service)
├── storyboard-service (依赖: project-service, screenplay-service)
├── storyboard-board-service (依赖: project-service)
├── comment-service (依赖: project-service, user-service)
└── export-service (依赖: project-service, video-service)

资源服务层
├── resource-service (核心)
├── attachment-service (依赖: file-storage-service)
└── file-storage-service (依赖: 对象存储)

AI 服务层
├── ai-service (依赖: credit-service, 第三方 AI 平台)
└── video-service (依赖: ai-service, resource-service)
```

---

## 快速导航

### 按功能查找

**用户认证**

- [手机号登录](./user/user-service.md#手机号登录)
- [微信扫码登录](./user/wechat-service.md)
- [短信验证码](./user/sms-service.md)

**积分充值**

- [积分管理](./user/credit-service.md)
- [充值订单](./user/recharge-service.md)
- [支付集成](./user/payment-service.md)

**项目管理**

- [创建项目](./project/project-service.md)
- [项目资源](./project/project-resource-service.md)
- [剧本编辑](./project/screenplay-service.md)
- [分镜设计](./project/storyboard-service.md)

**AI 生成**

- [图片生成](./ai/ai-service.md)
- [视频生成](./ai/video-service.md)

---

## 相关文档

- [API 设计规范](../05-api-design.md)
- [数据库设计](../04-database-design.md)
- [安全设计](../12-security.md)