kenaz 0.3.18 → 0.3.19

package/core/.collaboration/docs/API.md

@@ -1,787 +0,0 @@
-# .collaboration API 參考文檔
-
-完整的 JavaScript API 文檔，用於程式化操作 .collaboration 任務系統。
-
-## 目錄
-
-- [安裝與設置](#安裝與設置)
-- [TaskAPI 類別](#taskapi-類別)
-- [IndexManager 類別](#indexmanager-類別)
-- [LockManager 類別](#lockmanager-類別)
-- [IDGenerator 模組](#idgenerator-模組)
-- [資料結構](#資料結構)
-- [錯誤處理](#錯誤處理)
-
----
-
-## 安裝與設置
-
-### 引入模組
-
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const { IndexManager } = require('./.collaboration/core/index-manager.js');
-const { LockManager } = require('./.collaboration/core/lock-manager.js');
-const { generateTaskID, validateTaskID } = require('./.collaboration/core/id-generator.js');
-```
-
-### 初始化 API
-
-```javascript
-// 使用預設配置
-const api = new TaskAPI();
-
-// 自訂配置
-const api = new TaskAPI({
-  newSystemDir: path.join(__dirname, 'custom/tasks/db'),
-  oldQueueFile: path.join(__dirname, 'custom/TASK_QUEUE.json'),
-  completedFile: path.join(__dirname, 'custom/COMPLETED_TASKS.json')
-});
-```
-
----
-
-## TaskAPI 類別
-
-統一任務查詢和管理 API，整合新舊任務系統。
-
-### 建構函數
-
-```javascript
-new TaskAPI(config?: Object)
-```
-
-**參數**:
-- `config.newSystemDir` (string): 新系統任務目錄，預設 `.collaboration/tasks/db`
-- `config.oldQueueFile` (string): 舊系統佇列文件，預設 `dev/pipeline/TASK_QUEUE.json`
-- `config.completedFile` (string): 已完成任務文件，預設 `.memory/COMPLETED_TASKS.json`
-
-### 方法
-
-#### `getAllTasks(options)`
-
-取得所有任務，合併新舊系統資料。
-
-**參數**:
-- `options.includeCompleted` (boolean): 是否包含已完成任務，預設 `true`
-
-**返回**: `Promise<Object>`
-
-```javascript
-{
-  version: "2.0.0",
-  tasks: [...],           // 所有任務
-  statistics: {           // 統計資料
-    total: 10,
-    pending: 5,
-    in_progress: 3,
-    completed: 2,
-    blocked: 0
-  },
-  metadata: {
-    last_updated: "2026-02-11T10:00:00Z",
-    sources: {
-      new: 8,             // 新系統任務數
-      old: 2,             // 舊系統任務數
-      completed: 0        // 已完成任務數
-    }
-  }
-}
-```
-
-**範例**:
-
-```javascript
-// 取得所有任務
-const allData = await api.getAllTasks();
-console.log(`總任務數: ${allData.statistics.total}`);
-console.log(`Pending: ${allData.statistics.pending}`);
-
-// 只取得未完成任務
-const activeTasks = await api.getAllTasks({ includeCompleted: false });
-```
-
----
-
-#### `getTask(taskId)`
-
-取得單個任務詳情。
-
-**參數**:
-- `taskId` (string): 任務 ID（如 `TASK_5KPEES80MMXH`）
-
-**返回**: `Promise<Object|null>`
-
-**拋出**:
-- `Error`: 如果任務 ID 格式無效
-
-**範例**:
-
-```javascript
-const task = await api.getTask('TASK_5KPEES80MMXH');
-if (task) {
-  console.log(`任務標題: ${task.title}`);
-  console.log(`狀態: ${task.status}`);
-  console.log(`來源: ${task._source}`);  // 'new' | 'old' | 'completed'
-} else {
-  console.log('任務不存在');
-}
-```
-
----
-
-#### `createTask(taskData)`
-
-建立新任務。
-
-**參數**:
-- `taskData.title` (string, required): 任務標題
-- `taskData.description` (string): 任務描述
-- `taskData.status` (string): 狀態，預設 `pending`
-- `taskData.priority` (string): 優先級，預設 `P2`
-- `taskData.created_by` (Object): 建立者資訊（可選，自動從 Git 取得）
-- `taskData.assigned_to` (Object): 分配對象
-- `taskData.collaborators` (Array): 協作者列表
-
-**返回**: `Promise<Object>` - 建立的任務
-
-**範例**:
-
-```javascript
-// 簡單建立
-const task = await api.createTask({
-  title: '實作登入功能',
-  priority: 'P1'
-});
-
-// 完整建立
-const task = await api.createTask({
-  title: '實作登入功能',
-  description: '建立登入頁面和認證 API',
-  priority: 'P1',
-  status: 'pending',
-  assigned_to: {
-    name: '李四',
-    git_user: 'lisi',
-    timestamp: new Date().toISOString()
-  },
-  collaborators: [
-    { name: '王五', git_user: 'wangwu' }
-  ]
-});
-
-console.log(`任務已建立: ${task.id}`);
-console.log(`檔案路徑: ${task._file_path}`);
-```
-
----
-
-#### `updateTask(taskId, updates)`
-
-更新任務。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `updates` (Object): 更新資料（任何任務欄位）
-
-**返回**: `Promise<Object>` - 更新後的任務
-
-**拋出**:
-- `Error`: 任務不存在
-- `Error`: 任務被其他用戶鎖定
-- `Error`: 無法更新舊系統任務
-
-**範例**:
-
-```javascript
-// 更新狀態
-const task = await api.updateTask('TASK_5KPEES80MMXH', {
-  status: 'in_progress'
-});
-
-// 更新多個欄位
-const task = await api.updateTask('TASK_5KPEES80MMXH', {
-  status: 'in_progress',
-  priority: 'P0',
-  description: '更新後的描述'
-});
-
-console.log(`版本號: ${task._version}`);  // 自動遞增
-```
-
----
-
-#### `deleteTask(taskId)`
-
-刪除任務。
-
-**參數**:
-- `taskId` (string): 任務 ID
-
-**返回**: `Promise<boolean>` - 是否成功刪除
-
-**拋出**:
-- `Error`: 無法刪除舊系統任務
-
-**範例**:
-
-```javascript
-const success = await api.deleteTask('TASK_5KPEES80MMXH');
-if (success) {
-  console.log('任務已刪除');
-}
-```
-
----
-
-#### `claimTask(taskId, gitUser?)`
-
-認領任務（分配給自己或指定用戶）。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `gitUser` (string, optional): Git 用戶名（預設為當前用戶）
-
-**返回**: `Promise<Object>` - 更新後的任務
-
-**範例**:
-
-```javascript
-// 認領給自己
-const task = await api.claimTask('TASK_5KPEES80MMXH');
-console.log(`已認領，分配給: ${task.assigned_to.git_user}`);
-
-// 認領並分配給他人
-const task = await api.claimTask('TASK_5KPEES80MMXH', 'lisi');
-```
-
----
-
-#### `completeTask(taskId)`
-
-標記任務為完成。
-
-**參數**:
-- `taskId` (string): 任務 ID
-
-**返回**: `Promise<Object>` - 更新後的任務
-
-**範例**:
-
-```javascript
-const task = await api.completeTask('TASK_5KPEES80MMXH');
-console.log(`任務已完成，執行者: ${task.executed_by.name}`);
-console.log(`完成時間: ${task.executed_by.timestamp}`);
-```
-
----
-
-#### `queryTasks(query)`
-
-查詢任務（按條件過濾）。
-
-**參數**:
-- `query.status` (string): 按狀態過濾
-- `query.assigned_to` (string): 按分配對象過濾（git_user）
-- `query.priority` (string): 按優先級過濾
-- `query.created_by` (string): 按建立者過濾（git_user）
-
-**返回**: `Promise<Array>` - 符合條件的任務列表
-
-**範例**:
-
-```javascript
-// 查詢所有 pending 任務
-const pending = await api.queryTasks({ status: 'pending' });
-
-// 查詢我的任務
-const myTasks = await api.queryTasks({ assigned_to: 'zhangsan' });
-
-// 查詢 P0 任務
-const urgent = await api.queryTasks({ priority: 'P0' });
-
-// 組合查詢
-const myUrgent = await api.queryTasks({
-  assigned_to: 'zhangsan',
-  priority: 'P0',
-  status: 'in_progress'
-});
-```
-
----
-
-## IndexManager 類別
-
-管理 JSONL 索引系統，提供高效的任務分類查詢。
-
-### 方法
-
-#### `updateTask(taskId, task)`
-
-更新任務索引。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `task` (Object): 任務資料
-
-**返回**: `Promise<void>`
-
-**範例**:
-
-```javascript
-const indexMgr = new IndexManager();
-await indexMgr.updateTask('TASK_5KPEES80MMXH', task);
-```
-
----
-
-#### `removeTask(taskId, task)`
-
-從索引中移除任務。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `task` (Object): 任務資料（用於確定索引位置）
-
-**返回**: `Promise<void>`
-
----
-
-#### `rebuildAll()`
-
-重建所有索引。
-
-**返回**: `Promise<Object>` - 統計資料
-
-**範例**:
-
-```javascript
-const stats = await indexMgr.rebuildAll();
-console.log(`總任務數: ${stats.totalTasks}`);
-console.log(`狀態分類: ${stats.byStatus}`);
-console.log(`用戶分類: ${stats.byUser}`);
-console.log(`優先級分類: ${stats.byPriority}`);
-```
-
----
-
-#### `getByStatus(status)`
-
-按狀態查詢任務 ID。
-
-**參數**:
-- `status` (string): 狀態值（`pending`, `in_progress`, `completed`, `blocked`）
-
-**返回**: `Promise<Array<string>>` - 任務 ID 列表
-
-**範例**:
-
-```javascript
-const pendingIds = await indexMgr.getByStatus('pending');
-console.log(`有 ${pendingIds.length} 個 pending 任務`);
-```
-
----
-
-#### `getByUser(gitUser)`
-
-按用戶查詢任務 ID。
-
-**參數**:
-- `gitUser` (string): Git 用戶名
-
-**返回**: `Promise<Array<string>>` - 任務 ID 列表
-
----
-
-#### `getByPriority(priority)`
-
-按優先級查詢任務 ID。
-
-**參數**:
-- `priority` (string): 優先級（`P0`, `P1`, `P2`, `P3`）
-
-**返回**: `Promise<Array<string>>` - 任務 ID 列表
-
----
-
-## LockManager 類別
-
-管理任務鎖定機制，避免並發編輯衝突。
-
-### 方法
-
-#### `acquireLock(taskId, gitUser, ttlMinutes?)`
-
-鎖定任務。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `gitUser` (string): Git 用戶名
-- `ttlMinutes` (number): 鎖定時長（分鐘），預設 60
-
-**返回**: `Promise<Object>` - 鎖定資訊
-
-**拋出**:
-- `Error`: 任務已被其他用戶鎖定
-
-**範例**:
-
-```javascript
-const lockMgr = new LockManager();
-
-try {
-  const lock = await lockMgr.acquireLock('TASK_5KPEES80MMXH', 'zhangsan', 30);
-  console.log(`鎖定成功，過期時間: ${lock.expires_at}`);
-} catch (error) {
-  console.error(`鎖定失敗: ${error.message}`);
-}
-```
-
----
-
-#### `releaseLock(taskId, gitUser)`
-
-釋放鎖定。
-
-**參數**:
-- `taskId` (string): 任務 ID
-- `gitUser` (string): Git 用戶名
-
-**返回**: `Promise<boolean>` - 是否成功釋放
-
-**範例**:
-
-```javascript
-const success = await lockMgr.releaseLock('TASK_5KPEES80MMXH', 'zhangsan');
-if (success) {
-  console.log('鎖定已釋放');
-}
-```
-
----
-
-#### `isLocked(taskId)`
-
-檢查任務是否被鎖定。
-
-**參數**:
-- `taskId` (string): 任務 ID
-
-**返回**: `Promise<boolean>`
-
----
-
-#### `getLockInfo(taskId)`
-
-取得鎖定資訊。
-
-**參數**:
-- `taskId` (string): 任務 ID
-
-**返回**: `Promise<Object|null>` - 鎖定資訊或 null
-
-**範例**:
-
-```javascript
-const lockInfo = await lockMgr.getLockInfo('TASK_5KPEES80MMXH');
-if (lockInfo) {
-  console.log(`鎖定者: ${lockInfo.locked_by}`);
-  console.log(`鎖定時間: ${lockInfo.locked_at}`);
-  console.log(`過期時間: ${lockInfo.expires_at}`);
-}
-```
-
----
-
-#### `cleanExpiredLocks()`
-
-清理過期鎖定。
-
-**返回**: `Promise<number>` - 清理的鎖定數量
-
----
-
-## IDGenerator 模組
-
-生成唯一的任務 ID（ULID 格式）。
-
-### 函數
-
-#### `generateTaskID()`
-
-生成新的任務 ID。
-
-**返回**: `string` - 格式為 `TASK_XXXXXXXXXXXX`（15 字元）
-
-**特性**:
-- 時間部分（6 字元）：可排序，精確到毫秒
-- 隨機部分（4 字元）：確保唯一性
-- 編碼：Crockford Base32（避免歧義字元）
-
-**範例**:
-
-```javascript
-const { generateTaskID } = require('./.collaboration/core/id-generator.js');
-
-const taskId = generateTaskID();
-console.log(taskId);  // 輸出: TASK_5KPEES80MMXH
-```
-
----
-
-#### `validateTaskID(taskId)`
-
-驗證任務 ID 格式。
-
-**參數**:
-- `taskId` (string): 任務 ID
-
-**返回**: `boolean`
-
-**範例**:
-
-```javascript
-const { validateTaskID } = require('./.collaboration/core/id-generator.js');
-
-console.log(validateTaskID('TASK_5KPEES80MMXH'));  // true
-console.log(validateTaskID('TASK_123'));           // false
-console.log(validateTaskID('invalid'));            // false
-```
-
----
-
-## 資料結構
-
-### 任務物件 (Task)
-
-```typescript
-interface Task {
-  // 核心欄位
-  id: string;                    // 任務 ID（TASK_XXXXXXXXXXXX）
-  title: string;                 // 標題
-  description: string;           // 描述
-  status: 'pending' | 'in_progress' | 'completed' | 'blocked';
-  priority: 'P0' | 'P1' | 'P2' | 'P3';
-
-  // 用戶追蹤
-  created_by: UserInfo;          // 建立者
-  assigned_to: UserInfo | null;  // 分配對象
-  last_modified_by: UserInfo;    // 最後修改者
-  collaborators: UserInfo[];     // 協作者列表
-  executed_by: UserInfo | null;  // 執行者（完成時填入）
-
-  // 元數據
-  _version: number;              // 版本號（樂觀鎖定）
-  _file_path?: string;           // 檔案路徑
-  _source?: 'new' | 'old' | 'completed';  // 資料來源
-
-  // 可選欄位
-  estimated_hours?: number;      // 預估工時
-  acceptance_criteria?: string[]; // 驗收標準
-  scope?: string[];              // 影響範圍
-  dependencies?: string[];       // 依賴任務
-  tags?: string[];               // 標籤
-}
-```
-
----
-
-### 用戶資訊 (UserInfo)
-
-```typescript
-interface UserInfo {
-  name: string;           // 顯示名稱
-  git_user: string;       // Git 用戶名（從 email 取得）
-  email?: string;         // Email
-  timestamp: string;      // ISO 8601 時間戳
-}
-```
-
----
-
-### 鎖定資訊 (LockInfo)
-
-```typescript
-interface LockInfo {
-  task_id: string;        // 任務 ID
-  locked_by: string;      // 鎖定者（@git_user 格式）
-  locked_at: string;      // 鎖定時間（ISO 8601）
-  expires_at: string;     // 過期時間（ISO 8601）
-  _version: number;       // 版本號
-}
-```
-
----
-
-## 錯誤處理
-
-### 常見錯誤
-
-| 錯誤訊息 | 原因 | 解決方案 |
-|---------|------|---------|
-| `無效的任務 ID: XXX` | 任務 ID 格式不正確 | 使用 `validateTaskID()` 驗證 |
-| `任務不存在: XXX` | 任務未找到 | 檢查任務 ID 是否正確 |
-| `任務被其他用戶鎖定: @user` | 任務已被鎖定 | 等待鎖定過期或聯繫鎖定者 |
-| `無法更新舊系統任務: XXX` | 嘗試更新 TASK_QUEUE.json 中的任務 | 遷移到新系統或使用舊系統 API |
-| `無法刪除舊系統任務: XXX` | 嘗試刪除舊系統任務 | 手動編輯 TASK_QUEUE.json |
-
-### 錯誤處理範例
-
-```javascript
-try {
-  const task = await api.getTask('TASK_5KPEES80MMXH');
-} catch (error) {
-  if (error.message.includes('無效的任務 ID')) {
-    console.error('任務 ID 格式錯誤');
-  } else if (error.message.includes('不存在')) {
-    console.error('任務未找到');
-  } else {
-    console.error('未知錯誤:', error.message);
-  }
-}
-```
-
----
-
-## 最佳實踐
-
-### 1. 使用樂觀鎖定避免衝突
-
-```javascript
-const task = await api.getTask('TASK_5KPEES80MMXH');
-const currentVersion = task._version;
-
-// 修改任務
-const updated = await api.updateTask('TASK_5KPEES80MMXH', {
-  status: 'in_progress'
-});
-
-// 檢查版本號
-if (updated._version !== currentVersion + 1) {
-  console.warn('任務在更新期間被其他人修改');
-}
-```
-
----
-
-### 2. 使用鎖定保護長時間操作
-
-```javascript
-const lockMgr = new LockManager();
-const taskId = 'TASK_5KPEES80MMXH';
-
-try {
-  // 鎖定任務（30 分鐘）
-  await lockMgr.acquireLock(taskId, 'zhangsan', 30);
-
-  // 執行長時間操作
-  // ...
-
-  // 釋放鎖定
-  await lockMgr.releaseLock(taskId, 'zhangsan');
-} catch (error) {
-  console.error('操作失敗:', error.message);
-}
-```
-
----
-
-### 3. 批量查詢優化
-
-```javascript
-// ❌ 不佳：逐個查詢
-for (const id of taskIds) {
-  const task = await api.getTask(id);
-  console.log(task.title);
-}
-
-// ✅ 最佳：一次查詢所有任務
-const allData = await api.getAllTasks();
-const taskMap = new Map(allData.tasks.map(t => [t.id, t]));
-
-for (const id of taskIds) {
-  const task = taskMap.get(id);
-  if (task) console.log(task.title);
-}
-```
-
----
-
-### 4. 自動清理過期鎖定
-
-```javascript
-// 定期清理（建議每小時執行一次）
-setInterval(async () => {
-  const lockMgr = new LockManager();
-  const cleaned = await lockMgr.cleanExpiredLocks();
-  if (cleaned > 0) {
-    console.log(`已清理 ${cleaned} 個過期鎖定`);
-  }
-}, 60 * 60 * 1000);  // 每小時
-```
-
----
-
-## 完整範例
-
-### 任務生命週期
-
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const { LockManager } = require('./.collaboration/core/lock-manager.js');
-
-const api = new TaskAPI();
-const lockMgr = new LockManager();
-
-async function taskLifecycle() {
-  // 1. 建立任務
-  const task = await api.createTask({
-    title: '實作登入功能',
-    description: '建立登入頁面和認證 API',
-    priority: 'P1'
-  });
-  console.log(`✅ 任務已建立: ${task.id}`);
-
-  // 2. 認領任務
-  const claimed = await api.claimTask(task.id);
-  console.log(`✅ 任務已認領，分配給: ${claimed.assigned_to.name}`);
-
-  // 3. 鎖定任務
-  await lockMgr.acquireLock(task.id, 'zhangsan', 60);
-  console.log(`🔒 任務已鎖定`);
-
-  // 4. 執行工作
-  await new Promise(resolve => setTimeout(resolve, 5000));
-
-  // 5. 更新進度
-  await api.updateTask(task.id, {
-    description: '登入頁面已完成，正在開發 API'
-  });
-
-  // 6. 完成任務
-  const completed = await api.completeTask(task.id);
-  console.log(`✅ 任務已完成，執行者: ${completed.executed_by.name}`);
-
-  // 7. 釋放鎖定
-  await lockMgr.releaseLock(task.id, 'zhangsan');
-  console.log(`🔓 鎖定已釋放`);
-}
-
-taskLifecycle().catch(console.error);
-```
-
----
-
-## 相關文檔
-
-- [CLI 使用指南](./CLI.md) - 命令列工具完整文檔
-- [遷移指南](./MIGRATION.md) - 從舊系統遷移步驟
-- [架構設計](./ARCHITECTURE.md) - 系統架構詳細說明
-- [常見問題](./FAQ.md) - 疑難排解
-
----
-
-**版本**: 1.0.0
-**最後更新**: 2026-02-11
-**維護者**: Developer Team