refactor(app): rewrite application with Nuxt 4, Pinia, and TailwindCSS
This commit replaces the original vanilla JavaScript implementation with a modern frontend stack. The entire application has been rewritten to improve maintainability, developer experience, and leverage modern web technologies. Key changes include: - Replaced plain HTML, CSS, and JS with a Nuxt 4 project structure. - Migrated state management from a global state object to a Pinia store for better organization and reactivity. - Rebuilt the UI with Vue 3 components and styled with TailwindCSS. - Changed the primary persistence mechanism from manual file I/O to automatic LocalStorage saving, while retaining import/export functionality. - All core features, including drag-and-drop, task management, and the import/merge diffing logic, have been ported to the new architecture.
This commit is contained in:
xiaomai
237
README.md
237
README.md
@@ -1,99 +1,178 @@
|
||||
Open Kanban
|
||||
===========
|
||||
# ⚡ Open Kanban (Nuxt 4 版)
|
||||
|
||||
一款可本地使用、可开源的离线 Kanban（看板）。
|
||||
一个完全本地可用、隐私安全、支持导入/导出的 **现代离线看板应用**。
|
||||
基于 **Nuxt 4 + TailwindCSS + Pinia** 构建，默认使用浏览器 **LocalStorage** 持久化数据，
|
||||
无需服务端、无需账号，直接运行即可使用。💥
|
||||
|
||||
- 纯前端（HTML/CSS/JS），无需安装服务端。
|
||||
- 数据保存在本机（Windows）JSON 文件中，支持导入/导出。
|
||||
- 支持拖拽移动/排序任务，编辑任务详情、步骤、类别、阶段和布局。
|
||||
- 增强协作：导入他人导出的文件时，提供差异预览与合并策略（偏向导入/偏向当前），可选同步删除缺失项。
|
||||
- 记录操作历史（meta.history），便于追踪改动来源与时间。
|
||||
---
|
||||
|
||||
快速开始
|
||||
--------
|
||||
## ✨ 功能特性
|
||||
|
||||
1. 双击打开 `index.html`（推荐使用 Chrome/Edge）。
|
||||
2. 默认不会自动读取任何私有 JSON 文件，点击“打开…”手动选择，或配置 `config.json` 指定示例文件。
|
||||
3. 可直接使用仓库内的 `sample-board.json` 开始体验。
|
||||
- 🧠 **纯前端离线运行**
|
||||
无需安装后端服务，开箱即用。
|
||||
所有数据均保存在浏览器 LocalStorage，可导出 JSON 备份。
|
||||
|
||||
提示：如需本地 HTTP 访问（可避免部分浏览器对 file:// 读取限制），可在此目录临时起一个服务，例如：
|
||||
- PowerShell: 以管理员打开 PowerShell，执行 `cd <此目录>; python -m http.server 8989`，浏览器访问 `http://localhost:8989/`。
|
||||
- 💾 **本地永久保存**
|
||||
自动将看板写入 LocalStorage（`public.localStorageKey`），
|
||||
支持手动保存、导出、导入与清空。
|
||||
|
||||
主要功能
|
||||
--------
|
||||
- 🔄 **导入 / 导出 / 合并预览**
|
||||
支持将 JSON 文件导入并进行差异对比：
|
||||
|
||||
- 打开/保存
|
||||
- “打开…”读取 JSON 文件至内存。
|
||||
- “保存/导出”将当前看板下载为 JSON 文件（默认名取自 `config.json` 的 `defaultFilename`，默认为 `kanban.json`）。
|
||||
- 看板与拖拽
|
||||
- 根据 `layout.columns` 渲染多列，每列可包含多个阶段（stage）。
|
||||
- 支持跨阶段、阶段内排序拖放；自动更新 `stages[].tasks` 顺序。
|
||||
- 任务管理
|
||||
- 添加、编辑、删除任务；编辑标题、描述、类别与步骤（含勾选完成）。
|
||||
- 卡片上显示类别与步骤完成统计。
|
||||
- 阶段与类别
|
||||
- 添加、重命名、删除阶段（空阶段可删）；选择列位置。
|
||||
- 添加、重命名类别与颜色；正被引用的类别不可删除。
|
||||
- 搜索/筛选
|
||||
- 关键词搜索（标题/描述），按类别筛选。
|
||||
- 协作导入/合并
|
||||
- “导入/合并…”选择 JSON 后显示差异预览：任务/阶段新增、删除、修改，布局变化。
|
||||
- 合并策略：
|
||||
- 冲突优先“导入文件”：相同 ID 的任务/阶段在冲突字段上使用导入方；阶段任务顺序、布局亦以导入方为准。
|
||||
- 冲突优先“当前看板”：保持当前数据，仅补充导入方新增项。
|
||||
- 可选“同步删除在导入文件中不存在的任务/阶段”。
|
||||
- 历史记录
|
||||
- 记录操作人（右上角输入框），以及每次操作（新增、编辑、移动、合并等）。
|
||||
- 支持“清空历史（写入文件）”，以在文件内重置历史并记录一次清空事件。
|
||||
- 检测任务、阶段、布局变化
|
||||
- 支持“偏向导入”与“偏向当前”两种合并策略
|
||||
- 可选“同步删除导入文件中缺失的项”保持严格一致
|
||||
|
||||
数据结构说明（兼容扩展）
|
||||
----------------------
|
||||
- 🧱 **任务与阶段管理**
|
||||
|
||||
原始结构：
|
||||
- `categories`: `[{ uuid, title, color }]`
|
||||
- `stages`: `[{ uuid, title, tasks: [taskUuid] }]`
|
||||
- `tasks`: `[{ uuid, title, description, category, steps: [{ details, done }] }]`
|
||||
- `layout`: `{ columns: [[stageUuid, ...], ...] }`
|
||||
- 任务增删改查：标题、描述、类别、步骤（含勾选完成）
|
||||
- 阶段可重命名、移动、删除
|
||||
- 类别带颜色标识，引用保护机制防止误删
|
||||
|
||||
本应用增加可选 `meta` 字段，用于协作追踪：
|
||||
- `meta`: `{ id: 'open-kanban', version, createdAt, modifiedAt, actor, history: [{ id, ts, actor, type, payload }] }`
|
||||
- 🧲 **拖拽排序**
|
||||
阶段内与跨阶段拖动任务，自动更新数据结构。
|
||||
|
||||
未包含 `meta` 的旧文件可直接读取，保存时会补充。
|
||||
- 🔍 **搜索与筛选**
|
||||
支持关键词搜索（标题 / 描述）与按类别筛选。
|
||||
|
||||
协作建议
|
||||
--------
|
||||
- 🧩 **可配置品牌与行为**
|
||||
自定义应用标题、默认导出文件名、自动加载的示例文件等。
|
||||
|
||||
- 建议每位协作者在右上角填写自己的名字，导出前先“保存/导出”。
|
||||
- 通过“导入/合并…”接收他人文件时，先查看差异预览，再选择合并策略。
|
||||
- 需要严格控制主副本时，勾选“同步删除缺失项”，保持两侧严格一致。
|
||||
- 如需更细粒度的冲突解决（按字段逐项选择），欢迎提 Issue 我再扩展 UI 细节功能。
|
||||
---
|
||||
|
||||
已知限制与备注
|
||||
--------------
|
||||
## 🚀 使用方式
|
||||
|
||||
- 纯前端页面无法直接写入磁盘文件，需要通过“保存/导出”下载保存。
|
||||
- 若浏览器禁止 `file://` 下的 `fetch`，自动读取示例或私有 JSON 可能失败，请手动“打开…”。
|
||||
- 阶段删除仅允许删除空阶段（避免误删任务）。如需支持“连同任务一起删除/移动到归档”，可以后续补充选项。
|
||||
### 1️⃣ 开发环境运行
|
||||
|
||||
配置与目录结构
|
||||
--------------
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm i
|
||||
|
||||
- `index.html` 入口页面
|
||||
- `styles.css` 样式
|
||||
- `app.js` 主逻辑
|
||||
- `config.json` 应用配置（可选）：
|
||||
- `appTitle`: 页面标题（默认 `Kanban`）
|
||||
- `defaultFilename`: 导出默认文件名（默认 `kanban.json`）
|
||||
- `autoLoadFile`: 启动时自动读取的文件（默认空，不自动读取）
|
||||
- `sample-board.json` 示例数据（通用，未包含任何公司/隐私信息）
|
||||
- `.gitignore` 已默认忽略常见私有文件名（如 `*.private.json`、`*.local.json` 等），避免误提交
|
||||
# 启动开发模式
|
||||
npm run dev
|
||||
```
|
||||
|
||||
欢迎提出改进需求，我可以继续完善比如：按人分配、任务评论、每列 WIP 限制、标签、多选批量操作、导出增量补丁等。
|
||||
浏览器打开输出地址（通常为）：
|
||||
|
||||
隐私与开源建议
|
||||
--------------
|
||||
```
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
- 默认不会自动读取任何私有数据。
|
||||
- 如需在本地使用私有数据，请将你的私有文件（例如 `tasks.private.json`）保留在本地且不提交到仓库；可将该文件名加入 `.gitignore`。
|
||||
- 如需自动加载示例或指定文件，请在 `config.json` 中设置 `autoLoadFile`（建议指向 `sample-board.json`）。
|
||||
- 若需更换品牌/标题，请在 `config.json` 中修改 `appTitle`；代码与 UI 默认不显示任何公司名称。
|
||||
### 2️⃣ 构建与预览
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 运行配置（`nuxt.config.ts`）
|
||||
|
||||
在 `runtimeConfig.public` 中可自定义以下配置项：
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
| ----------------- | --------------------- | ---------------------------------------------------------- |
|
||||
| `appTitle` | `"Kanban"` | 页面标题 |
|
||||
| `localStorageKey` | `"open-kanban-board"` | LocalStorage 键名 |
|
||||
| `defaultFilename` | `"kanban.json"` | 导出文件名 |
|
||||
| `autoLoadFile` | `""` | 启动时自动加载的 JSON 文件路径（例：`/sample-board.json`） |
|
||||
|
||||
---
|
||||
|
||||
## 📂 项目结构
|
||||
|
||||
```
|
||||
/ # 项目根目录
|
||||
├─ app.vue # 主应用入口
|
||||
├─ pages/ # 页面目录
|
||||
├─ components/ # UI 组件
|
||||
├─ stores/ # Pinia 状态管理
|
||||
├─ public/
|
||||
│ ├─ sample-board.json # 示例数据
|
||||
│ └─ favicon.ico
|
||||
├─ nuxt.config.ts # 配置文件
|
||||
├─ package.json
|
||||
└─ README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧾 数据结构
|
||||
|
||||
应用内部数据结构遵循以下规范：
|
||||
|
||||
```json
|
||||
{
|
||||
"categories": [{ "uuid": "", "title": "", "color": "" }],
|
||||
"stages": [{ "uuid": "", "title": "", "tasks": ["taskUuid"] }],
|
||||
"tasks": [
|
||||
{
|
||||
"uuid": "",
|
||||
"title": "",
|
||||
"description": "",
|
||||
"category": "",
|
||||
"steps": [{ "details": "", "done": true }]
|
||||
}
|
||||
],
|
||||
"layout": { "columns": [["stageUuid", "stageUuid"]] },
|
||||
"meta": {
|
||||
"id": "open-kanban",
|
||||
"version": "1.0",
|
||||
"createdAt": "",
|
||||
"modifiedAt": "",
|
||||
"actor": "",
|
||||
"history": [{ "id": "", "ts": "", "actor": "", "type": "", "payload": {} }]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 隐私与数据安全
|
||||
|
||||
- 默认不读取任何私有文件或远程数据。
|
||||
- 所有数据仅保存在浏览器本地（LocalStorage）。
|
||||
- 导入的 JSON 文件仅在浏览器内解析，不会上传到任何服务器。
|
||||
- 建议用户自行导出 JSON 文件进行备份或团队共享。
|
||||
- 若需自动加载非私有数据，可在配置中设置 `autoLoadFile`。
|
||||
|
||||
---
|
||||
|
||||
## 🧑🤝🧑 协作建议
|
||||
|
||||
- 各协作者可在“操作人”输入框填写自己的名字。
|
||||
- 导出前请先保存当前版本。
|
||||
- 导入他人文件时使用合并预览选择合并策略。
|
||||
- 若需严格同步主副本，可启用“同步删除缺失项”。
|
||||
- 更复杂的冲突解决（字段级）将在未来版本支持。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 已知限制
|
||||
|
||||
- 浏览器 LocalStorage 有体积上限（约 5~10MB），如需存放大型项目请使用 JSON 导入导出。
|
||||
- 不支持直接写入磁盘文件（需通过“保存/导出”下载）。
|
||||
- 当前版本未包含多用户同步功能（未来可能支持 WebRTC / CRDT 同步模式）。
|
||||
|
||||
---
|
||||
|
||||
## 🧭 后续计划
|
||||
|
||||
- 👤 成员分配与头像标识
|
||||
- 💬 任务评论与活动时间线
|
||||
- 🏷️ 标签系统与多标签筛选
|
||||
- 🔢 每列 WIP 限制
|
||||
- 🧰 批量操作与快捷键支持
|
||||
- 📦 导出增量补丁文件
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
Open Kanban 是一个完全掌控在你手中的工具：
|
||||
无账号、无追踪、无外部依赖。
|
||||
在你的浏览器里，它就是一个本地应用。
|
||||
|
||||
**离线即自由，协作也本地。**
|
||||
**Open Kanban — 自主掌控你的工作流。** ⚡🔥
|
||||
|
||||
Reference in New Issue
Block a user