kenaz 0.3.17 → 0.3.19

package/core/.collaboration/docs/ARCHITECTURE.md

@@ -1,596 +0,0 @@
-# .collaboration 系統架構設計文檔
-
-## 目錄
-
-1. [概述](#概述)
-2. [設計目標](#設計目標)
-3. [核心架構](#核心架構)
-4. [資料模型](#資料模型)
-5. [工作流程](#工作流程)
-6. [Git 整合](#git-整合)
-7. [衝突處理](#衝突處理)
-8. [效能考量](#效能考量)
-9. [安全性](#安全性)
-10. [未來擴展](#未來擴展)
-
----
-
-## 概述
-
-`.collaboration` 是一個基於 Git 的分散式任務協作系統，專為多用戶在不同系統上透過 Git 進行任務協作而設計。系統採用**原子檔案結構 + JSONL 索引 + 時間戳鎖定**的架構，實現了無需中央伺服器的協作模式。
-
-### 核心特性
-
-- ✅ UUID 任務 ID（TASK_ + ULID）
-- ✅ 原子檔案結構（一個任務一個檔案）
-- ✅ JSONL Append-only 索引
-- ✅ 時間戳鎖定機制
-- ✅ 樂觀鎖定（版本號衝突偵測）
-- ✅ 統一 API 層（相容 Dashboard）
-- ✅ Git Hooks 自動化
-- ✅ 多用戶角色追蹤
-
----
-
-## 設計目標
-
-### 1. Git 友好性 🎯
-
-**問題**：傳統任務系統使用單一 JSON 檔案，多用戶同時編輯會產生衝突。
-
-**解決方案**：
-- **原子檔案結構**：一個任務 = 一個檔案 → 減少衝突機率
-- **JSONL 索引**：Append-only 格式 → Git 自動合併
-- **時間戳鎖定**：Append-only 鎖定檔案 → 不覆寫
-
-**效果**：
-```bash
-# 用戶 A 建立任務
-dev/tasks/db/users/zhangsan/TASK_01HQFX9K2G.json
-
-# 用戶 B 同時建立任務
-dev/tasks/db/users/lisi/TASK_01HQGN2P7K.json
-
-# Git merge：無衝突 ✅
-```
-
-### 2. 分散式協作 🌐
-
-**場景**：用戶不在同一系統，透過 Git 通訊。
-
-**解決方案**：
-- 無需中央伺服器
-- 樂觀鎖定（版本號）
-- Git 作為唯一通訊渠道
-
-**工作流程**：
-```
-用戶 A: 建立任務 → Git push → 用戶 B: Git pull → 認領任務
-```
-
-### 3. Dashboard 相容性 📊
-
-**需求**：Dashboard 依賴 `TASK_QUEUE.json` 格式。
-
-**解決方案**：
-- 統一 API 層（`task-api.js`）
-- 自動合併新舊系統
-- 輸出格式相容
-
-**API 回應**：
-```json
-{
-  "version": "2.0.0",
-  "tasks": [...],  // 相容舊格式
-  "statistics": { ... },
-  "metadata": {
-    "sources": {
-      "new": 10,
-      "old": 5,
-      "completed": 20
-    }
-  }
-}
-```
-
-### 4. 效能最佳化 ⚡
-
-**問題**：隨著任務增加，檔案掃描變慢。
-
-**解決方案**：
-- JSONL 索引（快速查詢）
-- 增量更新（不全量重建）
-- 未來：快取層
-
----
-
-## 核心架構
-
-### 系統分層
-
-```
-┌─────────────────────────────────────────────────┐
-│  CLI Layer (task-cli.js)                       │
-│  - 用戶命令介面                                   │
-└────────────────┬────────────────────────────────┘
-                 │
-┌────────────────▼────────────────────────────────┐
-│  API Layer (task-api.js)                       │
-│  - 統一查詢介面                                   │
-│  - 整合新舊系統                                   │
-│  - Dashboard 相容                                │
-└─────┬───────────────┬───────────────┬───────────┘
-      │               │               │
-┌─────▼─────┐  ┌──────▼──────┐  ┌─────▼──────────┐
-│  Index    │  │  Lock       │  │  ID Generator  │
-│  Manager  │  │  Manager    │  │                │
-└─────┬─────┘  └──────┬──────┘  └────────────────┘
-      │               │
-┌─────▼───────────────▼────────────────────────────┐
-│  Storage Layer                                   │
-│  - dev/tasks/db/ (原子檔案)                       │
-│  - dev/tasks/index/ (JSONL 索引)                 │
-│  - dev/tasks/locks/ (鎖定檔案)                    │
-└──────────────────────────────────────────────────┘
-```
-
-### 核心模組
-
-| 模組 | 檔案 | 職責 |
-|------|------|------|
-| ID Generator | `id-generator.js` | 生成 UUID (TASK_ + ULID) |
-| Task API | `task-api.js` | 統一查詢、CRUD 操作 |
-| Lock Manager | `lock-manager.js` | 任務鎖定/解鎖 |
-| Index Manager | `index-manager.js` | JSONL 索引管理 |
-| Conflict Resolver | `conflict-resolver.js` | 衝突偵測與解決 |
-| Task CLI | `task-cli.js` | 命令列介面 |
-
----
-
-## 資料模型
-
-### UUID 格式
-
-```
-TASK_01HQFX9K2G
-│    │      │
-│    │      └─ 隨機部分（4 chars, 1M+ 組合/毫秒）
-│    └─────── 時間戳部分（6 chars, ~8900 年）
-└──────────── 前綴（向下相容）
-```
-
-**編碼**: Crockford Base32（避免易混淆字元）
-**長度**: 15 字元
-**特性**: 時間排序、全域唯一
-
-### 任務檔案結構
-
-```json
-{
-  "id": "TASK_01HQFX9K2G",
-  "title": "實作登入功能",
-  "description": "建立用戶登入頁面和 API",
-  "status": "pending",
-  "priority": "P1",
-
-  "created_by": {
-    "name": "張三",
-    "git_user": "zhangsan",
-    "timestamp": "2026-02-11T10:00:00+08:00"
-  },
-
-  "assigned_to": {
-    "name": "李四",
-    "git_user": "lisi",
-    "timestamp": "2026-02-11T10:05:00+08:00"
-  },
-
-  "last_modified_by": {
-    "name": "王五",
-    "git_user": "wangwu",
-    "timestamp": "2026-02-11T10:10:00+08:00"
-  },
-
-  "collaborators": [
-    { "name": "趙六", "git_user": "zhaoliu" }
-  ],
-
-  "executed_by": null,
-
-  "_version": 1,
-  "_file_path": "dev/tasks/db/users/zhangsan/TASK_01HQFX9K2G.json"
-}
-```
-
-### JSONL 索引格式
-
-```jsonl
-{"id":"TASK_01HQFX9K2G","user":"zhangsan","ts":1707628800,"v":1}
-{"id":"TASK_01HQGN2P7K","user":"lisi","ts":1707628900,"v":1}
-{"id":"TASK_01HQFX9K2G","user":"zhangsan","ts":1707629000,"v":2}
-```
-
-**欄位說明**：
-- `id`: 任務 ID
-- `user`: 負責用戶
-- `ts`: 時間戳（Unix）
-- `v`: 版本號
-
-**特性**：
-- Append-only（只追加，不修改）
-- Git 友好（自動合併）
-- 支援去重（取最新版本）
-
-### 鎖定檔案格式
-
-```json
-{
-  "task_id": "TASK_01HQFX9K2G",
-  "locked_by": "@zhangsan",
-  "locked_at": "2026-02-11T10:00:00+08:00",
-  "expires_at": "2026-02-11T11:00:00+08:00",
-  "_version": 1
-}
-```
-
-**檔案名稱**: `{user}_{timestamp}.lock`
-**特性**:
-- Append-only（不覆寫）
-- 自動過期（1 小時）
-- 多用戶鎖定偵測
-
----
-
-## 工作流程
-
-### 1. 建立任務
-
-```bash
-# CLI 命令
-node .collaboration/cli/task-cli.js create \
-  --title "實作登入功能" \
-  --priority P1
-
-# 內部流程
-┌─────────────────────────────────────────────────┐
-│ 1. 生成 UUID (TASK_01HQFX9K2G)                  │
-│ 2. 取得 Git user 資訊                            │
-│ 3. 建立任務物件                                  │
-│ 4. 寫入 dev/tasks/db/users/{user}/TASK_*.json  │
-│ 5. 更新 JSONL 索引                               │
-│ 6. 提示 Git 操作                                 │
-└─────────────────────────────────────────────────┘
-
-# Git 操作
-git add dev/tasks/db/users/zhangsan/TASK_01HQFX9K2G.json
-git commit -m "feat: 建立任務 TASK_01HQFX9K2G"
-git push origin main
-```
-
-### 2. 認領任務
-
-```bash
-# 用戶 B pull 最新版本
-git pull origin main
-
-# 認領任務
-node .collaboration/cli/task-cli.js claim TASK_01HQFX9K2G
-
-# 內部流程
-┌─────────────────────────────────────────────────┐
-│ 1. 載入任務檔案                                  │
-│ 2. 檢查鎖定狀態                                  │
-│ 3. 更新 assigned_to 欄位                         │
-│ 4. 版本號 +1                                     │
-│ 5. 寫回任務檔案                                  │
-│ 6. 更新索引                                      │
-└─────────────────────────────────────────────────┘
-
-# Git 操作
-git add dev/tasks/db/users/zhangsan/TASK_01HQFX9K2G.json
-git commit -m "chore: 認領任務 TASK_01HQFX9K2G"
-git push origin main
-```
-
-### 3. 完成任務
-
-```bash
-node .collaboration/cli/task-cli.js complete TASK_01HQFX9K2G
-
-# 內部流程
-┌─────────────────────────────────────────────────┐
-│ 1. 載入任務檔案                                  │
-│ 2. 更新 status = "completed"                    │
-│ 3. 設定 executed_by 欄位                         │
-│ 4. 版本號 +1                                     │
-│ 5. 寫回任務檔案                                  │
-│ 6. 更新索引 (by-status/completed.jsonl)         │
-└─────────────────────────────────────────────────┘
-```
-
----
-
-## Git 整合
-
-### Git Hooks
-
-#### post-merge Hook
-
-**目的**: Git merge 後自動重建索引
-
-**位置**: `.githooks/post-merge`
-
-```bash
-#!/bin/bash
-# post-merge hook
-
-echo "Rebuilding task indexes..."
-node .collaboration/core/index-manager.js rebuild
-
-exit 0
-```
-
-**安裝**:
-```bash
-git config core.hooksPath .githooks
-```
-
-#### pre-commit Hook
-
-**目的**: 提交前檢查鎖定衝突
-
-**位置**: `.githooks/pre-commit`
-
-```bash
-#!/bin/bash
-# pre-commit hook
-
-node .collaboration/hooks/pre-commit.js
-
-exit $?
-```
-
-### Git 工作流程範例
-
-#### 場景：兩個用戶同時編輯不同任務
-
-```
-用戶 A:
-  1. git pull
-  2. 建立任務 A (TASK_01HQFX9K2G)
-  3. git push
-
-用戶 B:
-  1. git pull
-  2. 建立任務 B (TASK_01HQGN2P7K)
-  3. git push
-
-結果: ✅ 無衝突（不同檔案）
-```
-
-#### 場景：兩個用戶同時編輯同一任務
-
-```
-用戶 A:
-  1. git pull
-  2. 更新任務 (version: 1 → 2)
-  3. git push
-
-用戶 B:
-  1. git pull (稍晚)
-  2. 嘗試更新任務 (version: 1 → 2)
-  3. git push → 衝突!
-
-Git 衝突標記:
-<<<<<<< HEAD
-  "_version": 2,
-  "assigned_to": { "git_user": "zhangsan" }
-=======
-  "_version": 2,
-  "assigned_to": { "git_user": "lisi" }
->>>>>>> branch
-
-解決:
-  node .collaboration/core/conflict-resolver.js TASK_01HQFX9K2G
-  # 工具自動比較時間戳，選擇最新版本
-```
-
----
-
-## 衝突處理
-
-### 樂觀鎖定策略
-
-**原理**: 使用版本號偵測並發修改
-
-```javascript
-function detectConflict(localTask, remoteTask) {
-  if (localTask._version !== remoteTask._version) {
-    return {
-      hasConflict: true,
-      winner: localTask.last_modified_by.timestamp >
-              remoteTask.last_modified_by.timestamp ? 'local' : 'remote'
-    };
-  }
-  return { hasConflict: false };
-}
-```
-
-### 衝突解決流程
-
-```
-1. 偵測衝突（版本號不一致）
-   ↓
-2. 比較 last_modified_by.timestamp
-   ↓
-3. 選擇最新版本作為 winner
-   ↓
-4. 合併元數據（collaborators 合併）
-   ↓
-5. 版本號 = max(local, remote) + 1
-```
-
-### 鎖定機制
-
-**時間戳鎖定**：
-```
-dev/tasks/locks/TASK_01HQFX9K2G/
-├── zhangsan_1707628800.lock  (✅ 有效)
-├── lisi_1707628900.lock      (❌ 過期)
-└── wangwu_1707629000.lock    (⚠️  衝突!)
-```
-
-**檢查邏輯**：
-1. 掃描任務鎖定目錄
-2. 移除過期鎖定（> 1 小時）
-3. 檢查是否有其他用戶的活躍鎖定
-4. 如有 → 拒絕操作
-
----
-
-## 效能考量
-
-### 索引策略
-
-**問題**: 掃描所有任務檔案很慢
-
-**解決方案**: JSONL 索引
-
-```
-查詢 pending 任務:
-  1. 讀取 dev/tasks/index/by-status/pending.jsonl
-  2. 解析 JSONL（每行一個任務）
-  3. 去重（取最新版本）
-  4. 返回任務 ID 列表
-
-時間複雜度: O(n) → O(k)
-其中 k = pending 任務數量 << n = 總任務數量
-```
-
-### 增量更新
-
-**策略**: 不全量重建索引
-
-```javascript
-// 建立任務時立即更新索引
-await indexMgr.updateTask(taskId, task);
-
-// 只在 Git merge 後才全量重建
-# post-merge hook: node .collaboration/core/index-manager.js rebuild
-```
-
-### 未來優化
-
-- [ ] 快取層（記憶體快取）
-- [ ] 壓縮索引（Gzip）
-- [ ] 分片索引（按日期分片）
-
----
-
-## 安全性
-
-### Git 用戶驗證
-
-```javascript
-function _getGitUser() {
-  const name = execSync('git config user.name').trim();
-  const email = execSync('git config user.email').trim();
-  const gitUser = email.split('@')[0];
-
-  return { name, email, git_user: gitUser };
-}
-```
-
-### 權限控制
-
-**目前**: 無權限控制（信任 Git 用戶）
-**未來**: 基於角色的權限控制（RBAC）
-
-```yaml
-roles:
-  admin:
-    - create_task
-    - assign_task
-    - delete_task
-  developer:
-    - create_task
-    - claim_task
-  viewer:
-    - list_tasks
-```
-
----
-
-## 未來擴展
-
-### 短期（1-3 個月）
-
-- [ ] 衝突解決工具完整實作
-- [ ] Git Hooks 自動化
-- [ ] CLI 完整測試
-- [ ] Dashboard 深度整合
-
-### 中期（3-6 個月）
-
-- [ ] 快取層（Redis）
-- [ ] 權限控制（RBAC）
-- [ ] 任務範本系統
-- [ ] 批次操作 API
-
-### 長期（6-12 個月）
-
-- [ ] Web UI（取代 CLI）
-- [ ] 實時同步（WebSocket）
-- [ ] 分析報表（時間追蹤、效率分析）
-- [ ] 多專案支援
-
----
-
-## 附錄
-
-### A. 資料夾結構
-
-```
-dev/tasks/
-├── db/
-│   ├── users/
-│   │   ├── zhangsan/
-│   │   │   ├── TASK_01HQFX9K2G.json
-│   │   │   └── TASK_01HQGN2P7K.json
-│   │   └── lisi/
-│   │       └── TASK_01HQHN3Q8M.json
-│   └── shared/
-│       └── TASK_01HQJP4R9N.json
-├── index/
-│   ├── by-status/
-│   │   ├── pending.jsonl
-│   │   ├── in_progress.jsonl
-│   │   └── completed.jsonl
-│   ├── by-user/
-│   │   ├── zhangsan.jsonl
-│   │   └── lisi.jsonl
-│   └── by-priority/
-│       ├── P0.jsonl
-│       ├── P1.jsonl
-│       └── P2.jsonl
-└── locks/
-    ├── TASK_01HQFX9K2G/
-    │   └── zhangsan_1707628800.lock
-    └── TASK_01HQGN2P7K/
-        └── lisi_1707628900.lock
-```
-
-### B. API 參考
-
-參見 [API.md](./API.md)
-
-### C. CLI 指南
-
-參見 [CLI.md](./CLI.md)
-
----
-
-**建立日期**: 2026-02-11
-**最後更新**: 2026-02-11
-**版本**: 1.0.0
-**作者**: Lead Agent