From 8c6efae3fb1ae8b66d1285330510311095ec0bcb Mon Sep 17 00:00:00 2001
From: npmrun <1549469775@qq.com>
Date: Fri, 24 Apr 2026 22:57:11 +0800
Subject: [PATCH] docs(spec): add Vditor unification design for markdown
 editing

Document the approved design to replace editable markdown inputs with Vditor, including PC/mobile behavior, scope boundaries, and acceptance criteria.

Made-with: Cursor
---
 .../specs/2026-04-24-vditor-unification-design.md  | 137 +++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-24-vditor-unification-design.md

diff --git a/docs/superpowers/specs/2026-04-24-vditor-unification-design.md b/docs/superpowers/specs/2026-04-24-vditor-unification-design.md
new file mode 100644
index 0000000..38f18f3
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-24-vditor-unification-design.md
@@ -0,0 +1,137 @@
+# Markdown 编辑器统一为 Vditor 设计
+
+## 1. 背景与目标
+
+当前项目在可编辑 Markdown 输入场景使用 `md-editor-v3`。本次需求是将所有“可编辑输入”场景统一替换为 `Vditor`，并明确端侧体验策略：
+
+- PC 端：完整工具栏 + 预览能力（A）
+- 移动端：编辑优先、精简工具栏、预览为次级入口（B）
+
+本次设计目标：
+
+- 统一编辑器技术栈，降低后续维护成本。
+- 保持现有数据契约与后端 API 不变，避免不必要联动改造。
+- 保证移动端可用性，不牺牲主要输入效率。
+- 将改动收敛在单一封装组件，减少页面级回归风险。
+
+## 2. 方案结论
+
+采用 **方案 1：保留现有组件入口，内部替换为 Vditor**。
+
+- 对外继续使用 `PostBodyMarkdownEditor` 与 `v-model`。
+- 组件内部从 `md-editor-v3` 切换到 `Vditor` 实例化与事件同步。
+- 页面侧（如新建/编辑文章）尽量零改动或仅最小改动。
+
+不采用其余方案原因：
+
+- 新建并行组件逐页替换：会增加过渡期双栈维护成本。
+- 抽象多编辑器驱动层：对当前“统一到 Vditor”目标属于过度设计。
+
+## 3. 范围与边界
+
+### 3.1 本次范围
+
+- 所有“可编辑 Markdown 输入”页面统一使用 `Vditor` 封装。
+- 包括但不限于文章新建、文章编辑等输入表单场景。
+
+### 3.2 非本次范围
+
+- 只读预览/渲染页面（例如公开页渲染链路）不改为 Vditor 渲染。
+- 服务端 Markdown 处理、导出、清洗逻辑不因本次改造重写。
+- 非 Markdown 输入控件不纳入改造。
+
+## 4. 架构设计
+
+### 4.1 组件边界
+
+- 保留 `PostBodyMarkdownEditor` 作为唯一编辑器入口组件。
+- 组件输入：`modelValue: string`
+- 组件输出：`update:modelValue`（Markdown 文本）
+- 组件职责：
+  - 初始化/销毁 Vditor 实例
+  - 双向同步内容
+  - 端侧差异化配置（PC/移动端）
+  - 上传回调与错误提示
+
+### 4.2 生命周期与运行环境
+
+- 仅客户端初始化（保持 `ClientOnly` 思路），避免 SSR 下访问 `window/document`。
+- 组件卸载时必须销毁实例，避免重复绑定与内存泄漏。
+- 路由切换或父级重渲染后，可稳定恢复编辑内容。
+
+### 4.3 数据契约
+
+- 持续使用纯 Markdown 字符串作为唯一存储/传输格式。
+- 不引入额外富文本 JSON 结构。
+- 与现有保存 API 入参保持一致：`bodyMarkdown` 不变。
+
+## 5. 交互与端侧策略
+
+### 5.1 PC 端策略（A）
+
+- 默认完整工具栏，覆盖高频与中频编辑操作。
+- 保留预览能力，满足边写边看排版需求。
+- 维持大编辑区高度，保障长文编辑连续性。
+
+### 5.2 移动端策略（B）
+
+- 默认“编辑优先”视图，输入区占据主区域。
+- 工具栏精简为高频操作：
+  - 粗体、斜体、标题、列表、链接、图片、代码块
+- 预览作为次级入口（切换按钮或分段视图），不默认占据主区域。
+- 调整高度与滚动行为，降低软键盘弹起带来的遮挡风险。
+
+### 5.3 内容同步规则
+
+- 外部 `modelValue` 变化时，编辑器内容同步更新。
+- 编辑器内容变化时，实时触发 `update:modelValue`。
+- 避免循环赋值：当内容未变化时不重复 setValue。
+
+## 6. 上传与错误处理
+
+- 图片上传继续复用现有 `/api/file/upload` 接口与鉴权方式。
+- 上传成功后插入返回 URL。
+- 上传失败时通过 toast 提示，但不阻断用户继续编辑。
+- 网络异常与接口异常统一走已有错误处理体验，不新增后端协议。
+
+## 7. 兼容性与回归风险
+
+### 7.1 需保持不变的能力
+
+- Front matter 清理策略与渲染安全策略（如 HTML 禁用）保持现有语义。
+- 文章保存、回填、预览链路的字段名与行为保持一致。
+- 字数统计继续基于 Markdown 文本计算。
+
+### 7.2 主要风险
+
+1. 编辑器实例销毁不完整导致重复监听。  
+2. 移动端工具栏过多导致输入区被压缩。  
+3. 外部值同步与内部变更监听冲突，造成内容抖动。  
+4. 图片上传回调与编辑器插入语法对接不一致。
+
+### 7.3 风险缓解
+
+- 在组件层集中处理初始化、销毁、监听与去重逻辑。
+- 以断点配置拆分 PC/移动端 toolbar，避免“一套配置走天下”。
+- 对上传、保存、回填做最小闭环手测与自动化回归。
+
+## 8. 验收标准
+
+1. 所有 Markdown 可编辑输入页面均使用统一 Vditor 封装组件。  
+2. 新建与编辑文章场景可正常输入、保存、回填。  
+3. 图片上传成功可插入，失败有可见提示。  
+4. PC 端满足“完整工具栏 + 预览”；移动端满足“编辑优先 + 精简工具栏 + 次级预览”。  
+5. 无 SSR 客户端对象报错；路由切换后无明显实例泄漏迹象。  
+6. 服务端接口与数据结构无需改造即可兼容上线。
+
+## 9. 实施边界（本阶段）
+
+本文件仅定义设计与验收，不直接包含代码实现。  
+下一步进入实现计划阶段，将改造拆解为可执行任务（依赖调整、组件替换、页面回归、测试与发布验证）。
+
+## 10. 规格自检（已完成）
+
+- 已检查：无 TBD/TODO 等占位符。  
+- 已检查：范围仅覆盖“可编辑输入场景”，与用户约束一致。  
+- 已检查：PC 与移动端策略明确，未出现互相冲突描述。  
+- 已检查：验收标准可执行、可验证，且与架构边界一致。