# ⚡ Open Kanban (Nuxt 4 版)

一个完全本地可用、隐私安全、支持导入/导出的 **现代离线看板应用**。
基于 **Nuxt 4 + TailwindCSS + Pinia** 构建，默认使用浏览器 **LocalStorage** 持久化数据，
无需服务端、无需账号，直接运行即可使用。💥

---

## ✨ 功能特性

- 🧠 **纯前端离线运行**
  无需安装后端服务，开箱即用。
  所有数据均保存在浏览器 LocalStorage，可导出 JSON 备份。

- 💾 **本地永久保存**
  自动将看板写入 LocalStorage（`public.localStorageKey`），
  支持手动保存、导出、导入与清空。

- 🔄 **导入 / 导出 / 合并预览**
  支持将 JSON 文件导入并进行差异对比：

  - 检测任务、阶段、布局变化
  - 支持“偏向导入”与“偏向当前”两种合并策略
  - 可选“同步删除导入文件中缺失的项”保持严格一致

- 🧱 **任务与阶段管理**

  - 任务增删改查：标题、描述、类别、步骤（含勾选完成）
  - 阶段可重命名、移动、删除
  - 类别带颜色标识，引用保护机制防止误删

- 🧲 **拖拽排序**
  阶段内与跨阶段拖动任务，自动更新数据结构。

- 🔍 **搜索与筛选**
  支持关键词搜索（标题 / 描述）与按类别筛选。

- 🧩 **可配置品牌与行为**
  自定义应用标题、默认导出文件名、自动加载的示例文件等。

---

## 🚀 使用方式

### 1️⃣ 开发环境运行

```bash
# 安装依赖
npm i

# 启动开发模式
npm run dev
```

浏览器打开输出地址（通常为）：

```
http://localhost:3000
```

### 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 — 自主掌控你的工作流。** ⚡🔥