TravelContentCreator/docs/ARCHITECTURE_CLEANUP.md

# 项目架构分析与清理计划

> 更新时间: 2024-12-10

## 目录结构概览

```
TravelContentCreator/
├── api/                 # ✅ 活跃 - FastAPI 路由
├── domain/              # ✅ 活跃 - 核心业务逻辑
├── poster_v2/           # ✅ 活跃 - 新海报系统
├── prompts/             # ✅ 活跃 - Prompt 模板
├── core/                # ⚠️ 部分失效 - 旧核心模块
├── poster/              # ⚠️ 部分失效 - 旧海报系统
├── _archived/           # 🗃️ 已归档 - 废弃代码
├── libs/                # ✅ 第三方 - MediaCrawler
├── assets/              # ✅ 资源 - 字体/图片
├── result/              # 📁 输出 - 测试结果
├── scripts/             # ✅ 脚本 - 测试脚本
├── docs/                # ✅ 文档
└── data/                # 📁 数据 - 临时文件
```

---

## 模块状态

### ✅ 活跃模块 (正在使用)

| 模块 | 路径 | 说明 |
|-----|------|------|
| **API 路由** | `api/routers/` | aigc, prompt, reference, hotspot |
| **AIGC 引擎** | `domain/aigc/engines/` | topic_generate, content_generate, poster_smart_v2 |
| **Prompt 管理** | `domain/prompt/` | PromptRegistry, ReferenceManager |
| **热点爬虫** | `domain/hotspot/` | 百度、Bing、日历、小红书 |
| **海报 V2** | `poster_v2/` | 5 种布局，Fabric JSON 输出 |
| **AI Agent** | `core/ai/` | AIAgent, AIModelConfig |
| **配置** | `core/config_loader.py` | 统一配置加载 |

### ⚠️ 部分失效模块 (需评估)

| 模块 | 路径 | 状态 | 建议 |
|-----|------|------|------|
| `core/content_service.py` | 旧内容服务 | 已被 V2 引擎取代 | 可删除 |
| `core/integration_service.py` | 旧集成服务 | 依赖数据库 | 可删除 |
| `core/media_manager.py` | 媒体管理 | 部分使用 | 保留 |
| `core/models.py` | 数据模型 | 部分使用 | 评估 |
| `core/cookie_manager.py` | Cookie | 未使用 | 可删除 |
| `core/document_adapter.py` | 文档适配 | 未使用 | 可删除 |
| `core/xhs_adapter.py` | 小红书适配 | 未使用 | 可删除 |
| `poster/` | 旧海报系统 | 已被 poster_v2 取代 | 可删除 |

### 🗃️ 已归档模块 (_archived/)

| 模块 | 说明 | 建议 |
|-----|------|------|
| `database_service.py` | 数据库服务 | 已不再使用 |
| `integration.py` | 旧集成 | 已不再使用 |
| `tweet.py` | 推文生成 | 已不再使用 |
| `xhs_spider/` | 旧爬虫 | 已被 MediaCrawler 取代 |

---

## API 路由状态

### ✅ 活跃路由

```python
# api/main.py
app.include_router(aigc.router, prefix="/api/v2")      # AIGC 引擎
app.include_router(reference.router, prefix="/api/v2") # 参考文献
app.include_router(hotspot.router, prefix="/api/v2")   # 热点数据
app.include_router(prompt.router, prefix="/api/v1")    # Prompt 管理
```

### ❌ 已禁用路由

```python
# 以下路由依赖已删除的模块，已在 main.py 中注释
# app.include_router(tweet.router)
# app.include_router(poster.router)
# app.include_router(document.router)
# app.include_router(data.router)
# app.include_router(integration.router)
# app.include_router(content_integration.router)
```

---

## 引擎状态

### ✅ 可用引擎

| 引擎 ID | 类 | 版本 | 状态 |
|--------|-----|------|------|
| `topic_generate` | TopicGenerateEngineV2 | 2.0.0 | ✅ |
| `content_generate` | ContentGenerateEngineV2 | 2.1.0 | ✅ |
| `poster_smart_v2` | PosterSmartEngineV2 | 2.0.0 | ✅ |

### ⚠️ 旧引擎 (可清理)

| 引擎 | 文件 | 说明 |
|-----|------|------|
| `poster_generate` | `poster_generate_v2.py` | 旧海报，依赖 poster/ |
| `poster_generate_v3` | `poster_generate_v3.py` | 中间版本 |
| `poster_smart_v1` | `poster_smart_v1.py` | poster_smart_v2 前身 |

---

## 存储占用

| 目录 | 大小 | 说明 |
|-----|------|------|
| `assets/` | 215MB | 字体、图片资源 |
| `libs/` | 39MB | MediaCrawler |
| `result/` | 22MB | 测试输出，可清理 |
| `data/` | 8.1MB | 临时数据 |
| `static/` | 4.1MB | 静态文件 |
| `tests/` | 3.8MB | 测试文件 |

---

## 清理计划

### Phase 1: 立即可删除

```bash
# 旧海报系统 (已被 poster_v2 取代)
rm -rf poster/

# 旧核心模块 (未使用)
rm core/content_service.py
rm core/integration_service.py
rm core/cookie_manager.py
rm core/document_adapter.py
rm core/xhs_adapter.py

# 清理测试输出
rm -rf result/poster_smart_test/
rm -rf result/poster_v2_test/
```

### Phase 2: 评估后删除

```bash
# 评估 core/models.py 是否仍被引用
grep -r "from core.models" --include="*.py"
grep -r "from core import models" --include="*.py"

# 评估旧引擎是否仍被调用
grep -r "poster_generate_v2" --include="*.py"
grep -r "poster_smart_v1" --include="*.py"
```

### Phase 3: 归档目录清理

```bash
# _archived 已是归档目录，可保留或完全删除
# 如果确认不需要，可以删除
rm -rf _archived/
```

---

## 依赖关系图

```
┌─────────────────────────────────────────────────────────────┐
│                         API Layer                            │
│  api/routers/aigc.py → EngineExecutor → Engines             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Engine Layer                           │
│                                                             │
│  topic_generate_v2 ─────┐                                   │
│  content_generate_v2 ───┼──→ PromptRegistry                 │
│  poster_smart_v2 ───────┘         │                         │
│         │                         ▼                         │
│         │              domain/prompt/                       │
│         │                   │                               │
│         ▼                   ▼                               │
│    poster_v2/         ReferenceManager                      │
│    (5 layouts)        (titles.yaml, contents.yaml)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Core Layer                              │
│                                                             │
│  core/ai/ai_agent.py ───→ OpenAI API                        │
│  core/config_loader.py ─→ config/app_config.yaml            │
└─────────────────────────────────────────────────────────────┘
```

---

## 推荐清理顺序

1. **备份** - `git tag v2.0-pre-cleanup`
2. **删除 poster/** - 旧海报系统
3. **清理 core/** - 未使用的服务
4. **删除旧引擎** - poster_generate_v2, v3, poster_smart_v1
5. **清理 result/** - 测试输出
6. **评估 _archived/** - 确认后删除

---

## 当前可用功能总结

| 功能 | 入口 | 状态 |
|-----|------|------|
| 选题生成 | `POST /api/v2/aigc/execute` | ✅ |
| 内容生成 | `POST /api/v2/aigc/execute` | ✅ |
| 海报生成 | `POST /api/v2/aigc/execute` | ✅ |
| Prompt 管理 | `/api/v1/prompt/*` | ✅ |
| 参考文献 | `/api/v2/reference/*` | ✅ |
| 热点数据 | `/api/v2/hotspot/*` | ✅ |
| 配置查询 | `/api/v2/aigc/config/*` | ✅ |