TravelContentCreator/docs/POSTER_V2_MODULE.md

海报模块 v2 (poster_v2)

概述

基于小红书风格的海报生成模块，支持5种布局、5种主题，可与真实图片结合生成美观的营销海报。

目录结构

poster_v2/
├── __init__.py              # 入口: PosterFactory, PosterContent, Theme
├── factory.py               # PosterFactory 统一生成入口
├── config.py                # 配置管理 (从项目统一配置读取)
├── schemas/
│   ├── content.py           # PosterContent 数据模型
│   └── theme.py             # Theme 主题配置
├── layouts/
│   ├── base.py              # BaseLayout 抽象基类
│   ├── hero_bottom.py       # 布局A: 大图底部文字
│   ├── overlay_center.py    # 布局B: 居中叠加
│   ├── overlay_bottom.py    # 布局C: 底部毛玻璃
│   ├── split_vertical.py    # 布局D: 左图右文
│   └── card_float.py        # 布局E: 悬浮卡片
├── renderers/
│   ├── text.py              # 文字渲染器
│   ├── shape.py             # 形状渲染器
│   └── effect.py            # 效果渲染器
└── themes/
    └── __init__.py

使用方式

基础用法

from poster_v2 import PosterFactory, PosterContent

factory = PosterFactory()

# 直接生成
poster = factory.generate(
    layout="hero_bottom",
    theme="ocean",
    title="景点标题",
    subtitle="副标题描述",
    price="¥199",
    tags=["周末游", "亲子"]
)
poster.save("output.png")

带真实图片

from PIL import Image

img = Image.open("photo.jpg")
content = PosterContent(
    title="广东小新疆",
    subtitle="绝美秘境等你来",
    price="¥0",
    image=img
)
poster = factory.generate_from_content(content, layout="hero_bottom", theme="sunset")

智能推荐布局

# 根据内容特征推荐布局
layout = factory.suggest_layout({"emoji": "🍰"})  # → overlay_bottom
layout = factory.suggest_layout({"features": ["A", "B", "C", "D"]})  # → card_float

5种布局

布局	类名	适用场景	特点
hero_bottom	HeroBottomLayout	景点、美食、通用	大图+底部渐变文字区
overlay_center	OverlayCenterLayout	攻略、活动	居中大标题+装饰线
overlay_bottom	OverlayBottomLayout	美食探店	底部毛玻璃+emoji支持
split_vertical	SplitVerticalLayout	酒店、民宿	左图右文50/50分栏
card_float	CardFloatLayout	精品推荐	悬浮白色卡片+阴影

5种主题

主题	名称	主色	适用场景
ocean	深青海洋	#4A8B8B	海洋、旅游、清新
sunset	日落暖橙	#D66853	美食、活力、温暖
peach	蜜桃粉	#D4918A	甜品、少女、浪漫
mint	薄荷绿	#6A9B88	自然、民宿、健康
latte	拿铁咖啡	#8B7355	咖啡、高级、复古

PosterContent 字段

字段	类型	说明
title	str	主标题 (必填)
subtitle	str	副标题
price	str	价格 (如 "¥199")
price_suffix	str	价格后缀 (如 "/人")
tags	List[str]	标签列表
highlights	List[str]	亮点标签 (overlay_bottom)
features	List[str]	特色列表 (card_float)
details	List[str]	详情列表
label	str	角标 (如 "精选推荐")
emoji	str	emoji符号
image	PIL.Image	背景图片

配置

配置优先级：

1. 环境变量 POSTER_FONT_DIR / POSTER_EMOJI_FONT
2. 项目配置 config/app.yaml → paths.resource.font
3. 默认值 assets/font

测试脚本

# 基础测试
python scripts/test_poster_v2.py

# 真实图片测试
python scripts/test_poster_v2_real_image.py

输出目录：

• result/poster_v2_test/ - 基础测试结果
• result/poster_v2_real/ - 真实图片测试结果

API 接口

方式1: 智能海报生成 (推荐)

AI 自动生成海报文案，适合只有产品基本信息的场景：

POST /api/aigc/execute
{
    "engine": "poster_smart",
    "params": {
        "category": "景点",
        "name": "正佳极地海洋世界",
        "description": "位于广州正佳广场的大型海洋馆",
        "price": "199元/人",
        "location": "广州天河",
        "features": "企鹅馆, 海豚表演, 儿童乐园",
        "target_audience": "亲子家庭",
        "image_url": "https://...",
        
        // 可选: 覆盖AI推荐
        "override_layout": "hero_bottom",
        "override_theme": "ocean"
    }
}

返回：

{
    "success": true,
    "data": {
        "image_base64": "...",
        "layout": "hero_bottom",
        "theme": "ocean",
        "generated_content": {
            "title": "🐧 正佳海洋世界真的绝了",
            "subtitle": "周末带娃去的，企鹅太可爱了！",
            "highlights": ["适合遛娃", "出片率高"],
            "price": "¥199"
        }
    }
}

方式2: 直接海报生成

已有完整文案时使用：

POST /api/aigc/execute
{
    "engine": "poster_generate_v3",
    "params": {
        "layout": "hero_bottom",
        "theme": "ocean",
        "content": {
            "title": "标题",
            "subtitle": "副标题",
            "price": "¥199",
            "tags": ["周末游", "亲子"]
        },
        "image_url": "https://..."
    }
}

响应

{
    "success": true,
    "data": {
        "image_base64": "...",
        "layout": "hero_bottom",
        "theme": "ocean"
    }
}

服务层直接调用

from poster_v2 import get_poster_service_v2

service = get_poster_service_v2()

result = service.generate(
    layout="hero_bottom",
    theme="ocean",
    content={"title": "标题", "price": "¥199"},
    image_base64="..."  # 可选
)

设计原则

1. 布局与渲染分离 - Layout 负责计算位置，Renderer 负责绘制
2. 动态内容适配 - 内容区域根据文案自动计算高度
3. 主题可配置 - 配色/字体可通过主题切换
4. 单一职责 - 每个布局类只负责一种布局