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

## 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 字符，与若依账户规则一致） |

**示例**

```http
GET /app/auth/usernameAvailable?userName=herder01
```

### 2.2 响应

统一 `AjaxResult`：`code`、`msg`、`data`。

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

**成功示例**

```json
{
  "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 加密） |

**示例**

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

### 3.2 响应

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

**成功示例**

```json
{
  "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）

```javascript
// 校验用户名
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 |