xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 9 Pull Requests 2 Actions Packages Projects Releases 7 Wiki Activity

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
10 changed files with 583 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
alembic/versions/047_template_versioning.py
Executable
+64
View File
@@ -0,0 +1,64 @@
"""Phase 2 - 模板发布版本化：version字段 + 发布历史表
Revision ID: 047
Revises: 046
Create Date: 2026-07-20
Changes:
1. edit_templates 加 version 字段（INT，默认1，每次发布+1）
2. 新建 edit_template_versions 表存发布历史快照，支持回滚
"""
import sqlalchemy as sa
from alembic import op
revision = "047_template_versioning"
down_revision = "046_task_title"
branch_labels = None
depends_on = None
def upgrade() -> None:
conn = op.get_bind()
# 1. edit_templates 加 version 字段
op.add_column(
"edit_templates",
sa.Column("version", sa.Integer, nullable=False, server_default="1"),
)
# 2. 新建 edit_template_versions 发布历史表
conn.execute(sa.text("""
CREATE TABLE IF NOT EXISTS edit_template_versions (
id VARCHAR(36) PRIMARY KEY,
template_id VARCHAR(32) NOT NULL,
version INTEGER NOT NULL,
name VARCHAR(200) NOT NULL DEFAULT '',
editing_mode VARCHAR(30) NOT NULL DEFAULT 'one_take',
config JSONB NOT NULL DEFAULT '{}',
clip_configs JSONB NOT NULL DEFAULT '[]',
change_note VARCHAR(500) NOT NULL DEFAULT '',
published_by VARCHAR(36) NOT NULL DEFAULT '',
created_at TIMESTAMP NOT NULL DEFAULT NOW()
)
"""))
conn.execute(
sa.text(
"CREATE INDEX IF NOT EXISTS ix_edit_template_versions_template_id " "ON edit_template_versions(template_id)"
)
)
conn.execute(
sa.text(
"CREATE UNIQUE INDEX IF NOT EXISTS ix_edit_template_versions_template_version "
"ON edit_template_versions(template_id, version)"
)
)
def downgrade() -> None:
conn = op.get_bind()
conn.execute(sa.text("DROP TABLE IF EXISTS edit_template_versions"))
op.drop_column("edit_templates", "version")
apps/api/app/api/routes/templates_editor.py
+89
View File
@@ -186,6 +186,42 @@ class EditorPublishResponse(BaseModel):
template_id: str
status: str = "published"
clip_count: int
version: int = 1
class EditorTemplateVersionItem(BaseModel):
"""模板版本历史条目"""
version: int
name: str
editing_mode: str
clip_count: int
change_note: str
published_by: str
created_at: str
class EditorVersionListResponse(BaseModel):
"""模板版本列表响应"""
versions: list[EditorTemplateVersionItem]
total: int
class EditorRollbackRequest(BaseModel):
"""回滚请求体"""
version: int
class EditorRollbackResponse(BaseModel):
"""回滚响应"""
template_id: str
status: str = "rolled_back"
rollback_to_version: int
new_version: int
clip_count: int
# ── Dependencies ────────────────────────────────────────────────────────────
@@ -295,6 +331,59 @@ def publish_draft_to_template(
template_id=tpl.id,
status="published",
clip_count=len(clips),
version=tpl.version,
)
@router.get("/versions", response_model=EditorVersionListResponse)
def list_template_versions(
template_id: str,
services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
_: AuthenticatedUser = Depends(get_current_user),
limit: int = Query(default=50, ge=1, le=200),
):
"""查询模板发布版本历史"""
tpl_svc, _ = services
versions = tpl_svc.list_template_versions(template_id, limit=limit)
items = [
EditorTemplateVersionItem(
version=v.version,
name=v.name,
editing_mode=v.editing_mode,
clip_count=len(v.clip_configs),
change_note=v.change_note,
published_by=v.published_by,
created_at=v.created_at.isoformat() if hasattr(v.created_at, "isoformat") else str(v.created_at),
)
for v in versions
]
return EditorVersionListResponse(versions=items, total=len(items))
@router.post("/rollback", response_model=EditorRollbackResponse, status_code=status.HTTP_200_OK)
def rollback_template(
template_id: str,
request: EditorRollbackRequest,
services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
_: AuthenticatedUser = Depends(get_current_user),
):
"""回滚模板到指定历史版本
回滚本身也是一次发布，版本号会 +1，可以再次回滚。
"""
tpl_svc, _ = services
try:
tpl = tpl_svc.rollback_to_version(template_id, request.version)
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
clip_configs = tpl_svc.list_clip_configs(template_id)
return EditorRollbackResponse(
template_id=tpl.id,
status="rolled_back",
rollback_to_version=request.version,
new_version=tpl.version,
clip_count=len(clip_configs),
)
apps/api/app/services/edit_template_service.py
+188 -4
View File
@@ -41,6 +41,11 @@ class EditTemplateService:
self._clip_config_repo = SQLAlchemyTemplateClipConfigRepository(db)
self._plan_repo = SQLAlchemyEditPlanRepository(db)
self._plan_clip_repo = SQLAlchemyEditPlanClipRepository(db)
from packages.adapters.sqlalchemy_impl.template_version_repository import (
SQLAlchemyTemplateVersionRepository,
)
self._version_repo = SQLAlchemyTemplateVersionRepository(db)
self._db = db
# ── 模板 CRUD ──────────────────────────────────────────────────────────
@@ -649,6 +654,9 @@ class EditTemplateService:
self,
template_id: str,
draft_plan_id: str,
*,
change_note: str = "",
published_by: str = "",
) -> Any:
"""将草稿剪辑计划的内容发布（同步）到模板
@@ -706,15 +714,54 @@ class EditTemplateService:
# 5. 事务更新
try:
# 5.0 先保存旧版快照（发布前的状态），用于回滚
old_version = template.version or 1
old_clip_configs = self._clip_config_repo.list_by_template(template_id)
old_clip_snapshots = [
{
"clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
"order": cfg.order,
"min_duration": cfg.min_duration,
"max_duration": cfg.max_duration,
"text_template": cfg.text_template or "",
"transition_effect": (
cfg.transition_effect.value
if hasattr(cfg.transition_effect, "value")
else cfg.transition_effect
),
"config": cfg.config or {},
}
for cfg in old_clip_configs
]
from packages.domain.template_version import EditTemplateVersion
old_snapshot = EditTemplateVersion.create(
template_id=template_id,
version=old_version,
name=template.name,
editing_mode=template.editing_mode,
config=dict(template.config) if template.config else {},
clip_configs=old_clip_snapshots,
change_note=f"v{old_version} 快照（发布前）",
published_by=published_by,
)
self._version_repo.create(old_snapshot)
# 更新模板元信息
template.config = template_config
template.editing_mode = editing_mode
template.bump_version() # 版本号 +1
updated_template = self._template_repo.update(template)
# 删除旧的片段配置
old_configs = self._clip_config_repo.list_by_template(template_id)
for cfg in old_configs:
self._clip_config_repo.delete(cfg.id)
# 批量删除旧的片段配置（N+1 → 1条DELETE，外层事务统一提交）
from packages.adapters.sqlalchemy_impl.models import (
TemplateClipConfigModel,
)
self._db.query(TemplateClipConfigModel).filter(TemplateClipConfigModel.template_id == template_id).delete(
synchronize_session=False
)
# 创建新的片段配置
created_configs: list[TemplateClipConfig] = []
@@ -779,3 +826,140 @@ class EditTemplateService:
exc,
)
raise
# ── 版本历史与回滚 ────────────────────────────────────────────────────
def list_template_versions(self, template_id: str, limit: int = 50) -> list[Any]:
"""列出模板的发布版本历史（按版本号倒序）"""
self.get_template_or_raise(template_id) # 校验存在性
return self._version_repo.list_by_template(template_id, limit=limit)
def rollback_to_version(self, template_id: str, version: int) -> Any:
"""回滚模板到指定历史版本
流程：
1. 校验目标版本存在
2. 保存当前状态为新版本快照（当前版本号）
3. 用目标版本的快照覆盖模板 config + clip_configs
4. 版本号 +1（回滚本身也是一次发布）
Returns:
EditTemplate: 回滚后的模板
Raises:
ValueError: 模板/版本不存在
"""
from packages.domain.template_clip_config import TemplateClipConfig
template = self.get_template_or_raise(template_id)
# 1. 读取目标版本快照
target_version = self._version_repo.get_by_version(template_id, version)
if target_version is None:
raise ValueError(f"模板 {template_id} 不存在版本 {version}")
current_version = template.version or 1
try:
# 2. 先保存当前状态快照（当前版本号），确保回滚可撤销
old_clip_configs = self._clip_config_repo.list_by_template(template_id)
old_clip_snapshots = [
{
"clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
"order": cfg.order,
"min_duration": cfg.min_duration,
"max_duration": cfg.max_duration,
"text_template": cfg.text_template or "",
"transition_effect": (
cfg.transition_effect.value
if hasattr(cfg.transition_effect, "value")
else cfg.transition_effect
),
"config": cfg.config or {},
}
for cfg in old_clip_configs
]
from packages.domain.template_version import EditTemplateVersion
current_snapshot = EditTemplateVersion.create(
template_id=template_id,
version=current_version,
name=template.name,
editing_mode=template.editing_mode,
config=dict(template.config) if template.config else {},
clip_configs=old_clip_snapshots,
change_note=f"v{current_version} 快照（回滚到 v{version} 前）",
published_by="rollback",
)
self._version_repo.create(current_snapshot)
# 3. 覆盖模板配置 + editing_mode + name + preview_url
template.config = dict(target_version.config)
template.editing_mode = target_version.editing_mode
if target_version.name:
template.name = target_version.name
template.bump_version() # 版本号 +1
updated_template = self._template_repo.update(template)
# 4. 先删后插 clip_configs（批量删除避免N+1）
from packages.adapters.sqlalchemy_impl.models import (
TemplateClipConfigModel,
)
self._db.query(TemplateClipConfigModel).filter(TemplateClipConfigModel.template_id == template_id).delete(
synchronize_session=False
)
for clip_snap in target_version.clip_configs:
# 转场效果兼容校验
try:
from packages.domain.template_clip_config import TransitionEffect
transition = TransitionEffect(clip_snap.get("transition_effect", "cut"))
except (ValueError, ImportError):
from packages.domain.template_clip_config import TransitionEffect
transition = TransitionEffect.CUT
# 片段类型兼容校验
try:
from packages.domain.template_clip_config import ClipType
clip_type = ClipType(clip_snap.get("clip_type", "main"))
except (ValueError, ImportError):
from packages.domain.template_clip_config import ClipType
clip_type = ClipType.MAIN
config_obj = TemplateClipConfig.create(
template_id=template_id,
clip_type=clip_type,
order=clip_snap.get("order", 0),
min_duration=clip_snap.get("min_duration", 0.0),
max_duration=clip_snap.get("max_duration", 0.0),
text_template=clip_snap.get("text_template", ""),
transition_effect=transition,
config=clip_snap.get("config", {}) or {},
)
self._clip_config_repo.create(config_obj)
self._db.commit()
logger.info(
"模板回滚成功: template_id=%s from_v=%d to_v=%d new_v=%d",
template_id,
current_version,
version,
updated_template.version,
)
return updated_template
except Exception as exc:
self._db.rollback()
logger.error(
"模板回滚失败: template_id=%s target_version=%d error=%s",
template_id,
version,
exc,
)
raise
packages/adapters/sqlalchemy_impl/edit_template_repository.py
Regular → Executable
+3
View File
@@ -76,6 +76,7 @@ class SQLAlchemyEditTemplateRepository:
preview_url=template.preview_url,
sort_weight=template.sort_weight,
status=template.status,
version=template.version,
)
self.session.add(model)
self.session.commit()
@@ -95,6 +96,7 @@ class SQLAlchemyEditTemplateRepository:
model.preview_url = template.preview_url
model.sort_weight = template.sort_weight
model.status = template.status
model.version = template.version
model.updated_at = template.updated_at
self.session.commit()
self.session.refresh(model)
@@ -135,6 +137,7 @@ class SQLAlchemyEditTemplateRepository:
preview_url=model.preview_url or "",
sort_weight=model.sort_weight or 0,
status=EditTemplateStatus(model.status) if model.status else EditTemplateStatus.ACTIVE,
version=model.version or 1,
created_at=model.created_at,
updated_at=model.updated_at,
)
packages/adapters/sqlalchemy_impl/models.py
+21
View File
@@ -134,10 +134,31 @@ class EditTemplateModel(Base):
preview_url = Column(String(1000), nullable=False, default="")
sort_weight = Column(Integer, nullable=False, default=0, index=True)
status = Column(String(20), nullable=False, default="active", index=True)
version = Column(Integer, nullable=False, default=1)
created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
updated_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
class EditTemplateVersionModel(Base):
"""模板发布版本快照 ORM 模型
每次发布保存完整快照，支持版本历史查询和回滚。
"""
__tablename__ = "edit_template_versions"
id = Column(String(36), primary_key=True)
template_id = Column(String(32), nullable=False, index=True)
version = Column(Integer, nullable=False)
name = Column(String(200), nullable=False, default="")
editing_mode = Column(String(30), nullable=False, default="one_take")
config = Column(JSON, nullable=False, default=dict)
clip_configs = Column(JSON, nullable=False, default=list)
change_note = Column(String(500), nullable=False, default="")
published_by = Column(String(36), nullable=False, default="")
created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
class EditPlanModel(Base):
"""Phase 8 剪辑计划 ORM 模型
packages/adapters/sqlalchemy_impl/template_version_repository.py
Executable
+79
View File
@@ -0,0 +1,79 @@
"""SQLAlchemy implementation of EditTemplateVersionRepository."""
from __future__ import annotations
from typing import List
from sqlalchemy.orm import Session
from packages.domain.template_version import EditTemplateVersion
class SQLAlchemyTemplateVersionRepository:
"""模板版本仓储实现（SQLAlchemy）。"""
def __init__(self, db: Session) -> None:
self._db = db
def create(self, version: EditTemplateVersion) -> EditTemplateVersion:
"""保存新版本快照"""
from packages.adapters.sqlalchemy_impl.models import EditTemplateVersionModel
model = EditTemplateVersionModel(
id=version.id,
template_id=version.template_id,
version=version.version,
name=version.name,
editing_mode=version.editing_mode,
config=version.config,
clip_configs=version.clip_configs,
change_note=version.change_note,
published_by=version.published_by,
created_at=version.created_at,
)
self._db.add(model)
self._db.flush()
return version
def get_by_version(self, template_id: str, version: int) -> EditTemplateVersion | None:
"""按版本号获取快照"""
from packages.adapters.sqlalchemy_impl.models import EditTemplateVersionModel
model = (
self._db.query(EditTemplateVersionModel)
.filter(
EditTemplateVersionModel.template_id == template_id,
EditTemplateVersionModel.version == version,
)
.first()
)
if model is None:
return None
return self._to_entity(model)
def list_by_template(self, template_id: str, limit: int = 50) -> List[EditTemplateVersion]:
"""列出模板的所有历史版本（按版本号倒序）"""
from packages.adapters.sqlalchemy_impl.models import EditTemplateVersionModel
models = (
self._db.query(EditTemplateVersionModel)
.filter(EditTemplateVersionModel.template_id == template_id)
.order_by(EditTemplateVersionModel.version.desc())
.limit(limit)
.all()
)
return [self._to_entity(m) for m in models]
def _to_entity(self, model) -> EditTemplateVersion:
return EditTemplateVersion(
id=model.id,
template_id=model.template_id,
version=model.version,
name=model.name or "",
editing_mode=model.editing_mode or "one_take",
config=model.config or {},
clip_configs=model.clip_configs or [],
change_note=model.change_note or "",
published_by=model.published_by or "",
created_at=model.created_at,
)
packages/domain/edit_template.py
Regular → Executable
+8
View File
@@ -51,6 +51,7 @@ class EditTemplate:
preview_url: str = ""
sort_weight: int = 0
status: EditTemplateStatus = EditTemplateStatus.ACTIVE
version: int = 1
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
@@ -66,6 +67,7 @@ class EditTemplate:
preview_url: str = "",
sort_weight: int = 0,
status: EditTemplateStatus = EditTemplateStatus.ACTIVE,
version: int = 1,
) -> EditTemplate:
"""创建新模板实例"""
clean_name = name.strip()
@@ -86,6 +88,7 @@ class EditTemplate:
preview_url=preview_url.strip(),
sort_weight=sort_weight,
status=status,
version=version,
)
def activate(self) -> None:
@@ -102,3 +105,8 @@ class EditTemplate:
def is_active(self) -> bool:
"""模板是否处于激活状态"""
return self.status == EditTemplateStatus.ACTIVE
def bump_version(self) -> None:
"""版本号+1，发布时调用"""
self.version += 1
self.updated_at = datetime.now(timezone.utc)
packages/domain/template_version.py
Executable
+53
View File
@@ -0,0 +1,53 @@
"""EditTemplateVersion — 模板发布版本快照，用于回滚和版本历史."""
from __future__ import annotations
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any
from uuid import uuid4
@dataclass(slots=True)
class EditTemplateVersion:
"""模板发布版本快照
每次发布时保存模板当时的完整状态（config + clip_configs），
支持回滚到任意历史版本。
"""
id: str
template_id: str
version: int
name: str = ""
editing_mode: str = "one_take"
config: dict[str, Any] = field(default_factory=dict)
clip_configs: list[dict[str, Any]] = field(default_factory=list)
change_note: str = ""
published_by: str = ""
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
@classmethod
def create(
cls,
template_id: str,
version: int,
*,
name: str = "",
editing_mode: str = "one_take",
config: dict[str, Any] | None = None,
clip_configs: list[dict[str, Any]] | None = None,
change_note: str = "",
published_by: str = "",
) -> "EditTemplateVersion":
return cls(
id=uuid4().hex,
template_id=template_id,
version=version,
name=name,
editing_mode=editing_mode,
config=config or {},
clip_configs=clip_configs or [],
change_note=change_note,
published_by=published_by,
)
tests/unit/test_oneclick_gen_p0_fixes.py
+2
View File
@@ -239,6 +239,8 @@ class TestP1Validations:
mock_template.id = "tmpl_001"
mock_template.name = "Test Template"
mock_template.is_active = True
mock_template.status = "active"
mock_template.version = 1
session = MagicMock()
mock_session = MagicMock()
tests/unit/test_templates_editor_api.py
Regular → Executable
+76
View File
@@ -96,7 +96,16 @@ def _create_test_app():
id=TEST_TEMPLATE_ID,
name="发布后的模板",
status="published",
version=2,
)
mock_template_svc.list_template_versions.return_value = []
mock_template_svc.rollback_to_version.return_value = MagicMock(
id=TEST_TEMPLATE_ID,
name="回滚后的模板",
status="active",
version=3,
)
mock_template_svc.list_clip_configs.return_value = []
mock_plan_svc = MagicMock()
mock_plan_svc.get_plan_or_raise.return_value = mock_plan
@@ -449,3 +458,70 @@ class TestSubtitleRoutes:
# ---------------------------------------------------------------------------
# 片段调整端点测试
# ---------------------------------------------------------------------------
# ---------------------------------------------------------------------------
# 版本管理端点测试
# ---------------------------------------------------------------------------
class TestVersioningEndpoints:
"""模板版本历史 + 回滚端点测试"""
def test_publish_returns_version(self, client):
"""发布后返回新版本号"""
c, mock_tpl_svc, _ = client
resp = c.post(BASE + "/publish")
assert resp.status_code == 200
data = resp.json()
assert data["version"] == 2
assert data["status"] == "published"
def test_list_versions_empty(self, client):
"""查询版本历史，空列表也正常返回"""
c, mock_tpl_svc, _ = client
resp = c.get(BASE + "/versions")
assert resp.status_code == 200
data = resp.json()
assert data["total"] == 0
assert data["versions"] == []
mock_tpl_svc.list_template_versions.assert_called_once_with(TEST_TEMPLATE_ID, limit=50)
def test_list_versions_with_limit(self, client):
"""版本历史支持 limit 参数"""
c, mock_tpl_svc, _ = client
resp = c.get(BASE + "/versions?limit=10")
assert resp.status_code == 200
mock_tpl_svc.list_template_versions.assert_called_once_with(TEST_TEMPLATE_ID, limit=10)
def test_list_versions_limit_too_large_422(self, client):
"""limit 超过上限返回 422"""
c, _, _ = client
resp = c.get(BASE + "/versions?limit=500")
assert resp.status_code == 422
def test_rollback_success(self, client):
"""回滚到指定版本成功"""
c, mock_tpl_svc, _ = client
resp = c.post(BASE + "/rollback", json={"version": 1})
assert resp.status_code == 200
data = resp.json()
assert data["status"] == "rolled_back"
assert data["rollback_to_version"] == 1
assert data["new_version"] == 3
assert data["template_id"] == TEST_TEMPLATE_ID
mock_tpl_svc.rollback_to_version.assert_called_once_with(TEST_TEMPLATE_ID, 1)
def test_rollback_missing_version_422(self, client):
"""回滚请求缺 version 返回 422"""
c, _, _ = client
resp = c.post(BASE + "/rollback", json={})
assert resp.status_code == 422
def test_rollback_value_error_400(self, client):
"""回滚目标版本不存在返回 400"""
c, mock_tpl_svc, _ = client
mock_tpl_svc.rollback_to_version.side_effect = ValueError("版本不存在")
resp = c.post(BASE + "/rollback", json={"version": 99})
assert resp.status_code == 400
assert "不存在" in resp.json()["detail"]