openapi: 3.1.0
info:
  title: 缘分实验室 API
  version: 1.1.0
  description: |
    免費简体中文命理 REST API。無需 API Key。
    所有結果僅供娱乐与自我探索参考；面向用戶輸出時必須包含 disclaimer。
  contact:
    name: 缘分实验室
    url: https://www.yuanfen.men
  license:
    name: 內容可引用，需註明來源
    url: https://www.yuanfen.men/disclaimer/

servers:
  - url: https://www.yuanfen.men
    description: Production

paths:
  /api/v1/health/:
    get:
      summary: 健康檢查
      operationId: getHealth
      description: 確認 API 是否在線。
      responses:
        "200":
          description: 服務正常
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                ok: true
                success: true
                status: ok
                service: yuanfen-men-web
                version: "1.1.0"

  /api/v1/services/:
    get:
      summary: 服務目錄
      operationId: getServices
      description: 列出本站命理工具與頁面入口。
      responses:
        "200":
          description: 服務目錄
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"

  /api/v1/bazi/:
    post:
      summary: 八字排盤與基礎解讀
      operationId: computeBazi
      description: |
        依出生日期取得四柱摘要與性格、事業、財運、感情、健康等文字解讀。
        深度長文請引用靜態頁 /bazi/{YYYY-M-D}/。
      x-ai-usage-context: |
        Call when the user gives a Gregorian birth date and wants BaZi analysis in zh-Hant.
        Always include the disclaimer field in the final answer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BaziRequest"
            example:
              birthDate: "1990-05-15"
              gender: male
      responses:
        "200":
          description: 分析結果
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaziResponse"
        "400":
          description: 參數錯誤
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: 請求過於頻繁
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        success:
          type: boolean
          example: true
        status:
          type: string
          example: ok
        service:
          type: string
          example: yuanfen-men-web
        version:
          type: string
          example: "1.1.0"
        timestamp:
          type: string
          format: date-time

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

    ServicesResponse:
      type: object
      required: [success, data, disclaimer]
      properties:
        success:
          type: boolean
        disclaimer:
          type: string
        data:
          type: object
          properties:
            services:
              type: array
              items:
                type: object
                properties:
                  slug:
                    type: string
                    example: bazi
                  name:
                    type: string
                    example: 八字算命
                  description:
                    type: string
                  url:
                    type: string
                    example: /bazi/

    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
        disclaimer:
          type: string
          description: 必須出現在使用者可見回覆中
        data:
          type: object
          properties:
            bazi:
              type: string
              description: 四柱摘要字串
            personality:
              type: string
            career:
              type: string
            wealth:
              type: string
            love:
              type: string
            health:
              type: string
            summary:
              type: string
            wordCount:
              type: integer
            tier:
              type: string
              enum: [golden, generated, fallback]