{
  "components": {
    "schemas": {
      "Authorization": {
        "type": "object"
      },
      "BaseReq": {
        "type": "object"
      },
      "CredentialsPayload": {
        "properties": {
          "accountType": {
            "type": "string"
          },
          "password": {
            "description": "密碼 (後端應使用 bcrypt 進行雜湊)",
            "type": "string"
          },
          "password_confirm": {
            "description": "確認密碼",
            "type": "string"
          }
        },
        "required": [
          "password",
          "password_confirm",
          "accountType"
        ],
        "type": "object"
      },
      "ErrorResp": {
        "properties": {
          "code": {
            "type": "integer"
          },
          "details": {
            "type": "string"
          },
          "error": {
            "description": "可選的錯誤信息"
          },
          "msg": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "msg"
        ],
        "type": "object"
      },
      "LoginReq": {
        "properties": {
          "auth_method": {
            "type": "string"
          },
          "credentials": {
            "$ref": "#/components/schemas/CredentialsPayload"
          },
          "login_id": {
            "description": "信箱或手機號碼",
            "type": "string"
          },
          "platform": {
            "$ref": "#/components/schemas/PlatformPayload"
          }
        },
        "required": [
          "auth_method",
          "login_id"
        ],
        "type": "object"
      },
      "LoginResp": {
        "properties": {
          "access_token": {
            "type": "string"
          },
          "refresh_token": {
            "type": "string"
          },
          "token_type": {
            "description": "通常固定為 \"Bearer\"",
            "type": "string"
          },
          "uid": {
            "type": "string"
          }
        },
        "required": [
          "uid",
          "access_token",
          "refresh_token",
          "token_type"
        ],
        "type": "object"
      },
      "PagerResp": {
        "properties": {
          "index": {
            "type": "integer"
          },
          "size": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "total",
          "size",
          "index"
        ],
        "type": "object"
      },
      "PlatformPayload": {
        "properties": {
          "provider": {
            "description": "平台名稱",
            "type": "string"
          },
          "token": {
            "description": "平台提供的 Access Token 或 ID Token",
            "type": "string"
          }
        },
        "required": [
          "provider",
          "token"
        ],
        "type": "object"
      },
      "RefreshTokenReq": {
        "properties": {
          "refresh_token": {
            "type": "string"
          }
        },
        "required": [
          "refresh_token"
        ],
        "type": "object"
      },
      "RefreshTokenResp": {
        "properties": {
          "access_token": {
            "type": "string"
          },
          "refresh_token": {
            "description": "可選：某些策略下刷新後也會換發新的 Refresh Token",
            "type": "string"
          },
          "token_type": {
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "refresh_token",
          "token_type"
        ],
        "type": "object"
      },
      "RequestPasswordResetReq": {
        "properties": {
          "account_type": {
            "type": "string"
          },
          "identifier": {
            "description": "使用者帳號 (信箱或手機)",
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "account_type"
        ],
        "type": "object"
      },
      "RequestVerificationCodeReq": {
        "properties": {
          "purpose": {
            "type": "string"
          }
        },
        "required": [
          "purpose"
        ],
        "type": "object"
      },
      "ResetPasswordReq": {
        "properties": {
          "identifier": {
            "type": "string"
          },
          "password": {
            "description": "新密碼",
            "type": "string"
          },
          "password_confirm": {
            "description": "確認新密碼",
            "type": "string"
          },
          "verify_code": {
            "description": "來自上一步驗證通過的 Code，作為一種「票證」",
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "verify_code",
          "password",
          "password_confirm"
        ],
        "type": "object"
      },
      "RespOK": {
        "properties": {
          "code": {
            "type": "integer"
          },
          "data": {},
          "msg": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "msg"
        ],
        "type": "object"
      },
      "SubmitVerificationCodeReq": {
        "properties": {
          "purpose": {
            "type": "string"
          },
          "verify_code": {
            "type": "string"
          }
        },
        "required": [
          "purpose",
          "verify_code"
        ],
        "type": "object"
      },
      "UpdatePasswordReq": {
        "properties": {
          "current_password": {
            "type": "string"
          },
          "new_password": {
            "type": "string"
          },
          "new_password_confirm": {
            "type": "string"
          }
        },
        "required": [
          "current_password",
          "new_password",
          "new_password_confirm"
        ],
        "type": "object"
      },
      "UpdateUserInfoReq": {
        "properties": {
          "address": {
            "description": "地址",
            "type": "string"
          },
          "avatar_url": {
            "description": "頭像 URL",
            "type": "string"
          },
          "birthdate": {
            "description": "生日 (格式: 1993-04-17)",
            "type": "string"
          },
          "carrier": {
            "description": "載具",
            "type": "string"
          },
          "currency": {
            "description": "貨幣代號",
            "type": "string"
          },
          "full_name": {
            "description": "用戶全名",
            "type": "string"
          },
          "gender_code": {
            "description": "性別",
            "type": "string"
          },
          "national": {
            "description": "國家",
            "type": "string"
          },
          "nickname": {
            "description": "暱稱",
            "type": "string"
          },
          "post_code": {
            "description": "郵遞區號",
            "type": "string"
          },
          "preferred_language": {
            "description": "語言",
            "type": "string"
          }
        },
        "type": "object"
      },
      "UserInfoResp": {
        "properties": {
          "address": {
            "description": "地址",
            "type": "string"
          },
          "avatar_url": {
            "description": "頭像 URL",
            "type": "string"
          },
          "birthdate": {
            "description": "生日 (格式: 1993-04-17)",
            "type": "string"
          },
          "carrier": {
            "description": "載具",
            "type": "string"
          },
          "create_at": {
            "type": "string"
          },
          "currency": {
            "description": "偏好幣種",
            "type": "string"
          },
          "email": {
            "description": "信箱",
            "type": "string"
          },
          "full_name": {
            "description": "用戶全名",
            "type": "string"
          },
          "gender_code": {
            "description": "性別代碼",
            "type": "string"
          },
          "is_email_verified": {
            "description": "信箱是否已驗證",
            "type": "boolean"
          },
          "is_phone_verified": {
            "description": "手機是否已驗證",
            "type": "boolean"
          },
          "national": {
            "description": "國家",
            "type": "string"
          },
          "nickname": {
            "description": "暱稱",
            "type": "string"
          },
          "phone_number": {
            "description": "電話",
            "type": "string"
          },
          "platform": {
            "description": "註冊平台",
            "type": "string"
          },
          "post_code": {
            "description": "郵遞區號",
            "type": "string"
          },
          "preferred_language": {
            "description": "偏好語言",
            "type": "string"
          },
          "role": {
            "description": "角色",
            "type": "string"
          },
          "uid": {
            "description": "用戶 UID",
            "type": "string"
          },
          "update_at": {
            "type": "string"
          },
          "user_status": {
            "description": "用戶狀態",
            "type": "string"
          }
        },
        "required": [
          "platform",
          "uid",
          "avatar_url",
          "full_name",
          "nickname",
          "gender_code",
          "birthdate",
          "phone_number",
          "is_phone_verified",
          "email",
          "is_email_verified",
          "address",
          "user_status",
          "preferred_language",
          "currency",
          "national",
          "post_code",
          "carrier",
          "role",
          "update_at",
          "create_at"
        ],
        "type": "object"
      },
      "VerifyCodeReq": {
        "properties": {
          "identifier": {
            "type": "string"
          },
          "verify_code": {
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "verify_code"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "contact": {
      "email": "igs170911@gmail.com",
      "name": "Daniel Wang"
    },
    "description": "This is Digimon Platform ",
    "title": "Digimon Platform API Gateway",
    "version": "v1"
  },
  "openapi": "3.0.3",
  "paths": {
    "/api/v1/auth/password-resets": {
      "put": {
        "description": "使用有效的驗證碼來設定新的密碼。",
        "operationId": "authResetPassword",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetPasswordReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 密碼重設成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"驗證碼無效或請求參數錯誤\""
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "執行密碼重設"
      }
    },
    "/api/v1/auth/password-resets/request": {
      "post": {
        "description": "為指定的 email 或 phone 發送一個一次性的密碼重設驗證碼。",
        "operationId": "authRequestPasswordReset",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestPasswordResetReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 請求成功 (為安全起見，即使帳號不存在也應返回成功)"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求過於頻繁\" // 429 Too Many Requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "請求發送密碼重設驗證碼"
      }
    },
    "/api/v1/auth/password-resets/verify": {
      "post": {
        "description": "在實際重設密碼前，先驗證使用者輸入的驗證碼是否正確。",
        "operationId": "authVerifyPasswordResetCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyCodeReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 驗證碼正確"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"驗證碼無效或已過期\""
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "校驗密碼重設驗證碼"
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "description": "使用傳統帳號密碼或第三方平台進行註冊。成功後直接返回登入後的 Token 資訊。",
        "operationId": "authRegister",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResp"
                }
              }
            },
            "description": "// 註冊成功，並返回 Token"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"帳號已被註冊\" // 409 Conflict: 資源衝突"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "註冊新帳號"
      }
    },
    "/api/v1/auth/sessions": {
      "post": {
        "description": "使用傳統帳號密碼或第三方平台 Token 進行登入，以創建一個新的會話(Session)。",
        "operationId": "authLogin",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResp"
                }
              }
            },
            "description": "// 登入成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"帳號或密碼錯誤 / 無效的平台 Token\" // 401 Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "使用者登入"
      }
    },
    "/api/v1/auth/sessions/refresh": {
      "post": {
        "description": "使用有效的 Refresh Token 來獲取一組新的 Access Token 和 Refresh Token。",
        "operationId": "authRefreshToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshTokenReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshTokenResp"
                }
              }
            },
            "description": "// 刷新成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"無效或已過期的 Refresh Token\" // 401 Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "刷新 Access Token"
      }
    },
    "/api/v1/health": {
      "get": {
        "description": "檢查系統服務狀態，用於監控和負載均衡器健康檢查。返回系統運行狀態信息。",
        "operationId": "pingPing",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": ""
          }
        },
        "summary": "系統健康檢查"
      }
    },
    "/api/v1/user/me": {
      "get": {
        "operationId": "userGetUserInfo",
        "parameters": [
          {
            "in": "header",
            "name": "Authorization",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfoResp"
                }
              }
            },
            "description": "// 成功獲取"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"未授權或 Token 無效\""
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"找不到使用者\""
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "取得當前登入的會員資訊(自己)"
      },
      "put": {
        "description": "只更新傳入的欄位，未傳入的欄位將保持不變。",
        "operationId": "userUpdateUserInfo",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserInfoReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfoResp"
                }
              }
            },
            "description": "// 更新成功，並返回更新後的使用者資訊"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"未授權或 Token 無效\""
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "更新當前登入的會員資訊"
      }
    },
    "/api/v1/user/me/password": {
      "put": {
        "description": "必須提供當前密碼以進行驗證。",
        "operationId": "userUpdatePassword",
        "parameters": [
          {
            "in": "header",
            "name": "Authorization",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePasswordReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 密碼修改成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤或新舊密碼不符\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"未授權或 Token 無效\""
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"當前密碼不正確\" // 403 Forbidden"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "修改當前登入使用者的密碼"
      }
    },
    "/api/v1/user/me/verifications": {
      "post": {
        "description": "根據傳入的 `purpose` 發送對應的驗證碼。",
        "operationId": "userRequestVerificationCode",
        "parameters": [
          {
            "in": "header",
            "name": "Authorization",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestVerificationCodeReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 請求已受理"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求參數格式錯誤\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"未授權或 Token 無效\""
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"請求過於頻繁\" // 429 Too Many Requests"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "請求發送驗證碼 (用於驗證信箱/手機)"
      },
      "put": {
        "description": "提交收到的驗證碼，以完成特定目的的驗證，例如綁定手機或 Email。",
        "operationId": "userSubmitVerificationCode",
        "parameters": [
          {
            "in": "header",
            "name": "Authorization",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitVerificationCodeReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespOK"
                }
              }
            },
            "description": "// 驗證成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"驗證碼無效或已過期\""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "\"未授權或 Token 無效\""
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResp"
                }
              }
            },
            "description": "// 伺服器內部錯誤"
          }
        },
        "summary": "提交驗證碼以完成驗證"
      }
    }
  },
  "servers": [
    {
      "url": "http://localhost:8888"
    },
    {
      "url": "https://localhost:8888"
    }
  ],
  "x-date": "2025-10-02 17:47:43",
  "x-description": "This is a go-doc generated swagger file.",
  "x-generator": "go-doc",
  "x-github": "https://github.com/danielchan-25/go-doc",
  "x-source": "go-zero API specification"
}