refactor(backend): 智能剪辑后端公共逻辑抽取+解耦 #1884

Merged

auto-approve-bot merged 2 commits from refactor/backend-audit-cleanup-0914 into develop 2026-09-14 03:15:00 +08:00

Conversation 2 Commits 2 Files Changed 5

+465 -177

xiaoxia commented 2026-09-14 02:51:23 +08:00

Owner

Copy Link

Copy Source

重构内容

本次重构严格遵守「不增删功能、不改变接口契约、不改变业务逻辑」原则，聚焦 P2 解耦 + P1 重复代码消除。

1. 新增公共服务 apps/api/app/services/generation_common.py（+175 行）

承载从路由层下沉的 4 个公共函数，消除多处重复实现：

• query_voice_durations(db, voice_ids)：批量查询配音素材时长（原 generation_tasks._query_voice_durations，多处重复实现）
• writeback_edit_plan_config(plan_id, task_id, title_config, db)：任务入队后回写 EditPlan.config（原 generation_tasks._writeback_edit_plan_config，含标题变化清封面逻辑）
• collect_plan_segments(plan_id, clip_repo)：分页读取 plan clips 构建素材区间避让表（消除了 generation_tasks、edit_plan_service 内两处完全重复的嵌套函数）
• resolve_latest_plan_by_template(db, template_id, user_id)：按 template_id+user_id 查最新 EditPlan（消除 generation_tasks、generation_variant_plans 内 3 处重复查询块）

2. 路由层保留兼容别名（re-export）

• generation_tasks._query_voice_durations / _writeback_edit_plan_config 改为委托公共函数，签名和返回值不变，外部 import 路径完全可用
• 消除 P2.1 问题：generation_variant_plans.py 不再跨 route 私有函数依赖，统一走 service 层

3. 收敛重复片段

• generation_tasks / edit_plan_service / generation_variant_plans 三处 template_id → 最新 plan 查询统一走公共函数
• generation_tasks / edit_plan_service 两处 _collect_segments / _collect_plan_segments 分页素材区间收集统一走公共函数
• edit_plan_service 内 apply_voice_duration_to_plan / ensure_variant_plans 改用公共 collect_plan_segments

4. 改动文件清单

文件	变化
apps/api/app/services/generation_common.py	新增 公共服务模块
apps/api/app/api/routes/generation_tasks.py	-164 行，函数体委托公共服务
apps/api/app/api/routes/generation_variant_plans.py	-21 行，改用公共函数
apps/api/app/services/edit_plan_service.py	-25 行，内部区间收集改用公共函数

5. 未做的高风险项（保守处理）

• ❌ unified_render_service.py（2332 行）类级拆分：涉及 FFmpeg 滤镜链核心逻辑，类级拆分易破坏渲染时序，留给后续小步迭代
• ❌ edit_plan_service.py mixin 拆分：现有单元测试通过 monkey-patch edit_plan_service.record_used_segments 验证副作用，拆到 mixin 会打破 patch 路径，需要同步改测试，本次「不改测试」原则下保留原状
• ❌ generation_tasks.py 拆分 validator/dispatcher：与 schema/response 紧密耦合，独立拆分风险高
• ❌ 三处批量变体 clone+reselect 流程统一收敛：三个调用方在「失败重试、回滚策略、variant_plan_ids 校验」上存在细微差异，强行统一会改变行为，暂保留差异，只抽公共原子函数
• ❌ service 层直接 db.query(AssetModel) 绕过 repository：都是只读时长查询，当前 asset_repo 未提供批量时长接口，贸然改 repository 接口影响面大，保留

验证

• ✅ 15070 个单元测试全部通过（pytest tests/unit/）
• ✅ 目标范围集成测试（variant / render / edit_plan / avatar / generation_task / preview）1515 个通过
• ✅ ruff check F401/F811/F841 全部通过，无未使用 import / 未使用变量
• ✅ black / isort 格式化通过
• ✅ 不改变任何 API 路径、请求/响应结构、公共方法签名
• ⚠️ 全量集成测试中 tests/integration/test_error_scenarios.py 报 users.phone_verified 列不存在，这是测试数据库 schema 落后于模型定义的环境问题（其他集成测试用例不受影响），与本次重构无关

## 重构内容 本次重构严格遵守「不增删功能、不改变接口契约、不改变业务逻辑」原则，聚焦 P2 解耦 + P1 重复代码消除。 ### 1. 新增公共服务 `apps/api/app/services/generation_common.py`（+175 行） 承载从路由层下沉的 4 个公共函数，消除多处重复实现： - `query_voice_durations(db, voice_ids)`：批量查询配音素材时长（原 `generation_tasks._query_voice_durations`，多处重复实现） - `writeback_edit_plan_config(plan_id, task_id, title_config, db)`：任务入队后回写 EditPlan.config（原 `generation_tasks._writeback_edit_plan_config`，含标题变化清封面逻辑） - `collect_plan_segments(plan_id, clip_repo)`：分页读取 plan clips 构建素材区间避让表（消除了 generation_tasks、edit_plan_service 内两处完全重复的嵌套函数） - `resolve_latest_plan_by_template(db, template_id, user_id)`：按 template_id+user_id 查最新 EditPlan（消除 generation_tasks、generation_variant_plans 内 3 处重复查询块） ### 2. 路由层保留兼容别名（re-export） - `generation_tasks._query_voice_durations` / `_writeback_edit_plan_config` 改为委托公共函数，签名和返回值不变，外部 import 路径完全可用 - 消除 P2.1 问题：`generation_variant_plans.py` 不再跨 route 私有函数依赖，统一走 service 层 ### 3. 收敛重复片段 - generation_tasks / edit_plan_service / generation_variant_plans 三处 `template_id → 最新 plan` 查询统一走公共函数 - generation_tasks / edit_plan_service 两处 `_collect_segments` / `_collect_plan_segments` 分页素材区间收集统一走公共函数 - edit_plan_service 内 apply_voice_duration_to_plan / ensure_variant_plans 改用公共 collect_plan_segments ### 4. 改动文件清单 | 文件 | 变化 | |---|---| | `apps/api/app/services/generation_common.py` | **新增** 公共服务模块 | | `apps/api/app/api/routes/generation_tasks.py` | -164 行，函数体委托公共服务 | | `apps/api/app/api/routes/generation_variant_plans.py` | -21 行，改用公共函数 | | `apps/api/app/services/edit_plan_service.py` | -25 行，内部区间收集改用公共函数 | ### 5. 未做的高风险项（保守处理） - ❌ `unified_render_service.py`（2332 行）类级拆分：涉及 FFmpeg 滤镜链核心逻辑，类级拆分易破坏渲染时序，留给后续小步迭代 - ❌ `edit_plan_service.py` mixin 拆分：现有单元测试通过 monkey-patch `edit_plan_service.record_used_segments` 验证副作用，拆到 mixin 会打破 patch 路径，需要同步改测试，本次「不改测试」原则下保留原状 - ❌ `generation_tasks.py` 拆分 validator/dispatcher：与 schema/response 紧密耦合，独立拆分风险高 - ❌ 三处批量变体 clone+reselect 流程统一收敛：三个调用方在「失败重试、回滚策略、variant_plan_ids 校验」上存在细微差异，强行统一会改变行为，暂保留差异，只抽公共原子函数 - ❌ service 层直接 `db.query(AssetModel)` 绕过 repository：都是只读时长查询，当前 asset_repo 未提供批量时长接口，贸然改 repository 接口影响面大，保留 ## 验证 - ✅ 15070 个单元测试全部通过（`pytest tests/unit/`） - ✅ 目标范围集成测试（variant / render / edit_plan / avatar / generation_task / preview）1515 个通过 - ✅ `ruff check` F401/F811/F841 全部通过，无未使用 import / 未使用变量 - ✅ `black` / `isort` 格式化通过 - ✅ 不改变任何 API 路径、请求/响应结构、公共方法签名 - ⚠️ 全量集成测试中 `tests/integration/test_error_scenarios.py` 报 `users.phone_verified` 列不存在，这是测试数据库 schema 落后于模型定义的环境问题（其他集成测试用例不受影响），与本次重构无关

xiaoxia added 1 commit 2026-09-14 02:51:24 +08:00

refactor(api/services): 抽取generation_common公共服务承载query_voice_durations/writeback/collect_segments/resolve_latest_plan，消除路由层重复实现和跨route私有函数依赖，保留兼容别名 bc267ad4da

gitea-actions bot commented 2026-09-14 02:52:52 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

xiaoxia added 1 commit 2026-09-14 03:05:41 +08:00

test(api/services): 为generation_common公共服务补充单元测试，修复CI增量覆盖率门禁(20%→87%) 840b26eb12

auto-approve-bot merged commit 14580f536a into develop 2026-09-14 03:15:00 +08:00

auto-approve-bot deleted branch refactor/backend-audit-cleanup-0914 2026-09-14 03:15:01 +08:00

gitea-actions bot commented 2026-09-14 03:15:27 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia referenced this pull request 2026-09-14 09:41:26 +08:00

release: 2026.09.14 智能剪辑批量变体P0修复+AI数字人MOV支持+代码审查重构 #1885

xiaoxia referenced this pull request 2026-09-14 10:03:31 +08:00

release v0.1.136: 智能剪辑批量变体P0修复+AI数字人MOV支持+代码审查重构 #1886

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1884