MTKJPAY/mt-pay/ERP_USER_API.md

ERP用户管理API文档

概述

ERP用户管理模块提供了用户注册、登录等基础功能，支持账号、密码、店铺号管理。

数据库表

erp_user 表结构

执行以下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

请求体：

{
  "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个字符，必须唯一

响应示例：

{
  "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

请求体：

{
  "username": "testuser",
  "password": "123456"
}

参数说明：

• username (必填): 账号
• password (必填): 密码

响应示例：

{
  "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：

@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测试注册接口

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测试登录接口

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