TravelContentCreator/docs/REFACTORING_IMPLEMENTATION.md

技术债务重构实施文档

本文档记录技术债务改进的具体实施过程

---

实施计划

#	改进项	状态	完成时间
1	数据库访问改接口	✅ 完成	2024-12-08
2	图片传输改 URL	✅ 完成	2024-12-08
3	放弃 ppid	✅ 完成	2024-12-08
4	Prompt Registry	✅ 完成	2024-12-08
5	依赖注入统一	✅ 完成	2024-12-08

---

1. 数据库访问改接口

目标

Python 端不再直接连接数据库，所有数据由 Java 端通过 HTTP 接口传递。

改动前架构

┌─────────────┐     ┌─────────────┐
│   Java 端   │     │  Python 端  │
└──────┬──────┘     └──────┬──────┘
       │                   │
       │  各自连接          │  各自连接
       ▼                   ▼
    ┌─────────────────────────┐
    │         MySQL           │
    └─────────────────────────┘

改动后架构

┌─────────────┐                    ┌─────────────┐
│   Java 端   │ ──── HTTP ────────>│  Python 端  │
└──────┬──────┘   (完整数据)        └─────────────┘
       │                                  │
       │  唯一数据源                       │ 无数据库访问
       ▼                                  │
    ┌─────────────────────────┐           │
    │         MySQL           │           X
    └─────────────────────────┘

新的接口协议

Java 端调用 Python 端时，传递完整数据：

{
  "engine": "topic_generate",
  "params": {
    "num_topics": 5,
    "month": "2024-12",
    
    // 直接传完整对象，而不是 ID
    "scenic_spot": {
      "id": 1,
      "name": "天津冒险湾",
      "description": "主题乐园...",
      "location": "天津市"
    },
    "product": {
      "id": 10,
      "name": "门票套餐",
      "price": 299,
      "description": "..."
    },
    "style": {
      "id": 5,
      "name": "攻略风",
      "description": "实用性强..."
    },
    "audience": {
      "id": 3,
      "name": "亲子家庭",
      "description": "..."
    }
  }
}

实施步骤

1. 定义新的参数 Schema
2. 创建 V2 引擎接收完整对象
3. V2 引擎不访问数据库
4. 更新 Java 端调用方式 (待 Java 端配合)

已创建文件

• domain/aigc/engines/topic_generate_v2.py - 选题生成 V2
• domain/aigc/engines/content_generate_v2.py - 内容生成 V2
• domain/aigc/engines/poster_generate_v2.py - 海报生成 V2

---

2. 图片传输改 URL

目标

不再传递 Base64，改为传递图片 URL 或路径。

新的接口协议

{
  "engine": "poster_generate",
  "params": {
    "template_id": "vibrant",
    
    // 方式1: S3 URL
    "image_urls": [
      "https://s3.xxx.com/bucket/image1.jpg",
      "https://s3.xxx.com/bucket/image2.jpg"
    ],
    
    // 方式2: 本地路径 (如果共享存储)
    "image_paths": [
      "/data/images/123.jpg"
    ],
    
    // 方式3: 素材 ID (Python 自行获取)
    "material_ids": [123, 456]
  }
}

实施步骤

1. 修改引擎支持 URL 下载
2. 添加图片下载工具 (aiohttp)
3. 更新 Java 端传参方式 (待 Java 端配合)

已实现

PosterGenerateEngineV2 支持三种图片来源:

• image_urls - 从 URL 下载 (推荐)
• image_paths - 从本地路径读取
• images_base64 - Base64 (兼容旧接口)

---

3. 放弃 ppid

目标

不再使用 ppid，Java 端直接传递解析后的完整数据。

改动

• 移除 Python 端的 resolve_ppid() 逻辑
• 移除 ProductPackageRepository
• 引擎参数 Schema 中移除 ppid

实施步骤

1. V2 引擎不包含 ppid 参数
2. V2 引擎不访问 ProductPackageRepository
3. 参数 Schema 只接收完整对象

说明

V2 引擎的参数 Schema 中没有 ppid，只接收:

• scenic_spot - 完整景区对象
• product - 完整产品对象
• style - 完整风格对象
• audience - 完整受众对象

Java 端需要在调用前解析 ppid 并传递完整数据。

---

4. Prompt Registry

目标

集中管理 Prompt，支持版本化。

目录结构

prompts/
├── topic_generate/
│   └── v1.0.0.yaml
├── content_generate/
│   └── v1.0.0.yaml
└── content_judge/
    └── v1.0.0.yaml

实施步骤

1. 创建 domain/prompt/ 模块
2. 实现 PromptRegistry 类
3. 迁移现有 prompt 到 YAML
4. V2 引擎使用新 Registry

已创建文件

模块:

• domain/prompt/__init__.py
• domain/prompt/registry.py - PromptRegistry 实现

Prompt 配置:

• prompts/topic_generate/v1.0.0.yaml
• prompts/content_generate/v1.0.0.yaml
• prompts/content_judge/v1.0.0.yaml

使用示例

from domain.prompt import PromptRegistry

registry = PromptRegistry('prompts')

# 渲染 prompt
system, user = registry.render(
    'content_generate',
    context={'style_content': '...', 'demand_content': '...', ...},
    version='latest'
)

# 获取模型参数
config = registry.get('content_generate')
params = config.get_model_params()  # {'temperature': 0.3, ...}

---

5. 依赖注入统一

目标

统一使用容器模式管理依赖。

实施步骤

1. 创建 Container 类
2. 实现服务注册和获取
3. 逐步迁移现有依赖获取方式 (渐进式)

已创建文件

• domain/container.py - Container 实现

使用示例

from domain.container import Container, get_service, inject

# 方式1: 直接获取
from core.config import ConfigManager
config = Container.get(ConfigManager)

# 方式2: 便捷函数
from domain import get_service
config = get_service(ConfigManager)

# 方式3: 装饰器注入
@inject(ConfigManager, AIAgent)
def my_function(config, agent, other_param):
    ...

说明

Container 采用渐进式迁移策略:

• 新代码使用 Container
• 旧代码保持不变，逐步迁移
• V2 引擎内部使用延迟加载，兼容两种方式

---

变更日志

日期	改动	文件
2024-12-08	创建实施文档	docs/REFACTORING_IMPLEMENTATION.md
2024-12-08	创建 PromptRegistry	domain/prompt/registry.py
2024-12-08	创建 Container	domain/container.py
2024-12-08	创建 V2 引擎	domain/aigc/engines/*_v2.py
2024-12-08	迁移 Prompt 到 YAML	prompts/*.yaml

---

新旧引擎对比

特性	V1 引擎	V2 引擎
数据库访问	✅ 直接访问	❌ 不访问
ppid 支持	✅ 自动解析	❌ 不支持
图片传输	Base64	URL/路径/Base64
Prompt 管理	文件模板	PromptRegistry
依赖注入	延迟加载	Container

Java 端调用示例

V1 引擎 (旧)

{
  "engine": "topic_generate",
  "params": {
    "ppid": 12345,
    "num_topics": 5
  }
}

V2 引擎 (新)

{
  "engine": "topic_generate_v2",
  "params": {
    "num_topics": 5,
    "month": "2024-12",
    "scenic_spot": {
      "id": 1,
      "name": "天津冒险湾",
      "description": "..."
    },
    "product": {
      "id": 10,
      "name": "门票套餐",
      "price": 299
    }
  }
}

---

待办事项

• Java 端更新调用方式，使用 V2 引擎
• 验证 V2 引擎功能正确性
• 清理 V1 引擎中的数据库访问代码 (可选)
• 删除 Python 端的 database_service.py (待确认无其他依赖)