refactor(cover): 封面生成API从templates_editor解耦到generation路由 #1359

Merged

auto-approve-bot merged 3 commits from refactor/cover-api-decouple into develop 2026-08-13 18:56:00 +08:00

Conversation 5 Commits 3 Files Changed 12

+182 -100

xiaoxia commented 2026-08-13 18:26:44 +08:00

Owner

Copy Link

Copy Source

变更概述

将封面生成 API 从 templates_editor 模块彻底解耦，迁移到 generation 路由下。

后端

• 新增 apps/api/app/api/routes/generation_cover.py — 新路由 POST /api/v1/generation/generate-cover
  • template_id 改为 query parameter
  • Schemas 内联定义，不再依赖 templates_editor/schemas.py
  • 保留所有原有逻辑（3步查找预览视频URL、MediaKit抽帧、回写plan.config）
• 更新 router.py — 注册新路由到 /generation 前缀
• 清理 templates_editor/__init__.py — 移除 cover_router
• 删除 templates_editor/cover.py
• 清理 templates_editor/schemas.py — 移除 GenerateCoverRequest / GenerateCoverResponse
• 新增 tests/unit/test_generation_cover.py — 新路由单元测试

前端

• 新增 api/generation/cover.ts — 新 API 调用 /generation/generate-cover
• 更新 api/generation/index.ts — 导出 generateCover
• 更新 useStep6Cover.ts — import 路径改为 @/api/generation
• 清理 api/template-editor/aiFeatures.ts — 移除 generateCover 函数
• 清理 api/template-editor/index.ts — 移除相关 export
• 清理 api/template-editor/types.ts — 移除 GenerateCoverRequest/GenerateCoverResponse/CoverResult
• 更新 test/api/edit-plans.test.ts — 移除旧 cover 测试

测试

• 13631 个后端测试全部通过（2 个 pre-existing failure 与本次变更无关）
• 7 个新增单元测试验证新路由导入、schema 验证、路径正确性

## 变更概述 将封面生成 API 从 `templates_editor` 模块彻底解耦，迁移到 `generation` 路由下。 ### 后端 - **新增** `apps/api/app/api/routes/generation_cover.py` — 新路由 `POST /api/v1/generation/generate-cover` - `template_id` 改为 query parameter - Schemas 内联定义，不再依赖 templates_editor/schemas.py - 保留所有原有逻辑（3步查找预览视频URL、MediaKit抽帧、回写plan.config） - **更新** `router.py` — 注册新路由到 `/generation` 前缀 - **清理** `templates_editor/__init__.py` — 移除 cover_router - **删除** `templates_editor/cover.py` - **清理** `templates_editor/schemas.py` — 移除 `GenerateCoverRequest` / `GenerateCoverResponse` - **新增** `tests/unit/test_generation_cover.py` — 新路由单元测试 ### 前端 - **新增** `api/generation/cover.ts` — 新 API 调用 `/generation/generate-cover` - **更新** `api/generation/index.ts` — 导出 `generateCover` - **更新** `useStep6Cover.ts` — import 路径改为 `@/api/generation` - **清理** `api/template-editor/aiFeatures.ts` — 移除 `generateCover` 函数 - **清理** `api/template-editor/index.ts` — 移除相关 export - **清理** `api/template-editor/types.ts` — 移除 `GenerateCoverRequest`/`GenerateCoverResponse`/`CoverResult` - **更新** `test/api/edit-plans.test.ts` — 移除旧 cover 测试 ### 测试 - 13631 个后端测试全部通过（2 个 pre-existing failure 与本次变更无关） - 7 个新增单元测试验证新路由导入、schema 验证、路径正确性

xiaoxia added 1 commit 2026-08-13 18:26:44 +08:00

refactor(cover): 封面生成API从templates_editor解耦到generation路由 49b5a0834d

gitea-actions bot commented 2026-08-13 18:28:15 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot added 1 commit 2026-08-13 18:34:31 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 26338f7f2d

xiaoxia added 1 commit 2026-08-13 18:46:09 +08:00

fix(test): replace broad pytest.raises(Exception) with ValidationError (B017) af88a8136b

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

Collaborator

Copy Link

Copy Source

【阻塞级判定】

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

📊 审查概览

• 整体评价：通过
• 建议级问题数量：2 个

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

无

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

1. [apps/web/src/api/generation/cover.ts: 27] 请求体参数冗余

   • 具体内容：在调用 apiClient.post 时，template_id 被同时放入了 data（请求体）和 params（查询参数）。后端接口 generate_cover 通过 Query(...) 获取 template_id，且 GenerateCoverRequest Schema 中并未定义该字段，因此请求体中的 template_id 会被忽略。建议移除请求体中的 template_id: templateId，保持数据传输的一致性。

2. [apps/api/app/api/routes/generation_cover.py: 36] Schema 类型约束不够严格

   • 具体内容：GenerateCoverRequest 中的 cover_type 字段定义为 str，仅通过文档字符串描述了可选值。建议使用 Literal 或 Enum（例如 Literal["ai_frame", "manual", "upload", "ai_regenerate"]）进行约束，以便在 FastAPI 自动生成的文档中明确展示枚举值，并在校验阶段拒绝非法值，防止下游逻辑因拼写错误产生意外行为。

✅ 良好实践

• 测试覆盖全面：新增的 test_generation_cover.py 不仅测试了新路由的导入和路径，还反向验证了旧模块（templates_editor）中已正确移除相关 Schema 和路由，有效防止了重构后的代码残留。
• 类型定义迁移清晰：前端 TypeScript 类型定义随着 API 路由的迁移进行了同步移动和清理，保持了前后端代码结构的一致性。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能正常

---

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

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/web/src/api/generation/cover.ts: 27] 请求体参数冗余** - 具体内容：在调用 `apiClient.post` 时，`template_id` 被同时放入了 `data`（请求体）和 `params`（查询参数）。后端接口 `generate_cover` 通过 `Query(...)` 获取 `template_id`，且 `GenerateCoverRequest` Schema 中并未定义该字段，因此请求体中的 `template_id` 会被忽略。建议移除请求体中的 `template_id: templateId`，保持数据传输的一致性。 2. **[apps/api/app/api/routes/generation_cover.py: 36] Schema 类型约束不够严格** - 具体内容：`GenerateCoverRequest` 中的 `cover_type` 字段定义为 `str`，仅通过文档字符串描述了可选值。建议使用 `Literal` 或 `Enum`（例如 `Literal["ai_frame", "manual", "upload", "ai_regenerate"]`）进行约束，以便在 FastAPI 自动生成的文档中明确展示枚举值，并在校验阶段拒绝非法值，防止下游逻辑因拼写错误产生意外行为。 ### ✅ 良好实践 - **测试覆盖全面**：新增的 `test_generation_cover.py` 不仅测试了新路由的导入和路径，还反向验证了旧模块（`templates_editor`）中已正确移除相关 Schema 和路由，有效防止了重构后的代码残留。 - **类型定义迁移清晰**：前端 TypeScript 类型定义随着 API 路由的迁移进行了同步移动和清理，保持了前后端代码结构的一致性。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能正常 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-13 10:48:04 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot approved these changes 2026-08-13 18:55:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-13 18:55:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit 17174e2cf5 into develop 2026-08-13 18:56:00 +08:00

auto-approve-bot deleted branch refactor/cover-api-decouple 2026-08-13 18:56:01 +08:00

gitea-actions bot commented 2026-08-13 18:57:00 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

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#1359