diff --git a/docs/AIGC_API_GUIDE.md b/docs/AIGC_API_GUIDE.md index 8665ca9..6811854 100644 --- a/docs/AIGC_API_GUIDE.md +++ b/docs/AIGC_API_GUIDE.md @@ -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 模板管理 | + +--- + ## 版本历史 | 版本 | 日期 | 变更 | diff --git a/docs/ARCHITECTURE_CLEANUP.md b/docs/ARCHITECTURE_CLEANUP.md new file mode 100644 index 0000000..acbc4c4 --- /dev/null +++ b/docs/ARCHITECTURE_CLEANUP.md @@ -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/*` | ✅ |