{
  "openapi": "3.1.0",
  "info": {
    "title": "Snowflake Account Manager API",
    "version": "1.0.0",
    "description": "邮箱、银行卡和 Snowflake 账号库存管理 API。领取资源后默认锁定 15 分钟。"
  },
  "servers": [{ "url": "https://snow.51proxy.org" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "magicToken": { "type": "apiKey", "in": "header", "name": "X-Bind-Token" } },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] },
      "LockToken": { "type": "object", "properties": { "lock_token": { "type": "string", "format": "uuid" } }, "required": ["lock_token"] },
      "EmailClaim": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "client_id": { "type": "string" }, "refresh_token": { "type": "string" }, "lock_token": { "type": "string", "format": "uuid" }, "locked_at": { "type": "string" } }, "required": ["id", "email", "password", "client_id", "refresh_token", "lock_token"] },
      "CardInput": { "type": "object", "properties": { "card_number": { "type": "string" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "expiry_year": { "type": "integer" }, "cvc": { "type": "string" }, "holder_name": { "type": "string" }, "billing_address": { "type": "string" } }, "required": ["card_number", "expiry_month", "expiry_year", "cvc"] },
      "SnowflakeInput": { "type": "object", "properties": { "email_id": { "type": "integer" }, "email_lock_token": { "type": "string", "format": "uuid" }, "username": { "type": "string" }, "password": { "type": "string" }, "account_name": { "type": "string" }, "host": { "type": "string" }, "region": { "type": "string" }, "apps_api_origin": { "type": "string", "format": "uri", "description": "非 AWS 或特殊部署时可显式指定" }, "notes": { "type": "string" } }, "required": ["email_id", "email_lock_token", "username", "password", "account_name", "host", "region"] },
      "SubscriptionInput": { "type": "object", "properties": { "card_id": { "type": "integer" }, "card_lock_token": { "type": "string", "format": "uuid" }, "subscription_status": { "type": "string", "enum": ["active", "trialing", "past_due", "cancelled"], "default": "active" }, "subscription_plan": { "type": "string" }, "external_subscription_id": { "type": "string" }, "notes": { "type": "string" } }, "required": ["card_id", "card_lock_token"] },
      "BindCompleteInput": { "type": "object", "description": "只含 Stripe PaymentMethod ID 和非敏感账单资料；禁止传卡号或 CVC", "properties": { "pm_id": { "type": "string", "pattern": "^pm_" }, "billing_profile": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": ["line1", "city", "state", "postal_code", "country"] } }, "required": ["email", "name", "address"] } }, "required": ["pm_id", "billing_profile"] }
    }
  },
  "paths": {
    "/api/stats": { "get": { "summary": "库存统计", "responses": { "200": { "description": "成功" } } } },
    "/api/emails": { "get": { "summary": "邮箱列表", "parameters": [{ "name": "status", "in": "query", "schema": { "type": "string", "enum": ["available", "locked", "used"] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }], "responses": { "200": { "description": "成功" } } } },
    "/api/emails/import": { "post": { "summary": "批量导入邮箱", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "responses": { "201": { "description": "导入完成" } } } },
    "/api/emails/claim": { "post": { "summary": "领取并锁定邮箱", "responses": { "200": { "description": "领取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailClaim" } } } }, "404": { "description": "无可用邮箱" } } } },
    "/api/emails/{id}/release": { "post": { "summary": "释放邮箱", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockToken" } } } }, "responses": { "200": { "description": "释放成功" }, "409": { "description": "锁已失效" } } } },
    "/api/cards": {
      "get": { "summary": "银行卡列表", "responses": { "200": { "description": "成功" } } },
      "post": { "summary": "添加银行卡", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardInput" } } } }, "responses": { "201": { "description": "创建成功" } } }
    },
    "/api/cards/claim": { "post": { "summary": "领取并锁定银行卡", "responses": { "200": { "description": "领取成功" }, "404": { "description": "无可用银行卡" } } } },
    "/api/cards/{id}/release": { "post": { "summary": "释放银行卡", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockToken" } } } }, "responses": { "200": { "description": "释放成功" }, "409": { "description": "锁已失效" } } } },
    "/api/snowflake-accounts": {
      "get": { "summary": "Snowflake 账号列表", "responses": { "200": { "description": "成功" } } },
      "post": { "summary": "回写注册结果并消耗邮箱", "description": "重复回写相同 email_id 和账号资料时返回幂等成功。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnowflakeInput" } } } }, "responses": { "200": { "description": "幂等成功" }, "201": { "description": "创建成功" }, "409": { "description": "邮箱锁失效或账号冲突" } } }
    },
    "/api/snowflake-accounts/{id}/subscription": { "post": { "summary": "回写绑卡与订阅结果并消耗银行卡", "description": "相同账号和银行卡的重复回写返回幂等成功。", "parameters": [{ "name": "id", "in": "path", "required": true, "description": "第一次回写返回的 Snowflake 账号 ID", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInput" } } } }, "responses": { "200": { "description": "幂等成功" }, "201": { "description": "订阅回写成功" }, "404": { "description": "账号不存在" }, "409": { "description": "银行卡锁失效或已被绑定" } } } },
    "/api/snowflake-accounts/{id}/bind-session": { "post": { "summary": "为账号创建人工绑卡链接", "description": "后端完成 Snowsight OAuth 并获取短期 SetupIntent。不会向调用方返回 Snowflake Cookie 或密码。", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_seconds": { "type": "integer", "minimum": 300, "maximum": 900, "default": 600 } } } } } }, "responses": { "201": { "description": "返回 bind_session_id、magic_url、expires_in" }, "502": { "description": "Snowflake 登录或 SetupIntent 创建失败" } } } },
    "/api/bind/{id}/bootstrap": { "get": { "security": [{ "magicToken": [] }], "summary": "初始化托管 Stripe 绑卡页", "description": "返回 Stripe publishable key 和短期 SetupIntent client_secret，不返回 Snowflake Cookie。", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "初始化成功" }, "410": { "description": "链接无效或过期" } } } },
    "/api/bind/{id}/complete": { "post": { "security": [{ "magicToken": [] }], "summary": "提交 Stripe 验证结果并绑定到 Snowflake", "description": "浏览器通过 Stripe Elements 得到 pm_id 后调用。本站永不接收 PAN/CVC。", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindCompleteInput" } } } }, "responses": { "200": { "description": "绑定成功" }, "409": { "description": "链接过期或已使用" }, "502": { "description": "Snowflake 拒绝绑定或验证失败" } } } },
    "/api/auth/login": { "post": { "security": [], "summary": "后台登录", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } }, "required": ["password"] } } } }, "responses": { "200": { "description": "登录成功" }, "401": { "description": "密码错误" } } } },
    "/api/auth/logout": { "post": { "security": [], "summary": "退出登录", "responses": { "200": { "description": "成功" } } } },
    "/api/auth/session": { "get": { "security": [], "summary": "检查登录状态", "responses": { "200": { "description": "成功" } } } }
  }
}