/analyze-java-domain-flow

description: 高效分析 Java Spring Boot 專案的調用鏈與流程圖（單一檔案輸出）
allowed-tools:
  - Task
  - TodoWrite
  - Read
  - Write
  - Glob
  - Grep
  - Bash

Legacy Java Domain Flow Analyzer

專注於**調用鏈追蹤與流程圖生成**的高效領域分析工具。

**使用方式**：

/legacy-analyzer:analyze-java-domain-flow 商品建立
/legacy-analyzer:analyze-java-domain-flow 訂單取消
/legacy-analyzer:analyze-java-domain-flow 用戶登入

**與 analyze-java-domain 的差異**： | 比較項目 | analyze-java-domain | analyze-java-domain-flow | |---------|---------------------|--------------------------| | 輸出檔案 | 6 個 Markdown 檔案 (~850行) | 單一檔案 (~300行) | | 執行時間 | 4-6 分鐘 | 2-3 分鐘 | | 核心內容 | 完整領域文件 | 調用鏈 + 流程圖 | | 資料模型 | 詳細 DTO/Entity 說明 | 僅列出涉及類別 | | 業務規則 | 完整規則文件 | 不包含 |

---

搜尋範圍

**只搜尋**：`.java`、`.xml`（MyBatis Mapper） **排除**：`pom.xml`、`.yml`、`.properties`

---

要執行此操作，請精確遵循以下步驟：

階段 1: 入口點發現（Haiku，~30秒）

1. **解析使用者輸入**，產生搜尋策略：

   {
     "domain": "商品建立",
     "keywords": {
       "chinese": ["商品", "產品", "建立", "新增"],
       "english": ["Product", "Item", "Create", "Add", "Save"],
       "patterns": ["create.*Product", "add.*Product", "Product.*Controller"]
     }
   }

2. 使用 **Haiku 代理**快速定位入口點：

**搜尋策略**（必須限制檔案類型）：

   Grep: pattern="@(Post|Put|Get|Delete)Mapping.*{keyword}" glob="*.java"
   Grep: pattern="class.*{keyword}.*(Controller|Service)" glob="*.java"

**輸出入口點 JSON**：

   {
     "entry_points": [
       {
         "file": "ProductController.java",
         "method": "createProduct",
         "http": "POST /api/products",
         "line": 67
       }
     ],
     "related_classes": ["ProductController", "ProductService", "ProductRepository"]
   }

3. **如果找不到入口點**，終止並建議：

   找不到與「{關鍵字}」相關的程式碼。
   建議：使用英文關鍵字如 "Product" 或 "Order"

---

階段 2: 調用鏈追蹤（Sonnet，~1-2分鐘）

4. 對每個入口點（最多 3 個），啟動 **Sonnet 代理**並行追蹤。

**追蹤規則**：

• 從 Controller → Service → Repository → MyBatis XML
• 最大深度：5 層
• 只追蹤專案內程式碼（遇到框架類別標記為「框架內建」停止）

**追蹤步驟**：

a. 讀取 Controller 方法，找出調用的 Service b. 讀取 Service 實現類別，找出調用的 Repository/其他 Service c. 讀取 Repository，識別 JPA 方法或 MyBatis Mapper d. 如果是 MyBatis，讀取對應的 XML Mapper 檔案

**輸出調用鏈 JSON**：

   {
     "chain_id": "chain-1",
     "entry": "POST /api/products → ProductController.createProduct",
     "nodes": [
       {
         "level": 0,
         "layer": "Controller",
         "class": "ProductController",
         "method": "createProduct(ProductDTO)",
         "file": "src/.../ProductController.java:67-85",
         "calls": ["productService.create"]
       },
       {
         "level": 1,
         "layer": "Service",
         "class": "ProductServiceImpl",
         "method": "create(ProductDTO)",
         "file": "src/.../ProductServiceImpl.java:45-78",
         "annotations": ["@Transactional"],
         "logic": "檢查名稱重複 → 轉換 DTO → 保存",
         "calls": ["productRepo.existsByName", "productRepo.save"]
       },
       {
         "level": 2,
         "layer": "Repository",
         "class": "ProductRepository",
         "method": "save(Product)",
         "file": "src/.../ProductRepository.java:12",
         "type": "JPA 內建方法"
       }
     ],
     "classes_involved": ["ProductController", "ProductServiceImpl", "ProductRepository", "Product", "ProductDTO"]
   }

5. 收集所有調用鏈結果

---

階段 3: 流程驗證與評分（Haiku，~20秒）

6. 對每條調用鏈啟動 **Haiku 代理**進行驗證評分：

**驗證維度**：

• **路徑完整性 (40%)**：調用鏈是否從入口到資料層完整
• **證據準確性 (40%)**：檔案路徑和行號是否正確
• **邏輯清晰度 (20%)**：流程描述是否清楚

**輸出評分 JSON**：

   {
     "chain_id": "chain-1",
     "scores": {
       "completeness": 95,
       "accuracy": 90,
       "clarity": 85
     },
     "total": 91,
     "status": "verified"
   }

**狀態判定**：

• `total >= 80`：verified (已驗證)
• `total >= 60`：partial (部分驗證)
• `total < 60`：unverified (未驗證，標記警告)

---

階段 4: 流程圖與文件生成（Sonnet，~1分鐘）

7. 啟動 **Sonnet 代理**生成單一 Markdown 文件。

**文件結構**（目標 ~300 行）：

   # {領域名稱} 調用鏈分析

   > 自動生成於 {timestamp} | 驗證狀態: {N} 條已驗證

   ## 快速概覽

   | 項目 | 數值 |
   |------|------|
   | 入口點 | {N} 個 |
   | 調用鏈 | {M} 條 |
   | 涉及類別 | {K} 個 |
   | 平均深度 | {D} 層 |

   ## 入口點總覽

   | HTTP 方法 | 路徑 | Controller.方法 | 驗證狀態 |
   |-----------|------|-----------------|----------|
   | POST | /api/products | ProductController.createProduct | verified |

   ---

   ## 調用鏈 1: {簡短描述}

   **入口**: `POST /api/products` → `ProductController.createProduct`
   **狀態**: verified (91分)

   ### 流程圖

   ```mermaid
   sequenceDiagram
       participant C as Controller
       participant S as Service
       participant R as Repository
       participant DB as Database

       C->>S: productService.create(dto)
       S->>S: 檢查名稱重複
       S->>R: productRepo.existsByName(name)
       R->>DB: SELECT EXISTS
       DB-->>R: boolean
       R-->>S: false
       S->>R: productRepo.save(product)
       R->>DB: INSERT
       DB-->>R: Product
       R-->>S: Product
       S-->>C: ProductDTO

調用層級

| 層級 | 類別.方法 | 檔案位置 | 說明 | |------|----------|----------|------| | 0 | ProductController.createProduct | ProductController.java:67 | 接收請求 | | 1 | ProductServiceImpl.create | ProductServiceImpl.java:45 | 業務邏輯 | | 2 | ProductRepository.save | ProductRepository.java:12 | 資料存取 |

關鍵邏輯 (`ProductServiceImpl.java:50-55`)

   if (productRepo.existsByName(dto.getName())) {
       throw new ProductExistsException();
   }
   Product product = mapper.toEntity(dto);
   return productRepo.save(product);

---

整體架構圖

   flowchart TD
       subgraph Controller Layer
           A[ProductController]
       end
       subgraph Service Layer
           B[ProductServiceImpl]
       end
       subgraph Repository Layer
           C[ProductRepository]
       end
       subgraph Database
           D[(products)]
       end

       A -->|createProduct| B
       B -->|existsByName| C
       B -->|save| C
       C --> D

---

涉及類別清單

| 類別 | 類型 | 檔案位置 | |------|------|----------| | ProductController |