[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6D81F33N9CF6BWMH4VCWBMG":3,"skill-same:01M6D81F33N9CF6BWMH4VCWBMG":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":35,"linkOnly":36,"markdownContent":37,"markdownBody":38,"frontMatter":39,"refName":40,"commitSha":41,"skillDirectory":42,"forksCount":43,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":46,"ownerDescription":47,"updatedAt":48,"install":49,"resources":62},"01M6D81F33N9CF6BWMH4VCWBMG","coding-standards",null,"Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.","oabdelmaksoud\u002FSuperClaw","oabdelmaksoud","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F50699149?v=4","01M6D5CVVN778ZCDP1WHS816SP","Omar Abdelmaksoud","01M6D5CW1RHNSKCJR85GJACBFT",2,"MIT","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34],"coding standards","coding","standards","typescript","javascript","react","development","best practices","js","node","patterns","2026-11-10 10:12:30",false,"---\nname: coding-standards\ndescription: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.\n---\n\n# 程式碼標準與最佳實務\n\n適用於所有專案的通用程式碼標準。\n\n## 程式碼品質原則\n\n### 1. 可讀性優先\n- 程式碼被閱讀的次數遠多於被撰寫的次數\n- 使用清晰的變數和函式名稱\n- 優先使用自文件化的程式碼而非註解\n- 保持一致的格式化\n\n### 2. KISS（保持簡單）\n- 使用最簡單的解決方案\n- 避免過度工程\n- 不做過早優化\n- 易於理解 > 聰明的程式碼\n\n### 3. DRY（不重複自己）\n- 將共用邏輯提取為函式\n- 建立可重用的元件\n- 在模組間共享工具函式\n- 避免複製貼上程式設計\n\n### 4. YAGNI（你不會需要它）\n- 在需要之前不要建置功能\n- 避免推測性的通用化\n- 只在需要時增加複雜度\n- 從簡單開始，需要時再重構\n\n## TypeScript\u002FJavaScript 標準\n\n### 變數命名\n\n```typescript\n\u002F\u002F ✅ 良好：描述性名稱\nconst marketSearchQuery = 'election'\nconst isUserAuthenticated = true\nconst totalRevenue = 1000\n\n\u002F\u002F ❌ 不良：不清楚的名稱\nconst q = 'election'\nconst flag = true\nconst x = 1000\n```\n\n### 函式命名\n\n```typescript\n\u002F\u002F ✅ 良好：動詞-名詞模式\nasync function fetchMarketData(marketId: string) { }\nfunction calculateSimilarity(a: number[], b: number[]) { }\nfunction isValidEmail(email: string): boolean { }\n\n\u002F\u002F ❌ 不良：不清楚或只有名詞\nasync function market(id: string) { }\nfunction similarity(a, b) { }\nfunction email(e) { }\n```\n\n### 不可變性模式（關鍵）\n\n```typescript\n\u002F\u002F ✅ 總是使用展開運算符\nconst updatedUser = {\n  ...user,\n  name: 'New Name'\n}\n\nconst updatedArray = [...items, newItem]\n\n\u002F\u002F ❌ 永遠不要直接修改\nuser.name = 'New Name'  \u002F\u002F 不良\nitems.push(newItem)     \u002F\u002F 不良\n```\n\n### 錯誤處理\n\n```typescript\n\u002F\u002F ✅ 良好：完整的錯誤處理\nasync function fetchData(url: string) {\n  try {\n    const response = await fetch(url)\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`)\n    }\n\n    return await response.json()\n  } catch (error) {\n    console.error('Fetch failed:', error)\n    throw new Error('Failed to fetch data')\n  }\n}\n\n\u002F\u002F ❌ 不良：無錯誤處理\nasync function fetchData(url) {\n  const response = await fetch(url)\n  return response.json()\n}\n```\n\n### Async\u002FAwait 最佳實務\n\n```typescript\n\u002F\u002F ✅ 良好：可能時並行執行\nconst [users, markets, stats] = await Promise.all([\n  fetchUsers(),\n  fetchMarkets(),\n  fetchStats()\n])\n\n\u002F\u002F ❌ 不良：不必要的順序執行\nconst users = await fetchUsers()\nconst markets = await fetchMarkets()\nconst stats = await fetchStats()\n```\n\n### 型別安全\n\n```typescript\n\u002F\u002F ✅ 良好：正確的型別\ninterface Market {\n  id: string\n  name: string\n  status: 'active' | 'resolved' | 'closed'\n  created_at: Date\n}\n\nfunction getMarket(id: string): Promise\u003CMarket> {\n  \u002F\u002F 實作\n}\n\n\u002F\u002F ❌ 不良：使用 'any'\nfunction getMarket(id: any): Promise\u003Cany> {\n  \u002F\u002F 實作\n}\n```\n\n## React 最佳實務\n\n### 元件結構\n\n```typescript\n\u002F\u002F ✅ 良好：具有型別的函式元件\ninterface ButtonProps {\n  children: React.ReactNode\n  onClick: () => void\n  disabled?: boolean\n  variant?: 'primary' | 'secondary'\n}\n\nexport function Button({\n  children,\n  onClick,\n  disabled = false,\n  variant = 'primary'\n}: ButtonProps) {\n  return (\n    \u003Cbutton\n      onClick={onClick}\n      disabled={disabled}\n      className={`btn btn-${variant}`}\n    >\n      {children}\n    \u003C\u002Fbutton>\n  )\n}\n\n\u002F\u002F ❌ 不良：無型別、結構不清楚\nexport function Button(props) {\n  return \u003Cbutton onClick={props.onClick}>{props.children}\u003C\u002Fbutton>\n}\n```\n\n### 自訂 Hooks\n\n```typescript\n\u002F\u002F ✅ 良好：可重用的自訂 hook\nexport function useDebounce\u003CT>(value: T, delay: number): T {\n  const [debouncedValue, setDebouncedValue] = useState\u003CT>(value)\n\n  useEffect(() => {\n    const handler = setTimeout(() => {\n      setDebouncedValue(value)\n    }, delay)\n\n    return () => clearTimeout(handler)\n  }, [value, delay])\n\n  return debouncedValue\n}\n\n\u002F\u002F 使用方式\nconst debouncedQuery = useDebounce(searchQuery, 500)\n```\n\n### 狀態管理\n\n```typescript\n\u002F\u002F ✅ 良好：正確的狀態更新\nconst [count, setCount] = useState(0)\n\n\u002F\u002F 基於先前狀態的函式更新\nsetCount(prev => prev + 1)\n\n\u002F\u002F ❌ 不良：直接引用狀態\nsetCount(count + 1)  \u002F\u002F 在非同步情境中可能過時\n```\n\n### 條件渲染\n\n```typescript\n\u002F\u002F ✅ 良好：清晰的條件渲染\n{isLoading && \u003CSpinner \u002F>}\n{error && \u003CErrorMessage error={error} \u002F>}\n{data && \u003CDataDisplay data={data} \u002F>}\n\n\u002F\u002F ❌ 不良：三元地獄\n{isLoading ? \u003CSpinner \u002F> : error ? \u003CErrorMessage error={error} \u002F> : data ? \u003CDataDisplay data={data} \u002F> : null}\n```\n\n## API 設計標準\n\n### REST API 慣例\n\n```\nGET    \u002Fapi\u002Fmarkets              # 列出所有市場\nGET    \u002Fapi\u002Fmarkets\u002F:id          # 取得特定市場\nPOST   \u002Fapi\u002Fmarkets              # 建立新市場\nPUT    \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（完整）\nPATCH  \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（部分）\nDELETE \u002Fapi\u002Fmarkets\u002F:id          # 刪除市場\n\n# 過濾用查詢參數\nGET \u002Fapi\u002Fmarkets?status=active&limit=10&offset=0\n```\n\n### 回應格式\n\n```typescript\n\u002F\u002F ✅ 良好：一致的回應結構\ninterface ApiResponse\u003CT> {\n  success: boolean\n  data?: T\n  error?: string\n  meta?: {\n    total: number\n    page: number\n    limit: number\n  }\n}\n\n\u002F\u002F 成功回應\nreturn NextResponse.json({\n  success: true,\n  data: markets,\n  meta: { total: 100, page: 1, limit: 10 }\n})\n\n\u002F\u002F 錯誤回應\nreturn NextResponse.json({\n  success: false,\n  error: 'Invalid request'\n}, { status: 400 })\n```\n\n### 輸入驗證\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F ✅ 良好：Schema 驗證\nconst CreateMarketSchema = z.object({\n  name: z.string().min(1).max(200),\n  description: z.string().min(1).max(2000),\n  endDate: z.string().datetime(),\n  categories: z.array(z.string()).min(1)\n})\n\nexport async function POST(request: Request) {\n  const body = await request.json()\n\n  try {\n    const validated = CreateMarketSchema.parse(body)\n    \u002F\u002F 使用驗證過的資料繼續處理\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      return NextResponse.json({\n        success: false,\n        error: 'Validation failed',\n        details: error.errors\n      }, { status: 400 })\n    }\n  }\n}\n```\n\n## 檔案組織\n\n### 專案結構\n\n```\nsrc\u002F\n├── app\u002F                    # Next.js App Router\n│   ├── api\u002F               # API 路由\n│   ├── markets\u002F           # 市場頁面\n│   └── (auth)\u002F           # 認證頁面（路由群組）\n├── components\u002F            # React 元件\n│   ├── ui\u002F               # 通用 UI 元件\n│   ├── forms\u002F            # 表單元件\n│   └── layouts\u002F          # 版面配置元件\n├── hooks\u002F                # 自訂 React hooks\n├── lib\u002F                  # 工具和設定\n│   ├── api\u002F             # API 客戶端\n│   ├── utils\u002F           # 輔助函式\n│   └── constants\u002F       # 常數\n├── types\u002F                # TypeScript 型別\n└── styles\u002F              # 全域樣式\n```\n\n### 檔案命名\n\n```\ncomponents\u002FButton.tsx          # 元件用 PascalCase\nhooks\u002FuseAuth.ts              # hooks 用 camelCase 加 'use' 前綴\nlib\u002FformatDate.ts             # 工具用 camelCase\ntypes\u002Fmarket.types.ts         # 型別用 camelCase 加 .types 後綴\n```\n\n## 註解與文件\n\n### 何時註解\n\n```typescript\n\u002F\u002F ✅ 良好：解釋「為什麼」而非「什麼」\n\u002F\u002F 使用指數退避以避免在服務中斷時壓垮 API\nconst delay = Math.min(1000 * Math.pow(2, retryCount), 30000)\n\n\u002F\u002F 為了處理大陣列的效能，此處刻意使用突變\nitems.push(newItem)\n\n\u002F\u002F ❌ 不良：陳述顯而易見的事實\n\u002F\u002F 將計數器加 1\ncount++\n\n\u002F\u002F 將名稱設為使用者的名稱\nname = user.name\n```\n\n### 公開 API 的 JSDoc\n\n```typescript\n\u002F**\n * 使用語意相似度搜尋市場。\n *\n * @param query - 自然語言搜尋查詢\n * @param limit - 最大結果數量（預設：10）\n * @returns 按相似度分數排序的市場陣列\n * @throws {Error} 如果 OpenAI API 失敗或 Redis 不可用\n *\n * @example\n * ```typescript\n * const results = await searchMarkets('election', 5)\n * console.log(results[0].name) \u002F\u002F \"Trump vs Biden\"\n * ```\n *\u002F\nexport async function searchMarkets(\n  query: string,\n  limit: number = 10\n): Promise\u003CMarket[]> {\n  \u002F\u002F 實作\n}\n```\n\n## 效能最佳實務\n\n### 記憶化\n\n```typescript\nimport { useMemo, useCallback } from 'react'\n\n\u002F\u002F ✅ 良好：記憶化昂貴的計算\nconst sortedMarkets = useMemo(() => {\n  return markets.sort((a, b) => b.volume - a.volume)\n}, [markets])\n\n\u002F\u002F ✅ 良好：記憶化回呼函式\nconst handleSearch = useCallback((query: string) => {\n  setSearchQuery(query)\n}, [])\n```\n\n### 延遲載入\n\n```typescript\nimport { lazy, Suspense } from 'react'\n\n\u002F\u002F ✅ 良好：延遲載入重型元件\nconst HeavyChart = lazy(() => import('.\u002FHeavyChart'))\n\nexport function Dashboard() {\n  return (\n    \u003CSuspense fallback={\u003CSpinner \u002F>}>\n      \u003CHeavyChart \u002F>\n    \u003C\u002FSuspense>\n  )\n}\n```\n\n### 資料庫查詢\n\n```typescript\n\u002F\u002F ✅ 良好：只選擇需要的欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('id, name, status')\n  .limit(10)\n\n\u002F\u002F ❌ 不良：選擇所有欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('*')\n```\n\n## 測試標準\n\n### 測試結構（AAA 模式）\n\n```typescript\ntest('calculates similarity correctly', () => {\n  \u002F\u002F Arrange（準備）\n  const vector1 = [1, 0, 0]\n  const vector2 = [0, 1, 0]\n\n  \u002F\u002F Act（執行）\n  const similarity = calculateCosineSimilarity(vector1, vector2)\n\n  \u002F\u002F Assert（斷言）\n  expect(similarity).toBe(0)\n})\n```\n\n### 測試命名\n\n```typescript\n\u002F\u002F ✅ 良好：描述性測試名稱\ntest('returns empty array when no markets match query', () => { })\ntest('throws error when OpenAI API key is missing', () => { })\ntest('falls back to substring search when Redis unavailable', () => { })\n\n\u002F\u002F ❌ 不良：模糊的測試名稱\ntest('works', () => { })\ntest('test search', () => { })\n```\n\n## 程式碼異味偵測\n\n注意這些反模式：\n\n### 1. 過長函式\n```typescript\n\u002F\u002F ❌ 不良：函式超過 50 行\nfunction processMarketData() {\n  \u002F\u002F 100 行程式碼\n}\n\n\u002F\u002F ✅ 良好：拆分為較小的函式\nfunction processMarketData() {\n  const validated = validateData()\n  const transformed = transformData(validated)\n  return saveData(transformed)\n}\n```\n\n### 2. 過深巢狀\n```typescript\n\u002F\u002F ❌ 不良：5 層以上巢狀\nif (user) {\n  if (user.isAdmin) {\n    if (market) {\n      if (market.isActive) {\n        if (hasPermission) {\n          \u002F\u002F 做某事\n        }\n      }\n    }\n  }\n}\n\n\u002F\u002F ✅ 良好：提前返回\nif (!user) return\nif (!user.isAdmin) return\nif (!market) return\nif (!market.isActive) return\nif (!hasPermission) return\n\n\u002F\u002F 做某事\n```\n\n### 3. 魔術數字\n```typescript\n\u002F\u002F ❌ 不良：無解釋的數字\nif (retryCount > 3) { }\nsetTimeout(callback, 500)\n\n\u002F\u002F ✅ 良好：命名常數\nconst MAX_RETRIES = 3\nconst DEBOUNCE_DELAY_MS = 500\n\nif (retryCount > MAX_RETRIES) { }\nsetTimeout(callback, DEBOUNCE_DELAY_MS)\n```\n\n**記住**：程式碼品質是不可協商的。清晰、可維護的程式碼能實現快速開發和自信的重構。\n","# 程式碼標準與最佳實務\n\n適用於所有專案的通用程式碼標準。\n\n## 程式碼品質原則\n\n### 1. 可讀性優先\n- 程式碼被閱讀的次數遠多於被撰寫的次數\n- 使用清晰的變數和函式名稱\n- 優先使用自文件化的程式碼而非註解\n- 保持一致的格式化\n\n### 2. KISS（保持簡單）\n- 使用最簡單的解決方案\n- 避免過度工程\n- 不做過早優化\n- 易於理解 > 聰明的程式碼\n\n### 3. DRY（不重複自己）\n- 將共用邏輯提取為函式\n- 建立可重用的元件\n- 在模組間共享工具函式\n- 避免複製貼上程式設計\n\n### 4. YAGNI（你不會需要它）\n- 在需要之前不要建置功能\n- 避免推測性的通用化\n- 只在需要時增加複雜度\n- 從簡單開始，需要時再重構\n\n## TypeScript\u002FJavaScript 標準\n\n### 變數命名\n\n```typescript\n\u002F\u002F ✅ 良好：描述性名稱\nconst marketSearchQuery = 'election'\nconst isUserAuthenticated = true\nconst totalRevenue = 1000\n\n\u002F\u002F ❌ 不良：不清楚的名稱\nconst q = 'election'\nconst flag = true\nconst x = 1000\n```\n\n### 函式命名\n\n```typescript\n\u002F\u002F ✅ 良好：動詞-名詞模式\nasync function fetchMarketData(marketId: string) { }\nfunction calculateSimilarity(a: number[], b: number[]) { }\nfunction isValidEmail(email: string): boolean { }\n\n\u002F\u002F ❌ 不良：不清楚或只有名詞\nasync function market(id: string) { }\nfunction similarity(a, b) { }\nfunction email(e) { }\n```\n\n### 不可變性模式（關鍵）\n\n```typescript\n\u002F\u002F ✅ 總是使用展開運算符\nconst updatedUser = {\n  ...user,\n  name: 'New Name'\n}\n\nconst updatedArray = [...items, newItem]\n\n\u002F\u002F ❌ 永遠不要直接修改\nuser.name = 'New Name'  \u002F\u002F 不良\nitems.push(newItem)     \u002F\u002F 不良\n```\n\n### 錯誤處理\n\n```typescript\n\u002F\u002F ✅ 良好：完整的錯誤處理\nasync function fetchData(url: string) {\n  try {\n    const response = await fetch(url)\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`)\n    }\n\n    return await response.json()\n  } catch (error) {\n    console.error('Fetch failed:', error)\n    throw new Error('Failed to fetch data')\n  }\n}\n\n\u002F\u002F ❌ 不良：無錯誤處理\nasync function fetchData(url) {\n  const response = await fetch(url)\n  return response.json()\n}\n```\n\n### Async\u002FAwait 最佳實務\n\n```typescript\n\u002F\u002F ✅ 良好：可能時並行執行\nconst [users, markets, stats] = await Promise.all([\n  fetchUsers(),\n  fetchMarkets(),\n  fetchStats()\n])\n\n\u002F\u002F ❌ 不良：不必要的順序執行\nconst users = await fetchUsers()\nconst markets = await fetchMarkets()\nconst stats = await fetchStats()\n```\n\n### 型別安全\n\n```typescript\n\u002F\u002F ✅ 良好：正確的型別\ninterface Market {\n  id: string\n  name: string\n  status: 'active' | 'resolved' | 'closed'\n  created_at: Date\n}\n\nfunction getMarket(id: string): Promise\u003CMarket> {\n  \u002F\u002F 實作\n}\n\n\u002F\u002F ❌ 不良：使用 'any'\nfunction getMarket(id: any): Promise\u003Cany> {\n  \u002F\u002F 實作\n}\n```\n\n## React 最佳實務\n\n### 元件結構\n\n```typescript\n\u002F\u002F ✅ 良好：具有型別的函式元件\ninterface ButtonProps {\n  children: React.ReactNode\n  onClick: () => void\n  disabled?: boolean\n  variant?: 'primary' | 'secondary'\n}\n\nexport function Button({\n  children,\n  onClick,\n  disabled = false,\n  variant = 'primary'\n}: ButtonProps) {\n  return (\n    \u003Cbutton\n      onClick={onClick}\n      disabled={disabled}\n      className={`btn btn-${variant}`}\n    >\n      {children}\n    \u003C\u002Fbutton>\n  )\n}\n\n\u002F\u002F ❌ 不良：無型別、結構不清楚\nexport function Button(props) {\n  return \u003Cbutton onClick={props.onClick}>{props.children}\u003C\u002Fbutton>\n}\n```\n\n### 自訂 Hooks\n\n```typescript\n\u002F\u002F ✅ 良好：可重用的自訂 hook\nexport function useDebounce\u003CT>(value: T, delay: number): T {\n  const [debouncedValue, setDebouncedValue] = useState\u003CT>(value)\n\n  useEffect(() => {\n    const handler = setTimeout(() => {\n      setDebouncedValue(value)\n    }, delay)\n\n    return () => clearTimeout(handler)\n  }, [value, delay])\n\n  return debouncedValue\n}\n\n\u002F\u002F 使用方式\nconst debouncedQuery = useDebounce(searchQuery, 500)\n```\n\n### 狀態管理\n\n```typescript\n\u002F\u002F ✅ 良好：正確的狀態更新\nconst [count, setCount] = useState(0)\n\n\u002F\u002F 基於先前狀態的函式更新\nsetCount(prev => prev + 1)\n\n\u002F\u002F ❌ 不良：直接引用狀態\nsetCount(count + 1)  \u002F\u002F 在非同步情境中可能過時\n```\n\n### 條件渲染\n\n```typescript\n\u002F\u002F ✅ 良好：清晰的條件渲染\n{isLoading && \u003CSpinner \u002F>}\n{error && \u003CErrorMessage error={error} \u002F>}\n{data && \u003CDataDisplay data={data} \u002F>}\n\n\u002F\u002F ❌ 不良：三元地獄\n{isLoading ? \u003CSpinner \u002F> : error ? \u003CErrorMessage error={error} \u002F> : data ? \u003CDataDisplay data={data} \u002F> : null}\n```\n\n## API 設計標準\n\n### REST API 慣例\n\n```\nGET    \u002Fapi\u002Fmarkets              # 列出所有市場\nGET    \u002Fapi\u002Fmarkets\u002F:id          # 取得特定市場\nPOST   \u002Fapi\u002Fmarkets              # 建立新市場\nPUT    \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（完整）\nPATCH  \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（部分）\nDELETE \u002Fapi\u002Fmarkets\u002F:id          # 刪除市場\n\n# 過濾用查詢參數\nGET \u002Fapi\u002Fmarkets?status=active&limit=10&offset=0\n```\n\n### 回應格式\n\n```typescript\n\u002F\u002F ✅ 良好：一致的回應結構\ninterface ApiResponse\u003CT> {\n  success: boolean\n  data?: T\n  error?: string\n  meta?: {\n    total: number\n    page: number\n    limit: number\n  }\n}\n\n\u002F\u002F 成功回應\nreturn NextResponse.json({\n  success: true,\n  data: markets,\n  meta: { total: 100, page: 1, limit: 10 }\n})\n\n\u002F\u002F 錯誤回應\nreturn NextResponse.json({\n  success: false,\n  error: 'Invalid request'\n}, { status: 400 })\n```\n\n### 輸入驗證\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F ✅ 良好：Schema 驗證\nconst CreateMarketSchema = z.object({\n  name: z.string().min(1).max(200),\n  description: z.string().min(1).max(2000),\n  endDate: z.string().datetime(),\n  categories: z.array(z.string()).min(1)\n})\n\nexport async function POST(request: Request) {\n  const body = await request.json()\n\n  try {\n    const validated = CreateMarketSchema.parse(body)\n    \u002F\u002F 使用驗證過的資料繼續處理\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      return NextResponse.json({\n        success: false,\n        error: 'Validation failed',\n        details: error.errors\n      }, { status: 400 })\n    }\n  }\n}\n```\n\n## 檔案組織\n\n### 專案結構\n\n```\nsrc\u002F\n├── app\u002F                    # Next.js App Router\n│   ├── api\u002F               # API 路由\n│   ├── markets\u002F           # 市場頁面\n│   └── (auth)\u002F           # 認證頁面（路由群組）\n├── components\u002F            # React 元件\n│   ├── ui\u002F               # 通用 UI 元件\n│   ├── forms\u002F            # 表單元件\n│   └── layouts\u002F          # 版面配置元件\n├── hooks\u002F                # 自訂 React hooks\n├── lib\u002F                  # 工具和設定\n│   ├── api\u002F             # API 客戶端\n│   ├── utils\u002F           # 輔助函式\n│   └── constants\u002F       # 常數\n├── types\u002F                # TypeScript 型別\n└── styles\u002F              # 全域樣式\n```\n\n### 檔案命名\n\n```\ncomponents\u002FButton.tsx          # 元件用 PascalCase\nhooks\u002FuseAuth.ts              # hooks 用 camelCase 加 'use' 前綴\nlib\u002FformatDate.ts             # 工具用 camelCase\ntypes\u002Fmarket.types.ts         # 型別用 camelCase 加 .types 後綴\n```\n\n## 註解與文件\n\n### 何時註解\n\n```typescript\n\u002F\u002F ✅ 良好：解釋「為什麼」而非「什麼」\n\u002F\u002F 使用指數退避以避免在服務中斷時壓垮 API\nconst delay = Math.min(1000 * Math.pow(2, retryCount), 30000)\n\n\u002F\u002F 為了處理大陣列的效能，此處刻意使用突變\nitems.push(newItem)\n\n\u002F\u002F ❌ 不良：陳述顯而易見的事實\n\u002F\u002F 將計數器加 1\ncount++\n\n\u002F\u002F 將名稱設為使用者的名稱\nname = user.name\n```\n\n### 公開 API 的 JSDoc\n\n```typescript\n\u002F**\n * 使用語意相似度搜尋市場。\n *\n * @param query - 自然語言搜尋查詢\n * @param limit - 最大結果數量（預設：10）\n * @returns 按相似度分數排序的市場陣列\n * @throws {Error} 如果 OpenAI API 失敗或 Redis 不可用\n *\n * @example\n * ```typescript\n * const results = await searchMarkets('election', 5)\n * console.log(results[0].name) \u002F\u002F \"Trump vs Biden\"\n * ```\n *\u002F\nexport async function searchMarkets(\n  query: string,\n  limit: number = 10\n): Promise\u003CMarket[]> {\n  \u002F\u002F 實作\n}\n```\n\n## 效能最佳實務\n\n### 記憶化\n\n```typescript\nimport { useMemo, useCallback } from 'react'\n\n\u002F\u002F ✅ 良好：記憶化昂貴的計算\nconst sortedMarkets = useMemo(() => {\n  return markets.sort((a, b) => b.volume - a.volume)\n}, [markets])\n\n\u002F\u002F ✅ 良好：記憶化回呼函式\nconst handleSearch = useCallback((query: string) => {\n  setSearchQuery(query)\n}, [])\n```\n\n### 延遲載入\n\n```typescript\nimport { lazy, Suspense } from 'react'\n\n\u002F\u002F ✅ 良好：延遲載入重型元件\nconst HeavyChart = lazy(() => import('.\u002FHeavyChart'))\n\nexport function Dashboard() {\n  return (\n    \u003CSuspense fallback={\u003CSpinner \u002F>}>\n      \u003CHeavyChart \u002F>\n    \u003C\u002FSuspense>\n  )\n}\n```\n\n### 資料庫查詢\n\n```typescript\n\u002F\u002F ✅ 良好：只選擇需要的欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('id, name, status')\n  .limit(10)\n\n\u002F\u002F ❌ 不良：選擇所有欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('*')\n```\n\n## 測試標準\n\n### 測試結構（AAA 模式）\n\n```typescript\ntest('calculates similarity correctly', () => {\n  \u002F\u002F Arrange（準備）\n  const vector1 = [1, 0, 0]\n  const vector2 = [0, 1, 0]\n\n  \u002F\u002F Act（執行）\n  const similarity = calculateCosineSimilarity(vector1, vector2)\n\n  \u002F\u002F Assert（斷言）\n  expect(similarity).toBe(0)\n})\n```\n\n### 測試命名\n\n```typescript\n\u002F\u002F ✅ 良好：描述性測試名稱\ntest('returns empty array when no markets match query', () => { })\ntest('throws error when OpenAI API key is missing', () => { })\ntest('falls back to substring search when Redis unavailable', () => { })\n\n\u002F\u002F ❌ 不良：模糊的測試名稱\ntest('works', () => { })\ntest('test search', () => { })\n```\n\n## 程式碼異味偵測\n\n注意這些反模式：\n\n### 1. 過長函式\n```typescript\n\u002F\u002F ❌ 不良：函式超過 50 行\nfunction processMarketData() {\n  \u002F\u002F 100 行程式碼\n}\n\n\u002F\u002F ✅ 良好：拆分為較小的函式\nfunction processMarketData() {\n  const validated = validateData()\n  const transformed = transformData(validated)\n  return saveData(transformed)\n}\n```\n\n### 2. 過深巢狀\n```typescript\n\u002F\u002F ❌ 不良：5 層以上巢狀\nif (user) {\n  if (user.isAdmin) {\n    if (market) {\n      if (market.isActive) {\n        if (hasPermission) {\n          \u002F\u002F 做某事\n        }\n      }\n    }\n  }\n}\n\n\u002F\u002F ✅ 良好：提前返回\nif (!user) return\nif (!user.isAdmin) return\nif (!market) return\nif (!market.isActive) return\nif (!hasPermission) return\n\n\u002F\u002F 做某事\n```\n\n### 3. 魔術數字\n```typescript\n\u002F\u002F ❌ 不良：無解釋的數字\nif (retryCount > 3) { }\nsetTimeout(callback, 500)\n\n\u002F\u002F ✅ 良好：命名常數\nconst MAX_RETRIES = 3\nconst DEBOUNCE_DELAY_MS = 500\n\nif (retryCount > MAX_RETRIES) { }\nsetTimeout(callback, DEBOUNCE_DELAY_MS)\n```\n\n**記住**：程式碼品質是不可協商的。清晰、可維護的程式碼能實現快速開發和自信的重構。\n",{"name":5,"description":7},"main","7b610356e36623652299fa2acb477ff821b1d920","upstream-sync\u002Fwork\u002Fecc\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards",0,"https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud","https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fo-abdelmaksoud\u002F","Full-Stack Engineer | AI Systems Architect | Building autonomous multi-agent systems","2026-03-08 21:12:53",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add oabdelmaksoud\u002FSuperClaw --skill coding-standards",{"tool":55,"command":56},"bunx","bunx skills add oabdelmaksoud\u002FSuperClaw --skill coding-standards",{"tool":58,"command":59},"pnpm","pnpm dlx skills add oabdelmaksoud\u002FSuperClaw --skill coding-standards","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards\u002FSKILL.md",true,[63],{"path":64,"resourceType":65,"resourceTypeDesc":66,"sizeBytes":67,"sourceHtmlUrl":68},"scripts\u002Frun.py","SCRIPT","脚本",14,"https:\u002F\u002Fgithub.com\u002Fdwalleck\u002Fskill-evaluator\u002Fblob\u002Fmain\u002Ftests\u002FSkillEvaluator.Tests\u002FFixtures\u002Fskills\u002Fdemo-skill\u002Fscripts\u002Frun.py",[70,89,103,133,157,176],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":79,"publishedAt":35},"01M6D88QCPTBZVCRED0NZ1Y8K8","visa-doc-translate","Translate visa application documents (images) to English and create a bilingual PDF with original and translation","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fvisa-doc-translate\u002FSKILL.md",[76],{"categoryNo":77,"categoryName":78,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理",[80,81,82,83,84,85,86,87,88],"translate","doc","visa doc translate","translation","application","create","images","PDF","documents",{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":35},"01M6D88NBM95T3TFM50CYYAP65","verification-loop","A comprehensive verification system for Claude Code sessions.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[96,97,98,99,100,101,102],"verification","loop","verification loop","sessions","code","claude code sessions","system",{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":120,"publishedAt":35},"01M6D88JFZ2P996GVRHJNSZSTM","tdd-workflow","Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Ftdd-workflow\u002FSKILL.md",[109,112,115],{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":113,"categoryName":114,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":116,"categoryName":117,"taxonomyType":118,"taxonomyTypeDesc":119},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[121,122,123,124,125,126,100,30,127,128,129,130,131,132],"tdd","workflow","tdd workflow","e2e tests","e2e","integration","use","test","refactoring","coverage","tests","writing",{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":137,"categories":138,"keywords":139,"publishedAt":35},"01M6D88FTHRRSVJMXF2G7MQAK3","swiftui-patterns","SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS\u002FmacOS UI best practices.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswiftui-patterns\u002FSKILL.md",[],[34,140,141,142,143,144,145,31,146,147,148,149,150,151,152,153,154,155,156],"swiftui","swiftui patterns","architecture","macos","performance","state management","state","ui","Optimization","ios","architecture patterns","Composition","performance optimization","view","management","swiftui architecture","navigation",{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":164,"publishedAt":35},"01M6D88D527QTQT9DKHTRFN6EA","swift-protocol-di-testing","Protocol-based dependency injection for testable Swift code — mock file system, network, and external APIs using focused protocols and Swift Testing.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswift-protocol-di-testing\u002FSKILL.md",[163],{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},[165,166,167,168,100,169,170,171,172,102,173,174,175],"swift protocol di testing","protocol","swift","testing","protocols","file","network","injection","dependency","swift testing","dependency injection",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":182,"publishedAt":35},"01M6D88AJW8H2QNWSW5ZY82R43","swift-concurrency-6-2","Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FSuperClaw\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswift-concurrency-6-2\u002FSKILL.md",[],[183,184,167,185,186,40],"concurrency","swift concurrency","swift concurrency 6 2","default"]