MTKJPAY/mt-pay/ERP_USER_API.md

# 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传输安全