yu-zhi-ran/docs/upgrade-plan.md

宇之然平台升级计划

基于 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 生成：

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

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

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：

@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 改动：

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