认证与账户 API
认证与账户 API
本文归纳登录、验证码、用户信息、账号、地址、钱包、角色、菜单和权限相关接口。来源为 wt-admin、wt-client Controller 和前端 admin/src/api、client/api、ops/api。
使用场景
认证与账户接口支撑所有端的登录态和权限判断，是其他业务接口的前置条件：
| 场景 | 入口 | 说明 |
|---|---|---|
| 管理端登录 | /api/v1/captcha/image、/api/v1/login、/api/v1/info、/api/v1/routers |
登录后拉取用户信息和动态路由 |
| 消费者微信登录 | /api/v1/login/wechat、/api/v1/login/wechat/phone/bind |
未绑定手机号时必须先完成绑定 |
| 用户资料维护 | /api/v1/system/user/profile |
管理端和小程序复用当前用户资料接口 |
| 账户关系查询 | /api/v1/account/user |
判断当前用户关联的个人、商户、员工等账户 |
| 地址管理 | /api/v1/user/personal/address |
消费者下单前必须有可用收货地址 |
| 权限配置 | /api/v1/system/user、/api/v1/system/role、/api/v1/system/menu、/api/v1/system/permission |
管理端用户、角色、菜单和权限闭环 |
登录调用顺序
管理端和运营小程序账号密码登录：
- 调用
GET /api/v1/captcha/image获取验证码图片和uuid。 - 调用
POST /api/v1/login，提交用户名、密码、验证码和uuid。 - 保存返回的
token。 - 调用
GET /api/v1/info获取用户、角色和权限。 - 调用
GET /api/v1/routers获取菜单路由。
消费者微信登录：
- 小程序调用
wx.login获取微信临时code。 - 调用
POST /api/v1/login/wechat。 - 如果返回
phoneBound = true，保存登录态并进入业务页面。 - 如果返回
needBindPhone = true，只在当前页面临时保存登录结果。 - 用户授权手机号后，调用
POST /api/v1/login/wechat/phone/bind。 - 绑定成功后再写入本地
token、userId、personalAccountId。
后端认证逻辑
登录和权限链路由 wt-framework 安全配置、wt-system 用户权限模型和 wt-user 账户关系共同支撑。
| 环节 | 后端处理 |
|---|---|
| 验证码 | 生成验证码图片和 uuid，登录时按 uuid 校验验证码是否正确和过期 |
| 账号密码登录 | 校验用户存在、密码、状态、黑名单和登录限制，成功后签发 JWT |
| 当前用户信息 | 根据 Token 解析用户，查询角色、权限和账户关系 |
| 菜单路由 | 根据角色和菜单状态组装路由树，前端按路由动态挂载页面 |
| 微信登录 | 用微信 code 换取 openid，匹配或创建用户，未绑定手机号时返回绑定提示 |
| 手机号绑定 | 解密或换取手机号后绑定用户，补齐个人账户和登录态 |
鉴权失败排查顺序：
- 请求头是否带
Authorization: Bearer <token>。 - Token 是否过期或被强退。
- 用户状态是否启用。
- 角色是否绑定菜单。
- 菜单或权限标识是否与接口
@PreAuthorize一致。 - 前端代理是否把请求发到了正确的
admin或client入口。
关键字段
| 字段 | 说明 |
|---|---|
token |
后续接口鉴权 Token，前端放入 Authorization: Bearer <token> |
userId |
系统用户 ID |
personalAccountId |
消费者个人账户 ID，订单、地址、钱包等个人业务依赖该字段 |
merchantAccountId |
商户账户 ID，商户店铺、库存、发货和结算依赖该字段 |
employeeAccountId |
员工账户 ID，仓库和配送员任务依赖该字段 |
permissions |
当前用户权限标识集合，前端用于按钮和页面能力控制 |
roles |
当前用户角色集合 |
languageId |
用户语言配置，小程序登录会按语言传递 |
账户关系
一个系统用户可以关联多个业务账户，不同端进入业务时取用的账户 ID 不同。
| 账户 | 主要用途 | 常见业务 |
|---|---|---|
| 个人账户 | 消费者身份 | 地址、购物车、订单、评价、卡券钱包、个人钱包 |
| 商户账户 | 商户经营身份 | 店铺、库存、商户营销、发货、结算、提现 |
| 员工账户 | 员工作业身份 | 仓库管理员、配送员、商户员工、平台员工 |
| 企业账户 | 企业客户身份 | 企业资料、企业交易场景 |
| 政府账户 | 政府客户身份 | 政府资料和特定采购场景 |
业务接口不要只依赖 userId 判断数据范围。消费者订单应使用 personalAccountId，商户经营应使用 merchantAccountId，配送员任务应使用 employeeAccountId。
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 图形验证码 | GET |
/api/v1/captcha/image |
无 | 登录验证码 | admin、client、ops |
CaptchaController |
| shared | 账号密码登录 | POST |
/api/v1/login |
无 | 用户登录并获取 Token | admin、client、ops |
SysLoginController |
| shared | 当前用户信息 | GET |
/api/v1/info |
登录态 | 获取用户、角色、权限 | admin、client、ops |
SysLoginController |
| shared | 当前用户路由 | GET |
/api/v1/routers |
登录态 | 获取菜单路由 | admin、client、ops |
SysLoginController |
| client | 微信小程序登录 | POST |
/api/v1/login/wechat |
无 | 微信登录或自动注册 | client |
WxMiniProgramLoginController |
| client | 微信手机号绑定 | POST |
/api/v1/login/wechat/phone/bind |
登录态 | 绑定微信手机号 | client |
WxMiniProgramLoginController |
| client | 用户注册 | POST |
/api/v1/register |
无 | 个人账户注册 | client |
SysRegisterController |
| shared | 当前用户资料 | GET、PUT |
/api/v1/system/user/profile |
登录态 | 查看和修改个人资料 | admin、client |
SysProfileController |
| shared | 修改密码 | PUT |
/api/v1/system/user/profile/pwd |
登录态 | 修改当前用户密码 | admin、client |
SysProfileController |
| shared | 修改头像 | POST |
/api/v1/system/user/profile/avatar |
登录态 | 绑定头像文件 | client |
SysProfileController |
| shared | 上传头像 | POST |
/api/v1/system/user/profile/avatar/upload |
登录态 | 后端直传头像 | client |
SysProfileController |
| admin | 系统用户 | GET /page、GET /{userId}、POST、PUT、DELETE |
/api/v1/system/user |
admin:system:user:* |
后台用户管理 | admin |
SysUserController |
| admin | 角色管理 | GET /page、GET /{roleId}、POST、PUT、DELETE |
/api/v1/system/role |
admin:system:role:* |
角色和授权 | admin |
SysRoleController |
| admin | 菜单管理 | GET /list、GET /page、GET /tree/select、POST、PUT、DELETE |
/api/v1/system/menu |
admin:system:menu:* |
菜单和路由配置 | admin |
SysMenuController |
| admin | 权限管理 | GET /list、GET /page、GET /user/{userId}、GET /role/{roleId}、POST、PUT、DELETE |
/api/v1/system/permission |
admin:system:permission:* |
权限标识维护 | admin |
SysPermissionController |
| client | 客户端角色查询 | GET /page、GET /{roleId}、GET /admin/{roleId} |
/api/v1/system/role |
client:system:role:* |
客户端角色查询 | client、ops |
SysRoleController |
| client | 客户端菜单查询 | GET /list、GET /page、GET /tree/select、GET /tree/{roleId} |
/api/v1/system/menu |
client:system:menu:* |
客户端菜单查询 | client、ops |
SysMenuController |
| admin | 账户总览 | GET、GET /personal/account、GET /merchant/account、GET /employee/account |
/api/v1/account/user |
admin:user:account:* |
查询用户关联账户 | admin |
UserAccountController |
| client | 账户总览 | GET、GET /personal/account、GET /merchant/account、GET /employee/account |
/api/v1/account/user |
client:user:account:* |
查询当前用户账户关系 | client、ops |
UserAccountController |
| admin | 个人账户 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/user/personal/account |
admin:user:personal:account:* |
个人账户管理 | admin |
PersonalAccountController |
| client | 个人账户 | GET、GET /wallet、GET /wallet/balance、PUT |
/api/v1/user/personal/account |
client:user:personal:account:* |
当前个人账户资料 | client |
PersonalAccountController |
| admin | 企业账户 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/user/account/enterprise |
admin:user:enterprise:* |
企业账户管理 | admin |
EnterpriseAccountController |
| client | 企业账户 | GET、PUT |
/api/v1/user/account/enterprise |
client:user:enterprise:* |
当前企业账户资料 | client |
EnterpriseAccountController |
| admin | 政府账户 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/user/account/government |
admin:user:government:* |
政府账户管理 | admin |
GovernmentAccountController |
| admin | 商户账户 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/user/account/merchant |
admin:user:merchant:* |
商户账户管理 | admin |
MerchantAccountController |
| client | 商户账户 | GET、POST、PUT |
/api/v1/user/account/merchant |
client:user:merchant:* |
商户入驻和资料维护 | ops |
MerchantAccountController |
| shared | 商户账户文件 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/user/account/merchant/file |
*:user:merchant:file:* |
商户资质文件 | admin、ops |
MerchantAccountFileController |
| shared | 员工账户 | GET 或 GET /page、PUT |
/api/v1/user/account/employee |
*:user:employee:* |
员工账户查询和维护 | admin、ops |
EmployeeAccountController |
| admin | 收货地址管理 | GET /page、GET /{addressId}、POST、PUT、DELETE |
/api/v1/user/account/address |
admin:user:address:* |
后台地址管理 | admin |
AccountAddressController |
| client | 个人收货地址 | GET /page、GET /self、GET /{addressId}、POST、PUT、DELETE、PUT /{addressId}/isDefault |
/api/v1/user/personal/address |
client:user:personal:address:* |
小程序地址管理 | client |
PersonalAccountAddressController |
| client | 个人钱包 | GET /self、GET /{walletId}、POST /withdraw |
/api/v1/user/personal/wallet |
client:user:wallet:* |
个人钱包和提现 | client |
PersonalWalletController |
| client | 个人钱包流水 | GET /page、GET /{transactionId} |
/api/v1/user/personal/wallet/transaction |
client:user:wallet:transaction:* |
钱包流水查询 | client |
PersonalWalletTransactionController |
| client | 个人支付记录 | GET /list、GET /page、GET /{transactionId} |
/api/v1/user/personal/payment/transaction |
client:user:payment:transaction:* |
支付流水查询 | client |
PersonalPaymentTransactionController |
前端封装
admin/src/api/captchaApi.ts、usersApi.ts、roleApi.ts、menuApi.ts、accountApi.ts、walletApi.ts。client/api/index.js的user、file、data分组。ops/api/auth.js、ops/api/system.js。
维护注意事项
- 登录接口和用户资料接口是多端公共基础，变更字段时需要同步检查
admin、client和ops。 - 微信登录未绑定手机号时，前端不得写入完整登录态，避免用户绕过手机号绑定。
- 角色、菜单和权限变更后，需要验证
/api/v1/info和/api/v1/routers返回是否和管理端菜单一致。 - 地址接口需要保证默认地址唯一，下单页应优先使用默认地址。
- 头像上传成功后，小程序需要重新拉取用户资料并刷新本地缓存。
- 商户、员工和个人账户接口必须在后端做归属校验，不能只通过前端隐藏入口隔离数据。
联调验收
| 场景 | 验收口径 |
|---|---|
| 管理端登录 | 验证码、登录、用户信息、动态路由连续成功 |
| 权限控制 | 无权限用户访问接口返回 403 或业务拒绝，页面按钮不可见 |
| 微信未绑手机号 | 不写入完整登录态，绑定手机号后再进入业务首页 |
| 多账户用户 | 能正确查询个人、商户、员工等账户关系 |
| 默认地址 | 新增、修改和设置默认地址后，默认地址唯一 |
| 头像上传 | 上传后 fileId、头像 URL 和用户资料能同步刷新 |