528 lines
17 KiB
Markdown
528 lines
17 KiB
Markdown
# Home4j 数据库设计文档
|
||
|
||
> **版本**：v1.0
|
||
> **更新日期**：2026年2月3日
|
||
> **数据库**：H2（默认）/ MySQL（可选）
|
||
|
||
---
|
||
|
||
## 一、设计原则
|
||
|
||
1. **简洁优先**：MVP 阶段保持表结构简单，避免过度设计
|
||
2. **扩展预留**：关键字段预留扩展空间（如 JSON 类型的 extra 字段）
|
||
3. **软删除**：重要数据支持软删除，便于恢复
|
||
4. **审计字段**：所有表包含创建时间、更新时间
|
||
|
||
---
|
||
|
||
## 二、实体关系图（ER Diagram）
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ t_user │ │ t_config │
|
||
├─────────────────┤ ├─────────────────┤
|
||
│ id (PK) │ │ id (PK) │
|
||
│ username │ │ config_key │
|
||
│ password_hash │ │ config_value │
|
||
│ role │ │ config_type │
|
||
│ ... │ │ ... │
|
||
└─────────────────┘ └─────────────────┘
|
||
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ t_group │ │ t_bookmark │
|
||
├─────────────────┤ ├─────────────────┤
|
||
│ id (PK) │◄──────│ id (PK) │
|
||
│ name │ 1:N │ group_id (FK) │
|
||
│ icon │ │ name │
|
||
│ sort_order │ │ url │
|
||
│ ... │ │ icon │
|
||
└─────────────────┘ │ sort_order │
|
||
│ ... │
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、数据表详细设计
|
||
|
||
### 3.1 用户表（t_user）
|
||
|
||
> 存储管理员账号信息，MVP 阶段仅支持单管理员
|
||
|
||
| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|
||
|-------|------|------|--------|------|
|
||
| `id` | BIGINT | PK, AUTO_INCREMENT | - | 主键 |
|
||
| `username` | VARCHAR(50) | NOT NULL, UNIQUE | - | 用户名 |
|
||
| `password_hash` | VARCHAR(255) | NOT NULL | - | 密码哈希（BCrypt） |
|
||
| `nickname` | VARCHAR(100) | - | NULL | 显示昵称 |
|
||
| `email` | VARCHAR(100) | - | NULL | 邮箱（预留） |
|
||
| `role` | VARCHAR(20) | NOT NULL | 'ADMIN' | 角色：ADMIN / USER |
|
||
| `status` | TINYINT | NOT NULL | 1 | 状态：1-正常 0-禁用 |
|
||
| `last_login_time` | TIMESTAMP | - | NULL | 最后登录时间 |
|
||
| `last_login_ip` | VARCHAR(50) | - | NULL | 最后登录IP |
|
||
| `created_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
**索引**：
|
||
- `uk_username` UNIQUE (`username`)
|
||
|
||
**SQL**：
|
||
```sql
|
||
CREATE TABLE t_user (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
username VARCHAR(50) NOT NULL,
|
||
password_hash VARCHAR(255) NOT NULL,
|
||
nickname VARCHAR(100),
|
||
email VARCHAR(100),
|
||
role VARCHAR(20) NOT NULL DEFAULT 'ADMIN',
|
||
status TINYINT NOT NULL DEFAULT 1,
|
||
last_login_time TIMESTAMP,
|
||
last_login_ip VARCHAR(50),
|
||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
CONSTRAINT uk_username UNIQUE (username)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 分组表（t_group）
|
||
|
||
> 书签的分类容器，支持排序和折叠
|
||
|
||
| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|
||
|-------|------|------|--------|------|
|
||
| `id` | BIGINT | PK, AUTO_INCREMENT | - | 主键 |
|
||
| `name` | VARCHAR(100) | NOT NULL | - | 分组名称 |
|
||
| `icon` | VARCHAR(255) | - | NULL | 图标（图标名/URL/base64） |
|
||
| `description` | VARCHAR(500) | - | NULL | 分组描述 |
|
||
| `sort_order` | INT | NOT NULL | 0 | 排序序号（升序） |
|
||
| `collapsed` | BOOLEAN | NOT NULL | FALSE | 是否默认折叠 |
|
||
| `visible` | BOOLEAN | NOT NULL | TRUE | 是否可见 |
|
||
| `color` | VARCHAR(20) | - | NULL | 主题色（预留 v1.0） |
|
||
| `created_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
**索引**：
|
||
- `idx_sort_order` (`sort_order`)
|
||
|
||
**SQL**：
|
||
```sql
|
||
CREATE TABLE t_group (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
name VARCHAR(100) NOT NULL,
|
||
icon VARCHAR(255),
|
||
description VARCHAR(500),
|
||
sort_order INT NOT NULL DEFAULT 0,
|
||
collapsed BOOLEAN NOT NULL DEFAULT FALSE,
|
||
visible BOOLEAN NOT NULL DEFAULT TRUE,
|
||
color VARCHAR(20),
|
||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
||
);
|
||
|
||
CREATE INDEX idx_group_sort_order ON t_group (sort_order);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 书签表（t_bookmark）
|
||
|
||
> 核心实体，存储书签链接信息
|
||
|
||
| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|
||
|-------|------|------|--------|------|
|
||
| `id` | BIGINT | PK, AUTO_INCREMENT | - | 主键 |
|
||
| `group_id` | BIGINT | FK, NOT NULL | - | 所属分组ID |
|
||
| `name` | VARCHAR(100) | NOT NULL | - | 书签名称 |
|
||
| `url` | VARCHAR(2000) | NOT NULL | - | 链接地址 |
|
||
| `icon` | VARCHAR(500) | - | NULL | 图标（图标名/URL/base64） |
|
||
| `icon_type` | VARCHAR(20) | NOT NULL | 'TEXT' | 图标类型：BUILTIN/URL/UPLOAD/TEXT/EMOJI |
|
||
| `description` | VARCHAR(500) | - | NULL | 书签描述 |
|
||
| `sort_order` | INT | NOT NULL | 0 | 排序序号（升序） |
|
||
| `open_in_new_tab` | BOOLEAN | NOT NULL | TRUE | 是否新标签页打开 |
|
||
| `pinned` | BOOLEAN | NOT NULL | FALSE | 是否置顶 |
|
||
| `visible` | BOOLEAN | NOT NULL | TRUE | 是否可见 |
|
||
| `click_count` | INT | NOT NULL | 0 | 点击次数（预留 v1.0） |
|
||
| `last_click_time` | TIMESTAMP | - | NULL | 最后点击时间（预留 v1.0） |
|
||
| `created_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
**索引**：
|
||
- `idx_group_id` (`group_id`)
|
||
- `idx_group_sort` (`group_id`, `sort_order`)
|
||
|
||
**外键**：
|
||
- `fk_bookmark_group` FOREIGN KEY (`group_id`) REFERENCES `t_group`(`id`)
|
||
|
||
**SQL**：
|
||
```sql
|
||
CREATE TABLE t_bookmark (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
group_id BIGINT NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
url VARCHAR(2000) NOT NULL,
|
||
icon VARCHAR(500),
|
||
icon_type VARCHAR(20) NOT NULL DEFAULT 'TEXT',
|
||
description VARCHAR(500),
|
||
sort_order INT NOT NULL DEFAULT 0,
|
||
open_in_new_tab BOOLEAN NOT NULL DEFAULT TRUE,
|
||
pinned BOOLEAN NOT NULL DEFAULT FALSE,
|
||
visible BOOLEAN NOT NULL DEFAULT TRUE,
|
||
click_count INT NOT NULL DEFAULT 0,
|
||
last_click_time TIMESTAMP,
|
||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
CONSTRAINT fk_bookmark_group FOREIGN KEY (group_id) REFERENCES t_group(id) ON DELETE CASCADE
|
||
);
|
||
|
||
CREATE INDEX idx_bookmark_group_id ON t_bookmark (group_id);
|
||
CREATE INDEX idx_bookmark_group_sort ON t_bookmark (group_id, sort_order);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 配置表（t_config）
|
||
|
||
> 存储应用级配置，Key-Value 结构
|
||
|
||
| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|
||
|-------|------|------|--------|------|
|
||
| `id` | BIGINT | PK, AUTO_INCREMENT | - | 主键 |
|
||
| `config_key` | VARCHAR(100) | NOT NULL, UNIQUE | - | 配置键 |
|
||
| `config_value` | TEXT | - | NULL | 配置值 |
|
||
| `config_type` | VARCHAR(20) | NOT NULL | 'STRING' | 值类型：STRING/NUMBER/BOOLEAN/JSON |
|
||
| `category` | VARCHAR(50) | NOT NULL | 'GENERAL' | 分类：GENERAL/APPEARANCE/LAYOUT |
|
||
| `description` | VARCHAR(255) | - | NULL | 配置说明 |
|
||
| `created_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
**索引**：
|
||
- `uk_config_key` UNIQUE (`config_key`)
|
||
- `idx_category` (`category`)
|
||
|
||
**SQL**：
|
||
```sql
|
||
CREATE TABLE t_config (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
config_key VARCHAR(100) NOT NULL,
|
||
config_value TEXT,
|
||
config_type VARCHAR(20) NOT NULL DEFAULT 'STRING',
|
||
category VARCHAR(50) NOT NULL DEFAULT 'GENERAL',
|
||
description VARCHAR(255),
|
||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
CONSTRAINT uk_config_key UNIQUE (config_key)
|
||
);
|
||
|
||
CREATE INDEX idx_config_category ON t_config (category);
|
||
```
|
||
|
||
**预置配置项**：
|
||
|
||
| config_key | config_value | config_type | category | 说明 |
|
||
|-----------|--------------|-------------|----------|------|
|
||
| `app.title` | Home4j | STRING | GENERAL | 网站标题 |
|
||
| `app.subtitle` | Welcome Home | STRING | GENERAL | 副标题 |
|
||
| `app.logo` | NULL | STRING | GENERAL | Logo URL |
|
||
| `app.favicon` | NULL | STRING | GENERAL | Favicon URL |
|
||
| `app.theme` | light | STRING | APPEARANCE | 当前主题 |
|
||
| `app.language` | zh-CN | STRING | GENERAL | 界面语言 |
|
||
| `layout.columns` | 4 | NUMBER | LAYOUT | 每行列数 |
|
||
| `layout.card_size` | normal | STRING | LAYOUT | 卡片尺寸 |
|
||
| `layout.density` | normal | STRING | LAYOUT | 显示密度 |
|
||
| `search.enabled` | true | BOOLEAN | GENERAL | 启用搜索 |
|
||
| `search.placeholder` | 搜索书签... | STRING | GENERAL | 搜索框占位符 |
|
||
| `init.completed` | false | BOOLEAN | GENERAL | 初始化是否完成 |
|
||
|
||
---
|
||
|
||
### 3.5 书签标签表（t_bookmark_tag）- 预留 v0.5
|
||
|
||
> 书签的标签，支持多对多关系（预留）
|
||
|
||
| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|
||
|-------|------|------|--------|------|
|
||
| `id` | BIGINT | PK, AUTO_INCREMENT | - | 主键 |
|
||
| `name` | VARCHAR(50) | NOT NULL, UNIQUE | - | 标签名称 |
|
||
| `color` | VARCHAR(20) | - | NULL | 标签颜色 |
|
||
| `created_at` | TIMESTAMP | NOT NULL | CURRENT_TIMESTAMP | 创建时间 |
|
||
|
||
**SQL**（预留）：
|
||
```sql
|
||
CREATE TABLE t_bookmark_tag (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
name VARCHAR(50) NOT NULL,
|
||
color VARCHAR(20),
|
||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
CONSTRAINT uk_tag_name UNIQUE (name)
|
||
);
|
||
|
||
-- 书签-标签关联表
|
||
CREATE TABLE t_bookmark_tag_rel (
|
||
bookmark_id BIGINT NOT NULL,
|
||
tag_id BIGINT NOT NULL,
|
||
PRIMARY KEY (bookmark_id, tag_id),
|
||
CONSTRAINT fk_rel_bookmark FOREIGN KEY (bookmark_id) REFERENCES t_bookmark(id) ON DELETE CASCADE,
|
||
CONSTRAINT fk_rel_tag FOREIGN KEY (tag_id) REFERENCES t_bookmark_tag(id) ON DELETE CASCADE
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 四、枚举值定义
|
||
|
||
### 4.1 用户角色（UserRole）
|
||
```java
|
||
public enum UserRole {
|
||
ADMIN, // 管理员，可编辑
|
||
USER // 普通用户（预留 v1.0）
|
||
}
|
||
```
|
||
|
||
### 4.2 图标类型（IconType）
|
||
```java
|
||
public enum IconType {
|
||
BUILTIN, // 内置图标库
|
||
URL, // 外部 URL
|
||
UPLOAD, // 用户上传
|
||
TEXT, // 文字首字母
|
||
EMOJI // Emoji 表情
|
||
}
|
||
```
|
||
|
||
### 4.3 配置类型（ConfigType）
|
||
```java
|
||
public enum ConfigType {
|
||
STRING, // 字符串
|
||
NUMBER, // 数字
|
||
BOOLEAN, // 布尔
|
||
JSON // JSON 对象
|
||
}
|
||
```
|
||
|
||
### 4.4 配置分类（ConfigCategory）
|
||
```java
|
||
public enum ConfigCategory {
|
||
GENERAL, // 常规设置
|
||
APPEARANCE, // 外观设置
|
||
LAYOUT // 布局设置
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、Quarkus Panache 实体示例
|
||
|
||
### 5.1 Bookmark 实体
|
||
|
||
```java
|
||
package com.home4j.entity;
|
||
|
||
import io.quarkus.hibernate.orm.panache.PanacheEntity;
|
||
import jakarta.persistence.*;
|
||
import java.time.LocalDateTime;
|
||
|
||
@Entity
|
||
@Table(name = "t_bookmark")
|
||
public class Bookmark extends PanacheEntity {
|
||
|
||
@ManyToOne(fetch = FetchType.LAZY)
|
||
@JoinColumn(name = "group_id", nullable = false)
|
||
public BookmarkGroup group;
|
||
|
||
@Column(nullable = false, length = 100)
|
||
public String name;
|
||
|
||
@Column(nullable = false, length = 2000)
|
||
public String url;
|
||
|
||
@Column(length = 500)
|
||
public String icon;
|
||
|
||
@Enumerated(EnumType.STRING)
|
||
@Column(name = "icon_type", nullable = false, length = 20)
|
||
public IconType iconType = IconType.TEXT;
|
||
|
||
@Column(length = 500)
|
||
public String description;
|
||
|
||
@Column(name = "sort_order", nullable = false)
|
||
public Integer sortOrder = 0;
|
||
|
||
@Column(name = "open_in_new_tab", nullable = false)
|
||
public Boolean openInNewTab = true;
|
||
|
||
@Column(nullable = false)
|
||
public Boolean pinned = false;
|
||
|
||
@Column(nullable = false)
|
||
public Boolean visible = true;
|
||
|
||
@Column(name = "click_count", nullable = false)
|
||
public Integer clickCount = 0;
|
||
|
||
@Column(name = "last_click_time")
|
||
public LocalDateTime lastClickTime;
|
||
|
||
@Column(name = "created_at", nullable = false, updatable = false)
|
||
public LocalDateTime createdAt;
|
||
|
||
@Column(name = "updated_at", nullable = false)
|
||
public LocalDateTime updatedAt;
|
||
|
||
@PrePersist
|
||
public void prePersist() {
|
||
createdAt = LocalDateTime.now();
|
||
updatedAt = LocalDateTime.now();
|
||
}
|
||
|
||
@PreUpdate
|
||
public void preUpdate() {
|
||
updatedAt = LocalDateTime.now();
|
||
}
|
||
|
||
// 常用查询方法
|
||
public static List<Bookmark> findByGroupId(Long groupId) {
|
||
return find("group.id = ?1 ORDER BY pinned DESC, sortOrder ASC", groupId).list();
|
||
}
|
||
|
||
public static List<Bookmark> findVisible() {
|
||
return find("visible = true ORDER BY pinned DESC, sortOrder ASC").list();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 BookmarkGroup 实体
|
||
|
||
```java
|
||
package com.home4j.entity;
|
||
|
||
import io.quarkus.hibernate.orm.panache.PanacheEntity;
|
||
import jakarta.persistence.*;
|
||
import java.time.LocalDateTime;
|
||
import java.util.List;
|
||
|
||
@Entity
|
||
@Table(name = "t_group")
|
||
public class BookmarkGroup extends PanacheEntity {
|
||
|
||
@Column(nullable = false, length = 100)
|
||
public String name;
|
||
|
||
@Column(length = 255)
|
||
public String icon;
|
||
|
||
@Column(length = 500)
|
||
public String description;
|
||
|
||
@Column(name = "sort_order", nullable = false)
|
||
public Integer sortOrder = 0;
|
||
|
||
@Column(nullable = false)
|
||
public Boolean collapsed = false;
|
||
|
||
@Column(nullable = false)
|
||
public Boolean visible = true;
|
||
|
||
@Column(length = 20)
|
||
public String color;
|
||
|
||
@OneToMany(mappedBy = "group", cascade = CascadeType.ALL, orphanRemoval = true)
|
||
public List<Bookmark> bookmarks;
|
||
|
||
@Column(name = "created_at", nullable = false, updatable = false)
|
||
public LocalDateTime createdAt;
|
||
|
||
@Column(name = "updated_at", nullable = false)
|
||
public LocalDateTime updatedAt;
|
||
|
||
@PrePersist
|
||
public void prePersist() {
|
||
createdAt = LocalDateTime.now();
|
||
updatedAt = LocalDateTime.now();
|
||
}
|
||
|
||
@PreUpdate
|
||
public void preUpdate() {
|
||
updatedAt = LocalDateTime.now();
|
||
}
|
||
|
||
// 常用查询方法
|
||
public static List<BookmarkGroup> findAllOrdered() {
|
||
return find("ORDER BY sortOrder ASC").list();
|
||
}
|
||
|
||
public static List<BookmarkGroup> findVisible() {
|
||
return find("visible = true ORDER BY sortOrder ASC").list();
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、数据初始化
|
||
|
||
### 6.1 首次启动初始化
|
||
|
||
```sql
|
||
-- 插入默认分组
|
||
INSERT INTO t_group (name, icon, sort_order, collapsed, visible)
|
||
VALUES ('默认分组', 'folder', 0, FALSE, TRUE);
|
||
|
||
-- 插入默认配置
|
||
INSERT INTO t_config (config_key, config_value, config_type, category, description) VALUES
|
||
('app.title', 'Home4j', 'STRING', 'GENERAL', '网站标题'),
|
||
('app.subtitle', 'Welcome Home', 'STRING', 'GENERAL', '副标题'),
|
||
('app.theme', 'light', 'STRING', 'APPEARANCE', '当前主题'),
|
||
('app.language', 'zh-CN', 'STRING', 'GENERAL', '界面语言'),
|
||
('layout.columns', '4', 'NUMBER', 'LAYOUT', '每行列数'),
|
||
('layout.card_size', 'normal', 'STRING', 'LAYOUT', '卡片尺寸'),
|
||
('search.enabled', 'true', 'BOOLEAN', 'GENERAL', '启用搜索'),
|
||
('init.completed', 'false', 'BOOLEAN', 'GENERAL', '初始化是否完成');
|
||
```
|
||
|
||
---
|
||
|
||
## 七、数据库配置
|
||
|
||
### 7.1 H2 配置（开发/默认）
|
||
|
||
```properties
|
||
# application.properties
|
||
quarkus.datasource.db-kind=h2
|
||
quarkus.datasource.jdbc.url=jdbc:h2:file:./data/home4j;AUTO_SERVER=TRUE
|
||
quarkus.datasource.username=sa
|
||
quarkus.datasource.password=
|
||
quarkus.hibernate-orm.database.generation=update
|
||
```
|
||
|
||
### 7.2 MySQL 配置（生产可选）
|
||
|
||
```properties
|
||
# application-mysql.properties
|
||
quarkus.datasource.db-kind=mysql
|
||
quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/home4j?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
|
||
quarkus.datasource.username=home4j
|
||
quarkus.datasource.password=your_password
|
||
quarkus.hibernate-orm.database.generation=update
|
||
```
|
||
|
||
---
|
||
|
||
## 八、表结构总览
|
||
|
||
| 表名 | 说明 | MVP | v0.5 | v1.0 |
|
||
|-----|------|-----|------|------|
|
||
| `t_user` | 用户表 | ✅ | ✅ | ✅ |
|
||
| `t_group` | 分组表 | ✅ | ✅ | ✅ |
|
||
| `t_bookmark` | 书签表 | ✅ | ✅ | ✅ |
|
||
| `t_config` | 配置表 | ✅ | ✅ | ✅ |
|
||
| `t_bookmark_tag` | 标签表 | - | ✅ | ✅ |
|
||
| `t_bookmark_tag_rel` | 书签标签关联 | - | ✅ | ✅ |
|
||
|
||
---
|
||
|
||
> **文档结束**
|
||
> 本设计将随项目进展持续更新
|