initial commit

README.md

@@ -0,0 +1,99 @@
+Open Kanban
+===========
+
+一款可本地使用、可开源的离线 Kanban（看板）。
+
+- 纯前端（HTML/CSS/JS），无需安装服务端。
+- 数据保存在本机（Windows）JSON 文件中，支持导入/导出。
+- 支持拖拽移动/排序任务，编辑任务详情、步骤、类别、阶段和布局。
+- 增强协作：导入他人导出的文件时，提供差异预览与合并策略（偏向导入/偏向当前），可选同步删除缺失项。
+- 记录操作历史（meta.history），便于追踪改动来源与时间。
+
+快速开始
+--------
+
+1. 双击打开 `index.html`（推荐使用 Chrome/Edge）。
+2. 默认不会自动读取任何私有 JSON 文件，点击“打开…”手动选择，或配置 `config.json` 指定示例文件。
+3. 可直接使用仓库内的 `sample-board.json` 开始体验。
+
+提示：如需本地 HTTP 访问（可避免部分浏览器对 file:// 读取限制），可在此目录临时起一个服务，例如：
+- PowerShell: 以管理员打开 PowerShell，执行 `cd <此目录>; python -m http.server 8989`，浏览器访问 `http://localhost:8989/`。
+
+主要功能
+--------
+
+- 打开/保存
+  - “打开…”读取 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 可能失败，请手动“打开…”。
+- 阶段删除仅允许删除空阶段（避免误删任务）。如需支持“连同任务一起删除/移动到归档”，可以后续补充选项。
+
+配置与目录结构
+--------------
+
+- `index.html` 入口页面
+- `styles.css` 样式
+- `app.js` 主逻辑
+- `config.json` 应用配置（可选）：
+  - `appTitle`: 页面标题（默认 `Kanban`）
+  - `defaultFilename`: 导出默认文件名（默认 `kanban.json`）
+  - `autoLoadFile`: 启动时自动读取的文件（默认空，不自动读取）
+- `sample-board.json` 示例数据（通用，未包含任何公司/隐私信息）
+- `.gitignore` 已默认忽略常见私有文件名（如 `*.private.json`、`*.local.json` 等），避免误提交
+
+欢迎提出改进需求，我可以继续完善比如：按人分配、任务评论、每列 WIP 限制、标签、多选批量操作、导出增量补丁等。
+
+隐私与开源建议
+--------------
+
+- 默认不会自动读取任何私有数据。
+- 如需在本地使用私有数据，请将你的私有文件（例如 `tasks.private.json`）保留在本地且不提交到仓库；可将该文件名加入 `.gitignore`。
+- 如需自动加载示例或指定文件，请在 `config.json` 中设置 `autoLoadFile`（建议指向 `sample-board.json`）。
+- 若需更换品牌/标题，请在 `config.json` 中修改 `appTitle`；代码与 UI 默认不显示任何公司名称。