docs/v1.0/requirements/backend/04-services

后端服务文档总览

最后更新：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() 等基础验证方法

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 层：在所有操作中验证引用完整性

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)
        # 处理关联数据...

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

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

4. 级联删除处理

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

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

详细规范：

• 数据库设计规范
• 服务文档 UUID 定义清理

---

目录结构

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

📁 user/ - 用户相关服务

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

• 用户管理服务
• 短信验证码服务
• 微信登录服务
• 算力积分管理服务
• 充值管理服务
• 支付服务

📁 project/ - 项目相关服务

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

• 项目管理服务
• 项目资源服务
• 文件夹管理服务
• 剧本管理服务
• 分镜管理服务
• 分镜看板管理服务
• 评论管理服务
• 导出服务

📁 resource/ - 资源相关服务

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

• 资源管理服务
• 附件管理服务
• 文件存储服务

📁 ai/ - AI 相关服务

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

• AI 服务
• 视频服务

---

服务依赖关系

用户服务层
├── 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)

---

快速导航

按功能查找

用户认证

• 手机号登录
• 微信扫码登录
• 短信验证码

积分充值

• 积分管理
• 充值订单
• 支付集成

项目管理

• 创建项目
• 项目资源
• 剧本编辑
• 分镜设计

AI 生成

• 图片生成
• 视频生成

---

相关文档

• API 设计规范
• 数据库设计
• 安全设计