kenaz 0.3.18 → 0.3.19

package/core/.collaboration/docs/MIGRATION.md

@@ -1,804 +0,0 @@
-# .collaboration 遷移指南
-
-從舊的 `dev/pipeline/` 任務系統遷移到新的 `.collaboration` 系統的完整指南。
-
-## 目錄
-
-- [為什麼要遷移](#為什麼要遷移)
-- [遷移前準備](#遷移前準備)
-- [遷移步驟](#遷移步驟)
-- [遷移工具](#遷移工具)
-- [驗證遷移](#驗證遷移)
-- [回滾計劃](#回滾計劃)
-- [常見問題](#常見問題)
-- [最佳實踐](#最佳實踐)
-
----
-
-## 為什麼要遷移
-
-### 舊系統的限制
-
-| 問題 | 舊系統 (dev/pipeline/) | 新系統 (.collaboration/) |
-|------|----------------------|-------------------------|
-| **Git 衝突** | 頻繁發生（單一 JSON 文件） | 幾乎無衝突（原子文件） |
-| **多用戶協作** | 困難（鎖定機制不完善） | 順暢（樂觀鎖定 + 版本號） |
-| **任務 ID** | 遞增數字（易衝突） | UUID（全局唯一） |
-| **索引效率** | 需要載入整個文件 | JSONL 索引（快速查詢） |
-| **擴展性** | 單一文件有大小限制 | 可無限擴展（扁平化存儲） |
-| **可移植性** | 相對路徑依賴 | 完全可移植（Git 友好） |
-
----
-
-### 新系統的優勢
-
-- ✅ **原子文件結構** - 一個任務一個檔案，最小化 Git 衝突
-- ✅ **UUID 任務 ID** - 全局唯一，可排序，支援分散式協作
-- ✅ **JSONL 索引** - Append-only 格式，Git 自動合併友好
-- ✅ **樂觀鎖定** - 版本號衝突偵測，無需中央伺服器
-- ✅ **完整用戶追蹤** - 建立者、分配者、執行者、協作者
-- ✅ **統一 API** - 相容舊系統，支援漸進式遷移
-
----
-
-## 遷移前準備
-
-### 1. 備份舊系統資料
-
-```bash
-# 建立備份目錄
-mkdir -p .migration/backup/$(date +%Y%m%d)
-
-# 備份 TASK_QUEUE.json
-cp dev/pipeline/TASK_QUEUE.json .migration/backup/$(date +%Y%m%d)/
-
-# 備份已完成任務
-cp dev/pipeline/completed/*.yaml .migration/backup/$(date +%Y%m%d)/ 2>/dev/null || true
-
-# 備份記憶檔案
-cp .memory/COMPLETED_TASKS.json .migration/backup/$(date +%Y%m%d)/ 2>/dev/null || true
-
-echo "✅ 備份完成：.migration/backup/$(date +%Y%m%d)/"
-```
-
----
-
-### 2. 檢查 Git 狀態
-
-```bash
-# 確保工作區乾淨
-git status
-
-# 如果有未提交的變更，先提交
-git add .
-git commit -m "chore: 遷移前的檢查點"
-git push origin main
-
-# 建立遷移分支（建議）
-git checkout -b migration/collaboration-system
-```
-
----
-
-### 3. 安裝必要工具
-
-```bash
-# 檢查 Node.js 版本（需要 >= 14）
-node --version
-
-# 測試 CLI 工具
-node .collaboration/cli/task-cli.js --help
-
-# 測試 API
-node -e "
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-console.log('✅ API 載入成功');
-"
-```
-
----
-
-## 遷移步驟
-
-### 步驟 1：分析現有任務
-
-```bash
-# 統計任務數量
-echo "舊系統任務統計："
-node -e "
-const fs = require('fs');
-const data = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-console.log(\`總任務數: \${data.tasks.length}\`);
-console.log(\`Pending: \${data.tasks.filter(t => t.status === 'pending').length}\`);
-console.log(\`In Progress: \${data.tasks.filter(t => t.status === 'in_progress').length}\`);
-console.log(\`Completed: \${data.tasks.filter(t => t.status === 'completed').length}\`);
-"
-```
-
----
-
-### 步驟 2：遷移任務資料
-
-**選項 A：使用自動遷移腳本（推薦）**
-
-```javascript
-// .collaboration/tools/migrate.js
-const fs = require('fs').promises;
-const path = require('path');
-const { TaskAPI } = require('../core/task-api.js');
-const { generateTaskID } = require('../core/id-generator.js');
-
-async function migrateFromOldSystem() {
-  const api = new TaskAPI();
-
-  // 讀取舊系統任務
-  const oldQueue = JSON.parse(
-    await fs.readFile('dev/pipeline/TASK_QUEUE.json', 'utf8')
-  );
-
-  console.log(`開始遷移 ${oldQueue.tasks.length} 個任務...`);
-
-  const idMapping = {};  // 舊 ID → 新 ID 映射
-
-  for (const oldTask of oldQueue.tasks) {
-    // 生成新的 UUID
-    const newId = generateTaskID();
-    idMapping[oldTask.id] = newId;
-
-    // 轉換任務格式
-    const newTask = {
-      id: newId,
-      title: oldTask.title,
-      description: oldTask.description || oldTask.requirements?.join('\n') || '',
-      status: oldTask.status,
-      priority: oldTask.priority,
-      estimated_hours: oldTask.estimated_hours,
-      acceptance_criteria: oldTask.acceptance_criteria || [],
-      scope: oldTask.scope_paths || [],
-      dependencies: oldTask.dependencies || [],  // 稍後更新為新 ID
-      created_by: {
-        name: oldTask.created_by || 'System',
-        git_user: 'system',
-        timestamp: oldTask.created_at || new Date().toISOString()
-      },
-      assigned_to: oldTask.assigned_to ? {
-        name: oldTask.assigned_to,
-        git_user: oldTask.assigned_to.toLowerCase(),
-        timestamp: new Date().toISOString()
-      } : null,
-      last_modified_by: {
-        name: 'Migration Script',
-        git_user: 'system',
-        timestamp: new Date().toISOString()
-      },
-      collaborators: [],
-      executed_by: oldTask.status === 'completed' ? {
-        name: oldTask.executed_by || 'Unknown',
-        git_user: 'unknown',
-        timestamp: oldTask.completed_at || new Date().toISOString()
-      } : null,
-      _version: 1,
-      _migration: {
-        old_id: oldTask.id,
-        migrated_at: new Date().toISOString(),
-        source: 'dev/pipeline/TASK_QUEUE.json'
-      }
-    };
-
-    // 寫入新系統
-    const userDir = path.join('.collaboration/tasks/db/all');
-    await fs.mkdir(userDir, { recursive: true });
-
-    const taskPath = path.join(userDir, `${newId}.json`);
-    await fs.writeFile(taskPath, JSON.stringify(newTask, null, 2));
-
-    console.log(`✅ 遷移: ${oldTask.id} → ${newId}`);
-  }
-
-  // 更新依賴關係（使用新 ID）
-  console.log('\n更新依賴關係...');
-  for (const [oldId, newId] of Object.entries(idMapping)) {
-    const taskPath = path.join('.collaboration/tasks/db/all', `${newId}.json`);
-    const task = JSON.parse(await fs.readFile(taskPath, 'utf8'));
-
-    if (task.dependencies && task.dependencies.length > 0) {
-      task.dependencies = task.dependencies.map(depId => idMapping[depId] || depId);
-      await fs.writeFile(taskPath, JSON.stringify(task, null, 2));
-    }
-  }
-
-  // 儲存 ID 映射表
-  await fs.writeFile(
-    '.migration/id_mapping.json',
-    JSON.stringify(idMapping, null, 2)
-  );
-
-  console.log(`\n✅ 遷移完成！`);
-  console.log(`ID 映射表已儲存: .migration/id_mapping.json`);
-
-  return idMapping;
-}
-
-// 執行遷移
-migrateFromOldSystem().catch(console.error);
-```
-
-**執行遷移**:
-```bash
-# 執行遷移腳本
-node .collaboration/tools/migrate.js
-
-# 輸出範例：
-# 開始遷移 10 個任務...
-# ✅ 遷移: TASK_147 → TASK_5KPEES80F922
-# ✅ 遷移: TASK_148 → TASK_5KPEES80HT6S
-# ...
-# ✅ 遷移完成！
-# ID 映射表已儲存: .migration/id_mapping.json
-```
-
----
-
-**選項 B：手動遷移（小規模）**
-
-如果只有少量任務（< 10 個），可以手動遷移：
-
-```bash
-# 1. 為每個舊任務建立新任務
-node .collaboration/cli/task-cli.js create \
-  --title "實作登入功能" \
-  --description "從 TASK_147 遷移" \
-  --priority P1
-
-# 2. 記錄 ID 映射
-echo "TASK_147 → TASK_5KPEES80F922" >> .migration/manual_mapping.txt
-```
-
----
-
-### 步驟 3：重建索引
-
-```bash
-# 重建所有索引
-node .collaboration/cli/task-cli.js rebuild
-
-# 輸出範例：
-# 重建索引中...
-# ✅ 索引重建完成
-# 總任務數: 10
-# 狀態分類: 4
-# 用戶分類: 3
-# 優先級分類: 3
-```
-
----
-
-### 步驟 4：驗證遷移結果
-
-```bash
-# 比較任務數量
-echo "舊系統:"
-node -e "
-const fs = require('fs');
-const data = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-console.log(\`總任務數: \${data.tasks.length}\`);
-"
-
-echo ""
-echo "新系統:"
-node -e "
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-(async () => {
-  const data = await api.getAllTasks();
-  console.log(\`總任務數: \${data.statistics.total}\`);
-  console.log(\`Pending: \${data.statistics.pending}\`);
-  console.log(\`In Progress: \${data.statistics.in_progress}\`);
-  console.log(\`Completed: \${data.statistics.completed}\`);
-})();
-"
-
-# 檢查每個任務
-node .collaboration/cli/task-cli.js list
-```
-
----
-
-### 步驟 5：提交遷移
-
-```bash
-# 加入所有新任務
-git add .collaboration/tasks/
-
-# 加入 ID 映射表
-git add .migration/
-
-# 提交
-git commit -m "feat: 遷移任務系統從 dev/pipeline 到 .collaboration
-
-- 遷移 10 個任務
-- 重建所有索引
-- 保留 ID 映射表供回滾使用
-
-BREAKING CHANGE: 任務 ID 格式從 TASK_XXX 改為 TASK_XXXXXXXXXXXX
-"
-
-# 推送
-git push origin migration/collaboration-system
-
-# 建立 PR（可選）
-gh pr create \
-  --title "feat: 遷移到 .collaboration 任務系統" \
-  --body "完整遷移舊系統任務到新系統，詳見提交訊息"
-```
-
----
-
-### 步驟 6：更新團隊工具
-
-更新 Dashboard 和其他工具以使用新系統：
-
-```javascript
-// 在 Dashboard 中使用統一 API
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-// 取得所有任務（自動合併新舊系統）
-const allData = await api.getAllTasks();
-
-// Dashboard 會自動顯示來源標記
-// 🆕 - 新系統任務
-// 📦 - 舊系統任務（如果還有）
-```
-
----
-
-### 步驟 7：封存舊系統（可選）
-
-等待團隊適應新系統後（建議 2 週），封存舊系統：
-
-```bash
-# 移動舊系統到封存目錄
-mkdir -p .archive/old-pipeline/$(date +%Y%m%d)
-mv dev/pipeline/TASK_QUEUE.json .archive/old-pipeline/$(date +%Y%m%d)/
-
-# 提交
-git add .
-git commit -m "chore: 封存舊任務系統"
-git push
-```
-
----
-
-## 遷移工具
-
-### ID 映射表查詢工具
-
-```javascript
-// .collaboration/tools/lookup-old-id.js
-const fs = require('fs');
-
-const mapping = JSON.parse(fs.readFileSync('.migration/id_mapping.json', 'utf8'));
-const oldId = process.argv[2];
-
-if (mapping[oldId]) {
-  console.log(`${oldId} → ${mapping[oldId]}`);
-} else {
-  console.log(`❌ 未找到對應的新 ID`);
-}
-```
-
-**使用**:
-```bash
-node .collaboration/tools/lookup-old-id.js TASK_147
-# 輸出: TASK_147 → TASK_5KPEES80F922
-```
-
----
-
-### 依賴關係檢查工具
-
-```javascript
-// .collaboration/tools/check-dependencies.js
-const { TaskAPI } = require('../core/task-api.js');
-
-(async () => {
-  const api = new TaskAPI();
-  const allData = await api.getAllTasks();
-
-  console.log('檢查依賴關係...\n');
-
-  for (const task of allData.tasks) {
-    if (task.dependencies && task.dependencies.length > 0) {
-      for (const depId of task.dependencies) {
-        const depTask = await api.getTask(depId);
-        if (!depTask) {
-          console.log(`❌ ${task.id}: 依賴任務不存在 ${depId}`);
-        } else {
-          console.log(`✅ ${task.id} → ${depId} (${depTask.status})`);
-        }
-      }
-    }
-  }
-})();
-```
-
----
-
-## 驗證遷移
-
-### 驗證清單
-
-- [ ] 任務數量一致
-- [ ] 所有狀態正確遷移
-- [ ] 優先級正確
-- [ ] 依賴關係完整
-- [ ] 索引正常工作
-- [ ] CLI 命令正常
-- [ ] Dashboard 正常顯示
-- [ ] Git 提交乾淨無衝突
-
-### 自動驗證腳本
-
-```bash
-# .collaboration/tools/validate-migration.sh
-#!/bin/bash
-
-echo "🔍 驗證遷移結果..."
-echo ""
-
-# 1. 檢查任務數量
-echo "1️⃣ 檢查任務數量..."
-OLD_COUNT=$(node -e "console.log(JSON.parse(require('fs').readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8')).tasks.length)")
-NEW_COUNT=$(ls .collaboration/tasks/db/all/*.json 2>/dev/null | wc -l)
-
-if [ "$OLD_COUNT" -eq "$NEW_COUNT" ]; then
-  echo "✅ 任務數量一致: $NEW_COUNT 個"
-else
-  echo "❌ 任務數量不一致: 舊 $OLD_COUNT vs 新 $NEW_COUNT"
-  exit 1
-fi
-
-# 2. 檢查索引
-echo ""
-echo "2️⃣ 檢查索引..."
-if [ -d ".collaboration/tasks/index/" ]; then
-  echo "✅ 索引目錄存在"
-else
-  echo "❌ 索引目錄不存在"
-  exit 1
-fi
-
-# 3. 測試 CLI
-echo ""
-echo "3️⃣ 測試 CLI..."
-if node .collaboration/cli/task-cli.js list > /dev/null 2>&1; then
-  echo "✅ CLI 正常工作"
-else
-  echo "❌ CLI 執行失敗"
-  exit 1
-fi
-
-# 4. 測試 API
-echo ""
-echo "4️⃣ 測試 API..."
-if node -e "
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-(async () => {
-  await api.getAllTasks();
-  console.log('✅ API 正常工作');
-})().catch(e => { console.error('❌ API 執行失敗'); process.exit(1); });
-"; then
-  :
-else
-  exit 1
-fi
-
-echo ""
-echo "🎉 驗證通過！"
-```
-
-**執行驗證**:
-```bash
-bash .collaboration/tools/validate-migration.sh
-```
-
----
-
-## 回滾計劃
-
-### 完全回滾（恢復到舊系統）
-
-```bash
-# 1. 切換到遷移前的提交
-git log --oneline | grep "遷移前的檢查點"
-git revert <commit-hash>
-
-# 2. 恢復備份
-cp .migration/backup/20260211/TASK_QUEUE.json dev/pipeline/
-
-# 3. 刪除新系統（可選）
-rm -rf .collaboration/tasks/db/all/*.json
-
-# 4. 提交
-git add .
-git commit -m "revert: 回滾到舊任務系統"
-git push
-```
-
----
-
-### 部分回滾（保留新任務，恢復舊 ID）
-
-如果需要保留新系統但恢復舊 ID 格式：
-
-```javascript
-// .collaboration/tools/rollback-ids.js
-const fs = require('fs').promises;
-const path = require('path');
-
-async function rollbackIds() {
-  const mapping = JSON.parse(
-    await fs.readFile('.migration/id_mapping.json', 'utf8')
-  );
-
-  // 反轉映射
-  const reverseMapping = {};
-  for (const [oldId, newId] of Object.entries(mapping)) {
-    reverseMapping[newId] = oldId;
-  }
-
-  // 遍歷所有任務
-  const tasksDir = '.collaboration/tasks/db/all';
-  const files = await fs.readdir(tasksDir);
-
-  for (const file of files) {
-    if (!file.endsWith('.json')) continue;
-
-    const taskPath = path.join(tasksDir, file);
-    const task = JSON.parse(await fs.readFile(taskPath, 'utf8'));
-
-    const newId = path.basename(file, '.json');
-    const oldId = reverseMapping[newId];
-
-    if (oldId) {
-      task.id = oldId;
-
-      // 更新依賴
-      if (task.dependencies) {
-        task.dependencies = task.dependencies.map(d => reverseMapping[d] || d);
-      }
-
-      // 重新命名文件
-      const newPath = path.join(tasksDir, `${oldId}.json`);
-      await fs.writeFile(newPath, JSON.stringify(task, null, 2));
-      await fs.unlink(taskPath);
-
-      console.log(`✅ 回滾: ${newId} → ${oldId}`);
-    }
-  }
-
-  console.log('回滾完成！');
-}
-
-rollbackIds().catch(console.error);
-```
-
----
-
-## 常見問題
-
-### Q1: 遷移需要多久？
-
-**A**: 取決於任務數量：
-- < 10 個任務：5-10 分鐘（手動）
-- 10-50 個任務：15-30 分鐘（自動腳本）
-- > 50 個任務：30-60 分鐘（自動腳本 + 驗證）
-
----
-
-### Q2: 是否可以漸進式遷移？
-
-**A**: 可以！新系統支援與舊系統並存：
-
-```javascript
-// 統一 API 自動合併兩個系統
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-const allData = await api.getAllTasks();
-// 包含舊系統（TASK_QUEUE.json）和新系統（.collaboration/tasks/db/）的任務
-```
-
-**建議策略**：
-1. 新任務使用新系統建立
-2. 舊任務保持不動
-3. 當舊任務完成時，自動封存
-4. 3 個月後全部遷移到新系統
-
----
-
-### Q3: 如何處理進行中的任務？
-
-**A**: 遷移時保留狀態：
-
-```javascript
-// 遷移腳本會保留所有欄位
-const newTask = {
-  ...oldTask,
-  status: oldTask.status,  // 保留 in_progress
-  assigned_to: { ... },    // 保留分配資訊
-  _version: 1
-};
-```
-
-建議在非工作時間（週末）遷移，減少影響。
-
----
-
-### Q4: 依賴關係如何處理？
-
-**A**: 自動更新為新 ID：
-
-```javascript
-// 遷移腳本會自動處理
-task.dependencies = task.dependencies.map(oldDepId => {
-  return idMapping[oldDepId] || oldDepId;
-});
-```
-
-如果發現依賴錯誤，使用檢查工具：
-```bash
-node .collaboration/tools/check-dependencies.js
-```
-
----
-
-### Q5: 遷移後如何查找舊 ID？
-
-**A**: 使用 ID 映射表：
-
-```bash
-# 查詢工具
-node .collaboration/tools/lookup-old-id.js TASK_147
-
-# 或直接查看映射表
-cat .migration/id_mapping.json | grep "TASK_147"
-```
-
-映射表範例：
-```json
-{
-  "TASK_147": "TASK_5KPEES80F922",
-  "TASK_148": "TASK_5KPEES80HT6S",
-  ...
-}
-```
-
----
-
-## 最佳實踐
-
-### 1. 在遷移分支上進行
-
-```bash
-# 建立遷移分支
-git checkout -b migration/collaboration-system
-
-# 遷移完成後合併
-git checkout main
-git merge migration/collaboration-system
-```
-
----
-
-### 2. 分階段驗證
-
-```bash
-# 階段 1：遷移 10%
-node .collaboration/tools/migrate.js --limit 10
-
-# 驗證
-bash .collaboration/tools/validate-migration.sh
-
-# 階段 2：遷移全部
-node .collaboration/tools/migrate.js
-```
-
----
-
-### 3. 保留備份至少 3 個月
-
-```bash
-# 備份目錄結構
-.migration/
-├── backup/
-│   ├── 20260211/        # 第一次備份
-│   ├── 20260312/        # 第二次備份
-│   └── 20260411/        # 第三次備份
-└── id_mapping.json      # ID 映射表
-```
-
----
-
-### 4. 通知團隊成員
-
-**遷移前通知**（提前 3 天）：
-```
-📢 任務系統遷移通知
-
-我們將在 2026-02-14（週六）進行任務系統遷移。
-
-變更：
-- 任務 ID 格式：TASK_147 → TASK_5KPEES80F922
-- 新增 CLI 工具：task-cli.js
-- Git 衝突大幅減少
-
-準備：
-- 請在 2/13 前完成所有進行中的任務
-- 2/14 當天不要建立新任務
-- 遷移後查看 ID 映射表：.migration/id_mapping.json
-```
-
-**遷移後通知**：
-```
-✅ 任務系統遷移完成
-
-新功能：
-- 使用 `task list` 查看任務
-- 使用 `task claim TASK_XXX` 認領任務
-- 詳見文檔：.collaboration/docs/CLI.md
-
-如有問題請聯繫 IT 支援。
-```
-
----
-
-### 5. 建立遷移日誌
-
-```markdown
-# 遷移日誌
-
-## 2026-02-11 14:00 - 開始遷移
-- 建立備份
-- 建立遷移分支
-
-## 2026-02-11 14:30 - 執行遷移腳本
-- 遷移 10 個任務
-- 生成 ID 映射表
-
-## 2026-02-11 15:00 - 驗證
-- ✅ 任務數量一致
-- ✅ 依賴關係正確
-- ✅ CLI 測試通過
-
-## 2026-02-11 15:30 - 提交
-- 提交到遷移分支
-- 建立 PR
-
-## 2026-02-12 10:00 - 合併到 main
-- PR 審查通過
-- 合併到 main
-- 通知團隊
-
-## 2026-02-15 - 封存舊系統
-- 無重大問題
-- 封存 TASK_QUEUE.json
-```
-
----
-
-## 相關文檔
-
-- [API 參考文檔](./API.md) - JavaScript API 完整文檔
-- [CLI 使用指南](./CLI.md) - 命令列工具文檔
-- [常見問題](./FAQ.md) - 疑難排解指南
-- [架構設計](./ARCHITECTURE.md) - 系統架構詳細說明
-
----
-
-**版本**: 1.0.0
-**最後更新**: 2026-02-11
-**維護者**: Developer Team