375 lines
10 KiB
Markdown
375 lines
10 KiB
Markdown
---
|
||
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. **解析使用者輸入**，產生搜尋策略：
|
||
|
||
```json
|
||
{
|
||
"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**：
|
||
```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**：
|
||
```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**：
|
||
```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 行）：
|
||
|
||
```markdown
|
||
# {領域名稱} 調用鏈分析
|
||
|
||
> 自動生成於 {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`)
|
||
|
||
```java
|
||
if (productRepo.existsByName(dto.getName())) {
|
||
throw new ProductExistsException();
|
||
}
|
||
Product product = mapper.toEntity(dto);
|
||
return productRepo.save(product);
|
||
```
|
||
|
||
---
|
||
|
||
## 整體架構圖
|
||
|
||
```mermaid
|
||
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 | Controller | src/.../ProductController.java |
|
||
| ProductServiceImpl | Service | src/.../ProductServiceImpl.java |
|
||
| ProductRepository | Repository | src/.../ProductRepository.java |
|
||
| Product | Entity | src/.../Product.java |
|
||
| ProductDTO | DTO | src/.../ProductDTO.java |
|
||
|
||
---
|
||
|
||
## 驗證摘要
|
||
|
||
| 調用鏈 | 完整性 | 準確性 | 清晰度 | 總分 | 狀態 |
|
||
|--------|--------|--------|--------|------|------|
|
||
| chain-1: 建立商品 | 95 | 90 | 85 | 91 | verified |
|
||
```
|
||
|
||
**文件撰寫規則**：
|
||
- 使用繁體中文
|
||
- 每條調用鏈必須有 **Mermaid sequenceDiagram**
|
||
- 文件末尾必須有 **整體架構 flowchart**
|
||
- 程式碼片段限制 5-10 行
|
||
- 所有檔案引用必須包含行號
|
||
- **禁止**：改善建議、效能優化、測試策略
|
||
|
||
8. 將文件寫入：`.legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md`
|
||
|
||
---
|
||
|
||
## 完成
|
||
|
||
9. 顯示完成摘要：
|
||
|
||
```
|
||
╔═══════════════════════════════════════════════════════════╗
|
||
║ Domain Flow Analyzer - 分析完成 ║
|
||
╚═══════════════════════════════════════════════════════════╝
|
||
|
||
🎯 分析領域: {領域關鍵字}
|
||
|
||
📁 輸出位置: .legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md
|
||
|
||
📊 分析結果:
|
||
- 入口點: {N} 個
|
||
- 調用鏈: {M} 條 (已驗證: {V} 條)
|
||
- 涉及類別: {K} 個
|
||
- 平均驗證分數: {score}
|
||
|
||
📈 調用鏈概覽:
|
||
1. POST /api/products → ProductController.createProduct [91分]
|
||
2. ...
|
||
|
||
🔗 快速導覽:
|
||
- 整體架構圖: DOMAIN-FLOW.md#整體架構圖
|
||
- 調用鏈詳解: DOMAIN-FLOW.md#調用鏈-1-{描述}
|
||
|
||
💡 特色:
|
||
- 單一檔案輸出（約 300 行）
|
||
- 包含 Mermaid 序列圖與架構圖
|
||
- 所有調用鏈經過驗證評分
|
||
```
|
||
|
||
---
|
||
|
||
## 執行時間估算
|
||
|
||
| 階段 | 時間 | 模型 |
|
||
|------|------|------|
|
||
| 入口點發現 | ~30秒 | Haiku |
|
||
| 調用鏈追蹤 | ~1-2分鐘 | Sonnet (並行) |
|
||
| 流程驗證 | ~20秒 | Haiku (並行) |
|
||
| 文件生成 | ~1分鐘 | Sonnet |
|
||
| **總計** | **~2-3分鐘** | |
|
||
|
||
---
|
||
|
||
## 與 analyze-java-domain 的配合使用
|
||
|
||
```
|
||
場景 1: 快速了解流程
|
||
→ 使用 analyze-java-domain-flow（2-3分鐘）
|
||
→ 獲得調用鏈圖表
|
||
|
||
場景 2: 深度了解領域
|
||
→ 先用 analyze-java-domain-flow 掌握流程
|
||
→ 再用 analyze-java-domain 獲得完整文件
|
||
```
|
||
|
||
---
|
||
|
||
## 重要注意事項
|
||
|
||
- **核心輸出**：調用鏈 + Mermaid 流程圖（不包含資料模型、業務規則詳解）
|
||
- **單一檔案**：所有內容整合到一個 Markdown 檔案
|
||
- **驗證機制**：每條調用鏈都有驗證評分，確保準確性
|
||
- **效率優先**：比 analyze-java-domain 快約 50%
|