fix(clips): 全面修复 Clips API 响应结构 — 替换 PR #1403 #1404

Merged

xiaoxia merged 6 commits from fix/clips-api-response-structure into develop 2026-08-17 18:18:48 +08:00

Conversation 5 Commits 6 Files Changed 4

+626 -36

xiaoxia commented 2026-08-17 14:43:18 +08:00

Owner

Copy Link

Copy Source

背景

前端工程师反馈 clips API 返回结果混乱：缺少关键字段（asset_id, status, start_time 等）、split/merge 响应格式不统一、无法获取素材视频URL。本 PR 替换之前的 #1403（仅加 asset_url），做完整修复。

改动总览

级别	内容	文件
P0	EditorClipResponse 补全所有数据库字段	schemas.py
P1	split/merge 端点统一使用 EditorClipResponse	clips.py
P1	asset_url 签名URL解析（批量查询）	clips.py
P2	ClipsFromAssetsResponse 补上 plan_id	schemas.py

P0: EditorClipResponse 新增字段

{
  "id": "clip-xxx",
  "plan_id": "plan-xxx",
  "clip_type": "main",
  "order": 0,
  "duration": 5.0,
  "start_time": 0.0,
  "text_content": "",
  "transition_effect": "fade",
  "transition_duration": 0.5,
  "playback_speed": 1.0,
  "asset_id": "asset-xxx",
  "asset_url": "https://oss.xxx.com/...?Expires=...",
  "status": "pending",
  "template_clip_config_id": "tc-xxx",
  "config": {},
  "created_at": "2026-08-17T06:00:00",
  "updated_at": "2026-08-17T06:00:00"
}

P1: split/merge 响应统一

split 返回：

{
  "left_clip": { /* EditorClipResponse */ },
  "right_clip": { /* EditorClipResponse */ }
}

merge 返回：

{
  "merged_clip": { /* EditorClipResponse */ },
  "deleted_clip_ids": ["clip-1", "clip-2"]
}

P1: asset_url 实现

• 使用现有 StorageService.get_download_url() 生成 OSS 签名URL
• 使用 AssetRepository.find_by_id() 查询素材 storage_key
• 列表接口批量查询，避免 N+1
• 异常安全：失败只记日志，返回 null
• 签名有效期 1 小时

修改文件

文件	改动
schemas.py	EditorClipResponse +9字段, ClipsFromAssetsResponse +plan_id
clips.py	_clip_to_response 全字段对齐, _build_asset_url_map 新增, 5个端点增加 asset_repo 注入

替换关系

本 PR 完全替换 PR #1403（feat/clips-asset-url 分支），包含其所有功能并扩展修复。

验证

• CI 全绿后合并
• 前端联调验证 asset_url 可播放

## 背景 前端工程师反馈 clips API 返回结果混乱：缺少关键字段（asset_id, status, start_time 等）、split/merge 响应格式不统一、无法获取素材视频URL。本 PR 替换之前的 #1403（仅加 asset_url），做完整修复。 ## 改动总览 | 级别 | 内容 | 文件 | |------|------|------| | P0 | EditorClipResponse 补全所有数据库字段 | schemas.py | | P1 | split/merge 端点统一使用 EditorClipResponse | clips.py | | P1 | asset_url 签名URL解析（批量查询） | clips.py | | P2 | ClipsFromAssetsResponse 补上 plan_id | schemas.py | ## P0: EditorClipResponse 新增字段 ```json { "id": "clip-xxx", "plan_id": "plan-xxx", "clip_type": "main", "order": 0, "duration": 5.0, "start_time": 0.0, "text_content": "", "transition_effect": "fade", "transition_duration": 0.5, "playback_speed": 1.0, "asset_id": "asset-xxx", "asset_url": "https://oss.xxx.com/...?Expires=...", "status": "pending", "template_clip_config_id": "tc-xxx", "config": {}, "created_at": "2026-08-17T06:00:00", "updated_at": "2026-08-17T06:00:00" } ``` ## P1: split/merge 响应统一 **split** 返回： ```json { "left_clip": { /* EditorClipResponse */ }, "right_clip": { /* EditorClipResponse */ } } ``` **merge** 返回： ```json { "merged_clip": { /* EditorClipResponse */ }, "deleted_clip_ids": ["clip-1", "clip-2"] } ``` ## P1: asset_url 实现 - 使用现有 `StorageService.get_download_url()` 生成 OSS 签名URL - 使用 `AssetRepository.find_by_id()` 查询素材 storage_key - 列表接口批量查询，避免 N+1 - 异常安全：失败只记日志，返回 null - 签名有效期 1 小时 ## 修改文件 | 文件 | 改动 | |------|------| | `schemas.py` | EditorClipResponse +9字段, ClipsFromAssetsResponse +plan_id | | `clips.py` | _clip_to_response 全字段对齐, _build_asset_url_map 新增, 5个端点增加 asset_repo 注入 | ## 替换关系 本 PR 完全替换 PR #1403（feat/clips-asset-url 分支），包含其所有功能并扩展修复。 ## 验证 - CI 全绿后合并 - 前端联调验证 asset_url 可播放

xiaoxia added 1 commit 2026-08-17 14:43:18 +08:00

fix(clips): 全面修复 Clips API 响应结构 ... 9aa0c69b26

P0: EditorClipResponse 补全所有数据库字段
- 新增 start_time, transition_duration, asset_id, status,
  template_clip_config_id, created_at, updated_at
- 新增 asset_url (OSS签名URL, 1小时有效)

P1: split/merge 端点统一使用 EditorClipResponse
- split 返回 {left_clip, right_clip} 均为 EditorClipResponse
- merge 返回 {merged_clip, deleted_clip_ids}
- 移除 dict[str, Any] 响应类型

P1: asset_url 签名URL解析
- 批量查询 Asset 表获取 storage_key
- 使用 StorageService.get_download_url() 签名
- 列表/详情/split/merge 端点均支持

P2: ClipsFromAssetsResponse 补上 plan_id 字段

gitea-actions bot commented 2026-08-17 14:46:14 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1404
预览链接	https://pr-1404.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1404 | | 预览链接 | [https://pr-1404.preview.xiaoxiajianji.com](https://pr-1404.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia added 1 commit 2026-08-17 15:35:52 +08:00

fix: remove unused typing.Any import + add clips API response structure tests ... 2e53c59cd7

- Remove unused 'from typing import Any' (Ruff F401)
- Add 28 unit/integration tests covering:
  - _clip_to_response: enum conversion, datetime formatting, asset_url param
  - _build_asset_url_map: empty list, storage failure, asset not found,
    no storage_key, success path, exception handling, mixed scenarios
  - Route integration: list/detail/split/merge with asset URL resolution
- Incremental coverage: 100% (95/95 added lines covered)

auto-approve-bot added 1 commit 2026-08-17 15:40:35 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 34bd9372ce

xiaoxia referenced this pull request 2026-08-17 15:41:01 +08:00

PR#3 前端CSS标题叠加与拖拽调整 #1405

auto-approve-bot approved these changes 2026-08-17 15:50:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-17 15:50:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia referenced this issue from a commit 2026-08-17 16:29:08 +08:00

fix: batch query assets to resolve N+1 in _build_asset_url_map

xiaoxia added 1 commit 2026-08-17 16:29:08 +08:00

fix: batch query assets to resolve N+1 in _build_asset_url_map ... 9e97473eec

- Add find_by_ids() to SQLAlchemyAssetRepository (single SQL IN query)
- Replace per-id find_by_id loop with single batch call
- Fixes AI Code Review blocking performance issue in PR #1404

xiaoxia added 1 commit 2026-08-17 16:37:41 +08:00

fix: update test mocks for batch query + add asset_id dedup ... ac416493e0

- Replace find_by_id mocks with find_by_ids (returns list) in all 28 tests
- Add .id attributes to mock assets for asset_map key matching
- Dedup asset_ids in _build_asset_url_map to avoid redundant signing
- Fixes AI Code Review blocking issues #1 and #3

xiaoxia added 1 commit 2026-08-17 18:08:27 +08:00

fix: preserve insertion order in asset_id dedup to fix test ordering ... 1db2ee0808

Changed set-based dedup to order-preserving dedup in _build_asset_url_map.
Set dedup caused non-deterministic iteration order which broke
side_effect-based mock assertions in tests.

auto-approve-bot commented 2026-08-17 18:13:08 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：1 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [apps/api/app/api/routes/templates_editor/clips.py: ~317] merge_draft_clips 接口响应结构破坏性变更
   • 问题类型：逻辑bug / 数据损坏风险
   • 问题描述：merge_draft_clips 函数的返回值结构发生了重大变化。原代码直接返回合并后的片段属性（如 id, plan_id 等），而新代码将其包裹在 merged_clip 对象中，并新增了 deleted_clip_ids 字段。这会导致前端或调用方无法通过 response.id 获取数据，而是需要改为 response.merged_clip.id。在未同步更新调用方的情况下，这将导致功能异常。
   • 修改建议：确保此变更是预期的，并且前端已同步修改。如果需要保持向后兼容，应保持原有扁平结构，或者进行版本控制。如果是内部重构且确认调用方同步更新，需在 PR 描述中明确说明 Breaking Change。

💡 改进建议（不阻塞合并）

1. [apps/api/app/api/routes/templates_editor/clips.py: 22] 违反依赖倒置原则（DIP）

   • 具体内容：代码直接导入了 SQLAlchemyAssetRepository（from packages.adapters...），导致 API 层（应用层）直接依赖了具体的 Repository 实现（基础设施层）。这违反了整洁架构的分层原则，增加了耦合度。建议定义一个 AssetRepository Protocol 或抽象基类，函数参数依赖该抽象接口，而非具体实现类。

2. [apps/api/app/api/routes/templates_editor/clips.py: 280, 317] 移除 response_model 导致契约丢失

   • 具体内容：在 split_draft_clip 和 merge_draft_clips 路由装饰器中移除了 response_model 参数。虽然代码能正常运行，但这会导致 FastAPI 失去对响应数据的自动验证、序列化保证以及 OpenAPI 文档的自动生成能力。建议定义明确的 Pydantic 响应模型（如 SplitClipResponse）并应用，以确保 API 契约的严谨性。

✅ 良好实践

• 性能优化：_build_asset_url_map 函数实现了批量查询素材（find_by_ids）并去重，有效避免了 N+1 查询问题，这是很好的性能实践。
• 健壮性：_clip_to_response 函数使用了 getattr 配合默认值，能够很好地处理模型字段缺失或为 None 的情况，增强了代码的容错性。
• 异常处理：在获取存储服务和生成签名 URL 时增加了 try-except 块，并在异常时返回 None 或降级处理，避免了因第三方服务故障导致主流程中断。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-17 10:13:08 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：1 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[apps/api/app/api/routes/templates_editor/clips.py: ~317] merge_draft_clips 接口响应结构破坏性变更** - 问题类型：逻辑bug / 数据损坏风险 - 问题描述：`merge_draft_clips` 函数的返回值结构发生了重大变化。原代码直接返回合并后的片段属性（如 `id`, `plan_id` 等），而新代码将其包裹在 `merged_clip` 对象中，并新增了 `deleted_clip_ids` 字段。这会导致前端或调用方无法通过 `response.id` 获取数据，而是需要改为 `response.merged_clip.id`。在未同步更新调用方的情况下，这将导致功能异常。 - 修改建议：确保此变更是预期的，并且前端已同步修改。如果需要保持向后兼容，应保持原有扁平结构，或者进行版本控制。如果是内部重构且确认调用方同步更新，需在 PR 描述中明确说明 Breaking Change。 ### 💡 改进建议（不阻塞合并） 1. **[apps/api/app/api/routes/templates_editor/clips.py: 22] 违反依赖倒置原则（DIP）** - 具体内容：代码直接导入了 `SQLAlchemyAssetRepository`（`from packages.adapters...`），导致 API 层（应用层）直接依赖了具体的 Repository 实现（基础设施层）。这违反了整洁架构的分层原则，增加了耦合度。建议定义一个 `AssetRepository` Protocol 或抽象基类，函数参数依赖该抽象接口，而非具体实现类。 2. **[apps/api/app/api/routes/templates_editor/clips.py: 280, 317] 移除 response_model 导致契约丢失** - 具体内容：在 `split_draft_clip` 和 `merge_draft_clips` 路由装饰器中移除了 `response_model` 参数。虽然代码能正常运行，但这会导致 FastAPI 失去对响应数据的自动验证、序列化保证以及 OpenAPI 文档的自动生成能力。建议定义明确的 Pydantic 响应模型（如 `SplitClipResponse`）并应用，以确保 API 契约的严谨性。 ### ✅ 良好实践 - **性能优化**：`_build_asset_url_map` 函数实现了批量查询素材（`find_by_ids`）并去重，有效避免了 N+1 查询问题，这是很好的性能实践。 - **健壮性**：`_clip_to_response` 函数使用了 `getattr` 配合默认值，能够很好地处理模型字段缺失或为 None 的情况，增强了代码的容错性。 - **异常处理**：在获取存储服务和生成签名 URL 时增加了 `try-except` 块，并在异常时返回 `None` 或降级处理，避免了因第三方服务故障导致主流程中断。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-17 10:13:08 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit 3c800d3f3f into develop 2026-08-17 18:18:48 +08:00

gitea-actions bot commented 2026-08-17 18:19:34 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1404 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1404 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this pull request 2026-08-17 20:09:05 +08:00

fix(test): 修复 mock clip 缺失字段导致 7 个单测 Pydantic 校验失败 #1407

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1404