hanifalkauni/uml-architect

UML-Architect 技能指令

這些指令旨在讓 AI Agent 產生的架構分析與 UML 圖表輸出，能與 UML-Architect MCP 伺服器「100% 相同且一致」。

---

1. 五階段執行協定（執行管線）

階段一：目標解析與程式碼庫檢測

1. 識別目標：
   • 輸入是 API 端點（例如：POST /api/v1/orders/checkout），函式名稱（例如：processPayment），還是檔案/模組路徑（例如：src/controllers/order.controller.ts）？
2. 清單掃描（無需編譯）：
   • 檢查專案中的清單檔：package.json、go.mod、pom.xml、pyproject.toml、Cargo.toml、composer.json、Gemfile 或 *.csproj。
   • 辨識使用的框架：Express/NestJS、FastAPI/Django、Gin/Fiber、Spring Boot、Axum/Actix、ASP.NET、Laravel 或 Rails。

階段二：真實呼叫圖追蹤（嚴格追蹤 - 零幻覺）

從真實原始碼追蹤執行流程：

1. 進入點：開啟相關的路由/控制器檔案。
2. 中介軟體與守衛：追蹤 JWT 令牌檢查、session 驗證、請求結構驗證（Zod、Joi、Pydantic、DTO 驗證器）。
3. 控制器/處理器：檢查請求參數抽取與服務層委派的邏輯。
4. 服務/領域層：追蹤核心業務邏輯、輔助函數呼叫與資料計算。
5. 資料庫與 ORM：追蹤查詢/變更操作（SELECT、INSERT、UPDATE、交易提交/回滾）。
6. 外部整合：追蹤 HTTP 呼叫（Stripe、銀行 API、SendGrid、OAuth）或 RPC 呼叫。
7. 訊息佇列/事件：追蹤非同步事件發布至 Kafka、RabbitMQ、SQS、Redis PubSub 或 Celery。
8. 錯誤分支：將 try/catch、if err != nil、except 或錯誤守衛區塊映射到替代分支（alt）。

---

2. 標準圖表參與者與別名

使用標準的參與者命名規則，使圖表清晰、一致且易於閱讀：

類別	參與者 ID	參與者標籤格式	參與者類型
客戶端/呼叫者	Client	Client / Frontend App（或 User / Mobile App）	actor
控制器/處理器	Ctrl	<檔案名稱/控制器> (Controller)	participant
服務層	Svc	<服務名稱>（例如：OrderService）	participant
第三方/外部	ExtAPI	<供應商/閘道器> (External API)（例如：Stripe API）	participant
資料庫/儲存	DB	Database (Storage / ORM)（例如：PostgreSQL Database）	participant
佇列/事件代理	Queue	Message Broker (Kafka / Queue)	participant

---

3. Mermaid.js 語法規則與視覺主題

1. 主題指令（圖表第一行必須包含）： 預設使用現代 tokyo-night 主題：

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. 序列圖：
   • 務必包含 sequenceDiagram 與 autonumber。
   • 使用 ->> 表示同步呼叫，-->> 表示回應/回傳，-) 表示非同步/佇列事件。
   • 將驗證失敗與成功的分支包裹在 alt 和 else 區塊中：

     alt Validasi Input / Auth Gagal
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validasi Lolos (Happy Path)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. 語法自我修復（避免錯誤）：
   • 避免在訊息中使用未加引號的方括號。
   • 不要在參與者 ID 中使用斜線（/）（務必使用如 Ctrl、Svc 等乾淨的別名）。

---

4. 強制輸出合約格式

每次產生的圖表回應必須遵循下方 Markdown 結構，以確保與 MCP 伺服器輸出一致：

# UML 圖表：<目標/端點名稱>

> *由 **UML-Architect 技能代理** (v1.0.0) 自動產生*

## 視覺圖表
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Frontend App
    participant Ctrl as <控制器名稱> (Controller)
    participant Svc as <服務名稱>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <HTTP_METHOD> <URL_PATH>
    alt Validasi Input / Auth Gagal
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validasi Lolos (Happy Path)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Save / Query Transaction Record
        DB-->>Svc: DB Commit Success
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Success Payload)
    end
```

<details>
<summary>查看替代格式（PlantUML）</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<控制器名稱> (Controller)" as Ctrl
participant "<服務名稱>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <HTTP_METHOD> <URL_PATH>
alt Input / Auth Validation Failed
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validation Passed (Happy Path)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Save / Query Transaction Record
DB --> Svc: DB Commit Success
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Success Payload)
end
@enduml
```
</details>

### 架構流程說明（<目標/端點名稱>）

此執行流程包含 **<N> 個主要元件**：

* **Client / Frontend App** (`Client`)：扮演使用者/呼叫者的角色。
* **<控制器名稱> (Controller)** (`Ctrl`)：扮演請求與回應控管的角色。
* **<服務名稱>** (`Svc`)：扮演領域業務邏輯的提供者。
* **Database (Storage / ORM)** (`DB`)：扮演交易資料持久化的媒介。
* **Message Broker (Kafka / Queue)** (`Queue`)：扮演非同步事件的接收者。

#### 執行步驟詳解：
1. **Client** 發送 `<HTTP_METHOD> <URL_PATH>` 請求給 **Ctrl**。
   * *條件檢查*：若參數無效或身份驗證失敗，流程直接中斷，並回傳 HTTP 400/401 回應。
2. **Ctrl** 將有效的 payload 委派給 **Svc**。
3. **Svc** 對 **DB** 執行查詢/變更，並接收儲存確認。
4. **Ctrl** 發出事件通知到 **Queue**。
5. **Ctrl** 回傳 HTTP 200/201 成功回應給 **Client**。

#### 錯誤處理與例外（錯誤路徑）：
* **ValidationException**：若 payload 不符合結構條件，產生 HTTP `400` 回應。
* **UnauthorizedException**：若授權令牌無效或過期，產生 HTTP `401` 回應。
* **InternalException**：若發生網路故障或資料庫回滾，產生 HTTP `500` 回應。

---

5. 其他圖表類型（若使用者要求）

• 流程圖/活動圖：使用 flowchart TD，搭配圓形開始/結束節點 ([ ... ])、決策菱形 { "條件？" } 與處理方塊 [ ... ]。
• 狀態機圖：使用 stateDiagram-v2，包含初始狀態 [*]、轉換狀態、守衛條件與終止狀態 [*]。
• 元件/架構圖：使用 graph TD，搭配巢狀 subgraph（表現層、業務邏輯層、資料與持久層）。