Files

T

labmem 86182ce5d7 docs(ts): 新增 Polaris 个人导航站说明文档与设计图

- 新增 Polaris 个人导航站项目说明文档，涵盖项目定位、视觉风格、
  首页布局、搜索方案、技术选型、数据结构与分阶段开发规划
- 新增 Polaris 首页页面设计图

2026-08-20 23:23:53 +08:00

23 KiB

Raw Blame History

Polaris 个人导航站项目说明文档

1. 项目名称

Polaris

Polaris 原意为“北极星”，具有方向、导航、定位、指引的含义。该名称与个人导航站的产品定位非常契合。

本项目的核心目标是打造一个轻量、安静、高效、可长期维护的个人导航站，用于集中管理和访问常用网站、分类资源与个人入口。

2. 项目定位

Polaris 不是后台管理系统，也不是信息密集型 Dashboard。

它的定位是：

一个具有个人审美、可自定义背景、可快速搜索和访问常用链接的浏览器起始页。

页面应给人的感觉是：

私人入口
浏览器首页
轻量工具启动页
个人网址导航
安静、高效、有氛围感

而不是：

后台系统
资源管理平台
复杂书签管理器
信息看板
数据仪表盘

3. 项目目标

Polaris 第一阶段目标：

提供一个美观的个人导航首页；
支持快速访问常用链接；
支持左侧分类导航；
支持搜索框；
支持当前时间与日期展示；
支持左侧边栏折叠；
支持背景图更换的设计预留；
数据第一版写死在本地 JSON 或 TS 配置中；
代码结构预留未来接入 Go 后端接口的能力。

后续阶段目标：

从 Go 后端 API 获取链接、分类、设置等数据；
使用数据库持久化配置；
支持后台或隐藏入口管理链接；
支持用户自定义背景；
支持主题色、深色模式、导入导出等个性化能力。

4. 当前方案是否为静态页面

当前方案不是传统意义上的纯静态页面。

更准确地说：

第一版可以静态部署，但产品形态是动态可配置的个人导航站。

第一版数据可以写死在本地配置文件中，例如：

links.json
categories.json
settings.json

但页面本身具有动态交互：

当前时间实时更新
搜索框交互
搜索引擎切换
本地链接搜索
侧边栏折叠
导航选中状态
背景样式预留
快捷键操作

后续可以将本地 JSON 数据源替换为 Go 后端 API，不需要推翻前端整体结构。

5. 整体视觉风格

Polaris 推荐采用：

轻量玻璃感 + 极简浏览器起始页 + 柔和个人空间感

设计关键词：

极简
半透明
玻璃感
柔和阴影
大留白
低饱和
可换背景
个人化
安静
高级感

整体视觉应避免过重的管理系统风格。

首页不应常驻展示以下元素：

设置按钮
编辑按钮
管理按钮
新增按钮
统计数据
用户头像
访问次数
站点域名副标题
复杂分类卡片

这些能力可以在后续阶段通过隐藏入口、独立配置页或快捷键面板实现。

6. 首页整体布局

首页采用左右结构：

┌──────────────────┬────────────────────────────────────────────┐
│ 左侧边栏          │ 主内容区域                                  │
│                  │                                            │
│ Logo + 折叠按钮   │ 问候语 + 当前时间                            │
│ 首页              │ 日期 / 星期                                  │
│ AI 工具           │ 搜索框                                      │
│ 开发工具          │ 常用链接                                    │
│ 设计资源          │                                            │
│ 学习资料          │                                            │
│ 效率工具          │                                            │
│ 娱乐媒体          │                                            │
│ 生活服务          │                                            │
└──────────────────┴────────────────────────────────────────────┘

布局原则：

左侧边栏负责分类导航；
主内容区域只展示最高频内容；
首页不展示分类卡片；
首页不展示编辑、设置、管理类按钮；
常用链接只做轻量展示。

7. 左侧边栏设计

7.1 边栏内容

左侧边栏从上到下依次展示：

Logo
折叠按钮
首页
AI 工具
开发工具
设计资源
学习资料
效率工具
娱乐媒体
生活服务

暂时不展示：

设置
关于
编辑
管理
新增分类
账户信息

7.2 折叠按钮位置

折叠按钮放在侧边栏顶部右侧，与 Logo 位于同一行。

示意：

┌──────────────────────┐
│ Logo            ≪    │
└──────────────────────┘

不采用侧边栏中间悬浮按钮。

原因：

中间悬浮按钮视觉上突兀；
容易产生后台管理系统的感觉；
会破坏页面边界的干净感；
顶部右侧更符合用户对全局控制按钮的认知。

7.3 边栏宽度

展开状态：

推荐宽度：240px
可选范围：220px - 260px

折叠状态：

推荐宽度：72px
可选范围：68px - 80px

展开时显示图标和文字。

折叠时只显示图标。

7.4 边栏视觉样式

推荐样式：

background: rgba(255, 255, 255, 0.68);
backdrop-filter: blur(24px);
border: 1px solid rgba(255, 255, 255, 0.45);
box-shadow: 0 24px 80px rgba(15, 23, 42, 0.10);
border-radius: 24px;

边栏与页面边缘保持一定距离，形成悬浮玻璃面板感。

推荐边距：

left: 20px;
top: 20px;
bottom: 20px;

8. 主内容区域设计

主内容区域展示：

问候语
当前时间
当前日期
搜索框
常用链接

不展示：

分类卡片
设置入口
编辑入口
管理入口
统计信息
复杂小组件

主内容整体居中，视觉重心位于页面中上方。

推荐信息层级：

1. 当前时间 / 问候语
2. 搜索框
3. 常用链接
4. 左侧分类导航
5. 背景氛围

9. 时间与问候语

首页顶部展示问候语和当前时间。

示例：

晚上好，21:56
2026 年 8 月 20 日 星期四

问候语规则：

05:00 - 11:59  早上好
12:00 - 13:59  中午好
14:00 - 17:59  下午好
18:00 - 23:59  晚上好
00:00 - 04:59  夜深了

推荐样式：

font-size: 56px;
font-weight: 700;
color: #0F172A;

日期样式：

font-size: 16px;
color: #64748B;

10. 搜索框设计

10.1 搜索框定位

搜索框是 Polaris 首页最核心的交互组件。

搜索框位于时间与日期下方，居中展示。

10.2 搜索范围

Polaris 第一版搜索框仅支持以下四种搜索方式：

Google 搜索
Bing 搜索
GitHub 搜索
本地搜索

其中：

Google 搜索：使用 Google 搜索引擎搜索输入内容；
Bing 搜索：使用 Bing 搜索引擎搜索输入内容；
GitHub 搜索：在 GitHub 中搜索输入内容；
本地搜索：搜索 Polaris 本地配置中的链接、分类和名称。

第一版不支持：

直接输入 URL 跳转
自定义搜索引擎
多搜索引擎聚合结果
AI 搜索
站外爬取搜索
全文索引搜索

这些能力可以作为后续扩展。

10.3 搜索框尺寸

桌面端推荐：

width: 760px;
height: 68px;

可选范围：

宽度：720px - 860px
高度：64px - 72px

移动端：

width: calc(100vw - 32px);
height: 60px;

10.4 搜索框视觉样式

推荐样式：

background: rgba(255, 255, 255, 0.72);
backdrop-filter: blur(22px);
border: 1px solid rgba(255, 255, 255, 0.65);
border-radius: 24px;
box-shadow: 0 20px 60px rgba(15, 23, 42, 0.12);

placeholder 示例：

搜索网站、书签或关键词...

右侧可以展示快捷键提示：

⌘K

Windows / Linux 环境下可展示：

Ctrl K

10.5 搜索模式切换

搜索模式可以通过以下方式切换：

搜索框左侧下拉选择
快捷键切换
命令面板中选择
默认使用上一次选择的搜索方式

推荐第一版采用简单方案：

搜索框左侧或右侧提供当前搜索模式标识
点击后可切换 Google / Bing / GitHub / 本地

也可以先默认使用 Google，后续再增加模式切换。

10.6 本地搜索范围

本地搜索的数据来自本地配置文件。

搜索范围包括：

链接标题
链接关键词
链接描述
分类名称
分类 ID

建议链接数据中预留 keywords 字段。

示例：

{
  "id": "github",
  "title": "GitHub",
  "url": "https://github.com",
  "categoryId": "dev",
  "icon": "github",
  "pinned": true,
  "keywords": ["代码", "仓库", "开源", "git"],
  "sort": 10
}

11. 常用链接区域

11.1 区域定位

常用链接用于展示用户最高频访问的网站。

首页不展示分类卡片，以保持页面干净。

推荐第一版展示 8 个常用链接：

GitHub
ChatGPT
Gmail
Notion
Figma
YouTube
Vercel
Bilibili

实际项目中可以根据个人习惯调整。

11.2 链接卡片内容

常用链接卡片只展示：

图标
名称

不展示：

域名
描述
编辑按钮
更多按钮
拖拽按钮
访问统计

11.3 链接卡片样式

推荐样式：

background: rgba(255, 255, 255, 0.62);
backdrop-filter: blur(20px);
border: 1px solid rgba(255, 255, 255, 0.56);
border-radius: 20px;
box-shadow: 0 14px 40px rgba(15, 23, 42, 0.10);

推荐尺寸：

width: 200px;
height: 76px;

推荐布局：

两行四列

示意：

┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ GitHub │ │ChatGPT │ │ Gmail  │ │ Notion │
└────────┘ └────────┘ └────────┘ └────────┘

┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Figma  │ │YouTube │ │ Vercel │ │Bilibili│
└────────┘ └────────┘ └────────┘ └────────┘

Hover 效果：

transform: translateY(-2px);
background: rgba(255, 255, 255, 0.78);
box-shadow: 0 18px 50px rgba(15, 23, 42, 0.14);
transition: all 180ms ease;

12. 背景设计

12.1 背景类型

Polaris 支持背景自定义的设计预留。

第一版可以先使用默认背景图。

后续支持：

静态图片背景
渐变背景
纯色背景
本地上传背景
远程图片背景
深色背景

默认背景建议：

湖面
雪山
晨雾
天空
抽象渐变
低对比度风景图

12.2 背景遮罩

由于用户未来可能更换任意背景，因此需要增加背景遮罩层，保证内容可读。

浅色主题：

background-overlay: rgba(255, 255, 255, 0.32);
backdrop-filter: blur(8px);

深色主题：

background-overlay: rgba(15, 23, 42, 0.42);
backdrop-filter: blur(8px);

13. 配色系统

默认采用浅色玻璃主题。

14. 字体建议

推荐字体栈：

font-family:
  Inter,
  "SF Pro Display",
  "SF Pro Text",
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  "PingFang SC",
  "Hiragino Sans GB",
  "Microsoft YaHei",
  sans-serif;

字体原则：

标题清晰
正文轻盈
导航可读
不要使用过度装饰性字体

15. 技术选型

15.1 前端技术栈

推荐前端技术栈：

Next.js
TypeScript
Tailwind CSS
shadcn/ui
lucide-react

说明：

Next.js：适合从静态页面起步，后续接入动态接口；
TypeScript：适合维护链接、分类、配置等结构化数据；
Tailwind CSS：适合快速实现玻璃感、响应式、主题变量；
shadcn/ui：用于基础组件，例如 Button、Input、Dialog、Command；
lucide-react：用于侧边栏和操作图标。

15.2 后端技术栈

后端由 Go 实现。

推荐后端技术栈：

Go
Gin / Chi
PostgreSQL / MySQL / SQLite
sqlc / GORM
Docker

建议选择：

Go + Chi + PostgreSQL + sqlc

或者：

Go + Gin + PostgreSQL + GORM

如果希望结构更清晰、SQL 可控，推荐：

Chi + sqlc

如果希望开发更快、上手成本更低，推荐：

Gin + GORM

15.3 第一版数据方案

第一版不接后端。

数据写在前端本地配置中。

推荐目录：

src/
  data/
    links.json
    categories.json
    settings.json
  services/
    links.ts
    categories.ts
    settings.ts
  types/
    navigation.ts
  components/
    Sidebar.tsx
    SearchBox.tsx
    QuickLinks.tsx

注意：页面组件不要直接依赖 JSON 文件。

应该通过 service 层获取数据。

第一版：

import links from "@/data/links.json"

export async function getLinks() {
  return links
}

后续接 Go 后端时，只需要修改 service 层：

export async function getLinks() {
  const res = await fetch("/api/links")
  if (!res.ok) {
    throw new Error("Failed to fetch links")
  }
  return res.json()
}

这样页面组件不用大规模重构。

16. 推荐数据结构

16.1 分类数据

{
  "id": "dev",
  "title": "开发工具",
  "icon": "code",
  "sort": 20
}

字段说明：

id: 分类唯一标识
title: 分类名称
icon: 图标名称
sort: 排序值

16.2 链接数据

{
  "id": "github",
  "title": "GitHub",
  "url": "https://github.com",
  "icon": "github",
  "categoryId": "dev",
  "pinned": true,
  "keywords": ["代码", "仓库", "开源", "git"],
  "sort": 10
}

字段说明：

id: 链接唯一标识
title: 链接名称
url: 链接地址
icon: 图标名称或图标 URL
categoryId: 所属分类
pinned: 是否展示在首页常用链接区域
keywords: 本地搜索关键词
sort: 排序值

16.3 设置数据

{
  "siteName": "Polaris",
  "theme": "light-glass",
  "search": {
    "defaultProvider": "google",
    "enabledProviders": ["google", "bing", "github", "local"]
  },
  "background": {
    "type": "image",
    "url": "/backgrounds/default.jpg",
    "blur": 8,
    "overlay": 0.32
  },
  "sidebar": {
    "defaultCollapsed": false
  }
}

字段说明：

siteName: 站点名称
theme: 主题名称
search.defaultProvider: 默认搜索方式
search.enabledProviders: 启用的搜索方式
background: 背景配置
sidebar.defaultCollapsed: 侧边栏默认是否折叠

17. 搜索功能设计

17.1 搜索 Provider

第一版支持四个 provider：

export type SearchProvider = "google" | "bing" | "github" | "local"

17.2 搜索行为

Google：

https://www.google.com/search?q={keyword}

Bing：

https://www.bing.com/search?q={keyword}

GitHub：

https://github.com/search?q={keyword}

Local：

在本地 links / categories 数据中搜索

17.3 本地搜索匹配规则

本地搜索匹配字段：

title
keywords
categoryId
category title

推荐匹配逻辑：

完全匹配优先
标题匹配其次
关键词匹配再次
分类匹配最后

搜索结果可以展示：

图标
标题
所属分类

回车行为：

如果只有一个高匹配本地结果，回车打开该链接
如果有多个结果，展示搜索结果列表
如果没有结果，展示空状态

18. 未来 Go 后端 API 设计

后续接入 Go 后端时，推荐 API：

GET /api/categories
GET /api/links
GET /api/links?categoryId=dev
GET /api/settings

后续管理能力：

POST   /api/links
PUT    /api/links/:id
DELETE /api/links/:id

POST   /api/categories
PUT    /api/categories/:id
DELETE /api/categories/:id

PUT    /api/settings

背景相关：

POST /api/backgrounds
GET  /api/backgrounds
PUT  /api/settings/background

19. 数据库表设计草案

19.1 categories

CREATE TABLE categories (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  icon TEXT NOT NULL,
  sort INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

19.2 links

CREATE TABLE links (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  url TEXT NOT NULL,
  icon TEXT,
  category_id TEXT NOT NULL,
  pinned BOOLEAN NOT NULL DEFAULT FALSE,
  keywords JSONB,
  sort INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,

  CONSTRAINT fk_links_category
    FOREIGN KEY (category_id)
    REFERENCES categories(id)
);

19.3 settings

CREATE TABLE settings (
  key TEXT PRIMARY KEY,
  value JSONB NOT NULL,
  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

20. 推荐开发阶段

第一阶段：前端静态版

目标：完成 Polaris 首页基础体验。

包含：

页面背景
背景遮罩
左侧边栏
边栏折叠
导航选中态
时间与日期
搜索框
Google / Bing / GitHub / 本地搜索
常用链接
响应式基础适配

数据来源：

本地 JSON / TS 配置

第二阶段：分类页面

目标：完成导航站基本内容结构。

包含：

AI 工具页面
开发工具页面
设计资源页面
学习资料页面
效率工具页面
娱乐媒体页面
生活服务页面
分类下链接展示
分类内搜索

数据来源仍可使用本地配置。

第三阶段：数据访问层抽象

目标：为接入 Go 后端做准备。

包含：

封装 links service
封装 categories service
封装 settings service
统一 TypeScript 类型
统一错误处理
统一 loading 状态

此阶段完成后，页面组件不直接关心数据来自 JSON 还是 API。

第四阶段：Go 后端 API

目标：前端从后端读取数据。

包含：

Go API 服务
数据库连接
links 查询接口
categories 查询接口
settings 查询接口
基础 CORS 配置
Docker 部署预留

第五阶段：管理能力

目标：允许用户维护自己的导航数据。

包含：

新增链接
编辑链接
删除链接
调整排序
修改分类
修改背景
修改主题
导入导出配置

管理能力不进入首页主视觉，可以放到独立管理页或隐藏入口中。

21. 推荐项目目录结构

21.1 前端目录结构

polaris-web/
  src/
    app/
      page.tsx
      layout.tsx
      globals.css

    components/
      layout/
        Sidebar.tsx
        MainLayout.tsx

      home/
        ClockGreeting.tsx
        SearchBox.tsx
        QuickLinks.tsx

      common/
        GlassCard.tsx
        Icon.tsx

    data/
      links.json
      categories.json
      settings.json

    services/
      links.ts
      categories.ts
      settings.ts
      search.ts

    types/
      navigation.ts
      settings.ts
      search.ts

    lib/
      cn.ts
      date.ts
      search-providers.ts

    styles/
      theme.css

21.2 后端目录结构

polaris-api/
  cmd/
    server/
      main.go

  internal/
    config/
    database/
    handler/
    middleware/
    model/
    repository/
    service/

  migrations/
  sql/
  Dockerfile
  docker-compose.yml

22. 首页线框

┌──────────────────────┬────────────────────────────────────────────────────┐
│                      │                                                    │
│   LOGO          ≪    │                                                    │
│                      │                                                    │
│   ⌂  首页            │                                                    │
│   ✦  AI 工具         │                 晚上好，21:56                      │
│   <> 开发工具        │              2026 年 8 月 20 日 星期四              │
│   ◌  设计资源        │                                                    │
│   📖 学习资料        │       ┌────────────────────────────────────┐       │
│   ⚡ 效率工具        │       │  🔍 搜索网站、书签或关键词...   ⌘K  │       │
│   ▶  娱乐媒体        │       └────────────────────────────────────┘       │
│   ☕ 生活服务        │                                                    │
│                      │                 常用链接                           │
│                      │       ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│                      │       │ GitHub │ │ChatGPT │ │ Gmail  │ │ Notion │ │
│                      │       └────────┘ └────────┘ └────────┘ └────────┘ │
│                      │       ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│                      │       │ Figma  │ │YouTube │ │ Vercel │ │Bilibili│ │
│                      │       └────────┘ └────────┘ └────────┘ └────────┘ │
│                      │                                                    │
└──────────────────────┴────────────────────────────────────────────────────┘

23. 设计原则总结

Polaris 首页应遵循以下原则：

首页只放最高频内容
搜索框是核心入口
搜索范围保持克制
常用链接轻量展示
分类入口放在左侧边栏
首页不展示分类卡片
首页不展示编辑和设置按钮
背景可换，但内容必须始终清晰
玻璃感要轻，不要炫技
交互动效要柔和，不要夸张
整体像浏览器起始页，不像后台系统
第一版数据本地配置，后续平滑切换到 Go 后端

最终目标：

打开 Polaris 后，用户可以立刻搜索、立刻访问常用网站，也可以通过侧边栏进入分类页面。页面具有个人氛围，但保持干净、高效、克制。

23 KiB Raw Blame History Unescape Escape

Polaris 个人导航站项目说明文档

1. 项目名称

2. 项目定位

3. 项目目标

4. 当前方案是否为静态页面

5. 整体视觉风格

6. 首页整体布局

7. 左侧边栏设计

7.1 边栏内容

7.2 折叠按钮位置

7.3 边栏宽度

7.4 边栏视觉样式

8. 主内容区域设计

9. 时间与问候语

10. 搜索框设计

10.1 搜索框定位

10.2 搜索范围

10.3 搜索框尺寸

10.4 搜索框视觉样式

10.5 搜索模式切换

10.6 本地搜索范围

11. 常用链接区域

11.1 区域定位

11.2 链接卡片内容

11.3 链接卡片样式

12. 背景设计

12.1 背景类型

12.2 背景遮罩

13. 配色系统

14. 字体建议

15. 技术选型

15.1 前端技术栈

15.2 后端技术栈

15.3 第一版数据方案

16. 推荐数据结构

16.1 分类数据

16.2 链接数据

16.3 设置数据

17. 搜索功能设计

17.1 搜索 Provider

17.2 搜索行为

17.3 本地搜索匹配规则

18. 未来 Go 后端 API 设计

19. 数据库表设计草案

19.1 categories

19.2 links

19.3 settings

20. 推荐开发阶段

第一阶段：前端静态版

第二阶段：分类页面

第三阶段：数据访问层抽象

第四阶段：Go 后端 API

第五阶段：管理能力

21. 推荐项目目录结构

21.1 前端目录结构

21.2 后端目录结构

22. 首页线框

23. 设计原则总结

23 KiB

Raw Blame History