我們將正式踏入Phase3：後端邏輯、API與資料庫串接。

許多人在開發後端時，習慣直接動手寫APIRoute，結果寫到一半才發現：欸？這個欄位前端有傳嗎？、刪除失敗時錯誤碼該回傳400還是404？、更新狀態需要哪些QueryParameters？。

先設計，後編碼（Design-FirstArchitecture）是確保前後端開發不踩坑的核心原則。今天我們將學習如何引導AI繪製Mermaid時序圖（SequenceDiagram）來釐清邏輯，並產出一份符合OpenAPI/RESTful規範的後端API規格書！

1.為什麼要先叫AI畫SequenceDiagram？
時序圖（SequenceDiagram）是釐清多個角色/系統間互動時間軸的最佳工具。透過視覺化的圖表，能幫我們在動筆寫程式碼前，看清以下細節：

認證與權限檢查點（例如：JWT權限驗證放在哪一步？）。

資料庫讀寫時間點（例如：是否需要先SELECT檢查存在，再執行UPDATE？）。

錯誤處理與異常分支（例如：資料不存在時要回傳什麼HTTPCode？）。

[Client]  ---( 1. POST /api/v1/skills )--->  [Next.js API Route]        
                                                    ｜                    
                                           ( 2. Auth & Zod Validation )  
                                                    ｜                   
                                              [ Prisma ORM ]             
                                                    ｜                    
 [Client]  <---( 3. 201 Created + JSON )---   [ Database ]               

2.實戰步驟1：請AI生成Mermaid時序圖
開啟Cursor，對著@docs/api-sequence.md發送Prompt，讓AI繪製新增/更新/刪除技能的互動時序圖：
你是一位資深後端架構師。請幫我為VibePulse的技能管理模組（SkillResource）繪製Mermaid.js的SequenceDiagram，並儲存在docs/api-sequence.md中。

時序圖需求：
1.參與者(Participants)：
-Client(前端ReactApp)
-APIHandler(Next.jsAppRouterAPIRoute)
-Validator(ZodSchemaValidation)
-Database(PrismaORM+PostgreSQL)

2.核心流程涵蓋：
-POST/api/skills(建立技能)：包含Zod欄位驗證失敗(400)與成功寫入資料庫(201)的ALT分支。
-DELETE/api/skills/:id(刪除技能)：包含檢查技能是否存在(404)與成功刪除(200)的ALT分支。

3.格式要求：使用標準sequenceDiagram語法，加入簡明註解。
AI產出的Mermaid時序圖語法：
程式碼片段

sequenceDiagram
    autonumber
    actor Client as 前端 Client
    participant API as API Handler (/api/skills)
    participant Val as Zod Validator
    participant DB as Prisma / Database

    %% POST 流程
    rect rgb(240, 248, 255)
    note over Client, DB: 1. 新增技能流程 (POST)
    Client->>API: POST /api/skills (JSON Payload)
    API->>Val: 執行 safeParse(body)
    
    alt 驗證失敗 (Invalid Payload)
        Val-->>API: 返回 Error Details
        API-->>Client: 400 Bad Request { success: false, error: ... }
    else 驗證成功
        Val-->>API: 返回 Valid Data
        API->>DB: prisma.skill.create({ data })
        DB-->>API: 返回 Created Skill Object
        API-->>Client: 201 Created { success: true, data: skill }
    end
    end

    %% DELETE 流程
    rect rgb(255, 245, 238)
    note over Client, DB: 2. 刪除技能流程 (DELETE)
    Client->>API: DELETE /api/skills/:id
    API->>DB: prisma.skill.findUnique({ where: { id } })
    
    alt 找不到資料 (Not Found)
        DB-->>API: null
        API-->>Client: 404 Not Found { success: false, message: "Skill not found" }
    else 找到資料
        DB-->>API: skill object
        API->>DB: prisma.skill.delete({ where: { id } })
        DB-->>API: Deleted Record
        API-->>Client: 200 OK { success: true, message: "Skill deleted successfully" }
    end
    end

3.實戰步驟2：請AI產出RESTfulAPI規格文件
有了清晰的時序圖後，我們緊接著引導AI將規格標準化，產出一份給前後端團隊（或給AIAgent自己）閱讀的OpenAPI規格草案：
@docs/api-sequence.md(請參考時序圖邏輯)

請根據剛才生成的時序圖，為VibePulse撰寫一份極度嚴謹的API規格文件docs/api-spec.md。

規格要求：
1.端點清單：
-GET/api/skills：支援QueryParams(category,search,status)。
-POST/api/skills：建立新技能。
-PATCH/api/skills/:id：更新熟練度(proficiency)或最後練習時間。
-DELETE/api/skills/:id：刪除指定技能。
2.統一回應格式(UnifiedResponseStandard)：
-成功Response：{"success":true,"data":T,"meta"?:{"total":number}}
-失敗Response：{"success":false,"error":{"code":string,"message":string,"details"?:any}}
3.HTTP狀態碼說明：明確標註200,201,400,404,500的觸發條件與ResponseJSON範例。
AI產出的docs/api-spec.md精選片段：

端點：GET /api/skills
Method: GET

URL: /api/skills

Query Parameters:

category (optional): 'Frontend'  'Backend'  'AI'  'DevOps'

search (optional): string (搜尋標題或標籤)

Response 200 (OK):

{
  "success": true,
  "data": [
    {
      "id": "sk-01",
      "title": "Next.js App Router & Server Actions",
      "category": "Frontend",
      "proficiency": 85,
      "lastPracticedAt": "2026-08-11T14:30:00Z",
      "tags": ["React", "Next.js"],
      "status": "learning",
      "notesCount": 12
    }
  ],
  "meta": {
    "total": 1,
    "page": 1
  }
}

4.Design-First架構檢視與API評估重點
在將這份規格交付給下階段實作APIRoute前，請檢查以下三個重點：

語意化HTTP動詞：

GET：僅用於讀取，不改變伺服器狀態。

POST：建立全新資源。

PATCH：部分更新（例如只更新proficiency欄位，而非覆蓋整個物件）。

DELETE：移除資源。

錯誤結構的一致性：

前端攔截器（Interceptor）只需要判斷res.data.success是否為false，就能統一彈出Toast或錯誤處理，無需為不同端點寫不同的error解析邏輯。

保留Pagination&Metadata擴充空間：

即便MVP目前資料量不大，GETResponse也必須保留meta欄位，以便未來擴充分頁功能。

今天我們正式揭開了後端開發的序幕：

透過自然語言指揮AI生成了Mermaid時序圖，視覺化釐清了API互動與例外分支。

建立了標準化的RESTfulAPI規格書與統一Response/Error格式。

為明天開始的Next.jsAPIRoutes實作奠定了堅實且不會踩坑的基礎！