nex_docus/DATABASE.md

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)

存储系统用户基本信息。

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)

定义系统角色。

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='角色表';

预置角色数据:

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)

用户与角色多对多关系。

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)

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

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='系统菜单表';

预置菜单数据:

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)

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

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)

存储项目基本信息。

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 '访问次数',
  `git_repo_url` VARCHAR(255) DEFAULT NULL COMMENT 'Git仓库地址',
  `git_branch` VARCHAR(50) DEFAULT 'main' COMMENT 'Git分支',
  `git_username` VARCHAR(100) DEFAULT NULL COMMENT 'Git用户名',
  `git_token` VARCHAR(255) DEFAULT NULL COMMENT 'Git访问令牌/密码',
  `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)

项目协作成员管理。

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)

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

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)

记录关键操作日志。

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