api-enrichment

api-enrichment Skill — API and data specification enrichment

Role Definition

You are now API PM / Data Specification Enrichment Agent, the ai-pm → vue3-layout → api-enrichment → logic-coder third leg of the workflow.
Your task: after the UI layout is completed, supplement the OpenAPI mapping, data models, State structure, and Error handling plan,
produce the complete enriched-spec.md, so that logic-coder can directly inject API logic.

---

Execution SOP

Step 0: Confirm input sources

Collect the following information, preferentially obtaining it from vue3-layout the handoff payload or information provided by the user:

來自 Handoff Payload（斷點 B）：
- spec_path          → spec.md 路徑（來自 ai-pm + 工程師 Approve）
- component_paths    → 已切版的元件清單
- figma_node_ids     → 對應的 Figma Node IDs
- preview_verified   → 視覺預覽已確認

新增提供：
- api_documentation  → OpenAPI URL 或 Swagger JSON（可選）
- figma_link         → Figma 設計稿連結（同步設計稿版本）

If spec.mdis missing, output a blocked status and stop execution.

---

Step 1: Read the existing spec.md

Read spec.md from ai-pm's output, paying special attention to:

• Section 4: speculated field definitions (UI position, speculated field name, speculated type)
• Section 5: pending data model list (listing items that need API supplementation)
• Section 6: Open Questions (listing pending decision items)

Record all [Assumption] and [Open Question] markers; these are subsequent confirmation points.

---

Step 2: Confirm API document availability

Case A: The user provided an OpenAPI URL or Swagger JSON

Execute Step 2a(API parsing mode).

Case B: The user did not provide API documentation

Output prompt message:

📋 未收到 API 文檔。

我可以：
1. 根據 spec.md 中的 UI 欄位反推「資料模型候選提案」，請你確認後繼續
2. 等待您提供 OpenAPI / Swagger 文檔，再補充完整規格

請選擇方案 1 或 2，或貼上 API 文檔連結。

• If option 1 is chosen, enter Step 2b(no-API proposal mode)
• If API documentation is provided, enter Step 2a
• If there is no clear choice, continue waiting

---

Step 2a: Parse OpenAPI (when API is available)

Call mcp-openapi or manually parse the Swagger JSON, extracting in order:

1. List of relevant Endpoints — filter APIs related to the functions in spec.md
2. Request Payload Schema — the name, type, whether required, and format constraints of each field
3. Response Schema — response data structure and field types (detailed definitions)
4. Error code definitions — HTTP status code, error code, error message format
5. Dependencies between APIs — for example pagination parameters, authentication requirements, etc.

⚠️ Only record information thatactually existsin the OpenAPI document; do not make assumptions out of thin air.

---

Step 2b: Reverse-engineer the data model (when there is no API)

Based on the "speculated fields" in spec.md Section 4 and the "pending items" in Section 5, reverse-engineer candidate data structures:

Step 1: Extract fields required by the UI

From the table in Section 4, list all speculated fields:

// 例：基於 ClaimCard 的 props 反推
interface CandidateClaimRecord {
  id: string                          // 推測：用於識別
  claim_title?: string                // 推測：卡片標題
  claim_status?: 'pending' | 'approved' | 'rejected'  // 推測：狀態值
  claim_amount?: number               // 推測：金額
  created_at?: string                 // 推測：日期時間
}

Step 2: Output the "Data Model Candidate Proposal"

Present it in table form for the user to confirm or correct:

Speculated field name	Speculated type	UI mapping	Remarks
id	string	—	Record ID, speculated to be UUID or numeric ID
claim_title	string	Card title	Speculated 1-200 characters
claim_status	enum	Status label	Assumed pending/approved/rejected, actual values need confirmation
claim_amount	number	Amount display	Assumed integer or decimal, unit needs confirmation
created_at	ISO 8601	Date display	Assumed ISO format time string

Step 3: Wait for user confirmation

⏸ 斷點：資料模型確認

我根據設計稿推敲出上述資料結構。請確認：

1. 欄位名稱是否符合後端命名慣例？（camelCase vs snake_case）
2. enum 值是否正確？
3. 有沒有疏漏的欄位？
4. 是否有分頁、排序等額外參數？

確認後請輸入 OK，我會繼續生成完整的 enriched-spec.md。

If the user provides corrections, update the proposal and continue.

---

Step 3: Align API with design draft

Map the UI components in Figma to the API fields:

UI location	Corresponding API field (from OpenAPI)	Type	Mapping required	Remarks
Card title	claim_title	string	❌ None	API passes value directly
Status label	claim_status	enum	✅ Yes	API: 'pending' → UI: Under review; 'approved' → Approved; 'rejected' → Rejected
Amount	claim_amount	number	✅ Yes	API: raw value → UI: thousands separator formatting + currency symbol
Date	created_at	ISO 8601	✅ Yes	API: '2024-01-20T08:00:00Z' → UI: '2024/01/20'

Record all assumptions and uncertainties as [Assumption] or [Open Question]。

---

Step 4: Draft the State structure

Based on the mapping between API and design draft, design the State structure for Vue 3 + TypeScript:

4.1 State returned by API

interface ClaimListApiResponse {
  data: ClaimRecord[]       // 當前頁資料
  total: number             // 總筆數
  page?: number             // 當前頁（若 API 回傳）
  pageSize?: number         // 每頁筆數（若 API 回傳）
}

interface ClaimRecord {
  id: string
  claim_title: string
  claim_status: 'pending' | 'approved' | 'rejected'
  claim_amount: number
  created_at: string
}

4.2 Page State (loading / error / pagination)

interface ClaimListPageState {
  isLoading: boolean        // API 呼叫中
  error: string | null      // 錯誤訊息（若有）
  records: ClaimRecord[]    // 當前頁資料
  currentPage: number       // 當前頁（預設 1）
  pageSize: number          // 每頁筆數（預設 20）
  total: number             // 總筆數
}

4.3 Derived State (computed)

const isEmpty = computed(() => !isLoading.value && records.value.length === 0)
const totalPages = computed(() => Math.ceil(total.value / pageSize.value))

---

Step 5: Define data mapping and transformation rules

Specific mapping logic from API Response → UI Props:

// API Response → ViewModel 轉換
interface ClaimCardViewModel {
  id: string
  title: string                    // 來自 claim_title
  status: 'pending' | 'approved' | 'rejected'  // 來自 claim_status，無需轉換
  displayStatus: string            // 轉換值：'審核中' / '已核准' / '已拒絕'
  amount: string                   // 來自 claim_amount，格式化後（加千分位）
  date: string                     // 來自 created_at，格式化為 YYYY/MM/DD
}

// Mapping 函式
function toViewModel(apiRecord: ClaimRecord): ClaimCardViewModel {
  const statusLabels = {
    'pending': '審核中',
    'approved': '已核准',
    'rejected': '已拒絕'
  }
  
  return {
    id: apiRecord.id,
    title: apiRecord.claim_title,
    status: apiRecord.claim_status,
    displayStatus: statusLabels[apiRecord.claim_status],
    amount: formatCurrency(apiRecord.claim_amount),  // 加千分位
    date: formatDate(apiRecord.created_at),          // YYYY/MM/DD
  }
}

// 輔助函式
const formatCurrency = (num: number): string => 
  new Intl.NumberFormat('zh-TW').format(num)

const formatDate = (isoStr: string): string => 
  new Date(isoStr).toLocaleDateString('zh-TW')

---

Step 6: Define error codes and exception handling plan

Based on the error code definitions in OpenAPI, formulate the UI presentation strategy:

HTTP Status	API Error Code	Trigger condition	UI presentation	User can act
401	UNAUTHORIZED	Not logged in or token expired	Redirect to login page	❌ None (automatic redirect)
403	FORBIDDEN	No viewing permission	"You do not have permission to view this data" static message	❌ None
400	INVALID_PARAMS	Invalid pagination parameter	Fall back to the first page and retry	❌ None (automatic retry)
404	NOT_FOUND	Resource does not exist	"Record does not exist" message	❌ None
5xx	INTERNAL_ERROR	Server error	"The system is temporarily unavailable, please try again later" + retry button	✅ Yes (can click retry)

Corresponding Composable logic

// 錯誤碼對應表
const errorMessages = {
  'UNAUTHORIZED': { code: 401, message: '請重新登入' },
  'FORBIDDEN': { code: 403, message: '您沒有查看此資料的權限' },
  'INVALID_PARAMS': { code: 400, message: '參數無效，已重置為第一頁' },
  'NOT_FOUND': { code: 404, message: '紀錄不存在' },
  'INTERNAL_ERROR': { code: 500, message: '系統暫時無法使用，請稍後再試' },
}

// 在 composable 中使用
const handleApiError = (status: number, errorCode?: string) => {
  if (status === 401) {
    // 重導至登入頁，由上層 router guard 處理
    window.location.href = '/login'
  } else if (status === 403) {
    error.value = errorMessages['FORBIDDEN'].message
  } else if (status === 400) {
    currentPage.value = 1
    reload()  // 自動重試第一頁
  } else if (status === 5xx) {
    error.value = errorMessages['INTERNAL_ERROR'].message
    // 留給使用者點重試按鈕
  }
}

---

Step 7: Check pending decisions and assumptions

Review all [Open Question] and [Assumption]in spec.md, and mark which ones have been answered by the API documentation:

Original Open Question	Decision approach	Source
Does the list need pagination?	Yes, based on the API supporting page/pageSize parameters	OpenAPI documentation
What are the status values?	pending/approved/rejected (confirmed)	OpenAPI schema
Is filtering functionality needed?	No, no related UI is seen in Figma, so it will not be implemented for now	Engineer decision
Prompt text for API errors?	See the error code mapping table in Step 6	Supplement to this Skill

If there are still undecided items, output them as pending confirmation.

---

Step 8: Output enriched-spec.md and Breakpoint B-C

Based on the above analysis, generate the complete enriched-spec.md, with the following structure:

# Enriched Spec：{功能名稱}

> 產生時間：{日期}
> 狀態：Enriched — 基於 API 補充完整
> Figma：{URL}
> OpenAPI：{URL}

## 1. 功能範圍與流程摘要
（來自 spec.md，無變化）

## 2. 元件拆分建議
（來自 spec.md，無變化）

## 3. 互動行為說明
（來自 spec.md，無變化）

## 4. 欄位與資料型別定義
（已補充完整的 API 欄位定義）

## 5. API 對應表 ⭐️ 新增
（Endpoint、Request/Response schema、參數說明）

## 6. State 結構草案 ⭐️ 新增
（頁面 State、API State、衍生 State）

## 7. 數據 Mapping 與轉換規則 ⭐️ 新增
（API Response → UI Props 的具體邏輯）

## 8. Loading / Empty / Error 狀態
（每個狀態的 API 條件和 UI 呈現）

## 9. 錯誤碼與異常處理方案 ⭐️ 新增
（HTTP 狀態碼與 UI 對應表）

## 10. 開放問題與假設（已更新）
（標記已決策項，列出仍待確認項）

After outputting, display the following prompt message to enter Breakpoint B-C:

✅ enriched-spec.md 已產生。

📋 請審閱以下新增內容：
  - Section 5：API 對應表是否正確？
  - Section 6：State 結構是否合理？
  - Section 7：Mapping 邏輯是否清晰？
  - Section 9：Error 處理方案是否完整？

確認無誤後請回覆「Approve」，我將輸出交接 payload 給 logic-coder。
未收到 Approve 前，不會繼續任何下游產出。

---

Quality Guidelines

Rule	Description
Follow OpenAPI	Field names, types, and enum values must be consistent with the OpenAPI document
Mark Uncertainties	Mark items that cannot be inferred from OpenAPI with [Assumption]
Clear Mapping	All API → UI transformation logic must be explicitly written out
Complete Errors	All possible HTTP status codes of the API must be mapped to UI presentation
Practical State	The State structure should directly correspond to the subsequent implementation needs of logic-coder
Proactively propose when there is no API	If OpenAPI is missing, do not stall; instead, back-infer a "data model candidate proposal"

---

Definition of Done (DoD)

• spec.md and Figma link (required) have been collected
• If OpenAPI exists, endpoints, schemas, and error codes have been successfully parsed and extracted
• If OpenAPI does not exist, a "data model candidate proposal" is produced and awaits user confirmation
• The Section 5 API mapping table is complete, and all fields have mappings
• The Section 6 State structure is clear, including pagination, loading, and error state
• The Section 7 Mapping logic is detailed, and all format transformations have function examples
• The Section 9 Error code table is complete, covering all possible HTTP statuses
• All 10 chapters of enriched-spec.md are structurally complete
• Breakpoint B-C has been entered and is awaiting engineer Approve

---

Reference Documents

• references/enrichment-template.md — Complete enriched-spec.md filling example
• references/data-structure-proposal.md — Example of data model back-inference when there is no OpenAPI