How liuxiaopai-ai/raphael-publish works
项目类型与目的(先定“边界”,决定画什么)
从 README 与文件树看,这是一个 纯前端静态 Web 应用(React + Vite + TS + Tailwind),核心目标是:
• 提供一个 Markdown 编辑 + 实时预览 的排版工具
• 支持 富文本/截图粘贴 → 自动转 Markdown(“魔法粘贴”)
• 提供 多主题渲染(30 套主题)
• 输出面向 微信公众号粘贴环境的兼容 HTML(wechatCompat:DOM 重塑、图片 Base64 等)
• 支持 导出 PDF/HTML
部署方式是 构建 dist 后静态托管(GitHub Pages),没有传统后端服务与数据库。
因此系统设计图的主干应是:
• “浏览器端应用内部模块架构 + 关键数据流(粘贴 → Markdown → 渲染 → 兼容处理 → 复制/导出)”
• “CI/CD 与静态托管(GitHub Actions → Pages)”
而不是“前后端/数据库”那种经典图。
从文件结构提炼可画的模块边界(按目录拆组件)
你可以把系统拆成 4 层来画(越上层越接近 UI,越下层越接近引擎/算法):
交付与运行时边界(Deployment / Runtime)
• .github/workflows/ci.yml:CI(lint/test/build)
• .github/workflows/deploy.yml:部署到 GitHub Pages(推 dist)
• public/CNAME:自定义域名(publish.raphael.app)
• index.html、vite.config.ts:前端入口与构建配置
App Shell / 页面编排层(React 页面与布局)
• src/main.tsx:React 挂载入口
• src/App.tsx:应用顶层容器(状态提升/子面板组合通常在这里发生)
• src/index.css、tailwind.config.js、postcss.config.js:全局样式与 Tailwind 管线
UI 组件层(可直接映射到图中的“子系统”)
• src/components/EditorPanel.tsx:编辑器面板(输入 Markdown、粘贴处理入口)
• src/components/PreviewPanel.tsx:预览面板(把 Markdown 渲染成 HTML/主题化/微信兼容)
• src/components/ThemeSelector.tsx:主题选择器
• src/components/Toolbar.tsx:导出/复制/视口切换等动作入口
• src/components/DeviceFrame.tsx:多端预览外壳(手机/平板/桌面尺寸)
• src/components/Header.tsx:顶部导航/品牌区
核心引擎与适配层(这是“架构图里最该细分”的部分)
• src/lib/markdown.ts:Markdown 解析/渲染(markdown-it、highlight.js)
• src/lib/htmlToMarkdown.ts:富文本 HTML → Markdown(turndown;“魔法粘贴”核心)
• src/lib/wechatCompat.ts:微信兼容引擎(DOM 重塑、表格/列表修复、多图布局、图片处理等)
• src/lib/themes/*:主题体系(classic/modern/extra + types + index)
• src/defaultContent.ts:默认示例内容(用于初始化)
测试与质量:
• src/lib/*.test.ts + vitest.config.ts:单元测试(markdown/htmlToMarkdown)
• e2e/app.spec.ts + playwright.config.ts:端到端测试(关键流程回归)
读 README 提炼“关键数据流/用例”,用于画箭头
README 里最关键的交互流是 4 条,建议每条都在图中用箭头画出来:
魔法粘贴流
Clipboard HTML / 富文本 / 图片 → EditorPanel → htmlToMarkdown → Markdown state → PreviewPanel
主题渲染流
ThemeSelector → 选择 Theme config(themes/*)→ PreviewPanel 渲染样式(Tailwind/CSS + theme tokens)
复制到公众号流(最重要的“目标输出”)
Markdown → markdown.ts 渲染 HTML → wechatCompat.ts 做 DOM/样式/结构兼容处理 → 图片 Base64 内联 → Clipboard 写入(最终粘贴到公众号后台)
导出流
Markdown/HTML → HTML 生成 → html2pdf.js 导出 PDF 或导出 HTML 文件 → 下载到本地
这些流决定了图中箭头方向:输入(用户/剪贴板)→ 转换引擎 → 状态 → 渲染/适配 → 输出(预览/剪贴板/文件)。
建议画 3 张“互补”的架构图(每张目的不同)
为了“最准确+最可维护”,不要试图一张图塞所有细节。建议 3 张:
图 1:Context / Deployment(C4 Level 1-2 风格)
目的:回答“系统部署在哪里、依赖哪些外部东西”。
元素建议:
• 用户浏览器(含剪贴板能力)
• Raphael Publish(静态站点:GitHub Pages / 任意 CDN)
• GitHub Actions(CI + Deploy)
• 外部库(可作为注释:markdown-it, turndown, highlight.js, html2pdf.js)
箭头:
• 用户 ↔ 静态站点(HTTP)
• GitHub Actions → Pages(发布 dist)
• 用户 ↔ Clipboard(读/写)
目的:回答“React 应用内部有哪些子系统,职责如何分”。
建议把应用画成一个大框 Raphael Publish (React SPA),内部拆:
• App Shell(App/main)
• UI:EditorPanel / PreviewPanel / Toolbar / ThemeSelector / DeviceFrame
• Core libs:htmlToMarkdown / markdown renderer / wechatCompat / themes
• Assets/Styles:Tailwind/CSS、defaultContent
箭头体现依赖方向(UI → lib;ThemeSelector → themes;PreviewPanel → markdown + wechatCompat)。
图 3:Sequence / Dataflow(关键路径时序图)
目的:回答“点击/粘贴后到底发生了什么”。
至少画两条时序:
• 粘贴富文本 → Markdown → 预览更新
• 点击“复制到公众号” → HTML 生成 → wechatCompat → 图片 Base64 → clipboard.write
针对该项目(纯前端工具)的“组件划分”画法要点
因为没有后端,架构准确性的关键在于把浏览器能力与前端引擎画清楚:
必须显式画出来的“外部/边界能力”
• Clipboard(读:paste 事件、写:复制)
• File Download(导出 HTML/PDF)
• DOM/Rendering(预览区的实际渲染容器)
• 静态托管(GitHub Pages)
必须显式区分的“内部引擎”
• HTML→Markdown(turndown):输入是富文本 DOM/HTML
• Markdown→HTML(markdown-it + highlight.js):输入是 Markdown 字符串
• WeChat 兼容处理(wechatCompat):输入是 HTML DOM/字符串,输出是“可粘贴的兼容 HTML”(含图片 Base64、表格/列表重构、多图布局)
这三者是本项目的“核心差异化”,在图上要比普通 UI 组件更突出(例如用不同颜色或更粗边框)。
清晰标签(建议统一命名)
• 用文件/目录名做括号注释:例如
WeChat Compatibility Engine (src/lib/wechatCompat.ts)
• 主题模块:Theme Pack (src/lib/themes/*)
箭头(建议标注数据形态)
在箭头旁标注数据类型,会让图“工程上更可信”:
• Clipboard HTML / Rich Text
• Markdown string
• HTML string / DOM
• Base64 images
• PDF blob / HTML file
颜色/形状(建议约定)
• 蓝色:UI/React components
• 紫色:core conversion engines(htmlToMarkdown/markdown/wechatCompat)
• 绿色:external browser capabilities(Clipboard/Download)
• 灰色:build/test/deploy toolchain(Vite/Vitest/Playwright/GitHub Actions)
把“尽量细分组件”具体化:建议你在图里拆到这个粒度
基于现有目录,不要只画“Editor/Preview”,可以进一步拆“动作”子模块(即使它们在代码里未必是单独文件,也能作为逻辑组件存在于图上):
• EditorPanel 内部逻辑块(图上可标为子框):
• Paste Handler(富文本/图片)
• Markdown State Manager(React state)
• PreviewPanel 内部逻辑块:
• Markdown Renderer (markdown-it)
• Syntax Highlight (highlight.js)
• Theme Styler (themes)
• WeChat Compat Post-Processor (wechatCompat)
• Toolbar 动作块:
• Copy-to-WeChat Action
• Export PDF (html2pdf.js)
• Export HTML
• Viewport Switch (DeviceFrame)
测试/质量也建议作为侧边模块列出:
• Unit Tests (Vitest): markdown/htmlToMarkdown
• E2E (Playwright): app.spec.ts
• CI Pipeline: ci.yml runs tests + build
快速可复用的图示骨架(你可以直接照着画)
最核心的一张“模块+数据流图”可以按以下布局(从左到右):
• 左侧:User + Clipboard(外部)
• 中间左:EditorPanel(粘贴/输入)
• 中间:Markdown state(App 层状态)
• 中间右:Preview pipeline(markdown renderer → theme → wechatCompat)
• 右侧:Outputs(Preview DOM、Clipboard write、PDF/HTML download)
• 顶部或底部:Tooling lane(Vite build → dist → GitHub Pages;Vitest/Playwright)