user-system/docs/DATA_MODEL.md

数据模型设计

实现状态说明 (2026-03-29 更新)

本文档描述的是设计目标数据库结构，实际实现与设计存在以下差异：

与实际实现的差异

设计表格	实现状态	说明
user_credentials	⚠️ 合并实现	密码凭证存储在 users.password，TOTP数据在 users 表；社交账号在 user_social_accounts 表
audit_logs	⚠️ 命名差异	实际实现为 operation_logs 表
verification_codes	❌ 未实现	验证码当前在内存/Redis中管理，无独立表
token_blacklist	❌ 未实现	JWT吊销使用JTI机制，无需独立表
user_custom_fields	❌ 未实现	当前版本未支持此功能
system_configs	⚠️ 替代方案	系统配置通过 config.yaml 文件管理，无数据库表

实际实现的数据库表

当前 GORM AutoMigrate 实际创建的表：

• users
• roles
• permissions
• user_roles
• role_permissions
• devices
• login_logs
• operation_logs
• user_social_accounts
• webhooks
• webhook_deliveries
• password_history

---

概述

本文档描述用户管理系统的核心数据库表结构和字段定义。

支持的数据库

数据库	用途	特点
SQLite	默认数据库	无需独立部署，单文件存储，适合单机场景
PostgreSQL	生产环境可选	功能强大，支持高级特性，适合中大型应用
MySQL	生产环境可选	广泛使用，社区成熟，适合中大型应用
MongoDB	文档存储可选	灵活的文档存储，适合特定场景

注意：SQLite 作为默认数据库，所有表结构都兼容其他关系型数据库（PostgreSQL/MySQL），可通过配置文件平滑切换。

表结构设计

1. 用户表 (users)

用户基础信息表，存储用户的基本资料。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	用户 ID（主键）
username	VARCHAR	50	否	NULL	用户名（唯一索引）
email	VARCHAR	100	否	NULL	邮箱（唯一索引）
phone	VARCHAR	20	否	NULL	手机号（唯一索引）
nickname	VARCHAR	50	否	NULL	昵称
avatar	VARCHAR	255	否	NULL	头像 URL
gender	TINYINT	-	否	0	性别：0-未知，1-男，2-女
birthday	DATE	-	否	NULL	生日
region	VARCHAR	50	否	NULL	所在地区
bio	VARCHAR	500	否	NULL	个性签名
status	TINYINT	-	是	1	状态：0-待激活，1-正常，2-锁定，3-禁用
last_login_time	DATETIME	-	否	NULL	最后登录时间
last_login_ip	VARCHAR	50	否	NULL	最后登录 IP
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间
deleted_at	DATETIME	-	否	NULL	删除时间（软删除）

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_username (username)
• UNIQUE KEY uk_email (email)
• UNIQUE KEY uk_phone (phone)
• KEY idx_status (status)
• KEY idx_created_at (created_at)

---

2. 用户凭证表 (user_credentials)

用户凭证表，存储密码、社交绑定等信息。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	凭证 ID（主键）
user_id	BIGINT	-	是	-	用户 ID（外键）
credential_type	VARCHAR	20	是	-	凭证类型：password/wechat/qq/alipay/douyin/github/google
identifier	VARCHAR	100	是	-	标识符（openid、unionid 等）
credential_value	VARCHAR	500	否	NULL	凭证值（加密后的密码等）
salt	VARCHAR	100	否	NULL	盐值（用于密码加密）
is_primary	TINYINT	-	是	1	是否主要凭证：0-否，1-是
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• UNIQUE KEY uk_user_type_identifier (user_id, credential_type, identifier)

---

3. 角色表 (roles)

角色表，定义系统角色。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	角色 ID（主键）
name	VARCHAR	50	是	-	角色名称（唯一）
code	VARCHAR	50	是	-	角色代码（唯一）
description	VARCHAR	200	否	NULL	角色描述
parent_id	BIGINT	-	否	NULL	父角色 ID
level	INT	-	是	1	角色层级
is_system	TINYINT	-	是	0	是否系统角色：0-否，1-是
is_default	TINYINT	-	是	0	是否默认角色：0-否，1-是
status	TINYINT	-	是	1	状态：0-禁用，1-启用
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_name (name)
• UNIQUE KEY uk_code (code)
• KEY idx_parent_id (parent_id)
• KEY idx_level (level)
• KEY idx_is_default (is_default)

初始默认角色：

• id=1, code='admin', name='管理员', is_system=1, is_default=0 - 系统管理员角色，拥有所有权限
• id=2, code='user', name='普通用户', is_system=1, is_default=1 - 普通用户角色，基本权限

---

4. 权限表 (permissions)

权限表，定义系统权限。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	权限 ID（主键）
name	VARCHAR	50	是	-	权限名称
code	VARCHAR	100	是	-	权限代码（格式：resource:action）
resource	VARCHAR	50	是	-	资源名称
action	VARCHAR	20	是	-	操作类型（read/write/delete/execute）
description	VARCHAR	200	否	NULL	权限描述
type	VARCHAR	20	是	-	权限类型：api/page/button
group_id	BIGINT	-	否	NULL	权限分组 ID
status	TINYINT	-	是	1	状态：0-禁用，1-启用
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_code (code)
• KEY idx_resource (resource)
• KEY idx_group_id (group_id)
• KEY idx_type (type)

---

5. 用户角色关联表 (user_roles)

用户和角色的多对多关联表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	关联 ID（主键）
user_id	BIGINT	-	是	-	用户 ID
role_id	BIGINT	-	是	-	角色 ID
assigned_by	BIGINT	-	否	NULL	分配人 ID
assigned_at	DATETIME	-	是	CURRENT_TIMESTAMP	分配时间
expire_at	DATETIME	-	否	NULL	过期时间（NULL 表示永久）

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_user_role (user_id, role_id)
• KEY idx_role_id (role_id)

---

6. 角色权限关联表 (role_permissions)

角色和权限的多对多关联表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	关联 ID（主键）
role_id	BIGINT	-	是	-	角色 ID
permission_id	BIGINT	-	是	-	权限 ID
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_role_permission (role_id, permission_id)
• KEY idx_permission_id (permission_id)

---

7. 设备管理表 (devices)

用户设备管理表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	设备 ID（主键）
user_id	BIGINT	-	是	-	用户 ID
device_id	VARCHAR	100	是	-	设备唯一标识
device_name	VARCHAR	50	否	NULL	设备名称
device_type	VARCHAR	20	是	-	设备类型：pc/mobile/tablet
os	VARCHAR	50	否	NULL	操作系统
browser	VARCHAR	50	否	NULL	浏览器
ip	VARCHAR	50	否	NULL	IP 地址
location	VARCHAR	100	否	NULL	地理位置
is_trusted	TINYINT	-	是	0	是否信任：0-否，1-是
last_active_time	DATETIME	-	否	NULL	最后活跃时间
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• UNIQUE KEY uk_device_id (device_id)
• KEY idx_last_active_time (last_active_time)

---

8. 登录日志表 (login_logs)

用户登录日志表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	日志 ID（主键）
user_id	BIGINT	-	否	NULL	用户 ID
login_type	VARCHAR	20	是	-	登录方式：password/code/wechat/qq/...
login_method	VARCHAR	20	否	NULL	认证方式
ip	VARCHAR	50	否	NULL	IP 地址
location	VARCHAR	100	否	NULL	地理位置
device_id	VARCHAR	100	否	NULL	设备 ID
user_agent	VARCHAR	500	否	NULL	User-Agent
status	TINYINT	-	是	-	状态：0-失败，1-成功
failure_reason	VARCHAR	200	否	NULL	失败原因
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	登录时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• KEY idx_ip (ip)
• KEY idx_status (status)
• KEY idx_created_at (created_at)

分区设计（MySQL）：

• 按月分区，保留最近 12 个月数据

---

9. 审计日志表 (audit_logs)

系统审计日志表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	日志 ID（主键）
user_id	BIGINT	-	否	NULL	操作人 ID
action_type	VARCHAR	50	是	-	操作类型
resource_type	VARCHAR	50	是	-	资源类型
resource_id	BIGINT	-	否	NULL	资源 ID
action	VARCHAR	20	是	-	操作动作：create/update/delete
old_value	TEXT	-	否	NULL	操作前值
new_value	TEXT	-	否	NULL	操作后值
ip	VARCHAR	50	否	NULL	IP 地址
user_agent	VARCHAR	500	否	NULL	User-Agent
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	操作时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• KEY idx_resource_type (resource_type)
• KEY idx_created_at (created_at)

分区设计（MySQL）：

• 按月分区，保留最近 24 个月数据

---

10. 验证码表 (verification_codes)

验证码表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	验证码 ID（主键）
code	VARCHAR	20	是	-	验证码
type	VARCHAR	20	是	-	类型：register/login/reset_password/bind_phone/bind_email
identifier	VARCHAR	100	是	-	标识符（邮箱或手机号）
expire_at	DATETIME	-	是	-	过期时间
used	TINYINT	-	是	0	是否已使用：0-否，1-是
ip	VARCHAR	50	否	NULL	IP 地址
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_identifier_type (identifier, type)
• KEY idx_expire_at (expire_at)

---

11. Token 黑名单表 (token_blacklist)

Token 黑名单表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	记录 ID（主键）
user_id	BIGINT	-	是	-	用户 ID
token	VARCHAR	500	是	-	Token
token_type	VARCHAR	20	是	-	Token 类型：access/refresh
expire_at	DATETIME	-	是	-	过期时间
revoked_by	BIGINT	-	否	NULL	吊销人 ID
revoked_at	DATETIME	-	是	CURRENT_TIMESTAMP	吊销时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• KEY idx_expire_at (expire_at)

---

12. 用户自定义字段表 (user_custom_fields)

用户自定义字段表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	字段 ID（主键）
user_id	BIGINT	-	是	-	用户 ID
field_key	VARCHAR	50	是	-	字段键名
field_value	TEXT	-	否	NULL	字段值（JSON 格式）
field_type	VARCHAR	20	是	-	字段类型：string/number/boolean/date
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_user_id (user_id)
• UNIQUE KEY uk_user_key (user_id, field_key)

---

13. Webhook 配置表 (webhook_configs)

Webhook 配置表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	配置 ID（主键）
name	VARCHAR	50	是	-	Webhook 名称
event_types	TEXT	-	是	-	事件类型（JSON 数组）
url	VARCHAR	255	是	-	回调 URL
secret	VARCHAR	100	否	NULL	签名密钥
headers	TEXT	-	否	NULL	自定义请求头（JSON）
is_active	TINYINT	-	是	1	是否启用：0-否，1-是
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_is_active (is_active)

---

14. Webhook 日志表 (webhook_logs)

Webhook 日志表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	日志 ID（主键）
webhook_id	BIGINT	-	是	-	Webhook 配置 ID
event_type	VARCHAR	50	是	-	事件类型
event_data	TEXT	-	是	-	事件数据（JSON）
request_url	VARCHAR	255	是	-	请求 URL
request_headers	TEXT	-	否	NULL	请求头（JSON）
request_body	TEXT	-	否	NULL	请求体（JSON）
response_status	INT	-	否	NULL	响应状态码
response_body	TEXT	-	否	NULL	响应体
retry_count	INT	-	是	0	重试次数
status	VARCHAR	20	是	-	状态：pending/success/failed
error_message	TEXT	-	否	NULL	错误信息
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间

索引设计：

• PRIMARY KEY (id)
• KEY idx_webhook_id (webhook_id)
• KEY idx_event_type (event_type)
• KEY idx_status (status)
• KEY idx_created_at (created_at)

分区设计（MySQL）：

• 按月分区，保留最近 12 个月数据

---

15. 系统配置表 (system_configs)

系统配置表。

字段名	类型	长度	是否必填	默认值	说明
id	BIGINT	-	是	-	配置 ID（主键）
config_key	VARCHAR	100	是	-	配置键（唯一）
config_value	TEXT	-	否	NULL	配置值
config_type	VARCHAR	20	是	-	配置类型：string/number/boolean/json
description	VARCHAR	200	否	NULL	配置描述
is_system	TINYINT	-	是	0	是否系统配置：0-否，1-是
created_at	DATETIME	-	是	CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	-	是	CURRENT_TIMESTAMP ON UPDATE	更新时间

索引设计：

• PRIMARY KEY (id)
• UNIQUE KEY uk_config_key (config_key)

---

ER 图

erDiagram
    users ||--o{ user_credentials : "has"
    users ||--o{ user_roles : "has"
    users ||--o{ devices : "has"
    users ||--o{ login_logs : "has"
    users ||--o{ audit_logs : "has"
    users ||--o{ user_custom_fields : "has"
    users ||--o{ token_blacklist : "has"
    
    roles ||--o{ user_roles : "assigned to"
    roles ||--o{ role_permissions : "has"
    roles ||--o{ roles : "inherits from"
    
    permissions ||--o{ role_permissions : "assigned to"
    
    webhook_configs ||--o{ webhook_logs : "has"

---

MongoDB 结构设计

如果使用 MongoDB，建议采用以下集合结构：

users 集合

{
  "_id": ObjectId("..."),
  "username": "john_doe",
  "email": "john@example.com",
  "phone": "+86138xxxxxxxx",
  "nickname": "John",
  "avatar": "https://...",
  "profile": {
    "gender": 1,
    "birthday": "1990-01-01",
    "region": "北京",
    "bio": "...",
    "customFields": {
      "company": "ABC Inc.",
      "position": "Developer"
    }
  },
  "credentials": [
    {
      "type": "password",
      "hash": "...",
      "salt": "...",
      "isPrimary": true
    },
    {
      "type": "wechat",
      "openid": "...",
      "unionid": "..."
    }
  ],
  "roles": [1, 2],
  "devices": [
    {
      "deviceId": "...",
      "deviceName": "iPhone 15",
      "deviceType": "mobile",
      "isTrusted": true,
      "lastActiveTime": ISODate("2026-03-10T10:00:00Z")
    }
  ],
  "status": 1,
  "lastLogin": {
    "time": ISODate("2026-03-10T10:00:00Z"),
    "ip": "192.168.1.1"
  },
  "createdAt": ISODate("2026-01-01T00:00:00Z"),
  "updatedAt": ISODate("2026-03-10T10:00:00Z"),
  "deletedAt": null
}

roles 集合

{
  "_id": ObjectId("..."),
  "name": "普通用户",
  "code": "user",
  "description": "普通用户角色",
  "parentId": null,
  "level": 1,
  "isSystem": false,
  "status": 1,
  "permissions": [1, 2, 3],
  "createdAt": ISODate("2026-01-01T00:00:00Z"),
  "updatedAt": ISODate("2026-01-01T00:00:00Z")
}

permissions 集合

{
  "_id": ObjectId("..."),
  "name": "查看用户",
  "code": "user:read",
  "resource": "user",
  "action": "read",
  "description": "查看用户信息",
  "type": "api",
  "groupId": 1,
  "status": 1,
  "createdAt": ISODate("2026-01-01T00:00:00Z"),
  "updatedAt": ISODate("2026-01-01T00:00:00Z")
}

login_logs 集合

{
  "_id": ObjectId("..."),
  "userId": ObjectId("..."),
  "loginType": "password",
  "ip": "192.168.1.1",
  "location": "北京市",
  "device": {
    "deviceId": "...",
    "deviceName": "iPhone 15",
    "deviceType": "mobile",
    "os": "iOS 17",
    "browser": "Safari"
  },
  "status": 1,
  "failureReason": null,
  "createdAt": ISODate("2026-03-10T10:00:00Z")
}

---

索引策略

索引设计原则

1. 主键索引：所有表必须有主键
2. 唯一索引：用户名、邮箱、手机号等唯一字段
3. 复合索引：经常一起查询的字段组合
4. 覆盖索引：避免回表查询
5. 分区索引：大表按时间分区

常用查询优化

-- 用户登录查询
SELECT * FROM users 
WHERE (username = ? OR email = ? OR phone = ?) 
AND status = 1;

-- 角色权限查询
SELECT p.* FROM permissions p
INNER JOIN role_permissions rp ON p.id = rp.permission_id
WHERE rp.role_id IN (SELECT role_id FROM user_roles WHERE user_id = ?);

-- 登录日志统计
SELECT DATE(created_at) as date, COUNT(*) as count
FROM login_logs
WHERE user_id = ?
GROUP BY DATE(created_at)
ORDER BY date DESC;

---

数据迁移

初始化脚本

提供数据库初始化 SQL 脚本，包括：

1. 建表语句
2. 初始数据（默认角色、权限）
3. 索引创建
4. 分区设置

版本管理

使用数据库迁移工具（如 Flyway、Liquibase）管理数据库版本：

• 每次数据库结构变更需要迁移脚本
• 支持版本回滚
• 记录迁移历史

---

本文档持续更新中，如有疑问请联系技术团队。