# 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**，便于企业用户采用和二次开发。

---

> **文档结束**  
> 本文档将随项目进展持续更新，欢迎提出反馈和建议。