docs: 完善 API 指南，新增架构清理文档
- AIGC_API_GUIDE.md: 添加 Prompt/参考文献/热点/配置 API - ARCHITECTURE_CLEANUP.md: 项目架构分析，模块状态，清理计划
This commit is contained in:
parent
e0fe18966b
commit
78d54a2535
@ -408,6 +408,188 @@ python scripts/test_poster_smart_v2.py
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 4. 提示词管理 (Prompt)
|
||||||
|
|
||||||
|
### 功能
|
||||||
|
管理所有 Prompt 模板，支持版本控制、变量渲染。
|
||||||
|
|
||||||
|
### API 路由: `/api/v1/prompt`
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| GET | `/list` | 列出所有 Prompt |
|
||||||
|
| GET | `/{name}/versions` | 列出版本 |
|
||||||
|
| GET | `/{name}` | 获取 Prompt 信息 |
|
||||||
|
| GET | `/{name}/preview` | 预览原始模板 |
|
||||||
|
| POST | `/render` | 渲染 Prompt |
|
||||||
|
| POST | `/style-audience` | 获取风格/人群内容 |
|
||||||
|
|
||||||
|
### 渲染 Prompt 示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
POST /api/v1/prompt/render
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "content_generate",
|
||||||
|
"version": "latest",
|
||||||
|
"context": {
|
||||||
|
"style_content": "小红书种草风",
|
||||||
|
"demand_content": "亲子家庭",
|
||||||
|
"object_content": "长隆野生动物世界"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 返回
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "content_generate",
|
||||||
|
"version": "v2.1.0",
|
||||||
|
"system_prompt": "你是一个小红书营销文案专家...",
|
||||||
|
"user_prompt": "请为以下内容生成文案...",
|
||||||
|
"model_params": {
|
||||||
|
"temperature": 0.8,
|
||||||
|
"max_tokens": 2000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 参考文献库 (Reference)
|
||||||
|
|
||||||
|
### 功能
|
||||||
|
管理标题模板和正文范文，供内容生成引擎参考。
|
||||||
|
|
||||||
|
### API 路由: `/api/v2/reference`
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| GET | `/list` | 获取统计 |
|
||||||
|
| GET | `/titles` | 获取标题列表 |
|
||||||
|
| POST | `/titles` | 添加标题 |
|
||||||
|
| PUT | `/titles/{index}` | 更新标题 |
|
||||||
|
| DELETE | `/titles/{index}` | 删除标题 |
|
||||||
|
| GET | `/contents` | 获取正文列表 |
|
||||||
|
| POST | `/contents` | 添加正文 |
|
||||||
|
| POST | `/batch/add` | 批量添加 |
|
||||||
|
| POST | `/reload` | 重载缓存 |
|
||||||
|
|
||||||
|
### 获取标题示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GET /api/v2/reference/titles?count=10&random=true
|
||||||
|
```
|
||||||
|
|
||||||
|
### 返回
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"titles": [
|
||||||
|
"广州遛娃天花板！这个地方太适合带孩子了",
|
||||||
|
"本地人私藏！XX元吃遍这条美食街"
|
||||||
|
],
|
||||||
|
"count": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 热点数据 (Hotspot)
|
||||||
|
|
||||||
|
### 功能
|
||||||
|
抓取百度、微博、小红书等平台热点，供选题参考。
|
||||||
|
|
||||||
|
### API 路由: `/api/v2/hotspot`
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| GET | `/all` | 所有来源 |
|
||||||
|
| GET | `/baidu` | 百度热搜 (实时+旅游) |
|
||||||
|
| GET | `/weibo` | 微博热搜 |
|
||||||
|
| GET | `/xiaohongshu` | 小红书热门 |
|
||||||
|
| GET | `/bing` | Bing 搜索建议 |
|
||||||
|
| GET | `/calendar` | 节日日历 |
|
||||||
|
| GET | `/travel` | 旅游相关聚合 |
|
||||||
|
| GET | `/trending` | 热门话题合并 |
|
||||||
|
| GET | `/custom` | 自定义热点 |
|
||||||
|
| POST | `/custom` | 添加自定义热点 |
|
||||||
|
|
||||||
|
### 获取百度热搜
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GET /api/v2/hotspot/baidu?limit=20
|
||||||
|
```
|
||||||
|
|
||||||
|
### 返回
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"source": "baidu",
|
||||||
|
"count": 20,
|
||||||
|
"topics": [
|
||||||
|
{
|
||||||
|
"title": "冬季旅游好去处",
|
||||||
|
"source": "baidu",
|
||||||
|
"rank": 1,
|
||||||
|
"heat": 4892341,
|
||||||
|
"category": "travel",
|
||||||
|
"url": "https://...",
|
||||||
|
"extra": {"tab": "travel"}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 配置查询
|
||||||
|
|
||||||
|
### API 路由: `/api/v2/aigc/config`
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| GET | `/config/styles` | 所有风格配置 |
|
||||||
|
| GET | `/config/audiences` | 所有人群配置 |
|
||||||
|
| GET | `/config/all` | 风格+人群 |
|
||||||
|
|
||||||
|
### 获取所有配置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GET /api/v2/aigc/config/all
|
||||||
|
```
|
||||||
|
|
||||||
|
### 返回
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"styles": [
|
||||||
|
{"id": "xiaohongshu", "name": "小红书种草", "description": "..."}
|
||||||
|
],
|
||||||
|
"audiences": [
|
||||||
|
{"id": "family", "name": "亲子家庭", "description": "..."}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 完整 API 路由表
|
||||||
|
|
||||||
|
| 前缀 | 模块 | 说明 |
|
||||||
|
|-----|------|------|
|
||||||
|
| `/api/v2/aigc` | AIGC 引擎 | 选题/内容/海报生成 |
|
||||||
|
| `/api/v2/reference` | 参考文献 | 标题/正文管理 |
|
||||||
|
| `/api/v2/hotspot` | 热点数据 | 百度/微博/小红书 |
|
||||||
|
| `/api/v1/prompt` | 提示词 | Prompt 模板管理 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 版本历史
|
## 版本历史
|
||||||
|
|
||||||
| 版本 | 日期 | 变更 |
|
| 版本 | 日期 | 变更 |
|
||||||
|
|||||||
220
docs/ARCHITECTURE_CLEANUP.md
Normal file
220
docs/ARCHITECTURE_CLEANUP.md
Normal file
@ -0,0 +1,220 @@
|
|||||||
|
# 项目架构分析与清理计划
|
||||||
|
|
||||||
|
> 更新时间: 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/*` | ✅ |
|
||||||
Loading…
x
Reference in New Issue
Block a user