docs: 更新批量操作与备份恢复说明，新增 ADR-006
- README 补充批量添加/删除、导入前自动备份、归档恢复与 CI 说明 - ADR-006 记录覆盖式操作前快照、id 查重与未保存确认等决策
This commit is contained in:
chenshoulin
@@ -3,12 +3,15 @@
|
||||
一个轻量的个人看板工具：打开即用、数据存在本地、不依赖后端。
|
||||
|
||||
- 固定三列：**待办 / 进行中 / 已完成**
|
||||
- 快速新增、拖拽排序、详情编辑、删除撤销
|
||||
- 快速新增、拖拽排序、详情编辑、删除撤销；详情里可直接切换状态
|
||||
- **批量添加**：一次录入多行清单，整批共用目标列 / 优先级 / 标签 / 截止日期
|
||||
- **批量删除**：多选后整批删除，可一键撤销
|
||||
- 搜索与筛选（关键词 / 优先级 / 标签 / 今日到期 / 逾期）
|
||||
- **今日视图**：按紧急度分组汇总（逾期 / 今天到期 / 进行中 / 待办），含本周完成等统计
|
||||
- 键盘快捷键；任务卡片可用方向键换列与调序
|
||||
- **深色模式**：跟随系统 / 浅色 / 深色三态
|
||||
- 导出导入 JSON + 启动自动备份
|
||||
- 导出导入 JSON + 启动自动备份；**覆盖式导入或恢复快照前会自动留档**
|
||||
- 已完成任务可批量归档，归档任务可在详情里随时恢复
|
||||
- **可安装为 PWA，支持离线使用**
|
||||
|
||||
---
|
||||
@@ -22,36 +25,48 @@ npm run dev
|
||||
|
||||
打开终端提示的地址即可。首次进入是空看板，在任意列顶部的输入框里输入标题、回车即可创建任务。
|
||||
|
||||
## 批量添加与批量删除
|
||||
|
||||
工具栏的「批量添加」可以一次录入多条任务：清单里**一行一条**，整段粘贴即可；行首的 `-`、`*`、`1.` 这类列表符号会自动去掉，空行会被忽略。
|
||||
|
||||
这一批共用同一个目标列、优先级、标签与截止日期 —— 先统一建出来，再单独调整个别任务。
|
||||
|
||||
不打开面板也行：在任意列的快速新增输入框里**粘贴多行文本**，会按行直接拆成多条任务（插入该列列首）；单行粘贴仍是常规输入，不会被拦截。
|
||||
|
||||
要清理一批任务，点工具栏的「多选」：卡片变成可勾选的方框，点哪张选哪张，操作条上可以「全选 N 个」（只覆盖**当前筛选后可见**的任务）或「清空选择」，然后「删除 N 个」整批删掉。
|
||||
|
||||
批量添加与批量删除都会弹出带「撤销」的提示，误操作可以整批撤回（删除撤销会连原顺序一起还原）。多选期间拖拽会停用，避免顺手拖乱了顺序；筛选条件一变也会清空选择，保证「删掉的都是眼前看得见的」。
|
||||
|
||||
## 脚本
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---|---|
|
||||
| `npm run dev` | 启动开发服务器 |
|
||||
| `npm run build` | 类型检查 + 生产构建，产物在 `dist/` |
|
||||
| `npm run preview` | 本地预览生产构建 |
|
||||
| `npm run typecheck` | 只做类型检查 |
|
||||
| `npm run test` | 单元测试（Vitest） |
|
||||
| `npm run test:coverage` | 单元测试 + 覆盖率报告 |
|
||||
| `npm run test:e2e` | 端到端测试（Playwright，默认驱动系统已安装的 Chrome） |
|
||||
| `node scripts/screenshot.mjs` | 生成界面截图（需先起 dev server），产物在 `.screenshots/` |
|
||||
| `npm run lint` / `npm run format` | 代码检查与格式化 |
|
||||
| 命令 | 说明 |
|
||||
| --------------------------------- | --------------------------------------------------------- |
|
||||
| `npm run dev` | 启动开发服务器 |
|
||||
| `npm run build` | 类型检查 + 生产构建，产物在 `dist/` |
|
||||
| `npm run preview` | 本地预览生产构建 |
|
||||
| `npm run typecheck` | 只做类型检查 |
|
||||
| `npm run test` | 单元测试（Vitest） |
|
||||
| `npm run test:coverage` | 单元测试 + 覆盖率报告 |
|
||||
| `npm run test:e2e` | 端到端测试（Playwright，默认驱动系统已安装的 Chrome） |
|
||||
| `node scripts/screenshot.mjs` | 生成界面截图（需先起 dev server），产物在 `.screenshots/` |
|
||||
| `npm run lint` / `npm run format` | 代码检查与格式化 |
|
||||
|
||||
## 快捷键
|
||||
|
||||
| 按键 | 作用 |
|
||||
|---|---|
|
||||
| `N` | 聚焦「待办」列的快速新增输入框 |
|
||||
| `/` | 聚焦搜索框 |
|
||||
| `?` | 打开快捷键帮助 |
|
||||
| `Esc` | 关闭当前面板 |
|
||||
| 按键 | 作用 |
|
||||
| ----- | ------------------------------ |
|
||||
| `N` | 聚焦「待办」列的快速新增输入框 |
|
||||
| `/` | 聚焦搜索框 |
|
||||
| `?` | 打开快捷键帮助 |
|
||||
| `Esc` | 关闭当前面板 |
|
||||
|
||||
卡片获得焦点（`Tab` 或点击）后：
|
||||
|
||||
| 按键 | 作用 |
|
||||
|---|---|
|
||||
| 按键 | 作用 |
|
||||
| ------- | ------------------------- |
|
||||
| `←` `→` | 把卡片移到上一列 / 下一列 |
|
||||
| `↑` `↓` | 在列内上移 / 下移 |
|
||||
| `Enter` | 打开任务详情 |
|
||||
| `↑` `↓` | 在列内上移 / 下移 |
|
||||
| `Enter` | 打开任务详情 |
|
||||
|
||||
在输入框内输入时不会触发全局快捷键。方向键移动在筛选态下只允许跨列（列内排序需要看到完整列表才有意义）。
|
||||
|
||||
@@ -61,9 +76,9 @@ npm run dev
|
||||
|
||||
顶部导航可在两个视图之间切换：
|
||||
|
||||
| 视图 | 路径 | 组织方式 |
|
||||
|---|---|---|
|
||||
| 看板 | `/` | 按**状态**：待办 / 进行中 / 已完成 |
|
||||
| 视图 | 路径 | 组织方式 |
|
||||
| ---- | -------- | ----------------------------------------------- |
|
||||
| 看板 | `/` | 按**状态**：待办 / 进行中 / 已完成 |
|
||||
| 今日 | `/today` | 按**紧急度**：已逾期 → 今天到期 → 进行中 → 待办 |
|
||||
|
||||
今日视图顶部有四张统计卡片（逾期 / 今天到期 / 进行中 / 本周完成），下方是可直接勾选完成的待办列表。
|
||||
@@ -103,12 +118,15 @@ python scripts/generate-icons.py
|
||||
- 换浏览器或换设备
|
||||
- Safari 的 7 天未访问存储清理策略
|
||||
|
||||
因此工具内置了两道保护：
|
||||
因此工具内置了三道保护：
|
||||
|
||||
1. **启动自动备份**：每次打开看板时留一份快照，最多保留最近 3 份，可在「备份」面板中一键恢复。
|
||||
2. **手动导出**：「备份」面板 → 导出为 JSON，文件名形如 `kanban-2026-10-18.json`。
|
||||
2. **覆盖前自动留档**：导入 JSON 或从快照恢复会整份替换数据，执行前会先把当前数据写一份快照，选错文件或选错备份也能退回去。
|
||||
3. **手动导出**：「备份」面板 → 导出为 JSON，文件名形如 `kanban-2026-10-18.json`。
|
||||
|
||||
导入是**覆盖式**的：选中文件后会先校验，再显示将被覆盖的任务数量，需要二次确认才会执行。文件不合法时不会改动任何现有数据。
|
||||
导入是**覆盖式**的：选中文件后会先校验，再显示将被覆盖的任务数量，需要二次确认才会执行。确认覆盖前会自动备份当前数据；文件不合法时不会改动任何现有数据。
|
||||
|
||||
任务详情里的「状态」可以直接切换待办 / 进行中 / 已完成，不必回到看板拖拽。编辑后如果没保存就关闭，抽屉会先提醒，不会静默丢弃草稿。
|
||||
|
||||
> 如果需要在多设备间同步，需要自行接入后端；`TaskRepository` 接口就是为此预留的扩展点（见下）。
|
||||
|
||||
@@ -174,8 +192,15 @@ docs/
|
||||
└── tasks.json # 可导入看板的种子数据
|
||||
e2e/ # Playwright 端到端测试
|
||||
scripts/ # 图标生成等辅助脚本
|
||||
.gitea/workflows/ # CI（lint / typecheck / test / build）
|
||||
```
|
||||
|
||||
## 持续集成
|
||||
|
||||
仓库内置 `.gitea/workflows/ci.yml`：推送与合并请求会依次执行 `npm run lint`、`npm run typecheck`、`npm run test`、`npm run build`。
|
||||
|
||||
E2E 需要真实浏览器，默认不放进 CI（要求 runner 预装 Chrome）；请在本地或用带浏览器的 runner 执行 `npm run test:e2e`。
|
||||
|
||||
## 架构要点
|
||||
|
||||
- **单一数据源**：Pinia store 是内存态的唯一来源，所有变更经由 `TaskRepository` 落盘；拖拽也只消费事件，不接管数据。看板与今日视图共享同一份数据。
|
||||
@@ -188,8 +213,8 @@ scripts/ # 图标生成等辅助脚本
|
||||
|
||||
## 测试
|
||||
|
||||
- 单元测试：480 个用例，覆盖 `src/` 下的纯逻辑与组件行为，行覆盖率约 96%。
|
||||
- 端到端测试：25 个用例，分两组运行 —— 交互类跑 dev server，PWA 类跑生产构建（Service Worker 只在构建产物中生成）。覆盖「新增 → 拖拽 → 完成 → 刷新保持」「导出 → 清空 → 导入还原」「删除撤销」「搜索筛选」「键盘快捷键与方向键移动」「深色模式切换」「今日视图」「离线打开」等主链路，每个用例使用独立的浏览器上下文。
|
||||
- 单元测试：605 个用例，覆盖 `src/` 下的纯逻辑与组件行为，行覆盖率约 96%。
|
||||
- 端到端测试：28 个用例，分两组运行 —— 交互类跑 dev server，PWA 类跑生产构建（Service Worker 只在构建产物中生成）。覆盖「新增 → 拖拽 → 完成 → 刷新保持」「批量添加」「多选批量删除 + 撤销」「导出 → 清空 → 导入还原」「删除撤销」「搜索筛选」「键盘快捷键与方向键移动」「深色模式切换」「今日视图」「离线打开」等主链路，每个用例使用独立的浏览器上下文。
|
||||
|
||||
```bash
|
||||
npm run test:coverage
|
||||
@@ -216,3 +241,4 @@ PLAYWRIGHT_CHANNEL=chromium npm run test:e2e # 用自带 Chromium（需先 npx
|
||||
- 今日视图的分组规则固定（逾期 > 今天到期 > 进行中 > 待办），不可自定义。
|
||||
- 统计只覆盖本周完成数等基础指标，没有趋势图或历史留存。
|
||||
- 深色模式只跟随系统或手动三态切换，没有按时间段自动切换。
|
||||
- 删除只提供 5 秒内的 Toast 撤销，还没有回收站；误删超过窗口后只能从自动备份里找。
|
||||
|
||||
Reference in New Issue
Block a user