{"openapi":"3.1.0","info":{"title":"久爵用户端 API","description":"久爵 H5、小程序和 App 共用的业务用户接口；后台管理接口不在本文档范围内。","version":"1.0.0"},"servers":[{"url":"/api/v1","description":"当前 Webman 用户端 API"}],"tags":[{"name":"System","description":"系统探活接口"},{"name":"Public","description":"公开站点配置和协议"},{"name":"Auth","description":"业务用户认证与令牌生命周期"},{"name":"User","description":"当前业务用户资料"},{"name":"Payment","description":"业务用户支付下单与查询"}],"paths":{"/health":{"get":{"operationId":"getApiHealth","summary":"API 健康检查","tags":["System"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/public/config":{"get":{"operationId":"getPublicConfig","summary":"获取应用公共配置","tags":["Public"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicConfigResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/public/protocols/{type}":{"get":{"operationId":"getPublicProtocol","summary":"获取指定公开协议","tags":["Public"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"type","in":"path","required":true,"description":"协议类型","schema":{"type":"string","enum":["member","privacy","register","cancellation"]}}]}},"/auth/login":{"post":{"operationId":"loginBusinessUser","summary":"业务用户登录","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}}}},"/auth/sms-codes":{"post":{"operationId":"sendBusinessSmsCode","summary":"发送业务用户短信验证码","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsCodeResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsCodeRequest"}}}}}},"/auth/register":{"post":{"operationId":"registerBusinessUser","summary":"使用手机号注册业务用户","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}}}},"/auth/sms-login":{"post":{"operationId":"smsLoginBusinessUser","summary":"使用短信验证码登录","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsLoginRequest"}}}}}},"/auth/wechat":{"post":{"operationId":"wechatLoginBusinessUser","summary":"使用微信授权码登录","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WechatLoginRequest"}}}}}},"/auth/reset-password":{"post":{"operationId":"resetBusinessPassword","summary":"使用短信验证码重置密码","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}}}}},"/auth/refresh":{"post":{"operationId":"refreshBusinessToken","summary":"轮换业务用户令牌","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}}}}},"/auth/logout":{"post":{"operationId":"logoutBusinessUser","summary":"退出当前业务用户会话","tags":["Auth"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/payments":{"post":{"operationId":"createPaymentOrder","summary":"创建支付订单","tags":["Payment"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCreateRequest"}}}},"security":[{"bearerAuth":[]}]}},"/payments/virtual-currency":{"post":{"operationId":"consumeVirtualCurrency","summary":"查询代币余额并扣减已有代币","tags":["Payment"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrencyConsumeRequest"}}}},"security":[{"bearerAuth":[]}]}},"/payments/{orderNo}":{"get":{"operationId":"getPaymentOrder","summary":"查询当前用户的支付订单","tags":["Payment"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderNo","in":"path","required":true,"description":"商户订单号","schema":{"type":"string"}}]}},"/users/me":{"get":{"operationId":"getCurrentBusinessUser","summary":"获取当前业务用户资料","tags":["User"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"updateCurrentBusinessUser","summary":"修改当前业务用户资料","tags":["User"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateRequest"}}}},"security":[{"bearerAuth":[]}]}},"/users/me/password":{"put":{"operationId":"changeCurrentBusinessUserPassword","summary":"修改当前业务用户密码","tags":["User"],"responses":{"200":{"description":"请求成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordChangeResponse"}}}},"400":{"description":"参数或业务校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"访问令牌无效或已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordChangeRequest"}}}},"security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque"}},"schemas":{"ErrorResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":"null"}}},"ActionResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":["object","null"]}}},"HealthResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":"object","required":["application","service","version","status","time"],"properties":{"application":{"type":"string","example":"api"},"service":{"type":"string","example":"jiujue-api"},"version":{"type":"string","example":"v1"},"status":{"type":"string","example":"ok"},"time":{"type":"string","format":"date-time"}}}}},"PublicConfigResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":"object","required":["site","maintenance","protocols"],"properties":{"site":{"$ref":"#/components/schemas/SiteConfig"},"maintenance":{"$ref":"#/components/schemas/MaintenanceConfig"},"protocols":{"type":"array","items":{"$ref":"#/components/schemas/ProtocolSummary"}}}}}},"ProtocolResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/ProtocolDetail"}}},"AuthResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/AuthPayload"}}},"ProfileResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/BusinessUserProfile"}}},"PasswordChangeResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":"object","required":["require_relogin"],"properties":{"require_relogin":{"type":"boolean","example":true}}}}},"LoginRequest":{"type":"object","required":["account","password"],"properties":{"account":{"type":"string","maxLength":128,"description":"用户名、手机号或邮箱"},"password":{"type":"string","format":"password","maxLength":72},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"h5"},"device_id":{"type":["string","null"],"maxLength":191}}},"SmsCodeRequest":{"type":"object","required":["phone","scene"],"properties":{"phone":{"type":"string","maxLength":32,"description":"手机号"},"scene":{"type":"string","enum":["register","login","reset_password"]}}},"SmsCodeResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"type":"object","required":["expire_seconds","interval_seconds"],"properties":{"expire_seconds":{"type":"integer","example":300},"interval_seconds":{"type":"integer","example":60}}}}},"RegisterRequest":{"type":"object","required":["phone","code","password"],"properties":{"phone":{"type":"string","maxLength":32},"code":{"type":"string","minLength":4,"maxLength":8},"password":{"type":"string","format":"password","minLength":8,"maxLength":72},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"h5"},"device_id":{"type":["string","null"],"maxLength":191}}},"SmsLoginRequest":{"type":"object","required":["phone","code"],"properties":{"phone":{"type":"string","maxLength":32},"code":{"type":"string","minLength":4,"maxLength":8},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"h5"},"device_id":{"type":["string","null"],"maxLength":191}}},"WechatLoginRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"微信授权码"},"scene":{"type":"string","enum":["miniapp","oa"],"default":"miniapp"},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"miniapp"},"device_id":{"type":["string","null"],"maxLength":191}}},"ResetPasswordRequest":{"type":"object","required":["phone","code","password"],"properties":{"phone":{"type":"string","maxLength":32},"code":{"type":"string","minLength":4,"maxLength":8},"password":{"type":"string","format":"password","minLength":8,"maxLength":72}}},"PaymentCreateRequest":{"type":"object","required":["channel","amount"],"properties":{"channel":{"type":"string","enum":["wechat","alipay","lishoutong","wechat_virtual"]},"amount":{"type":"number","minimum":0.01},"subject":{"type":"string","maxLength":128},"trade_type":{"type":"string","maxLength":32},"openid":{"type":"string","maxLength":64},"session_key":{"type":"string","maxLength":128},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"h5"},"return_url":{"type":"string","maxLength":500}}},"CurrencyConsumeRequest":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","minimum":1,"description":"消耗的代币数量"},"subject":{"type":"string","maxLength":128},"product_id":{"type":"string","maxLength":64},"client_type":{"type":"string","enum":["web","h5","ios","android","miniapp"],"default":"miniapp"}}},"PaymentOrderResponse":{"type":"object","required":["code","msg","data"],"properties":{"code":{"type":"integer","example":200},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/PaymentOrder"}}},"PaymentOrder":{"type":"object","required":["order_no","channel","amount","status"],"properties":{"id":{"type":"integer","format":"int64"},"order_no":{"type":"string"},"channel":{"type":"string"},"trade_type":{"type":"string"},"subject":{"type":"string"},"amount":{"type":"string"},"status":{"type":"integer","enum":[0,1,2,3]},"trade_no":{"type":["string","null"]},"prepay":{"type":"object","additionalProperties":true},"paid_at":{"type":["string","null"],"format":"date-time"},"client_type":{"type":"string"}}},"RefreshRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","minLength":1}}},"ProfileUpdateRequest":{"type":"object","properties":{"nickname":{"type":"string","maxLength":64},"real_name":{"type":["string","null"],"maxLength":64},"avatar":{"type":["string","null"],"maxLength":1000},"gender":{"type":"integer","enum":[0,1,2]},"birthday":{"type":["string","null"],"format":"date"},"email":{"type":["string","null"],"format":"email","maxLength":128},"phone":{"type":["string","null"],"maxLength":32},"country":{"type":["string","null"],"maxLength":64},"province":{"type":["string","null"],"maxLength":64},"city":{"type":["string","null"],"maxLength":64},"address":{"type":["string","null"],"maxLength":500}}},"PasswordChangeRequest":{"type":"object","required":["current_password","new_password"],"properties":{"current_password":{"type":"string","format":"password","maxLength":72},"new_password":{"type":"string","format":"password","minLength":8,"maxLength":72}}},"AuthPayload":{"type":"object","required":["token_type","access_token","refresh_token","expires_at","refresh_expires_at","user"],"properties":{"token_type":{"type":"string","example":"Bearer"},"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"refresh_expires_at":{"type":"string","format":"date-time"},"user":{"$ref":"#/components/schemas/BusinessUserProfile"}}},"BusinessUserProfile":{"type":"object","required":["id","user_no","nickname","gender","status","level","vip_level","points","balance","frozen_balance","source","login_count"],"properties":{"id":{"type":"integer","format":"int64"},"user_no":{"type":"string"},"username":{"type":["string","null"]},"nickname":{"type":"string"},"real_name":{"type":["string","null"]},"avatar":{"type":["string","null"]},"gender":{"type":"integer","enum":[0,1,2]},"birthday":{"type":["string","null"],"format":"date"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"country":{"type":["string","null"]},"province":{"type":["string","null"]},"city":{"type":["string","null"]},"address":{"type":["string","null"]},"status":{"type":"integer"},"level":{"type":"integer"},"vip_level":{"type":"integer"},"vip_expired_at":{"type":["string","null"],"format":"date-time"},"points":{"type":"integer","format":"int64"},"balance":{"type":"string"},"frozen_balance":{"type":"string"},"source":{"type":"string"},"register_channel":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"last_login_at":{"type":["string","null"],"format":"date-time"},"last_login_ip":{"type":["string","null"]},"last_active_at":{"type":["string","null"],"format":"date-time"},"login_count":{"type":"integer","format":"int64"}}},"SiteConfig":{"type":"object","required":["enabled","name","url","logo","icon","contact_phone","contact_email","record_no","copyright"],"properties":{"enabled":{"type":"boolean"},"name":{"type":"string"},"url":{"type":"string"},"logo":{"type":"string"},"icon":{"type":"string"},"contact_phone":{"type":"string"},"contact_email":{"type":"string"},"record_no":{"type":"string"},"copyright":{"type":"string"}}},"MaintenanceConfig":{"type":"object","required":["enabled","message"],"properties":{"enabled":{"type":"boolean"},"message":{"type":"string"}}},"ProtocolSummary":{"type":"object","required":["type","title"],"properties":{"type":{"type":"string"},"title":{"type":"string"}}},"ProtocolDetail":{"type":"object","required":["type","title","content"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"content":{"type":"string","description":"已执行安全过滤的 HTML"}}}}},"x-jiujue-application":"docs"}