[Tech Debt] 建立通用 Zod Schema 模組

[andrewck24]

描述

建立一個存放全域、可重用的自訂 Zod Schema 的檔案。

實作內容

// src/lib/zod-schemas.ts
import { z } from "zod";

export const zCoerceOptionalNumber = z.preprocess(
  (val) => (val === "" || val === null || val === undefined ? undefined : val),
  z.coerce
    .number({
      invalid_type_error: "必須為數字",
    })
    .optional()
);

export const zCoerceRequiredNumber = z.preprocess(
  (val) => (val === "" || val === null || val === undefined ? undefined : val),
  z.coerce.number({
    invalid_type_error: "必須為數字",
    required_error: "此欄位為必填",
  })
);

export const zCoerceOptionalInteger = z.preprocess(
  (val) => (val === "" || val === null || val === undefined ? undefined : val),
  z.coerce
    .number({
      invalid_type_error: "必須為數字",
    })
    .int("必須為整數")
    .optional()
);

任務清單

• 建立 src/lib/zod-schemas.ts 檔案
• 實作 zCoerceOptionalNumber schema
• 實作 zCoerceRequiredNumber schema
• 實作 zCoerceOptionalInteger schema
• 新增完整的 JSDoc 說明
• 撰寫單元測試
• 更新專案文件

可能問題與解決方案

• 問題: 通用 schema 無法涵蓋所有使用場景
• 解決: 提供工廠函式，允許自訂錯誤訊息和驗證規則

風險與緩解

• 風險等級：低
• 緩解：以新增為主，不影響既有邏輯；先以單元測試驗證行為，再逐步導入到 features

測試與驗收

• 單元測試覆蓋 coercion、整數驗證與錯誤訊息
• README/文件同步更新並示例用法

---

優先級: Medium
Story Points: 3
預估工時: 1 天