{
  "info": {
    "_postman_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "sproutgate-api",
    "description": "萌芽账户认证中心：统一登录注册、令牌与资料、每日签到、公开用户目录与主页点赞、管理端用户与注册策略等 JSON HTTP 接口。集合变量 `baseUrl` 已指向生产环境，调试前请填写 `jwtToken`（用户 JWT）或 `adminToken`（管理端令牌）。",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://auth.api.shumengya.top",
      "type": "string"
    },
    {
      "key": "jwtToken",
      "value": "",
      "type": "string"
    },
    {
      "key": "adminToken",
      "value": "",
      "type": "string"
    },
    {
      "key": "account",
      "value": "demo",
      "type": "string"
    },
    {
      "key": "inviteCode",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "服务说明",
      "item": [
        {
          "name": "API 根信息",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/",
            "description": "返回 API 名称、版本与路由前缀说明。"
          },
          "response": []
        },
        {
          "name": "API 根信息 /api",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api",
            "description": "与 GET / 相同。"
          },
          "response": []
        },
        {
          "name": "健康检查",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/health",
            "description": "服务存活与运行环境标识。"
          },
          "response": []
        }
      ]
    },
    {
      "name": "认证 /api/auth",
      "item": [
        {
          "name": "登录",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"password\": \"\",\n  \"clientId\": \"\",\n  \"clientName\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/login",
            "description": "账号密码登录，返回 JWT 与用户信息。可选 clientId/clientName 用于记录接入应用（亦可通过请求头 X-Auth-Client / X-Auth-Client-Name）。"
          },
          "response": []
        },
        {
          "name": "注册",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"password\": \"\",\n  \"username\": \"\",\n  \"email\": \"\",\n  \"inviteCode\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/register",
            "description": "新用户注册（策略由服务端配置决定，可能要求邀请码）。"
          },
          "response": []
        },
        {
          "name": "邮箱验证",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"code\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/verify-email",
            "description": "提交邮箱验证码完成验证。"
          },
          "response": []
        },
        {
          "name": "忘记密码",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"email\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/forgot-password",
            "description": "请求向绑定邮箱发送重置流程（具体行为以后端为准）。"
          },
          "response": []
        },
        {
          "name": "重置密码",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"code\": \"\",\n  \"newPassword\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/reset-password",
            "description": "使用验证码设置新密码。"
          },
          "response": []
        },
        {
          "name": "辅助邮箱 - 请求验证码",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/secondary-email/request",
            "description": "已登录用户为辅助邮箱请求验证码。"
          },
          "response": []
        },
        {
          "name": "辅助邮箱 - 验证",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"\",\n  \"code\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/secondary-email/verify",
            "description": "提交验证码完成辅助邮箱绑定。"
          },
          "response": []
        },
        {
          "name": "校验 JWT",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"token\": \"{{jwtToken}}\"\n}"
            },
            "url": "{{baseUrl}}/api/auth/verify",
            "description": "校验 token 是否有效并返回用户公开信息。可选请求头 X-Auth-Client、X-Auth-Client-Name 记录接入方。"
          },
          "response": []
        },
        {
          "name": "当前用户（含签到摘要）",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              },
              {
                "key": "X-Visit-Ip",
                "value": "",
                "description": "可选，覆盖访问 IP；留空则使用服务端看到的客户端 IP。",
                "disabled": true
              },
              {
                "key": "X-Visit-Location",
                "value": "",
                "description": "可选，若为空且配置了地理位置服务则可能根据 IP 解析。",
                "disabled": true
              },
              {
                "key": "X-Auth-Client",
                "value": "",
                "disabled": true
              },
              {
                "key": "X-Auth-Client-Name",
                "value": "",
                "disabled": true
              }
            ],
            "url": "{{baseUrl}}/api/auth/me",
            "description": "需 Authorization: Bearer。返回用户资料与今日签到相关字段，并记录访问信息。"
          },
          "response": []
        },
        {
          "name": "每日签到",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/auth/check-in",
            "description": "当日签到领取萌芽币等奖励。"
          },
          "response": []
        },
        {
          "name": "更新个人资料",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"password\": null,\n  \"username\": null,\n  \"phone\": null,\n  \"avatarUrl\": null,\n  \"websiteUrl\": null,\n  \"bio\": null\n}"
            },
            "url": "{{baseUrl}}/api/auth/profile",
            "description": "部分字段更新；未修改的字段可省略或置为 null。"
          },
          "response": []
        }
      ]
    },
    {
      "name": "公开 /api/public",
      "item": [
        {
          "name": "公开用户目录",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/public/users",
            "description": "列出未封禁用户的公开目录项（按注册时间排序）。"
          },
          "response": []
        },
        {
          "name": "公开用户主页",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}",
                "description": "可选；带上时返回访客点赞状态等额外字段。",
                "disabled": true
              }
            ],
            "url": "{{baseUrl}}/api/public/users/{{account}}",
            "description": "按账号获取公开资料与点赞数；可选 JWT 用于访客视角。"
          },
          "response": []
        },
        {
          "name": "主页点赞",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{jwtToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/public/users/{{account}}/like",
            "description": "对已登录用户给指定主页点赞（有每日次数等限制）。"
          },
          "response": []
        },
        {
          "name": "注册策略（公开）",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/public/registration-policy",
            "description": "前端展示用：是否需要邀请码等公开策略。"
          },
          "response": []
        }
      ]
    },
    {
      "name": "管理 /api/admin",
      "item": [
        {
          "name": "用户列表",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/admin/users",
            "description": "管理端：列出全部用户（需 X-Admin-Token，或 Query token=、或 Authorization Bearer）。本请求使用集合变量 adminToken。"
          },
          "response": []
        },
        {
          "name": "创建用户",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"account\": \"\",\n  \"password\": \"\",\n  \"username\": \"\",\n  \"email\": \"\",\n  \"level\": 0,\n  \"sproutCoins\": 0,\n  \"secondaryEmails\": [],\n  \"phone\": \"\",\n  \"avatarUrl\": \"\",\n  \"websiteUrl\": \"\",\n  \"bio\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/admin/users",
            "description": "管理端创建用户。"
          },
          "response": []
        },
        {
          "name": "更新用户",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"password\": null,\n  \"username\": null,\n  \"email\": null,\n  \"level\": null,\n  \"sproutCoins\": null,\n  \"secondaryEmails\": null,\n  \"phone\": null,\n  \"avatarUrl\": null,\n  \"websiteUrl\": null,\n  \"bio\": null,\n  \"banned\": null,\n  \"banReason\": null\n}"
            },
            "url": "{{baseUrl}}/api/admin/users/{{account}}",
            "description": "管理端更新用户字段；封禁等会触发 token 失效策略。"
          },
          "response": []
        },
        {
          "name": "删除用户",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/admin/users/{{account}}",
            "description": "管理端删除用户。"
          },
          "response": []
        },
        {
          "name": "签到配置 - 获取",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/admin/check-in/config",
            "description": "获取每日签到奖励萌芽币配置。"
          },
          "response": []
        },
        {
          "name": "签到配置 - 更新",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"rewardCoins\": 1\n}"
            },
            "url": "{{baseUrl}}/api/admin/check-in/config",
            "description": "设置每次签到奖励（必须大于 0）。"
          },
          "response": []
        },
        {
          "name": "注册策略 - 获取（含邀请码列表）",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/admin/registration",
            "description": "管理端查看注册策略与邀请码条目。"
          },
          "response": []
        },
        {
          "name": "注册策略 - 更新",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"requireInviteCode\": false,\n  \"forbiddenAccounts\": \"\",\n  \"inviteRegisterRewardCoins\": null\n}"
            },
            "url": "{{baseUrl}}/api/admin/registration",
            "description": "更新是否必填邀请码、禁用账号名单、邀请注册奖励等。"
          },
          "response": []
        },
        {
          "name": "创建邀请码",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"note\": \"\",\n  \"maxUses\": 1,\n  \"expiresAt\": \"\"\n}"
            },
            "url": "{{baseUrl}}/api/admin/registration/invites",
            "description": "新增邀请码；expiresAt 格式以后端校验为准（通常 ISO 时间字符串）。"
          },
          "response": []
        },
        {
          "name": "删除邀请码",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "X-Admin-Token",
                "value": "{{adminToken}}"
              }
            ],
            "url": "{{baseUrl}}/api/admin/registration/invites/{{inviteCode}}",
            "description": "按邀请码删除。"
          },
          "response": []
        }
      ]
    }
  ]
}