docs(quick-note): add design spec and implementation plan

Document the approved quick note modal design and the step-by-step implementation plan used to deliver the feature. Made-with: Cursor
2 weeks ago · 727a380459
2 changed files with 552 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-27-quick-note-modal-implementation-plan.md
+++ b/docs/superpowers/plans/2026-04-27-quick-note-modal-implementation-plan.md
@ -0,0 +1,405 @@
 # Quick Note Modal 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:** 在顶部“写文章”按钮左侧新增“速记”入口，提供可拖拽/可全屏的轻量速记弹框，支持上传、手动保存、每用户唯一内容和未保存离开保护。
 **Architecture:** 前端在 `AppShell` 挂载速记入口与弹框，弹框拆分为容器层（拖拽、全屏、未保存拦截）和编辑器层（轻量 Vditor + 上传复用）。后端新增用户唯一 `quick_notes` 存储与 `GET/PUT /api/me/quick-note` 接口，服务层统一处理 upsert、长度校验和换行标准化。全链路以 TDD 驱动，按“先失败测试 -> 最小实现 -> 通过测试 -> 提交”小步推进。
 **Tech Stack:** Nuxt 4、Vue 3、TypeScript、Bun test、Drizzle ORM（SQLite）
 ---
 ## File Structure
 **Create**
 - `app/components/QuickNoteModal.vue`：速记弹框容器（近全屏、全屏切换、拖拽、未保存拦截、beforeunload）
 - `app/components/QuickNoteEditor.vue`：轻量编辑器（复用 Vditor 与上传配置）
 - `app/components/quick-note-editor-vditor-config.ts`：速记编辑器 Vditor 轻量配置
 - `app/components/quick-note-modal-state.ts`：速记 dirty/save 状态与交互纯函数
 - `app/components/quick-note-modal-state.test.ts`：状态纯函数测试
 - `server/service/quick-note/index.ts`：速记服务（get/upsert/normalize/validate）
 - `server/service/quick-note/index.test.ts`：速记服务测试
 - `server/api/me/quick-note.get.ts`：获取当前用户速记
 - `server/api/me/quick-note.put.ts`：手动保存当前用户速记
 - `packages/drizzle-pkg/migrations/0012_quick_notes.sql`：新增 quick_notes 表与唯一索引
 **Modify**
 - `app/components/AppShell.vue`：新增“速记”按钮并挂载弹框
 - `packages/drizzle-pkg/database/sqlite/schema/content.ts`：新增 `quickNotes` 表定义
 - `packages/drizzle-pkg/lib/schema/content.ts`：导出 `quickNotes`
 - `packages/drizzle-pkg/migrations/meta/_journal.json`：登记新 migration
 - `server/api/me` 下路由索引（若项目需要）用于自动发现 `quick-note` 接口
 **Test**
 - `app/components/quick-note-modal-state.test.ts`
 - `app/components/post-body-markdown-editor-vditor-config.test.ts`（可补一条“复用上传格式兼容”断言）
 - `server/service/quick-note/index.test.ts`
 ---
 ### Task 1: 数据层建模（每用户唯一 quick note）
 **Files:**
 - Modify: `packages/drizzle-pkg/database/sqlite/schema/content.ts`
 - Modify: `packages/drizzle-pkg/lib/schema/content.ts`
 - Create: `packages/drizzle-pkg/migrations/0012_quick_notes.sql`
 - Modify: `packages/drizzle-pkg/migrations/meta/_journal.json`
 - [ ] **Step 1: 写失败检查（确认 quick_notes 尚未存在）**
 ```bash
 rg "quick_notes|quickNotes" packages/drizzle-pkg/database/sqlite/schema/content.ts packages/drizzle-pkg/lib/schema/content.ts
 ```
 Expected: 无匹配结果。
 - [ ] **Step 2: 运行检查确认失败基线**
 Run: `rg "quick_notes|quickNotes" packages/drizzle-pkg/database/sqlite/schema/content.ts packages/drizzle-pkg/lib/schema/content.ts`  
 Expected: Exit code 1（无命中）
 - [ ] **Step 3: 增加表定义与导出**
 ```ts
 // packages/drizzle-pkg/database/sqlite/schema/content.ts
 export const quickNotes = sqliteTable(
  "quick_notes",
  {
    id: integer().primaryKey(),
    userId: integer("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
    content: text().notNull().default(""),
    createdAt: integer("created_at", { mode: "timestamp_ms" }).defaultNow().notNull(),
    updatedAt: integer("updated_at", { mode: "timestamp_ms" }).defaultNow().$onUpdate(() => new Date()).notNull(),
  },
  (table) => [uniqueIndex("quick_notes_user_id_unique").on(table.userId)],
 );
 ```
 ```ts
 // packages/drizzle-pkg/lib/schema/content.ts
 export { quickNotes } from "../../database/sqlite/schema/content";
 ```
 ```sql
 -- packages/drizzle-pkg/migrations/0012_quick_notes.sql
 CREATE TABLE `quick_notes` (
  `id` integer PRIMARY KEY NOT NULL,
  `user_id` integer NOT NULL,
  `content` text NOT NULL DEFAULT '',
  `created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
  `updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
  FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
 );
 CREATE UNIQUE INDEX `quick_notes_user_id_unique` ON `quick_notes` (`user_id`);
 ```
 - [ ] **Step 4: 生成并校验 schema/migration 一致性**
 Run: `cd packages/drizzle-pkg && bun run generate`  
 Expected: 生成结果无冲突，`migrations` 元信息可追踪 `0012_quick_notes.sql`
 - [ ] **Step 5: 提交**
 ```bash
 git add packages/drizzle-pkg/database/sqlite/schema/content.ts packages/drizzle-pkg/lib/schema/content.ts packages/drizzle-pkg/migrations/0012_quick_notes.sql packages/drizzle-pkg/migrations/meta/_journal.json
 git commit -m "feat(db): add per-user quick note table"
 ```
 ---
 ### Task 2: 服务层实现（读取、upsert、校验）
 **Files:**
 - Create: `server/service/quick-note/index.ts`
 - Create: `server/service/quick-note/index.test.ts`
 - [ ] **Step 1: 写失败测试（无记录返回空、保存后可读取、超长报错）**
 ```ts
 import { describe, expect, test } from "bun:test";
 import { normalizeQuickNoteContent, validateQuickNoteContentLength } from "./index";
 describe("quick-note content guards", () => {
  test("normalizes CRLF to LF", () => {
    expect(normalizeQuickNoteContent("a\r\nb")).toBe("a\nb");
  });
  test("throws when exceeds limit", () => {
    expect(() => validateQuickNoteContentLength("x".repeat(200001))).toThrow("速记内容过长");
  });
 });
 ```
 - [ ] **Step 2: 运行测试确认失败**
 Run: `bun test server/service/quick-note/index.test.ts`  
 Expected: FAIL（函数/模块尚未实现）
 - [ ] **Step 3: 写最小实现**
 ```ts
 import { dbGlobal } from "drizzle-pkg/lib/db";
 import { quickNotes } from "drizzle-pkg/lib/schema/content";
 import { eq } from "drizzle-orm";
 import { nextIntegerId } from "#server/utils/sqlite-id";
 export const QUICK_NOTE_MAX_LENGTH = 200_000;
 export function normalizeQuickNoteContent(content: string) {
  return content.replace(/\r\n/g, "\n");
 }
 export function validateQuickNoteContentLength(content: string) {
  if (content.length > QUICK_NOTE_MAX_LENGTH) {
    throw createError({ statusCode: 400, statusMessage: "速记内容过长" });
  }
 }
 ```
 并补充 `getQuickNoteByUserId`、`upsertQuickNoteByUserId`，用 `userId` 查询，不存在则 insert，存在则 update。
 - [ ] **Step 4: 运行测试确认通过**
 Run: `bun test server/service/quick-note/index.test.ts`  
 Expected: PASS
 - [ ] **Step 5: 提交**
 ```bash
 git add server/service/quick-note/index.ts server/service/quick-note/index.test.ts
 git commit -m "feat(server): add quick note service with validation"
 ```
 ---
 ### Task 3: API 层实现（GET/PUT /api/me/quick-note）
 **Files:**
 - Create: `server/api/me/quick-note.get.ts`
 - Create: `server/api/me/quick-note.put.ts`
 - Modify: `server/service/quick-note/index.ts`（若需补返回 DTO）
 - [ ] **Step 1: 写失败检查（接口文件不存在）**
 ```bash
 ls server/api/me/quick-note.get.ts server/api/me/quick-note.put.ts
 ```
 Expected: 报不存在。
 - [ ] **Step 2: 运行检查确认失败**
 Run: `ls server/api/me/quick-note.get.ts server/api/me/quick-note.put.ts`  
 Expected: `No such file or directory`
 - [ ] **Step 3: 写最小接口实现**
 ```ts
 // server/api/me/quick-note.get.ts
 import { getQuickNoteByUserId } from "#server/service/quick-note";
 export default defineWrappedResponseHandler(async (event) => {
  const user = await event.context.auth.requireUser();
  const row = await getQuickNoteByUserId(user.id);
  return R.success({ quickNote: { content: row?.content ?? "", updatedAt: row?.updatedAt ?? null } });
 });
 ```
 ```ts
 // server/api/me/quick-note.put.ts
 import { upsertQuickNoteByUserId } from "#server/service/quick-note";
 export default defineWrappedResponseHandler(async (event) => {
  const user = await event.context.auth.requireUser();
  const body = await readBody<{ content: string }>(event);
  if (typeof body.content !== "string") {
    throw createError({ statusCode: 400, statusMessage: "content 必须为字符串" });
  }
  const row = await upsertQuickNoteByUserId(user.id, body.content);
  return R.success({ quickNote: { content: row.content, updatedAt: row.updatedAt } });
 });
 ```
 - [ ] **Step 4: 启动服务并手工验证**
 Run: `bun run dev`  
 Expected:
 - `GET /api/me/quick-note` 已登录返回 `{ content }`
 - `PUT /api/me/quick-note` 手动保存成功并可再次读回
 - [ ] **Step 5: 提交**
 ```bash
 git add server/api/me/quick-note.get.ts server/api/me/quick-note.put.ts server/service/quick-note/index.ts
 git commit -m "feat(api): add me quick-note get and put endpoints"
 ```
 ---
 ### Task 4: 前端轻量编辑器与状态机（dirty/save）
 **Files:**
 - Create: `app/components/quick-note-editor-vditor-config.ts`
 - Create: `app/components/QuickNoteEditor.vue`
 - Create: `app/components/quick-note-modal-state.ts`
 - Create: `app/components/quick-note-modal-state.test.ts`
 - [ ] **Step 1: 写失败测试（dirty 判定、保存后清洁、失败保留草稿）**
 ```ts
 import { describe, expect, test } from "bun:test";
 import { computeIsDirty } from "./quick-note-modal-state";
 describe("quick note modal state", () => {
  test("is dirty when draft differs from saved", () => {
    expect(computeIsDirty({ savedContent: "a", draftContent: "b" })).toBe(true);
  });
 });
 ```
 - [ ] **Step 2: 运行测试确认失败**
 Run: `bun test app/components/quick-note-modal-state.test.ts`  
 Expected: FAIL（状态模块未实现）
 - [ ] **Step 3: 写最小实现（状态 + 轻量编辑器）**
 ```ts
 // app/components/quick-note-modal-state.ts
 export function computeIsDirty(input: { savedContent: string; draftContent: string }) {
  return input.savedContent !== input.draftContent;
 }
 ```
 ```ts
 // app/components/quick-note-editor-vditor-config.ts
 export const QUICK_NOTE_TOOLBAR = ["bold", "italic", "headings", "|", "list", "ordered-list", "|", "link", "upload", "code"];
 ```
 `QuickNoteEditor.vue` 复用 `post-body-markdown-editor-vditor-bridge.ts` 模式，上传格式复用现有解析逻辑，保留 `onUploadError` 提示。
 - [ ] **Step 4: 运行测试确认通过**
 Run: `bun test app/components/quick-note-modal-state.test.ts app/components/post-body-markdown-editor-vditor-config.test.ts`  
 Expected: PASS
 - [ ] **Step 5: 提交**
 ```bash
 git add app/components/quick-note-editor-vditor-config.ts app/components/QuickNoteEditor.vue app/components/quick-note-modal-state.ts app/components/quick-note-modal-state.test.ts
 git commit -m "feat(app): add lightweight quick-note editor and dirty-state helpers"
 ```
 ---
 ### Task 5: 弹框容器与入口集成（拖拽/全屏/未保存拦截）
 **Files:**
 - Create: `app/components/QuickNoteModal.vue`
 - Modify: `app/components/AppShell.vue`
 - [ ] **Step 1: 写失败检查（确认 AppShell 尚无“速记”入口）**
 ```bash
 rg "速记|QuickNoteModal|quick-note" app/components/AppShell.vue
 ```
 Expected: 无命中。
 - [ ] **Step 2: 运行检查确认失败**
 Run: `rg "速记|QuickNoteModal|quick-note" app/components/AppShell.vue`  
 Expected: Exit code 1（无命中）
 - [ ] **Step 3: 写最小 UI 与交互实现**
 ```vue
 <!-- app/components/AppShell.vue (header actions) -->
 <UButton
  v-if="showQuickCreate"
  color="neutral"
  variant="soft"
  icon="i-lucide-notebook-pen"
  size="sm"
  class="hidden md:inline-flex"
  @click="quickNoteOpen = true"
 >
  速记
 </UButton>
 <QuickNoteModal v-model:open="quickNoteOpen" />
 ```
 ```ts
 // QuickNoteModal.vue (核心片段)
 const isFullscreen = ref(false);
 const isDirty = computed(() => draftContent.value !== savedContent.value);
 onMounted(() => window.addEventListener("beforeunload", onBeforeUnload));
 onBeforeUnmount(() => window.removeEventListener("beforeunload", onBeforeUnload));
 ```
 并实现：
 - 默认近全屏（保留边距）
 - 右上角按钮切换全屏/退出全屏
 - 非全屏标题栏拖拽
 - 关闭弹框时 dirty 二次确认
 - [ ] **Step 4: 启动前端手测关键交互**
 Run: `bun run dev`  
 Expected:
 - “速记”按钮在“写文章”左侧可见
 - 打开即近全屏
 - 全屏切换可用
 - 未保存关闭时弹确认框
 - 未保存刷新/离页触发浏览器原生提醒
 - [ ] **Step 5: 提交**
 ```bash
 git add app/components/AppShell.vue app/components/QuickNoteModal.vue
 git commit -m "feat(ui): add quick-note modal entry with drag/fullscreen and unsaved guards"
 ```
 ---
 ### Task 6: 端到端回归与质量闸门
 **Files:**
 - Modify: `docs/superpowers/specs/2026-04-27-quick-note-modal-design.md`（仅在验收结论需要补充时）
 - [ ] **Step 1: 运行自动化测试**
 Run: `bun test app/components/quick-note-modal-state.test.ts server/service/quick-note/index.test.ts app/components/post-body-markdown-editor-vditor-config.test.ts`  
 Expected: PASS
 - [ ] **Step 2: 运行 lint（仅本次变更范围）**
 Run: `bun run lint`  
 Expected: 无新增错误（允许存在历史告警，但不能新增）
 - [ ] **Step 3: 手工验收清单**
 Run: `bun run dev`  
 Expected:
 - 每个登录用户只有一条速记内容（切账号互不影响）
 - 仅手动保存写入服务端
 - 未保存保护在“关闭弹框”和“离开页面”两处都生效
 - 上传可用，插入行为与文章编辑链路一致
 - [ ] **Step 4: 最终提交**
 ```bash
 git add app/components server/api/me server/service/quick-note packages/drizzle-pkg
 git commit -m "feat(quick-note): implement per-user quick note modal with manual save"
 ```
 - [ ] **Step 5: 输出验证证据**
 Run: `git show --stat --oneline -1`  
 Expected: 展示 quick-note 相关文件变更清单，便于 PR 描述直接引用。
 ---
 ## Self-Review
 1. **Spec coverage:** 已覆盖入口位置、近全屏+全屏切换、拖拽、轻量编辑器+上传、用户唯一存储、手动保存、双重未保存提醒、测试与验收。  
 2. **Placeholder scan:** 无 TBD/TODO/“后续补充”；每个任务均给出具体路径、命令、预期输出和最小代码片段。  
 3. **Type consistency:** 前后统一使用 `quick-note` 路由命名、`savedContent/draftContent/isDirty` 状态命名、`GET/PUT /api/me/quick-note` 接口约定。
--- a/docs/superpowers/specs/2026-04-27-quick-note-modal-design.md
+++ b/docs/superpowers/specs/2026-04-27-quick-note-modal-design.md
@ -0,0 +1,147 @@
 # Quick Note Modal Design
 ## Background
 Current writing flow is centered on article creation. The user needs a faster way to jot down temporary or reusable notes without opening the full post creation flow. The quick note should be accessible near the top "Write Article" button and support a lightweight editing experience with media upload.
 ## Goals
 - Add a `Quick Note` entry to the left side of the top `Write Article` button.
 - Open a draggable modal that defaults to near-fullscreen and can switch to true fullscreen.
 - Provide a lightweight editor with upload support.
 - Store one unique quick note per authenticated user.
 - Use manual save only.
 - Protect unsaved changes when closing the modal or leaving the page.
 ## Non-goals
 - No auto-save in this iteration.
 - No multi-note list, categorization, or version history.
 - No public sharing capability.
 - No cross-user collaboration.
 ## User Experience
 ### Entry and Open
 - A `Quick Note` button appears to the left of `Write Article`.
 - Clicking `Quick Note` opens the modal and loads the current user's note from backend.
 - If no note exists, editor opens with empty content.
 ### Modal Behavior
 - Default state is near-fullscreen (small viewport margins).
 - Modal is draggable by title bar when not in fullscreen.
 - Top-right button toggles `Fullscreen` and `Exit Fullscreen`.
 - Fullscreen mode disables dragging.
 - Exiting fullscreen restores draggable mode and previous near-fullscreen frame behavior.
 ### Editor Behavior
 - Use a lightweight markdown editor configuration to reduce startup and UI complexity.
 - Keep upload capability aligned with existing article editor upload flow.
 - Editing updates local draft only until user clicks `Save`.
 ### Save and Unsaved Protection
 - Save button triggers manual persistence.
 - Unsaved state (`isDirty`) is determined by comparing `draftContent` against `savedContent`.
 - On modal close attempt with unsaved content, show confirmation dialog:
  - Confirm: close and discard unsaved changes in current session.
  - Cancel: keep modal open.
 - On page leave/refresh/navigation with unsaved content while modal is open, trigger browser `beforeunload` confirmation.
 - After successful save, dirty state is cleared.
 ## Architecture and Components
 ### Frontend
 - Add `Quick Note` trigger in the top action area where `Write Article` is rendered.
 - Add `QuickNoteModal.vue`:
  - Modal shell, header controls, drag behavior, fullscreen toggle, close interception.
  - Unsaved-close confirmation handling.
  - Register/unregister `beforeunload` guard while open.
 - Add `QuickNoteEditor.vue`:
  - Lightweight editor wrapper.
  - Minimal toolbar and markdown input area.
  - Upload hook integration by reusing existing editor upload bridge/uploader path.
 - State model inside modal:
  - `savedContent: string`
  - `draftContent: string`
  - `isDirty: boolean` (derived)
  - `isSaving: boolean`
  - `isLoading: boolean`
 ### Backend
 - Introduce persistent user-unique quick note record.
 - Data model (`quick_notes` or project-consistent naming):
  - `id`
  - `user_id` (unique index)
  - `content` (text)
  - `created_at`
  - `updated_at`
 - Add API endpoints:
  - `GET /api/me/quick-note`
    - Returns current user's note content.
    - Returns empty content if no record exists.
  - `PUT /api/me/quick-note`
    - Accepts `content`.
    - Performs upsert by `user_id`.
    - Returns saved content and timestamps.
 ## Data and Validation Rules
 - Endpoint access requires authenticated `me` context.
 - Content must be string.
 - Enforce max content length (proposed: 200,000 chars) to prevent abuse and oversized payloads.
 - Normalize line endings server-side to keep storage consistent.
 ## Error Handling
 - Load failure: show inline load error with retry option.
 - Save failure: keep `draftContent` untouched, preserve dirty state, and show save error toast/message.
 - Concurrent upsert conflicts (rare): service layer retries update path once after conflict.
 ## Testing Strategy
 ### Frontend Unit Tests
 - `QuickNoteModal` open/close, fullscreen toggle, drag enable/disable switching.
 - Dirty-state derived behavior for save success/failure.
 - Close interception when dirty.
 - `beforeunload` guard registration lifecycle and dirty-condition trigger.
 - `QuickNoteEditor` upload insertion path and save event behavior.
 ### Backend Unit Tests
 - `GET /api/me/quick-note` with existing note.
 - `GET /api/me/quick-note` with no existing note.
 - `PUT /api/me/quick-note` create path and update path.
 - Validation rejection for non-string or oversized payload.
 - Auth rejection for unauthenticated access.
 ### Manual Acceptance
 - Quick Note button opens modal in near-fullscreen.
 - Fullscreen/exit button works as expected.
 - Draggable behavior works only outside fullscreen.
 - Unsaved close prompt appears on close attempts.
 - Browser leave prompt appears on refresh/navigate with unsaved changes.
 - Save persists content; reopening shows latest saved state.
 - Upload works in quick note editor and follows existing media behavior.
 ## Rollout and Compatibility
 - Feature can ship without affecting existing article editor behavior.
 - No migration impact on posts data.
 - New quick note storage is isolated to authenticated user scope.
 ## Open Decisions (Resolved)
 - Uniqueness scope: per authenticated user.
 - Save strategy: manual only.
 - Unsaved reminders: modal close + page leave.
 - Default view: near-fullscreen.
 - Fullscreen trigger: top-right toggle button.
 - Editor approach: lightweight editor with upload retained.