1. 获取用户详情 （用于面板中持久化保存用户信息）

接口地址： /merchantapi/user/user/userdetail

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "user": {
      "id": 1000,
      "username": "test1000", //用户名
      "nickname": "张三", // 昵称；为空时后端按 username 生成默认昵称
      "email": "", //邮箱
      "is_freeze": 0, // 商户账号冻结状态：0=正常，1=已冻结
      "create_at": "2025-11-19 00:29:41", //店铺(商户账号)开通时间
      "avatar": "https://fast.qqss.net/static/common/images/noavatar.png", // 用户头像
      "has_cash_pwd": true, //是否已设置二级密码
      "has_user_collect": true, //是否已绑定收款资料（与用户端共用）
      "collect_status": 1, //收款资料审核状态：0=待审核，1=已通过，null=未绑定
      "has_hall": 0 //是否已开通货源大厅：0=否，1=是（新增于 2026-02-05）
    },
    "perms": ["merchantapi/workbench/index", "merchantapi/shop/link/index"] //用户权限列表
  }
}

2. 设置用户头像

接口地址： /merchantapi/user/user/setAvatar

请求方式： POST

请求参数：

参数名	类型	必填	说明
avatar	string	是	头像 URL

响应示例：

{
  "code": 1,
  "msg": "保存成功"
}

---

3. 设置用户昵称

接口地址： /merchantapi/user/user/setNickname

请求方式： POST

请求参数：

参数名	类型	必填	说明
nickname	string	是	昵称，1-10 个字符

响应示例：

{
  "code": 1,
  "msg": "保存成功"
}

说明：

• username 继续作为系统用户名/账号标识使用，昵称展示请优先使用 nickname
• 如果用户未设置昵称，详情接口会返回后端生成的默认昵称

---

4. 绑定邮箱

接口地址： /merchantapi/user/user/bindEmail

请求方式： POST

请求参数：

参数名	类型	必填	说明
email	string	是	邮箱地址
code	string	是	邮箱验证码

响应示例：

{
  "code": 1,
  "msg": "保存成功"
}

---

5. 绑定 QQ

接口地址： /merchantapi/user/user/bindqq

请求方式： POST

请求参数：

参数名	类型	必填	说明
qq	string	是	QQ 号码

响应示例：

{
  "code": 1,
  "msg": "保存成功"
}

---

6. 发送绑定邮箱验证码

接口地址： /merchantapi/user/user/sendEmailCode

请求方式： POST

请求参数：

参数名	类型	必填	说明
email	string	是	邮箱地址

响应示例：

{
  "code": 1,
  "msg": "发送成功"
}

说明： 验证码有效期 5 分钟，前端请做1分钟限流

---

7. 设置二级密码

接口地址： /merchantapi/user/user/setCashPwd

请求方式： POST

请求参数：

参数名	类型	必填	说明
cash_pwd	string	是	二级密码
email_code	string	是	当前绑定邮箱收到的验证码

响应示例：

{
  "code": 1,
  "msg": "保存成功"
}

业务规则：

• 首次设置和修改密码都需要提供 cash_pwd 和 email_code

---

8. 发送二级密码邮箱验证码

接口地址： /merchantapi/user/user/sendEmailCodeForCashPwd（使用当前用户的邮箱）

响应示例：

{
  "code": 1,
  "msg": "发送成功"
}

说明：

• 发送至用户邮箱地址，没有绑定邮箱时会提示 邮箱不能为空
• 验证码有效期5分钟，前端请做1分钟限流

---

9. MiniApp 商户登录

接口地址： /merchantapi/user/user/miniAppMerchantLogin

请求方式： POST

认证： 无

请求参数：

参数名	类型	必填	说明
initData	string	是	MiniApp window.Telegram.WebApp.initData
shop_name	string	否	店铺名称；首次开通商户时可传
merchant_spread_id	int	否	商户邀请人 ID；从 merchant_spread_{ID} 解析，仅首次注册商户端时生效

响应示例：

{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "merchant_opened": true
  }
}

说明：

• 此接口用于商户端 MiniApp 授权登录
• merchant_opened=true 表示本次登录刚完成商户开通，商户端会展示用户端资料继承结果
• 后端会校验 initData，校验通过后创建或获取用户
• 登录用户会被开通或确认商户身份，user_type=1
• 首次开通商户时会初始化店铺、默认角色、信誉分、推广关系和登录日志
• 如果 用户没有 username，系统会使用 tg_用户ID 作为用户名
• Telegram first_name、last_name 会在首次创建用户或用户昵称为空时写入 nickname
• 登录成功后前端将 access_token 按商户端登录态保存，后续商户端接口使用 Authorization: Bearer {access_token}
• 旧参数 spread_id 暂时兼容；新前端统一使用 merchant_spread_id，已有商户不会因再次打开邀请链接而改绑

---

10. 开发环境商户测试账号登录

接口地址： /merchantapi/user/user/generateUserToken

请求方式： POST

认证： 无

请求参数：

参数名	类型	必填	说明
username	string	是	测试商户用户名
nickname	string	否	测试商户昵称；不传时后端按 username 生成默认昵称
sub	int/string	是	测试商户用户 ID
shop_name	string	否	店铺名称；首次开通商户时可传
merchant_spread_id	int	否	商户邀请人 ID；仅首次注册商户端时生效

响应示例：

{
  "code": 1,
  "msg": "生成token成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "merchant_opened": true
  }
}

说明：

• 此接口仅在 .env 中 DEVELOPMENT=1 时可用，正式环境会返回不支持
• 参数与用户端测试 token 接口保持一致：username、sub
• 接口会创建或获取用户，并开通或确认商户身份
• merchant_opened 与正式 MiniApp 登录接口语义一致，便于测试首次开通资料继承流程
• 会初始化店铺、默认角色、信誉分、推广关系和登录日志