# 宇之然内容平台 - 项目升级规划

> 从"可持续生活垂直工具" → "通用内容运营全流程平台"
> Phase 1: 自用验证 → Phase 2: SaaS 产品化
> **最后更新: 2026-05-08**

---

## 一、项目定位

**目标**: 构建覆盖"选题→创作→审核→发布→搜集→反馈"全链路的内容运营工具。
**当前阶段**: 自用验证（Own Use），同时为 SaaS 产品化预留架构。

**核心原则**:
- 所有业务逻辑不写死领域/行业相关字段
- 选题系统完全配置化（评分字段/状态/标签/分类均可自定义）
- 数据库迁移到 PostgreSQL，支持后续多租户扩展

---

## 二、当前进度

### ✅ 已完成

| 模块 | 状态 | 说明 |
|------|------|------|
| **数据库迁移** | ✅ 完成 | SQLite → PostgreSQL (yzr_nr)，所有表已创建/同步 |
| **选题配置化** | ✅ 完成 | TopicField + TopicConfigField + TopicStatusConfig 模型，灵活领域/评分字段 |
| **选题 CRUD** | ✅ 完成 | 支持 field_id/status/tags 过滤，批量操作，评分计算 |
| **内容日历 API** | ✅ 完成 | 创建/更新/删除排期，按年月查询，状态管理 |
| **数据追踪 API** | ✅ 完成 | ContentMetrics 模型，仪表盘/趋势/多平台汇总 |
| **素材库 API** | ✅ 完成 | 上传/管理/标签/搜索，usage_count 统计 |
| **创作任务 API** | ✅ 完成 | ContentTask 异步任务，状态/进度/结果管理 |
| **平台配置 API** | ✅ 完成 | 知乎/微信/小红书 平台配置，含合规规则 |
| **初始化数据** | ✅ 完成 | 默认领域(10个)、状态(5种)、平台(3个)、管理员 |
| **服务器运行** | ✅ 运行中 | http://localhost:8001 |

### ⚠️ 待前端适配

以下新 API 已完成后端，但前端页面尚未适配：

| 模块 | API | 前端文件 |
|------|-----|---------|
| 选题配置 | /api/topic-config/* | topics.html 需改版 |
| 内容日历 | /api/calendar/* | 需新建 calendar.html |
| 数据分析 | /api/metrics/* | 需新建 metrics.html |
| 素材库 | /api/assets/* | 需新建 assets.html |
| 创作任务 | /api/tasks/* | 需新建 tasks.html |
| 平台配置 | /api/platform-config/* | 需新建 platforms.html |

### ⏳ 未实现功能

| 优先级 | 模块 | 功能点 | 说明 |
|--------|------|--------|------|
| P0 | **内容日历前端** | 日历视图、拖拽排期、提醒设置 | API 已就绪，需前端 |
| P0 | **数据看板前端** | 趋势图、平台对比、选题推荐 | API 已就绪，需前端 |
| P0 | **素材库前端** | 图片上传/管理/预览 | API 已就绪，需前端 |
| P0 | **创作任务前端** | 实时进度条、任务列表、取消 | API 已就绪，需前端 |
| P1 | **多平台适配** | 一篇长文 → 知乎/小红书/微信各格式 | 核心差异化功能 |
| P1 | **热点采集** | 跨平台热搜、趋势追踪 | 有 collector 脚本待集成 |
| P1 | **选题推荐** | 基于历史数据推荐选题 | API 已就绪 (recommend-topics) |
| P2 | **内容复用** | 长文 → 短笔记 → 回答 → 朋友圈文案 | 自动化脚本 |
| P2 | **通知系统** | 企业微信/飞书推送 | 有 wecom_notifier.py 待集成 |
| P2 | **定时任务** | APScheduler 自动执行流水线 | core/scheduler.py 已有 |
| P3 | **多租户** | 租户隔离、团队协作 | SaaS 预留 |
| P3 | **支付订阅** | 免费/专业版分级、用量统计 | SaaS 预留 |

---

## 三、技术架构

### 3.1 技术栈

| 层次 | 技术 | 说明 |
|------|------|------|
| 后端 | FastAPI 0.104+ | ASGI 异步框架 |
| ORM | SQLAlchemy 2.0+ | PostgreSQL + psycopg2 |
| 前端 | Vue 3 (CDN) + Element Plus | SPA 单页应用 |
| 数据库 | PostgreSQL 15 | 自用阶段单租户，SaaS 预留多租户 |
| 认证 | JWT (python-jose) + bcrypt | Bearer Token |
| 定时 | APScheduler | 内容日历/定时任务 |

### 3.2 数据库连接

```
环境变量:
  USE_POSTGRES=true
  PG_HOST=127.0.0.1
  PG_PORT=5432
  PG_DATABASE=yzr_nr
  PG_USER=yzr_nr
  PG_PASSWORD=aTX3WKKnPfRnM5PC
```

### 3.3 项目结构（后端）

```
platform/backend/app/
├── api/                    # REST API 路由
│   ├── auth.py            # 认证
│   ├── topics.py          # 选题 CRUD [重构]
│   ├── articles.py        # 文章管理
│   ├── publishing.py      # 发布记录
│   ├── calendar.py        # 内容日历 [NEW]
│   ├── metrics.py         # 数据分析 [NEW]
│   ├── assets.py          # 素材库 [NEW]
│   ├── tasks.py           # 创作任务 [NEW]
│   ├── platform_config.py  # 平台配置 [NEW]
│   ├── topic_config.py    # 选题配置 [NEW]
│   └── admin/             # 管理后台
├── core/                  # 业务逻辑
├── models.py              # SQLAlchemy 模型 [重构]
├── schemas.py             # Pydantic 验证 [重构]
├── database.py            # 数据库连接 [重构]
├── initial_data.py        # 初始化数据 [重构]
└── main.py                # FastAPI 入口 [更新]

platform/frontend/
├── index.html             # 主仪表盘
├── topics.html            # 选题管理
├── calendar.html          # 内容日历 [待建]
├── metrics.html           # 数据分析 [待建]
├── assets.html            # 素材库 [待建]
├── login.html
├── admin.html
└── ...
```

---

## 四、数据模型

### 4.1 选题系统（配置化）

```
TopicField（领域/分类）
  id, name, icon, color, description, parent_id, sort_order, is_active

TopicConfigField（选题评分字段配置）
  id, field_id → TopicField, name, key, field_type, weight, options, min/max, is_required, sort_order

TopicStatusConfig（状态配置）
  id, status, label, color, icon, sort_order, is_default

Topic（选题，主表）
  id, field_id → TopicField, field_name, title, status, priority_score, total_score,
  format, core_concept, audience_pain, unique_angle, priority,
  tags(JSON), custom_data(JSON), scoring_data(JSON),
  cases(JSON), source_file, lock_by, lock_at,
  created_at, updated_at, generated_at, ready_at, published_at,
  compliance_score, platform_urls(JSON)
```

### 4.2 新增模型

| 模型 | 用途 |
|------|------|
| ContentCalendar | 内容日历/排期管理 |
| ContentMetrics | 文章数据追踪（阅读/点赞/评论等） |
| MediaAsset | 素材库（图片/视频/文档） |
| PlatformConfig | 平台配置（知乎/微信/小红书格式规则） |
| ContentTask | 创作任务（异步流水线状态） |

---

## 五、API 清单

### 选题配置

```
GET    /api/topic-config/fields
POST   /api/topic-config/fields
PUT    /api/topic-config/fields/{field_id}
DELETE /api/topic-config/fields/{field_id}
GET    /api/topic-config/fields/{field_id}/scoring
POST   /api/topic-config/fields/{field_id}/scoring
PUT    /api/topic-config/scoring/{config_id}
DELETE /api/topic-config/scoring/{config_id}
POST   /api/topic-config/fields/{field_id}/scoring/batch
```

### 选题

```
GET    /api/topics?field_id=&status=&tag=&search=&limit=&offset=
POST   /api/topics
GET    /api/topics/stats
GET    /api/topics/{topic_id}
PUT    /api/topics/{topic_id}
DELETE /api/topics/{topic_id}
POST   /api/topics/{topic_id}/score
POST   /api/topics/{topic_id}/publish
POST   /api/topics/{topic_id}/lock
POST   /api/topics/{topic_id}/unlock
GET    /api/topics/{topic_id}/articles
GET    /api/topics/{topic_id}/metrics
POST   /api/topics/batch-update-status
GET    /api/topics/field-distribution
```

### 内容日历

```
GET    /api/calendar?year=&month=
GET    /api/calendar/entries?start_date=&end_date=&status=&platform=
POST   /api/calendar/entries
PUT    /api/calendar/entries/{entry_id}
DELETE /api/calendar/entries/{entry_id}
POST   /api/calendar/entries/bind-topic
POST   /api/calendar/entries/from-topic?topic_id=&platform=
GET    /api/calendar/stats?year=&month=
```

### 数据分析

```
GET    /api/metrics/dashboard?days=
GET    /api/metrics/trend?days=&group_by=
GET    /api/metrics/entries?topic_id=&platform=
POST   /api/metrics/entries
PUT    /api/metrics/entries/{metric_id}
DELETE /api/metrics/entries/{metric_id}
GET    /api/metrics/topics/{topic_id}
GET    /api/metrics/by-platform
GET    /api/metrics/recommend-topics?limit=
```

### 素材库

```
GET    /api/assets?file_type=&tag=&topic_id=&search=&limit=&offset=
GET    /api/assets/tags
GET    /api/assets/counts
POST   /api/assets/upload
PUT    /api/assets/{asset_id}
DELETE /api/assets/{asset_id}
POST   /api/assets/{asset_id}/use
```

### 创作任务

```
GET    /api/tasks?status=&topic_id=&stage=&limit=
GET    /api/tasks/active
POST   /api/tasks
GET    /api/tasks/{task_id}
PUT    /api/tasks/{task_id}/start
PUT    /api/tasks/{task_id}/progress
PUT    /api/tasks/{task_id}/complete
PUT    /api/tasks/{task_id}/fail
DELETE /api/tasks/{task_id}
POST   /api/tasks/run-creator
```

### 平台配置

```
GET    /api/platform-config?active_only=
POST   /api/platform-config
GET    /api/platform-config/{platform}
PUT    /api/platform-config/{platform}
DELETE /api/platform-config/{platform}
```

---

## 六、实施计划

### Phase 1（当前）：自用验证

**目标**: 2个月内完成全链路闭环，自己稳定产出10-20篇文章

**已完成**:
- ✅ 数据库迁移 PostgreSQL
- ✅ 选题系统配置化
- ✅ 所有新模型 + API 后端完成
- ✅ 服务运行中

**进行中**:
- ⏳ 前端适配（新页面）

**待开发**:
- 前端: 内容日历/数据分析/素材库/创作任务 页面
- 前端: 选题管理改版（适配配置化）
- 集成: 热点采集脚本 → API
- 集成: 企微通知 → API
- 集成: 多平台格式适配

### Phase 2：SaaS 产品化（待定）

---

## 七、启动方式

```bash
cd /root/openclaw-workspace/projects/yu-zhi-ran/platform/backend

# 环境变量（.env 已配置）
USE_POSTGRES=true PG_HOST=127.0.0.1 PG_PORT=5432 \
PG_DATABASE=yzr_nr PG_USER=yzr_nr PG_PASSWORD=aTX3WKKnPfRnM5PC \
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

# 默认管理员: admin / admin123
# API 文档: http://localhost:8001/docs
```

---

## 八、数据库当前状态

```
领域: 10 个（未来工作方式、AI与效率、可持续生活、数字游民、个人成长、科技人文、个人知识工厂、科技人文交叉、可持续生活系统、测试）
选题: 26 个
状态分布: 待处理20 / 待审查2 / 待发布3 / 已发布1
平台: 3 个（知乎/微信公众号/小红书）
```

---

*文档版本: v0.2*
*更新时间: 2026-05-08*