Initial commit: yu-zhi-ran platform with automation integration

2026-04-19 14:05:09 +08:00
commit 3cb2df51c8
209 changed files with 80379 additions and 0 deletions
@@ -0,0 +1,297 @@
+# 宇之然内容创作平台 - 系统架构与部署指南
+
+## 系统组成
+
+整个项目由两个核心部分组成：
+
+| 组件 | 位置 | 职责 | 状态 |
+|------|------|------|------|
+| **内容流水线** | `automation/scripts/` | 选-写-优-发 全自动化脚本 | 已实现 |
+| **管理平台** | `platform/` | Web管理界面 + API + 数据同步 | 新开发 |
+| **数据存储** | `automation/data/` | JSON 选题库 + 发布包 | 共享 |
+
+### 1. 内容流水线（模块化）
+
+```
+collector.py    → 收集热点 → automation/data/sustainability_topics.json
+creator.py      → 创作内容 → automation/data/drafts/YYYY-MM-DD/
+optimizer.py    → 合规优化 → 生成 optimization_report.json
+publisher.py    → 发布包生成 → automation/data/releases/ + content/published/
+```
+
+**特点**：
+- 独立可运行，每个脚本都有 CLI 参数
+- 数据文件基于日期组织
+- 日志写入 `automation/logs/`
+
+### 2. 管理平台（Web UI）
+
+```
+backend/
+├── app/
+│   ├── main.py                # FastAPI 入口
+│   ├── database.py            # SQLite 连接
+│   ├── models.py              # Topic, Article 模型
+│   ├── schemas.py             # Pydantic 验证
+│   ├── api/
+│   │   ├── system.py          # 系统状态、流水线触发、日志查看
+│   │   ├── topics.py          # 选题 CRUD + 发布标记
+│   │   ├── articles.py        # 文章管理
+│   │   └── publisher.py       # 发布包生成与查看
+│   └── core/
+│       ├── generator.py       # 调用 creator.py
+│       ├── optimizer.py       # 调用 compliance_optimizer.py
+│       └── sync.py            # JSON↔DB 同步
+frontend/
+└── index.html                 # Vue 3 + Element Plus SPA
+```
+
+**特点**：
+- 前端无构建，CDN依赖（Tailwind + Vue + Element Plus）
+- 数据通过 REST API 与后端交互
+- 实时显示流水线状态
+
+## 部署方式：直接目录运行（不用 Docker）
+
+### 前置条件
+
+- Python 3.10+
+- `pip install -r platform/backend/requirements.txt`
+- 确保自动化脚本可运行（`scripts/` 及其依赖已就绪）
+
+### 启动步骤
+
+```bash
+# 1. 进入 platform 目录
+cd /root/.openclaw/workspaces/yzr-yxl/projects/yu-zhi-ran/platform
+
+# 2. （首次）创建数据目录
+mkdir -p data logs
+
+# 3. 启动服务器
+./run.sh 8001
+
+# 或手动：
+cd backend
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
+```
+
+### 访问
+
+- 前端界面：http://localhost:8000/
+- API 文档： http://localhost:8000/docs
+- 健康检查： http://localhost:8000/api/system/status
+
+## 系统架构与数据流
+
+```
+                    ┌─────────────────────────────────────┐
+                    │         Frontend (Vue 3)           │
+                    │  仪表盘 | 选题列表 | 预览 | 发布   │
+                    └─────────────────┬───────────────────┘
+                                      │ HTTP API (JSON)
+                    ┌─────────────────▼───────────────────┐
+                    │      FastAPI (backend/app)          │
+                    │  system | topics | publisher | api │
+                    └─────────────────┬───────────────────┘
+                                      │
+                ┌─────────────────────┼─────────────────────┐
+                │                     │                     │
+         ┌──────▼──────┐      ┌──────▼──────┐      ┌──────▼──────┐
+         │   core/     │      │   core/     │      │   core/     │
+         │ generator   │      │ optimizer   │      │   sync      │
+         └──────┬──────┘      └──────┬──────┘      └──────┬──────┘
+                │                     │                     │
+                └─────────────────────┼─────────────────────┘
+                                      │ subprocess (CLI)
+                    ┌─────────────────▼───────────────────┐
+                    │   automation/scripts/*.py           │
+                    │   collector creator optimizer      │
+                    │   publisher (生成发布包)            │
+                    └─────────────────┬───────────────────┘
+                                      │ 读写
+                    ┌─────────────────▼───────────────────┐
+                    │   automation/data/                  │
+                    │   sustainability_topics.json       │
+                    │   drafts/ releases/                │
+                    └─────────────────────────────────────┘
+```
+
+### 关键集成点
+
+1. **触发创作** → `POST /api/system/generate/run`
+   - FastAPI 调用 `generator.py → subprocess creator.py`
+   - 成功后调用 `sync_all_topics()` 同步选题状态到数据库
+
+2. **触发优化** → `POST /api/system/optimize/run`
+   - `optimizer.py → subprocess compliance_optimizer.py`
+   - 读取报告并更新数据库
+
+3. **生成发布包** → `POST /api/publisher/generate/{topic_id}`
+   - `publisher.py → subprocess publisher.py --topic-id {id}`
+   - 发布包存到 `content/published/` 和 `automation/data/releases/`
+
+4. **查看发布包** → `GET /api/publisher/package/{topic_id}/{platform}`
+   - 返回 HTML 内容供前端 iframe 预览或复制
+
+5. **流水线状态** → `GET /api/system/pipeline/status`
+   - 检查日志文件最后修改时间和错误关键词
+   - 返回各模块健康状态
+
+## 目录结构对比：原 vs 新
+
+### 原（纯脚本）
+
+```
+yu-zhi-ran/
+├── automation/          # 流水线
+├── scripts/            # 同 automation/scripts（软链？）
+├── content/            # 已发布内容
+└── 手动操作（打开终端运行脚本）
+```
+
+### 新（管理平台 + 流水线）
+
+```
+yu-zhi-ran/
+├── platform/          # 新增：Web管理平台
+│   ├── backend/
+│   │   ├── app/
+│   │   │   ├── main.py
+│   │   │   ├── api/
+│   │   │   └── core/
+│   │   └── requirements.txt
+│   ├── frontend/
+│   │   └── index.html
+│   └── run.sh         # 启动脚本
+├── automation/        # 流水线（不变）
+├── scripts/          # 流水线脚本（不变）
+└── (其他目录 unchanged)
+```
+
+**关系**：platform 读取 automation/data/ 的数据并调用 scripts/ 执行，不修改原有脚本。
+
+## 功能清单
+
+| 功能 | 实现状态 | API端点 | 前端位置 |
+|------|---------|---------|---------|
+| 系统概览 | ✅ | `GET /api/system/status` | 仪表盘统计卡片 |
+| 选题列表 | ✅ | `GET /api/topics?status=` | 选题管理表格 |
+| 选题详情 | ✅ | `GET /api/topics/{id}` | 预览对话框 |
+| 触发创作 | ✅ | `POST /api/system/generate/run` | "运行创作任务"按钮 |
+| 触发优化 | ✅ | `POST /api/system/optimize/run` | "运行合规优化"按钮 |
+| 生成发布包 | ✅ | `POST /api/publisher/generate/{id}` | 发布Tab → "重新生成" |
+| 发布包预览 | ✅ | `GET /api/publisher/package/{id}/{platform}` | 发布Tab → "查看" |
+| 发布包复制 | ✅ | (同上) | 发布Tab → "复制HTML" |
+| 标记已发布 | ✅ | `POST /api/topics/{id}/publish` | 发布Tab → "确认发布" |
+| 流水线状态 | ✅ | `GET /api/system/pipeline/status` | 流水线状态面板 |
+| 同步数据 | ✅ | `POST /api/sync/run` | 全量刷新按钮 |
+| 日志查看 | ✅ | `GET /api/system/logs/{date}?log_type=` | 日志对话框 |
+
+## 数据同步说明
+
+**源**：`automation/data/sustainability_topics.json`（自动化脚本写入）
+
+**目标**：`platform/backend/data/yzr.db` (SQLite)
+
+**同步策略**：
+- **实时同步**：每次创作/优化任务完成后自动调用 `sync_all_topics()`
+- **手动同步**：前端 "全量刷新" 按钮 → `POST /api/system/refresh`
+- **定时同步**：可在 platform 启动时预先执行一次
+
+**字段映射**：
+
+| JSON 字段 | Topic 模型字段 |
+|-----------|----------------|
+| `id` | `id` |
+| `title` | `title` |
+| `field` | `field` |
+| `status` | `status` |
+| `priority_score` | `priority_score` |
+| `compliance_score` | `compliance_score` |
+| `ready_at` | `ready_at` (date) |
+| `published_at` | `published_at` (date) |
+| `platform_urls` | `platform_urls` (JSON) |
+
+**状态对应**：
+- 自动化脚本使用中文状态：`"待处理"`, `"待发布"`, `"已发布"` 等
+- 平台数据库保持中文状态（前端也显示中文）
+
+## 扩展性
+
+### 添加新平台
+
+1. 在 `automation/scripts/publisher.py` 的 `PLATFORMS` 添加配置
+2. 在 `platform/backend/app/api/publisher.py` 的 `list_platform_packages()` 添加平台路径
+3. 在前端 "发布管理" 对话框添加新平台的输入框
+
+### 定时任务
+
+使用 crontab 定时运行自动化脚本：
+
+```bash
+# 每天 5:00 收集选题
+0 5 * * * cd /path/to/yu-zhi-ran && python automation/scripts/collector.py
+
+# 每天 9:00 生成内容（如果待处理选题充足）
+0 9 * * * cd /path/to/yu-zhi-ran && python automation/scripts/creator.py
+
+# 每天 14:00 合规优化（可选）
+0 14 * * * cd /path/to/yu-zhi-ran && python automation/scripts/optimizer.py
+
+# 每周一 10:00 发布（手动发布包生成）
+0 10 * * 1 cd /path/to/yu-zhi-ran && python automation/scripts/publisher.py
+```
+
+## 开发调试
+
+### 日志查看
+
+```bash
+# 实时 tail 日志
+tail -f automation/logs/creator_$(date +%Y-%m-%d).log
+tail -f automation/logs/optimizer_$(date +%Y-%m-%d).log
+tail -f automation/logs/publisher_$(date +%Y-%m-%d).log
+```
+
+### API 调试
+
+访问 http://localhost:8000/docs 使用 Swagger UI 测试所有端点。
+
+### 前端调试
+
+浏览器 DevTools → Network 查看 API 请求。
+
+## 故障排查
+
+| 问题 | 可能原因 | 解决方案 |
+|------|---------|----------|
+| 前端显示无数据 | 数据库未同步 | 点击"全量刷新"或访问 `/api/system/sync/run` |
+| 创作按钮灰色 | 无可用选题 | 检查 `automation/data/sustainability_topics.json` 是否有 `status: "待处理"` |
+| 生成发布包失败 | HTML不存在 | 检查 `automation/data/releases/YYYY-MM-DD/` 是否存在对应HTML |
+| 端口占用 | 已有服务运行 | 停止旧的 uvicorn 进程或改端口 |
+| 依赖缺失 | pip install 未完成 | 运行 `pip install -r platform/backend/requirements.txt` |
+
+## 后续优化建议
+
+1. **数据库初始化**: 添加自动创建表 + 初始数据脚本
+2. **权限控制**: 添加简单登录（当前无认证，仅本地访问）
+3. **任务队列**: 耗时的流水线步骤改为异步（BackgroundTasks + 状态轮询）
+4. **配置管理**: 将平台配置（PLATFORMS 的 enabled 状态）移到数据库
+5. **备份策略**: 定期备份 `automation/data/` 和 `platform/data/`
+6. **Docker 重构** (可选): 如需容器化，可分别构建 backend 和 nginx 镜像
+
+## 总结
+
+- ✅ **无 Docker**：直接 `./run.sh` 启动，依赖 `requirements.txt`
+- ✅ **双系统集成**：管理平台（Web UI）调用自动化流水线（CLI脚本）
+- ✅ **数据同步**：JSON ↔ SQLite 自动/手动同步
+- ✅ **状态监控**：流水线各模块健康状态面板
+- ✅ **一键操作**：创作、优化、生成发布包全部通过 Web 界面触发
+
+系统已准备好用于日常内容生产管理。
+
+---
+
+**维护者**: AI 助手小然
+**最后更新**: 2026-04-19