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 功能

只需创建一个引擎文件：

```python
# 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

```bash
# 执行引擎 (同步)
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
```

---

## 测试

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

---

## 注意事项

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