Chuyaoyuan/home4j
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Chuyaoyuan
2026-04-29 14:59:24 +08:00
parent e2fdaa8fe8
commit 8e96524e0b
81 changed files with 9151 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/20260205-181316.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

doc/FireShot Capture 039 - Home4j - [localhost].png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

doc/FireShot Capture 039 - Home4j - [localhost].png:Zone.Identifier
+3
View File
@@ -0,0 +1,3 @@
[ZoneTransfer]
ZoneId=3
HostUrl=chrome-extension://mcbpblocgmgfnpjjppndjkmgjaogfceg/
doc/FireShot Capture 040 - Home4j - [localhost].png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

doc/FireShot Capture 040 - Home4j - [localhost].png:Zone.Identifier
+3
View File
@@ -0,0 +1,3 @@
[ZoneTransfer]
ZoneId=3
HostUrl=chrome-extension://mcbpblocgmgfnpjjppndjkmgjaogfceg/
doc/FireShot Capture 041 - Home4j - [localhost].png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 688 KiB

doc/FireShot Capture 041 - Home4j - [localhost].png:Zone.Identifier
+3
View File
@@ -0,0 +1,3 @@
[ZoneTransfer]
ZoneId=3
HostUrl=chrome-extension://mcbpblocgmgfnpjjppndjkmgjaogfceg/
doc/Layout-theme-Multilingual.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 170 KiB

doc/README.md
+25
View File
@@ -0,0 +1,25 @@
home
1.综合参考
https://github.com/glanceapp/glance
https://github.com/gethomepage/homepage
https://github.com/Lissy93/dashy
https://github.com/linuxserver/Heimdall
2.优先参考
https://github.com/pawelmalak/flame
https://github.com/bastienwirtz/homer
https://daisyui.com/docs/cdn/
doc/card.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

doc/index.html
+76
View File
@@ -0,0 +1,76 @@
<!doctype html>
<html lang="zh" data-theme="light"> <!-- 可改成 dark、cupcake 等主题 -->
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>daisyUI 5 + Tailwind CSS 4 CDN 示例</title>
<!-- daisyUI 5 的核心 CSS（已优化到 ~34kB 压缩后，很适合 CDN 生产使用） -->
<!-- <script src="
https://cdn.jsdelivr.net/npm/daisyui@5.5.17/index.min.js
"></script> -->
<!-- <link href="
https://cdn.jsdelivr.net/npm/daisyui@5.5.17/daisyui.min.css
" rel="stylesheet"> -->
<script src="./js/browser@4.js"></script>
<link href="./css/daisyui@5.css" rel="stylesheet" type="text/css" />
<!-- <link rel="stylesheet" href="/css/tailwind.min.css"> -->
<!-- <script src="/js/daisyui.index.min.js"></script> -->
<!-- <link href="./css/themes.css" rel="stylesheet" type="text/css" /> -->
<!-- Tailwind CSS 4 的浏览器运行时引擎（必须放在 daisyUI 后面） -->
<!-- <script src="
https://cdn.jsdelivr.net/npm/tailwindcss@4.1.18/dist/lib.min.js
"></script> -->
<!-- <link href="
https://cdn.jsdelivr.net/npm/tailwindcss@4.1.18/index.min.css
" rel="stylesheet"> -->
</head>
<body class="min-h-screen bg-base-200 flex items-center justify-center p-8">
<div class="card w-96 bg-base-100 shadow-xl">
<figure>
<img
src="https://images.unsplash.com/photo-1556745757-8d76bdb6984f?ixlib=rb-4.0.3&auto=format&fit=crop&w=800&q=80"
alt="示例图片"
/>
</figure>
<div class="card-body">
<h2 class="card-title">daisyUI 5 + Tailwind 4</h2>
<p class="text-base-content/80">
这是一个纯 CDN 实现的卡片组件示例。<br>
无需 Node.js、无需构建步骤，<br>
支持所有 daisyUI 组件和 Tailwind 工具类。
</p>
<div class="card-actions justify-end mt-4">
<button class="btn btn-primary">主要按钮</button>
<button class="btn btn-outline btn-secondary">次要按钮</button>
</div>
</div>
</div>
<!-- 一些额外演示元素 -->
<div class="mt-12 flex flex-col items-center gap-6">
<button class="btn btn-lg btn-accent">大按钮 Accent</button>
<div class="badge badge-outline badge-info">Info 徽章</div>
<div class="badge badge-success gap-2">
<svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
</svg>
Success
</div>
<div class="alert alert-warning shadow-lg max-w-md">
<span>这是一个警告提示框示例！</span>
</div>
</div>
</body>
</html>
doc/jilu
+219
View File
@@ -0,0 +1,219 @@
你现在是一位拥有10年以上经验的高级产品经理 & 产品设计师，特别擅长从0到1设计SaaS、开源工具、开发者平台、基础设施类产品。你写的产品设计文档（PRD / PDD）逻辑清晰、结构完整、语言专业、重点突出、可执行性强。
请根据以下信息，为一个全新的项目撰写一份**完整的产品设计文档**。
### 参考的开源项目（请深度学习它们的优点、设计理念、功能组织方式、用户体验、架构思路等）
1.综合参考
https://github.com/glanceapp/glance
https://github.com/gethomepage/homepage
https://github.com/Lissy93/dashy
https://github.com/linuxserver/Heimdall
2.优先参考
https://github.com/pawelmalak/flame
https://github.com/bastienwirtz/homer
请从这些参考项目中提炼出最值得借鉴的模式、功能组织方式、用户心智模型、扩展性设计等，并应用到新项目中。
### 新项目基本信息
项目中文名称：Home4j
项目英文名称：Home4j
一句话核心目标：【为个人和小型团队打造极简、高性能、可自托管的Home 仪表盘和index导航工具】
目标用户群体：独立开发者、内容创作者、小团队、公司内部
使用场景举例：在flame、dashy、Heimdall、homer之间寻找更轻量替代品的用户，并习惯使用java
核心价值主张（一句话）：
因为市面较少有基于java的Home 仪表盘和导航工具，所以Home4j将提供一个轻量级、高度可定制的Home index解决方案，满足用户的特定需求。
主推技术栈（你（AI）也可以补充）:
- Java
- Solon
- Thymeleaf
- daisyui(CDN) - (之后可以支持自定义主题更换)
- h2 - (可以支持切换mysql)
- mybatisplus
- Docker
### 重要指令
1. **核心功能由你（AI）来定义**
请你根据项目目标、参考项目、目标用户痛点，**自主推导并决定**最应该包含的MVP核心功能，以及未来1-2年内值得扩展的重要功能。
不要依赖用户事先给出的功能列表，而是从“用户真实需求 + 参考项目最佳实践 + 差异化竞争力”三个维度去思考和设计。
2. 输出必须严格按照以下**中文结构**，使用Markdown格式，语言专业、简洁、有层次感
# 【项目中文名称】产品设计文档（PDD）
## 1. 概述与愿景
- 项目一句话介绍
- 核心价值主张
- 与竞品的差异化定位
- 从参考项目中学到的最关键启发
## 2. 用户与市场分析
- 目标用户画像（1-3个主要Persona，包含典型场景、痛点、期望）
- 竞品分析（至少3个主要竞品 + 参考开源项目的对比）
- 用户核心痛点与机会点总结
## 3. 核心功能设计（MVP）
- MVP范围界定说明
- 核心功能列表（建议用表格：功能名称 | 用户价值 | 优先级 | 参考来源）
- 每个核心功能的详细描述（包含用户故事、关键交互流程、验收标准）
## 4. 功能路线图（MVP → v1.0 → 未来方向）
- 分阶段功能规划（可用时间轴或表格表示）
- 每个阶段的关键里程碑
## 5. 用户体验与交互设计原则
- 整体设计语言与调性
- 核心用户旅程（建议画文字流程图或步骤描述）
- 关键页面/模块的交互逻辑说明
## 6. 技术架构与实现约束（产品视角）
- 推荐技术栈（语言、框架、数据库、自托管方式等）
- 部署方式（Docker、一键部署、Helm等）
- 扩展性与插件机制（如果适用）
- 性能与安全底线要求
## 7. 非功能性需求
- 性能目标
- 安全性与隐私保护
- 可观测性（日志、监控、tracing）
- 国际化与可访问性
## 8. 风险、挑战与应对
- 最大的3-5个风险点
- 对应的缓解措施
## 9. 附录
- 名词表 / 术语定义
- 参考资料与灵感来源
- 其他补充说明
请写得**详细但不冗长**（控制在3500-6000字之间），多使用表格、编号列表、加粗重点，让文档易读、易落地。
现在请开始撰写完整的产品设计文档。
# 启动命令
cd /e/test_code/test01/home4j && ./mvnw quarkus:dev
./mvnw quarkus:dev -DskipTests
cd /e/test_code/test01/home4j; ./mvnw quarkus:dev
cd /e/test_code/test01/home4j
./mvnw clean package -DskipTests
./mvnw package -DskipTests -Dquarkus.package.jar.type=uber-jar
JAR 文件位置
e:\test_code\test01\home4j\target\home4j-1.0.0-SNAPSHOT-runner.jar
java -jar home4j-1.0.0-SNAPSHOT-runner.jar
默认配置：
端口：8080
数据库：H2（内存数据库，重启丢失）
启动完成后，您可以访问：
地址 说明
http://localhost:8080 首页（重定向到登录）
http://localhost:8080/login 登录页面
http://localhost:8080/q/health 健康检查
http://localhost:8080/q/swagger-ui API 文档
默认管理员账号：
用户名：admin
密码：admin123
https://www.jsdelivr.com/package/npm/tailwindcss?tab=files&path=dist
https://www.jsdelivr.com/package/npm/daisyui?tab=files
你作为10多年的前端&全栈工程师，优化一下页面样式
第一步、主要参考并仔细理解daisyui 官方docs页面的样式和 组件代码等，地址：
https://github.com/saadeghi/daisyui/tree/master/packages/docs
第二步、并且我也附加了些参考图
Layout-theme-Multilingual.png （参考紧凑布局、右上角的 主题切换和多语言切换）
list.png （书签紧凑列表布局）
card.png （书签卡片布局，并且支持图标或图片的2中显示形式，文字上方居中和卡片背景显示）
第三步、主要需求：
1. 整体样式重构，参考daisyui首页的组件样式，优化Home4j的整体视觉风格，默认色系和daisyui docs相近，不用太高的饱和度和色彩避免过于艳丽
2. 实现daisyui一样的主题切换和多语言切换功能,在右侧用户图标旁边 (daisyui的themes.css已经引入 )
3. 提供书签的紧凑列表和卡片两种展示形式（1.紧凑列表布局 2.卡片布局，并且支持图标或图片的2中显示形式，文字上方居中和卡片背景显示）
4. 发现首页编辑时还是没有更换背景的功能，考虑一下，建议支持自定义背景图片或颜色
5. 确保在不同设备上的良好适配性
6. 关于排列，1.紧凑列表布局 默认5列摆放，每列按列表显示；2.卡片图标布局，不用太大，建议每行5列（5个）,每个卡片高度100左右，不用太大
7. 首页布局考虑加 日期时间 和天气显示，（例：左上角显示时间，时间为本机时间；右上角显示天气，地区默认为浏览器本地）
8. 其他优化你补充吧
不着急动代码，先和我确认改动点，我们讨论几次再改
1.搜索框位置：
保留单独的 Hero 区域
2.天气 API：
用免费的 wttr.in
3.多语言范围：
只切换 UI 文字
4.背景设置入口：
放在用户菜单下
5.主题持久化：
先只用 localStorage
6.卡片背景图
每个书签单独设置，是书签的设置项之一，可选 默认图标布局 还是 卡片背景布局
7.其他优化 ，全部赞同
你看是否还有其他问题
1.
选择 B. 简洁风格（无渐变，与 DaisyUI 文档类似），这个背景也会跟着主题切换改变颜色吗，还有页面下方的背景颜色会跟随主题改变吗，我的建议是需要改变
2.
选择 B. 放在工具栏中（搜索框下方的 sticky 工具栏）
3.
视图切换是全局切换，还是现在的工具栏位置（紧凑列表和 卡片布局）
卡片图标和卡片背景 只是书签的自定义设置，在书签编辑时设置
选择方案 B：两级设置
全局只切换「列表」和「卡片」
卡片模式下，每个书签自己选择「图标」或「背景图」
4. 书签新增字段 ，可以的
5. 分组标题样式
选择A. 分组标题独占一行（横跨 5 列），和之前一样，带隐藏和展开功能
6. 背景设置的数据存储
选择 B. 后端用户配置表（登录用户同步）
1.搜索框位置：
保留单独的 Hero 区域
搜索框不是应该在 单独的 Hero 区域吗，为什么在顶部导航栏，原来的工具栏也没有了？
不要动代码，先确认
doc/list.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 81 KiB

doc/功能列表.md
+535
View File
@@ -0,0 +1,535 @@
# Home4j 功能列表
> **版本**：v1.1
> **更新日期**：2026年2月3日
> **说明**：本文档定义 Home4j 的完整功能架构，从 MVP 到未来扩展，采用三级结构组织
---
## 核心定位说明
**Home4j 是一个导航工具**，核心竞争力是：
1. **Java 技术栈**：基于 Quarkus，对 Java 开发者友好
2. **轻量部署体验**：Docker 一键部署，资源占用低
3. **离线友好**：所有资源本地化，支持内网部署
---
## 功能优先级说明
| 标记 | 含义 | 版本规划 |
|-----|------|---------|
| 🔴 **P0** | 必须有，MVP 核心功能 | v0.1 |
| 🟡 **P1** | 重要，体验优化功能 | v0.5 |
| 🟢 **P2** | 增强，v1.0 完整功能 | v1.0 |
| ⚪ **P3** | 未来，长期规划功能 | v1.x+ |
---
## 一、书签管理模块 🔖
> 核心价值：快速访问和组织用户的常用链接
### 1.1 书签基础操作
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 1.1.1 添加书签 | 支持手动输入 URL、名称、描述创建书签 | 🔴 P0 |
| 1.1.2 编辑书签 | 修改书签的所有属性信息 | 🔴 P0 |
| 1.1.3 删除书签 | 单个删除，需二次确认 | 🔴 P0 |
| 1.1.4 批量删除 | 多选后批量删除书签 | 🟡 P1 |
| 1.1.5 书签排序 | 拖拽调整书签顺序 | 🔴 P0 |
| 1.1.6 书签复制 | 复制现有书签快速创建新书签 | 🟡 P1 |
### 1.2 书签属性配置
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 1.2.1 基础信息 | 名称、URL、描述 | 🔴 P0 |
| 1.2.2 图标设置 | 支持内置图标/URL图标/上传图标/自动获取favicon | 🔴 P0 |
| 1.2.3 分组归属 | 选择书签所属分组 | 🔴 P0 |
| 1.2.4 标签设置 | 为书签添加多个标签用于筛选 | 🟡 P1 |
| 1.2.5 打开方式 | 新标签页/当前页/iframe嵌入 | 🟡 P1 |
| 1.2.6 自定义颜色 | 书签卡片的强调色 | 🟢 P2 |
| 1.2.7 访问密码 | 单个书签的访问保护 | 🟢 P2 |
### 1.3 书签高级功能
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 1.3.1 URL 有效性检测 | 定期检查书签链接是否可访问 | 🟢 P2 |
| 1.3.2 Favicon 自动获取 | 根据 URL 自动抓取网站图标 | 🟡 P1 |
| 1.3.3 书签置顶 | 将重要书签置顶显示 | 🟡 P1 |
| 1.3.4 书签隐藏 | 临时隐藏不常用书签 | 🟢 P2 |
| 1.3.5 快捷访问编号 | 数字键 1-9 快速打开对应书签 | 🟢 P2 |
| 1.3.6 访问统计 | 记录书签点击次数和最近访问时间 | 🟢 P2 |
---
## 二、分组管理模块 📁
> 核心价值：按场景/类型组织书签，提升查找效率
### 2.1 分组基础操作
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 2.1.1 创建分组 | 新建分组并设置名称、图标 | 🔴 P0 |
| 2.1.2 编辑分组 | 修改分组名称、图标、描述 | 🔴 P0 |
| 2.1.3 删除分组 | 删除分组（书签移至默认分组或一并删除） | 🔴 P0 |
| 2.1.4 分组排序 | 拖拽调整分组显示顺序 | 🔴 P0 |
| 2.1.5 分组折叠 | 折叠/展开分组内容 | 🔴 P0 |
| 2.1.6 默认折叠状态 | 设置分组默认是否折叠 | 🟡 P1 |
### 2.2 分组属性配置
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 2.2.1 分组名称 | 显示名称，支持中英文 | 🔴 P0 |
| 2.2.2 分组图标 | 内置图标库选择或自定义 | 🔴 P0 |
| 2.2.3 分组描述 | 可选的分组说明文字 | 🟡 P1 |
| 2.2.4 分组颜色 | 分组标题栏的主题色 | 🟢 P2 |
| 2.2.5 显示模式 | 网格/列表/紧凑三种布局 | 🟢 P2 |
| 2.2.6 列数设置 | 分组内书签每行显示数量 | 🟡 P1 |
### 2.3 分组高级功能
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 2.3.1 分组可见性 | 设置分组仅特定用户可见 | 🟢 P2 |
| 2.3.2 分组标签页 | 多个分组作为 Tab 切换显示 | ⚪ P3 |
| 2.3.3 嵌套分组 | 支持分组内创建子分组 | ⚪ P3 |
| 2.3.4 分组独立页面 | 分组可作为独立页面访问 | ⚪ P3 |
---
## 三、搜索与筛选模块 🔍
> 核心价值：快速定位目标书签，提升使用效率
### 3.1 全局搜索
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 3.1.1 快捷键激活 | `Ctrl+K` 或 `/` 打开搜索框 | 🔴 P0 |
| 3.1.2 实时搜索 | 输入即搜索，无需回车 | 🔴 P0 |
| 3.1.3 多字段匹配 | 搜索名称、URL、描述、标签 | 🔴 P0 |
| 3.1.4 模糊搜索 | 支持拼音首字母、模糊匹配 | 🟡 P1 |
| 3.1.5 搜索高亮 | 匹配关键词高亮显示 | 🔴 P0 |
| 3.1.6 键盘导航 | ↑↓ 选择，Enter 打开，Esc 关闭 | 🔴 P0 |
### 3.2 筛选功能
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 3.2.1 按分组筛选 | 只显示特定分组的书签 | 🟡 P1 |
| 3.2.2 按标签筛选 | 根据标签过滤书签 | 🟡 P1 |
| 3.2.3 按访问频率 | 显示最常访问/最近访问的书签 | 🟢 P2 |
| 3.2.4 组合筛选 | 多条件组合筛选 | 🟢 P2 |
### 3.3 搜索增强
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 3.3.1 搜索历史 | 记录最近搜索词 | 🟢 P2 |
| 3.3.2 搜索建议 | 输入时显示匹配建议 | 🟢 P2 |
| 3.3.3 外部搜索引擎 | 未匹配时跳转到搜索引擎 | 🟡 P1 |
| 3.3.4 搜索引擎切换 | 支持 Google/Bing/百度 等 | 🟡 P1 |
---
## 四、主题与外观模块 🎨
> 核心价值：满足个性化需求，提升视觉体验
### 4.1 主题切换
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 4.1.1 预设主题 | 提供 10+ 预设主题（light/dark/nord/dracula等） | 🔴 P0 |
| 4.1.2 一键切换 | 点击即时切换，无需刷新 | 🔴 P0 |
| 4.1.3 跟随系统 | 自动跟随操作系统深色/浅色模式 | 🔴 P0 |
| 4.1.4 主题偏好保存 | 记住用户选择的主题 | 🔴 P0 |
| 4.1.5 定时切换 | 按时间段自动切换主题 | 🟢 P2 |
### 4.2 自定义外观
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 4.2.1 自定义背景 | 支持颜色/图片/渐变背景 | 🟡 P1 |
| 4.2.2 背景模糊 | 背景图片模糊度调节 | 🟡 P1 |
| 4.2.3 背景遮罩 | 背景透明度遮罩 | 🟡 P1 |
| 4.2.4 自定义 CSS | 高级用户可注入自定义样式 | 🟡 P1 |
| 4.2.5 字体设置 | 自定义字体和字号 | 🟢 P2 |
| 4.2.6 圆角设置 | 卡片圆角大小调节 | 🟢 P2 |
### 4.3 布局配置
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 4.3.1 布局模式 | 网格/列表/紧凑三种模式 | 🔴 P0 |
| 4.3.2 列数设置 | 每行显示 2/3/4/5/6 列可选 | 🔴 P0 |
| 4.3.3 卡片尺寸 | 小/中/大三种卡片尺寸 | 🟡 P1 |
| 4.3.4 显示密度 | 紧凑/标准/宽松间距 | 🟡 P1 |
| 4.3.5 响应式断点 | 参考 Tailwind 断点，移动端（<640px）单列 | 🔴 P0 |
---
## 五、配置管理模块 ⚙️
> 核心价值：灵活的配置方式，满足不同用户习惯
### 5.1 Web UI 配置（主要方式）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 5.1.1 可视化编辑器 | 通过界面修改所有配置项 | � P0 |
| 5.1.2 实时预览 | 修改后即时预览效果 | 🟡 P1 |
| 5.1.3 保存到数据库 | 所有配置保存到数据库 | � P0 |
| 5.1.4 配置分类 | 常规/外观/数据/账号 Tab 分类 | � P0 |
| 5.1.5 配置重置 | 恢复默认配置 | 🟡 P1 |
### 5.2 数据管理
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 5.2.1 数据导出 | 导出所有数据为 JSON/YAML | 🟡 P1 |
| 5.2.2 数据导入 | 从 JSON/YAML 导入数据 | 🟡 P1 |
| 5.2.3 数据备份 | 定时自动备份数据 | 🟢 P2 |
| 5.2.4 备份恢复 | 从备份文件恢复数据 | 🟢 P2 |
| 5.2.5 数据清空 | 清空所有数据（需二次确认） | 🟡 P1 |
| 5.2.6 竞品数据导入 | 支持从 Flame/Homer 导入数据 | ⚪ P3 |
---
## 六、图标系统模块 🖼️
> 核心价值：丰富的图标支持，提升视觉识别效率
### 6.1 内置图标库
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 6.1.1 基础图标集 | 内置 500+ 常用图标（基于 Lucide/Tabler） | 🔴 P0 |
| 6.1.2 品牌图标集 | 常见网站/服务的 Logo 图标 | 🟡 P1 |
| 6.1.3 图标搜索 | 在图标库中搜索图标 | 🔴 P0 |
| 6.1.4 图标预览 | 选择前预览图标效果 | 🔴 P0 |
| 6.1.5 最近使用 | 显示最近使用的图标 | 🟡 P1 |
### 6.2 自定义图标
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 6.2.1 URL 图标 | 支持外部图片 URL 作为图标 | 🔴 P0 |
| 6.2.2 URL 图标降级 | URL 不可访问时显示默认图标 | 🔴 P0 |
| 6.2.3 图标上传 | 上传本地图片作为图标 | 🟡 P1 |
| 6.2.4 Emoji 图标 | 支持使用 Emoji 作为图标 | 🟡 P1 |
| 6.2.5 文字图标 | 使用文字首字母作为图标 | 🔴 P0 |
| 6.2.6 SVG 图标 | 支持自定义 SVG 代码 | 🟢 P2 |
### 6.3 图标增强
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 6.3.1 图标颜色 | 自定义图标颜色 | 🟡 P1 |
| 6.3.2 图标大小 | 调整图标显示大小 | 🟡 P1 |
| 6.3.3 图标背景 | 图标背景色/形状设置 | 🟢 P2 |
| 6.3.4 Dashboard Icons | 集成 Dashboard Icons 图标集 | 🟢 P2 |
---
## 七、首页定制模块 🏠
> 核心价值：个性化首页展示，满足品牌和场景需求
### 7.1 页面头部
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 7.1.1 网站标题 | 自定义首页标题 | 🔴 P0 |
| 7.1.2 副标题 | 可选的副标题/欢迎语 | 🔴 P0 |
| 7.1.3 Logo 设置 | 自定义 Logo 图片 | 🟡 P1 |
| 7.1.4 Favicon 设置 | 自定义浏览器标签图标 | 🟡 P1 |
| 7.1.5 问候语 | 根据时间显示不同问候语 | 🟢 P2 |
| 7.1.6 头部隐藏 | 可选择隐藏头部区域 | 🟡 P1 |
### 7.2 页面布局
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 7.2.1 居中布局 | 内容区域居中显示 | 🔴 P0 |
| 7.2.2 最大宽度 | 设置内容区域最大宽度 | 🟡 P1 |
| 7.2.3 侧边栏模式 | 分组作为侧边栏导航 | 🟢 P2 |
| 7.2.4 全屏模式 | 隐藏所有 UI 只显示书签 | 🟢 P2 |
### 7.3 页面底部
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 7.3.1 版权信息 | 自定义底部版权文字 | 🟡 P1 |
| 7.3.2 快捷链接 | 底部显示常用链接 | 🟢 P2 |
| 7.3.3 底部隐藏 | 可选择隐藏底部区域 | 🟡 P1 |
| 7.3.4 页脚自定义 HTML | 高级用户可自定义页脚内容 | ⚪ P3 |
---
## 八、用户与权限模块 👥
> 核心价值：保护编辑权限，支持简单的访问控制
### 8.1 管理员登录（MVP）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 8.1.1 首次设置账号 | 首次启动强制设置管理员账号密码 | � P0 |
| 8.1.2 管理员登录 | 用户名密码登录 | � P0 |
| 8.1.3 Session 保持 | 登录状态保持，支持记住登录 | � P0 |
| 8.1.4 退出登录 | 退出管理员状态 | � P0 |
| 8.1.5 修改密码 | 管理员修改自己的密码 | � P0 |
### 8.2 访问控制（MVP）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 8.2.1 只读访问 | 未登录用户只能浏览，不能编辑 | 🔴 P0 |
| 8.2.2 编辑权限保护 | 添加/编辑/删除操作需要登录 | 🔴 P0 |
| 8.2.3 设置页面保护 | 设置页面需要登录才能访问 | 🔴 P0 |
### 8.3 多用户支持（v1.0+）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 8.3.1 用户注册 | 管理员邀请注册新用户 | 🟢 P2 |
| 8.3.2 用户列表 | 管理员查看所有用户 | 🟢 P2 |
| 8.3.3 用户编辑 | 修改用户信息和权限 | 🟢 P2 |
| 8.3.4 用户删除 | 删除用户账号 | � P2 |
| 8.3.5 角色权限 | 管理员/普通用户角色区分 | 🟢 P2 |
| 8.3.6 密码重置 | 管理员重置用户密码 | 🟢 P2 |
### 8.4 认证集成（未来）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 8.4.1 OAuth2 登录 | 支持 GitHub/Google OAuth | ⚪ P3 |
| 8.4.2 LDAP 集成 | 企业 LDAP/AD 认证 | ⚪ P3 |
| 8.4.3 SSO 支持 | 单点登录集成 | ⚪ P3 |
| 8.4.4 2FA 支持 | 两步验证（TOTP） | ⚪ P3 |
---
## 九、服务状态监控模块 📊
> 核心价值：简单了解服务可用性（非核心功能，保持轻量）
### 9.1 简单状态检测（v1.0）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 9.1.1 HTTP 状态检测 | 检测 URL 返回状态码 | 🟢 P2 |
| 9.1.2 状态图标显示 | 书签上显示红/绿状态点 | 🟢 P2 |
| 9.1.3 自定义检测间隔 | 设置检测频率 | 🟢 P2 |
### 9.2 状态展示
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 9.2.1 响应时间 | 显示服务响应延迟 | 🟢 P2 |
| 9.2.2 状态汇总 | 首页显示服务整体健康度 | 🟢 P2 |
| 9.2.3 故障提示 | 服务异常时醒目提示 | 🟢 P2 |
**说明**：
- 不保存历史数据
- 不生成报表
- 不支持告警通知
- 复杂监控需求可使用 Quarkus Dev UI 或专业工具
---
## 十、Widget 组件模块 🧩
> 核心价值：丰富信息展示（非核心差异化，延后实现）
### 10.1 内置 Widget（v1.0 简化版）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 10.1.1 时钟组件 | 显示当前时间/日期 | 🟢 P2 |
| 10.1.2 搜索框组件 | 独立的搜索引擎入口 | � P2 |
### 10.2 Widget 管理（v1.0）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 10.2.1 Widget 启用/禁用 | 选择显示哪些 Widget | 🟢 P2 |
| 10.2.2 Widget 位置 | 设置 Widget 显示位置 | 🟢 P2 |
### 10.3 扩展 Widget（v1.x+）
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 10.3.1 天气组件 | 显示当前天气信息 | ⚪ P3 |
| 10.3.2 快捷笔记 | 简单的便签/待办 | ⚪ P3 |
| 10.3.3 系统信息 | 显示服务器 CPU/内存/磁盘 | ⚪ P3 |
| 10.3.4 插件加载机制 | 基于 SPI 的插件加载 | ⚪ P3 |
| 10.3.5 插件开发 SDK | 提供 Widget 开发工具包 | ⚪ P3 |
| 10.3.6 插件市场 | 社区 Widget 分享平台 | ⚪ P3 |
**说明**：Widget 系统不是 Home4j 的核心差异化点，v1.0 仅提供简单的时钟和搜索组件，复杂 Widget 延后到 v1.x 作为可选插件。
---
## 十一、快捷操作模块 ⌨️
> 核心价值：键盘友好，提升操作效率
### 11.1 全局快捷键
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 11.1.1 搜索 | `Ctrl+K` 或 `/` 打开搜索 | 🔴 P0 |
| 11.1.2 添加书签 | `Ctrl+N` 打开添加弹窗 | 🟡 P1 |
| 11.1.3 设置 | `Ctrl+,` 打开设置 | 🟡 P1 |
| 11.1.4 主题切换 | `Ctrl+T` 切换深色/浅色 | 🟡 P1 |
| 11.1.5 帮助 | `?` 显示快捷键帮助 | 🟡 P1 |
| 11.1.6 全屏 | `F11` 切换全屏模式 | 🟢 P2 |
### 11.2 导航快捷键
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 11.2.1 数字键访问 | `1-9` 打开对应位置书签 | 🟢 P2 |
| 11.2.2 分组跳转 | `G+数字` 跳转到对应分组 | 🟢 P2 |
| 11.2.3 方向键导航 | 方向键在书签间移动 | 🟢 P2 |
| 11.2.4 Tab 导航 | Tab 键在元素间切换 | 🔴 P0 |
---
## 十二、部署与运维模块 🚀
> 核心价值：简化部署，降低运维成本
### 12.1 部署方式
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 12.1.1 Docker 部署 | 官方 Docker 镜像 | 🔴 P0 |
| 12.1.2 Docker Compose | 提供 compose 示例文件 | 🔴 P0 |
| 12.1.3 JAR 直接运行 | 单 JAR 文件直接运行 | 🔴 P0 |
| 12.1.4 Kubernetes | K8s 部署 YAML 和 Helm Chart | ⚪ P3 |
| 12.1.5 一键脚本 | Linux 一键安装脚本 | 🟡 P1 |
### 12.2 数据库支持
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 12.2.1 H2 数据库 | 默认嵌入式数据库，零配置 | 🔴 P0 |
| 12.2.2 MySQL 支持 | 可选切换到 MySQL | 🟡 P1 |
| 12.2.3 PostgreSQL | 可选切换到 PostgreSQL | 🟢 P2 |
| 12.2.4 SQLite | 可选切换到 SQLite | 🟢 P2 |
### 12.3 运维功能
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 12.3.1 健康检查端点 | `/health` 接口 | 🔴 P0 |
| 12.3.2 就绪检查端点 | `/ready` 接口 | 🟡 P1 |
| 12.3.3 Metrics 端点 | Prometheus 格式指标 | 🟢 P2 |
| 12.3.4 日志配置 | 日志级别动态调整 | 🟡 P1 |
| 12.3.5 版本信息 | `/info` 显示版本信息 | 🔴 P0 |
---
## 十三、API 接口模块 🔌
> 核心价值：支持自动化和二次开发
### 13.1 RESTful API
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 13.1.1 书签 CRUD API | 书签的增删改查接口 | 🟢 P2 |
| 13.1.2 分组 CRUD API | 分组的增删改查接口 | 🟢 P2 |
| 13.1.3 配置 API | 读取和修改配置接口 | 🟢 P2 |
| 13.1.4 导入导出 API | 数据导入导出接口 | 🟢 P2 |
| 13.1.5 API 文档 | Swagger/OpenAPI 文档 | 🟢 P2 |
### 13.2 API 安全
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 13.2.1 API Key 认证 | 使用 API Key 访问接口 | 🟢 P2 |
| 13.2.2 速率限制 | API 调用频率限制 | ⚪ P3 |
| 13.2.3 CORS 配置 | 跨域访问配置 | 🟢 P2 |
---
## 十四、国际化模块 🌍
> 核心价值：支持多语言，扩大用户群体
### 14.1 语言支持
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 14.1.1 中文（简体） | 默认语言 | 🔴 P0 |
| 14.1.2 英文 | 完整英文支持 | 🔴 P0 |
| 14.1.3 中文（繁体） | 繁体中文支持 | 🟢 P2 |
| 14.1.4 日文 | 日语支持 | ⚪ P3 |
| 14.1.5 社区翻译 | 支持社区贡献翻译 | ⚪ P3 |
### 14.2 语言切换
| 三级功能 | 描述 | 优先级 |
|---------|------|--------|
| 14.2.1 手动切换 | 设置中选择语言 | 🔴 P0 |
| 14.2.2 浏览器检测 | 自动检测浏览器语言 | 🟡 P1 |
| 14.2.3 语言偏好保存 | 记住用户语言选择 | 🔴 P0 |
---
## 功能统计汇总
| 版本 | P0 功能数 | P1 功能数 | P2 功能数 | P3 功能数 |
|-----|----------|----------|----------|----------|
| MVP (v0.1) | **50** | - | - | - |
| v0.5 | 50 | **35** | - | - |
| v1.0 | 50 | 35 | **35** | - |
| v1.x+ | 50 | 35 | 35 | **25** |
**总计**：约 145 个功能点
---
## 版本交付物清单
### MVP (v0.1) 交付物
- [ ] 完整的书签管理功能
- [ ] 分组管理功能
- [ ] 全局搜索功能
- [ ] 5+ 预设主题（DaisyUI 本地化）
- [ ] 管理员登录与权限保护
- [ ] Web UI 配置管理
- [ ] Docker 镜像发布
- [ ] 基础文档（README、快速开始）
### v0.5 交付物
- [ ] 数据导入导出
- [ ] 图标库增强
- [ ] 自定义背景
- [ ] 快捷键系统
- [ ] MySQL 支持
- [ ] 完整使用文档
### v1.0 交付物
- [ ] 多用户支持
- [ ] 简单服务状态监控
- [ ] RESTful API
- [ ] 基础 Widget（时钟、搜索）
- [ ] 访问统计
- [ ] API 文档
- [ ] 运维监控接口
---
> **文档结束**
> 本功能列表将随项目进展持续更新
doc/数据库设计.md
+527
View File
@@ -0,0 +1,527 @@
# 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` | 书签标签关联 | - | ✅ | ✅ |
---
> **文档结束**
> 本设计将随项目进展持续更新
doc/文档.md
+594
View File
@@ -0,0 +1,594 @@
# Home4j 产品设计文档（PDD）
> **文档版本**：v1.1
> **创建日期**：2026年1月30日
> **最后更新**：2026年2月3日
> **文档状态**：修订版
---
## 1. 概述与愿景
### 1.1 项目一句话介绍
**Home4j** 是一款基于 Java 技术栈的极简、高性能、可自托管的 Home 仪表盘和导航工具，专为独立开发者、内容创作者和小型团队打造。
### 1.2 核心价值主张
> 市面上鲜有基于 Java 的 Home 仪表盘解决方案。Home4j 填补这一空白，为 Java 生态用户提供**轻量级、高度可定制、开箱即用**的首页导航工具，让用户在熟悉的技术栈中获得一流的自托管体验。
### 1.3 与竞品的差异化定位
| 差异化维度 | Home4j 定位 |
|-----------|------------|
| **技术栈** | 基于 **Quarkus** 的轻量级 Java 方案，对 Java 开发者友好 |
| **配置方式** | **Web UI 为主**，数据库存储配置，支持导出备份 |
| **资源占用** | 目标内存 < 128MB，启动时间 < 3秒（JVM 模式） |
| **扩展性** | 预留 Widget 插件机制，支持企业级二次开发 |
| **部署体验** | 单 JAR 文件 / Docker 一键部署，零外部依赖 |
| **离线友好** | 所有资源本地化（图标、CSS），支持内网离线部署 |
### 1.4 从参考项目中学到的最关键启发
| 参考项目 | 核心启发 | 应用到 Home4j |
|---------|---------|--------------|
| **Flame** | 极简至上，专注核心功能；书签+应用分类清晰 | 采用相似的简洁 UI 哲学，MVP 聚焦书签管理 |
| **Homer** | YAML 配置驱动，声明式管理；图标系统完善 | 支持 YAML 配置文件，内置图标库 |
| **Glance** | Widget 化设计，信息聚合能力强 | 预留 Widget 扩展架构 |
| **Homepage** | 服务状态监控集成，实用性强 | v1.0 加入服务健康检查 |
| **Dashy** | 高度可定制，主题丰富 | 基于 DaisyUI 实现多主题切换 |
| **Heimdall** | 应用启动器思维，增强型书签概念 | 支持应用分组和快捷访问 |
---
## 2. 用户与市场分析
### 2.1 目标用户画像
#### Persona 1：独立开发者「小明」
| 属性 | 描述 |
|-----|------|
| **背景** | 全栈开发者，自建 NAS 和多个服务（GitLab、Jenkins、Portainer等） |
| **典型场景** | 需要统一入口管理 10+ 个自托管服务，希望一目了然 |
| **痛点** | 现有工具要么太重（Dashy），要么不熟悉技术栈（Node.js） |
| **期望** | 轻量、快速、能用 Java 二次开发、Docker 部署简单 |
#### Persona 2：小型团队技术负责人「阿杰」
| 属性 | 描述 |
|-----|------|
| **背景** | 5人创业团队 CTO，管理内部工具和文档入口 |
| **典型场景** | 为团队搭建内部 Portal，整合 Notion、飞书、内部系统 |
| **痛点** | 需要简单的权限控制，但不想引入复杂系统 |
| **期望** | 支持多用户、可配置访问权限、界面专业美观 |
#### Persona 3：内容创作者「小美」
| 属性 | 描述 |
|-----|------|
| **背景** | 技术博主，自建博客、图床、评论系统等 |
| **典型场景** | 希望有一个美观的个人主页展示所有项目入口 |
| **痛点** | 设计能力有限，希望开箱即用且美观 |
| **期望** | 多主题可选、支持自定义背景、移动端适配好 |
### 2.2 竞品分析
| 维度 | Flame | Homer | Dashy | Heimdall | **Home4j** |
|-----|-------|-------|-------|----------|------------|
| **技术栈** | Node.js | Vue/静态 | Vue | PHP/Laravel | **Java/Solon** |
| **配置方式** | Web UI | YAML | YAML + UI | Web UI | **YAML + Web UI** |
| **资源占用** | 低 | 极低 | 中等 | 中等 | **低** |
| **学习曲线** | 低 | 中 | 高 | 低 | **低** |
| **Widget 支持** | 有限 | 无 | 丰富 | 无 | **可扩展** |
| **服务状态监控** | ✅ | ❌ | ✅ | ❌ | **✅ (v1.0)** |
| **多用户** | ❌ | ❌ | ✅ | ❌ | **✅ (v1.0)** |
| **中文支持** | 一般 | 一般 | 良好 | 一般 | **原生支持** |
### 2.3 用户核心痛点与机会点
| 痛点 | 机会点 |
|-----|-------|
| Java 生态缺乏优质 Dashboard 工具 | 填补市场空白，吸引 Java 开发者群体 |
| 现有工具配置复杂或资源占用高 | 主打"极简 + 轻量"差异化 |
| 纯 YAML 配置对非技术用户不友好 | 提供 Web UI 可视化配置 |
| 大多数工具不支持中文优先 | 原生中文支持，国际化架构 |
| 企业内部使用缺乏基础权限控制 | 提供简单实用的多用户机制 |
---
## 3. 核心功能设计（MVP）
### 3.1 MVP 范围界定说明
MVP 目标：**让用户在 5 分钟内完成部署，10 分钟内配置出可用的个人导航页**。
**MVP 边界原则**：
- ✅ 必须有：书签管理、分组分类、主题切换、Docker 部署、管理员登录
- ⏳ 延后：Widget 系统、服务监控、多用户权限
- ❌ 不做：复杂的仪表盘编辑器、第三方集成、竞品数据导入
**MVP 权限模式**：
- **只读访问**：普通访客可浏览所有书签
- **管理员编辑**：需登录后才能添加/编辑/删除书签和配置
### 3.2 核心功能列表
| 功能名称 | 用户价值 | 优先级 | 参考来源 |
|---------|---------|--------|---------|
| **书签管理** | 快速访问常用服务和网站 | P0 | Flame, Homer |
| **分组分类** | 按场景/类型组织书签，提升查找效率 | P0 | Flame, Heimdall |
| **搜索功能** | 快速定位目标书签 | P0 | Dashy |
| **主题切换** | 满足个性化需求，适应不同场景 | P0 | Dashy |
| **管理员登录** | 保护编辑权限，防止误操作 | P0 | 通用需求 |
| **Web UI 配置** | 可视化管理所有设置 | P0 | Flame |
| **响应式布局** | 多设备访问体验一致 | P0 | 通用需求 |
| **图标系统** | 提升视觉识别效率（本地化） | P0 | Homer, Dashy |
| **Docker 部署** | 一键启动，环境隔离 | P0 | 所有参考项目 |
### 3.3 核心功能详细描述
#### 3.3.1 书签管理
**用户故事**：
> 作为一名独立开发者，我希望能够添加、编辑、删除我的服务书签，以便快速访问我的各种自托管服务。
**关键交互流程**：
```
[首页] → [点击添加按钮] → [填写书签信息表单]
→ [选择分组和图标] → [保存] → [首页显示新书签]
```
**书签数据结构**：
```yaml
bookmarks:
- name: "GitLab"
url: "https://gitlab.example.com"
icon: "gitlab" # 支持：内置图标名 / URL / base64
group: "开发工具"
description: "代码仓库"
tags: ["开发", "Git"]
```
**验收标准**：
- [ ] 支持添加书签（名称、URL、图标、分组、描述）
- [ ] 支持编辑和删除书签
- [ ] 书签点击在新标签页打开
- [ ] 支持拖拽排序
- [ ] 数据持久化到数据库
#### 3.3.2 分组分类
**用户故事**：
> 作为用户，我希望将书签按照用途分组（如：开发工具、监控系统、文档资料），以便快速找到目标。
**分组数据结构**：
```yaml
groups:
- name: "开发工具"
icon: "code"
order: 1
collapsed: false # 是否默认折叠
- name: "监控系统"
icon: "monitor"
order: 2
```
**验收标准**：
- [ ] 支持创建、编辑、删除分组
- [ ] 支持分组排序
- [ ] 支持分组折叠/展开
- [ ] 未分组书签显示在"默认"分组
#### 3.3.3 搜索功能
**用户故事**：
> 当我有大量书签时，我希望通过关键词快速搜索定位，而不是逐个查找。
**交互设计**：
- 快捷键 `/` 或 `Ctrl+K` 激活搜索框
- 支持搜索：书签名称、URL、描述、标签
- 实时过滤，高亮匹配内容
- 支持键盘导航（↑↓选择，Enter打开）
**验收标准**：
- [ ] 搜索响应时间 < 100ms
- [ ] 支持模糊匹配
- [ ] 搜索结果高亮显示
- [ ] 空结果友好提示
#### 3.3.4 主题切换
**用户故事**：
> 我希望根据个人喜好和使用场景切换界面主题，比如夜间使用深色模式。
**主题方案（基于 DaisyUI）**：
| 主题名称 | 适用场景 |
|---------|---------|
| light | 日间默认 |
| dark | 夜间模式 |
| cyberpunk | 科技风格 |
| nord | 护眼柔和 |
| dracula | 开发者偏好 |
**验收标准**：
- [ ] 支持至少 5 个预设主题
- [ ] 主题切换即时生效，无刷新
- [ ] 记住用户主题偏好
- [ ] 支持跟随系统深色模式
#### 3.3.5 数据存储策略
**设计理念**：
- **所有数据统一存储在数据库**：书签、分组、应用配置、用户偏好
- **Web UI 为主要配置入口**：用户通过界面管理所有设置
- **支持数据导出**：可导出为 JSON/YAML 格式用于备份和迁移
**数据分类**：
| 数据类型 | 存储位置 | 说明 |
|---------|---------|------|
| 书签数据 | 数据库 | 书签、分组的增删改查 |
| 应用配置 | 数据库 | 标题、副标题、主题、布局等全局设置 |
| 用户账号 | 数据库 | 管理员账号信息 |
| 用户偏好 | 数据库 + LocalStorage | 主题选择、语言偏好（支持游客记忆） |
**配置页面功能**：
- 常规设置：网站标题、副标题、Logo
- 外观设置：主题、布局、背景
- 数据管理：导入、导出、备份
- 账号管理：修改密码
---
#### 3.3.6 管理员登录
**用户故事**：
> 作为网站管理员，我希望通过登录验证后才能编辑内容，防止他人误操作或恶意修改。
**交互流程**：
```
[首页] → [点击设置/编辑按钮] → [跳转登录页]
→ [输入用户名密码] → [登录成功] → [进入管理模式]
```
**首次启动流程**：
```
[首次访问] → [初始化向导] → [设置管理员账号密码] → [完成] → [进入首页]
```
**验收标准**：
- [ ] 首次启动强制设置管理员账号
- [ ] 未登录用户只能浏览，不能编辑
- [ ] 登录状态支持 Session 保持
- [ ] 支持退出登录
- [ ] 支持修改密码
---
## 4. 功能路线图（MVP → v1.0 → 未来方向）
### 4.1 分阶段功能规划
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MVP (v0.1) v0.5 v1.0 未来
2个月 2个月 2个月 持续
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[书签管理] [图标库增强] [简单状态监控] [插件市场]
[分组分类] [数据导入导出] [多用户支持] [移动端APP]
[搜索功能] [自定义CSS] [访问统计] [团队协作]
[主题切换] [背景自定义] [API开放] [AI推荐]
[管理员登录] [快捷键系统] [基础Widget] [公开分享]
[Web UI配置] [PWA支持] [数据备份恢复]
[Docker部署]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### 4.2 关键里程碑
| 版本 | 时间节点 | 关键目标 | 成功指标 |
|-----|---------|---------|---------|
| **MVP (v0.1)** | M+2 | 核心功能可用，Docker 可部署 | 完成冒烟测试，GitHub 发布首个 Release |
| **v0.5** | M+4 | 体验优化，功能完善 | 收集 50+ 用户反馈，GitHub Star > 100 |
| **v1.0** | M+6 | 生产可用，企业特性 | 稳定运行 30 天无重大 Bug，Star > 500 |
---
## 5. 用户体验与交互设计原则
### 5.1 整体设计语言与调性
| 维度 | 设计原则 |
|-----|---------|
| **视觉风格** | 简洁克制、呼吸感强、信息层次清晰 |
| **交互理念** | 减少点击、键盘友好、即时反馈 |
| **色彩运用** | 主色调由主题决定，强调色用于交互元素 |
| **动效策略** | 轻量过渡动画，提升流畅感但不干扰 |
| **信息密度** | 可配置，支持紧凑/标准/宽松三种模式 |
### 5.2 核心用户旅程
#### 首次使用旅程
```
┌─────────────────────────────────────────────────────────────┐
│ 1. 部署启动 │
│ docker run -p 8080:8080 home4j/home4j │
│ ↓ │
│ 2. 访问首页 │
│ 浏览器打开 http://localhost:8080 │
│ ↓ │
│ 3. 初始化向导（首次，可跳过部分步骤） │
│ [设置管理员账号] → [选择主题] → [添加第一个书签] → [完成] │
│ ↓ │
│ 4. 日常使用 │
│ 游客：查看书签 → 点击访问 / 搜索定位 │
│ 管理员：登录 → 管理编辑 → 退出登录 │
└─────────────────────────────────────────────────────────────┘
```
**说明**：初始化向导由前端驱动，除「设置管理员账号」为必填外，其他步骤可跳过。
### 5.3 关键页面交互逻辑
#### 首页（Dashboard）
```
┌────────────────────────────────────────────────────────────┐
│ 🏠 Home4j [搜索框 Ctrl+K] [设置⚙️] │
├────────────────────────────────────────────────────────────┤
│ │
│ 📁 开发工具 [+] │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │GitHub│ │GitLab│ │Jenkins│ │Notion│ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ 📁 监控系统 [+] │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Grafana│ │Portainer│ │Uptime│ │
│ └──────┘ └──────┘ └──────┘ │
│ │
├────────────────────────────────────────────────────────────┤
│ Powered by Home4j [主题切换🌙] │
└────────────────────────────────────────────────────────────┘
```
#### 设置页面（Settings）
- **Tab 式导航**：常规 | 外观 | 数据 | 关于
- **实时预览**：修改即可看到效果
- **导入导出**：支持 JSON/YAML 格式
---
## 6. 技术架构与实现约束（产品视角）
### 6.1 推荐技术栈
| 层级 | 技术选型 | 选型理由 |
|-----|---------|---------|
| **后端框架** | Quarkus | 轻量级 Java 框架，启动快、内存占用低，生态完善 |
| **模板引擎** | Qute | Quarkus 原生模板引擎，类型安全，性能优秀 |
| **前端样式** | DaisyUI + Tailwind（本地） | 开箱即用的组件库，主题切换方便，**本地引用无 CDN 依赖** |
| **数据库** | H2（默认，文件模式）/ MySQL（可选） | H2 零配置，MySQL 满足企业需求 |
| **ORM** | Panache（Hibernate） | Quarkus 原生 ORM，简化数据库操作 |
| **容器化** | Docker | 标准化部署，环境一致性 |
### 6.2 部署方式
#### Docker 一键部署（推荐）
```bash
docker run -d \
--name home4j \
-p 8080:8080 \
-v /path/to/data:/app/data \
home4j/home4j:latest
```
#### Docker Compose
```yaml
version: '3'
services:
home4j:
image: home4j/home4j:latest
ports:
- "8080:8080"
volumes:
- ./data:/app/data
environment:
- TZ=Asia/Shanghai
restart: unless-stopped
```
#### JAR 直接运行
```bash
java -jar home4j-runner.jar
```
### 6.3 数据目录规划
```
/app/ # 应用根目录（Docker 内）
├── home4j-runner.jar # 应用主程序
├── resources/ # 资源目录
│ ├── static/ # 静态资源
│ │ ├── css/ # DaisyUI/Tailwind 本地文件
│ │ ├── js/ # JavaScript 文件
│ │ └── icons/ # 内置图标库
│ └── templates/ # Qute 模板文件
├── data/ # 数据目录（**需挂载**）
│ ├── home4j.mv.db # H2 数据库文件
│ ├── home4j.trace.db # H2 跟踪文件（可选）
│ └── uploads/ # 用户上传文件
│ └── icons/ # 用户上传的自定义图标
└── logs/ # 日志目录（可选挂载）
└── home4j.log
```
**挂载说明**：
- `/app/data` **必须挂载**：包含数据库和用户上传文件，确保数据持久化
- `/app/logs` 可选挂载：便于查看日志
### 6.4 图标系统实现
| 图标类型 | 存储位置 | 说明 |
|---------|---------|------|
| **内置图标** | `/resources/static/icons/` | 打包在 JAR 中，500+ 常用图标 |
| **URL 图标** | 外部 URL | 用户填写的图片 URL |
| **上传图标** | `/data/uploads/icons/` | 用户上传的自定义图标 |
| **默认图标** | `/resources/static/icons/default.svg` | URL 不可访问时的降级显示 |
**URL 图标处理逻辑**：
1. 前端尝试加载用户填写的 URL 图标
2. 如果加载失败（超时/404/跨域），自动降级显示默认图标
3. 默认图标为一个灰色的「问号」或「链接断裂」样式
### 6.5 扩展性与插件机制
**Widget 插件架构（v1.0+）**：
```
┌─────────────────────────────────────────┐
│ Home4j Core │
├─────────────────────────────────────────┤
│ Widget API (SPI) │
├──────────┬──────────┬──────────┬────────┤
│ 时钟组件 │ 搜索组件 │ 待办组件 │ 自定义 │
└──────────┴──────────┴──────────┴────────┘
```
- 基于 Quarkus 扩展机制或 Java SPI 加载插件
- 插件独立 JAR 包，放入 `/plugins` 目录自动加载
- v1.0 提供简单的内置 Widget，复杂插件延后到 v1.x
### 6.6 性能与安全底线要求
| 指标 | 目标值 |
|-----|-------|
| 冷启动时间 | < 3 秒（JVM 模式） |
| 内存占用 | < 128 MB（默认配置） |
| 首页加载时间 | < 500 ms |
| 并发支持 | > 100 QPS（单实例） |
| Docker 镜像大小 | < 200 MB |
---
## 7. 非功能性需求
### 7.1 性能目标
| 场景 | 指标 | 目标 |
|-----|-----|------|
| 首页渲染 | TTFB | < 100ms |
| 书签搜索 | 响应时间 | < 50ms（1000条书签内） |
| 配置保存 | 响应时间 | < 200ms |
| 主题切换 | 生效时间 | < 100ms，无闪烁 |
### 7.2 安全性与隐私保护
| 安全措施 | 说明 |
|---------|------|
| **数据本地化** | 所有数据存储在用户自己的服务器，不上传云端 |
| **HTTPS 支持** | 支持反向代理 SSL 终结 |
| **XSS 防护** | 输入输出转义，CSP 策略 |
| **CSRF 防护** | Token 验证机制 |
| **认证机制（v1.0）** | 支持基础认证，可选 OAuth2 |
### 7.3 可观测性
| 维度 | 实现方案 |
|-----|---------|
| **日志** | SLF4J + Logback，支持日志级别动态调整 |
| **健康检查** | `/actuator/health` 端点 |
| **指标暴露** | Prometheus 格式 `/metrics`（可选） |
### 7.4 国际化与可访问性
- **语言支持**：中文（默认）、英文
- **i18n 机制**：基于 `messages.properties` 资源文件
- **可访问性**：
- 语义化 HTML 结构
- 键盘完整可操作
- 支持屏幕阅读器
- 颜色对比度符合 WCAG 2.1 AA
---
## 8. 风险、挑战与应对
| 风险 | 等级 | 描述 | 缓解措施 |
|-----|------|------|---------|
| **市场认知度低** | 高 | Java Dashboard 类工具用户认知少 | 1. 发布技术博客分享<br>2. 提交到 awesome-selfhosted 列表<br>3. 录制视频教程 |
| **与成熟竞品竞争** | 高 | Flame/Homer 已有稳定用户群 | 1. 差异化定位 Java 用户<br>2. 功能上做精不做多<br>3. 强调离线部署优势 |
| **Quarkus 学习曲线** | 中 | 团队对 Quarkus 熟悉度 | 1. 使用 JVM 模式降低复杂度<br>2. 参考官方示例<br>3. 保持核心依赖简单 |
| **单人维护精力有限** | 中 | 开源项目持续维护挑战 | 1. MVP 功能精简<br>2. 代码质量优先<br>3. 积极培养社区贡献者 |
| **用户需求分散** | 中 | 不同用户对功能期望差异大 | 1. 坚持「导航工具」核心定位<br>2. 通过插件满足扩展需求<br>3. 建立 RFC 机制收集反馈 |
---
## 9. 附录
### 9.1 名词表 / 术语定义
| 术语 | 定义 |
|-----|------|
| **书签（Bookmark）** | 用户添加的链接条目，包含名称、URL、图标等属性 |
| **分组（Group）** | 书签的逻辑分类容器 |
| **Widget** | 可嵌入仪表盘的小组件，如时钟、天气等 |
| **主题（Theme）** | 预定义的视觉风格配置，包含颜色、字体等 |
| **YAML 配置** | 使用 YAML 格式定义应用配置的文件 |
### 9.2 参考资料与灵感来源
| 项目 | 地址 | 主要参考点 |
|-----|------|-----------|
| Flame | https://github.com/pawelmalak/flame | 极简设计、书签管理 |
| Homer | https://github.com/bastienwirtz/homer | YAML 配置、图标系统 |
| Glance | https://github.com/glanceapp/glance | Widget 架构 |
| Homepage | https://github.com/gethomepage/homepage | 服务状态集成 |
| Dashy | https://github.com/Lissy93/dashy | 主题系统、高级功能 |
| Heimdall | https://github.com/linuxserver/Heimdall | 应用启动器概念 |
### 9.3 其他补充说明
#### 项目目录结构（建议）
```
home4j/
├── src/
│ ├── main/
│ │ ├── java/com/home4j/
│ │ │ ├── resource/ # REST 资源（Controller）
│ │ │ ├── service/ # 业务逻辑
│ │ │ ├── repository/ # 数据访问（Panache）
│ │ │ ├── entity/ # 数据实体
│ │ │ ├── dto/ # 数据传输对象
│ │ │ ├── config/ # 配置类
│ │ │ └── plugin/ # 插件机制
│ │ ├── resources/
│ │ │ ├── templates/ # Qute 模板
│ │ │ ├── META-INF/
│ │ │ │ └── resources/ # 静态资源
│ │ │ │ ├── css/ # DaisyUI/Tailwind 本地文件
│ │ │ │ ├── js/ # JavaScript 文件
│ │ │ │ └── icons/ # 内置图标库
│ │ │ └── application.properties
├── docker/
│ └── Dockerfile
├── docs/ # 文档
└── README.md
```
#### 开源协议建议
推荐使用 **MIT License**，便于企业用户采用和二次开发。
---
> **文档结束**
> 本文档将随项目进展持续更新，欢迎提出反馈和建议。