feat: 个人轻量看板工具 MVP

从零实现一个 local-first 的个人任务看板，数据只存在浏览器本地，不依赖后端。功能 - 固定三列看板（待办 / 进行中 / 已完成），支持拖拽改状态与列内排序 - 快速新增、详情编辑、删除撤销、已完成归档 - 搜索与筛选（关键词 / 优先级 / 标签 / 今日到期 / 逾期） - 今日视图：按紧急度分组（逾期 > 今天到期 > 进行中）+ 统计卡片 - 导出导入 JSON；启动时自动留快照，保留最近 3 份 - 键盘快捷键（N / 「/」/ ? / Esc） - PWA：可安装、离线可用、更新提示技术要点 - 持久化采用 TaskRepository 端口 + 整份快照读写，schemaVersion 迁移表显式登记升级规则（当前 v2，v1 -> v2 为归档功能补 archivedAt） - 同列排序用相邻中点插入，间距不足时按列 normalize，避免浮点精度耗尽 - 拖拽只消费 Sortable 的事件，store 保持唯一数据源，不接管数据 - 数据损坏时先备份到 *.corrupt.<时间戳> 再报错，不覆盖用户数据 - 引入 vue-router 拆分看板与今日两个视图（见 docs/adr.md ADR-005）验证 - 单元测试 437 个（33 个文件），行覆盖率 96.8% - 端到端测试 23 个（Playwright），含真实拖拽与断网离线场景 - npm run build 通过，产物可静态托管注：部署时需配置 SPA 回落，否则直接访问 /today 会 404（详见 README）。
2026-10-18 11:59:49 +08:00
commit 4e064e82ea
98 changed files with 20084 additions and 0 deletions
@@ -0,0 +1,91 @@
+import { writeFile } from 'node:fs/promises'
+
+import { expect, test } from '@playwright/test'
+
+import { addTask, openBackupPanel } from './helpers'
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/')
+})
+
+test('导出 → 清空 → 导入，数据完全还原', async ({ page }, testInfo) => {
+  await addTask(page, '备份任务甲')
+  await addTask(page, '备份任务乙')
+  await expect(page.locator('article')).toHaveCount(2)
+
+  // 导出
+  await openBackupPanel(page)
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.getByRole('button', { name: '导出为 JSON' }).click(),
+  ])
+
+  expect(download.suggestedFilename()).toMatch(/^kanban-\d{4}-\d{2}-\d{2}\.json$/)
+  const exported = testInfo.outputPath('export.json')
+  await download.saveAs(exported)
+
+  // 模拟数据丢失
+  await page.evaluate(() => localStorage.removeItem('kanban.tasks'))
+  await page.reload()
+  await expect(page.locator('article')).toHaveCount(0)
+
+  // 导入
+  await openBackupPanel(page)
+  await page.setInputFiles('input[type="file"]', exported)
+  await expect(page.getByText('覆盖当前全部 0 个任务')).toBeVisible()
+  await page.getByRole('button', { name: '确认覆盖导入' }).click()
+
+  await expect(page.locator('article')).toHaveCount(2)
+  await expect(page.locator('article').filter({ hasText: '备份任务甲' })).toBeVisible()
+  await expect(page.locator('article').filter({ hasText: '备份任务乙' })).toBeVisible()
+
+  await page.reload()
+  await expect(page.locator('article')).toHaveCount(2)
+})
+
+test('导入非法文件时给出错误且不破坏现有数据', async ({ page }, testInfo) => {
+  await addTask(page, '不能丢的任务')
+
+  const brokenFile = testInfo.outputPath('broken.json')
+  await writeFile(brokenFile, '{ this is not json', 'utf8')
+
+  await openBackupPanel(page)
+  await page.setInputFiles('input[type="file"]', brokenFile)
+
+  await expect(page.getByText('不是合法的 JSON')).toBeVisible()
+  await expect(page.locator('article')).toHaveCount(1)
+  await expect(page.locator('article').filter({ hasText: '不能丢的任务' })).toBeVisible()
+})
+
+test('导入结构不合法时同样拒绝并保留现有数据', async ({ page }, testInfo) => {
+  await addTask(page, '保留我')
+
+  const badShape = testInfo.outputPath('bad-shape.json')
+  await writeFile(badShape, JSON.stringify({ tasks: [{ id: 'broken' }] }), 'utf8')
+
+  await openBackupPanel(page)
+  await page.setInputFiles('input[type="file"]', badShape)
+
+  await expect(page.getByText('第 1 条任务格式不合法')).toBeVisible()
+  await expect(page.getByRole('button', { name: '确认覆盖导入' })).toHaveCount(0)
+  await expect(page.locator('article')).toHaveCount(1)
+})
+
+test('自动备份列表可恢复数据', async ({ page }) => {
+  await addTask(page, '会被快照记录的任务')
+
+  // 重新打开看板会写入一份启动快照
+  await page.reload()
+  await expect(page.locator('article')).toHaveCount(1)
+
+  // 清空数据后，用启动快照恢复
+  await page.evaluate(() => localStorage.removeItem('kanban.tasks'))
+  await page.reload()
+  await expect(page.locator('article')).toHaveCount(0)
+
+  await openBackupPanel(page)
+  await page.getByRole('button', { name: '恢复' }).first().click()
+
+  await expect(page.getByText(/已从备份恢复 \d+ 个任务/)).toBeVisible()
+  await expect(page.locator('article').filter({ hasText: '会被快照记录的任务' })).toBeVisible()
+})
@@ -0,0 +1,115 @@
+import { expect, test } from '@playwright/test'
+
+import { addTask, dragCardToColumn } from './helpers'
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/')
+})
+
+test('每个用例使用独立上下文，初始看板为空', async ({ page }) => {
+  await expect(page.getByText('共 0 个任务')).toBeVisible()
+  await expect(page.locator('article')).toHaveCount(0)
+  await expect(page.getByText('暂无任务')).toHaveCount(3)
+})
+
+test('新增 → 拖到进行中 → 标记完成 → 刷新后状态仍正确', async ({ page }) => {
+  await addTask(page, 'E2E 主链路任务')
+  await expect(page.locator('[data-column-id="todo"] article')).toHaveCount(1)
+
+  await dragCardToColumn(page, 'E2E 主链路任务', 'doing')
+  await expect(page.locator('[data-column-id="doing"] article')).toHaveCount(1)
+  await expect(page.locator('[data-column-id="todo"] article')).toHaveCount(0)
+
+  // 刷新后位置保持 —— 这一条是「拖拽结果真的落盘了」的关键证据
+  await page.reload()
+  await expect(
+    page.locator('[data-column-id="doing"] article').filter({ hasText: 'E2E 主链路任务' }),
+  ).toBeVisible()
+
+  // 标记完成
+  await page
+    .locator('[data-column-id="doing"] article')
+    .filter({ hasText: 'E2E 主链路任务' })
+    .locator('button')
+    .first()
+    .click()
+  await expect(page.locator('[data-column-id="done"] article')).toHaveCount(1)
+
+  await page.reload()
+  await expect(
+    page.locator('[data-column-id="done"] article').filter({ hasText: 'E2E 主链路任务' }),
+  ).toBeVisible()
+})
+
+test('详情抽屉可编辑并持久化', async ({ page }) => {
+  await addTask(page, '待编辑任务')
+
+  await page.locator('article').filter({ hasText: '待编辑任务' }).click()
+  const titleInput = page.getByLabel('标题')
+  await expect(titleInput).toHaveValue('待编辑任务')
+
+  await titleInput.fill('已编辑任务')
+  await page.getByLabel('描述').fill('这是描述')
+  // 工具栏也有「高」按钮，必须限定在详情抽屉内
+  await page.getByRole('dialog').getByRole('button', { name: '高' }).click()
+  await page.getByRole('button', { name: '保存' }).click()
+
+  await expect(page.locator('article').filter({ hasText: '已编辑任务' })).toBeVisible()
+
+  await page.reload()
+  const card = page.locator('article').filter({ hasText: '已编辑任务' })
+  await expect(card).toBeVisible()
+  await expect(card).toContainText('高')
+})
+
+test('删除后可撤销', async ({ page }) => {
+  await addTask(page, '待删除任务')
+  await page.locator('article').filter({ hasText: '待删除任务' }).click()
+  await page.getByRole('button', { name: '删除' }).click()
+
+  await expect(page.locator('article')).toHaveCount(0)
+
+  await page.getByRole('button', { name: '撤销' }).click()
+  await expect(page.locator('article').filter({ hasText: '待删除任务' })).toBeVisible()
+
+  await page.reload()
+  await expect(page.locator('article').filter({ hasText: '待删除任务' })).toBeVisible()
+})
+
+test('搜索筛选后列计数同步变化', async ({ page }) => {
+  await addTask(page, '写方案')
+  await addTask(page, '买咖啡')
+
+  await expect(page.locator('article')).toHaveCount(2)
+
+  await page.getByLabel('搜索任务').fill('方案')
+  // 关键词有 200ms 防抖
+  await expect(page.locator('article')).toHaveCount(1)
+  await expect(page.locator('article').filter({ hasText: '写方案' })).toBeVisible()
+  await expect(page.locator('section').first().locator('header span')).toHaveText('1')
+})
+
+test('键盘快捷键：/ 聚焦搜索，N 聚焦新增，? 打开帮助', async ({ page }) => {
+  await page.keyboard.press('/')
+  await expect(page.getByLabel('搜索任务')).toBeFocused()
+
+  await page.keyboard.press('Escape')
+  await page.locator('body').click({ position: { x: 5, y: 5 } })
+
+  await page.keyboard.press('n')
+  await expect(page.getByLabel('添加任务').first()).toBeFocused()
+
+  await page.locator('body').click({ position: { x: 5, y: 5 } })
+  await page.keyboard.press('?')
+  await expect(page.getByText('聚焦「待办」列的快速新增输入框')).toBeVisible()
+})
+
+test('输入框内输入不会触发快捷键', async ({ page }) => {
+  const search = page.getByLabel('搜索任务')
+  await search.click()
+  await search.type('n')
+
+  // 焦点应仍在搜索框，而不是跳到新增输入框
+  await expect(search).toBeFocused()
+  await expect(search).toHaveValue('n')
+})
@@ -0,0 +1,43 @@
+import type { Page } from '@playwright/test'
+
+/** 在「待办」列的快速新增输入框里录入一条任务 */
+export async function addTask(page: Page, title: string): Promise<void> {
+  const input = page.getByLabel('添加任务').first()
+  await input.fill(title)
+  await input.press('Enter')
+}
+
+/**
+ * 把指定标题的卡片拖到目标列。
+ *
+ * SortableJS 用的是 pointer/mouse 事件而不是 HTML5 拖放，
+ * 且依赖拖动过程中的 pointermove 来判定落点，因此必须分步移动鼠标，
+ * 不能只做一次「按下 → 移动 → 抬起」。
+ */
+export async function dragCardToColumn(
+  page: Page,
+  title: string,
+  columnId: string,
+): Promise<void> {
+  const card = page.locator('article').filter({ hasText: title }).first()
+  const target = page.locator(`[data-column-id="${columnId}"]`)
+
+  const sourceBox = await card.boundingBox()
+  const targetBox = await target.boundingBox()
+  if (!sourceBox || !targetBox) throw new Error('无法定位拖拽源或目标元素')
+
+  const startX = sourceBox.x + sourceBox.width / 2
+  const startY = sourceBox.y + sourceBox.height / 2
+
+  await page.mouse.move(startX, startY)
+  await page.mouse.down()
+  // 先小幅移动，让 Sortable 进入拖拽状态
+  await page.mouse.move(startX, startY + 12, { steps: 5 })
+  await page.mouse.move(targetBox.x + targetBox.width / 2, targetBox.y + 30, { steps: 20 })
+  await page.mouse.up()
+}
+
+/** 打开「备份与恢复」面板 */
+export async function openBackupPanel(page: Page): Promise<void> {
+  await page.getByRole('button', { name: '备份' }).click()
+}
@@ -0,0 +1,122 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * PWA 端到端验证。
+ *
+ * 这些用例跑在 preview（生产构建）上，因为 Service Worker 只在构建产物中生成。
+ * 每个用例拥有独立的浏览器上下文，因此 Service Worker 也是各自安装的。
+ */
+
+/** 等待 Service Worker 激活并接管当前页面 */
+async function waitForServiceWorker(page: import('@playwright/test').Page): Promise<void> {
+  await page.waitForFunction(
+    async () => {
+      const registration = await navigator.serviceWorker.ready
+      return registration.active?.state === 'activated' && navigator.serviceWorker.controller !== null
+    },
+    undefined,
+    { timeout: 30_000 },
+  )
+}
+
+test('manifest 被链接且包含安装所需字段', async ({ page, request }) => {
+  await page.goto('/')
+
+  await expect(page.locator('link[rel="manifest"]')).toHaveAttribute('href', '/manifest.webmanifest')
+
+  const response = await request.get('/manifest.webmanifest')
+  expect(response.status()).toBe(200)
+
+  const manifest = (await response.json()) as {
+    name: string
+    short_name: string
+    start_url: string
+    display: string
+    theme_color: string
+    icons: Array<{ sizes: string; purpose?: string }>
+    shortcuts?: Array<{ url: string }>
+  }
+
+  expect(manifest.name).toBe('看板 · 个人任务管理')
+  expect(manifest.display).toBe('standalone')
+  expect(manifest.start_url).toBe('/')
+  expect(manifest.theme_color).toBe('#0284c7')
+
+  const sizes = manifest.icons.map((icon) => icon.sizes)
+  expect(sizes).toContain('192x192')
+  expect(sizes).toContain('512x512')
+  expect(manifest.icons.some((icon) => icon.purpose === 'maskable')).toBe(true)
+
+  // PWA 快捷方式指向今日视图
+  expect(manifest.shortcuts?.some((shortcut) => shortcut.url === '/today')).toBe(true)
+})
+
+test('图标资源均可访问', async ({ request }) => {
+  const icons = [
+    '/pwa-192x192.png',
+    '/pwa-512x512.png',
+    '/maskable-512x512.png',
+    '/apple-touch-icon.png',
+    '/favicon.svg',
+  ]
+
+  for (const path of icons) {
+    const response = await request.get(path)
+    expect(response.status(), `${path} 应可访问`).toBe(200)
+  }
+})
+
+test('Service Worker 注册并激活', async ({ page }) => {
+  await page.goto('/')
+  await waitForServiceWorker(page)
+
+  const state = await page.evaluate(async () => {
+    const registration = await navigator.serviceWorker.ready
+    return registration.active?.state ?? null
+  })
+
+  expect(state).toBe('activated')
+})
+
+test('离线后仍可打开看板，且本地数据完好', async ({ page, context }) => {
+  await page.goto('/')
+  await waitForServiceWorker(page)
+
+  const input = page.getByLabel('添加任务').first()
+  await input.fill('离线也要看到我')
+  await input.press('Enter')
+  await expect(page.locator('article')).toHaveCount(1)
+
+  // 断网后刷新：页面与数据都必须还在
+  await context.setOffline(true)
+  await page.reload()
+
+  await expect(page.getByText('共 1 个任务')).toBeVisible()
+  await expect(page.locator('article').filter({ hasText: '离线也要看到我' })).toBeVisible()
+
+  // 恢复网络，避免影响后续用例
+  await context.setOffline(false)
+})
+
+test('离线时深链 /today 也能打开（navigateFallback 生效）', async ({ page, context }) => {
+  await page.goto('/')
+  await waitForServiceWorker(page)
+
+  await context.setOffline(true)
+  await page.goto('/today')
+
+  await expect(page.getByRole('heading', { name: '今日' })).toBeVisible()
+  await expect(page.getByText('今日待办')).toBeVisible()
+
+  await context.setOffline(false)
+})
+
+test('静态资源被预缓存（sw.js 含 precache 清单）', async ({ request }) => {
+  const response = await request.get('/sw.js')
+  expect(response.status()).toBe(200)
+
+  const source = await response.text()
+  // workbox 生成的是压缩过的清单，这里只确认关键资源确实进了预缓存
+  expect(source).toContain('index.html')
+  expect(source).toContain('manifest.webmanifest')
+})
@@ -0,0 +1,97 @@
+import { expect, test } from '@playwright/test'
+
+import { addTask, dragCardToColumn } from './helpers'
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/')
+})
+
+/** 取浏览器本地的今天日期（不能用 toISOString，那是 UTC，可能差一天） */
+async function localToday(page: import('@playwright/test').Page): Promise<string> {
+  return page.evaluate(() => {
+    const now = new Date()
+    const month = String(now.getMonth() + 1).padStart(2, '0')
+    const day = String(now.getDate()).padStart(2, '0')
+    return `${now.getFullYear()}-${month}-${day}`
+  })
+}
+
+/** 新建任务并把截止日期设为今天 */
+async function addTaskDueToday(
+  page: import('@playwright/test').Page,
+  title: string,
+): Promise<void> {
+  const today = await localToday(page)
+  await addTask(page, title)
+  await page.locator('article').filter({ hasText: title }).click()
+  await page.getByLabel('截止日期').fill(today)
+  await page.getByRole('button', { name: '保存' }).click()
+  await expect(page.locator('article').filter({ hasText: title })).toBeVisible()
+}
+
+test('导航可在看板与今日之间切换', async ({ page }) => {
+  await expect(page.getByText('共 0 个任务')).toBeVisible()
+
+  await page.getByRole('link', { name: '今日' }).click()
+  await expect(page.getByRole('heading', { name: '今日' })).toBeVisible()
+  await expect(page.getByText('今日待办')).toBeVisible()
+
+  await page.getByRole('link', { name: '看板' }).click()
+  await expect(page.getByText('共 0 个任务')).toBeVisible()
+})
+
+test('今日视图汇总今天到期与进行中的任务', async ({ page }) => {
+  await addTaskDueToday(page, '今天到期的事')
+  await addTask(page, '正在做的事')
+  await dragCardToColumn(page, '正在做的事', 'doing')
+
+  await page.getByRole('link', { name: '今日' }).click()
+
+  // 两张卡片都在今日视图里
+  await expect(page.locator('article')).toHaveCount(2)
+  await expect(page.locator('article').filter({ hasText: '今天到期的事' })).toBeVisible()
+  await expect(page.locator('article').filter({ hasText: '正在做的事' })).toBeVisible()
+
+  // 分别落在「今天到期」和「进行中」两组。
+  // 必须限定 level: 2 —— 卡片标题是 h3，任务名恰好叫「今天到期的事」时会撞上分组标题
+  await expect(page.getByRole('heading', { level: 2, name: /今天到期/ })).toBeVisible()
+  await expect(page.getByRole('heading', { level: 2, name: /进行中/ })).toBeVisible()
+})
+
+test('未开始且无截止日期的任务不进入今日视图', async ({ page }) => {
+  await addTask(page, '以后再说')
+
+  await page.getByRole('link', { name: '今日' }).click()
+
+  await expect(page.locator('article')).toHaveCount(0)
+  await expect(page.getByText('今天没有待办事项')).toBeVisible()
+})
+
+test('今日视图可以勾选完成', async ({ page }) => {
+  await addTaskDueToday(page, '今天要做完')
+
+  await page.getByRole('link', { name: '今日' }).click()
+  await expect(page.locator('article')).toHaveCount(1)
+
+  await page.locator('article button').first().click()
+
+  await expect(page.locator('article')).toHaveCount(0)
+  await expect(page.getByText('今天没有待办事项')).toBeVisible()
+
+  await page.reload()
+  await expect(page.getByText('今天没有待办事项')).toBeVisible()
+})
+
+test('今日视图与看板共享同一份数据', async ({ page }) => {
+  await addTask(page, '共享的任务')
+
+  await page.getByRole('link', { name: '今日' }).click()
+  await page.getByRole('link', { name: '看板' }).click()
+
+  await expect(page.locator('article').filter({ hasText: '共享的任务' })).toBeVisible()
+})
+
+test('未知路径回落到看板', async ({ page }) => {
+  await page.goto('/not-a-real-page')
+  await expect(page.getByText('共 0 个任务')).toBeVisible()
+})