# Vditor Unification Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 将所有 Markdown 可编辑输入场景统一到 `Vditor`，并满足 PC 端完整编辑体验与移动端编辑优先体验。

**Architecture:** 保留 `PostBodyMarkdownEditor` 作为唯一入口组件，对外接口继续使用 `v-model`，内部替换为 `Vditor` 实例并集中处理生命周期、上传回调与端侧差异化配置。页面层尽量不改动业务逻辑，只做必要的样式/交互对齐；通过组件级测试与关键路径手测保障保存、回填、上传与移动端可用性。

**Tech Stack:** Nuxt 4、Vue 3、TypeScript、Vditor、Bun

---

## File Structure

**Create**
- `app/components/PostBodyMarkdownEditor.vditor.test.ts`：编辑器组件行为测试（同步、上传、移动端配置切换）

**Modify**
- `package.json`：新增 `vditor` 依赖，移除 `md-editor-v3`（如无其他引用）
- `app/components/PostBodyMarkdownEditor.vue`：内部从 `md-editor-v3` 替换为 `Vditor`
- `app/pages/me/posts/new.vue`：仅在必要时调整容器样式（若编辑器高度或移动端布局需要）
- `app/pages/me/posts/[id].vue`：仅在必要时调整容器样式（与新建页一致）

**Test**
- `app/components/PostBodyMarkdownEditor.vditor.test.ts`
- 手工验证页面：`app/pages/me/posts/new.vue`、`app/pages/me/posts/[id].vue`

---

### Task 1: 依赖切换与基线校验

**Files:**
- Modify: `package.json`

- [ ] **Step 1: 写失败检查（确认旧编辑器仍被引用）**

```bash
rg "md-editor-v3" app package.json
```

Expected: 至少包含 `PostBodyMarkdownEditor.vue` 与 `package.json` 命中，表示替换前基线成立。

- [ ] **Step 2: 运行检查确认基线**

Run: `rg "md-editor-v3" app package.json`  
Expected: 有匹配结果（旧实现仍在）

- [ ] **Step 3: 更新依赖为 Vditor**

```json
{
  "dependencies": {
    "vditor": "^3.10.0"
  }
}
```

并移除：

```json
{
  "dependencies": {
    "md-editor-v3": "..."
  }
}
```

- [ ] **Step 4: 安装依赖并校验 lockfile 变更**

Run: `bun install`  
Expected: `vditor` 安装成功，依赖树无冲突错误

- [ ] **Step 5: 提交**

```bash
git add package.json bun.lock
git commit -m "chore(markdown): replace md-editor-v3 dependency with vditor"
```

---

### Task 2: 重写 PostBodyMarkdownEditor 组件为 Vditor 实现

**Files:**
- Modify: `app/components/PostBodyMarkdownEditor.vue`
- Test: `app/components/PostBodyMarkdownEditor.vditor.test.ts`

- [ ] **Step 1: 写失败测试（v-model 双向同步）**

```ts
import { describe, test, expect } from "bun:test";

describe("PostBodyMarkdownEditor v-model sync", () => {
  test("emits update when editor content changes", async () => {
    // mount component with modelValue = "a"
    // simulate editor input -> "b"
    // expect update:modelValue emitted with "b"
    expect(true).toBe(false);
  });
});
```

- [ ] **Step 2: 运行测试确认失败**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts`  
Expected: FAIL（测试占位断言失败或组件尚未适配 Vditor）

- [ ] **Step 3: 写最小实现（客户端初始化 + 销毁 + 双向同步）**

```ts
import Vditor from "vditor";
import "vditor/dist/index.css";

const editor = shallowRef<Vditor | null>(null);
const hostEl = ref<HTMLElement | null>(null);

onMounted(() => {
  if (!hostEl.value) return;
  editor.value = new Vditor(hostEl.value, {
    value: props.modelValue,
    input(value) {
      emit("update:modelValue", value);
    },
  });
});

watch(
  () => props.modelValue,
  (next) => {
    const inst = editor.value;
    if (!inst) return;
    if (inst.getValue() !== next) {
      inst.setValue(next, true);
    }
  },
);

onBeforeUnmount(() => {
  editor.value?.destroy();
  editor.value = null;
});
```

- [ ] **Step 4: 运行测试确认通过**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts`  
Expected: PASS（双向同步、实例销毁断言通过）

- [ ] **Step 5: 提交**

```bash
git add app/components/PostBodyMarkdownEditor.vue app/components/PostBodyMarkdownEditor.vditor.test.ts
git commit -m "refactor(editor): migrate PostBodyMarkdownEditor to vditor core"
```

---

### Task 3: 实现 PC/移动端差异化配置（A/B 策略）

**Files:**
- Modify: `app/components/PostBodyMarkdownEditor.vue`
- Test: `app/components/PostBodyMarkdownEditor.vditor.test.ts`

- [ ] **Step 1: 写失败测试（按断点应用不同 toolbar/preview 策略）**

```ts
describe("PostBodyMarkdownEditor responsive config", () => {
  test("uses full toolbar on desktop and compact toolbar on mobile", async () => {
    // mock matchMedia for desktop/mobile
    // assert Vditor config differs by mode
    expect(true).toBe(false);
  });
});
```

- [ ] **Step 2: 运行测试确认失败**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts -t "responsive config"`  
Expected: FAIL（断点策略尚未实现）

- [ ] **Step 3: 增加断点配置逻辑**

```ts
const isMobile = useMediaQuery("(max-width: 768px)");

const desktopToolbar = [
  "headings", "bold", "italic", "strike", "|",
  "list", "ordered-list", "check", "|",
  "quote", "line", "code", "inline-code", "|",
  "link", "upload", "table", "|", "preview", "fullscreen"
];

const mobileToolbar = ["bold", "italic", "headings", "list", "link", "upload", "code"];

const options = {
  toolbar: isMobile.value ? mobileToolbar : desktopToolbar,
  mode: isMobile.value ? "sv" : "wysiwyg",
  preview: {
    mode: isMobile.value ? "editor" : "both",
  },
};
```

并确保移动端存在可进入预览的入口（按钮或工具栏项）。

- [ ] **Step 4: 运行测试确认通过**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts -t "responsive config"`  
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add app/components/PostBodyMarkdownEditor.vue app/components/PostBodyMarkdownEditor.vditor.test.ts
git commit -m "feat(editor): add desktop/mobile tailored vditor modes"
```

---

### Task 4: 接入现有图片上传链路并对齐错误提示

**Files:**
- Modify: `app/components/PostBodyMarkdownEditor.vue`
- Test: `app/components/PostBodyMarkdownEditor.vditor.test.ts`

- [ ] **Step 1: 写失败测试（上传成功插入 URL，失败提示）**

```ts
describe("PostBodyMarkdownEditor image upload", () => {
  test("inserts uploaded urls into markdown", async () => {
    // mock fetchData('/api/file/upload') -> { files: [{ url: "https://x/a.png" }] }
    // trigger upload hook
    // expect markdown contains image syntax with returned url
    expect(true).toBe(false);
  });
});
```

- [ ] **Step 2: 运行测试确认失败**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts -t "image upload"`  
Expected: FAIL（上传钩子尚未对接）

- [ ] **Step 3: 实现上传适配**

```ts
upload: {
  accept: "image/*",
  handler: async (files) => {
    const form = new FormData();
    files.forEach((f) => form.append("file", f));
    try {
      const { files: uploaded } = await fetchData("/api/file/upload", {
        method: "POST",
        body: form,
      });
      toast.add({ title: "图片已上传", color: "success" });
      return JSON.stringify({
        msg: "",
        code: 0,
        data: { errFiles: [], succMap: Object.fromEntries(uploaded.map((x) => [x.url, x.url])) },
      });
    } catch {
      toast.add({ title: "图片上传失败", color: "warning" });
      return JSON.stringify({ msg: "upload failed", code: 1, data: { errFiles: [], succMap: {} } });
    }
  },
},
```

- [ ] **Step 4: 运行测试确认通过**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts -t "image upload"`  
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add app/components/PostBodyMarkdownEditor.vue app/components/PostBodyMarkdownEditor.vditor.test.ts
git commit -m "feat(editor): wire vditor image upload to existing api"
```

---

### Task 5: 页面回归与移动端可用性验证

**Files:**
- Modify: `app/pages/me/posts/new.vue`（如需最小样式调整）
- Modify: `app/pages/me/posts/[id].vue`（如需最小样式调整）

- [ ] **Step 1: 写失败检查（页面仍依赖统一编辑器组件）**

```bash
rg "<PostBodyMarkdownEditor" app/pages/me/posts/new.vue app/pages/me/posts/[id].vue
```

Expected: 两个页面都命中，确认页面接入点统一。

- [ ] **Step 2: 启动开发环境并验证基础流程**

Run: `bun run dev`  
Expected:
- 新建文章页可输入 Markdown、可保存
- 编辑文章页可回填并保存

- [ ] **Step 3: 移动端手测（浏览器设备模拟）**

Run: `bun run dev` + 浏览器 DevTools 移动设备模式  
Expected:
- 默认编辑优先
- 工具栏为精简模式
- 可进入预览视图
- 软键盘/视口变化下输入区可持续编辑

- [ ] **Step 4: 执行相关自动化测试**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts`  
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add app/pages/me/posts/new.vue app/pages/me/posts/[id].vue app/components/PostBodyMarkdownEditor.vditor.test.ts
git commit -m "test(editor): verify vditor behavior on post create/edit flows"
```

---

### Task 6: 清理旧编辑器引用并最终验收

**Files:**
- Modify: `app/components/PostBodyMarkdownEditor.vue`
- Modify: `package.json`

- [ ] **Step 1: 写失败检查（仍存在旧编辑器运行时引用）**

```bash
rg "md-editor-v3|MdEditor" app package.json
```

Expected: 若仍有命中则说明清理未完成。

- [ ] **Step 2: 清理所有旧编辑器运行时引用**

Run: `rg "md-editor-v3|MdEditor" app package.json`  
Expected: 无运行时代码命中（仅历史文档可保留）

- [ ] **Step 3: 执行最小验收命令**

Run: `bun test app/components/PostBodyMarkdownEditor.vditor.test.ts`  
Expected: PASS

- [ ] **Step 4: 手工闭环验收**

Run: `bun run dev`  
Expected:
- PC 端：完整工具栏 + 可预览
- 移动端：编辑优先 + 精简工具栏 + 次级预览
- 图片上传成功插入，失败有提示
- 保存/回填链路正常

- [ ] **Step 5: 提交**

```bash
git add app/components/PostBodyMarkdownEditor.vue package.json bun.lock app/components/PostBodyMarkdownEditor.vditor.test.ts
git commit -m "refactor(markdown): fully unify editable markdown inputs on vditor"
```

---

## Self-Review

1. **Spec coverage:** 已覆盖范围边界（仅可编辑输入）、PC=A 与移动端=B 策略、上传链路、双向同步、生命周期、验收标准。  
2. **Placeholder scan:** 无 TBD/TODO/“后续补充”占位词；每个任务均给出命令与预期结果。  
3. **Type consistency:** 全程统一使用 `PostBodyMarkdownEditor`、`modelValue/update:modelValue`、`/api/file/upload` 命名，前后一致。