yu-zhi-ran/PROJECT_STRUCTURE.md

# 宇之然项目目录结构说明

## 整体布局

```
yu-zhi-ran/                          # 项目根目录
├── platform/                       # ⭐ 管理平台（Web UI + API）
│   ├── backend/                    #   FastAPI 后端
│   │   ├── app/
│   │   │   ├── main.py            #   入口
│   │   │   ├── database.py        #   数据库连接（SQLite）
│   │   │   ├── models.py          #   Topic, Article 模型
│   │   │   ├── schemas.py         #   Pydantic 验证
│   │   │   ├── initial_data.py    #   初始数据导入
│   │   │   ├── api/               #   REST API 路由
│   │   │   │   ├── system.py      #   │ 系统状态、流水线控制、日志
│   │   │   │   ├── topics.py      #   │ 选题 CRUD
│   │   │   │   ├── publisher.py   #   │ 发布包管理
│   │   │   │   └── articles.py    #   │ 文章查看
│   │   │   └── core/              #   │ 业务逻辑封装
│   │   │       ├── generator.py   #   │  调用 scripts/creator.py
│   │   │       ├── optimizer.py  #   │  调用 scripts/compliance_optimizer.py
│   │   │       └── sync.py        #   │  同步 JSON → 数据库
│   │   └── requirements.txt
│   ├── frontend/
│   │   └── index.html             #   Vue 3 SPA（CDN 依赖）
│   ├── run.sh                      #   快速启动脚本
│   ├── check.py                    #   部署前检查
│   ├── README.md                   #   平台使用文档
│   └── PORTFOLIO.md                #   架构详解
│
├── automation/                     # 🔄 自动化流水线数据与日志
│   ├── scripts/ (软链) → ../scripts/   #   实际脚本在 ../scripts/
│   ├── data/                       #   数据存储
│   │   ├── sustainability_topics.json   #   ⭐ 核心：选题库
│   │   ├── drafts/                       #   草稿（按日期）
│   │   │   └── 2026-04-19/
│   │   │       ├── A02_zhihu.md
│   │   │       ├── A02_wechat.md
│   │   │       └── A02_xiaohongshu.md
│   │   └── releases/                     #   发布包（按日期）
│   │       └── 2026-04-19/
│   │           ├── zhihu/zhihu_A02_zhihu.html
│   │           ├── wechat/wechat_A02_wechat.html
│   │           └── xiaohongshu/
│   └── logs/                       #   运行日志
│       ├── collector_2026-04-19.log
│       ├── creator_2026-04-19.log
│       ├── optimizer_2026-04-19.log
│       └── publisher_summary_2026-04-19.json
│
├── scripts/                        # 🛠️ 底层 CLI 脚本（被 automation/scripts/ 调用）
│   ├── collector.py                #   采集热点 + 本地降级
│   ├── creator.py                  #   研究→大纲→撰写流水线
│   ├── compliance_optimizer.py     #   合规检查 + 自动修复
│   ├── publisher.py                #   发布包生成（HTML + 指南）
│   ├── research.py                 #   资料收集（API + 本地）
│   ├── outline.py                  #   大纲生成
│   ├── writer.py                   #   核心撰写逻辑
│   ├── wecom_notifier.py          #   企业微信通知（可选）
│   └── ...（其他辅助脚本）
│
├── content/                        # 📚 已发布内容存储
│   ├── published/                  #   按 topic_id 组织
│   │   ├── A01/
│   │   │   └── 手动发布/
│   │   │       ├── 知乎/文章.html
│   │   │       └── 小红书/文章.html
│   │   └── A02/
│   ├── drafts/                    #   草稿（可选）
│   ├── ideas/                     #   选题记录（Markdown）
│   └── images/                    #   配图资源
│
├── config/                         # ⚙️ 配置文件
│   ├── sources.yaml               #   RSS/网页源配置
│   └── wecom_config.yaml          #   企业微信机器人配置
│
├── brand/                          # 🏷️ 品牌资产
│   ├── brand-book.md              #   愿景、调性、原则
│   └── guidelines.md              #   内容创作指南
│
├── strategy/                       # 📈 内容策略
│   └── 全球-本土比较研究与全新内容战略规划-2026-04-15.md
│
├── tasks/                          # 📋 项目管理
│   └── todo.md
│
├── research/                       # 📊 行业研究
│   └── trends-2026.md
│
├── logs/                          # 📝 根目录日志（兼容）
├── backup/                        # 💾 备份归档
├── README.md                      #   项目总览
├── YUZHIRAN_PLATFORM.md           #   完整文档（本文件同级）
├── TEST_FULL_PIPELINE.md          #   测试指南
├── test_full_pipeline.py          #   全流程测试脚本
├── run_publisher.sh               #   快速发布脚本
└── start-platform.sh              #   启动管理平台（新增）

# 软链接
automation/scripts → ../scripts/
```

---

## 🔗 关键依赖关系

### platform/backend/app/core/*.py 的路径计算

| 文件 | parents 层数 | PROJECT_ROOT 指向 |
|------|-------------|-------------------|
| `database.py` | `parents[3]` | `yu-zhi-ran/` |
| `initial_data.py` | `parents[3]` | `yu-zhi-ran/` |
| `generator.py` | `parents[4]` | `yu-zhi-ran/` |
| `optimizer.py` | `parents[4]` | `yu-zhi-ran/` |
| `sync.py` | `parents[4]` | `yu-zhi-ran/` |
| `api/system.py` | `parents[4]` | `yu-zhi-ran/` |
| `api/publisher.py` | `parents[4]` | `yu-zhi-ran/` |

**规律**：
- 在 `app/` 一级：`parents[3]` → `yu-zhi-ran/`
- 在 `app/api/` 或 `app/core/`：`parents[4]` → `yu-zhi-ran/`

✅ 所有路径已统一修正，可正常工作。

---

## 🚀 工作流程

### 自动流水线（cron）

```
每天 05:00  →  collector.py  → automation/data/sustainability_topics.json（新增选题）
每天 05:30  →  creator.py    → automation/data/drafts/ + HTML 发布包
每天 05:45  →  compliance_optimizer.py → 自动合规检查
每天 06:00  →  publisher.py  → content/published/（手动发布包）
```

### Web 平台手动控制

```
前端界面
    │
    ├─▶ POST /api/system/generate/run
    │       ↓
    │   core/generator.py → subprocess(scripts/creator.py)
    │       ↓
    │   sync_all_topics() → 更新数据库
    │
    ├─▶ POST /api/system/optimize/run
    │       ↓
    │   core/optimizer.py → subprocess(scripts/compliance_optimizer.py)
    │       ↓
    │   读取 optimization_report.json → 更新数据库
    │
    └─▶ POST /api/publisher/generate/{topic_id}
            ↓
        api/publisher.py → subprocess(scripts/publisher.py --topic-id X)
            ↓
        复制 HTML 到 content/published/X/手动发布/
```

---

## 📁 数据源唯一性

**核心数据文件**：`automation/data/sustainability_topics.json`

这是系统中**唯一**的选题状态源：
- `collector.py` 写入新选题（status: "待处理"）
- `creator.py` 更新为"待审查" → "draft"
- `compliance_optimizer.py` 更新为"待发布"
- `publisher.py` 更新为"已发布"
- `platform` 的 `sync.py` 同步此 JSON 到 SQLite 供前端快速查询

**不要手动编辑数据库**！应通过脚本或 API 修改 JSON。

---

## 🎯 部署检查清单

- [x] Python 依赖安装 (`platform/backend/requirements.txt`)
- [x] 虚拟环境创建（可选）
- [x] 数据目录存在 (`automation/data/`)
- [x] 日志目录存在 (`automation/logs/`)
- [x] 选题 JSON 存在 (`automation/data/sustainability_topics.json`)
- [x] 前端文件就绪 (`platform/frontend/index.html`)
- [x] 软链接 `automation/scripts → ../scripts/` 正常
- [x] 端口 8000 可用
- [ ] cron 定时任务已配置（如需自动运行）

---

## 🔧 常见命令

```bash
# 1. 启动管理平台
cd yu-zhi-ran
./start-platform.sh 8000

# 2. 手动运行完整流水线（测试）
python test_full_pipeline.py --topic-id A05

# 3. 查看日志
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_summary_$(date +%Y-%m-%d).json

# 4. 查看选题库状态
python -c "import json; d=json.load(open('automation/data/sustainability_topics.json')); print(f'总:{len(d)}, 待处理:{sum(1 for t in d if t.get(\"status\")==\"待处理\")}, 待发布:{sum(1 for t in d if t.get(\"status\")==\"待发布\")}')"

# 5. 触发单步任务
python scripts/collector.py
python scripts/creator.py --topic-id A01
python scripts/publisher.py --topic-id A01

# 6. API 测试
curl http://localhost:8000/api/system/status | python3 -m json.tool
```

---

## 📝 说明

### 为何保留软链接？

`automation/scripts/` 通过软链接指向 `../scripts/`，原因：
- 历史兼容：部分脚本内部使用了硬编码路径 `PROJECT_ROOT/scripts/`
- 统一管理：所有脚本集中在一个目录，便于维护
- 避免复制：减少磁盘占用和同步问题

### platform 与 automation 的关系

- **platform**: Web 管理界面 + API 服务
- **automation**: 数据存储 + 日志归档 + 软链接脚本
- **scripts**: 实际执行逻辑（CLI 工具）

platform 通过 `subprocess` 调用 `scripts/` 中的脚本，输出写入 `automation/data/` 和 `automation/logs/`。

---

**更新日期**: 2026-04-19
**维护**: AI 助手小然