lab/ts/web/astro/polaris/Polaris 个人导航站项目说明文档.md

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

## 1. 项目名称

**Polaris**

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

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

---

## 2. 项目定位

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

它的定位是：

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

页面应给人的感觉是：

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

而不是：

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

---

## 3. 项目目标

Polaris 第一阶段目标：

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

后续阶段目标：

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

---

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

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

更准确地说：

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

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

```text
links.json
categories.json
settings.json
```

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

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

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

---

## 5. 整体视觉风格

Polaris 推荐采用：

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

设计关键词：

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

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

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

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

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

---

## 6. 首页整体布局

首页采用左右结构：

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

布局原则：

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

---

## 7. 左侧边栏设计

### 7.1 边栏内容

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

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

暂时不展示：

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

---

### 7.2 折叠按钮位置

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

示意：

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

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

原因：

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

---

### 7.3 边栏宽度

展开状态：

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

折叠状态：

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

展开时显示图标和文字。

折叠时只显示图标。

---

### 7.4 边栏视觉样式

推荐样式：

```css
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;
```

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

推荐边距：

```text
left: 20px;
top: 20px;
bottom: 20px;
```

---

## 8. 主内容区域设计

主内容区域展示：

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

不展示：

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

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

推荐信息层级：

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

---

## 9. 时间与问候语

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

示例：

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

问候语规则：

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

推荐样式：

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

日期样式：

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

---

## 10. 搜索框设计

### 10.1 搜索框定位

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

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

---

### 10.2 搜索范围

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

```text
Google 搜索
Bing 搜索
GitHub 搜索
本地搜索
```

其中：

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

第一版不支持：

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

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

---

### 10.3 搜索框尺寸

桌面端推荐：

```text
width: 760px;
height: 68px;
```

可选范围：

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

移动端：

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

---

### 10.4 搜索框视觉样式

推荐样式：

```css
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 示例：

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

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

```text
⌘K
```

Windows / Linux 环境下可展示：

```text
Ctrl K
```

---

### 10.5 搜索模式切换

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

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

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

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

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

---

### 10.6 本地搜索范围

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

搜索范围包括：

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

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

示例：

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

---

## 11. 常用链接区域

### 11.1 区域定位

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

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

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

```text
GitHub
ChatGPT
Gmail
Notion
Figma
YouTube
Vercel
Bilibili
```

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

---

### 11.2 链接卡片内容

常用链接卡片只展示：

```text
图标
名称
```

不展示：

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

---

### 11.3 链接卡片样式

推荐样式：

```css
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);
```

推荐尺寸：

```text
width: 200px;
height: 76px;
```

推荐布局：

```text
两行四列
```

示意：

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

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

Hover 效果：

```css
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 支持背景自定义的设计预留。

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

后续支持：

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

默认背景建议：

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

---

### 12.2 背景遮罩

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

浅色主题：

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

深色主题：

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

---

## 13. 配色系统

默认采用浅色玻璃主题。

推荐 CSS 变量：

```css
:root {
  --color-text-primary: #0F172A;
  --color-text-secondary: #64748B;
  --color-text-muted: #94A3B8;

  --color-primary: #3B82F6;
  --color-primary-hover: #2563EB;
  --color-primary-soft: rgba(59, 130, 246, 0.10);

  --color-surface-sidebar: rgba(255, 255, 255, 0.68);
  --color-surface-card: rgba(255, 255, 255, 0.62);
  --color-surface-search: rgba(255, 255, 255, 0.72);

  --color-border-light: rgba(255, 255, 255, 0.56);
  --color-border-subtle: rgba(15, 23, 42, 0.08);

  --shadow-soft: 0 14px 40px rgba(15, 23, 42, 0.10);
  --shadow-medium: 0 20px 60px rgba(15, 23, 42, 0.12);
}
```

后续可支持深色玻璃主题。

---

## 14. 字体建议

推荐字体栈：

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

字体原则：

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

---

## 15. 技术选型

### 15.1 前端技术栈

推荐前端技术栈：

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

说明：

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

---

### 15.2 后端技术栈

后端由 Go 实现。

推荐后端技术栈：

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

建议选择：

```text
Go + Chi + PostgreSQL + sqlc
```

或者：

```text
Go + Gin + PostgreSQL + GORM
```

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

```text
Chi + sqlc
```

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

```text
Gin + GORM
```

---

### 15.3 第一版数据方案

第一版不接后端。

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

推荐目录：

```text
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 层获取数据。

第一版：

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

export async function getLinks() {
  return links
}
```

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

```ts
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 分类数据

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

字段说明：

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

---

### 16.2 链接数据

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

字段说明：

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

---

### 16.3 设置数据

```json
{
  "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
  }
}
```

字段说明：

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

---

## 17. 搜索功能设计

### 17.1 搜索 Provider

第一版支持四个 provider：

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

---

### 17.2 搜索行为

Google：

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

Bing：

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

GitHub：

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

Local：

```text
在本地 links / categories 数据中搜索
```

---

### 17.3 本地搜索匹配规则

本地搜索匹配字段：

```text
title
keywords
categoryId
category title
```

推荐匹配逻辑：

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

搜索结果可以展示：

```text
图标
标题
所属分类
```

回车行为：

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

---

## 18. 未来 Go 后端 API 设计

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

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

后续管理能力：

```text
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
```

背景相关：

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

---

## 19. 数据库表设计草案

### 19.1 categories

```sql
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

```sql
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

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

---

## 20. 推荐开发阶段

### 第一阶段：前端静态版

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

包含：

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

数据来源：

```text
本地 JSON / TS 配置
```

---

### 第二阶段：分类页面

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

包含：

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

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

---

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

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

包含：

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

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

---

### 第四阶段：Go 后端 API

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

包含：

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

---

### 第五阶段：管理能力

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

包含：

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

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

---

## 21. 推荐项目目录结构

### 21.1 前端目录结构

```text
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 后端目录结构

```text
polaris-api/
  cmd/
    server/
      main.go

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

  migrations/
  sql/
  Dockerfile
  docker-compose.yml
```

---

## 22. 首页线框

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

---

## 23. 设计原则总结

Polaris 首页应遵循以下原则：

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

最终目标：

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