# 宇之然平台升级计划

> 基于 2026-05 代码库现状分析

---

## 现状能力矩阵

| 能力 | 状态 | 备注 |
|------|------|------|
| 趋势采集 → 选题 | ✅ 跑通 | APScheduler 01:30 定时采集 |
| 研究/大纲/创作 | ✅ 跑通 | 全链路LLM |
| 多平台适配（3平台） | ✅ 跑通 | writer.py 独立适配 |
| 合规审查 | ✅ 跑通 | LLM迭代修复 |
| 配图/封面生成 | ❌ 未接入 | `image_generator.py` 独立脚本，API 未整合 |
| 文章管理页面 | ❌ 缺失 | 只有选题管理，无独立文章列表页 |
| 发布 UI | ⚠️ 简陋 | topics.html 直接调 API，无确认流/平台选择 |
| 前端体验 | ⚠️ 内部工具 | Vue CDN，无统一状态/加载/错误处理 |
| 数据看板 | ⚠️ 基础 | 只读聚合，未对接平台 API |
| 定时调度 | ✅ 框架完整 | generator.py → optimizer.py → sync.py |
| 任务状态追踪 | ✅ 有框架 | ContentTask + tasks.html |

---

## Phase 1 — 高收益低投入（约 3 天）

### 1.1 配图整合到创作流程

**现状**：`scripts/image_generator.py` 已能生成封面/图表/概念图，但只独立运行。

**改动**：

`scripts/creator.py` 在 writer 成功后追加 image 生成：

```python
# writer.py 成功后
if run_step("writer.py", topic_id):
    run_step("image_generator.py", topic_id)
```

`image_generator.py` 接收 topic_id 参数，生成路径存回 DB：

```python
def generate_for_topic(topic_id, platforms=["zhihu","wechat","xiaohongshu"]):
    topic = get_topic_by_id(topic_id)
    for platform in platforms:
        path = generate_cover_image(topic['title'], platform)
        update_article_cover(topic_id, platform, path)
```

**API**：`GET /api/articles/{topic_id}/images` 返回三平台封面 URL。

**估计**：1 天。

### 1.2 文章管理页面

**现状**：无独立文章页。

**新建** `platform/frontend/articles.html`：

```
字段: 选题ID | 平台 | 标题片段 | 状态 | 合规分 | 创建时间 | 操作
功能: 按选题/平台/状态筛选, 预览, 复制
```

**新增 API** `GET /api/articles/list`：

```python
@router.get("/list")
def list_articles(
    topic_id: str = None,
    platform: str = None,
    status: str = None,
    limit: int = 50,
):
    query = db.query(Article).join(Topic).add_columns(Topic.title.label("topic_title"))
    # 筛选 + 分页
```

**估计**：1.5 天。

### 1.3 统一前端体验

**每页 30 分钟**批量改进：
- 所有 fetch 类方法加 try/catch + loading 状态
- 空数据时显示 `.empty-state` UI（admin.html 已有现成样式）
- 操作反馈用 `this.$message`

**估计**：0.5 天。

---

## Phase 2 — 体验闭环（约 5 天）

### 2.1 发布审批 UI

**现状**：`topics.html` 点"发布" → 直接调 API 标记已发布。

**改进**：发布按钮改为弹窗，可选平台、确认。

**API 改动**：

```python
class MultiPublishRequest(BaseModel):
    topic_id: str
    platforms: List[str]  # ["zhihu", "wechat", "xiaohongshu"]
    scheduled_at: Optional[datetime] = None
```

`PublishRecord` 加 `platform` 字段（当前写死 "all"）。

**估计**：2 天。

### 2.2 日历关联文章状态

日历卡片加文章状态指示（已完成/待审查/已发布）+ 平台图标。

**估计**：1 天。

### 2.3 CSS 收敛 + 移动端适配

- 公共样式从各 HTML 移到 `theme-modern.css`
- 补全移动端卡片布局（当前 admin.html 有，metrics.html/tasks.html 等没有）
- 统一按钮尺寸、间距、颜色

**估计**：1-2 天。

---

## Phase 3 — 数据闭环（约 7 天）

### 3.1 平台数据对接

`scripts/sync_metrics.py` 每天自动拉取各平台阅读量/互动数据，存入 `ContentMetrics`。

调度：scheduler.py 加 `scheduled_metrics_sync`（06:00）。

**估计**：3-5 天（取决于平台 API 复杂度）。

### 3.2 数据看板增强

- 趋势图（周/月/季）
- 各平台对比
- 最佳发布时间分析

前端用 Chart.js（CDN），数据来自现有 `GET /api/metrics/dashboard`。

**估计**：2 天。

---

## Phase 4 — 对外准备（约 10-15 天，按需）

| 模块 | 内容 | 估计 |
|------|------|------|
| 多租户 | User 表加 org_id，数据隔离 | 3 天 |
| 订阅支付 | 支付宝/微信支付 API | 2 天 |
| 安装部署 | docker-compose + 一键脚本 | 2 天 |
| 帮助文档 | 用户手册 | 1 天 |
| 域名备案 | ICP 备案 | 2-4 周（流程） |

---

## 前端框架评估

### 现状

| 项目 | 版本 | 文件大小 |
|------|------|---------|
| Vue 3 | 3.5.32 (2024 Q4) | 160KB min |
| Element Plus | 2.13.7 (2025/2026) | 2.1MB full |
| 构建工具 | 无 | — |

### 选项对比

| 方案 | 成本 | 收益 | 推荐 |
|------|------|------|------|
| **A. 维持 CDN 现状** | 0 | — | ⭐ 自用首选 |
| B. 升级到最新 Vue 3.5.x + Element Plus CDN | ~0 | 兼容性修复 | 没必要（已是最新） |
| C. CDN → ESM + importmap 渐进 | 1-2d | 按需加载，减 1.5MB | 可选优化 |
| D. Vue 3 + Vite + SFC | 3-5d | TS、HMR、组件化 | 对外前做 |
| E. Nuxt 3 | 5-10d | SSR、路由 | 杀鸡用牛刀 |

### 建议：维持 CDN，暂不换框架

**理由**：

1. **版本够新**：Vue 3.5.32 + Element Plus 2.13.7 都是最新生态版本，没有升级动力
2. **CDN 是优势**：对于自用工具，`edit file → refresh browser` 的迭代速度远快于 `npm run dev`
3. **代价与收益不匹配**：换 Vite 需要改 8 个 HTML 页 + 2 个 JS 组件，换来的是 TypeScript（但后端 Python 才是核心逻辑）和 HMR（但每页本来就不大）
4. **唯一值得做的优化**：改用 `importmap` + Element Plus 按需引入，可以把 2.1MB bundle 减到 ~500KB。但这对自用工具感知不强

**如果要对外商用**，Phase 4 时再切 Vite + SFC，用 Vue 3 + Vite 标准模版重写前端。

## 已完成：导航布局重构（2026-05-16）

将原来两套布局（PC sidebar + H5 bottom-nav + "更多"浮层）改为**一套顶部导航栏自适应**。

**改动**：
- 新建 `uni-nav.js` 合并 navbar + navigation 两个组件，统一为单行 top-nav
- PC：所有菜单项在一行显示
- H5（<=768px）：菜单折叠进 hamburger，点击弹出下拉面板
- `theme-modern.css` 添加 `.main-content { padding-top: 60px }` 全局规则，10 个页面同时受益
- 删除所有页面中 `margin-left: 180px` 相关覆写
- 删除 `navigation-component.js` 和 `navbar-component.js`（保留文件未清理）

**效果**：
- 一套布局在所有屏幕尺寸上自然过渡
- 10 个页面同时更新，无需逐个调整

## PC/H5 体验差距分析

### 与 opencode 的对比

| 维度 | opencode | 宇之然 | 差距 |
|------|----------|--------|------|
| 构建方式 | Vite + Tailwind | Vue CDN + 内联CSS | — |
| CSS 架构 | 1 个 bundle + 设计 token | 860行重复内联CSS + 82行共享 | 🔴 |
| 图标系统 | 统一 SVG 图标 | 全部 emoji（📊📋⚙️） | 🔴 |
| 响应式 | Tailwind 内置断点 | 手动 @media，5页缺失 | 🟡 |
| 暗色模式 | 内置 | 无 | 🔴 |
| 主题系统 | CSS 变量 | 硬编码颜色 | 🔴 |
| 导航 | SPA 路由 | 多页+180行JS导航组件 | 🟡 |
| 空状态 | 有 | 6页缺失 | 🟡 |
| 字体/间距 | 统一设计 token | 各自定义 | 🔴 |

### 根因：不是框架问题，是 CSS 架构问题

openCode 用 Tailwind 但本质是 **单一 CSS 设计系统**。宇之然的问题是**没有设计系统**，而不是没有用 Tailwind。

即使维持 Vue CDN，也能通过以下方式大幅提升体验一致性。

### PC/H5 优化计划（投入与收益评估）

| # | 问题 | 修复方式 | 估计 | 体验提升 |
|---|------|---------|------|---------|
| 1 | calendar.html 缺少 `</template>` | 修复该 bug | 5min | ❌ 修复 bug |
| 2 | index.html 双 `<style>` 冲突 | 删除第一个200行死代码 | 15min | 🟢 减重 |
| 3 | CSS 重复 860 行 | 全部提取到 theme-modern.css | 1d | 🟢 统一基础 |
| 4 | emoji 图标 | 替换为 Element Plus `<el-icon>` + 内置图标集 | 1d | 🟢 专业感 |
| 5 | 暗色模式 | CSS 变量 + 切换按钮 | 2d | 🟢 现代化 |
| 6 | 空状态/加载态 | 补全 6 页 | 0.5d | 🟡 体验完整 |
| 7 | H5 缺失卡片布局 | 补全 5 页 | 0.5d | 🟡 移动可用 |
| 8 | 导航组件简化 | 去掉 DOM 注入路径，只用 Vue 组件 | 0.5d | 🟡 减少复杂度 |

### 推荐执行顺序

1. **立即** — 修复 calendar.html bug + index.html 死代码（15 分钟）
2. **Phase 2b** — CSS 收敛 + emoji 替换 + 空状态补全（1.5 天）
3. **Phase 2c** — 暗色模式（2 天，可选）
4. **不做** — 不需要切框架，不需要 Tailwind，不需要 SPA

## 执行建议

1. **先做 Phase 1.2（文章页）** — 每天使用，数据已存在
2. **再做 Phase 1.1（配图）** — 创作完自动配封面，体验提升明显
3. **Phase 1.3 穿插各页** — 逐步打磨
4. **按需进入 Phase 2** — 看自用感受决定
5. **只有决定对外才进 Phase 4**