kenaz 0.3.18 → 0.3.20

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

@@ -1,320 +0,0 @@
-# .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

@@ -1,261 +0,0 @@
-#!/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 };