{
    "schemes": [
        "http",
        "https"
    ],
    "swagger": "2.0",
    "info": {
        "description": "统一认证、用户资料、每日签到、公开用户主页与管理端等 JSON HTTP 接口。",
        "title": "萌芽账户认证中心 API",
        "contact": {},
        "version": "0.1.0"
    },
    "host": "localhost:8080",
    "basePath": "/",
    "paths": {
        "/": {
            "get": {
                "description": "与 GET /api 相同，返回名称、版本与路由前缀说明。",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "meta"
                ],
                "summary": "API 简介 JSON",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api": {
            "get": {
                "description": "与 GET / 相同。",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "meta"
                ],
                "summary": "API 简介 JSON",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/check-in/config": {
            "get": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "签到奖励配置（管理端也可用）",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "更新签到奖励",
                "parameters": [
                    {
                        "description": "rewardCoins",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.UpdateCheckInConfigRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/oauth": {
            "get": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "OAuth 配置（脱敏）",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "更新 OAuth 配置",
                "parameters": [
                    {
                        "description": "配置",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.PutAdminOAuthRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/registration": {
            "get": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "注册策略与邀请码列表",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "更新注册策略",
                "parameters": [
                    {
                        "description": "策略",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.UpdateRegistrationPolicyRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/registration/invites": {
            "post": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "创建邀请码",
                "parameters": [
                    {
                        "description": "邀请配置",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.CreateInviteRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/registration/invites/{code}": {
            "delete": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "删除邀请码",
                "parameters": [
                    {
                        "type": "string",
                        "description": "邀请码",
                        "name": "code",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/turnstile": {
            "get": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "Turnstile 配置（脱敏）",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "更新 Turnstile 配置",
                "parameters": [
                    {
                        "description": "siteKey、secretKey",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.PutAdminTurnstileRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/users": {
            "get": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "用户列表",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "创建用户",
                "parameters": [
                    {
                        "description": "用户",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.CreateUserRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/admin/users/{account}": {
            "put": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "更新用户",
                "parameters": [
                    {
                        "type": "string",
                        "description": "账号",
                        "name": "account",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "可部分更新",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.UpdateUserRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "AdminToken": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "admin"
                ],
                "summary": "删除用户",
                "parameters": [
                    {
                        "type": "string",
                        "description": "账号",
                        "name": "account",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/check-in": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "每日签到",
                "responses": {
                    "200": {
                        "description": "checkedIn、user、checkIn 等",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/forgot-password": {
            "post": {
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "忘记密码（发重置邮件）",
                "parameters": [
                    {
                        "description": "账号与邮箱",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.ForgotPasswordRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/login": {
            "post": {
                "description": "可选 Turnstile：开启时 body 需带 turnstileToken。",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "账号密码登录",
                "parameters": [
                    {
                        "description": "登录请求",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.LoginRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "token、expiresAt、user",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/me": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "需要 Authorization: Bearer。可选头：X-Visit-Ip、X-Visit-Location、X-Auth-Client、X-Auth-Client-Name。",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "当前用户（含签到摘要）",
                "parameters": [
                    {
                        "type": "string",
                        "description": "访客 IP",
                        "name": "X-Visit-Ip",
                        "in": "header"
                    },
                    {
                        "type": "string",
                        "description": "访客地区展示文案",
                        "name": "X-Visit-Location",
                        "in": "header"
                    },
                    {
                        "type": "string",
                        "description": "接入应用 ID",
                        "name": "X-Auth-Client",
                        "in": "header"
                    },
                    {
                        "type": "string",
                        "description": "接入应用名称",
                        "name": "X-Auth-Client-Name",
                        "in": "header"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "user、checkIn",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/oauth/{provider}": {
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "oauth"
                ],
                "summary": "解绑 OAuth 提供商",
                "parameters": [
                    {
                        "type": "string",
                        "description": "github|gitea|google|microsoft|linuxdo",
                        "name": "provider",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/oauth/{provider}/bind": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "oauth"
                ],
                "summary": "已登录用户绑定 OAuth（返回授权 URL）",
                "parameters": [
                    {
                        "type": "string",
                        "description": "github|gitea|google|microsoft|linuxdo",
                        "name": "provider",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "returnTo",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.OAuthBindURLRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "url",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/oauth/{provider}/callback": {
            "get": {
                "description": "成功时通常 302 回 return_to 并带 token；失败时 JSON 或重定向错误页。",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "oauth"
                ],
                "summary": "OAuth 回调（IdP 重定向）",
                "parameters": [
                    {
                        "type": "string",
                        "description": "提供商",
                        "name": "provider",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "授权码",
                        "name": "code",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "state",
                        "name": "state",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "IdP 错误码",
                        "name": "error",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "302": {
                        "description": "重定向至客户端"
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/oauth/{provider}/start": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "oauth"
                ],
                "summary": "OAuth 登录起点（重定向 IdP）",
                "parameters": [
                    {
                        "type": "string",
                        "description": "github|gitea|google|microsoft|linuxdo",
                        "name": "provider",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "登录完成回跳 URL（须符合后台允许前缀）",
                        "name": "return_to",
                        "in": "query",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Turnstile 开启时必填",
                        "name": "turnstile_token",
                        "in": "query"
                    }
                ],
                "responses": {
                    "302": {
                        "description": "重定向至 IdP"
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/profile": {
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "更新个人资料（可选改密码）",
                "parameters": [
                    {
                        "description": "资料字段",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.UpdateProfileRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/register": {
            "post": {
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "自助注册（发验证邮件）",
                "parameters": [
                    {
                        "description": "注册请求",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.RegisterRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "sent、expiresAt",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/reset-password": {
            "post": {
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "重置密码",
                "parameters": [
                    {
                        "description": "账号、验证码、新密码",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.ResetPasswordRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/secondary-email/request": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "请求验证辅助邮箱（发邮件）",
                "parameters": [
                    {
                        "description": "邮箱",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.SecondaryEmailRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/secondary-email/verify": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "验证并绑定辅助邮箱",
                "parameters": [
                    {
                        "description": "邮箱与验证码",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.VerifySecondaryEmailRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/verify": {
            "post": {
                "description": "校验 token 是否有效；可在请求头带 X-Auth-Client / X-Auth-Client-Name 记录接入应用。",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "校验 JWT",
                "parameters": [
                    {
                        "description": "token",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.VerifyRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "valid、user",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/auth/verify-email": {
            "post": {
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "auth"
                ],
                "summary": "邮箱验证并完成注册",
                "parameters": [
                    {
                        "description": "账号与验证码",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/handlers.VerifyEmailRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "created、user",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/health": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "meta"
                ],
                "summary": "健康检查",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/public/registration-policy": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "public"
                ],
                "summary": "公开注册策略与 OAuth/Turnstile 开关",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/public/users": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "public"
                ],
                "summary": "公开用户目录",
                "responses": {
                    "200": {
                        "description": "total、users",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/public/users/{account}": {
            "get": {
                "description": "可选 Authorization：登录用户可看到点赞状态等扩展字段。",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "public"
                ],
                "summary": "公开用户主页",
                "parameters": [
                    {
                        "type": "string",
                        "description": "账号",
                        "name": "account",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Bearer（可选）",
                        "name": "Authorization",
                        "in": "header"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "user、profileLikeCount 等",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        },
        "/api/public/users/{account}/like": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "public"
                ],
                "summary": "主页点赞",
                "parameters": [
                    {
                        "type": "string",
                        "description": "被点赞用户账号",
                        "name": "account",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "handlers.CreateInviteRequest": {
            "type": "object",
            "properties": {
                "expiresAt": {
                    "type": "string"
                },
                "maxUses": {
                    "type": "integer"
                },
                "note": {
                    "type": "string"
                }
            }
        },
        "handlers.CreateUserRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "avatarUrl": {
                    "type": "string"
                },
                "bio": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "level": {
                    "type": "integer"
                },
                "password": {
                    "type": "string"
                },
                "phone": {
                    "type": "string"
                },
                "secondaryEmails": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "sproutCoins": {
                    "type": "integer"
                },
                "username": {
                    "type": "string"
                },
                "websiteUrl": {
                    "type": "string"
                }
            }
        },
        "handlers.ForgotPasswordRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                }
            }
        },
        "handlers.LoginRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "clientId": {
                    "type": "string"
                },
                "clientName": {
                    "type": "string"
                },
                "password": {
                    "type": "string"
                },
                "turnstileToken": {
                    "type": "string"
                }
            }
        },
        "handlers.OAuthBindURLRequest": {
            "type": "object",
            "properties": {
                "returnTo": {
                    "type": "string"
                }
            }
        },
        "handlers.PutAdminOAuthRequest": {
            "type": "object",
            "properties": {
                "allowOAuthSignUpWhenInviteRequired": {
                    "type": "boolean"
                },
                "allowedReturnPrefixes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "giteaBaseUrl": {
                    "type": "string"
                },
                "giteaClientId": {
                    "type": "string"
                },
                "giteaClientSecret": {
                    "type": "string"
                },
                "giteaEnabled": {
                    "type": "boolean"
                },
                "giteaLogoUrl": {
                    "type": "string"
                },
                "githubClientId": {
                    "type": "string"
                },
                "githubClientSecret": {
                    "type": "string"
                },
                "githubEnabled": {
                    "type": "boolean"
                },
                "githubLogoUrl": {
                    "type": "string"
                },
                "googleClientId": {
                    "type": "string"
                },
                "googleClientSecret": {
                    "type": "string"
                },
                "googleEnabled": {
                    "type": "boolean"
                },
                "googleLogoUrl": {
                    "type": "string"
                },
                "linuxdoClientId": {
                    "type": "string"
                },
                "linuxdoClientSecret": {
                    "type": "string"
                },
                "linuxdoConnectBaseUrl": {
                    "type": "string"
                },
                "linuxdoEnabled": {
                    "type": "boolean"
                },
                "linuxdoLogoUrl": {
                    "type": "string"
                },
                "microsoftClientId": {
                    "type": "string"
                },
                "microsoftClientSecret": {
                    "type": "string"
                },
                "microsoftEnabled": {
                    "type": "boolean"
                },
                "microsoftLogoUrl": {
                    "type": "string"
                },
                "microsoftTenant": {
                    "type": "string"
                }
            }
        },
        "handlers.PutAdminTurnstileRequest": {
            "type": "object",
            "properties": {
                "enabled": {
                    "type": "boolean"
                },
                "secretKey": {
                    "type": "string"
                },
                "siteKey": {
                    "type": "string"
                }
            }
        },
        "handlers.RegisterRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "inviteCode": {
                    "type": "string"
                },
                "password": {
                    "type": "string"
                },
                "turnstileToken": {
                    "type": "string"
                },
                "username": {
                    "type": "string"
                }
            }
        },
        "handlers.ResetPasswordRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "code": {
                    "type": "string"
                },
                "newPassword": {
                    "type": "string"
                }
            }
        },
        "handlers.SecondaryEmailRequest": {
            "type": "object",
            "properties": {
                "email": {
                    "type": "string"
                }
            }
        },
        "handlers.UpdateCheckInConfigRequest": {
            "type": "object",
            "properties": {
                "rewardCoins": {
                    "type": "integer"
                }
            }
        },
        "handlers.UpdateProfileRequest": {
            "type": "object",
            "properties": {
                "avatarUrl": {
                    "type": "string"
                },
                "bio": {
                    "type": "string"
                },
                "password": {
                    "type": "string"
                },
                "phone": {
                    "type": "string"
                },
                "username": {
                    "type": "string"
                },
                "websiteUrl": {
                    "type": "string"
                }
            }
        },
        "handlers.UpdateRegistrationPolicyRequest": {
            "type": "object",
            "properties": {
                "forbiddenAccounts": {
                    "type": "string"
                },
                "inviteRegisterRewardCoins": {
                    "description": "nil 表示不修改此项",
                    "type": "integer"
                },
                "requireInviteCode": {
                    "type": "boolean"
                }
            }
        },
        "handlers.UpdateUserRequest": {
            "type": "object",
            "properties": {
                "avatarUrl": {
                    "type": "string"
                },
                "banReason": {
                    "type": "string"
                },
                "banned": {
                    "type": "boolean"
                },
                "bio": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "level": {
                    "type": "integer"
                },
                "password": {
                    "type": "string"
                },
                "phone": {
                    "type": "string"
                },
                "secondaryEmails": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "sproutCoins": {
                    "type": "integer"
                },
                "username": {
                    "type": "string"
                },
                "websiteUrl": {
                    "type": "string"
                }
            }
        },
        "handlers.VerifyEmailRequest": {
            "type": "object",
            "properties": {
                "account": {
                    "type": "string"
                },
                "code": {
                    "type": "string"
                }
            }
        },
        "handlers.VerifyRequest": {
            "type": "object",
            "properties": {
                "token": {
                    "type": "string"
                }
            }
        },
        "handlers.VerifySecondaryEmailRequest": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                }
            }
        }
    },
    "securityDefinitions": {
        "AdminToken": {
            "description": "管理端令牌；也可使用 Query `token` 或与部分客户端相同的 `Authorization` 头（见实现）。",
            "type": "apiKey",
            "name": "X-Admin-Token",
            "in": "header"
        },
        "BearerAuth": {
            "description": "JWT：Authorization 头填写「Bearer 」+ token（示例：Bearer eyJ...）。",
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    }
}