# 智能电网物联网设备后台管理系统 - 数据库文档

## 数据库基本信息

- **数据库名称**: `smart_grid_iot`
- **字符集**: `utf8mb4` (支持完整Unicode，包括emoji表情)
- **排序规则**: `utf8mb4_unicode_ci`
- **存储引擎**: `InnoDB` (支持事务、外键约束、行级锁)
- **MySQL版本要求**: 5.7+ / 8.0+ (推荐8.0+)

## 表清单

### 核心业务表（6张）

| 序号 | 表名 | 中文名称 | 说明 |
|------|------|----------|------|
| 1 | `users` | 用户表 | 存储系统用户信息，包括管理员和普通用户 |
| 2 | `roles` | 角色表 | 存储系统角色信息，用于RBAC权限控制 |
| 3 | `permissions` | 权限表 | 存储权限信息，支持菜单、按钮、API三种类型，支持树形结构 |
| 4 | `user_roles` | 用户角色关联表 | 用户与角色的多对多关联关系 |
| 5 | `role_permissions` | 角色权限关联表 | 角色与权限的多对多关联关系 |
| 6 | `operation_logs` | 操作日志表 | 记录用户操作行为，用于审计和安全追踪 |

## 表结构详细说明

### 1. users (用户表)

**用途**: 存储系统所有用户的基本信息和认证信息

**主要字段**:
- `id`: 主键，自增bigint
- `username`: 用户名，唯一索引
- `password`: bcrypt加密密码
- `nickname`: 昵称/显示名称
- `email`: 邮箱地址
- `phone`: 手机号码
- `avatar`: 头像URL
- `status`: 账户状态(0-禁用, 1-启用)
- `last_login_at`: 最后登录时间
- `last_login_ip`: 最后登录IP(支持IPv6)

**索引**:
- PRIMARY KEY (`id`)
- UNIQUE KEY `uk_username` (`username`)
- KEY `idx_status` (`status`) - 按状态筛选用户
- KEY `idx_created_at` (`created_at`) - 按时间排序

### 2. roles (角色表)

**用途**: 定义系统中的角色，实现基于角色的访问控制(RBAC)

**主要字段**:
- `id`: 主键
- `name`: 角色显示名称
- `code`: 角色编码(唯一标识符，如 super_admin)
- `description`: 角色描述
- `status`: 启用状态
- `sort_order`: 排序权重

**初始角色**:
1. **超级管理员** (super_admin) - 拥有系统所有权限
2. **普通管理员** (admin) - 拥有大部分管理权限
3. **运维人员** (operator) - 拥有设备管理和查看权限

### 3. permissions (权限表)

**用途**: 定义系统中的细粒度权限，支持树形菜单结构

**权限类型**:
- `menu`: 菜单权限(对应前端路由页面)
- `button`: 按钮权限(控制界面按钮显隐)
- `api`: API接口权限(控制后端接口访问)

**主要字段**:
- `parent_id`: 父权限ID(NULL表示一级菜单)
- `route`: 前端路由路径
- `component`: Vue组件路径
- `icon`: 菜单图标

**初始权限结构**:
```
├── 仪表盘 (dashboard)
├── 系统管理 (system)
│   ├── 用户管理 (user:list)
│   │   ├── 新增用户 (user:create)
│   │   ├── 编辑用户 (user:update)
│   │   ├── 删除用户 (user:delete)
│   │   └── 重置密码 (user:resetPwd)
│   └── 角色管理 (role:list)
│       ├── 新增角色 (role:create)
│       ├── 编辑角色 (role:update)
│       ├── 删除角色 (role:delete)
│       └── 分配权限 (role:assignPermission)
├── 系统设置 (settings)
│   ├── 基本设置 (system:basicSetting)
│   └── 安全设置 (system:securitySetting)
└── 操作日志 (log:operation)
```

### 4. user_roles (用户角色关联表)

**用途**: 实现用户与角色的多对多关系

**特点**:
- 联合唯一索引 `(user_id, role_id)` 防止重复分配
- 支持一个用户拥有多个角色
- 支持一个角色分配给多个用户

### 5. role_permissions (角色权限关联表)

**用途**: 实现角色与权限的多对多关系

**特点**:
- 联合唯一索引 `(role_id, permission_id)` 防止重复分配
- 通过批量授权提高效率
- 支持灵活的权限组合

### 6. operation_logs (操作日志表)

**用途**: 记录系统的操作日志，用于安全审计和问题追踪

**记录内容**:
- 操作人信息(user_id, username)
- 操作详情(action, module, method, url)
- 网络信息(ip_address, user_agent)
- 请求数据(request_params - JSON)
- 响应数据(response_data - JSON)
- 性能指标(duration - 毫秒)
- 错误信息(error_message - 仅失败时记录)

**索引优化**:
- `idx_user_id`: 按用户查询日志
- `idx_username`: 按用户名查询
- `idx_module`: 按模块筛选
- `idx_created_at`: 按时间范围查询

## 初始账户信息

### 管理员账户

- **用户名**: `admin`
- **密码**: `admin123456`
- **角色**: 超级管理员
- **权限**: 拥有系统所有权限

⚠️ **重要提示**: 首次登录后请立即修改默认密码！

## 如何执行初始化脚本

### 方式一: MySQL命令行客户端

```bash
# 登录MySQL
mysql -u root -p

# 执行初始化脚本
source /path/to/database/init.sql;

# 或者一行命令
mysql -u root -p < /path/to/database/init.sql
```

### 方式二: Navicat/DBeaver等GUI工具

1. 打开数据库连接工具
2. 新建查询窗口
3. 复制 init.sql 的全部内容
4. 执行SQL脚本(F5或点击执行按钮)

### 方式三: Node.js程序化执行

```javascript
const mysql = require('mysql2/promise');
const fs = require('fs');
const path = require('path');

async function initDatabase() {
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    password: 'your_password'
  });

  const sql = fs.readFileSync(
    path.join(__dirname, 'database/init.sql'),
    'utf-8'
  );

  await connection.query(sql);
  console.log('数据库初始化完成！');
  await connection.end();
}

initDatabase().catch(console.error);
```

## 注意事项

### 🔐 安全相关

1. **修改默认密码**: 首次登录后立即修改admin账户的默认密码
2. **密码加密**: 所有密码使用bcrypt加密存储(saltRounds=10)
3. **敏感数据**: operation_logs表可能包含敏感信息，注意访问控制
4. **备份策略**: 定期备份数据库，建议每日自动备份

### 📊 性能优化建议

1. **索引使用**: 已为常用查询字段建立索引，避免全表扫描
2. **日志清理**: operation_logs表会持续增长，建议定期归档或清理历史数据(如保留90天)
3. **连接池**: 应用层使用连接池管理数据库连接
4. **查询优化**: 避免SELECT *，只查询需要的字段

### 🔧 维护操作

```sql
-- 查看表结构和索引
SHOW CREATE TABLE users;
SHOW INDEX FROM users;

-- 查看数据量
SELECT
  table_name,
  table_rows,
  data_length/1024/1024 AS size_mb
FROM information_schema.tables
WHERE table_schema = 'smart_grid_iot';

-- 清理90天前的操作日志(谨慎执行!)
DELETE FROM operation_logs
WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);
```

### 📝 字符集说明

- 使用 **utf8mb4** 而非 utf8，因为：
  - utf8mb4支持完整的Unicode字符集(包括emoji)
  - utf8在MySQL中实际是utf8mb3，最多3字节
  - 某些特殊字符(如💡🔧)需要4字节编码

### 🚀 版本兼容性

- **MySQL 5.7+**: 完全兼容
- **MySQL 8.0+**: 推荐，支持更多特性(如CTE、窗口函数)
- **MariaDB 10.3+**: 基本兼容，但部分语法可能有差异

## ER关系图

```
users (1) ─────< (N) user_roles (N) >───── (1) roles (1) ─────< (N) role_permissions (N) >───── (1) permissions
                                                                                                        │
                                                                                                        ├─ type: menu (菜单)
                                                                                                        ├─ type: button (按钮)
                                                                                                        └─ type: api (接口)

users (1) ─────────────────────────────────────────────────────────────────────────────────────> (N) operation_logs
```

## 技术栈对接

### 后端 (Node.js + Sequelize)

实体文件位置: `server/src/entity/`
- [user.entity.ts](../server/src/entity/user.entity.ts) - User模型
- [role.entity.ts](../server/src/entity/role.entity.ts) - Role模型
- [permission.entity.ts](../server/src/entity/permission.entity.ts) - Permission模型
- [userRole.entity.ts](../server/src/entity/userRole.entity.ts) - UserRole关联模型
- [rolePermission.entity.ts](../server/src/entity/rolePermission.entity.ts) - RolePermission关联模型
- [operationLog.entity.ts](../server/src/entity/operationLog.entity.ts) - OperationLog模型

### 配置文件

数据库连接配置: `server/src/config/config.default.ts` 或 `config.local.ts`

---

**最后更新**: 2026-05-27
**维护者**: 开发团队