feat(phase2): 模板发布版本化 + 回滚能力 #646

Merged

auto-approve-bot merged 6 commits from feat/phase2-publish-versioning into develop 2026-07-20 18:15:00 +08:00

Conversation 4 Commits 6 Files Changed 10

+583 -4

xiaoxia commented 2026-07-20 15:36:26 +08:00

Owner

Copy Link

Copy Source

背景

Phase 2 发布流程打通：模板编辑器草稿 → 正式模板的完整链路，增加版本号、状态流转、回滚能力。

改动

• edit_templates 加 version 字段：每次发布自动+1，默认1
• 新增 edit_template_versions 表：存每次发布的完整快照（config + clip_configs）
• 发布前自动存旧版快照：发布时先保存当前状态再更新，确保可回滚
• 回滚接口：POST /rollback 指定版本号回滚，回滚本身也是一次发布（版本+1），可撤销
• 版本历史接口：GET /versions 列出所有历史版本

新增端点（2个）

• GET /templates/{id}/editor/versions — 版本历史列表
• POST /templates/{id}/editor/rollback — 回滚到指定版本

测试

• 新增7个单元测试（版本查询/回滚/参数校验/错误处理）
• 37个测试全绿

## 背景 Phase 2 发布流程打通：模板编辑器草稿 → 正式模板的完整链路，增加版本号、状态流转、回滚能力。 ## 改动 - **edit_templates 加 version 字段**：每次发布自动+1，默认1 - **新增 edit_template_versions 表**：存每次发布的完整快照（config + clip_configs） - **发布前自动存旧版快照**：发布时先保存当前状态再更新，确保可回滚 - **回滚接口**：POST /rollback 指定版本号回滚，回滚本身也是一次发布（版本+1），可撤销 - **版本历史接口**：GET /versions 列出所有历史版本 ## 新增端点（2个） - `GET /templates/{id}/editor/versions` — 版本历史列表 - `POST /templates/{id}/editor/rollback` — 回滚到指定版本 ## 测试 - 新增7个单元测试（版本查询/回滚/参数校验/错误处理） - 37个测试全绿

xiaoxia added 1 commit 2026-07-20 15:36:26 +08:00

feat(phase2): 模板发布版本化 + 回滚能力 ... 224639d0c8

- edit_templates 加 version 字段，每次发布自动+1
- 新增 edit_template_versions 表存发布历史快照
- 发布前自动保存旧版快照，支持随时回滚
- 回滚本身也是一次发布（版本号+1），可撤销
- 新增 API：GET /versions 查历史、POST /rollback 回滚
- 7个单元测试覆盖版本查询/回滚/参数校验
- 37个测试全绿

gitea-actions bot commented 2026-07-20 15:38:12 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

xiaoxia added 1 commit 2026-07-20 15:46:03 +08:00

fix(test): 修复oneclick_gen测试mock不完整导致的EditTemplateStatus转换失败 ... 1c994842d2

test_oneclick_gen_p0_fixes.py 中 mock_template 缺少 status/version 字段，
导致 _model_to_entity 中 EditTemplateStatus(MagicMock) 转换失败。
补充 mock 属性修复增量测试选中时的失败。

xiaoxia added 1 commit 2026-07-20 17:37:21 +08:00

style: black格式修复 e4eb1c7fdf

xiaoxia added 1 commit 2026-07-20 17:42:12 +08:00

style: alembic migration black格式化 b138697cb4

auto-approve-bot commented 2026-07-20 17:59:55 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #646

⚠️ 问题（2个需要修改）

1. apps/api/app/services/edit_template_service.py 第876行：事务原子性失效导致数据不一致风险。

   • 问题描述：在 rollback_to_version 方法中，虽然使用了 try...except 并在异常时调用 self._db.rollback()，但事务内部调用的 self._template_repo.update() 和 self._clip_config_repo.delete/create() 方法内部均显式调用了 self.session.commit()。这意味着在 rollback 操作的多个步骤中，如果中间某一步（如恢复 clip_configs）失败，之前的步骤（如更新 version、删除旧 configs）已经提交到数据库，无法回滚。这将导致模板处于“版本号已增加但配置丢失”的损坏状态。
   • 后果：回滚操作失败时，数据库中会残留部分更新的数据，破坏数据完整性。
   • 修改建议：重构事务管理代码。应确保 Service 层控制事务边界，Repository 层的方法（如 update, delete, create）在参与复杂事务时不应自动 commit，或者使用 SQLAlchemy 的 begin_nested() / savepoint，或者将所有数据库操作放在一个事务上下文管理器中，仅在 Service 层最后统一 commit。

2. apps/api/app/services/edit_template_service.py 第856行：异常处理逻辑错误。

   • 问题描述：在 rollback_to_version 的循环中，except (ValueError, ImportError) 块内重新执行了 from packages.domain.template_clip_config import TransitionEffect。如果发生 ImportError（模块导入失败），在 except 块中再次导入通常也会失败，这并不能解决问题，且掩盖了真正的错误原因。此外，将 ImportError 与数值转换的 ValueError 混在一起处理是不恰当的。
   • 后果：如果枚举值解析失败，代码会静默降级为默认值（如 CUT），可能导致回滚后的数据与历史版本不一致；且如果真的发生导入错误，会导致难以排查的循环或崩溃。
   • 修改建议：将模块导入移到循环外部（方法顶部），仅捕获 ValueError 来处理不兼容的枚举值，并考虑记录警告日志以便追踪数据兼容性问题。

💡 建议（3个可选）

1. apps/api/app/services/edit_template_service.py 第870行：N+1 查询性能问题。

   • 具体内容：在删除旧的 clip_configs 时，使用了 for cfg in old_configs: self._clip_config_repo.delete(cfg.id)，这会在循环中执行多次 DELETE 语句。建议在 Repository 层实现支持 WHERE template_id = ? 的批量删除方法，以减少数据库交互次数。

2. apps/api/app/services/edit_template_service.py 第718行 & 第828行：代码重复。

   • 具体内容：publish_draft_to_template 和 rollback_to_version 中存在大量相同的代码逻辑，用于将 TemplateClipConfig 对象列表转换为字典列表（快照）。建议将这段逻辑提取为 TemplateClipConfig 类的一个实例方法（如 to_snapshot_dict()）或一个独立的辅助函数，以提高代码可维护性。

3. apps/api/app/api/routes/templates_editor.py 第363行：冗余查询。

   • 具体内容：在 rollback_template 接口中，调用 tpl_svc.rollback_to_version 完成回滚后，又立即调用 tpl_svc.list_clip_configs 仅为了获取 clip_count。建议优化 Service 层返回值，让 rollback_to_version 直接返回包含 clip_count 的结果对象，避免额外的数据库查询。

---

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

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-20 17:59:55 | 模型:}

## 代码审查结果 - PR #646 ### ⚠️ 问题（2个需要修改） 1. **apps/api/app/services/edit_template_service.py 第876行**：事务原子性失效导致数据不一致风险。 - 问题描述：在 `rollback_to_version` 方法中，虽然使用了 `try...except` 并在异常时调用 `self._db.rollback()`，但事务内部调用的 `self._template_repo.update()` 和 `self._clip_config_repo.delete/create()` 方法内部均显式调用了 `self.session.commit()`。这意味着在 `rollback` 操作的多个步骤中，如果中间某一步（如恢复 clip_configs）失败，之前的步骤（如更新 version、删除旧 configs）已经提交到数据库，无法回滚。这将导致模板处于“版本号已增加但配置丢失”的损坏状态。 - 后果：回滚操作失败时，数据库中会残留部分更新的数据，破坏数据完整性。 - 修改建议：重构事务管理代码。应确保 Service 层控制事务边界，Repository 层的方法（如 `update`, `delete`, `create`）在参与复杂事务时不应自动 `commit`，或者使用 SQLAlchemy 的 `begin_nested()` / `savepoint`，或者将所有数据库操作放在一个事务上下文管理器中，仅在 Service 层最后统一 `commit`。 2. **apps/api/app/services/edit_template_service.py 第856行**：异常处理逻辑错误。 - 问题描述：在 `rollback_to_version` 的循环中，`except (ValueError, ImportError)` 块内重新执行了 `from packages.domain.template_clip_config import TransitionEffect`。如果发生 `ImportError`（模块导入失败），在 except 块中再次导入通常也会失败，这并不能解决问题，且掩盖了真正的错误原因。此外，将 `ImportError` 与数值转换的 `ValueError` 混在一起处理是不恰当的。 - 后果：如果枚举值解析失败，代码会静默降级为默认值（如 `CUT`），可能导致回滚后的数据与历史版本不一致；且如果真的发生导入错误，会导致难以排查的循环或崩溃。 - 修改建议：将模块导入移到循环外部（方法顶部），仅捕获 `ValueError` 来处理不兼容的枚举值，并考虑记录警告日志以便追踪数据兼容性问题。 ### 💡 建议（3个可选） 1. **apps/api/app/services/edit_template_service.py 第870行**：N+1 查询性能问题。 - 具体内容：在删除旧的 `clip_configs` 时，使用了 `for cfg in old_configs: self._clip_config_repo.delete(cfg.id)`，这会在循环中执行多次 DELETE 语句。建议在 Repository 层实现支持 `WHERE template_id = ?` 的批量删除方法，以减少数据库交互次数。 2. **apps/api/app/services/edit_template_service.py 第718行 & 第828行**：代码重复。 - 具体内容：`publish_draft_to_template` 和 `rollback_to_version` 中存在大量相同的代码逻辑，用于将 `TemplateClipConfig` 对象列表转换为字典列表（快照）。建议将这段逻辑提取为 `TemplateClipConfig` 类的一个实例方法（如 `to_snapshot_dict()`）或一个独立的辅助函数，以提高代码可维护性。 3. **apps/api/app/api/routes/templates_editor.py 第363行**：冗余查询。 - 具体内容：在 `rollback_template` 接口中，调用 `tpl_svc.rollback_to_version` 完成回滚后，又立即调用 `tpl_svc.list_clip_configs` 仅为了获取 `clip_count`。建议优化 Service 层返回值，让 `rollback_to_version` 直接返回包含 clip_count 的结果对象，避免额外的数据库查询。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-20 17:59:55 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia added 1 commit 2026-07-20 18:00:04 +08:00

fix(phase2): 回滚补全name字段 + 批量删除替代N+1 ... 52f21a0924

1. 回滚时恢复模板 name 字段（快照已存但未恢复）
2. 发布和回滚中的片段配置删除改用 bulk delete，替代 N+1 循环删除
3. 使用 synchronize_session=False 避免 session 级联开销
4. 删除操作在外层事务中统一 commit，不破坏事务一致性

xiaoxia added 1 commit 2026-07-20 18:06:12 +08:00

fix(alembic): 修复047 migration的revision/down_revision命名不一致 ... 88b2d9e453

046的revision是'046_task_title'，之前写成'046'导致alembic找不到父版本，
迁移验证和集成测试都因此失败。统一命名规范。

auto-approve-bot approved these changes 2026-07-20 18:13:59 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-07-20 18:13:59 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit 419cc3fb6a into develop 2026-07-20 18:15:00 +08:00

auto-approve-bot deleted branch feat/phase2-publish-versioning 2026-07-20 18:15:01 +08:00

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