/analyze-java-domain

description: 分析 Legacy Java Spring Boot 專案中的特定領域邏輯與業務流程
allowed-tools:
  - Task
  - TodoWrite
  - Read
  - Write
  - Glob
  - Grep
  - Bash

Legacy Java Domain Analyzer

針對使用者指定的領域/功能關鍵字，深度分析 Java Spring Boot 專案中的相關邏輯與完整調用鏈。

**使用方式**：

/legacy-analyzer:analyze-java-domain 請分析商品建立的流程
/legacy-analyzer:analyze-java-domain 分析訂單取消邏輯
/legacy-analyzer:analyze-java-domain 整理用戶註冊流程

**與 analyze-java 的差異**：

• `analyze-java`：掃描全專案，生成完整文件（7-9 分鐘）
• `analyze-java-domain`：定向搜尋特定領域，深度追蹤調用鏈（3-5 分鐘）

---

搜尋範圍限制

**只搜尋以下檔案類型**：

• `.java` - Java 原始碼（Controller, Service, Repository, Entity 等）
• `.xml` - MyBatis Mapper 檔案（SQL 查詢邏輯）

**排除的檔案**：

• `pom.xml` - Maven 依賴定義
• `build.gradle` - Gradle 依賴定義
• `.yml` / `.yaml` / `.properties` - 配置檔（與領域邏輯無關）

**Grep 搜尋時必須使用 glob 參數限制範圍**：

# 正確方式
Grep: pattern="關鍵字" glob="*.java"
Grep: pattern="關鍵字" glob="*.xml" （排除 pom.xml 的結果）

# 錯誤方式（不要這樣做）
Grep: pattern="關鍵字" （會搜尋所有檔案）

---

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

準備工作

1. **解析使用者輸入**，識別：

• **領域關鍵字**（Domain Keywords）：如「商品建立」、「訂單取消」、「用戶註冊」
• **搜尋關鍵字**（Search Keywords）：從領域關鍵字推導出可能的：
• 中文詞彙：商品、產品、建立、新增、創建
• 英文詞彙：Product, Item, Goods, Create, Add, Insert
• 方法名：createProduct, addProduct, insertProduct, saveProduct
• 類別名：ProductController, ProductService, ProductRepository
• API 路徑：/product, /products, /api/product

**輸出搜尋策略 JSON**：

   {
     "user_query": "商品建立的流程",
     "domain": "商品建立",
     "search_keywords": {
       "chinese": ["商品", "產品", "建立", "新增", "創建"],
       "english": ["Product", "Item", "Goods", "Create", "Add", "Save"],
       "method_patterns": ["create.*Product", "add.*Product", "save.*Product", "insert.*Product"],
       "class_patterns": ["Product.*Controller", "Product.*Service", "Product.*Repository"],
       "api_patterns": ["/product", "/products", "POST.*product"]
     }
   }

2. 使用 TodoWrite 建立待辦事項清單

3. 創建工作目錄：`.legacy-analysis/domain-{keyword}-{timestamp}/`

• keyword：領域關鍵字的英文簡寫（如 product-create）

---

階段 1: 快速資格檢查與入口點發現

4. 使用 **Haiku 代理**快速檢查專案並找出入口點：

**代理任務**：

• 確認是 Spring Boot 專案（檢查 pom.xml 或 build.gradle）
• 使用 Grep 搜尋所有搜尋關鍵字，統計匹配數量
• 識別最可能的**入口點**（Entry Points）：
• Controller 類別中包含關鍵字的方法
• API 端點（@RequestMapping, @PostMapping, @GetMapping）

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

   # 搜尋 Controller 中的相關端點（只搜尋 .java）
   Grep: pattern="@(Post|Put|Get|Delete)Mapping.*product" glob="*.java"
   Grep: pattern="@RequestMapping.*product" glob="*.java"

   # 搜尋 Service 中的相關方法（只搜尋 .java）
   Grep: pattern="(create|add|save|insert).*Product" glob="*.java"

   # 搜尋類別定義（只搜尋 .java）
   Grep: pattern="class.*Product.*(Controller|Service|Repository)" glob="*.java"

   # 搜尋 MyBatis Mapper 中的相關 SQL（只搜尋 .xml，排除 pom.xml）
   Grep: pattern="<(select|insert|update|delete).*product" glob="*.xml"
   # 注意：過濾結果時排除 pom.xml

**輸出入口點 JSON**：

   {
     "project_valid": true,
     "total_matches": 45,
     "entry_points": [
       {
         "type": "controller",
         "file": "src/main/java/com/example/controller/ProductController.java",
         "method": "createProduct",
         "http_method": "POST",
         "path": "/api/products",
         "line": 67
       },
       {
         "type": "controller",
         "file": "src/main/java/com/example/controller/ProductController.java",
         "method": "addProduct",
         "http_method": "POST",
         "path": "/api/products/add",
         "line": 112
       }
     ],
     "related_classes": [
       "ProductController",
       "ProductService",
       "ProductServiceImpl",
       "ProductRepository",
       "Product",
       "ProductDTO"
     ]
   }

**如果匹配數量 = 0**，輸出建議並終止：

   ❌ 找不到與「{領域關鍵字}」相關的程式碼

   建議嘗試：
   1. 使用不同的關鍵字（如「商品」改為「Product」或「Item」）
   2. 確認專案中是否有此功能
   3. 使用 /legacy-analyzer:analyze-java 進行全專案掃描

5. 將入口點資訊寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/01-entry-points.json`

---

階段 2: 深度調用鏈追蹤

6. 對於每個入口點，啟動一個 **Sonnet 代理**進行深度追蹤。

**如果入口點 <= 3 個**：全部並行啟動 **如果入口點 > 3 個**：只追蹤最重要的 3 個（根據 HTTP 方法優先級：POST > PUT > DELETE > GET）

**每個追蹤代理的任務**：

從入口點開始，遞歸追蹤完整的調用鏈：

   Controller.method()
     ↓ 調用
   Service.method()
     ↓ 調用
   Repository.method()
     ↓ 操作
   Entity

**追蹤步驟**：

a. **讀取入口 Controller 方法**：

• 使用 Read 讀取 Controller 檔案（.java）
• 找到目標方法
• 識別方法內調用的 Service

b. **追蹤 Service 層**：

• 讀取 Service 介面和實現類別（.java）
• 分析業務邏輯
• 識別調用的 Repository 和其他 Service

c. **追蹤 Repository 層**：

• 讀取 Repository 介面（.java）
• 識別自定義查詢方法
• **如果使用 MyBatis**：搜尋對應的 Mapper XML 檔案

        # 根據 Repository/Mapper 介面名稱搜尋對應的 XML
        Glob: pattern="**/ProductMapper.xml"
        # 或搜尋 XML 中的 namespace
        Grep: pattern="namespace.*ProductMapper" glob="*.xml"

d. **追蹤 MyBatis Mapper XML**（如果存在）：

• 讀取 Mapper XML 檔案
• 分析 SQL 語句（select, insert, update, delete）
• 識別動態 SQL（if, choose, foreach）
• 記錄 resultMap 和參數映射

e. **分析相關 Entity**：

• 讀取涉及的 Entity 類別（.java）
• 分析欄位和關聯關係

f. **識別橫切關注點**：

• @Transactional 事務邊界
• 異常處理
• 驗證邏輯（@Valid）
• 日誌記錄

**輸出調用鏈 JSON**：

   {
     "entry_point": {
       "file": "ProductController.java",
       "method": "createProduct",
       "line": 67
     },
     "call_chain": [
       {
         "level": 0,
         "type": "controller",
         "class": "ProductController",
         "method": "createProduct(ProductDTO)",
         "file": "src/.../ProductController.java",
         "lines": "67-85",
         "annotations": ["@PostMapping", "@Valid"],
         "description": "接收商品建立請求，驗證輸入",
         "calls": ["productService.createProduct"]
       },
       {
         "level": 1,
         "type": "service",
         "class": "ProductServiceImpl",
         "method": "createProduct(ProductDTO)",
         "file": "src/.../ProductServiceImpl.java",
         "lines": "45-78",
         "annotations": ["@Transactional"],
         "description