kenaz 0.3.18 → 0.3.20

package/core/.collaboration/docs/FAQ.md

@@ -1,695 +0,0 @@
-# .collaboration 常見問題 (FAQ)
-
-關於 .collaboration 分散式任務協作系統的常見問題解答。
-
-## 目錄
-
-- [基本概念](#基本概念)
-- [安裝與設置](#安裝與設置)
-- [任務管理](#任務管理)
-- [Git 工作流程](#git-工作流程)
-- [衝突處理](#衝突處理)
-- [效能與優化](#效能與優化)
-- [疑難排解](#疑難排解)
-- [最佳實踐](#最佳實踐)
-
----
-
-## 基本概念
-
-### Q: 什麼是 .collaboration 系統？
-
-**A**: `.collaboration` 是一個基於 Git 的分散式任務協作系統，特色包括：
-
-- **分散式** - 無需中央伺服器，完全基於 Git
-- **原子文件** - 每個任務一個 JSON 文件，最小化衝突
-- **UUID 任務 ID** - 全局唯一，可排序（ULID 格式）
-- **JSONL 索引** - Append-only 格式，Git 合併友好
-- **樂觀鎖定** - 版本號衝突偵測
-
----
-
-### Q: 為什麼要使用 .collaboration 而不是其他任務管理工具？
-
-**A**: 主要優勢：
-
-| 特性 | .collaboration | Jira/Trello | GitHub Issues |
-|------|---------------|-------------|---------------|
-| **離線工作** | ✅ 完全支援 | ❌ 需要網路 | ❌ 需要網路 |
-| **版本控制** | ✅ Git 原生 | ❌ 需手動 | ⚠️  有限支援 |
-| **自訂欄位** | ✅ JSON 格式 | ⚠️  受限 | ⚠️  受限 |
-| **API 存取** | ✅ 完全控制 | ⚠️  受限 | ⚠️  Rate Limit |
-| **資料所有權** | ✅ 你擁有 | ❌ 供應商 | ❌ GitHub |
-| **成本** | ✅ 免費 | 💰 付費 | ✅ 免費（有限） |
-
-**適用場景**：
-- ✅ 需要離線工作
-- ✅ 需要完全控制資料
-- ✅ 已使用 Git 進行協作
-- ✅ 需要與代碼緊密整合
-
-**不適用場景**：
-- ❌ 非技術團隊（CLI 使用困難）
-- ❌ 需要豐富的 UI 介面
-- ❌ 需要複雜的工作流程（如 Scrum/Kanban）
-
----
-
-### Q: 任務 ID 的格式是什麼？
-
-**A**: 格式為 `TASK_` + 10 字元 ULID
-
-```
-TASK_5KPEES80MMXH
-      ↑↑↑↑↑↑    ↑↑↑↑
-      時間部分  隨機部分
-      (6字元)   (4字元)
-```
-
-**特性**：
-- **時間部分**：可排序，精確到毫秒
-- **隨機部分**：確保唯一性
-- **編碼**：Crockford Base32（避免 0/O, 1/I/L 歧義）
-
-**範例**：
-```javascript
-const { generateTaskID } = require('./.collaboration/core/id-generator.js');
-
-console.log(generateTaskID());  // TASK_5KPEES80MMXH
-console.log(generateTaskID());  // TASK_5KPEES80NRTW (不同時間，不同隨機)
-```
-
----
-
-## 安裝與設置
-
-### Q: 如何在新專案中使用 .collaboration？
-
-**A**: 複製目錄結構即可：
-
-```bash
-# 1. 複製整個 .collaboration 目錄到新專案
-cp -r /path/to/template/.collaboration /path/to/new-project/
-
-# 2. 初始化 Git（如果尚未初始化）
-cd /path/to/new-project
-git init
-
-# 3. 測試是否正常
-node .collaboration/cli/task-cli.js --help
-
-# 4. 建立第一個任務
-node .collaboration/cli/task-cli.js create --title "初始化專案" --priority P1
-```
-
----
-
-### Q: 需要安裝什麼依賴？
-
-**A**: 只需要 Node.js（>= 14）
-
-```bash
-# 檢查 Node.js 版本
-node --version  # 應該 >= 14.0.0
-
-# 無需 npm install！系統使用 Node.js 內建模組：
-# - fs (檔案系統)
-# - path (路徑處理)
-# - child_process (Git 命令)
-```
-
----
-
-### Q: 如何整合到現有專案？
-
-**A**: 參考[遷移指南](./MIGRATION.md)
-
-簡要步驟：
-1. 備份現有任務資料
-2. 複製 `.collaboration/` 目錄
-3. 執行遷移腳本（可選）
-4. 驗證遷移結果
-5. 提交到 Git
-
----
-
-## 任務管理
-
-### Q: 如何建立任務？
-
-**A**: 使用 CLI 或 API
-
-**CLI 方式**：
-```bash
-node .collaboration/cli/task-cli.js create \
-  --title "實作登入功能" \
-  --description "建立登入頁面和認證 API" \
-  --priority P1
-```
-
-**API 方式**：
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-const task = await api.createTask({
-  title: '實作登入功能',
-  description: '建立登入頁面和認證 API',
-  priority: 'P1'
-});
-
-console.log(`任務已建立: ${task.id}`);
-```
-
----
-
-### Q: 如何查看我的任務？
-
-**A**: 按分配對象過濾
-
-```bash
-# 方法 1：CLI（需要知道 Git 用戶名）
-node .collaboration/cli/task-cli.js list --assigned-to $(git config user.email | cut -d@ -f1)
-
-# 方法 2：API
-const api = new TaskAPI();
-const gitUser = execSync('git config user.email').toString().trim().split('@')[0];
-const myTasks = await api.queryTasks({ assigned_to: gitUser });
-```
-
----
-
-### Q: 如何更新任務狀態？
-
-**A**: 使用 `updateTask` API
-
-```javascript
-const api = new TaskAPI();
-
-// 更新狀態
-await api.updateTask('TASK_5KPEES80MMXH', {
-  status: 'in_progress'
-});
-
-// 或使用預設方法
-await api.claimTask('TASK_5KPEES80MMXH');  // → in_progress
-await api.completeTask('TASK_5KPEES80MMXH');  // → completed
-```
-
----
-
-### Q: 任務狀態有哪些？
-
-**A**: 4 種標準狀態
-
-| 狀態 | 說明 | 轉換 |
-|------|------|------|
-| `pending` | 待執行 | 初始狀態 |
-| `in_progress` | 執行中 | 認領後 |
-| `completed` | 已完成 | 完成後 |
-| `blocked` | 已阻塞 | 遇到阻礙 |
-
-**狀態流轉**：
-```
-pending → in_progress → completed
-            ↓
-          blocked → in_progress
-```
-
----
-
-### Q: 如何設置任務優先級？
-
-**A**: 使用 P0-P3 級別
-
-| 優先級 | 說明 | SLA |
-|-------|------|-----|
-| `P0` | 緊急（Critical） | 立即處理 |
-| `P1` | 高（High） | 24 小時內 |
-| `P2` | 中（Medium） | 1 週內 |
-| `P3` | 低（Low） | 有空處理 |
-
-**範例**：
-```bash
-# 建立緊急任務
-node .collaboration/cli/task-cli.js create \
-  --title "修復線上登入問題" \
-  --priority P0
-
-# 查看所有 P0 任務
-node .collaboration/cli/task-cli.js list --priority P0
-```
-
----
-
-## Git 工作流程
-
-### Q: 何時需要提交到 Git？
-
-**A**: 每次建立或更新任務後
-
-**最佳實踐**：
-```bash
-# 1. 建立任務
-task-cli.js create --title "新功能"
-
-# 2. 立即提交
-git add .collaboration/tasks/
-git commit -m "feat: 建立任務 TASK_5KPEES80MMXH"
-git push
-
-# 3. 認領任務
-task-cli.js claim TASK_5KPEES80MMXH
-
-# 4. 再次提交
-git add .collaboration/tasks/
-git commit -m "chore: 認領任務 TASK_5KPEES80MMXH"
-git push
-```
-
-**為什麼要立即提交？**
-- ✅ 其他用戶可以看到任務
-- ✅ 避免本地丟失
-- ✅ 記錄變更歷史
-
----
-
-### Q: 如何同步其他用戶的任務？
-
-**A**: 定期 `git pull`
-
-```bash
-# 每天開始工作前
-git pull origin main
-
-# 列出所有任務（包含其他用戶建立的）
-task-cli.js list
-```
-
-**建議頻率**：
-- 每天早上 1 次
-- 認領任務前 1 次
-- 提交任務前 1 次
-
----
-
-### Q: Commit Message 有什麼建議格式？
-
-**A**: 使用 Conventional Commits
-
-```bash
-# 建立任務
-git commit -m "feat: 建立任務 TASK_5KPEES80MMXH - 實作登入功能"
-
-# 認領任務
-git commit -m "chore: 認領任務 TASK_5KPEES80MMXH"
-
-# 完成任務
-git commit -m "feat: 完成任務 TASK_5KPEES80MMXH - 實作登入功能"
-
-# 修正任務
-git commit -m "fix: 修正任務 TASK_5KPEES80MMXH 的描述"
-```
-
-**前綴規則**：
-- `feat:` - 建立新任務、完成任務
-- `chore:` - 認領、分配、狀態更新
-- `fix:` - 修正任務資料
-- `docs:` - 更新任務描述
-
----
-
-## 衝突處理
-
-### Q: 為什麼會發生 Git 衝突？
-
-**A**: 當兩個用戶同時編輯同一任務時
-
-**範例**：
-```
-用戶 A（10:00）                用戶 B（10:00）
-   ↓                              ↓
-讀取 TASK_XXX.json             讀取 TASK_XXX.json
-(_version: 1)                  (_version: 1)
-   ↓                              ↓
-修改 status → in_progress      修改 priority → P0
-   ↓                              ↓
-寫入 (_version: 2)             寫入 (_version: 2)
-   ↓                              ↓
-git commit & push ✅           git commit & push ❌
-                                  ↓
-                               衝突！
-```
-
----
-
-### Q: 如何避免衝突？
-
-**A**: 使用鎖定機制
-
-```bash
-# 1. 鎖定任務
-task-cli.js lock TASK_5KPEES80MMXH
-
-# 2. 修改任務
-# ... 執行工作 ...
-
-# 3. 完成後解鎖
-task-cli.js unlock TASK_5KPEES80MMXH
-```
-
-**自動過期**：
-- 預設鎖定 60 分鐘
-- 過期後自動釋放
-
----
-
-### Q: 如何解決已發生的衝突？
-
-**A**: 手動合併或使用版本號判斷
-
-**步驟 1：檢查衝突**
-```bash
-git pull origin main
-# CONFLICT (content): Merge conflict in .collaboration/tasks/db/all/TASK_XXX.json
-```
-
-**步驟 2：查看衝突內容**
-```bash
-cat .collaboration/tasks/db/all/TASK_5KPEES80MMXH.json
-
-# <<<<<<< HEAD
-#   "status": "in_progress",
-#   "_version": 2,
-#   "last_modified_by": { "git_user": "zhangsan", "timestamp": "2026-02-11T10:05:00Z" }
-# =======
-#   "priority": "P0",
-#   "_version": 2,
-#   "last_modified_by": { "git_user": "lisi", "timestamp": "2026-02-11T10:08:00Z" }
-# >>>>>>> origin/main
-```
-
-**步驟 3：判斷保留哪個版本**
-
-使用時間戳判斷：
-- `zhangsan`: 10:05:00
-- `lisi`: 10:08:00
-- **保留 lisi 的版本**（較新）
-
-**步驟 4：合併並遞增版本號**
-```json
-{
-  "status": "in_progress",
-  "priority": "P0",
-  "_version": 3,  // 遞增版本號
-  "last_modified_by": {
-    "git_user": "lisi",
-    "timestamp": "2026-02-11T10:08:00Z"
-  }
-}
-```
-
-**步驟 5：標記為已解決**
-```bash
-git add .collaboration/tasks/db/all/TASK_5KPEES80MMXH.json
-git commit -m "fix: 解決任務 TASK_5KPEES80MMXH 的合併衝突"
-git push
-```
-
----
-
-### Q: 未來會有自動衝突解決工具嗎？
-
-**A**: 是的！計劃中的 `conflict-resolver.js`
-
-```bash
-# 未來使用方式
-node .collaboration/core/conflict-resolver.js TASK_5KPEES80MMXH
-
-# 輸出：
-# 🔍 檢測到衝突
-# 本地版本（zhangsan, 10:05:00）: status → in_progress
-# 遠端版本（lisi, 10:08:00）: priority → P0
-#
-# 推薦操作：保留遠端版本（較新）
-# 是否自動合併？(y/n)
-```
-
----
-
-## 效能與優化
-
-### Q: 任務數量很多時會變慢嗎？
-
-**A**: 不會，已優化
-
-**原因**：
-1. **JSONL 索引** - 無需載入所有任務
-2. **扁平化存儲** - 無需遍歷目錄
-3. **按需查詢** - 只載入需要的任務
-
-**效能測試**：
-| 任務數量 | 查詢時間 | 建立時間 |
-|---------|---------|---------|
-| 100 | < 10ms | < 5ms |
-| 1,000 | < 50ms | < 5ms |
-| 10,000 | < 200ms | < 5ms |
-
----
-
-### Q: 如何加速查詢？
-
-**A**: 使用索引查詢
-
-```bash
-# ❌ 慢：載入所有任務再過濾
-const all = await api.getAllTasks();
-const pending = all.tasks.filter(t => t.status === 'pending');
-
-# ✅ 快：使用索引直接查詢
-const pending = await api.queryTasks({ status: 'pending' });
-```
-
----
-
-### Q: 索引會自動更新嗎？
-
-**A**: 會，但建議定期重建
-
-**自動更新**：
-- 建立任務時自動更新索引
-- 更新任務時自動更新索引
-
-**定期重建**（建議每週）：
-```bash
-task-cli.js rebuild
-```
-
----
-
-## 疑難排解
-
-### Q: 執行 CLI 報錯 "Cannot find module"
-
-**A**: 檢查 Node.js 版本和路徑
-
-```bash
-# 1. 檢查 Node.js 版本
-node --version  # 應該 >= 14
-
-# 2. 確認在正確的目錄
-pwd  # 應該在專案根目錄
-
-# 3. 檢查文件是否存在
-ls .collaboration/cli/task-cli.js
-ls .collaboration/core/task-api.js
-
-# 4. 嘗試完整路徑
-node "$(pwd)/.collaboration/cli/task-cli.js" --help
-```
-
----
-
-### Q: 建立任務後看不到文件
-
-**A**: 檢查權限和路徑
-
-```bash
-# 1. 檢查目錄權限
-ls -la .collaboration/tasks/db/all/
-
-# 2. 檢查是否真的建立成功
-task-cli.js list
-
-# 3. 手動查找文件
-find .collaboration/tasks/ -name "TASK_*.json"
-```
-
----
-
-### Q: Git 提交後其他用戶看不到任務
-
-**A**: 檢查是否推送到遠端
-
-```bash
-# 1. 檢查本地提交
-git log -1 --oneline
-
-# 2. 檢查是否推送
-git status  # 應該顯示 "Your branch is up to date"
-
-# 3. 如果未推送，推送它
-git push origin main
-
-# 4. 其他用戶拉取
-git pull origin main
-```
-
----
-
-### Q: 任務 ID 無法識別
-
-**A**: 檢查格式
-
-```bash
-# ✅ 正確格式
-TASK_5KPEES80MMXH  # TASK_ + 10 字元
-
-# ❌ 錯誤格式
-TASK_147           # 舊格式（不支援）
-TASK-5KPEES80MMXH  # 錯誤分隔符
-task_5kpees80mmxh  # 小寫（不支援）
-```
-
----
-
-## 最佳實踐
-
-### Q: 團隊協作有什麼建議？
-
-**A**: 遵循這些原則
-
-1. **每天同步** - 早上第一件事 `git pull`
-2. **使用鎖定** - 長時間工作時鎖定任務
-3. **小步提交** - 每次只修改一個任務
-4. **清晰描述** - 任務標題和描述要清楚
-5. **及時更新** - 狀態變化時立即提交
-
----
-
-### Q: 如何組織大型專案的任務？
-
-**A**: 使用標籤和優先級
-
-```javascript
-// 建立任務時加入標籤
-const task = await api.createTask({
-  title: '實作登入功能',
-  priority: 'P1',
-  tags: ['frontend', 'auth', 'sprint-1']  // 自訂欄位
-});
-
-// 查詢時過濾
-const allData = await api.getAllTasks();
-const authTasks = allData.tasks.filter(t => t.tags?.includes('auth'));
-```
-
----
-
-### Q: 如何追蹤任務歷史？
-
-**A**: 使用 Git log
-
-```bash
-# 查看任務的所有變更
-git log --oneline --follow .collaboration/tasks/db/all/TASK_5KPEES80MMXH.json
-
-# 查看詳細差異
-git log -p .collaboration/tasks/db/all/TASK_5KPEES80MMXH.json
-
-# 查看特定欄位變更
-git log -S '"status"' .collaboration/tasks/db/all/TASK_5KPEES80MMXH.json
-```
-
----
-
-### Q: 如何備份任務資料？
-
-**A**: Git 本身就是備份
-
-```bash
-# 1. 定期推送到遠端
-git push origin main
-
-# 2. 額外備份到其他遠端（可選）
-git remote add backup https://gitlab.com/user/project.git
-git push backup main
-
-# 3. 本地備份（可選）
-tar -czf tasks-backup-$(date +%Y%m%d).tar.gz .collaboration/tasks/
-```
-
----
-
-### Q: 如何整合到 CI/CD？
-
-**A**: 使用 Git Hooks 或 CI 腳本
-
-**GitHub Actions 範例**：
-```yaml
-# .github/workflows/task-validation.yml
-name: Task Validation
-
-on: [push, pull_request]
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v2
-        with:
-          node-version: '14'
-
-      - name: Validate Task Files
-        run: |
-          node .collaboration/tools/validate-all-tasks.js
-
-      - name: Rebuild Index
-        run: |
-          node .collaboration/cli/task-cli.js rebuild
-
-      - name: Check for Changes
-        run: |
-          if [ -n "$(git status --porcelain)" ]; then
-            echo "索引需要重建！"
-            exit 1
-          fi
-```
-
----
-
-## 相關文檔
-
-- [API 參考文檔](./API.md) - JavaScript API 完整文檔
-- [CLI 使用指南](./CLI.md) - 命令列工具文檔
-- [遷移指南](./MIGRATION.md) - 從舊系統遷移步驟
-- [架構設計](./ARCHITECTURE.md) - 系統架構詳細說明
-
----
-
-**版本**: 1.0.0
-**最後更新**: 2026-02-11
-**維護者**: Developer Team
-
----
-
-## 還有問題？
-
-如果本 FAQ 未涵蓋您的問題，請：
-
-1. 查看[完整文檔](./)
-2. 檢查 [GitHub Issues](https://github.com/your/repo/issues)（如果適用）
-3. 聯繫團隊維護者