# 技术选型与架构方案

## 1. 决策概览

### 1.1 技术栈选型

| 层级 | 技术选择 | 备选方案 | 决策理由 |
|------|---------|---------|---------|
| **静态生成器** | Hugo | Zola, Astro | 极速构建、成熟生态、Go模板 |
| **主题框架** | 自定义 | PaperMod, Stack | 完全可控、符合品牌调性 |
| **样式方案** | Tailwind CSS + 自定义CSS | SCSS/BEM | 原子化优先、暗色模式友好 |
| **搜索** | Fuse.js (客户端) | Pagefind, Algolia | 零后端、轻量、隐私优先 |
| **部署** | GitHub Pages + GitHub Actions | Vercel, Netlify | 简单免费、版本联动 |
| **CMS(可选)** | 本地Markdown | Decap CMS | 纯文本优先、Git版本控制 |

### 1.2 架构原则

```
┌─────────────────────────────────────────────────────────────┐
│                    架构决策原则                              │
├─────────────────────────────────────────────────────────────┤
│  1. 静态优先    →  零运行时依赖，最大可靠性                    │
│  2. 渐进增强    →  核心内容无JS亦可访问                       │
│  3. 内容即数据  →  Frontmatter驱动，结构化优先                │
│  4. 工具链极简  →  单一二进制(Hugo)，减少依赖                 │
│  5. 版本控制    →  Git为中心，内容+代码统一                   │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. 系统架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                         内容生产层 (Content Layer)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  Markdown    │  │  Frontmatter │  │  Assets      │              │
│  │  正文        │  │  元数据      │  │  图片/附件   │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
└─────────┼─────────────────┼─────────────────┼──────────────────────┘
          │                 │                 │
          └─────────────────┼─────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      构建层 (Build Layer)                            │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                     Hugo Static Generator                      │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │ │
│  │  │ 内容解析 │→ │ 模板渲染 │→ │ 搜索索引 │→ │ 资源优化 │      │ │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │ │
│  └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      输出层 (Output Layer)                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │  HTML    │  │  CSS/JS  │  │  Images  │  │  RSS/JSON│            │
│  │  页面    │  │  样式    │  │  资源    │  │  Feed    │            │
│  └────┬─────┘  └──────────┘  └──────────┘  └──────────┘            │
└───────┼─────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      部署层 (Deploy Layer)                           │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │              GitHub Pages (CDN + HTTPS)                        │ │
│  └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```

### 2.2 项目目录结构

```
val-blog/
├── archetypes/              # 内容模板
│   ├── journey.md          # 旅程记录模板
│   ├── sketch.md           # 速记模板
│   ├── gallery.md          # 图志模板
│   └── essay.md            # 深度文模板
├── assets/                  # 需处理的资源
│   ├── css/
│   │   ├── main.css        # 主样式
│   │   ├── dark.css        # 暗色模式
│   │   └── components/     # 组件样式
│   ├── js/
│   │   ├── search.js       # 搜索功能
│   │   ├── theme.js        # 主题切换
│   │   └── gallery.js      # 图片画廊
│   └── images/
│       └── logo.svg
├── config.toml             # 站点配置
├── content/                # 内容目录
│   ├── _index.md          # 首页
│   ├── about.md           # 关于页面
│   ├── journey/           # 旅程记录
│   ├── sketch/            # 速记
│   ├── gallery/           # 图志
│   ├── essay/             # 深度文
│   └── series/            # 系列文章
├── data/                   # 数据文件
│   └── navigation.yaml
├── layouts/                # 模板
│   ├── _default/
│   │   ├── baseof.html    # 基础模板
│   │   ├── list.html      # 列表页
│   │   └── single.html    # 单页
│   ├── index.html         # 首页模板
│   ├── partials/          # 模板片段
│   │   ├── head.html
│   │   ├── header.html
│   │   ├── footer.html
│   │   ├── navigation.html
│   │   ├── search.html
│   │   ├── theme-toggle.html
│   │   └── pagination.html
│   └── shortcodes/        # 短代码
│       ├── gallery.html
│       ├── timeline.html
│       └── map.html
├── static/                 # 静态文件
│   ├── fonts/
│   ├── images/
│   ├── favicon.ico
│   └── robots.txt
└── themes/                 # 主题目录（如使用子主题）
```

---

## 3. 功能模块设计

### 3.1 功能矩阵

| 功能 | 优先级 | 技术方案 | 状态 |
|------|-------|---------|------|
| 响应式布局 | P0 | Tailwind CSS | 待实现 |
| 暗色模式 | P0 | CSS变量 + localStorage | 待实现 |
| 中文排版优化 | P0 | typo.css + 自定义 | 待实现 |
| 全文搜索 | P0 | Fuse.js + 索引构建 | 待实现 |
| 标签系统 | P0 | Hugo Taxonomies | 待实现 |
| 时间线视图 | P0 | 自定义模板 | 待实现 |
| RSS/Atom | P0 | Hugo内置 | 待实现 |
| JSON Feed | P1 | 自定义模板 | 待实现 |
| 图片画廊 | P1 | 轻量JS + CSS Grid | 待实现 |
| 文章系列 | P1 | Hugo Sections | 待实现 |
| 阅读时间 | P1 | Hugo内置/自定义 | 待实现 |
| 目录导航 | P1 | 自动生成TOC | 待实现 |
| 相关文章 | P2 | 标签匹配 | 待实现 |
| 阅读进度 | P2 | CSS/JS | 待实现 |
| 代码高亮 | P2 | Prism.js/Chroma | 待实现 |
| PWA支持 | P2 | Service Worker | 待实现 |
| 评论系统 | P3 | Giscus(Utterances) | 待实现 |
| Newsletter | P3 | 第三方服务 | 待实现 |

### 3.2 暗色模式实现

```css
/* CSS变量定义 */
:root {
  /* 浅色模式 */
  --bg-primary: #F7F5F0;
  --bg-secondary: #FFFFFF;
  --text-primary: #2D3E50;
  --text-secondary: #5A6A7A;
  --accent: #C9A961;
  --border: #E5E1D8;
}

[data-theme="dark"] {
  /* 暗色模式 */
  --bg-primary: #1A1F2B;
  --bg-secondary: #232936;
  --text-primary: #D4D4D4;
  --text-secondary: #8A94A6;
  --accent: #D4B86A;
  --border: #3A4150;
}

/* 系统偏好检测 */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) {
    /* 暗色变量 */
  }
}
```

### 3.3 搜索架构

```
┌──────────────────────────────────────────────────────┐
│                  搜索实现方案                          │
├──────────────────────────────────────────────────────┤
│  构建时:                                              │
│  └── Hugo模板生成 search-index.json                   │
│      ├── title                                        │
│      ├── content (摘要)                               │
│      ├── tags                                         │
│      ├── date                                         │
│      └── permalink                                    │
│                                                      │
│  运行时:                                              │
│  ├── 页面加载时异步获取 search-index.json             │
│  ├── Fuse.js 初始化索引                               │
│  ├── 输入时实时搜索                                   │
│  └── 结果渲染 (标题+摘要+高亮)                        │
│                                                      │
│  优化:                                                │
│  ├── 索引分片 (按年份/类型)                           │
│  ├── 防抖 (300ms)                                     │
│  └── 缓存至 sessionStorage                            │
└──────────────────────────────────────────────────────┘
```

---

## 4. 内容模型

### 4.1 Frontmatter规范

```yaml
---
# 基础信息
标题相关
title: "文章标题"
subtitle: "副标题（可选）"

# 分类与标签
categories: ["journey"]  # journey/sketch/gallery/essay
tags: ["异世界", "魔法森林", "水晶洞穴"]
series: "魔法大陆纪行"  # 系列名称（可选）
series_order: 1        # 系列中的顺序

# 时间与状态
date: 2026-03-09T21:00:00+08:00
lastmod: 2026-03-09T22:30:00+08:00
draft: false
featured: false        # 是否精选

# 元数据
author: "Val"
location: "翡翠森林·北境"  # 故事发生地
world: "Aethoria"       # 世界观/宇宙名称

# 媒体
cover: 
  image: "/images/covers/forest-crystal.jpg"
  alt: "水晶洞穴内部"
  caption: "微弱的蓝光来自洞顶的水晶"

gallery:  # 图志专用
  - src: "/images/gallery/forest-01.jpg"
    alt: "森林入口"
  - src: "/images/gallery/forest-02.jpg"
    alt: "水晶洞穴"

# SEO
description: "在翡翠森林深处发现的水晶洞穴"
keywords: ["奇幻", "探险", "水晶洞穴"]

# 交互
comments: true
toc: true              # 是否显示目录
reading_time: true     # 是否显示阅读时间
---
```

### 4.2 内容类型定义

| 类型 | 目录 | 模板 | 特殊字段 |
|------|------|------|---------|
| 旅程记录 | `/journey/` | `journey/single.html` | location, route, timeline |
| 速记 | `/sketch/` | `sketch/single.html` | mood, weather, time_of_day |
| 图志 | `/gallery/` | `gallery/single.html` | gallery[], location |
| 深度文 | `/essay/` | `essay/single.html` | abstract, references |

---

## 5. 部署方案

### 5.1 GitHub Actions工作流

```yaml
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
          
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.123.0'
          extended: true
          
      - name: Build
        run: hugo --minify
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4
```

### 5.2 本地开发流程

```bash
# 1. 安装Hugo (macOS)
brew install hugo

# 2. 克隆项目
git clone <repo> val-blog
cd val-blog

# 3. 启动开发服务器
hugo server -D --bind 0.0.0.0

# 4. 创建新内容
hugo new content journey/2026/crystal-cave.md

# 5. 构建 (生产)
hugo --minify
```

---

## 6. 性能预算

| 指标 | 目标 | 最大允许 |
|------|------|---------|
| 首屏加载时间 | < 1.0s | 1.5s |
| 可交互时间 | < 1.5s | 2.0s |
| 首页总大小 | < 200KB | 300KB |
| 单页总大小 | < 150KB | 250KB |
| 搜索索引 | < 500KB | 1MB |
| Lighthouse分数 | > 90 | 80 |

---

## 7. 变更记录

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|---------|------|
| v0.1.0 | 2026-03-09 | 初稿创建 | Val |