# 数据库模型文档

## UserModel

UserModel 是一个用户管理模型，提供了基本的用户CRUD操作和查询方法。

### 主要特性

- ✅ 完整的CRUD操作
- ✅ 用户身份验证支持
- ✅ 用户名和邮箱唯一性验证
- ✅ 角色管理
- ✅ 时间戳自动管理

### 数据库字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 主键，自增 |
| username | string(100) | 用户名（必填，最大长度100） |
| email | string(100) | 邮箱（唯一） |
| password | string(100) | 密码（必填） |
| role | string(100) | 用户角色（必填） |
| phone | string(100) | 电话号码 |
| age | integer | 年龄（无符号整数） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 基本用法

```javascript
import { UserModel } from '../models/UserModel.js'

// 创建用户
const user = await UserModel.create({
    username: "zhangsan",
    email: "zhangsan@example.com",
    password: "hashedPassword",
    role: "user",
    phone: "13800138000",
    age: 25
})

// 查找所有用户
const allUsers = await UserModel.findAll()

// 根据ID查找用户
const user = await UserModel.findById(1)

// 根据用户名查找用户
const user = await UserModel.findByUsername("zhangsan")

// 根据邮箱查找用户
const user = await UserModel.findByEmail("zhangsan@example.com")

// 更新用户信息
await UserModel.update(1, {
    phone: "13900139000",
    age: 26
})

// 删除用户
await UserModel.delete(1)
```

### 查询方法

#### 基础查询
- `findAll()` - 查找所有用户
- `findById(id)` - 根据ID查找用户
- `findByUsername(username)` - 根据用户名查找用户
- `findByEmail(email)` - 根据邮箱查找用户

#### 数据操作
- `create(data)` - 创建新用户
- `update(id, data)` - 更新用户信息
- `delete(id)` - 删除用户

### 数据验证

#### 必填字段
- `username` - 用户名不能为空
- `password` - 密码不能为空
- `role` - 角色不能为空

#### 唯一性约束
- `email` - 邮箱必须唯一
- `username` - 建议在应用层实现唯一性验证

### 时间戳管理

系统自动管理以下时间戳：
- `created_at` - 创建时自动设置为当前时间
- `updated_at` - 每次更新时自动设置为当前时间

### 角色管理

支持用户角色字段，可用于权限控制：
```javascript
// 常见角色示例
const roles = {
    admin: "管理员",
    user: "普通用户",
    moderator: "版主"
}
```

### 错误处理

所有方法都包含适当的错误处理：
```javascript
try {
    const user = await UserModel.create({
        username: "", // 空用户名会抛出错误
        password: "password"
    })
} catch (error) {
    console.error("创建用户失败:", error.message)
}
```

### 性能优化

- 建议为 `username` 和 `email` 字段添加索引
- 支持分页查询（需要扩展实现）

### 迁移和种子

项目包含完整的数据库迁移和种子文件：
- `20250616065041_create_users_table.mjs` - 创建users表
- `20250616071157_users_seed.mjs` - 示例用户数据

### 运行迁移和种子

```bash
# 运行迁移
npx knex migrate:latest

# 运行种子
npx knex seed:run
```

### 安全注意事项

1. **密码安全**: 在创建用户前，确保密码已经过哈希处理
2. **输入验证**: 在应用层验证用户输入数据的有效性
3. **权限控制**: 根据用户角色实现适当的访问控制
4. **SQL注入防护**: 使用Knex.js的参数化查询防止SQL注入

### 扩展建议

可以考虑添加以下功能：
- 用户状态管理（激活/禁用）
- 密码重置功能
- 用户头像管理
- 用户偏好设置
- 登录历史记录
- 用户组管理