# webgame-collection 设计文档

2026-09-17 · 状态：待评审

## 1. 项目目标

一个收集"静态网页游戏"（无需服务端、纯前端交互的游戏）的开源目录站：

- 站点本身是纯静态页面（Vue3 构建产物），无服务端依赖
- 数据源为仓库内 JSON，一游戏一文件，通过 PR 提交收录
- 数据结构严格（JSON Schema 校验），并设计数据抽象层，未来可无缝接入后端 API
- 内置 markdown 文档渲染系统，访问文档时显示文档目录（TOC）
- 部署链路：GitHub Actions 构建镜像 → 推送 GHCR → 调 keel.sh webhook → k3s 拉取并滚动更新

## 2. 非目标（v1 不做）

- 站内 iframe 试玩（一律新标签外链跳转）
- 用户账号、评分、评论、收藏
- 后端 API、服务端搜索、分页（数据量预计 < 1000，纯前端处理）
- 多语言 i18n（中文为主；schema 不预留多语言字段）
- HPA、CDN、监控（纯静态 nginx，无必要）

## 3. 仓库结构

```
webgame-collection/            # 仓库根
├─ src/                        # 完整站点工程 = 唯一构建输入
│  ├─ package.json             # npm/vite 工程在此，cd src 后 npm run dev/build
│  ├─ vite.config.ts / index.html / tsconfig.json
│  ├─ app/                     # Vue 源码
│  │  ├─ main.ts / App.vue
│  │  ├─ router/               # 路由
│  │  ├─ views/                # 页面
│  │  ├─ components/           # 组件
│  │  ├─ data/                 # 数据抽象层（repository 接口 + fetch 实现）
│  │  └─ lib/                  # markdown 渲染、筛选/排序等纯函数
│  ├─ games/                   # 游戏 JSON 数据源（一游戏一文件，PR 提交点）
│  ├─ docs/                    # 站点文档源（*.md，frontmatter: title/order）
│  ├─ assets/covers/           # 仓库内封面图（文件名 = 游戏 id）
│  ├─ schema/game.schema.json  # JSON Schema（draft 2020-12）
│  ├─ scripts/build-data.mjs   # 校验 + 生成 public/data/*
│  └─ public/                  # favicon 等手写资源；public/data/ 为生成物（gitignore）
├─ docs/                       # 只服务 GitHub 仓库，不参与站点构建
│  ├─ README.md                # GitHub 首页会自动展示 docs/README.md
│  ├─ CONTRIBUTING.md          # GitHub 也会识别 docs/CONTRIBUTING.md
│  └─ superpowers/specs/       # 设计文档与实施计划
├─ deploy/                     # Dockerfile、nginx.conf、k8s manifests
├─ LICENSE                     # MIT
├─ .gitignore                  # node_modules、src/dist、src/public/data 等
└─ .github/workflows/          # validate.yml（PR 校验）、publish.yml（构建发布）
```

约束：站点构建只针对 `src/`（npm 工程根 = `src/`）；Docker 构建上下文为仓库根，但只拷贝 `src/` 与 `deploy/nginx.conf`。

## 4. 游戏数据 schema

### 4.1 文件与命名

- 位置：`src/games/<id>.json`，一游戏一文件
- `<id>`：`^[a-z0-9-]{1,64}$`，且必须等于文件名（CI 强制，防止 id/文件名漂移）

### 4.2 字段定义

| 字段 | 必填 | 类型 | 规则 |
|---|---|---|---|
| `id` | 是 | string | `^[a-z0-9-]{1,64}$`，等于文件名 |
| `name` | 是 | string | 1–60 字符 |
| `url` | 是 | string | 仅 https，合法 URL |
| `author.name` | 是 | string | 1–60 字符 |
| `author.url` | 否 | string | 仅 https |
| `description` | 是 | string | 1–140 字符，一句话简介（列表页展示） |
| `intro` | 否 | string | Markdown，≤ 5000 字符（详情页渲染） |
| `durationMinutes.min` | 是 | int | ≥ 1 |
| `durationMinutes.max` | 是 | int | ≥ min，≤ 600 |
| `type` | 是 | enum | 见 4.3 |
| `tags` | 是 | string[] | ≤ 8 个；每个 1–12 字符、无首尾空白、不重复 |
| `cover` | 否 | string | https 外链，或 `/data/assets/covers/<文件名>`（对应文件必须存在于 `src/assets/covers/`，文件名须为 `<id>.<png\|jpg\|jpeg\|webp\|avif\|gif>`） |
| `addedAt` | 是 | string | `YYYY-MM-DD` |

`additionalProperties: false`（所有对象层级），未知字段直接报错，保证严格。

### 4.3 type 枚举与中文标签

| 值 | 中文 |
|---|---|
| `puzzle` | 解谜 |
| `action` | 动作 |
| `idle` | 放置 |
| `strategy` | 策略 |
| `simulation` | 模拟 |
| `narrative` | 文字叙事 |
| `music` | 音乐 |
| `creative` | 创意 |
| `casual` | 休闲 |
| `other` | 其他 |

### 4.4 示例

```json
{
  "id": "2048",
  "name": "2048",
  "url": "https://play2048.co/",
  "author": { "name": "Gabriele Cirulli", "url": "https://github.com/gabrielecirulli/2048" },
  "description": "滑动合并数字方块的经典益智游戏。",
  "intro": "可选，Markdown 长简介。",
  "durationMinutes": { "min": 5, "max": 20 },
  "type": "puzzle",
  "tags": ["数字", "休闲"],
  "cover": "/data/assets/covers/2048.png",
  "addedAt": "2026-09-17"
}
```

### 4.5 校验规则（构建脚本 + PR CI 同源）

1. JSON Schema 校验（Ajv，draft 2020-12）
2. `id` 等于文件名
3. 全部游戏 `id` 全局唯一
4. `tags` 去重、无首尾空白、长度与数量限制
5. `cover` 为本地路径时，文件必须存在且扩展名合法
6. 校验失败输出可读错误（文件、字段、原因），退出码非 0

## 5. 生成数据（构建产物）

`scripts/build-data.mjs` 在校验通过后生成，写入 `src/public/data/`（gitignore，predev/prebuild 自动执行）：

| 产物 | 内容 |
|---|---|
| `public/data/index.json` | `{ schemaVersion, generatedAt, games: GameSummary[] }`，GameSummary = 除 `intro` 外的全部字段（目录页搜索/筛选用） |
| `public/data/games/<id>.json` | 完整游戏对象（含 `intro`），详情页按需拉取 |
| `public/data/docs.json` | `{ generatedAt, docs: [{ slug, title, order, content }] }`，`content` 为 markdown 原文（内联，文档数少，一次请求） |
| `public/data/assets/covers/*` | 从 `src/assets/covers/` 复制 |

脚本参数：无参 = 校验 + 生成；`--check` = 只校验（PR CI 用）。

## 6. 文档系统

- 数据源：`src/docs/*.md`，slug = 文件名（`^[a-z0-9-]+$`）
- frontmatter：`title` 必填；`order` 可选（数字，缺省 999，升序排序，同序按文件名）
- 缺失 `title`、文件名非法、slug 重复 → 构建失败
- 渲染：markdown-it（`linkify + typographer`），标题自动生成锚点（slug 化保留中文，重名自动去重）
- TOC：从 markdown-it token 流提取 `h2/h3`，右侧固定目录，`IntersectionObserver` 滚动高亮，点击平滑滚动
- 内容为仓库内 PR 审核过的可信来源，不引 DOMPurify；将来若接入用户投稿内容再加

## 7. 前端架构

### 7.1 技术栈

Vue 3 + TypeScript + Vite · Vue Router · Tailwind CSS v4 · markdown-it · Vitest · vue-tsc。
不引 Pinia（数据量小，模块级 composable + URL query 足够）。

### 7.2 路由

| 路由 | 页面 |
|---|---|
| `/` | 目录页：搜索 + 类型/时长/标签筛选 + 排序，响应式卡片网格 |
| `/games/:id` | 详情页：封面、元信息、intro markdown、"开始游戏"新标签外链、返回 |
| `/docs/:slug` | 文档页：左侧文档列表 + 右侧 TOC + 正文 |
| `/docs` | 重定向到第一篇文档 |
| `*` | 404（含"游戏不存在"） |

### 7.3 筛选状态

- 状态全部同步 URL query：`q`（关键词）、`type`、`tag`（逗号分隔多选）、`dur`、`sort`
- `q` 匹配 `name / description / author.name / tags`（忽略大小写，`includes`，中文可用）
- `dur` 桶（按 `durationMinutes.max` 判定，无重叠）：`short` ≤5 分钟；`mid` (5, 30]；`long` >30
- `sort`：`new`（addedAt 倒序，默认）/ `name`（中文 locale 排序）/ `duration`（min 升序）

### 7.4 数据抽象层（未来接后端的唯一边界）

```ts
// app/data/repository.ts —— 页面只依赖此接口
interface ContentRepository {
  listGames(): Promise<GameSummary[]>
  getGame(id: string): Promise<Game>          // 不存在抛 NotFoundError
  listDocs(): Promise<DocMeta[]>
  getDoc(slug: string): Promise<Doc>
}
```

- `app/data/staticRepo.ts`：fetch 实现，GET `{base}/index.json`、`{base}/games/<id>.json`、`{base}/docs.json`；内存缓存；错误类型化
- `app/data/index.ts`：导出单例；未来换 `ApiRepository` 只改这一处
- `base` = `import.meta.env.VITE_DATA_BASE_URL`，默认 `/data`；未来后端的 URL 结构照抄 `/data` 即可无缝切换
- 抽象层做轻量运行时校验（按 TS 类型检查响应体字段），不只信构建期
- 页面消费 `loading / error / data` 三态

### 7.5 视觉与兜底

- Tailwind v4，深色为主的现代目录站风格；卡片网格 1/2/3/4 列响应式
- 封面加载失败或无封面：游戏名首字 + 按 id 哈希取色的确定性渐变占位卡（稳定不闪）
- 空状态（筛选无结果）、加载骨架、错误重试面板

### 7.6 测试（Vitest，跑在 src/）

- 筛选/排序/搜索纯函数（含中文）
- TOC slug 化、提取、去重
- repository URL 拼接与错误映射（404 → NotFoundError）
- `build-data.mjs` 校验函数单测（合法/非法样例）

## 8. 部署

### 8.1 镜像构建

`deploy/Dockerfile` 多阶段：

1. `node:22-alpine`：拷 `src/package*.json` → `npm ci` → 拷 `src/` → `npm run build`
2. `nginx:alpine`：拷 `deploy/nginx.conf` 与构建产物 `dist/`

`.dockerignore` 排除 `docs/`、`deploy/k8s/`、`.git`、`node_modules`、`src/dist`、`src/public/data`。
镜像名：`ghcr.io/<owner>/webgame-collection:<sha-短哈希>` + `:latest`；包设为 public，k3s 免 imagePullSecret。

### 8.2 nginx 配置

- SPA fallback：`try_files $uri /index.html`
- gzip 开启
- 缓存：`/assets/`（Vite 哈希产物）`max-age=31536000, immutable`；`/data/*` ETag 协商缓存（`no-cache`）；`index.html` 不缓存

### 8.3 GitHub Actions

**`validate.yml`**（PR 触发，`paths: src/**`）：

1. setup-node 22 + npm cache（`cache-dependency-path: src/package-lock.json`）
2. `cd src && npm ci`
3. `npm run validate:data`（只校验，错误信息面向贡献者）
4. `npm run check`（`vue-tsc --noEmit && vitest run && vite build`）

**`publish.yml`**（push main）：

1. `permissions: contents: read, packages: write`
2. 登录 GHCR（`GITHUB_TOKEN`），`docker/build-push-action` 推 `sha-<短哈希>` + `latest`
3. 调 keel webhook：`POST ${{ secrets.KEEL_WEBHOOK_URL }}`（token 在 body/header，按集群 keel 版本约定）；secret 未配置则跳过并 log 提示（依赖轮询兜底）
4. `concurrency` 保证同时间仅一次发布

### 8.4 k3s 清单（`deploy/k8s/`）

- `namespace.yaml`、`deployment.yaml`：2 副本、RollingUpdate、readinessProbe GET `/`、资源 requests cpu 10m / 内存 16Mi，limits cpu 200m / 内存 128Mi
- `service.yaml`：ClusterIP:80
- `ingress.yaml`：k3s 默认 Traefik；host 与 TLS 用占位注释，按实际集群填
- keel 注解（Deployment）：

```yaml
keel.sh/policy: force
keel.sh/trigger: webhook     # 未配 webhook 时退回轮询
keel.sh/pollSchedule: "@every 1m"
```

- 不引入 HPA（纯静态 nginx）

### 8.5 需要一次性提供/配置的项

1. GitHub 仓库与 owner（决定镜像路径 `ghcr.io/<owner>/webgame-collection`）
2. GHCR 包可见性设为 public
3. k3s 中部署 keel.sh（或确认已有），取得 webhook URL 与 token → 写入 GH 仓库 secrets
4. 域名与 Ingress host（`deploy/k8s/ingress.yaml` 占位处）

## 9. 本地开发与验收

- 开发：`cd src && npm run dev`（predev 自动生成数据）
- 门槛：`npm run check`（vue-tsc + vitest + vite build）
- 生产形态：`docker build -f deploy/Dockerfile . && docker run -p 8080:80 <image>`，人工过一遍目录/筛选/详情/文档 TOC
- 端到端：合并一个游戏 JSON 的 PR → validate 通过；push main → GHCR 新镜像 → keel 更新 k3s → 站点出现新游戏

## 10. 未来接后端迁移路径

1. 后端提供与 `/data` 相同结构的接口（或标准 REST），URL 可直接沿用
2. 前端新增 `ApiRepository implements ContentRepository`，改 `app/data/index.ts` 单例导出即可，页面与组件零改动
3. 数据 schema 不变，PR 流程与校验规则继续适用于仓库内数据
4. 用户投稿/审核等有服务端的行为届时另开 spec，不在本设计内

## 11. 验收标准

- [ ] `src/games/` 新增合法 JSON 通过 `npm run validate:data`；非法样例（id 与文件名不符、tags 重复、cover 文件缺失、未知字段）全部报错
- [ ] `npm run dev` 目录页可搜索、按类型/时长/标签筛选、排序，URL query 可分享/刷新保持
- [ ] 详情页展示完整信息与 intro markdown，"开始游戏"新标签打开外链
- [ ] 文档页渲染 markdown，左侧列表 + 右侧 TOC 滚动高亮、锚点跳转正确
- [ ] 无封面/封面加载失败显示确定性占位卡
- [ ] `docker build` 产出镜像可跑通生产形态，缓存头符合 8.2
- [ ] PR 触发 validate.yml；push main 触发 publish.yml 推送 GHCR 并调 keel webhook
- [ ] `deploy/k8s/` 清单在 k3s 可 apply，keel 能拉新镜像滚动更新