kenaz 0.0.0-stage → 0.3.2

package/core/.collaboration/docs/examples/README.md

@@ -0,0 +1,320 @@
+# .collaboration 範例程式碼
+
+這個目錄包含 .collaboration 系統的可執行範例程式碼，幫助您快速理解如何使用 API。
+
+## 範例列表
+
+| 檔案 | 說明 | 難度 |
+|------|------|------|
+| [basic-usage.js](./basic-usage.js) | 基本使用範例 - CRUD 操作 | 初級 ⭐ |
+| [advanced-queries.js](./advanced-queries.js) | 進階查詢範例 - 複雜過濾與統計 | 中級 ⭐⭐ |
+| [team-workflow.js](./team-workflow.js) | 團隊協作範例 - 多用戶工作流程 | 進階 ⭐⭐⭐ |
+
+---
+
+## basic-usage.js
+
+**適合**：初次接觸 .collaboration 的開發者
+
+**涵蓋主題**：
+- ✅ 建立任務
+- ✅ 查詢任務
+- ✅ 認領任務
+- ✅ 更新任務
+- ✅ 鎖定/解鎖任務
+- ✅ 完成任務
+- ✅ ID 生成與驗證
+
+**執行方式**：
+```bash
+node .collaboration/docs/examples/basic-usage.js
+```
+
+**預期輸出**：
+```
+=============================================================
+📚 .collaboration 基本使用範例
+=============================================================
+
+1️⃣ 建立任務
+-------------------------------------------------------------
+✅ 任務已建立: TASK_5KPEES80MMXH
+   標題: 實作登入功能
+   優先級: P1
+   ...
+
+2️⃣ 查詢任務
+-------------------------------------------------------------
+✅ 總任務數: 1
+   Pending: 1
+   ...
+```
+
+---
+
+## advanced-queries.js
+
+**適合**：需要進行複雜查詢和資料分析的開發者
+
+**涵蓋主題**：
+- ✅ 組合查詢（多條件過濾）
+- ✅ 使用 JSONL 索引加速查詢
+- ✅ 自訂過濾條件
+- ✅ 統計分析（按優先級、建立者、完成率）
+- ✅ 排序（按時間、優先級）
+- ✅ 依賴關係分析
+- ✅ 時間範圍查詢
+
+**執行方式**：
+```bash
+node .collaboration/docs/examples/advanced-queries.js
+```
+
+**預期輸出**：
+```
+=============================================================
+🔍 進階查詢範例
+=============================================================
+
+1️⃣ 組合查詢
+-------------------------------------------------------------
+✅ 我的 P0 緊急任務: 2 個
+   - [TASK_XXX] 修復線上問題
+   - [TASK_YYY] 緊急部署
+   ...
+
+4️⃣ 統計分析
+-------------------------------------------------------------
+✅ 按優先級統計:
+   P0: 3 個
+   P1: 5 個
+   P2: 2 個
+   ...
+```
+
+---
+
+## team-workflow.js
+
+**適合**：需要理解多用戶協作場景的團隊 Lead
+
+**涵蓋主題**：
+- ✅ PM 建立 Sprint 任務並分配
+- ✅ 開發者查看自己的任務
+- ✅ 並行工作（多個開發者同時工作）
+- ✅ 依賴關係管理
+- ✅ 緊急任務插隊
+- ✅ 團隊進度報告
+- ✅ Sprint 回顧與統計
+
+**執行方式**：
+```bash
+node .collaboration/docs/examples/team-workflow.js
+```
+
+**預期輸出**：
+```
+=============================================================
+👥 團隊協作工作流程範例
+=============================================================
+
+📋 場景 1: PM 建立 Sprint 任務
+-------------------------------------------------------------
+✅ PM 建立任務...
+   - [TASK_AAA] 實作登入頁面 → @zhangsan
+   - [TASK_BBB] 實作註冊頁面 → @lisi
+   ...
+
+📊 場景 8: 團隊進度報告
+-------------------------------------------------------------
+✅ 團隊進度統計:
+
+   @zhangsan:
+     總任務: 3
+     待辦: 1
+     進行中: 1
+     已完成: 1
+   ...
+
+📈 整體完成率: 45.5% (5/11)
+```
+
+---
+
+## 如何使用這些範例
+
+### 1. 直接執行
+
+```bash
+# 執行基本範例
+node .collaboration/docs/examples/basic-usage.js
+
+# 執行進階範例
+node .collaboration/docs/examples/advanced-queries.js
+
+# 執行團隊協作範例
+node .collaboration/docs/examples/team-workflow.js
+```
+
+---
+
+### 2. 作為參考代碼
+
+複製範例代碼到您的專案中並修改：
+
+```javascript
+// 從範例複製
+const { TaskAPI } = require('./.collaboration/core/task-api.js');
+
+// 在您的程式碼中使用
+async function myFunction() {
+  const api = new TaskAPI();
+
+  // 建立任務
+  const task = await api.createTask({
+    title: '我的任務',
+    priority: 'P1'
+  });
+
+  console.log(`任務已建立: ${task.id}`);
+}
+```
+
+---
+
+### 3. 整合到測試
+
+```javascript
+// test/task-api.test.js
+const { TaskAPI } = require('../.collaboration/core/task-api.js');
+
+describe('TaskAPI', () => {
+  it('should create task', async () => {
+    const api = new TaskAPI();
+    const task = await api.createTask({
+      title: '測試任務',
+      priority: 'P1'
+    });
+
+    expect(task.id).toMatch(/^TASK_[A-Z0-9]{10}$/);
+    expect(task.title).toBe('測試任務');
+  });
+});
+```
+
+---
+
+## 範例資料
+
+範例執行時會自動建立和清理任務，不會影響您的實際任務資料。
+
+**自動清理**：
+- 所有範例在執行結束時會刪除建立的任務
+- 不會影響現有任務
+- 可以安全地重複執行
+
+---
+
+## 學習路徑
+
+建議按以下順序學習：
+
+1. **第 1 天**：執行 `basic-usage.js`，理解基本 CRUD 操作
+2. **第 2 天**：執行 `advanced-queries.js`，學習複雜查詢
+3. **第 3 天**：執行 `team-workflow.js`，理解團隊協作場景
+
+---
+
+## 疑難排解
+
+### 範例執行失敗
+
+**錯誤訊息**：`Cannot find module`
+
+**解決方案**：
+```bash
+# 確認在專案根目錄
+pwd
+
+# 確認文件存在
+ls .collaboration/core/task-api.js
+
+# 使用絕對路徑執行
+node "$(pwd)/.collaboration/docs/examples/basic-usage.js"
+```
+
+---
+
+### 權限錯誤
+
+**錯誤訊息**：`EACCES: permission denied`
+
+**解決方案**：
+```bash
+# 賦予執行權限
+chmod +x .collaboration/docs/examples/*.js
+
+# 再次執行
+node .collaboration/docs/examples/basic-usage.js
+```
+
+---
+
+## 進階自訂
+
+### 修改範例以使用真實資料
+
+如果您想讓範例不刪除任務（用於測試）：
+
+```javascript
+// 在範例末尾註解掉清理代碼
+// await api.deleteTask(task1.id);  // 註解這一行
+
+// 或設置環境變數
+if (process.env.KEEP_EXAMPLE_DATA !== 'true') {
+  await api.deleteTask(task1.id);
+}
+```
+
+---
+
+### 整合到 CI/CD
+
+```yaml
+# .github/workflows/examples.yml
+name: Examples
+
+on: [push]
+
+jobs:
+  run-examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
+
+      - name: Run Basic Example
+        run: node .collaboration/docs/examples/basic-usage.js
+
+      - name: Run Advanced Example
+        run: node .collaboration/docs/examples/advanced-queries.js
+
+      - name: Run Team Workflow
+        run: node .collaboration/docs/examples/team-workflow.js
+```
+
+---
+
+## 相關文檔
+
+- [API 參考文檔](../API.md) - 完整 API 文檔
+- [CLI 使用指南](../CLI.md) - 命令列工具
+- [常見問題](../FAQ.md) - 疑難排解
+
+---
+
+**版本**: 1.0.0
+**最後更新**: 2026-02-11
+**維護者**: Developer Team

package/core/.collaboration/docs/examples/advanced-queries.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * advanced-queries.js
+ * 進階查詢範例 - 展示複雜的任務查詢和過濾
+ *
+ * 執行方式:
+ *   node .collaboration/docs/examples/advanced-queries.js
+ */
+
+const { TaskAPI } = require('../../core/task-api.js');
+const { IndexManager } = require('../../core/index-manager.js');
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('🔍 進階查詢範例');
+  console.log('='.repeat(60));
+
+  const api = new TaskAPI();
+  const indexMgr = new IndexManager();
+
+  // ============================================================================
+  // 1. 組合查詢
+  // ============================================================================
+
+  console.log('\n1️⃣ 組合查詢');
+  console.log('-'.repeat(60));
+
+  // 查詢我的 P0 緊急任務
+  const myUrgent = await api.queryTasks({
+    priority: 'P0',
+    assigned_to: 'zhangsan',
+    status: 'in_progress'
+  });
+
+  console.log(`✅ 我的 P0 緊急任務: ${myUrgent.length} 個`);
+  myUrgent.forEach(task => {
+    console.log(`   - [${task.id}] ${task.title}`);
+  });
+
+  // ============================================================================
+  // 2. 使用索引快速查詢
+  // ============================================================================
+
+  console.log('\n2️⃣ 使用索引快速查詢');
+  console.log('-'.repeat(60));
+
+  // 按狀態查詢
+  const pendingIds = await indexMgr.getByStatus('pending');
+  console.log(`✅ Pending 任務 ID: ${pendingIds.length} 個`);
+
+  // 按用戶查詢
+  const userIds = await indexMgr.getByUser('zhangsan');
+  console.log(`✅ zhangsan 的任務: ${userIds.length} 個`);
+
+  // 按優先級查詢
+  const p0Ids = await indexMgr.getByPriority('P0');
+  console.log(`✅ P0 任務: ${p0Ids.length} 個`);
+
+  // ============================================================================
+  // 3. 自訂過濾條件
+  // ============================================================================
+
+  console.log('\n3️⃣ 自訂過濾條件');
+  console.log('-'.repeat(60));
+
+  const allData = await api.getAllTasks();
+
+  // 過濾本週建立的任務
+  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  const thisWeekTasks = allData.tasks.filter(task => {
+    const createdAt = new Date(task.created_by.timestamp);
+    return createdAt > weekAgo;
+  });
+
+  console.log(`✅ 本週建立的任務: ${thisWeekTasks.length} 個`);
+
+  // 過濾預估工時 > 4 小時的任務
+  const longTasks = allData.tasks.filter(task => {
+    return task.estimated_hours && task.estimated_hours > 4;
+  });
+
+  console.log(`✅ 預估 > 4 小時的任務: ${longTasks.length} 個`);
+
+  // 過濾有依賴的任務
+  const tasksWithDeps = allData.tasks.filter(task => {
+    return task.dependencies && task.dependencies.length > 0;
+  });
+
+  console.log(`✅ 有依賴的任務: ${tasksWithDeps.length} 個`);
+
+  // ============================================================================
+  // 4. 統計分析
+  // ============================================================================
+
+  console.log('\n4️⃣ 統計分析');
+  console.log('-'.repeat(60));
+
+  // 按優先級統計
+  const priorityStats = {};
+  allData.tasks.forEach(task => {
+    priorityStats[task.priority] = (priorityStats[task.priority] || 0) + 1;
+  });
+
+  console.log('✅ 按優先級統計:');
+  Object.entries(priorityStats).forEach(([priority, count]) => {
+    console.log(`   ${priority}: ${count} 個`);
+  });
+
+  // 按建立者統計
+  const creatorStats = {};
+  allData.tasks.forEach(task => {
+    const creator = task.created_by.git_user;
+    creatorStats[creator] = (creatorStats[creator] || 0) + 1;
+  });
+
+  console.log('\n✅ 按建立者統計:');
+  Object.entries(creatorStats)
+    .sort((a, b) => b[1] - a[1])  // 按數量排序
+    .forEach(([user, count]) => {
+      console.log(`   @${user}: ${count} 個`);
+    });
+
+  // 完成率統計
+  const completedCount = allData.statistics.completed;
+  const totalCount = allData.statistics.total;
+  const completionRate = ((completedCount / totalCount) * 100).toFixed(1);
+
+  console.log(`\n✅ 完成率: ${completionRate}% (${completedCount}/${totalCount})`);
+
+  // ============================================================================
+  // 5. 排序
+  // ============================================================================
+
+  console.log('\n5️⃣ 排序');
+  console.log('-'.repeat(60));
+
+  // 按建立時間排序（最新優先）
+  const sortedByTime = [...allData.tasks].sort((a, b) => {
+    return new Date(b.created_by.timestamp) - new Date(a.created_by.timestamp);
+  });
+
+  console.log('✅ 最近建立的 3 個任務:');
+  sortedByTime.slice(0, 3).forEach(task => {
+    console.log(`   - [${task.id}] ${task.title} (${task.created_by.timestamp})`);
+  });
+
+  // 按優先級排序（P0 > P1 > P2 > P3）
+  const priorityOrder = { 'P0': 0, 'P1': 1, 'P2': 2, 'P3': 3 };
+  const sortedByPriority = [...allData.tasks].sort((a, b) => {
+    return priorityOrder[a.priority] - priorityOrder[b.priority];
+  });
+
+  console.log('\n✅ 最高優先級的 3 個任務:');
+  sortedByPriority.slice(0, 3).forEach(task => {
+    console.log(`   - [${task.id}] ${task.title} (${task.priority})`);
+  });
+
+  // ============================================================================
+  // 6. 複雜過濾：組合多個條件
+  // ============================================================================
+
+  console.log('\n6️⃣ 複雜過濾');
+  console.log('-'.repeat(60));
+
+  // 找出：P0/P1、未完成、有人認領、無阻塞的任務
+  const urgentActive = allData.tasks.filter(task => {
+    return (task.priority === 'P0' || task.priority === 'P1') &&
+           task.status !== 'completed' &&
+           task.status !== 'blocked' &&
+           task.assigned_to !== null;
+  });
+
+  console.log(`✅ 高優先級進行中任務: ${urgentActive.length} 個`);
+  urgentActive.forEach(task => {
+    console.log(`   - [${task.id}] ${task.title}`);
+    console.log(`     優先級: ${task.priority} | 狀態: ${task.status} | 負責人: ${task.assigned_to.name}`);
+  });
+
+  // ============================================================================
+  // 7. 依賴關係分析
+  // ============================================================================
+
+  console.log('\n7️⃣ 依賴關係分析');
+  console.log('-'.repeat(60));
+
+  // 找出所有被依賴的任務
+  const dependedTasks = new Set();
+  allData.tasks.forEach(task => {
+    if (task.dependencies) {
+      task.dependencies.forEach(depId => dependedTasks.add(depId));
+    }
+  });
+
+  console.log(`✅ 被依賴的任務數: ${dependedTasks.size} 個`);
+
+  // 找出可以立即開始的任務（無依賴或依賴已完成）
+  const readyTasks = [];
+  for (const task of allData.tasks) {
+    if (task.status === 'pending') {
+      if (!task.dependencies || task.dependencies.length === 0) {
+        readyTasks.push(task);
+      } else {
+        // 檢查依賴是否全部完成
+        const allDepsCompleted = await Promise.all(
+          task.dependencies.map(async depId => {
+            const depTask = await api.getTask(depId);
+            return depTask && depTask.status === 'completed';
+          })
+        );
+
+        if (allDepsCompleted.every(completed => completed)) {
+          readyTasks.push(task);
+        }
+      }
+    }
+  }
+
+  console.log(`\n✅ 可以立即開始的任務: ${readyTasks.length} 個`);
+  readyTasks.forEach(task => {
+    console.log(`   - [${task.id}] ${task.title} (${task.priority})`);
+  });
+
+  // ============================================================================
+  // 8. 時間範圍查詢
+  // ============================================================================
+
+  console.log('\n8️⃣ 時間範圍查詢');
+  console.log('-'.repeat(60));
+
+  // 今天建立的任務
+  const today = new Date().toISOString().split('T')[0];
+  const todayTasks = allData.tasks.filter(task => {
+    return task.created_by.timestamp.startsWith(today);
+  });
+
+  console.log(`✅ 今天建立的任務: ${todayTasks.length} 個`);
+
+  // 本月完成的任務
+  const thisMonth = new Date().toISOString().slice(0, 7);  // YYYY-MM
+  const thisMonthCompleted = allData.tasks.filter(task => {
+    return task.status === 'completed' &&
+           task.executed_by?.timestamp.startsWith(thisMonth);
+  });
+
+  console.log(`✅ 本月完成的任務: ${thisMonthCompleted.length} 個`);
+
+  console.log('\n' + '='.repeat(60));
+  console.log('✅ 範例執行完成！');
+  console.log('='.repeat(60));
+}
+
+// 執行範例
+if (require.main === module) {
+  main().catch(error => {
+    console.error('❌ 執行失敗:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };