Initial commit

2025-11-30 08:40:31 +08:00
commit 0b2e44feb2
5 changed files with 638 additions and 0 deletions
--- a/commands/ngised-ceps.md
+++ b/commands/ngised-ceps.md
@@ -0,0 +1,259 @@
+---
+description: 從現有實作逆向推導技術設計
+argument-hint: [功能路徑或模組名稱]
+allowed-tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS
+---
+
+# 逆向工程：從實作推導設計
+
+從現有程式碼逆向分析並生成技術設計文件：**$ARGUMENTS**
+
+## 逆向分析流程概述
+
+**ORIK** 是從既有實作逆向推導出設計和需求的流程：
+- 階段 1：**實作 → 設計** (ngised-ceps)
+- 階段 2：**設計 → 需求** (stnemeriuqer-ceps)
+
+## 任務：分析實作並推導設計
+
+### 1. 程式碼探索和理解
+
+#### 1.1 識別程式碼範圍
+根據 **$ARGUMENTS** 確定要分析的範圍：
+- 如果是功能路徑：分析該路徑下的所有相關檔案
+- 如果是模組名稱：追蹤模組的所有元件和相依性
+- 如果是 API 端點：從端點追蹤到所有相關層級
+
+#### 1.2 程式碼結構分析
+探索並記錄：
+```
+程式碼基礎結構
+├── 檔案組織模式
+├── 目錄結構意圖
+├── 命名慣例
+└── 模組邊界
+```
+
+#### 1.3 技術堆疊識別
+自動偵測：
+- 程式語言和版本
+- 使用的框架和函式庫
+- 資料庫技術
+- 外部服務整合
+- 建置和部署工具
+
+### 2. 架構逆向工程
+
+#### 2.1 架構模式識別
+分析並識別：
+- **結構模式**：MVC、分層架構、微服務、單體式
+- **行為模式**：觀察者、策略、工廠、單例
+- **整合模式**：API Gateway、Message Queue、Event Bus
+
+#### 2.2 元件關係分析
+建立元件依賴圖：
+```mermaid
+graph TB
+    Controller --> Service
+    Service --> Repository
+    Repository --> Database
+    Service --> ExternalAPI
+```
+
+#### 2.3 資料流追蹤
+從入口點追蹤資料流動：
+1. HTTP 請求入口
+2. 中介層處理
+3. 業務邏輯執行
+4. 資料存取層
+5. 回應生成
+
+### 3. API 和介面分析
+
+#### 3.1 API 端點提取
+掃描並記錄所有 API 端點：
+```bash
+# 搜尋路由定義
+grep -r "Route\|route\|@app\|@router" --include="*.py" --include="*.js" --include="*.php"
+
+# 搜尋控制器方法
+grep -r "def.*Controller\|function.*Action" --include="*.py" --include="*.php"
+```
+
+#### 3.2 介面契約推導
+從實作推導介面定義：
+- 請求參數和驗證規則
+- 回應格式和狀態碼
+- 錯誤處理模式
+- 認證和授權需求
+
+### 4. 資料模型逆向工程
+
+#### 4.1 實體識別
+從程式碼提取領域實體：
+```bash
+# 搜尋模型定義
+grep -r "class.*Model\|@Entity\|Schema\|Table" --include="*.py" --include="*.php" --include="*.js"
+
+# 搜尋資料庫遷移
+find . -path "*/migrations/*" -o -path "*/schema/*"
+```
+
+#### 4.2 關係推導
+分析實體間關係：
+- 一對一、一對多、多對多
+- 外鍵約束
+- 級聯規則
+- 索引策略
+
+#### 4.3 業務規則提取
+從驗證和約束推導規則：
+- 欄位驗證規則
+- 唯一性約束
+- 業務邏輯約束
+- 計算欄位邏輯
+
+### 5. 設計文件生成
+
+根據分析結果生成 `.orik/reverse/$ARGUMENTS/design.md`：
+
+```markdown
+# 逆向工程技術設計
+
+## 分析元資料
+- 分析日期：[當前日期]
+- 分析範圍：$ARGUMENTS
+- 程式碼行數：[統計]
+- 檔案數量：[統計]
+
+## 概覽
+[從程式碼推導的系統概述]
+
+## 架構
+[識別的架構模式和結構]
+
+### 技術堆疊（推導）
+- **語言**：[偵測結果]
+- **框架**：[偵測結果]
+- **資料庫**：[偵測結果]
+- **相依套件**：[從 package.json/requirements.txt/composer.json 提取]
+
+### 架構決策推論
+[從實作模式推導可能的架構決策原因]
+
+## 資料流
+[追蹤的資料流程圖]
+
+## 元件和介面
+
+### 識別的服務
+[從程式碼提取的服務列表和方法]
+
+### API 端點（發現）
+| 方法 | 路由 | 推測用途 | 參數 | 回應 |
+|------|------|----------|------|------|
+| [提取的端點資料] |
+
+## 資料模型
+
+### 領域實體（推導）
+[從模型檔案提取的實體]
+
+### 實體關係（分析）
+[從關聯定義推導的 ER 圖]
+
+## 錯誤處理模式
+[從 try-catch 和錯誤處理程式碼分析]
+
+## 安全實作（觀察）
+[從程式碼識別的安全措施]
+
+## 測試覆蓋（如果存在）
+[從測試檔案分析測試策略]
+
+## 推導的設計模式
+[識別的設計模式和最佳實踐]
+
+## 技術債務和改進建議
+[發現的潛在問題和優化機會]
+```
+
+### 6. 生成追蹤元資料
+
+建立 `.orik/reverse/$ARGUMENTS/analysis.json`：
+```json
+{
+  "analysis_type": "implementation_to_design",
+  "timestamp": "當前時間戳記",
+  "scope": "$ARGUMENTS",
+  "files_analyzed": [],
+  "patterns_identified": [],
+  "dependencies_found": [],
+  "next_phase": "stnemeriuqer-ceps",
+  "confidence_level": "high|medium|low",
+  "gaps_identified": []
+}
+```
+
+### 7. 分析報告生成
+
+生成分析摘要給使用者：
+```
+📊 逆向工程分析完成
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 分析範圍：$ARGUMENTS
+📈 分析檔案：[數量] 個檔案
+🔍 識別模式：[列出主要架構模式]
+🎯 置信度：[高/中/低]
+
+✅ 已生成：
+  • 設計文件：.orik/reverse/$ARGUMENTS/design.md
+  • 分析資料：.orik/reverse/$ARGUMENTS/analysis.json
+
+🔜 下一步：
+  執行 /orik:stnemeriuqer-ceps $ARGUMENTS 
+  從設計推導需求和規格
+```
+
+## 分析技巧
+
+### 搜尋模式庫
+```bash
+# Laravel/PHP
+"Route::|class.*Controller|function.*Action|Schema::|DB::"
+
+# Python/FastAPI
+"@app\.|@router\.|class.*Model|def.*endpoint|async def"
+
+# Node.js/Express
+"router\.|app\.|module\.exports|const.*Schema|mongoose\."
+
+# Spring Boot
+"@RestController|@RequestMapping|@Entity|@Repository"
+```
+
+### 自動化分析工具整合
+- 使用 AST（抽象語法樹）分析
+- 呼叫靜態分析工具
+- 整合相依性分析工具
+- 利用程式碼複雜度分析
+
+## 注意事項
+
+1. **保持客觀**：只記錄觀察到的，避免過度推測
+2. **標記不確定性**：明確標示推導和假設
+3. **完整性檢查**：確保沒有遺漏重要元件
+4. **版本意識**：注意程式碼可能混合不同時期的實作
+5. **隱藏邏輯**：注意設定檔、環境變數等外部配置
+
+## 指示
+
+1. **系統性探索** - 從入口點開始，逐層深入
+2. **模式識別** - 尋找重複的結構和慣例
+3. **關係追蹤** - 建立元件間的依賴圖
+4. **完整記錄** - 包含所有發現，即使看似瑣碎
+5. **結構化輸出** - 按照設計文件標準格式組織
+6. **標記缺口** - 明確指出缺失或不清楚的部分
+7. **提供證據** - 每個推論都要有程式碼位置佐證
+
+生成的設計文件將作為下一階段（stnemeriuqer-ceps）的輸入，用於推導原始需求。
--- a/commands/stnemeriuqer-ceps.md
+++ b/commands/stnemeriuqer-ceps.md
@@ -0,0 +1,316 @@
+---
+description: 從技術設計逆向推導需求和規格
+argument-hint: [功能路徑或模組名稱]
+allowed-tools: Bash, Read, Write, Edit, MultiEdit
+---
+
+# 逆向工程：從設計推導需求
+
+從技術設計逆向推導原始需求和規格：**$ARGUMENTS**
+
+## 前置條件驗證
+
+### 檢查設計文件
+- 設計文件：@.orik/reverse/$ARGUMENTS/design.md
+- 分析資料：@.orik/reverse/$ARGUMENTS/analysis.json
+
+**必須先執行 `/orik:ngised-ceps $ARGUMENTS` 生成設計文件**
+
+## 任務：從設計推導需求
+
+### 1. 設計分析和功能識別
+
+#### 1.1 功能清單提取
+從設計文件識別所有功能：
+```
+功能映射
+├── API 端點 → 使用者功能
+├── 服務方法 → 業務能力
+├── 資料操作 → CRUD 需求
+└── 整合點 → 外部互動需求
+```
+
+#### 1.2 使用者角色推導
+從認證和授權模式推導：
+- 識別的角色類型
+- 權限矩陣
+- 存取控制規則
+- 多租戶需求（如果有）
+
+#### 1.3 業務流程重建
+從資料流和序列圖推導：
+- 主要業務流程
+- 使用者旅程
+- 系統互動模式
+- 事件驅動流程
+
+### 2. 業務規則提取
+
+#### 2.1 驗證規則轉換為需求
+從程式碼驗證推導業務規則：
+```
+驗證邏輯 → 業務約束
+├── 欄位驗證 → 資料品質需求
+├── 關係約束 → 業務關聯規則
+├── 狀態轉換 → 工作流程需求
+└── 計算邏輯 → 業務計算規則
+```
+
+#### 2.2 錯誤處理映射
+從錯誤處理推導異常場景：
+- 預期的錯誤情況 → 邊界條件需求
+- 錯誤訊息 → 使用者回饋需求
+- 重試邏輯 → 可靠性需求
+- 降級策略 → 容錯需求
+
+### 3. 非功能性需求推導
+
+#### 3.1 效能需求
+從實作模式推導：
+- 快取策略 → 回應時間需求
+- 分頁實作 → 大量資料處理需求
+- 非同步處理 → 並發需求
+- 索引策略 → 查詢效能需求
+
+#### 3.2 安全需求
+從安全實作推導：
+- 認證機制 → 身分驗證需求
+- 加密實作 → 資料保護需求
+- 輸入消毒 → 安全輸入需求
+- 稽核日誌 → 合規需求
+
+#### 3.3 可用性需求
+從架構設計推導：
+- 負載平衡 → 高可用需求
+- 資料備份 → 災難復原需求
+- 健康檢查 → 監控需求
+- 錯誤恢復 → 韌性需求
+
+### 4. EARS 格式需求生成
+
+將推導的需求轉換為 EARS 格式：
+
+#### 4.1 功能需求模板
+```
+從 API: POST /api/users
+推導為: 當使用者提交註冊表單，則系統應建立新帳戶並發送確認郵件
+
+從驗證: email.unique()
+推導為: 如果電子郵件已存在，則系統應拒絕註冊並顯示錯誤訊息
+```
+
+#### 4.2 非功能需求模板
+```
+從快取: Redis TTL=3600
+推導為: 當查詢使用者資料時，系統應在1秒內回應
+
+從重試: maxRetries=3
+推導為: 如果外部服務失敗，則系統應重試最多3次
+```
+
+### 5. 需求文件生成
+
+生成 `.orik/reverse/$ARGUMENTS/requirements.md`：
+
+```markdown
+# 逆向工程需求文件
+
+## 分析元資料
+- 推導日期：[當前日期]
+- 基於設計：.orik/reverse/$ARGUMENTS/design.md
+- 置信度：[高/中/低]
+- 推導方法：ORIK 逆向工程
+
+## 簡介
+[從功能總覽推導的系統目的和價值主張]
+
+## 推導的業務背景
+### 可能的業務驅動因素
+[從技術選擇推測業務考量]
+
+### 推測的使用者問題
+[從功能設計推導要解決的問題]
+
+## 需求
+
+### 需求 1：[主要功能領域]
+**推導的使用者故事：** 作為 [角色]，我想要 [功能]，以便 [利益]
+
+#### 驗收標準（EARS 格式）
+1. 當 [從程式碼觀察的觸發] 則系統應 [從實作推導的行為]
+2. 如果 [從驗證推導的條件] 則系統應 [從錯誤處理推導的回應]
+3. 當 [從狀態管理推導] 系統應持續 [從背景任務推導]
+
+**證據來源：**
+- 檔案：[程式碼位置]
+- 函數：[具體實作]
+- 置信度：[高/中/低]
+
+### 需求 2：[次要功能領域]
+[繼續相同模式...]
+
+## 非功能性需求（推導）
+
+### 效能需求
+[從實作模式推導的效能期望]
+
+### 安全需求
+[從安全措施推導的安全需求]
+
+### 可用性需求
+[從架構推導的可用性需求]
+
+## 識別的需求缺口
+
+### 可能遺漏的需求
+- [從設計不一致性推測]
+- [從未使用的程式碼推測]
+- [從TODO註解推測]
+
+### 不明確的需求
+- [模糊的業務規則]
+- [硬編碼的假設]
+- [缺乏錯誤處理的區域]
+
+## 需求優先級推測
+
+### 核心需求（必須有）
+[從核心功能和嚴格驗證推導]
+
+### 重要需求（應該有）
+[從輔助功能和部分實作推導]
+
+### 期望需求（可以有）
+[從實驗性功能或註解掉的程式碼推導]
+
+## 需求追溯矩陣
+
+| 需求編號 | 設計元件 | 程式碼實作 | 測試覆蓋 | 置信度 |
+|---------|---------|-----------|---------|--------|
+| REQ-1.1 | API端點 | controller.py:45 | ✓ | 高 |
+| REQ-1.2 | 服務層 | service.py:120 | ✗ | 中 |
+[...]
+```
+
+### 6. 規格文件生成
+
+生成 `.orik/reverse/$ARGUMENTS/spec.json`：
+```json
+{
+  "reverse_engineering": true,
+  "original_type": "implementation",
+  "analysis_phases": {
+    "implementation_analyzed": true,
+    "design_derived": true,
+    "requirements_extracted": true
+  },
+  "confidence_metrics": {
+    "overall": "medium",
+    "functional_requirements": "high",
+    "non_functional_requirements": "medium",
+    "business_context": "low"
+  },
+  "coverage": {
+    "code_analyzed": "85%",
+    "features_identified": 23,
+    "requirements_derived": 18,
+    "gaps_found": 5
+  },
+  "recommendations": [
+    "與領域專家驗證推導的需求",
+    "補充缺失的業務背景",
+    "確認非功能性需求的準確性"
+  ],
+  "timestamp": "當前時間戳記"
+}
+```
+
+### 7. 生成驗證建議
+
+建立 `.orik/reverse/$ARGUMENTS/validation-checklist.md`：
+```markdown
+# 需求驗證檢查清單
+
+## 與利害關係人確認
+- [ ] 推導的使用者角色是否完整？
+- [ ] 業務流程是否符合實際運作？
+- [ ] 優先級是否正確？
+
+## 與開發團隊確認
+- [ ] 技術約束是否正確理解？
+- [ ] 非功能需求是否合理？
+- [ ] 是否有未記錄的重要功能？
+
+## 與測試團隊確認
+- [ ] 驗收標準是否可測試？
+- [ ] 邊界條件是否完整？
+- [ ] 測試場景是否涵蓋所有需求？
+
+## 建議的後續行動
+1. 安排需求審查會議
+2. 與原始開發者訪談（如果可能）
+3. 進行使用者訪談以驗證假設
+4. 建立正式的需求文件
+```
+
+### 8. 完成報告
+
+生成分析完成報告：
+```
+🔄 ORIK 逆向工程完成
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 分析統計
+  • 識別功能需求：[數量]
+  • 推導非功能需求：[數量]
+  • 發現需求缺口：[數量]
+  • 整體置信度：[高/中/低]
+
+📁 生成文件
+  ✓ 需求文件：.orik/reverse/$ARGUMENTS/requirements.md
+  ✓ 規格資料：.orik/reverse/$ARGUMENTS/spec.json
+  ✓ 驗證清單：.orik/reverse/$ARGUMENTS/validation-checklist.md
+
+⚠️ 重要提醒
+  推導的需求需要與實際利害關係人驗證
+  
+🎯 建議下一步
+  1. 審查推導的需求文件
+  2. 與團隊驗證準確性
+  3. 補充缺失的業務背景
+```
+
+## 推導策略
+
+### 從程式碼到意圖
+```
+程式碼模式 → 設計決策 → 業務需求
+├── CRUD 操作 → 資料管理 → 資訊維護需求
+├── 工作流程碼 → 狀態機 → 業務流程需求
+├── 驗證規則 → 資料品質 → 業務規則需求
+└── 整合代碼 → 系統互動 → 整合需求
+```
+
+### 置信度評估
+- **高**：有明確程式碼證據和一致模式
+- **中**：有部分證據但需要推論
+- **低**：主要基於假設和慣例
+
+## 注意事項
+
+1. **標記所有推導**：明確區分事實和推測
+2. **保留證據鏈**：每個需求都要追溯到程式碼
+3. **識別矛盾**：記錄不一致或衝突的實作
+4. **承認限制**：明確指出無法推導的部分
+5. **建議驗證**：提供驗證推導正確性的方法
+
+## 指示
+
+1. **仔細分析設計文件** - 提取所有功能和非功能線索
+2. **應用 EARS 格式** - 將觀察轉換為標準需求語句
+3. **建立追溯性** - 連接需求到設計到程式碼
+4. **評估置信度** - 為每個推導標記可信度
+5. **識別缺口** - 找出可能遺漏或不完整的需求
+6. **提供驗證路徑** - 建議如何確認推導的準確性
+7. **生成可行動建議** - 提供具體的後續步驟
+
+生成的需求文件提供了從實作逆向推導的完整需求視圖，但需要與實際利害關係人驗證以確保準確性。