qiube
f7fbcc4138
- 在ResultCode中新增用户相关错误码（用户不存在、用户已存在、密码错误、Token无效等） - 创建ERP用户实体类ErpUser，包含账号、密码、店铺号等字段 - 实现用户注册功能，支持账号、手机号、邮箱唯一性校验 - 实现用户登录功能，支持密码验证和Token生成 - 添加Token验证机制，支持Bearer和自定义Header方式 - 创建用户管理API文档，包含注册、登录接口说明和错误码说明 - 实现IP地址获取功能，记录用户最后登录IP - 添加MD5密码加密和Token生成解析工具类 - 实现用户状态管理（激活/禁用）功能
254 lines
6.0 KiB
Markdown
254 lines
6.0 KiB
Markdown
# ERP用户管理API文档
|
||
|
||
## 概述
|
||
|
||
ERP用户管理模块提供了用户注册、登录等基础功能，支持账号、密码、店铺号管理。
|
||
|
||
## 数据库表
|
||
|
||
### erp_user 表结构
|
||
|
||
执行以下SQL创建表：
|
||
|
||
```sql
|
||
-- 文件位置：mt-pay/database/erp_user_schema.sql
|
||
```
|
||
|
||
表字段说明：
|
||
- `id`: 主键ID
|
||
- `username`: 账号（唯一，3-50个字符，只能包含字母、数字和下划线）
|
||
- `password`: 密码（MD5加密，6-20个字符）
|
||
- `nick_name`: 用户名称（可选，最大50个字符）
|
||
- `phone`: 手机号（可选，唯一，格式：1开头11位数字）
|
||
- `email`: 邮箱（可选，唯一，最大100个字符）
|
||
- `store_code`: 店铺号（最大50个字符）
|
||
- `status`: 状态（ACTIVE-激活，DISABLED-禁用）
|
||
- `last_login_time`: 最后登录时间
|
||
- `last_login_ip`: 最后登录IP
|
||
- `create_time`: 创建时间
|
||
- `update_time`: 更新时间
|
||
|
||
## API接口
|
||
|
||
### 1. 用户注册
|
||
|
||
**接口地址：** `POST /api/erp/user/register`
|
||
|
||
**请求头：**
|
||
```
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"storeCode": "STORE001",
|
||
"nickName": "测试用户",
|
||
"phone": "13800138000",
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `username` (必填): 账号，3-50个字符，只能包含字母、数字和下划线
|
||
- `password` (必填): 密码，6-20个字符
|
||
- `storeCode` (必填): 店铺号，最大50个字符
|
||
- `nickName` (可选): 用户名称，最大50个字符
|
||
- `phone` (可选): 手机号，格式：1开头11位数字（如：13800138000），必须唯一
|
||
- `email` (可选): 邮箱，最大100个字符，必须唯一
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": "0000",
|
||
"message": "注册成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"nickName": "测试用户",
|
||
"phone": "13800138000",
|
||
"email": "test@example.com",
|
||
"storeCode": "STORE001",
|
||
"status": "ACTIVE",
|
||
"createTime": "2024-12-24T10:00:00"
|
||
},
|
||
"timestamp": 1703412000000
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
- 账号已存在：`{"code": "6000", "message": "账号已存在"}`
|
||
- 手机号已被注册：`{"code": "6000", "message": "手机号已被注册"}`
|
||
- 邮箱已被注册：`{"code": "6000", "message": "邮箱已被注册"}`
|
||
- 参数验证失败：`{"code": "4001", "message": "参数验证失败"}`
|
||
|
||
---
|
||
|
||
### 2. 用户登录
|
||
|
||
**接口地址：** `POST /api/erp/user/login`
|
||
|
||
**请求头：**
|
||
```
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `username` (必填): 账号
|
||
- `password` (必填): 密码
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": "0000",
|
||
"message": "登录成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"nickName": "测试用户",
|
||
"phone": "13800138000",
|
||
"email": "test@example.com",
|
||
"storeCode": "STORE001",
|
||
"status": "ACTIVE",
|
||
"token": "MTIzNDU2Nzg5MGFiY2RlZjoxMjM0NTY3ODkwYWJjZGVmOjE3MDM0MTIwMDAwMDA6YWJjZGVmMTIzNDU2Nzg5MA==",
|
||
"tokenExpireTime": 1704016800000,
|
||
"lastLoginTime": "2024-12-24T10:00:00",
|
||
"lastLoginIp": "192.168.1.100"
|
||
},
|
||
"timestamp": 1703412000000
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
- 账号或密码错误：`{"code": "4002", "message": "账号或密码错误"}`
|
||
- 账号已被禁用：`{"code": "4003", "message": "账号已被禁用"}`
|
||
|
||
---
|
||
|
||
## Token使用说明
|
||
|
||
### Token生成
|
||
|
||
登录成功后，系统会返回一个`token`字段，该token的有效期为7天。
|
||
|
||
### Token验证
|
||
|
||
后续需要认证的接口，可以在请求头中携带token：
|
||
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
或者使用自定义header：
|
||
|
||
```
|
||
X-Auth-Token: {token}
|
||
```
|
||
|
||
### Token验证方法
|
||
|
||
在需要认证的接口中，可以通过以下方式验证token：
|
||
|
||
```java
|
||
@Autowired
|
||
private ErpUserService erpUserService;
|
||
|
||
// 验证token
|
||
ErpUser user = erpUserService.validateToken(token);
|
||
if (user == null) {
|
||
// Token无效或已过期
|
||
return Result.fail(ResultCode.TOKEN_INVALID);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 0000 | 操作成功 |
|
||
| 4000 | 参数错误 |
|
||
| 4001 | 参数验证失败 |
|
||
| 4002 | 未授权（账号或密码错误） |
|
||
| 4003 | 禁止访问（账号被禁用） |
|
||
| 6000 | 业务错误（账号已存在等） |
|
||
| 7001 | 用户不存在 |
|
||
| 7002 | 用户已存在 |
|
||
| 7003 | 密码错误 |
|
||
| 7004 | Token无效或已过期 |
|
||
|
||
---
|
||
|
||
## 安全说明
|
||
|
||
1. **密码加密**：密码使用MD5加密存储，生产环境建议使用BCrypt或Argon2等更安全的加密方式。
|
||
|
||
2. **Token安全**：
|
||
- 当前实现使用简单的MD5+Base64编码，生产环境建议使用JWT（JSON Web Token）
|
||
- Token包含用户ID、用户名、时间戳和签名
|
||
- Token有效期为7天，过期后需要重新登录
|
||
|
||
3. **IP记录**：系统会记录用户最后登录的IP地址，可用于安全审计。
|
||
|
||
4. **账号状态**：支持账号禁用功能，禁用后的账号无法登录。
|
||
|
||
---
|
||
|
||
## 后续扩展建议
|
||
|
||
1. **JWT Token**：将当前简单的Token实现替换为标准的JWT
|
||
2. **密码策略**：添加密码复杂度要求、密码过期策略
|
||
3. **登录限制**：添加登录失败次数限制、IP白名单等功能
|
||
4. **权限管理**：添加角色和权限管理功能
|
||
5. **操作日志**：记录用户的操作日志，便于审计
|
||
|
||
---
|
||
|
||
## 测试示例
|
||
|
||
### 使用curl测试注册接口
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/erp/user/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"storeCode": "STORE001",
|
||
"nickName": "测试用户",
|
||
"phone": "13800138000",
|
||
"email": "test@example.com"
|
||
}'
|
||
```
|
||
|
||
### 使用curl测试登录接口
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/erp/user/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 执行数据库表创建SQL后，才能使用注册和登录功能
|
||
2. 生产环境建议修改`TokenUtils`中的`TOKEN_SECRET`，使用更复杂的密钥
|
||
3. 建议在生产环境使用HTTPS协议，保护密码和Token传输安全
|
||
|