# TravelContentCreator 项目状态文档

> 更新日期: 2024-12-10  
> 版本: 2.3.0

---

## 1. 项目概述

TravelContentCreator 是一个旅游内容自动生成系统的 Python 后端服务，提供：
- 选题生成 (Topic Generate)
- 内容生成 (Content Generate)
- 海报生成 (Poster Generate)

### 1.1 技术栈

| 组件 | 技术 |
|-----|------|
| Web 框架 | FastAPI |
| AI 模型 | OpenAI API (GPT-4) |
| 模板引擎 | Jinja2 |
| 配置格式 | YAML |
| 运行端口 | 8001 |

### 1.2 目录结构

```
TravelContentCreator/
├── api/                      # FastAPI 应用
│   ├── main.py              # 应用入口
│   └── routers/             # 路由定义
│       ├── v2_aigc.py       # V2 统一 AIGC API
│       └── prompt.py        # Prompt 管理 API
├── domain/                   # 领域逻辑
│   ├── aigc/                # AIGC 引擎
│   │   ├── engines/         # 引擎实现
│   │   │   ├── base.py
│   │   │   ├── topic_generate_v2.py
│   │   │   ├── content_generate_v2.py
│   │   │   └── poster_generate_v2.py
│   │   └── shared/          # 共享组件
│   │       └── llm_client.py
│   └── prompt/              # Prompt 管理
│       ├── __init__.py
│       └── registry.py      # PromptRegistry
├── prompts/                  # Prompt 模板 (YAML)
│   ├── topic_generate/
│   │   ├── v1.0.0.yaml
│   │   └── v2.0.0.yaml
│   ├── content_generate/
│   │   ├── v1.0.0.yaml
│   │   └── v2.0.0.yaml
│   └── content_judge/
│       └── v1.0.0.yaml
├── config/                   # 配置文件
│   ├── styles.yaml          # 风格配置
│   └── audiences.yaml       # 人群配置
├── docs/                     # 文档
│   ├── PROJECT_STATUS.md    # 本文档
│   ├── FIELD_REFACTOR_DESIGN.md
│   ├── FIELD_MAPPING.md
│   └── JAVA_MIGRATION_GUIDE.md
└── tests/                    # 测试
    └── test_full_flow.py
```

---

## 2. Prompt 管理系统

### 2.1 PromptRegistry 核心功能

`PromptRegistry` 是 Prompt 管理的核心组件，位于 `domain/prompt/registry.py`。

**主要功能**：
- YAML 格式 Prompt 加载和解析
- 版本管理 (v1.0.0, v2.0.0, latest)
- Jinja2 模板渲染
- 变量验证
- 模型参数绑定

### 2.2 Prompt YAML 结构

```yaml
# prompts/{engine_name}/{version}.yaml

meta:
  name: topic_generate           # 引擎名称
  version: "2.0.0"               # 版本号
  description: "小红书选题生成"   # 描述
  author: "team"
  created_at: "2024-12-09"
  changelog: "新增热点信息支持"   # 变更说明

model:                           # 模型参数
  temperature: 0.2
  top_p: 0.3
  presence_penalty: 1.5

variables:                       # 变量定义
  num_topics:
    type: integer
    required: true
    description: "选题数量"
  month:
    type: string
    required: true
    description: "选题日期/月份"
  subject:
    type: object
    required: false
    description: "主体信息对象"
  hot_topics:
    type: object
    required: false
    description: "热点信息对象"

system: |                        # System Prompt (Jinja2 模板)
  你是景区小红书的每月选题策划投流师...
  
  ## 选题规则
  1. 根据当前年历...

user: |                          # User Prompt (Jinja2 模板)
  请为以下景区/产品生成 {{ num_topics }} 个选题。
  
  {% if subject %}
  ## 主体信息
  - 名称：{{ subject.name }}
  {% endif %}
```

### 2.3 PromptRegistry API

```python
from domain.prompt import PromptRegistry

# 初始化
registry = PromptRegistry('prompts')

# 获取 Prompt 配置
config = registry.get('topic_generate', 'v2.0.0')
config = registry.get('topic_generate', 'latest')  # 获取最新版本

# 渲染 Prompt
system_prompt, user_prompt = registry.render(
    'topic_generate',
    context={
        'num_topics': 5,
        'month': '2025-02',
        'subject': {...},
        'hot_topics': {...}
    },
    version='v2.0.0'
)

# 获取模型参数
model_params = config.get_model_params()
# {'temperature': 0.2, 'top_p': 0.3, 'presence_penalty': 1.5}

# 列出所有版本
versions = registry.list_versions('topic_generate')
# ['v1.0.0', 'v2.0.0']

# 获取元信息
meta = config.get_meta()
# {'name': 'topic_generate', 'version': '2.0.0', ...}
```

### 2.4 版本管理策略

| 版本 | 说明 |
|-----|------|
| v1.0.0 | 初始版本，基础功能 |
| v2.0.0 | 新增热点信息、参考内容支持 |
| latest | 自动指向最新版本 |

**版本选择逻辑**：
1. 如果指定版本存在，使用指定版本
2. 如果指定 `latest`，使用版本号最大的
3. 如果版本不存在，抛出异常

---

## 3. AIGC 引擎系统

### 3.1 引擎架构

```
BaseAIGCEngine (基类)
├── TopicGenerateEngineV2    # 选题生成
├── ContentGenerateEngineV2  # 内容生成
└── PosterGenerateEngineV2   # 海报生成
```

### 3.2 引擎接口

```python
class BaseAIGCEngine:
    engine_id: str           # 引擎 ID
    engine_name: str         # 引擎名称
    version: str             # 版本
    description: str         # 描述
    
    def get_param_schema(self) -> Dict[str, Any]:
        """定义参数结构"""
        pass
    
    def estimate_duration(self, params: Dict) -> int:
        """预估执行时间(秒)"""
        pass
    
    async def execute(self, params: Dict, task_id: str = None) -> EngineResult:
        """执行引擎"""
        pass
```

### 3.3 当前引擎状态

| 引擎 | 状态 | Prompt 版本 |
|-----|------|------------|
| topic_generate | ✅ 可用 | v1.0.0, v2.0.0 |
| content_generate | ✅ 可用 | v1.0.0, v2.0.0 |
| poster_generate | ⚠️ 待修复 | v1.0.0 |

---

## 4. 字段设计

### 4.1 Subject (主体信息)

参考 Java 端 `ProductPackage` 设计，合并景区和产品信息：

```python
subject = {
    "id": 1,                              # 主体 ID
    "name": "北京环球影城",                # 名称 (packageName)
    "type": "scenic_spot",                # 类型
    "description": "亚洲最大的环球影城",   # 描述
    "location": "北京市通州区",            # 地址 (address)
    "highlights": ["哈利波特", "变形金刚"], # 亮点
    "traffic_info": "地铁1号线...",        # 交通指南
    "products": [                          # 产品列表
        {
            "id": 10,
            "name": "单日票",
            "price": 638,
            "original_price": 738,
            "description": "含一次入园",
            "sales_period": "2025-01-01 至 2025-03-31",
            "usage_rules": "...",
            "package_info": "..."
        }
    ]
}
```

**与 Java ProductPackage 完整对应关系**：

| Python subject | Java ProductPackage | 说明 |
|---------------|---------------------|------|
| id | id | 主键 ID |
| name | packageName / scenicName | 套餐/景区名称 |
| type | dataType | 数据类型 (1景区/2产品/3套餐) |
| description | description | 详细描述 |
| location | address | 地址 |
| traffic_info | trafficInfo | 交通指南 |
| highlights | highlights | 亮点 |
| advantages | advantages | 优势/特色 |
| products[].id | productId | 产品 ID |
| products[].name | - | 产品名称 |
| products[].price | realPrice | 实际价格 |
| products[].original_price | originPrice | 原价 |
| products[].sales_period | salesPeriod | 售卖期 |
| products[].usage_rules | usageRules | 使用规则 |
| products[].package_info | packageInfo | 套票详情 |
| products[].surcharge | surcharge | 加价说明 |
| products[].reservation | reservation | 预约规则 |
| products[].refund | refund | 退改政策 |
| products[].discounts | discounts | 优惠内容 |

### 4.2 Reference (参考内容)

```python
reference = {
    "mode": "reference",  # none / reference / rewrite
    "title": "参考标题",
    "content": "参考正文..."
}
```

### 4.3 内置参考文献库

当用户没有指定 `reference` 时，系统会自动加载内置参考文献库：

| 文件 | 内容 | 数量 |
|-----|------|------|
| `prompts/reference/标题参考格式.json` | 爆款标题模板 | 100+ |
| `prompts/reference/正文范文参考.json` | 完整正文范例 | 10+ |

**使用逻辑**：
- 无 reference 或 `mode: none` → 随机抽取 20 个标题 + 3 篇范文
- 有 reference (`mode: reference/rewrite`) → 使用用户指定的参考内容

**Prompt 版本**：
- v2.0.0: 支持用户指定参考内容
- v2.1.0: 新增内置参考文献库自动加载

### 4.2.1 海报生成 (poster_generate)

**状态**: ✅ 可用 (方案 B 完成)

**架构**:
```
poster_generate_v2.py (v2.1.0)
    └── domain/poster/poster_service.py (轻量服务，无数据库依赖)
        └── poster/templates/*.py (模板渲染)
```

**API 调用**:
```bash
POST /api/v2/aigc/execute
{
  "engine": "poster_generate",
  "params": {
    "template_id": "vibrant",  # vibrant/business/collage
    "content": {"title": "...", "content": "...", "tag": "..."},
    "image_urls": ["https://..."],  # 可选
    "generate_fabric_json": false   # 可选
  }
}
```

**后续计划**: 方案 C 完整重构 (见 `docs/POSTER_REFACTOR_PLAN.md`)

### 4.2.2 热点数据模块

**状态**: ✅ 可用

**支持平台**:
- 百度热搜 ✅ (含旅游榜)
- 节日日历 ✅
- 小红书 ✅ (MediaCrawler 集成，需扫码登录)
- Bing 搜索 ✅
- 微博热搜 ⚠️ (需要优化)

**API 路由** (`/api/v2/hotspot/`):
- `GET /all` - 获取所有来源
- `GET /baidu` - 百度热搜 (实时 + 旅游榜)
- `GET /xiaohongshu` - 小红书热门 (需登录)
- `GET /bing` - Bing 搜索建议
- `GET /calendar` - 节日日历
- `GET /travel` - 旅游相关热点聚合
- `GET /trending` - 热门话题合并
- `POST /custom` - 添加自定义热点

**MediaCrawler 集成**:
- 位置: `libs/MediaCrawler/`
- 来源: https://github.com/NanmiCoder/MediaCrawler
- 支持: 小红书、抖音、微博、B站、快手、知乎、贴吧

**详细文档**: `docs/HOTSPOT_MODULE.md`

**参考文献管理 API** (`/api/v2/reference/`):

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/reference/list` | 获取统计信息 |
| GET | `/reference/titles` | 获取标题列表 (支持 count/random 参数) |
| GET | `/reference/titles/{index}` | 获取指定标题 |
| POST | `/reference/titles` | 添加新标题 |
| PUT | `/reference/titles/{index}` | 更新标题 |
| DELETE | `/reference/titles/{index}` | 删除标题 |
| GET | `/reference/contents` | 获取正文范文列表 |
| GET | `/reference/contents/{index}` | 获取指定范文 |
| POST | `/reference/contents` | 添加新范文 |
| PUT | `/reference/contents/{index}` | 更新范文 |
| DELETE | `/reference/contents/{index}` | 删除范文 |
| POST | `/reference/batch/add` | 批量添加 |
| POST | `/reference/reload` | 刷新缓存 |

**模式说明**：

| 模式 | 说明 | 适用场景 |
|-----|------|---------|
| none | 不使用参考 | 完全原创 |
| reference | 参考风格，原创内容 | 学习爆款风格 |
| rewrite | 保留框架，换主体 | 快速复制成功内容 |

### 4.3 Hot Topics (热点信息)

```python
hot_topics = {
    "events": [                    # 热点事件
        {
            "title": "春节档电影热映",
            "source": "微博热搜",
            "heat_score": 98,
            "related_keywords": ["春节", "亲子"],
            "expire_date": "2025-02-28"
        }
    ],
    "festivals": [                 # 节日节气
        {
            "name": "春节",
            "date": "2025-01-29",
            "marketing_angle": "团圆、年味"
        }
    ],
    "trending": [                  # 趋势话题
        {
            "topic": "#春节去哪玩",
            "platform": "小红书",
            "trend_direction": "rising"
        }
    ]
}
```

---

## 5. API 接口

### 5.1 V2 统一 API

**基础路径**: `/api/v2/aigc`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | /engines | 获取引擎列表 |
| POST | /execute | 执行引擎 |
| GET | /config/styles | 获取风格列表 |
| GET | /config/audiences | 获取人群列表 |
| GET | /config/all | 获取所有配置 |

### 5.2 执行引擎

```bash
POST /api/v2/aigc/execute
Content-Type: application/json

{
    "engine": "topic_generate",
    "params": {
        "month": "2025-02",
        "num_topics": 5,
        "subject": {...},
        "style": {"id": "gonglue", "name": "攻略风"},
        "audience": {"id": "qinzi", "name": "亲子向"},
        "hot_topics": {...}
    },
    "prompt_version": "v2.0.0"  // 可选
}
```

### 5.3 Prompt 管理 API

**基础路径**: `/api/prompt`

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | /list | 列出所有 Prompt |
| GET | /{name}/versions | 获取版本列表 |
| GET | /{name}/{version} | 获取 Prompt 详情 |
| POST | /{name}/{version}/render | 渲染 Prompt |

---

## 6. 配置文件

### 6.1 风格配置 (config/styles.yaml)

```yaml
styles:
  - id: gonglue
    name: 攻略风
    description: 实用信息为主，提供详细的游玩攻略
  - id: tuijian
    name: 极力推荐风
    description: 强烈推荐语气，突出产品优势
```

### 6.2 人群配置 (config/audiences.yaml)

```yaml
audiences:
  - id: qinzi
    name: 亲子向
    description: 家庭出游，关注儿童友好设施
  - id: zhoubianyou
    name: 周边游
    description: 短途出行，追求性价比
  - id: gaoshe
    name: 高奢酒店
    description: 高端消费，追求品质体验
```

---

## 7. 待办事项

### 7.1 Python 端

- [ ] 修复海报生成引擎依赖
- [ ] 添加节日日历数据
- [ ] 完善错误处理和日志

### 7.2 Java 端

- [ ] 新增 AIGCConfigService
- [ ] 改造 TopicGenerateServiceImpl
- [ ] 改造 ContentGenerateServiceImpl
- [ ] 更新 API 调用为 V2 接口

### 7.3 热点数据源 (规划中)

- [ ] 节日日历 (静态数据)
- [ ] 运营热点 (手动维护)
- [ ] 微博热搜 API (可选)

---

## 8. 运行服务

```bash
cd /root/TravelContentCreator
PYTHONPATH=. python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8001
```

**健康检查**：
```bash
curl http://localhost:8001/health
```

**测试选题生成**：
```bash
curl -X POST http://localhost:8001/api/v2/aigc/execute \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "topic_generate",
    "params": {
      "month": "2025-02",
      "num_topics": 2,
      "subject": {
        "id": 1,
        "name": "北京环球影城",
        "products": [{"id": 10, "name": "单日票", "price": 638}]
      },
      "style": {"id": "gonglue", "name": "攻略风"},
      "audience": {"id": "qinzi", "name": "亲子向"}
    }
  }'
```