805 lines
26 KiB
Markdown
805 lines
26 KiB
Markdown
---
|
||
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**：
|
||
```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**：
|
||
```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**：
|
||
```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": "核心業務邏輯：檢查商品名稱重複、設定預設值、保存商品",
|
||
"calls": ["productRepository.existsByName", "productRepository.save"],
|
||
"business_rules": [
|
||
"商品名稱不可重複",
|
||
"價格必須大於 0",
|
||
"庫存預設為 0"
|
||
]
|
||
},
|
||
{
|
||
"level": 2,
|
||
"type": "repository",
|
||
"class": "ProductRepository",
|
||
"method": "save(Product)",
|
||
"file": "src/.../ProductRepository.java",
|
||
"lines": "12",
|
||
"description": "JPA 內建方法，保存 Entity 到資料庫",
|
||
"calls": []
|
||
},
|
||
{
|
||
"level": 2,
|
||
"type": "mybatis-mapper",
|
||
"class": "ProductMapper",
|
||
"method": "insertProduct",
|
||
"file": "src/main/resources/mapper/ProductMapper.xml",
|
||
"lines": "25-35",
|
||
"sql_type": "insert",
|
||
"description": "MyBatis INSERT 語句，將商品資料插入 products 表",
|
||
"sql_snippet": "INSERT INTO products (name, price, stock) VALUES (#{name}, #{price}, #{stock})",
|
||
"dynamic_sql": false,
|
||
"calls": []
|
||
}
|
||
],
|
||
"mybatis_mappers": [
|
||
{
|
||
"interface": "ProductMapper.java",
|
||
"xml": "src/main/resources/mapper/ProductMapper.xml",
|
||
"statements": [
|
||
{"id": "insertProduct", "type": "insert", "line": 25},
|
||
{"id": "selectByName", "type": "select", "line": 40}
|
||
]
|
||
}
|
||
],
|
||
"entities_involved": [
|
||
{
|
||
"class": "Product",
|
||
"file": "src/.../entity/Product.java",
|
||
"table": "products",
|
||
"key_fields": ["id", "name", "price", "stock", "categoryId"]
|
||
},
|
||
{
|
||
"class": "ProductDTO",
|
||
"file": "src/.../dto/ProductDTO.java",
|
||
"purpose": "請求/響應資料傳輸物件"
|
||
}
|
||
],
|
||
"cross_cutting": {
|
||
"transaction": "@Transactional on ProductServiceImpl.createProduct",
|
||
"validation": "@Valid on request body",
|
||
"exception_handling": "throws ProductAlreadyExistsException"
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要規則**：
|
||
- ❗ 每個方法引用必須有實際檔案路徑和行號
|
||
- ❗ 使用 Read 驗證每個檔案內容
|
||
- ❗ 如果追蹤到第三方庫（如 JpaRepository），標記為「框架內建」不再深入
|
||
- ❗ 最大追蹤深度：5 層（防止無限遞歸）
|
||
- ❗ 只返回 JSON，不執行 Write 操作
|
||
- ❗ **只讀取 .java 和 .xml 檔案**（排除 pom.xml）
|
||
- ❗ MyBatis Mapper XML 通常位於 `src/main/resources/mapper/` 或類似目錄
|
||
|
||
7. 等待所有追蹤代理完成，收集結果
|
||
|
||
8. 合併所有調用鏈並寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/02-call-chains.json`
|
||
|
||
---
|
||
|
||
## 階段 3: 發現提取與評分
|
||
|
||
9. 從調用鏈中提取**發現（Findings）**：
|
||
|
||
將調用鏈轉換為結構化發現，每個發現代表一個重要的知識點：
|
||
|
||
**發現類型**：
|
||
- `entry-point`：API 入口點
|
||
- `business-logic`：業務邏輯
|
||
- `data-operation`：資料操作
|
||
- `validation`：驗證規則
|
||
- `transaction`：事務管理
|
||
- `exception`：異常處理
|
||
- `entity`：資料模型
|
||
- `mybatis-sql`：MyBatis SQL 語句（來自 .xml mapper）
|
||
- `mybatis-dynamic`：MyBatis 動態 SQL（if, choose, foreach）
|
||
|
||
**發現格式**（與 analyze-java 相容）：
|
||
```json
|
||
{
|
||
"finding_id": "DOMAIN-001",
|
||
"type": "entry-point",
|
||
"title": "商品建立 API 端點",
|
||
"description": "POST /api/products 端點接收商品建立請求，使用 @Valid 驗證輸入的 ProductDTO",
|
||
"evidence": [
|
||
{
|
||
"file": "src/main/java/com/example/controller/ProductController.java",
|
||
"lines": "67-85",
|
||
"snippet": "@PostMapping\npublic ResponseEntity<Product> createProduct(@Valid @RequestBody ProductDTO dto)"
|
||
}
|
||
],
|
||
"importance": "high",
|
||
"call_chain_ref": "chain-1"
|
||
}
|
||
```
|
||
|
||
10. 對每個發現啟動 **Haiku 代理**進行評分（與 analyze-java 相同的評分機制）：
|
||
|
||
**評分維度**：
|
||
- 證據強度 (40%)：檔案路徑驗證、行號準確性
|
||
- 重要性 (30%)：對理解領域邏輯的重要程度
|
||
- 完整性 (15%)：描述是否清晰完整
|
||
- 準確性 (15%)：技術描述是否正確
|
||
|
||
**輸出格式**：
|
||
```json
|
||
{
|
||
"finding_id": "DOMAIN-001",
|
||
"scores": {
|
||
"evidence": 95,
|
||
"importance": 90,
|
||
"completeness": 85,
|
||
"accuracy": 95
|
||
},
|
||
"total_score": 92.25,
|
||
"confidence_level": "very_high"
|
||
}
|
||
```
|
||
|
||
11. ⚠️ **MANDATORY**: 等待所有評分完成，不可跳過
|
||
|
||
12. 將評分結果寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/03-scores.json`
|
||
|
||
---
|
||
|
||
## 階段 4: 過濾與整理
|
||
|
||
13. 應用過濾規則（與 analyze-java 相同）：
|
||
- 保留 total_score >= 75
|
||
- evidence < 60 強制丟棄
|
||
- accuracy < 50 強制丟棄
|
||
- importance >= 90 且 evidence >= 70 例外保留
|
||
|
||
14. 按調用鏈順序組織發現：
|
||
- 將發現按其在調用鏈中的位置排序
|
||
- 標記發現之間的關聯關係
|
||
|
||
15. 寫入結構化資料：`.legacy-analysis/domain-{keyword}-{timestamp}/04-structured.json`
|
||
|
||
---
|
||
|
||
## 階段 5: 領域文件生成（分檔策略）
|
||
|
||
⚠️ **重要：為避免單一文件過大導致 token 限制問題，採用分檔策略**
|
||
|
||
### 文件撰寫原則（核心守則）
|
||
|
||
**文件目的**：幫助工程師/開發者/新人理解現有專案的 domain know-how 與 project design。
|
||
|
||
**必須刪除的內容類型**：
|
||
- ❌ 改善建議、優化建議（如「建議實作快取」、「未來可以加入 A/B Testing」）
|
||
- ❌ 效能優化策略（如「平行處理」、「批次查詢」建議）
|
||
- ❌ 測試代碼範例（測試應該在測試檔案本身查看）
|
||
- ❌ 假設性/範例性程式碼（只保留實際程式碼引用）
|
||
- ❌ 「應該」「建議」「優化」「未來」字眼的段落
|
||
- ❌ 監控與告警建議（如「應該實作的監控指標」）
|
||
|
||
**必須保留的內容類型**：
|
||
- ✅ 現有程式碼的結構與邏輯說明
|
||
- ✅ 實際的業務規則（從程式碼中提取）
|
||
- ✅ 資料模型與關聯關係
|
||
- ✅ 調用鏈與流程圖
|
||
- ✅ 錯誤訊息對照表（現有的）
|
||
- ✅ 檔案位置速查
|
||
|
||
**程式碼引用原則**：
|
||
- 只保留 5-15 行的關鍵邏輯片段
|
||
- 必須標註檔案路徑和行號（如 `ProductService.java:45-60`）
|
||
- 完整代碼應引導讀者查看原始檔案
|
||
- 禁止假設性或簡化範例程式碼
|
||
|
||
**避免重複原則**：
|
||
- API 端點列表只在 00-INDEX.md
|
||
- DTO 欄位說明只在 03-data-model.md
|
||
- 業務規則只在 04-business-rules.md
|
||
- 錯誤碼對照只在 04-business-rules.md
|
||
- 常數定義只在 03-data-model.md
|
||
|
||
---
|
||
|
||
16. **依章節分檔生成**，每個章節由獨立的 **Sonnet 代理**生成：
|
||
|
||
**輸入**（所有代理共用）：
|
||
- 結構化發現 JSON（04-structured.json）
|
||
- 調用鏈 JSON（02-call-chains.json）
|
||
- 入口點 JSON（01-entry-points.json）
|
||
- 使用者原始查詢
|
||
|
||
---
|
||
|
||
### 文件 1: 索引頁 (00-INDEX.md) - 目標 ~50 行
|
||
|
||
由主 session 直接生成，內容：
|
||
- 領域名稱和簡介（2-3 句話）
|
||
- 文件清單與連結
|
||
- API 端點總覽表格（唯一出現位置）
|
||
- 快速統計
|
||
|
||
```markdown
|
||
# {領域名稱} 領域分析
|
||
|
||
> 本文件幫助你理解 {領域名稱} 的現有實作，不包含改善建議。
|
||
|
||
## API 端點總覽
|
||
|
||
| HTTP 方法 | 路徑 | Controller 方法 | 用途 |
|
||
|-----------|------|----------------|------|
|
||
| POST | /api/products | createProduct | 建立商品 |
|
||
| GET | /api/products/{id} | getProduct | 查詢商品 |
|
||
|
||
## 文件索引
|
||
|
||
| 文件 | 說明 | 目標讀者 |
|
||
|------|------|----------|
|
||
| [01-概述](./01-overview.md) | 領域概念、架構全貌 | 新人、PM |
|
||
| [02-調用鏈](./02-call-chains.md) | 程式碼導覽、呼叫路徑 | 開發者 |
|
||
| [03-資料模型](./03-data-model.md) | DTO/Entity/Enum 參考 | 開發者 |
|
||
| [04-業務規則](./04-business-rules.md) | 業務邏輯、錯誤碼 | 開發者、QA |
|
||
| [05-檔案索引](./05-guide.md) | 檔案位置速查 | 開發者 |
|
||
|
||
## 快速統計
|
||
|
||
- 入口點: {N} 個
|
||
- 調用鏈: {M} 條
|
||
- 涉及類別: {K} 個
|
||
```
|
||
|
||
---
|
||
|
||
### 文件 2: 概述 (01-overview.md) - 目標 ~150 行
|
||
|
||
**代理任務**：生成領域概述和架構圖
|
||
|
||
**保留內容**：
|
||
- 簡介（3-5 句話）
|
||
- 核心功能列表（bullet points）
|
||
- 技術特色（使用了什麼框架/模式）
|
||
- 系統架構圖（單一 Mermaid flowchart）
|
||
- 核心類別說明表格（類別名、檔案路徑、職責）
|
||
|
||
**刪除內容**：
|
||
- ❌ 效能考量/優化策略
|
||
- ❌ 未來擴展方向
|
||
- ❌ 測試策略
|
||
- ❌ 詳細 DTO 設計（移到 03-data-model.md）
|
||
- ❌ API 端點列表（已在 00-INDEX.md）
|
||
- ❌ 多個序列圖（只保留一個最重要的）
|
||
|
||
**Mermaid 圖表限制**：
|
||
- 只使用一個整體架構 flowchart
|
||
- 只保留一個最重要 API 的序列圖
|
||
- 序列圖不超過 15 行
|
||
|
||
---
|
||
|
||
### 文件 3: 調用鏈詳解 (02-call-chains.md) - 目標 ~200 行
|
||
|
||
**代理任務**：說明程式碼呼叫路徑
|
||
|
||
**保留內容**：
|
||
- 調用鏈概覽表格（入口點、涉及類別、主要功能）
|
||
- 架構分層說明（Controller → Service → Repository）
|
||
- 每條調用鏈的層級結構（精簡版）：
|
||
- 類別和方法名稱
|
||
- 檔案路徑:行號
|
||
- 3-5 句功能說明
|
||
- 重要註解（@Transactional, @Valid）
|
||
- 共用元件說明
|
||
|
||
**刪除內容**：
|
||
- ❌ 效能瓶頸分析
|
||
- ❌ 優化策略建議
|
||
- ❌ 冗長的程式碼區塊（每個不超過 10 行）
|
||
- ❌ 重複的 Kutt API 整合說明（整合至此文件一次）
|
||
|
||
**程式碼片段限制**：
|
||
- 每個方法只保留關鍵 5-10 行
|
||
- 必須標註 `檔案名:行號`
|
||
- 以 `// ... 完整實作請見原始檔案` 結尾
|
||
|
||
**調用鏈呈現格式**（精簡版）：
|
||
```markdown
|
||
### 調用鏈 1: 建立商品
|
||
|
||
| 層級 | 類別.方法 | 檔案位置 | 說明 |
|
||
|------|----------|----------|------|
|
||
| 0 | ProductController.createProduct | ProductController.java:67 | 接收請求 |
|
||
| 1 | ProductService.createProduct | ProductServiceImpl.java:45 | 業務邏輯 |
|
||
| 2 | ProductRepository.save | ProductRepository.java:12 | 資料存取 |
|
||
|
||
**關鍵邏輯** (`ProductServiceImpl.java:50-55`):
|
||
```java
|
||
if (productRepository.existsByName(dto.getName())) {
|
||
throw new ProductAlreadyExistsException();
|
||
}
|
||
return productRepository.save(product);
|
||
// ... 完整實作請見原始檔案
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
### 文件 4: 資料模型 (03-data-model.md) - 目標 ~200 行
|
||
|
||
**代理任務**：說明資料結構（唯一來源）
|
||
|
||
**保留內容**：
|
||
- DTO/Entity 關係圖（Mermaid erDiagram）
|
||
- Entity 欄位說明表格（類別、欄位、型別、說明）
|
||
- DTO 欄位說明表格
|
||
- Enum 定義表格
|
||
- 常數定義表格（唯一位置）
|
||
- 資料流轉說明（簡短）
|
||
|
||
**刪除內容**：
|
||
- ❌ 效能考量
|
||
- ❌ 測試資料範例
|
||
- ❌ 假設性的表結構
|
||
- ❌ 簡化範例 DTO 程式碼
|
||
|
||
**表格格式範例**：
|
||
```markdown
|
||
## Entity: Product (`ProductEntity.java:15`)
|
||
|
||
| 欄位 | 型別 | 對應資料表欄位 | 說明 |
|
||
|------|------|---------------|------|
|
||
| id | Long | product_id | 主鍵 |
|
||
| name | String | product_name | 商品名稱 |
|
||
```
|
||
|
||
---
|
||
|
||
### 文件 5: 業務規則與異常 (04-business-rules.md) - 目標 ~150 行
|
||
|
||
**代理任務**：整理現有業務規則（唯一來源）
|
||
|
||
**保留內容**：
|
||
- 業務規則清單表格（規則、程式碼位置、說明）
|
||
- 錯誤碼/錯誤訊息對照表（唯一位置）
|
||
- 異常類別列表（類別名、觸發條件、HTTP 狀態碼）
|
||
- 驗證邏輯摘要（@Valid 欄位、自定義驗證）
|
||
|
||
**刪除內容**：
|
||
- ❌ 測試覆蓋建議
|
||
- ❌ 效能考量
|
||
- ❌ 修改指南
|
||
- ❌ 測試 SQL 範例
|
||
|
||
**表格格式範例**：
|
||
```markdown
|
||
## 業務規則
|
||
|
||
| 規則 | 程式碼位置 | 說明 |
|
||
|------|-----------|------|
|
||
| 商品名稱不可重複 | ProductServiceImpl.java:48 | 建立前檢查 |
|
||
| 價格必須大於 0 | ProductDTO.java:23 | @Min(1) 驗證 |
|
||
|
||
## 錯誤碼對照
|
||
|
||
| 錯誤碼 | HTTP 狀態 | 訊息 | 觸發條件 |
|
||
|--------|----------|------|----------|
|
||
| PRODUCT_001 | 409 | 商品名稱已存在 | 名稱重複 |
|
||
```
|
||
|
||
---
|
||
|
||
### 文件 6: 檔案索引 (05-guide.md) - 目標 ~100 行
|
||
|
||
**代理任務**：提供檔案位置速查（最有價值的參考）
|
||
|
||
**保留內容**：
|
||
- 相關檔案清單（按類型分類）
|
||
- Controllers
|
||
- Services
|
||
- Repositories
|
||
- Entities
|
||
- DTOs
|
||
- Mappers (MyBatis XML)
|
||
- 測試檔案位置（僅列出路徑，不詳述）
|
||
- 常見問題列表（僅標題和 1 句說明，不詳述解法）
|
||
|
||
**刪除內容**：
|
||
- ❌ 如何修改此流程（改善建議）
|
||
- ❌ 效能優化建議
|
||
- ❌ 測試策略詳述
|
||
- ❌ 部署與配置詳述
|
||
- ❌ API 測試範例（curl/Postman）
|
||
- ❌ 除錯技巧詳述
|
||
|
||
**檔案清單格式**：
|
||
```markdown
|
||
## 相關檔案
|
||
|
||
### Controllers
|
||
- `src/main/java/.../ProductController.java` - 商品 API 入口
|
||
|
||
### Services
|
||
- `src/main/java/.../ProductService.java` - 介面
|
||
- `src/main/java/.../ProductServiceImpl.java` - 實作
|
||
|
||
### Tests
|
||
- `src/test/java/.../ProductServiceTest.java`
|
||
- `src/test/java/.../ProductControllerTest.java`
|
||
|
||
## 常見問題
|
||
|
||
| 問題 | 相關檔案 |
|
||
|------|----------|
|
||
| 商品建立失敗 | ProductServiceImpl.java:48 |
|
||
| 價格驗證錯誤 | ProductDTO.java:23 |
|
||
```
|
||
|
||
---
|
||
|
||
**撰寫風格**（所有文件通用）：
|
||
- 使用繁體中文
|
||
- 假設讀者不了解此專案
|
||
- 優先使用表格呈現結構化資訊
|
||
- 所有程式碼引用必須有 `檔案名:行號`
|
||
- 每個文件開頭包含返回索引的連結
|
||
- 每個資訊只出現在一個文件中（避免重複）
|
||
- **禁止使用「建議」「應該」「優化」「未來」等字眼**
|
||
|
||
17. **並行生成文件**：
|
||
|
||
啟動 **4 個 Sonnet 代理**並行生成文件 2-5：
|
||
- 代理 A: 生成 `01-overview.md`（目標 ~150 行）
|
||
- 代理 B: 生成 `02-call-chains.md`（目標 ~200 行）
|
||
- 代理 C: 生成 `03-data-model.md`（目標 ~200 行）
|
||
- 代理 D: 生成 `04-business-rules.md`（~150 行）+ `05-guide.md`（~100 行）
|
||
|
||
主 session 同時生成 `00-INDEX.md`（目標 ~50 行）
|
||
|
||
**預期總行數**：約 850 行（相比原本 4000+ 行減少約 80%）
|
||
|
||
18. 將所有文件寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/docs/`
|
||
|
||
```
|
||
docs/
|
||
├── 00-INDEX.md # 索引頁 (~50 行)
|
||
├── 01-overview.md # 概述 (~150 行)
|
||
├── 02-call-chains.md # 調用鏈 (~200 行)
|
||
├── 03-data-model.md # 資料模型 (~200 行)
|
||
├── 04-business-rules.md # 業務規則 (~150 行)
|
||
└── 05-guide.md # 檔案索引 (~100 行)
|
||
```
|
||
|
||
---
|
||
|
||
## 完成
|
||
|
||
19. 顯示完成摘要：
|
||
|
||
```
|
||
╔═══════════════════════════════════════════════════════════╗
|
||
║ Legacy Domain Analyzer - 領域分析完成 ║
|
||
╚═══════════════════════════════════════════════════════════╝
|
||
|
||
🎯 分析領域: {領域關鍵字}
|
||
|
||
📁 工作目錄: .legacy-analysis/domain-{keyword}-{timestamp}/
|
||
|
||
📄 生成的文件:
|
||
├─ 01-entry-points.json (入口點 {N} 個)
|
||
├─ 02-call-chains.json (調用鏈 {M} 條)
|
||
├─ 03-scores.json (評分結果)
|
||
├─ 04-structured.json (結構化發現 {K} 個)
|
||
└─ docs/ (領域分析文件 - 精簡版) ⭐
|
||
├─ 00-INDEX.md (~50 行) 索引與 API 總覽
|
||
├─ 01-overview.md (~150 行) 概述與架構圖
|
||
├─ 02-call-chains.md (~200 行) 調用鏈詳解
|
||
├─ 03-data-model.md (~200 行) 資料模型
|
||
├─ 04-business-rules.md (~150 行) 業務規則
|
||
└─ 05-guide.md (~100 行) 檔案索引
|
||
|
||
📊 分析統計:
|
||
- 總執行時間: {X} 分 {Y} 秒
|
||
- 追蹤的調用鏈: {M} 條
|
||
- 文件總行數: ~850 行（精簡版）
|
||
- 平均置信度: {score}
|
||
|
||
🔗 主要入口點:
|
||
1. POST /api/products → ProductController.createProduct
|
||
2. ...
|
||
|
||
📖 閱讀指南:
|
||
- 新人/PM: 從 00-INDEX.md → 01-overview.md
|
||
- 開發者: 02-call-chains.md → 03-data-model.md
|
||
- QA: 04-business-rules.md
|
||
|
||
💡 文件特色:
|
||
- 專注於「理解現有專案」，不含改善建議
|
||
- 每個資訊只出現一次，無重複內容
|
||
- 所有程式碼引用包含檔案路徑和行號
|
||
- 總計約 850 行（相比完整版減少 80%）
|
||
```
|
||
|
||
---
|
||
|
||
## 重要注意事項
|
||
|
||
- **並行執行**：
|
||
- 階段 2 的追蹤代理（最多 3 個）並行啟動
|
||
- 階段 3 的評分代理全部並行啟動
|
||
- 階段 5 的文件生成代理（4 個）並行啟動
|
||
|
||
- **精簡文件策略**：
|
||
- 採用 6 個精簡文件（總計 ~850 行）
|
||
- 每個文件有明確的目標行數限制
|
||
- 禁止「建議」「應該」「優化」「未來」字眼
|
||
- 每個資訊只出現在一個文件中（避免重複）
|
||
- 程式碼片段限制 5-15 行，引導讀者看原始檔案
|
||
|
||
- **與 analyze-java 的互補性**：
|
||
- 先用 `analyze-java-domain` 理解特定功能
|
||
- 如需全局視角，再用 `analyze-java`
|
||
- 兩者輸出格式相容，可以合併
|
||
|
||
- **搜尋策略優化**：
|
||
- 使用多種關鍵字變體（中英文、駝峰、下劃線）
|
||
- 使用正則表達式匹配方法名模式
|
||
- 從 Controller 開始追蹤，確保找到完整流程
|
||
|
||
- **深度優先 vs 廣度優先**：
|
||
- 此命令採用深度優先策略
|
||
- 完整追蹤一條調用鏈後再追蹤下一條
|
||
- 最大深度 5 層，避免過度追蹤
|
||
|
||
- **時間估算**：
|
||
- 階段 1: 約 30 秒（Haiku 快速掃描）
|
||
- 階段 2: 約 2-3 分鐘（Sonnet 深度追蹤，最多 3 條鏈）
|
||
- 階段 3: 約 10-20 秒（Haiku 評分）
|
||
- 階段 4: 約 10 秒（主 session 處理）
|
||
- 階段 5: 約 1-2 分鐘（4 個 Sonnet 並行生成精簡文件）
|
||
- **總計: 約 4-6 分鐘**
|