feat: unify template segments data source to template_clip_configs

- template_repository: read/write segments via template_clip_configs table
  instead of old template_segments table
- list_segments: prefer template_clip_configs, fallback to template_segments
  for backward compatibility with existing data
- create_segments: write to template_clip_configs with material_type
  stored in config JSON field
- delete: clean both tables for safe cleanup
- Alembic migration 060: one-time migrate orphaned template_segments
  records to template_clip_configs
- 10 new tests covering the unified behavior

packages/adapters/sqlalchemy_impl/template_repository.py

@@ -1,4 +1,8 @@
-"""SQLAlchemy implementation of TemplateRepository."""
+"""SQLAlchemy implementation of TemplateRepository.
+
+模板 segments 数据源已统一为 template_clip_configs 表。
+旧 template_segments 表不再读写，保留表结构供历史数据查询。
+"""
 
 from __future__ import annotations
 
@@ -10,6 +14,7 @@ from sqlalchemy.orm import Session
 from packages.adapters.sqlalchemy_impl.models import (
     EditPlanModel,
     TemplateCategoryModel,
+    TemplateClipConfigModel,
     TemplateModel,
     TemplateSegmentModel,
 )
@@ -47,27 +52,25 @@ class SQLAlchemyTemplateRepository:
             like_pattern = f"%{keyword}%"
             query = query.filter(TemplateModel.name.like(like_pattern))
         if tag:
-            # JSON 数组包含指定标签（MySQL JSON_CONTAINS / SQLite json_each 兼容写法用 LIKE）
             query = query.filter(TemplateModel.tags.like(f'%"{tag}"%'))
         models = query.order_by(TemplateModel.created_at.desc()).offset(skip).limit(limit).all()
         templates = [self._model_to_entity(m) for m in models]
-        # 批量加载所有 segments，避免 N+1 查询
+        # 批量加载 segments：从 template_clip_configs 读取，映射为 TemplateSegment
         if templates:
             template_ids = [t.id for t in templates]
-            seg_models = (
-                self.session.query(TemplateSegmentModel)
-                .filter(TemplateSegmentModel.template_id.in_(template_ids))
-                .order_by(TemplateSegmentModel.segment_order)
+            clip_models = (
+                self.session.query(TemplateClipConfigModel)
+                .filter(TemplateClipConfigModel.template_id.in_(template_ids))
+                .order_by(TemplateClipConfigModel.order)
                 .all()
             )
-            # 按 template_id 分组
-            seg_map: dict[str, list] = {}
-            for sm in seg_models:
-                seg_map.setdefault(sm.template_id, []).append(
-                    self._segment_model_to_entity(sm),
+            clip_map: dict[str, list] = {}
+            for cm in clip_models:
+                clip_map.setdefault(cm.template_id, []).append(
+                    self._clip_config_to_segment(cm),
                 )
             for t in templates:
-                t.segments = seg_map.get(t.id, [])
+                t.segments = clip_map.get(t.id, [])
         return templates
 
     def get(self, template_id: str, user_id: str) -> Optional[Template]:
@@ -100,7 +103,6 @@ class SQLAlchemyTemplateRepository:
             is_active=template.is_active,
         )
         self.session.add(model)
-        # flush 而非 commit，让 create + create_segments 在同一事务中提交
         self.session.flush()
         self.session.refresh(model)
         result = self._model_to_entity(model)
@@ -145,7 +147,11 @@ class SQLAlchemyTemplateRepository:
         if model is None:
             return False
         model.is_active = False
-        # 级联清理关联的 segments，避免孤儿数据
+        # 清理 template_clip_configs（主数据源）
+        self.session.query(TemplateClipConfigModel).filter(
+            TemplateClipConfigModel.template_id == template_id,
+        ).delete(synchronize_session=False)
+        # 同时清理旧 template_segments（兼容历史数据）
         self.session.query(TemplateSegmentModel).filter(
             TemplateSegmentModel.template_id == template_id,
         ).delete(synchronize_session=False)
@@ -167,8 +173,6 @@ class SQLAlchemyTemplateRepository:
         )
         if category:
             query = query.filter(TemplateModel.category == category)
-        if mode:
-            query = query.filter(TemplateModel.mode == mode)
         if keyword:
             query = query.filter(TemplateModel.name.like(f"%{keyword}%"))
         if tag:
@@ -176,7 +180,7 @@ class SQLAlchemyTemplateRepository:
         return query.count()
 
     def copy_template(self, template_id: str, user_id: str, new_name: str) -> Template:
-        """复制模板（含所有 segments）。"""
+        """复制模板（含所有 segments，从 template_clip_configs 读取并写入）。"""
         source = self.get(template_id, user_id)
         if source is None:
             raise ValueError(f"Template {template_id} not found")
@@ -197,7 +201,7 @@ class SQLAlchemyTemplateRepository:
         )
         created = self.create(new_template)
 
-        # 复制 segments
+        # 复制 segments → 写入 template_clip_configs
         new_segments: List[TemplateSegment] = []
         for seg in source.segments:
             new_seg = TemplateSegment(
@@ -209,50 +213,85 @@ class SQLAlchemyTemplateRepository:
                 material_type=seg.material_type,
             )
             new_segments.append(new_seg)
-            model = TemplateSegmentModel(
+            config = {"material_type": seg.material_type} if seg.material_type else {}
+            clip_model = TemplateClipConfigModel(
                 id=new_seg.id,
-                template_id=new_seg.template_id,
-                segment_order=new_seg.segment_order,
-                duration_min=new_seg.duration_min,
-                duration_max=new_seg.duration_max,
-                material_type=new_seg.material_type,
+                template_id=new_id,
+                clip_type="main",
+                order=new_seg.segment_order,
+                min_duration=new_seg.duration_min,
+                max_duration=new_seg.duration_max,
+                text_template="",
+                material_requirements={},
+                transition_effect="cut",
+                config=config,
             )
-            self.session.add(model)
+            self.session.add(clip_model)
         if new_segments:
             self.session.commit()
 
         created.segments = new_segments
         return created
 
-    # ── Segments ──
+    # ── Segments（数据源：template_clip_configs）──
 
     def list_segments(self, template_id: str) -> List[TemplateSegment]:
-        models = (
+        """从 template_clip_configs 读取并按 TemplateSegment 格式返回。
+
+        优先读 template_clip_configs；如果为空则回退读旧 template_segments（兼容历史数据）。
+        """
+        clip_models = (
+            self.session.query(TemplateClipConfigModel)
+            .filter(TemplateClipConfigModel.template_id == template_id)
+            .order_by(TemplateClipConfigModel.order)
+            .all()
+        )
+        if clip_models:
+            return [self._clip_config_to_segment(m) for m in clip_models]
+
+        # 回退：读旧 template_segments 表（历史数据兼容）
+        old_models = (
             self.session.query(TemplateSegmentModel)
             .filter(TemplateSegmentModel.template_id == template_id)
             .order_by(TemplateSegmentModel.segment_order)
             .all()
         )
-        return [self._segment_model_to_entity(m) for m in models]
+        return [self._segment_model_to_entity(m) for m in old_models]
 
     def create_segments(self, segments: List[TemplateSegment]) -> List[TemplateSegment]:
+        """将 segments 写入 template_clip_configs 表。
+
+        material_type 信息保存在 config JSON 字段中。
+        """
         for seg in segments:
-            model = TemplateSegmentModel(
+            config = {"material_type": seg.material_type} if seg.material_type else {}
+            clip_model = TemplateClipConfigModel(
                 id=seg.id,
                 template_id=seg.template_id,
-                segment_order=seg.segment_order,
-                duration_min=seg.duration_min,
-                duration_max=seg.duration_max,
-                material_type=seg.material_type,
+                clip_type="main",
+                order=seg.segment_order,
+                min_duration=seg.duration_min,
+                max_duration=seg.duration_max,
+                text_template="",
+                material_requirements={},
+                transition_effect="cut",
+                config=config,
             )
-            self.session.add(model)
+            self.session.add(clip_model)
         self.session.commit()
         return segments
 
     def delete_segments_by_template(self, template_id: str) -> int:
+        """删除 template_clip_configs 中的记录。同时清理旧 template_segments。"""
         count = (
-            self.session.query(TemplateSegmentModel).filter(TemplateSegmentModel.template_id == template_id).delete()
+            self.session.query(TemplateClipConfigModel)
+            .filter(TemplateClipConfigModel.template_id == template_id)
+            .delete()
         )
+        # 同时清理旧表（兼容历史数据）
+        self.session.query(TemplateSegmentModel).filter(
+            TemplateSegmentModel.template_id == template_id,
+        ).delete(synchronize_session=False)
         self.session.commit()
         return count
 
@@ -353,8 +392,25 @@ class SQLAlchemyTemplateRepository:
             updated_at=model.updated_at,
         )
 
+    @staticmethod
+    def _clip_config_to_segment(model: TemplateClipConfigModel) -> TemplateSegment:
+        """将 TemplateClipConfigModel 映射为 TemplateSegment（前端兼容格式）。"""
+        config = model.config or {}
+        material_type = config.get("material_type")
+        return TemplateSegment(
+            id=model.id,
+            template_id=model.template_id,
+            segment_order=model.order,
+            duration_min=model.min_duration or 0.0,
+            duration_max=model.max_duration or 0.0,
+            material_type=material_type,
+            created_at=model.created_at,
+            updated_at=model.updated_at,
+        )
+
     @staticmethod
     def _segment_model_to_entity(model: TemplateSegmentModel) -> TemplateSegment:
+        """兼容旧 template_segments 表的映射（仅用于历史数据回退读取）。"""
         return TemplateSegment(
             id=model.id,
             template_id=model.template_id,