TravelContentCreator/docs/MIGRATION_PROGRESS.md

TravelContentCreator 架构迁移进度

迁移状态

Phase	状态	完成日期
Phase 1: 基础结构创建	✅ 完成	2024-12-08
Phase 2: 引擎封装	✅ 完成	2024-12-08
Phase 3: API 集成	✅ 完成	2024-12-08
Phase 4: 基础设施层	✅ 完成	2024-12-08
Phase 5: ppid 支持	✅ 完成	2024-12-08
Phase 6: 旧代码拆分	✅ 完成	2024-12-08
Phase 7: 清理优化	🔲 待开始	-

---

Phase 1: 基础结构创建 ✅

已完成

1. 路径配置 (config/paths.json)

   • 项目路径配置化，避免硬编码

2. 领域层结构 (domain/)

   domain/
   ├── __init__.py
   └── aigc/
       ├── __init__.py
       ├── engine_registry.py      # 引擎注册表
       ├── engine_executor.py      # 引擎执行器
       ├── engines/
       │   ├── __init__.py
       │   ├── base.py             # 引擎基类
       │   ├── poster_generate.py  # 海报生成引擎
       │   ├── content_generate.py # 内容生成引擎
       │   └── topic_generate.py   # 选题生成引擎
       └── shared/
           ├── __init__.py
           ├── component_factory.py    # 组件工厂
           ├── llm_client.py           # LLM 客户端
           ├── prompt_builder.py       # 提示词构建器
           ├── image_processor.py      # 图片处理器
           ├── database_accessor.py    # 数据库访问器
           └── file_storage.py         # 文件存储
   

---

Phase 2: 引擎封装 ✅

已完成

1. PosterGenerateEngine - 封装现有 PosterService
2. ContentGenerateEngine - 封装现有 TweetService 内容生成
3. TopicGenerateEngine - 封装现有 TweetService 选题生成

引擎特性

• 统一的参数 Schema 定义
• 自动参数验证
• 进度追踪
• 执行时间预估

---

Phase 3: API 集成 ✅

已完成

1. AIGC 统一路由 (api/routers/aigc.py)

   • POST /api/v2/aigc/execute - 执行引擎
   • GET /api/v2/aigc/task/{task_id}/status - 查询任务状态
   • POST /api/v2/aigc/task/{task_id}/cancel - 取消任务
   • GET /api/v2/aigc/engines - 列出所有引擎
   • GET /api/v2/aigc/engines/{engine_id} - 获取引擎详情
   • GET /api/v2/aigc/tasks - 列出任务
   • POST /api/v2/aigc/tasks/cleanup - 清理任务

2. 主应用集成 (api/main.py)

   • V1 API 保持不变
   • V2 API 新增 AIGC 统一入口

---

Phase 4: 基础设施层 ✅

已完成

1. 数据库连接管理 (infrastructure/database/connection.py)

   • 连接池管理
   • 配置加载（支持环境变量）
   • 上下文管理器

2. Repository 基类 (infrastructure/database/base_repository.py)

   • 通用 CRUD 操作
   • 软删除支持
   • 批量查询

3. 具体 Repository (infrastructure/database/repositories/)

   • ScenicSpotRepository - 景区
   • ProductRepository - 产品
   • ProductPackageRepository - 套餐 (ppid)
   • StyleRepository - 风格
   • AudienceRepository - 受众
   • TemplateRepository - 模板

---

Phase 5: ppid 支持 ✅

已完成

1. 所有引擎支持 ppid 参数

   • poster_generate - 海报生成
   • content_generate - 内容生成
   • topic_generate - 选题生成

2. ppid 解析逻辑

   • ProductPackageRepository.resolve_ids(ppid) - 解析为 scenic_spot_id + product_id
   • DatabaseAccessor.resolve_ppid(ppid) - 便捷方法

3. 与 Java 端对齐

   • 参考 AigcCompatibilityService.getOriginalIdsByPackageId()
   • 统一使用 ppid 作为入口

---

Phase 6: 旧代码拆分 ✅

已完成

1. 海报领域模块 (domain/poster/)

   • TemplateManager - 模板加载和管理
   • FabricGenerator - Fabric.js JSON 生成
   • PosterRenderer - 海报渲染和输出

2. 内容领域模块 (domain/content/)

   • TopicEngine - 选题生成引擎
   • ContentEngine - 内容生成引擎
   • JudgeEngine - 内容审核引擎
   • TopicIDMappingManager - ID 映射管理

3. 引擎集成

   • PosterGenerateEngine 可使用新的 TemplateManager, FabricGenerator, PosterRenderer
   • TopicGenerateEngine 可使用新的 TopicEngine
   • ContentGenerateEngine 可使用新的 ContentEngine, JudgeEngine

迁移策略

当前采用渐进式迁移：

• 新引擎同时保留旧服务调用和新模块调用
• 可通过配置切换使用哪个实现
• 验证新模块功能后，逐步移除旧服务依赖

---

Phase 7: 清理优化 (待开始)

计划

1. 删除冗余代码
2. 更新 import 路径
3. 添加单元测试
4. 性能优化

---

使用指南

新增 AIGC 功能

只需创建一个引擎文件：

# domain/aigc/engines/new_feature.py

from .base import BaseAIGCEngine, EngineResult

class NewFeatureEngine(BaseAIGCEngine):
    engine_id = "new_feature"
    engine_name = "新功能"
    version = "1.0.0"
    description = "功能描述"
    
    def get_param_schema(self):
        return {
            "param1": {"type": "str", "required": True, "desc": "参数1"},
        }
    
    async def execute(self, params):
        # 实现逻辑
        return EngineResult(success=True, data={...})

引擎会被自动发现和注册。

调用 API

# 执行引擎 (同步)
curl -X POST http://localhost:8000/api/v2/aigc/execute \
  -H "Content-Type: application/json" \
  -d '{"engine": "poster_generate", "params": {"template_id": "vibrant", "images": [...]}}'

# 执行引擎 (异步)
curl -X POST http://localhost:8000/api/v2/aigc/execute \
  -H "Content-Type: application/json" \
  -d '{"engine": "poster_generate", "params": {...}, "async_mode": true}'

# 查询任务状态
curl http://localhost:8000/api/v2/aigc/task/{task_id}/status

# 列出所有引擎
curl http://localhost:8000/api/v2/aigc/engines

---

测试

# 运行测试
cd /root/TravelContentCreator
python3 tests/test_aigc_engines.py

---

注意事项

1. V1 API 保持兼容 - 现有调用不受影响
2. 渐进式迁移 - 新引擎封装旧服务，逐步替换
3. 路径配置化 - 所有路径通过 config/paths.json 配置