edit | blame | history | raw

模拟账户 - 前端对接接口文档

一、说明

  • 主账户：注册时创建，可登录、充值、提现、切换至模拟账户。
  • 模拟账户：在**首次点击「切换至模拟账户」时自动创建**，与主账户一一绑定；**不能单独登录**，只能通过主账户登录后「切换」进入；功能与主账户一致，但**不支持充值、提现**，支持**重置资金**。
  • 所有需登录接口均在 Header 中携带：Authorization: Bearer {token}（或项目现有 token 方式）。

二、通用响应结构

{
  "data": {},     // 业务数据，成功时存在
  "code": 0,      // 0 表示成功，非 0 表示业务/系统错误
  "msg": "",      // 提示信息，失败时一般为错误文案
  "total": 0      // 部分列表接口有总数
}
  • 成功：code === 0，业务数据在 data 中。
  • 失败：code !== 0，错误信息在 msg 中。

三、登录 / 注册（与模拟账户相关部分）

1. 用户名密码登录（推荐用于「主账户」登录）

  • 地址：GET /api/user/login
  • 说明：仅主账户可登录；若传入的是模拟账户标识会报错。
  • 请求参数：Query
参数 类型 必填 说明
username string 是 用户名
password string 是 密码
  • 成功响应 data 示例：
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "用户登录名",
  "usercode": "用户UID/邀请码",
  "accountType": 0,
  "mainUserId": "主账户用户ID",
  "simUserId": "模拟账户用户ID或null"
}
字段 类型 说明
token string 访问令牌，后续请求 Header 携带
username string 当前登录用户名
usercode string 用户 UID/邀请码
accountType number 当前账户类型：0=主账户，1=模拟账户（登录接口必为 0）
mainUserId string 主账户 userId，用于展示/切换
simUserId string? 模拟账户 userId；尚未创建模拟账户时为 null（首次切换时会自动创建）
  • 失败示例（模拟账户尝试直接登录）：
{
  "data": null,
  "code": 1,
  "msg": "模拟账户不能直接登录，请使用主账户登录后切换"
}

2. 账号/手机/用户名登录（api 层）

  • 地址：POST /api/login
  • 说明：同上，仅主账户可登录；查到为模拟账户时返回错误。
  • 请求体：JSON（Content-Type: application/json）
参数 类型 必填 说明
userName string 是 账号/手机/用户名
passWord string 是 密码
type number 是 1=手机 2=邮箱 3=用户名
language string 否 如 "zh"/"en"，影响错误文案语言
userCode string 否 推荐码等
  • 成功响应：data 为 TokenInfoVO，其中 info 含模拟账户相关信息：
{
  "data": {
    "accessToken": "xxx",
    "refreshToken": "xxx",
    "expiresIn": 7200,
    "token": "xxx",
    "info": {
      "accountType": 0,
      "mainUserId": "主账户用户ID",
      "simUserId": "模拟账户用户ID或null"
    }
  },
  "code": 0,
  "msg": ""
}
  • 前端建议：登录成功后从 data.info 取 accountType、mainUserId、simUserId，用于展示「主/模拟」及是否可切换。

3. 注册（无验证码）

  • 地址：POST /api/registerNoVerifcode
  • 说明：注册成功即创建主账户 + 自动创建模拟账户；返回的 token 对应主账户，data.info 结构同 2。
  • 请求体：JSON
参数 类型 必填 说明
userName string 是 手机/邮箱/用户名
password string 是 密码
type number 是 1=手机 2=邮箱 3=用户名
userCode string 否 推荐码
  • 成功响应：data 同 2（含 info.accountType/mainUserId/simUserId），注册后 simUserId 一般非 null。

4. 注册（有验证码）

  • 地址：POST /api/registerVerifcode
  • 说明：同上，注册即主账户+模拟账户；返回结构同 2、3。
  • 请求体：在 3 的基础上增加 verifcode（验证码）等字段，按现有注册接口约定即可。

四、切换主账户 / 模拟账户

  • 地址：GET /api/user/switchAccount
  • 认证：需要登录（当前 token 可为「主账户」或「模拟账户」）。
  • 说明：
  • 当前为主账户 → 切换到模拟账户（若存在）；
  • 当前为模拟账户 → 切换回主账户。
    成功后返回**新 token**，前端需用新 token 替换旧 token，并更新本地缓存的 userId、accountType、mainUserId、simUserId。
  • 请求：无 Body，无 Query；Header 带当前 token。
  • 成功响应 data 示例：
{
  "token": "新的访问令牌，后续请求必须使用此 token",
  "userId": "当前身份对应的用户ID（主或模拟）",
  "accountType": 1,
  "username": "当前身份用户名",
  "usercode": "当前身份 UID",
  "mainUserId": "主账户用户ID",
  "simUserId": "模拟账户用户ID"
}
字段 类型 说明
token string 新 token，必须替换本地保存的 token
userId string 当前登录身份对应的 userId（主或模拟）
accountType number 0=主账户，1=模拟账户
mainUserId string 主账户 ID（不变）
simUserId string 模拟账户 ID（不变）
  • 说明：若主账户尚未创建模拟账户，接口会**先自动创建模拟账户再切换**，无需前端区分。仅当创建失败时才会返回错误。

五、重置模拟账户资金

  • 地址：POST /api/user/resetSimFunds
  • 认证：需要登录，且**当前必须为模拟账户**（accountType=1）。
  • 说明：将当前模拟账户的主钱包余额重置为系统配置的初始金额（如 100000），锁仓、冻结清零。
  • 请求：无 Body，无 Query；Header 带当前 token（必须是模拟账户 token）。
  • 成功响应 data 示例：
{
  "message": "重置成功",
  "balance": 100000
}
  • 失败示例（主账户调用）：
{
  "data": null,
  "code": 1,
  "msg": "仅模拟账户可重置资金"
}

六、前端逻辑建议

  1. 登录/注册后
  • 保存：token、userId、accountType、mainUserId、simUserId。
  • 主账户下可始终展示「切换至模拟账户」按钮（首次点击时后端会创建模拟账户并切换）；若 accountType === 1 可展示「切换回主账户」。
  1. 切换账户
  • 调用 GET /api/user/switchAccount，用返回的 data.token 覆盖本地 token。
  • 用返回的 userId、accountType、mainUserId、simUserId 更新本地状态。
  • 刷新资产、订单等依赖当前用户身份的接口。
  1. 模拟账户下
  • 隐藏或禁用「充值」「提现」入口；
  • 展示「重置资金」按钮，调用 POST /api/user/resetSimFunds。
  1. 错误处理
  • msg === "模拟账户不能直接登录，请使用主账户登录后切换"：提示用户使用主账户登录后再切换。
  • msg === "模拟账户不支持充值" / "模拟账户不支持提现"：在模拟账户下隐藏或禁用对应功能即可，一般不应让用户点到。

七、接口汇总

能力 方法 路径 说明
主账户登录 GET /api/user/login 返回 token + accountType/mainUserId/simUserId
账号密码登录 POST /api/login 返回 token，info 中含 accountType/mainUserId/simUserId
注册（无验证码） POST /api/registerNoVerifcode 同登录，含模拟账户信息
注册（有验证码） POST /api/registerVerifcode 同上
切换主/模拟账户 GET /api/user/switchAccount 返回新 token + 当前身份信息
重置模拟资金 POST /api/user/resetSimFunds 仅模拟账户，重置主钱包余额

八、注意事项

  • 所有上述接口的**基础路径**以实际部署为准（如 https://your-domain.com），若有统一网关前缀需自行加上。
  • Token 过期或未传时，接口会返回 401 等，前端需按现有逻辑跳转登录（主账户登录页）。
  • 模拟账户与主账户**共用同一套业务接口**（交易、资产等），仅充提与登录限制不同；前端通过 accountType 控制展示与禁用即可。