# NEX Docus 数据库设计文档

## 数据库连接信息
- **数据库类型**: MySQL 5.7.5+
- **连接地址**: 10.100.51.51:3306
- **数据库名**: nex_docus
- **字符集**: utf8mb4
- **排序规则**: utf8mb4_unicode_ci

## Redis 缓存
- **连接地址**: 10.100.51.51:6379
- **用途**: Session 存储、Token 黑名单、文件上传临时缓存

---

## 1. 用户认证相关表

### 1.1 用户表 (`users`)

存储系统用户基本信息。

```sql
CREATE TABLE `users` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '用户ID',
  `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名（登录账号）',
  `password_hash` VARCHAR(255) NOT NULL COMMENT '密码哈希（bcrypt）',
  `nickname` VARCHAR(50) DEFAULT NULL COMMENT '昵称（显示名称）',
  `email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
  `phone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
  `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
  `is_superuser` TINYINT DEFAULT 0 COMMENT '是否超级管理员：0-否 1-是',
  `last_login_at` DATETIME DEFAULT NULL COMMENT '最后登录时间',
  `last_login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最后登录IP',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX `idx_username` (`username`),
  INDEX `idx_email` (`email`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
```

### 1.2 角色表 (`roles`)

定义系统角色。

```sql
CREATE TABLE `roles` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '角色ID',
  `role_name` VARCHAR(50) NOT NULL UNIQUE COMMENT '角色名称',
  `role_code` VARCHAR(50) NOT NULL UNIQUE COMMENT '角色编码（如：admin, editor, viewer）',
  `description` VARCHAR(255) DEFAULT NULL COMMENT '角色描述',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
  `is_system` TINYINT DEFAULT 0 COMMENT '是否系统角色：0-否 1-是（系统角色不可删除）',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX `idx_role_code` (`role_code`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色表';
```

**预置角色数据**:
```sql
INSERT INTO `roles` (`role_name`, `role_code`, `description`, `is_system`) VALUES
('超级管理员', 'super_admin', '拥有系统所有权限', 1),
('项目管理员', 'project_admin', '可以创建和管理项目', 1),
('普通用户', 'user', '可以查看和编辑被授权的项目', 1),
('访客', 'guest', '只读权限', 1);
```

### 1.3 用户角色关联表 (`user_roles`)

用户与角色多对多关系。

```sql
CREATE TABLE `user_roles` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '关联ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `role_id` BIGINT NOT NULL COMMENT '角色ID',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  UNIQUE KEY `uk_user_role` (`user_id`, `role_id`),
  INDEX `idx_user_id` (`user_id`),
  INDEX `idx_role_id` (`role_id`),
  FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,
  FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联表';
```

---

## 2. 权限与菜单管理

### 2.1 系统菜单表 (`system_menus`)

定义系统功能菜单和权限点。

```sql
CREATE TABLE `system_menus` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '菜单ID',
  `parent_id` BIGINT DEFAULT 0 COMMENT '父菜单ID（0表示根菜单）',
  `menu_name` VARCHAR(50) NOT NULL COMMENT '菜单名称',
  `menu_code` VARCHAR(50) NOT NULL UNIQUE COMMENT '菜单编码（权限标识）',
  `menu_type` TINYINT NOT NULL COMMENT '菜单类型：1-目录 2-菜单 3-按钮/权限点',
  `path` VARCHAR(255) DEFAULT NULL COMMENT '路由路径',
  `component` VARCHAR(255) DEFAULT NULL COMMENT '组件路径',
  `icon` VARCHAR(100) DEFAULT NULL COMMENT '图标',
  `sort_order` INT DEFAULT 0 COMMENT '排序号',
  `visible` TINYINT DEFAULT 1 COMMENT '是否可见：0-隐藏 1-显示',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
  `permission` VARCHAR(100) DEFAULT NULL COMMENT '权限字符串（如：project:create）',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX `idx_parent_id` (`parent_id`),
  INDEX `idx_menu_code` (`menu_code`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统菜单表';
```

**预置菜单数据**:
```sql
INSERT INTO `system_menus` (`id`, `parent_id`, `menu_name`, `menu_code`, `menu_type`, `path`, `icon`, `sort_order`, `permission`) VALUES
(1, 0, '项目管理', 'project', 1, '/projects', 'FolderOutlined', 1, NULL),
(2, 1, '我的项目', 'my_projects', 2, '/projects/my', NULL, 1, 'project:view'),
(3, 1, '创建项目', 'create_project', 3, NULL, NULL, 2, 'project:create'),
(4, 1, '编辑项目', 'edit_project', 3, NULL, NULL, 3, 'project:edit'),
(5, 1, '删除项目', 'delete_project', 3, NULL, NULL, 4, 'project:delete'),
(10, 0, '文档管理', 'document', 1, '/documents', 'FileTextOutlined', 2, NULL),
(11, 10, '查看文档', 'view_document', 3, NULL, NULL, 1, 'document:view'),
(12, 10, '编辑文档', 'edit_document', 3, NULL, NULL, 2, 'document:edit'),
(13, 10, '删除文档', 'delete_document', 3, NULL, NULL, 3, 'document:delete'),
(20, 0, '系统管理', 'system', 1, '/system', 'SettingOutlined', 3, NULL),
(21, 20, '用户管理', 'user_manage', 2, '/system/users', NULL, 1, 'system:user:view'),
(22, 20, '角色管理', 'role_manage', 2, '/system/roles', NULL, 2, 'system:role:view');
```

### 2.2 角色菜单授权表 (`role_menus`)

角色与菜单权限的多对多关系。

```sql
CREATE TABLE `role_menus` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '关联ID',
  `role_id` BIGINT NOT NULL COMMENT '角色ID',
  `menu_id` BIGINT NOT NULL COMMENT '菜单ID',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  UNIQUE KEY `uk_role_menu` (`role_id`, `menu_id`),
  INDEX `idx_role_id` (`role_id`),
  INDEX `idx_menu_id` (`menu_id`),
  FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE,
  FOREIGN KEY (`menu_id`) REFERENCES `system_menus`(`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色菜单授权表';
```

---

## 3. 项目与文档管理

### 3.1 项目表 (`projects`)

存储项目基本信息。

```sql
CREATE TABLE `projects` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '项目ID',
  `name` VARCHAR(100) NOT NULL COMMENT '项目名称',
  `description` VARCHAR(500) DEFAULT NULL COMMENT '项目描述',
  `storage_key` CHAR(36) NOT NULL COMMENT '磁盘存储UUID（物理文件夹名）',
  `owner_id` BIGINT NOT NULL COMMENT '项目所有者ID',
  `is_public` TINYINT DEFAULT 0 COMMENT '是否公开：0-私有 1-公开',
  `is_template` TINYINT DEFAULT 0 COMMENT '是否模板项目：0-否 1-是',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-归档 1-活跃',
  `cover_image` VARCHAR(255) DEFAULT NULL COMMENT '封面图',
  `sort_order` INT DEFAULT 0 COMMENT '排序号',
  `visit_count` INT DEFAULT 0 COMMENT '访问次数',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  UNIQUE KEY `uk_storage_key` (`storage_key`),
  INDEX `idx_owner_id` (`owner_id`),
  INDEX `idx_name` (`name`),
  INDEX `idx_status` (`status`),
  INDEX `idx_created_at` (`created_at`),
  FOREIGN KEY (`owner_id`) REFERENCES `users`(`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='项目表';
```

### 3.2 项目成员表 (`project_members`)

项目协作成员管理。

```sql
CREATE TABLE `project_members` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '成员ID',
  `project_id` BIGINT NOT NULL COMMENT '项目ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `role` ENUM('admin', 'editor', 'viewer') DEFAULT 'viewer' COMMENT '项目角色：admin-管理员 editor-编辑者 viewer-查看者',
  `invited_by` BIGINT DEFAULT NULL COMMENT '邀请人ID',
  `joined_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '加入时间',
  UNIQUE KEY `uk_project_user` (`project_id`, `user_id`),
  INDEX `idx_project_id` (`project_id`),
  INDEX `idx_user_id` (`user_id`),
  INDEX `idx_role` (`role`),
  FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`) ON DELETE CASCADE,
  FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,
  FOREIGN KEY (`invited_by`) REFERENCES `users`(`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='项目成员表';
```

### 3.3 文档元数据表 (`document_meta`)

可选表，用于存储文档的额外元数据（标签、评论数等）。

```sql
CREATE TABLE `document_meta` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '元数据ID',
  `project_id` BIGINT NOT NULL COMMENT '项目ID',
  `file_path` VARCHAR(500) NOT NULL COMMENT '文件相对路径',
  `title` VARCHAR(200) DEFAULT NULL COMMENT '文档标题',
  `tags` VARCHAR(500) DEFAULT NULL COMMENT '标签（JSON数组）',
  `author_id` BIGINT DEFAULT NULL COMMENT '作者ID',
  `word_count` INT DEFAULT 0 COMMENT '字数统计',
  `view_count` INT DEFAULT 0 COMMENT '浏览次数',
  `last_editor_id` BIGINT DEFAULT NULL COMMENT '最后编辑者ID',
  `last_edited_at` DATETIME DEFAULT NULL COMMENT '最后编辑时间',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  UNIQUE KEY `uk_project_path` (`project_id`, `file_path`),
  INDEX `idx_project_id` (`project_id`),
  INDEX `idx_author_id` (`author_id`),
  FULLTEXT KEY `ft_title_tags` (`title`, `tags`),
  FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`) ON DELETE CASCADE,
  FOREIGN KEY (`author_id`) REFERENCES `users`(`id`) ON DELETE SET NULL,
  FOREIGN KEY (`last_editor_id`) REFERENCES `users`(`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表';
```

---

## 4. 操作日志与审计

### 4.1 操作日志表 (`operation_logs`)

记录关键操作日志。

```sql
CREATE TABLE `operation_logs` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '日志ID',
  `user_id` BIGINT DEFAULT NULL COMMENT '操作用户ID',
  `username` VARCHAR(50) DEFAULT NULL COMMENT '用户名（冗余字段）',
  `operation_type` VARCHAR(50) NOT NULL COMMENT '操作类型（create, update, delete等）',
  `resource_type` VARCHAR(50) NOT NULL COMMENT '资源类型（project, document, user等）',
  `resource_id` BIGINT DEFAULT NULL COMMENT '资源ID',
  `detail` TEXT DEFAULT NULL COMMENT '操作详情（JSON）',
  `ip_address` VARCHAR(50) DEFAULT NULL COMMENT 'IP地址',
  `user_agent` VARCHAR(500) DEFAULT NULL COMMENT '用户代理',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-失败 1-成功',
  `error_message` TEXT DEFAULT NULL COMMENT '错误信息',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '操作时间',
  INDEX `idx_user_id` (`user_id`),
  INDEX `idx_resource` (`resource_type`, `resource_id`),
  INDEX `idx_created_at` (`created_at`),
  FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志表';
```

---

## 5. 文件存储说明

### 5.1 物理存储结构

**根目录**: `/data/nex_docus_store/`

```
/data/nex_docus_store/
├── projects/
│   ├── <project_uuid>/          # 项目文件夹（UUID命名）
│   │   ├── README.md            # 项目首页
│   │   ├── _assets/             # 资源文件夹（图片、附件）
│   │   │   ├── images/          # 图片
│   │   │   └── files/           # 附件
│   │   ├── <folder>/            # 用户创建的文件夹
│   │   │   └── *.md             # Markdown文档
│   │   └── ...
└── temp/                        # 临时文件（上传缓存）
```

### 5.2 存储规则

1. **项目隔离**: 每个项目使用独立的 UUID 文件夹
2. **路径映射**: `storage_key` 字段存储 UUID，数据库存储显示名称
3. **资源管理**: 图片和附件存储在 `_assets` 目录
4. **安全控制**: 所有文件访问必须经过权限验证
5. **备份策略**: 可直接备份 `/data/nex_docus_store/` 目录

---

## 6. 索引优化建议

1. **复合索引**:
   - `projects`: (`owner_id`, `status`)
   - `project_members`: (`project_id`, `role`)
   - `document_meta`: (`project_id`, `last_edited_at`)

2. **覆盖索引**: 针对高频查询添加包含查询字段的复合索引

3. **分区表**: 当 `operation_logs` 数据量大时，可按月份分区

---

## 7. 数据库初始化脚本

创建完整的初始化 SQL 文件：`backend/scripts/init_database.sql`

执行顺序：
1. 创建数据库
2. 创建所有表
3. 插入初始角色数据
4. 插入初始菜单数据
5. 创建默认管理员用户

---

## 8. 性能优化建议

1. **连接池配置**: SQLAlchemy 配置合理的连接池大小
2. **查询优化**: 使用 `joinedload` 避免 N+1 查询
3. **缓存策略**:
   - 用户信息缓存（5分钟）
   - 菜单权限缓存（10分钟）
   - 项目列表缓存（1分钟）
4. **读写分离**: 后续可配置主从数据库

---

**文档版本**: v1.0
**最后更新**: 2023-12-20
**维护人**: Mula.liu