huimv-baqing/doc/app/用户注册/用户注册接口说明.md

用户注册（移动端 / 小程序）

1. 概述

项	说明
Base Path	/app/auth
鉴权	匿名访问（无需 Token）；类上 @Anonymous，由 Spring Security 放行
用途	登录页「注册」：校验用户名是否可用、提交注册
用户表	sys_user；角色关联 sys_user_role
默认角色	sys_role.role_id = **2**（普通角色，role_key=common）
默认部门	dept_id = 100（与若依初始化根部门一致）

注册成功后，使用既有接口 POST /login（用户名 + 密码，及验证码若开启）登录。

---

2. 校验用户名是否可用

GET /app/auth/usernameAvailable

2.1 请求

参数	位置	必填	说明
userName	Query	是	拟注册的登录名（2～20 字符，与若依账户规则一致）

示例

GET /app/auth/usernameAvailable?userName=herder01

2.2 响应

统一 AjaxResult：code、msg、data。

字段	类型	说明
data.userName	string	回显（trim 后）
data.available	boolean	true 可用；false 已被占用

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userName": "herder01",
    "available": true
  }
}

业务失败（如用户名为空、长度不符）：code 非 200，msg 为错误说明。

---

3. 用户注册

POST /app/auth/register

3.1 请求

Content-Type: application/json

字段	类型	必填	说明
nickName	string	是	用户昵称，1～30 字符
userName	string	是	登录用户名，2～20 字符
password	string	是	登录密码，5～20 字符（入库前 BCrypt 加密）

示例

{
  "nickName": "牧民甲",
  "userName": "herder01",
  "password": "abc12345"
}

3.2 响应

字段	类型	说明
data.userId	long	新用户主键
data.userName	string	登录名

成功示例

{
  "code": 200,
  "msg": "注册成功",
  "data": {
    "userId": 100,
    "userName": "herder01"
  }
}

常见失败 msg

场景	说明
用户名已存在	与 usernameAvailable 为 false 时注册结果一致
参数校验失败	昵称/用户名/密码长度不符
默认角色不存在	库中无 role_id=2 时需运维补数据

---

4. 前端（小程序）对接要点

1. 注册页流程建议

   • 输入用户名 → 失焦或点击「检查」调用 §2；available=false 时提示「用户名已被占用」。
     
   • 填写昵称、密码、确认密码 → 调用 §3；成功后再跳转登录页或自动调 POST /login。

2. 请求基址

   • 与现有 ruoyi-ui-app 一致：config.js 中 baseUrl + 上表路径（注意网关 context-path）。

3. 请求头

   • 注册与校验接口不要带 Authorization。

4. 与 PC 端 /register 区别

   • PC 注册依赖系统参数 sys.account.registerUser 及图形验证码；
     
   • 小程序走 /app/auth/**，固定绑定角色 2，无验证码（按产品要求）。

5. 登录

   • 仍使用 @/api/login.js 中 POST /login。

4.1 调用示例（uni.request）

// 校验用户名
uni.request({
  url: baseUrl + '/app/auth/usernameAvailable',
  method: 'GET',
  data: { userName: 'herder01' },
  success(res) {
    const ok = res.data && res.data.code === 200 && res.data.data.available
  }
})

// 注册
uni.request({
  url: baseUrl + '/app/auth/register',
  method: 'POST',
  header: { 'Content-Type': 'application/json' },
  data: {
    nickName: '牧民甲',
    userName: 'herder01',
    password: 'abc12345'
  },
  success(res) {
    if (res.data && res.data.code === 200) {
      // 跳转登录
    }
  }
})

---

5. 后端实现索引

类	说明
AppAuthController	/app/auth 接口
IAppUserRegisterService	注册与校验
AppUserRegisterRules	DEFAULT_ROLE_ID=2、DEFAULT_DEPT_ID=100

---

6. 修订记录

版本	日期	说明
1.0	2026-05-25	初版：匿名注册、用户名可用性校验、默认角色 2