6.4 KiB

Raw Blame History

分镜资源服务文档技术栈合规性更新

日期: 2026-01-29
类型: 文档更新
影响范围: 分镜资源服务文档

变更概述

更新 storyboard-resource-service.md 文档，使其完全符合 jointo-tech-stack 规范，包括日志系统、数据库注释、API 响应格式和迁移脚本示例。

变更详情

1. 添加日志系统

变更内容：

在服务类中添加模块级 logger
为所有关键方法添加日志记录
使用 %-formatting 格式化日志消息
添加异常日志（exc_info=True）
使用中文日志消息

示例：

import logging

logger = logging.getLogger(__name__)

async def create_image(self, user_id, storyboard_id, image_data):
    logger.info("用户 %s 为分镜 %s 创建图片", user_id, storyboard_id)
    
    try:
        # ... 业务逻辑
        logger.info("图片创建成功: image_id=%s, version=%d", created_image.image_id, version)
        return created_image
    except Exception as e:
        logger.error(
            "创建图片失败: user_id=%s, storyboard_id=%s",
            user_id, storyboard_id,
            exc_info=True
        )
        raise

符合规范：

✅ logging.md - 日志级别使用
✅ logging.md - %-formatting 格式化
✅ logging.md - 中文日志消息
✅ logging.md - 异常日志规范

2. 添加数据库注释

变更内容：

为所有表添加 COMMENT 注释
为关键列添加 COMMENT 注释
注释说明字段用途和约束

示例：

-- 表注释
COMMENT ON TABLE storyboard_images IS '分镜图片表 - 存储AI生成的分镜画面，支持多版本管理';

-- 列注释
COMMENT ON COLUMN storyboard_images.image_id IS '图片ID（主键）';
COMMENT ON COLUMN storyboard_images.status IS '生成状态: 0=pending, 1=processing, 2=completed, 3=failed';
COMMENT ON COLUMN storyboard_images.is_active IS '是否为当前激活版本（每个分镜只能有一个激活图片）';
COMMENT ON COLUMN storyboard_images.checksum IS 'SHA256校验和，用于文件去重';

符合规范：

✅ database.md - 表注释规范
✅ database.md - 列注释规范

3. 统一 API 响应格式

变更前：

[
  {
    "image_id": "...",
    "url": "..."
  }
]

变更后：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "image_id": "...",
      "url": "..."
    }
  ]
}

符合规范：

✅ api-design.md - 统一响应格式
✅ api-design.md - code/message/data 结构

4. 添加 Alembic 迁移脚本示例

变更内容：

添加完整的 Alembic 迁移脚本
包含所有 4 张表的创建
包含表注释和索引创建
包含 upgrade 和 downgrade 方法

示例：

"""添加分镜资源表

Revision ID: 20260129_1800_add_storyboard_resources
Revises: <previous_revision>
Create Date: 2026-01-29 18:00:00.000000
"""

def upgrade() -> None:
    # 创建表
    op.create_table('storyboard_images', ...)
    
    # 添加注释
    op.execute("COMMENT ON TABLE storyboard_images IS '...'")
    
    # 创建索引
    op.create_index('idx_storyboard_images_storyboard_id', ...)

def downgrade() -> None:
    op.drop_table('storyboard_images')

符合规范：

✅ migration.md - 迁移文件命名
✅ migration.md - 迁移文件结构
✅ migration.md - 注释和索引创建

5. 统一文档版本号

变更内容：

文档顶部和底部版本号统一为 v1.2
更新日期统一为 2026-01-29
添加完整的变更记录

技术栈合规性检查

✅ 完全符合

日志系统 (logging.md)
- ✅ 模块级 logger 获取
- ✅ %-formatting 格式化
- ✅ 中文日志消息
- ✅ 异常日志 exc_info=True
- ✅ 日志级别使用（INFO/DEBUG/ERROR）
数据库设计 (database.md)
- ✅ UUID 主键
- ✅ TIMESTAMPTZ 时间类型
- ✅ SMALLINT 枚举存储
- ✅ 无物理外键约束
- ✅ 表和列注释
- ✅ 正确的索引设计
API 设计 (api-design.md)
- ✅ 统一响应格式
- ✅ code/message/data 结构
- ✅ RESTful 路由设计
数据库迁移 (migration.md)
- ✅ Alembic 迁移脚本
- ✅ 命名规范
- ✅ upgrade/downgrade 方法
- ✅ 注释和索引创建
文档规范 (documentation.md)
- ✅ 版本号统一
- ✅ 变更记录完整
- ✅ 文档结构清晰

影响范围

文档变更

✅ docs/requirements/backend/04-services/project/storyboard-resource-service.md

代码变更

⚠️ 无（仅文档更新，实际代码实现时需遵循此规范）

后续工作

当实现分镜资源服务时，需要：

创建 Model 层
- 定义 StoryboardImage/Video/Dialogue/Voiceover 模型
- 使用 ResourceStatus IntEnum
- 添加完整的类型提示
创建 Repository 层
- 实现所有数据库操作
- 使用 async/await
- 添加日志记录
创建 Service 层
- 按照文档中的示例实现
- 添加完整的日志记录
- 添加异常处理
创建 API 层
- 实现所有 REST 端点
- 使用统一响应格式
- 添加请求验证
创建迁移脚本
- 使用文档中的迁移脚本模板
- 添加表和列注释
- 创建所有索引
编写测试
- 单元测试（Service 层）
- 集成测试（API 层）
- 参考 testing.md 规范

验证清单

日志系统符合 logging.md 规范
数据库注释符合 database.md 规范
API 响应格式符合 api-design.md 规范
迁移脚本符合 migration.md 规范
文档版本号统一
变更记录完整

总结

本次更新使分镜资源服务文档完全符合 jointo-tech-stack 技术栈规范，为后续实现提供了清晰的指导。文档现在包含：

完整的日志记录示例
数据库表和列注释
统一的 API 响应格式
Alembic 迁移脚本模板
异常处理和错误日志

开发人员可以直接参考此文档进行实现，确保代码质量和一致性。

6.4 KiB Raw Blame History

分镜资源服务文档技术栈合规性更新

变更概述

变更详情

1. 添加日志系统

2. 添加数据库注释

3. 统一 API 响应格式

4. 添加 Alembic 迁移脚本示例

5. 统一文档版本号

技术栈合规性检查

✅ 完全符合

影响范围

文档变更

代码变更

后续工作

验证清单

相关文档

总结

6.4 KiB

Raw Blame History