openapi: 3.1.0
info:
  title: AI 命理館 API
  version: 1.1.0
  description: |
    免費繁體中文命理 REST API。無需 API Key。
    所有結果僅供娛樂與文化參考，不構成任何決策建議。
    速率限制：每 IP 每分鐘 60 次（超出返回 429）。
servers:
  - url: https://www.xuanyin.co
paths:
  /api/v1/health:
    get:
      summary: 健康檢查
      operationId: healthCheck
      responses:
        "200":
          description: 服務正常
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: 服務不可用
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/services:
    get:
      summary: 服務列表
      operationId: listServices
      responses:
        "200":
          description: 可用服務目錄
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"

  /api/v1/bazi:
    post:
      summary: 八字算命
      operationId: computeBazi
      description: |
        依出生日期（必填）取得四柱八字與性格、事業、財運、感情、健康解讀。
        靜態長文頁面亦可直接引用：/bazi/{YYYY-M-D}/
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BaziRequest"
            examples:
              sample:
                value:
                  birthDate: "1990-05-15"
                  gender: "male"
      responses:
        "200":
          description: 分析結果
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaziResponse"
        "400":
          description: 請求格式錯誤（如 birthDate 缺失或格式不正確）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidDate:
                  value:
                    success: false
                    error: "birthDate 必填，格式 YYYY-MM-DD"
        "429":
          description: 請求過於頻繁
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: 伺服器錯誤
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    HealthResponse:
      type: object
      required: [success, status]
      properties:
        success:
          type: boolean
          example: true
        status:
          type: string
          example: ok

    ErrorResponse:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "birthDate 必填，格式 YYYY-MM-DD"

    ServicesResponse:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
              href:
                type: string

    BaziRequest:
      type: object
      required: [birthDate]
      properties:
        birthDate:
          type: string
          format: date
          description: 出生日期，西曆 YYYY-MM-DD，範圍 1950-01-01 至 2025-12-31
          example: "1990-05-15"
        gender:
          type: string
          enum: [male, female]
          description: 可選，影響敘事視角（四柱排盤相同）

    BaziResponse:
      type: object
      required: [success, data, disclaimer]
      properties:
        success:
          type: boolean
          example: true
        disclaimer:
          type: string
          description: 必須在面向用戶的輸出中包含此免責聲明
          example: "本結果僅供娛樂與文化參考，不構成任何人生、財務、醫療或法律決策建議。"
        data:
          type: object
          required: [bazi, personality, career, wealth, love, health, summary, tier]
          properties:
            bazi:
              type: string
              description: 四柱摘要
              example: "庚午 辛巳 庚辰"
            personality:
              type: string
              description: 性格分析
            career:
              type: string
              description: 事業運勢
            wealth:
              type: string
              description: 財運分析
            love:
              type: string
              description: 感情婚姻
            health:
              type: string
              description: 健康提醒
            summary:
              type: string
              description: 全文摘要
            wordCount:
              type: integer
              description: 正文字數（內部品質指標）
            tier:
              type: string
              enum: [golden, generated, fallback]
              description: 內容品質層級