# TravelContentCreator 项目总览

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

---

## 一、项目简介

TravelContentCreator 是一个 **旅游内容自动创作系统** 的 Python 后端服务，主要功能包括：

- **选题生成** - 基于热点、节日、目标人群生成小红书选题
- **内容生成** - 生成小红书风格的图文笔记正文
- **海报生成** - 自动生成配图海报
- **热点数据** - 多平台热点数据采集

### 技术栈

| 组件 | 技术 |
|-----|------|
| Web 框架 | FastAPI |
| AI 模型 | OpenAI GPT-4 |
| 模板引擎 | Jinja2 |
| 配置格式 | YAML / JSON |
| 图像处理 | Pillow |
| 爬虫 | aiohttp / MediaCrawler |

---

## 二、目录结构

```
TravelContentCreator/
├── api/                          # FastAPI 应用层
│   ├── main.py                   # 应用入口
│   ├── routers/                  # API 路由
│   │   ├── aigc.py              # V2 AIGC 统一接口
│   │   ├── hotspot.py           # 热点数据 API
│   │   ├── prompt.py            # Prompt 管理 API
│   │   └── reference.py         # 参考文献 API
│   ├── models/                   # 请求/响应模型
│   └── services/                 # 服务层 (部分已迁移)
│
├── domain/                       # 领域层 (核心业务逻辑)
│   ├── aigc/                    # AIGC 引擎
│   │   ├── engines/             # 引擎实现
│   │   │   ├── base.py          # 引擎基类
│   │   │   ├── topic_generate_v2.py
│   │   │   ├── content_generate_v2.py
│   │   │   └── poster_generate_v2.py
│   │   ├── engine_registry.py   # 引擎注册
│   │   ├── engine_executor.py   # 引擎执行器
│   │   └── shared/              # 共享组件
│   │       └── llm_client.py    # LLM 客户端
│   │
│   ├── hotspot/                 # 热点数据模块
│   │   ├── crawlers/            # 爬虫实现
│   │   │   ├── base.py          # 爬虫基类
│   │   │   ├── baidu.py         # 百度热搜
│   │   │   ├── bing.py          # Bing 搜索
│   │   │   ├── calendar.py      # 节日日历
│   │   │   ├── weibo.py         # 微博热搜
│   │   │   ├── xiaohongshu.py   # 小红书
│   │   │   └── mediacrawler/    # MediaCrawler 桥接
│   │   ├── manager.py           # 热点管理器
│   │   └── models.py            # 数据模型
│   │
│   ├── prompt/                  # Prompt 管理
│   │   ├── registry.py          # PromptRegistry
│   │   └── reference_manager.py # 参考文献管理
│   │
│   ├── poster/                  # 海报领域
│   │   ├── poster_service.py    # 海报服务
│   │   ├── poster_renderer.py   # 渲染器
│   │   ├── template_manager.py  # 模板管理
│   │   └── fabric_generator.py  # Fabric.js JSON
│   │
│   ├── content/                 # 内容领域
│   │   ├── topic_engine.py      # 选题引擎
│   │   ├── content_engine.py    # 内容引擎
│   │   └── judge_engine.py      # 评判引擎
│   │
│   └── container.py             # 依赖注入容器
│
├── prompts/                      # Prompt 模板 (YAML)
│   ├── topic_generate/          # 选题生成 Prompt
│   ├── content_generate/        # 内容生成 Prompt
│   ├── content_judge/           # 内容评判 Prompt
│   └── reference/               # 参考文献库
│       ├── titles.yaml          # 标题范例
│       └── contents.yaml        # 正文范例
│
├── poster/                       # 海报模板
│   ├── templates/               # 模板实现
│   │   ├── vibrant_template.py  # 活力风格
│   │   ├── business_template.py # 商务风格
│   │   └── collage_template.py  # 拼图风格
│   └── utils.py                 # 图像处理工具
│
├── config/                       # 配置文件
│   ├── ai_model.json            # AI 模型配置
│   ├── engines.json             # 引擎配置
│   ├── poster_gen.json          # 海报生成配置
│   └── ...
│
├── libs/                         # 外部库
│   └── MediaCrawler/            # 社交媒体爬虫
│
├── core/                         # 核心模块 (部分遗留)
├── docs/                         # 文档
└── tests/                        # 测试
```

---

## 三、核心模块

### 3.1 AIGC 引擎 (`domain/aigc/`)

统一的 AIGC 引擎框架，支持选题、内容、海报生成。

#### 引擎列表

| 引擎 | 类 | 状态 | 说明 |
|-----|-----|------|------|
| `topic_generate` | `TopicGenerateEngineV2` | ✅ | 选题生成 |
| `content_generate` | `ContentGenerateEngineV2` | ✅ | 内容生成 |
| `poster_generate` | `PosterGenerateEngineV2` | ✅ | 海报生成 |

#### 架构设计

```
EngineRegistry (引擎注册)
    ↓
EngineExecutor (引擎执行)
    ↓
BaseEngine (引擎基类)
    ├── TopicGenerateEngineV2
    ├── ContentGenerateEngineV2
    └── PosterGenerateEngineV2
```

#### API 调用

```bash
POST /api/v2/aigc/execute
{
  "engine": "topic_generate",
  "params": {
    "style_id": "travel_casual",
    "audience_id": "young_couple",
    "hot_topics": {...}
  }
}
```

---

### 3.2 热点数据模块 (`domain/hotspot/`)

多平台热点数据采集和管理。

#### 爬虫列表

| 爬虫 | 类 | 状态 | 说明 |
|-----|-----|------|------|
| 百度热搜 | `BaiduCrawler` | ✅ | 实时热点 + 旅游榜 |
| 节日日历 | `CalendarCrawler` | ✅ | 预设节日数据 |
| 小红书 | `XiaohongshuCrawler` | ✅ | MediaCrawler 集成 |
| Bing | `BingCrawler` | ✅ | 搜索建议 |
| 微博 | `WeiboCrawler` | ⚠️ | 需要优化 |

#### 架构设计

```
HotspotManager (热点管理器)
    ├── BaiduCrawler
    ├── BingCrawler
    ├── CalendarCrawler
    ├── XiaohongshuCrawler (→ XHSCrawlerBridge → MediaCrawler)
    └── WeiboCrawler
```

#### API 路由

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | `/api/v2/hotspot/all` | 获取所有来源 |
| GET | `/api/v2/hotspot/baidu` | 百度热搜 |
| GET | `/api/v2/hotspot/bing` | Bing 搜索 |
| GET | `/api/v2/hotspot/calendar` | 节日日历 |
| GET | `/api/v2/hotspot/xiaohongshu` | 小红书热门 |
| GET | `/api/v2/hotspot/travel` | 旅游相关聚合 |
| GET | `/api/v2/hotspot/trending` | 热门话题 |

---

### 3.3 Prompt 管理 (`domain/prompt/`)

YAML 格式的 Prompt 版本管理系统。

#### 核心组件

| 组件 | 说明 |
|-----|------|
| `PromptRegistry` | Prompt 加载、版本管理、模板渲染 |
| `ReferenceManager` | 参考文献库管理 (标题/正文范例) |

#### Prompt YAML 结构

```yaml
meta:
  name: topic_generate
  version: "2.0.0"
  description: "选题生成"

model:
  temperature: 0.2
  top_p: 0.3

variables:
  - name: style
    type: object
    required: true

system_prompt: |
  你是一个小红书内容策划专家...

user_prompt: |
  请根据以下信息生成选题:
  风格: {{ style.name }}
```

#### 参考文献库

位置: `prompts/reference/`

| 文件 | 说明 |
|-----|------|
| `titles.yaml` | 55+ 爆款标题模板 |
| `contents.yaml` | 10+ 完整正文范例 |
| `index.yaml` | 配置索引 |

---

### 3.4 海报模块 (`domain/poster/` + `poster/`)

自动生成配图海报。

#### 组件

| 组件 | 说明 |
|-----|------|
| `PosterServiceV2` | 轻量服务，无数据库依赖 |
| `PosterRenderer` | 渲染引擎 |
| `TemplateManager` | 模板管理 |
| `FabricGenerator` | Fabric.js JSON 输出 |

#### 模板

| 模板 | 说明 |
|-----|------|
| `vibrant` | 活力风格 |
| `business` | 商务风格 |
| `collage` | 拼图风格 |

---

### 3.5 MediaCrawler 集成 (`libs/MediaCrawler/`)

第三方社交媒体爬虫项目。

- **来源**: https://github.com/NanmiCoder/MediaCrawler
- **支持平台**: 小红书、抖音、微博、B站、快手、知乎、贴吧
- **桥接器**: `domain/hotspot/crawlers/mediacrawler/xhs_crawler.py`

---

## 四、API 概览

### V2 API (主要使用)

| 路由前缀 | 说明 |
|---------|------|
| `/api/v2/aigc` | AIGC 统一接口 |
| `/api/v2/hotspot` | 热点数据 |
| `/api/v2/reference` | 参考文献管理 |

### V1 API (部分保留)

| 路由前缀 | 状态 |
|---------|------|
| `/api/v1/prompt` | ✅ 可用 |
| `/api/v1/tweet` | ❌ 已禁用 |
| `/api/v1/poster` | ❌ 已禁用 |

---

## 五、配置文件

| 文件 | 说明 |
|-----|------|
| `config/ai_model.json` | AI 模型配置 (API Key, Model) |
| `config/engines.json` | 引擎配置 |
| `config/poster_gen.json` | 海报生成配置 |
| `config/paths.json` | 路径配置 |
| `config/database.json` | 数据库配置 (遗留) |

---

## 六、快速启动

```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务
cd /root/TravelContentCreator
PYTHONPATH=. uvicorn api.main:app --host 0.0.0.0 --port 8001

# 测试
curl http://localhost:8001/
curl http://localhost:8001/api/v2/hotspot/baidu?limit=10
```

---

## 七、文档索引

| 文档 | 说明 |
|-----|------|
| `PROJECT_OVERVIEW.md` | 项目总览 (本文档) |
| `PROJECT_STATUS.md` | 详细项目状态 |
| `HOTSPOT_MODULE.md` | 热点模块文档 |
| `NEXT_PHASE_PLAN.md` | 下阶段计划 |
| `POSTER_REFACTOR_PLAN.md` | 海报重构计划 |
| `TECHNICAL_DEBT.md` | 技术债务分析 |
| `JAVA_MIGRATION_GUIDE.md` | Java 端迁移指南 |
| `ARCHITECTURE_V2_MAINTAINABLE.md` | 架构设计 V2 |

---

## 八、技术债务 (摘要)

详见 `docs/TECHNICAL_DEBT.md`

| 问题 | 优先级 |
|-----|--------|
| 数据库双端访问 | 🔴 高 |
| ppid/sid/pid 混乱 | 🔴 高 |
| 图片 Base64 传输 | 🟡 中 |
| 临时文件堆积 (943MB) | 🟡 中 |
| 巨型文件 (poster.py 3031行) | 🟡 中 |

---

## 九、模块依赖关系

```
┌─────────────────────────────────────────────────────────────┐
│                        API Layer                            │
│  api/routers/aigc.py  hotspot.py  reference.py  prompt.py  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │   aigc   │  │  hotspot │  │  prompt  │  │  poster  │   │
│  │ engines  │  │ crawlers │  │ registry │  │ service  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Infrastructure                           │
│  prompts/  config/  libs/MediaCrawler  poster/templates    │
└─────────────────────────────────────────────────────────────┘
```

---

## 十、版本历史

| 版本 | 日期 | 说明 |
|-----|------|------|
| 2.3.0 | 2024-12-10 | 热点模块增强，MediaCrawler 集成 |
| 2.2.0 | 2024-12-09 | 海报服务重构，参考文献库 |
| 2.1.0 | 2024-12-08 | V2 AIGC API，Prompt Registry |
| 2.0.0 | 2024-12-07 | 架构重构 |