yu-zhi-ran/platform/PORTFOLIO.md

# 宇之然内容创作平台 - 系统架构与部署指南

## 系统组成

整个项目由两个核心部分组成：

| 组件 | 位置 | 职责 | 状态 |
|------|------|------|------|
| **内容流水线** | `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