TravelContentCreator/docs/POSTER_REFACTOR_PLAN.md

海报系统重构方案 (方案 C)

完整重构计划，将海报系统改造为 YAML 配置化、模块化的架构

一、当前状态 (方案 B 完成后)

已完成

• ✅ domain/poster/poster_service.py - 轻量服务 (无数据库依赖)
• ✅ domain/aigc/engines/poster_generate_v2.py - V2 引擎
• ✅ API 可用: POST /api/v2/aigc/execute (engine=poster_generate)

遗留问题

问题	文件	说明
巨型模板文件	vibrant_template.py (78KB)	难以维护
模板 bug	_generate_legacy	images 参数处理不一致
配置硬编码	模板内部	颜色、字体、布局都写死
旧服务残留	api/services/poster.py	3000+ 行，依赖已删除模块

---

二、目标架构

domain/poster/                    # 海报核心模块
├── __init__.py
├── poster_service.py            # 主服务 (已有)
├── poster_renderer.py           # 渲染器 (已有)
├── template_manager.py          # 模板管理器 (新增)
└── templates/                   # 模板目录 (新增)
    ├── base.py                  # 基类
    ├── vibrant/
    │   ├── config.yaml          # 模板配置
    │   ├── handler.py           # 渲染逻辑
    │   └── preview.png          # 预览图
    ├── business/
    │   ├── config.yaml
    │   └── handler.py
    └── collage/
        ├── config.yaml
        └── handler.py

prompts/poster/                   # 海报 Prompt
├── v1.0.0.yaml                  # 文案生成 Prompt
└── templates.yaml               # 模板元数据索引

---

三、模板配置 YAML 化

示例: templates/vibrant/config.yaml

meta:
  id: vibrant
  name: 活力风格
  description: 适合景点、活动等充满活力的场景
  version: "1.0.0"
  preview: preview.png

# 画布配置
canvas:
  width: 1350
  height: 1800
  background: transparent

# 颜色主题
colors:
  presets:
    ocean_deep:
      gradient: [[0, 30, 80], [20, 120, 220]]
    sunset_warm:
      gradient: [[255, 94, 77], [255, 154, 0]]
    cool_mint:
      gradient: [[64, 224, 208], [127, 255, 212]]
  default: ocean_deep

# 毛玻璃效果
glass_effect:
  max_opacity: 240
  blur_radius: 22
  transition_height: 120
  intensity_multiplier: 1.5

# 字体配置
fonts:
  title:
    path: assets/font/兰亭粗黑简.TTF
    size: 72
    color: [255, 255, 255]
  content:
    path: assets/font/兰亭粗黑简.TTF
    size: 36
    color: [255, 255, 255, 200]
  tag:
    path: assets/font/兰亭粗黑简.TTF
    size: 28
    color: [255, 255, 255, 180]

# 布局配置
layout:
  title:
    position: [50, 1200]
    max_width: 1250
  content:
    position: [50, 1350]
    max_width: 1250
    line_height: 1.5
  tag:
    position: [50, 1700]

---

四、重构步骤

Phase 1: 模板管理器 (1天)

# domain/poster/template_manager.py

class TemplateManager:
    """
    模板管理器
    - 从 YAML 加载模板配置
    - 动态实例化模板处理器
    - 支持热重载
    """
    
    def __init__(self, templates_dir: str):
        self.templates_dir = Path(templates_dir)
        self._configs = {}
        self._handlers = {}
    
    def load_template(self, template_id: str) -> TemplateConfig:
        """加载模板配置"""
        config_path = self.templates_dir / template_id / 'config.yaml'
        ...
    
    def get_handler(self, template_id: str) -> BaseTemplateHandler:
        """获取模板处理器"""
        ...

Phase 2: 拆分巨型模板 (2天)

将 vibrant_template.py (78KB) 拆分为:

templates/vibrant/
├── config.yaml          # 配置 (从代码中提取)
├── handler.py           # 核心渲染逻辑 (~500行)
├── effects.py           # 特效函数 (毛玻璃等)
├── text_layout.py       # 文字排版
└── color_utils.py       # 颜色处理

Phase 3: 统一模板接口 (1天)

# domain/poster/templates/base.py

class BaseTemplateHandler(ABC):
    """模板处理器基类"""
    
    def __init__(self, config: TemplateConfig):
        self.config = config
    
    @abstractmethod
    def render(
        self,
        image: Image.Image,
        content: Dict[str, Any],
        **options
    ) -> RenderResult:
        """渲染海报"""
        pass
    
    def render_to_base64(self, ...) -> str:
        """渲染并返回 Base64"""
        ...
    
    def render_to_fabric_json(self, ...) -> dict:
        """渲染并返回 Fabric.js JSON"""
        ...

Phase 4: 清理旧代码 (0.5天)

• 删除 api/services/poster.py (3000+ 行)
• 删除 poster/poster_generator.py (旧入口)
• 更新 utils/__init__.py 移除无效导入

Phase 5: 海报 Prompt 管理 (0.5天)

# prompts/poster/v1.0.0.yaml

meta:
  name: poster_content
  version: "1.0.0"
  description: "海报文案生成"

system: |
  你是一个专业的营销文案策划，擅长创作吸引眼球的海报文案。

user: |
  请为以下景区/产品创作海报文案：
  
  ## 产品信息
  {{ product_info }}
  
  ## 要求
  - 标题: 10字以内，吸引眼球
  - 副标题: 20字以内，突出卖点
  - 标签: 3-5个热门标签

---

五、预期收益

指标	当前	重构后
模板文件大小	78KB (单文件)	~5KB (配置) + ~500行 (代码)
新增模板难度	需要写 Python	只需写 YAML 配置
配置修改	改代码重启	改 YAML 热重载
代码可维护性	低	高

---

六、时间估算

阶段	工作量	优先级
Phase 1: 模板管理器	1天	P1
Phase 2: 拆分模板	2天	P1
Phase 3: 统一接口	1天	P1
Phase 4: 清理旧代码	0.5天	P2
Phase 5: Prompt 管理	0.5天	P2
总计	5天

---

七、风险与注意事项

1. 向后兼容: Java 端调用接口不变
2. 模板效果: 重构后视觉效果需与原版一致
3. 性能: 配置加载需要缓存，避免每次渲染都读文件
4. 测试: 需要对比测试，确保输出一致

---

八、下一步行动

1. 确认是否立即开始方案 C
2. 或先处理热点爬虫需求
3. 或先完善其他功能