Files
LFSpecs/DESIGN.md
T

630 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LFSpecs 设计稿(v0.2)
> 公开硬件规格库。收录手机、平板、电脑、SoC/CPU/GPU、外设等设备配置,页面只读展示,编辑需简单验证,AI 辅助补全参数。
> 本文档是设计稿,已确认的决策见第 11 节。
---
## 1. 一句话定位
一个**公开的硬件规格数据库**:像产品库一样浏览任何设备的详细参数,像编辑器一样低成本录入,像 Git 仓库一样可靠备份。
不是"我的设备清单",是"设备参数百科"——收录的是**产品型号**,不是某个人的资产。因此不记录购入价格、购买渠道、个人持有状态、使用心得。
**目标**
- 录入快:给个型号,AI 把参数表填好并按置信度分级,人只核对低置信度部分。
- 参数全:细到摄像头传感器型号、振动马达型号、扬声器单元规格。
- 浏览爽:分类、品牌、搜索、筛选、多设备横向对比,手机端也能看。
- 运维轻:单机/单容器可跑,数据是几个文件,拷走即迁移。
- 只读安全:访客看不到任何编辑入口,写操作必须过一道验证。
**非目标(明确不做)**
- 不做多用户注册体系 / 权限角色矩阵(只有一个"站主"身份)。
- 不做社区、评论、点赞、投稿。
- 不做实时价格抓取、电商比价(AI 查询是"补参数",不是"追价格")。
- 不做个人资产台账(无购入价、无保修期、无转卖记录)。
---
## 2. 技术选型
| 层 | 选择 | 理由 |
|---|---|---|
| 框架 | **Astro 5** | 默认零 JS、内容型站点最优;需要交互时用 islands 局部加载;内置图片优化、View Transitions |
| 样式 | **Tailwind CSS 4** | 与 shadcn 生态绑定,v4 走 `@tailwindcss/vite` 插件,无需 config 文件 |
| 组件 | **shadcn/ui** | 注意:它是 React 组件库,Astro 下需 `@astrojs/react` 集成,以 island 形式使用;纯展示区域仍可写 `.astro` 组件 |
| 校验 | **Zod** | 数据模型单一事实来源,表单、API、导入导出、AI 输出全部复用同一套 schema |
| 动效 | **Motion (原 framer-motion)** + Astro View Transitions | 见第 7 节 |
| 数据库 | **SQLite**(方案 A,见第 4 节) | 单文件、零运维、备份即拷贝;实现用 Node 内置 `node:sqlite`,无原生编译依赖 |
| 存储 | 本地磁盘 + S3 兼容(双驱动,见 9.1) | 先本地跑通,需要时一键切对象存储 |
| 语言 | TypeScript strict | — |
| 包管理 | pnpm | — |
**需要提前踩的点**
- shadcn/ui 在 Astro 中是"部分适配":`npx shadcn@latest init` 需选 Astro 选项(依赖 React 集成)。如果发现处处别扭,备选是只借它的**设计 token + Radix 无样式组件**,自己写 Astro 包装,或改用纯 Tailwind 手写组件。**建议先做一个 3 个组件的 PoC 验证,再决定全量采用。**
- Tailwind v4 的 `@theme` 写法与 shadcn 旧版 HSL 变量不同,初始化时注意版本一致。
---
## 3. 页面与功能
### 3.1 路由
```
/ 首页:分类入口 + 最新收录 + 热门对比
/devices 设备列表(分类 Tab + 品牌筛选 + 搜索 + 排序)
/devices/[slug] 设备详情:主图 + 关键参数网格 + 分组规格表 + 关联芯片 + 图库
/brands 品牌索引
/brands/[brand] 品牌下全部产品
/chips 芯片库(SoC / CPU / GPU / NPU / 模组)
/chips/[slug] 芯片详情 + "搭载该芯片的设备"反查列表
/peripherals 外设列表(显示器/键鼠/耳机/存储/网络/掌机配件)
/compare?ids=a,b,c 横向对比(2–4 个,同类别限定,差异高亮)
/admin 登录入口
/admin/devices/[slug] 编辑表单
/admin/import 批量导入导出
/api/* 写接口、AI 接口、导出接口
```
> 已去掉 `/timeline`(个人时间线属于私人内容),改为 `/brands` 索引,更符合公开数据库的浏览路径。
### 3.2 详情页信息布局(以手机为例)
- 头部:品牌 / 型号 / 别名 / 发布与上市日期 / 生命周期徽章(已发布·在售·停产)/ 封面图
- 关键参数卡(6–8 个最重要项,大字号):SoC、屏幕、电池、主摄、重量、存储
- 分组规格表:外观 / 屏幕 / 平台 / 内存存储 / 后置影像 / 前置影像 / 音频与震动 / 连接 / 电池充电 / 传感器 / 系统
- 关联:同 SoC 的其他机型、同代竞品入口(一键加入对比)
- 底部:数据来源与更新时间、字段级置信度说明
### 3.3 对比页设计要点
- 入口:列表勾选 / 详情页"加入对比"浮动条 / 直接拼 URL
- 顶部设备头图错位排列,便于识别
- 表格:首列字段名粘性,横向滚动;移动端可左右滑动查看设备
- 开关:**只看差异**、分组折叠
- 值对齐:数值化拆分(`6.79 英寸` → 6.79 + 单位),支持条形长度可视化(电池容量、屏幕亮度、重量)
- 同类别才能对比(手机 vs 手机、显卡 vs 显卡),跨类别给出提示
### 3.4 增强想法(可后置)
- **自动 OG 图**:每台设备生成分享卡片(satori / `@vercel/og`)
- **雷达图**:屏幕/性能/续航归一化评分可视化
- **结构化数据**:每页输出 `Product` JSON-LD,利于搜索引擎收录(公开站必备)
- **sitemap + RSS**:新收录设备可订阅
- **完整性提示**:后台将"缺关键字段"的设备标黄,引导补全
- **打印样式**:详情页可导出为干净的 PDF 规格表
- **Changelog**:每次编辑生成一条记录,公开可见(体现数据可追溯)
---
## 4. 数据层:三套方案(关键决策)
这是整个项目最需要先定的事,因为它决定部署方式、备份方式、编辑方式。
### ✅ 方案 A:Astro SSR + SQLite(已采纳)
- 部署:`@astrojs/node` adapter,Docker 单容器;数据 = `data/app.db` + `data/uploads/`,挂载卷。
- 备份:`scripts/backup.sh` 执行 `sqlite3 .backup` + 打包 uploads → 一个 `.tar.gz`。
- 迁移:换机器 = 拷目录 + 起容器。
- 编辑:`/admin` 表单直接写库,密码 cookie 会话。
- 优点:网页端可编辑;单文件备份;无外部依赖。
- 缺点:需要一台长期在线的机器(VPS / NAS / 树莓派);SQLite 单写入者,够用但不适合高并发。
### 方案 B:纯静态 + 数据即仓库(最轻运维)
- 数据存 `src/content/devices/*.md(x)` 或 `data/*.json`,走 Astro Content Collections + zod。
- 部署:任意静态托管(Cloudflare Pages / GitHub Pages / 对象存储 / NAS 静态目录)。
- 备份:Git 仓库本身就是备份与版本历史,零成本。
- 编辑:本地 `pnpm admin` 起一个仅本机可访问的编辑表单,保存后自动 `git commit`;或直接改 JSON + VS Code。
- 优点:部署最快、成本≈0、天然版本管理、迁移=clone。
- 缺点:**网页端不能改**(除非引入 Decap CMS/TinaCMS,那又需要一个 Git 网关/服务)。
### 方案 C:静态 + Cloudflare D1/R2 + Workers 写接口
- 页面静态化,写操作走 Worker + 密码;图片进 R2。
- 优点:零运维、全球加速、免费额度够个人用。
- 缺点:数据落在 Cloudflare,备份靠 `d1 export`(能做,但迁移到非 CF 环境要多一步)。
### 结论(已确认)
采纳 **方案 A**:VPS/NAS 上 Docker 单容器,Astro SSR(`@astrojs/node`)+ SQLite,浏览器内直接编辑。
- 数据访问仍收敛到单一 repository 层(`src/lib/repo.ts` 暴露 `listDevices/getDevice/saveDevice/...`),未来若想迁到 B/C 只改这一层。
- 保留 B/C 的价值:**A 必须能导出一份完整 JSON**,这样随时可以降级为静态站(导出 → 生成 content collection → 静态构建)。这个导出能力不是可选项,是方案 A 的逃生舱。
### 4.1 目录结构
```
LFSpecs/
├─ src/
│ ├─ pages/
│ │ ├─ index.astro
│ │ ├─ devices/index.astro · [slug].astro
│ │ ├─ chips/index.astro · [slug].astro
│ │ ├─ peripherals/index.astro
│ │ ├─ compare.astro
│ │ ├─ timeline.astro
│ │ ├─ admin/…(login / devices/[slug] / import)
│ │ └─ api/(auth, devices, ai, export, import)
│ ├─ components/ # .astro 为主,交互的才用 .tsx
│ ├─ lib/
│ │ ├─ repo.ts # 唯一数据出入口
│ │ ├─ db.ts # sqlite 连接 + 迁移
│ │ ├─ schema/ # zod:device / chip / specs 各分类 + FieldMeta
│ │ ├─ storage.ts # 图片存储抽象(local / s3)
│ │ ├─ ai/ # provider 抽象 + prompt + 结果校验
│ │ └─ auth.ts # 签发/校验 cookie
│ ├─ content/ # 可选:markdown 长文
│ └─ styles/
├─ data/ # 运行时数据(不进 git)
│ ├─ app.db
│ └─ uploads/
├─ scripts/backup.ts
├─ migrations/
├─ Dockerfile
└─ docker-compose.yml
```
### 4.2 表结构(SQLite)
```sql
CREATE TABLE devices (
id INTEGER PRIMARY KEY,
slug TEXT UNIQUE NOT NULL,
category TEXT NOT NULL, -- phone/tablet/laptop/desktop/handheld/peripheral
sub_category TEXT, -- 外设细分:monitor/keyboard/mouse/...
brand TEXT NOT NULL,
model TEXT NOT NULL,
aliases_json TEXT DEFAULT '[]', -- 别名 / 地区型号,参与搜索
announce_date TEXT,
release_date TEXT,
lifecycle TEXT NOT NULL DEFAULT 'released', -- announced/released/discontinued
cover_key TEXT, -- 存储 key,不是 URL
gallery_json TEXT DEFAULT '[]', -- 存储 key 数组
tags_json TEXT DEFAULT '[]',
summary TEXT, -- 客观简介
specs_json TEXT NOT NULL, -- 分类规格,zod 校验后写入
chip_refs_json TEXT DEFAULT '{}', -- {soc,cpu,gpu,npu,modem} -> chip.slug
meta_json TEXT DEFAULT '[]', -- FieldMeta[]:字段级置信度与来源
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
CREATE TABLE chips (
id INTEGER PRIMARY KEY,
slug TEXT UNIQUE NOT NULL, type TEXT NOT NULL, -- soc/cpu/gpu/npu/modem
brand TEXT, model TEXT NOT NULL, codename TEXT,
aliases_json TEXT DEFAULT '[]',
process TEXT, arch TEXT,
detail_json TEXT NOT NULL, -- 核心簇/显存/跑分等,结构随 type 变化
meta_json TEXT DEFAULT '[]',
created_at TEXT, updated_at TEXT
);
CREATE TABLE revisions ( -- 每次保存一条,用于回滚与 changelog
id INTEGER PRIMARY KEY,
entity TEXT NOT NULL, -- 'device' | 'chip'
entity_id INTEGER NOT NULL,
snapshot_json TEXT NOT NULL, -- 保存后的完整态
diff_json TEXT, -- 与上版差异,便于展示
created_at TEXT NOT NULL
);
CREATE TABLE ai_cache ( -- 省钱用
key TEXT PRIMARY KEY, -- category|brand|model
result_json TEXT NOT NULL,
sources_json TEXT, created_at TEXT NOT NULL
);
CREATE TABLE ai_drafts ( -- AI 结果先进草稿态,人工确认后才 merge
id INTEGER PRIMARY KEY, device_id INTEGER,
payload_json TEXT NOT NULL, sources_json TEXT,
status TEXT NOT NULL DEFAULT 'pending', created_at TEXT
);
CREATE INDEX idx_devices_cat ON devices(category);
CREATE INDEX idx_devices_brand ON devices(brand);
CREATE INDEX idx_chips_type ON chips(type);
```
> `specs_json` 用 JSON 列而非拆表:参数随代际变化大,拆表会陷入持续迁移。`json_extract` 足够应付筛选(如 `WHERE json_extract(specs_json,'$.display.refreshRate') >= 120`)。筛选需求变重时再加 `spec_index` 辅助表,把热门可筛字段(刷新率/容量/尺寸/重量)打平。
### 4.3 部署产物
```yaml
# docker-compose.yml
services:
app:
build: .
ports: ["3000:3000"]
volumes: ["./data:/app/data"]
environment:
ADMIN_PASSWORD: ${ADMIN_PASSWORD}
SESSION_SECRET: ${SESSION_SECRET}
AI_BASE_URL: ${AI_BASE_URL}
AI_API_KEY: ${AI_API_KEY}
AI_MODEL: ${AI_MODEL}
SEARCH_API_KEY: ${SEARCH_API_KEY}
STORAGE_DRIVER: ${STORAGE_DRIVER} # local | s3
# s3 时追加:S3_ENDPOINT / S3_BUCKET / S3_REGION / S3_KEY / S3_SECRET / S3_PUBLIC_BASE_URL
```
迁移到新机器:`tar` 打包 `data/` → 拷贝 → `docker compose up -d`。
---
## 5. 数据模型
### 5.1 设计取向
公开规格库的核心诉求是**可比**,所以:
- **强模板 + 可扩展**:每个 category 一套 zod schema 定义核心字段(保证任意两台同类设备都能逐行对齐),另留 `extra: Record<string,string>` 收纳长尾参数。不再"弱 schema"——对比页依赖字段一致性。
- **字段级元数据**:每个值都能携带 `confidence / sourceUrl / verified / capturedAt`。这是 AI 分级录入的基础,也是公开展示"数据可信度"的依据。
- **产品导向**:只记录产品客观参数,不含购入价、个人评价、持有状态。
### 5.2 实体
**Device(设备)** — 手机、平板、笔记本、台式机、掌机、外设统一入口,用 `category` 区分。
```ts
Device {
id, slug
category: 'phone' | 'tablet' | 'laptop' | 'desktop' | 'handheld' | 'peripheral'
subCategory? // 外设细分:monitor/keyboard/mouse/headset/storage/network
brand, model
aliases: string[] // 别名、地区型号(如 "Xiaomi 14 / 小米14")
announceDate?, releaseDate?
lifecycle: 'announced' | 'released' | 'discontinued'
cover?, gallery: string[] // 存 storage key,不是绝对 URL
tags: string[]
summary? // 客观简介(AI 可生成,人工可改)
specs: PhoneSpecs | LaptopSpecs | DesktopSpecs | GpuSpecs | ...
chipRefs: { soc?, cpu?, gpu?, npu?, modem? } // -> Chip.slug
meta: FieldMeta[] // 字段级来源与置信度
createdAt, updatedAt
}
```
**Chip(芯片)** — 独立实体,设备通过 `chipRefs` 引用,支持反查"搭载该芯片的机型"。
```ts
Chip {
id, slug
type: 'soc' | 'cpu' | 'gpu' | 'npu' | 'modem'
brand, model, codename?, aliases: string[]
process: string // "TSMC N4P"
arch: string // "ARMv9.2" / "Zen 5" / "Blackwell"
// SoC 专属
cpuClusters?: { name, cores: { microArch, count, clockMax, l1, l2 }[], l3 }[]
gpuBlock?: { name, arch, cores, clockMax, apis[] }
npuBlock?: { name, tops? }
ispBlock?, dspBlock?, modemBlock?
memorySupport?, storageSupport?, displaySupport?, videoCodec?
// CPU / GPU 专属
cores?, threads?, clocks?, cache?
smCount?, rtCores?, tensorCores?
memory?: { type, capacity, busWidth, bandwidth }
tdp?, pcie?, powerConnectors?
benchmarks: { name, score, unit }[]
features: string[]
meta: FieldMeta[]
createdAt, updatedAt
}
```
**FieldMeta(字段元数据)** — 与 AI 分级机制配套。
```ts
FieldMeta {
path: string // "specs.rearCamera[0].sensorModel"
confidence: 'high' | 'medium' | 'low'
sourceUrl?: string
verified: boolean // 人工确认过
capturedAt: string
}
```
**Revision / ai_cache / ai_drafts** — 与 4.2 节的表一致。
### 5.3 手机规格模板(细化版)
```ts
PhoneSpecs {
body: {
dimensions, weight, build: { front, back, frame },
sim, ipRating, colors[], buttons
}
display: {
size, resolution, aspectRatio, panel,
refreshRate, refreshRange, // "1-120Hz"
touchSampling, brightnessTypical, brightnessPeak,
hdr, protection, // "康宁大猩猩 Victus 2"
pwmDimming, // "2160Hz PWM"
alwaysOn
}
platform: { os, skin, chipset }
memory: { ram, ramType, storage, storageType, cardSlot }
rearCamera: CameraModule[]
frontCamera: CameraModule[]
vibration: { type, model?, size? } // 马达:X轴/Z轴线性、转子;型号如 "AAC 0809"
speakers: {
count, stereo, units: { model?, size?, power? }[],
dolbyAtmos, hiRes, loudnessDba?,
headphoneJack
}
connectivity: { cellular, wifi, bluetooth, nfc, gps, usb, ir, uwb }
battery: { capacity, type, wired, wireless, reverse, chargingProtocol }
sensors: {
fingerprint, fingerprintType, fingerprintPosition,
gyro, barometer, colorSensor, flickerSensor, sar, ...
}
software: { launchVersion, currentVersion, updatePolicy }
extra: Record<string, string>
}
CameraModule {
position: 'wide' | 'ultrawide' | 'tele' | 'periscope' | 'macro' | 'depth' | 'mono' | 'front'
sensorModel? // "Sony IMX890"
resolution, aperture, focalLength, sensorSize, pixelSize,
lensElements, // "7P"
ois, eis,
zoom?, // "3x 光学 / 30x 数码"
autofocusType?, // "双像素 PDAF / 激光对焦"
video: { max, modes[], stabilization } // max: "8K@24fps"
flash?
extra
}
```
**关键点:多摄必须逐颗建模**,不能在 `camera` 里塞一个字符串数组。每颗摄像头独立一条记录,才能做出"主摄 IMX890 + 长焦 OV64B + 超广角 JN1"这种可检索、可对比的结构。
**其他模板**
- 笔记本:`display / cpu / gpu / memory / storage / keyboard / touchpad / ports / battery / thermal / speakers / webcam / wifi / weight / build`
- 台式机:`cpu / gpu / motherboard / memory / storage / psu / case / cooling / ports`
- 显卡:`arch / shaders / rtCores / tensorCores / memory(类型·容量·位宽·带宽) / bus / tdp / powerConnectors / outputs / pcie / dimensions / cooling`
- 外设(按 subCategory 再分套模板):显示器 `panel/size/resolution/refreshRate/responseTime/brightness/contrast/colorGamut/hdr/ports/stand`;键盘 `layout/switch/actuation/travel/keycap/connection/battery`;鼠标 `sensor/dpi/reportRate/buttons/weight/connection`;耳机 `driver/impedance/frequencyResponse/anc/battery/codecs`;存储 `capacity/interface/seqRead/seqWrite/tbw/nand`。
### 5.4 对比逻辑
1. 校验同 `category`(外设再校验同 `subCategory`),2–4 台。
2. 取各设备 specs 的扁平化路径并集,按模板定义的字段顺序排序(模板里就是渲染顺序)。
3. 值比较前做**归一化**:拆成 `{ num, unit, raw }`,数值类字段(电池容量、屏幕亮度、重量、跑分)可用于排序与条形可视化。
4. 不同则高亮;缺失显示 `—` 并置灰。
5. 支持"只看差异"过滤与分组折叠。
---
## 6. 编辑验证("简单验证")
不做用户系统,只做**单密钥**:
1. 环境变量 `ADMIN_PASSWORD`(哈希后存,不存明文)。
2. `POST /api/auth/login` → 校验 → 签发 **HttpOnly + SameSite=Lax + Secure** cookie,内含签名 token(`jose`,有效期 7 天)。
3. 中间件保护 `/admin/*` 与所有写接口。
4. `POST` 接口校验 `Origin`,防 CSRF;登录接口做 IP 级限速(3 次/分钟)。
5. 可选:TOTP 二次验证(`otpauth`),10 行代码,愿意的话加上更稳。
> 关键原则:**读接口全部公开、无鉴权、可被 CDN 缓存**;只有写接口和 AI 接口需要 token。AI 接口也要鉴权,否则会被人刷爆额度。
---
## 7. AI 能力设计
> ✅ 已采纳:**OpenAI 兼容协议 + 独立搜索 API(Tavily/Exa)**。
### 7.1 三类能力,按优先级
1. **参数补全(P0)**:输入 `品牌 + 型号`,返回该分类的完整 specs JSON,每个字段带置信度与来源。
2. **纠错/查缺(P1)**:指向已有设备,AI 对比公开资料指出错误字段与缺失字段。
3. **文案生成(P2)**:生成客观简介与规格要点摘要(只写客观卖点,不写个人体验)。
4. (可选)**自然语言查询(P3)**:`"哪些手机支持 144Hz 且重量低于 190g"` → 转结构化筛选条件。
### 7.2 工程约束(很重要)
- **绝不静默入库**:AI 返回 → zod 校验 → 按置信度分级预填 → 人工核对 → 保存。AI 输出永远先落"草稿态"。
- **必须联网**:硬件参数迭代快,纯模型记忆幻觉严重。需要给模型接搜索工具(Tavily / Exa / Brave Search / 模型自带 web search)。
- **字段级来源**:每批 AI 结果附带 URL;写入 `meta[]`,详情页用"已核实 / 待核实"徽章区分。
- **缓存**:以 `category+brand+model` 为 key 存到 `ai_cache`,避免重复付费。
- **供应商可换**:统一走 **OpenAI 兼容协议**(`baseURL` + `apiKey` + `model` 三个环境变量),可切 OpenAI / DeepSeek / 通义 / Kimi / 本地 Ollama。
- **结构化输出**:优先用 JSON Schema 模式(`response_format: json_schema`),失败则退回"JSON + zod 修复一轮"。
- **成本**:单次补全预计 1–3k tokens 输入;加缓存后日常开销可忽略。
### 7.3 置信度分级(核心机制)
AI 必须为**每个字段**输出置信度,前端据此决定默认行为:
| 级别 | 判定依据 | 前台行为 | 保存行为 |
|---|---|---|---|
| `high` | 官方规格页原文,或 ≥2 个独立来源一致 | 自动填入,绿色徽章 | 可直接保存 |
| `medium` | 单一非官方来源(评测、数据库站),或由多个字段推导 | 预填,黄色徽章 + "待核对" | 可保存,但记录为未核实 |
| `low` | 模型推测、无出处、字段冲突 | 预填但标红,折叠进"待确认"区 | **阻塞保存**,必须逐项确认或清空 |
| 无 | 未找到 | 留空 | — |
交互要求:
- 每个字段右侧一个小徽章,hover 显示来源链接与抓取时间。
- 顶部固定条显示"共 N 项待核对",点击跳到首个 `low` 项。
- 批量操作:"全部接受 high"、"清空全部 low"。
- 保存后 `verified` 按用户是否手动确认置位;详情页据此显示数据可信度。
### 7.4 接口草案
```
POST /api/ai/lookup { category, brand, model }
-> { fields: { path, value, confidence, sourceUrl? }[], sources: Url[], cached: boolean }
POST /api/ai/audit { deviceId }
-> { issues: { path, expected, current, confidence, sourceUrl? }[] }
POST /api/ai/summary { deviceId }
-> { summary, highlights: string[] }
```
`fields` 用**扁平路径**而非嵌套对象:前端可以直接按 `path` 合入、高亮、着色,不必维护两套结构树。
---
## 8. 动效与视觉
### 8.1 选型建议(✅ 已采纳克制型)
| 用途 | 方案 | 说明 |
|---|---|---|
| 页面切换 | **Astro View Transitions**(`transition:animate`) | 零依赖,自带淡入/滑动 |
| 列表渐入、卡片悬停 | **Motion**(`motion/react`,在 island 内) | `useInView` + `stagger`,体积约 30KB |
| 数字滚动(跑分/容量) | 自写 20 行 hook | 不必引第三方 |
| 滚动叙事(首页 hero) | **GSAP + ScrollTrigger**(可选,仅首页懒加载) | 只在确实需要"一段横向滑动叙事"时才引 |
| 平滑滚动 | **Lenis**(可选) | 谨慎:会干扰可访问性,建议不开 |
| 骨架屏/加载 | 纯 CSS | — |
**结论:主用 Astro View Transitions + Motion;GSAP 作为可选增强,不默认引入**,避免三套动效库打架。
### 8.2 视觉方向
- 深色为主、浅色可选;中性灰底 + 单一强调色(如青绿/琥珀)。
- 大字号型号名 + 等宽字体的参数值(`font-variant-numeric: tabular-nums`),参数表对齐才好看。
- 卡片:细边框 + 极轻内发光,悬停时 1px 描边渐亮,不做夸张投影。
- 图片:设备正面照统一裁切比例(4:3 / 1:1),列表用同一角度,视觉更整齐。
---
## 9. 存储、部署与备份
### 9.1 图片存储驱动(本地 + 对象存储,双支持)
抽一层接口,默认本地,配置项一改就切对象存储:
```ts
interface StorageDriver {
put(key: string, buf: Buffer, contentType: string): Promise<void>
delete(key: string): Promise<void>
publicUrl(key: string): string
}
```
- **`local`**:写 `data/uploads/`,URL 走 `/uploads/*`,由 Astro 端点或静态服务返回。
- **`s3`**:S3 兼容协议(AWS S3 / Cloudflare R2 / MinIO / Backblaze B2),配置 `endpoint / bucket / region / accessKey / secretKey / publicBaseUrl`。
- **环境变量**:`STORAGE_DRIVER=local|s3`,其余按驱动按需读取。
**关键约束:数据库只存 key,绝不存绝对 URL。** 这样换驱动、换域名时数据完全不用改(`Device.cover` 存 `devices/xxx/cover.webp`,渲染时由 driver 生成 URL)。
- 上传即处理:`sharp` 生成 3 档(原图 / 1600w / 400w 缩略),转 WebP,原图保留。
- 对象存储的 `publicBaseUrl` 可以是 CDN 域名。
### 9.2 备份与迁移的差异
| 驱动 | 备份方式 | 说明 |
|---|---|---|
| local | `tar` 打包 `data/`(db + uploads) | 一份包即全量,最省心 |
| s3 | `sqlite3 .backup` + `rclone sync` 桶 | 两部分,脚本里分两条路径 |
### 9.3 方案 A 落地细节
```
docker-compose.yml
volumes: ./data:/app/data
```
- `data/app.db`(SQLite)、`data/uploads/`(图片)
- **备份**:`pnpm backup` → `sqlite3 .backup` + tar → `backups/2026-10-30.tar.gz`
- **迁移**:新机器解包 → `docker compose up -d` → 完成
- **导出**:`GET /api/export` 输出版本化的全量 JSON(含 `formatVersion`),作为长期归档格式
- **定时**:cron / 计划任务每日备份,保留 7 份轮转
> 使用 s3 驱动时,"图片随备份一起走"的前提消失,必须单独确认 `rclone sync` 是否成功——备份脚本要把两条路径的结果都打进日志。
### 9.4 必备的两条逃生通道
- `GET /api/export` 全量 JSON(含 `formatVersion`),用于跨方案迁移或降级为静态站
- `POST /admin/import` 导入并 zod 校验,拒绝脏数据
---
## 10. 分期
| 阶段 | 内容 | 产出 |
|---|---|---|
| M0 | 脚手架、Tailwind、shadcn PoC(3 个组件)、zod schema、storage 驱动、repo 层 | 能跑的空站 |
| M1 | 只读:手机列表/详情、芯片库、搜索筛选 + sitemap、JSON-LD | 可看、可收录的站 |
| M2 | 编辑:登录、表单(含字段级徽章)、图片上传、修订记录 | 可维护 |
| M3 | AI 分级补全(high 自动 / medium 标黄 / low 阻塞)+ 差异预览 | 录入效率 |
| M4 | 对比页(差异高亮、只看差异、条形可视化)、导出导入、备份脚本 | 完整闭环 |
| M5 | 动效打磨、OG 图、打印样式、部署上线 | 成品 |
---
## 11. 决策记录
| # | 决策 | 结论 | 影响 |
|---|---|---|---|
| D1 | 部署与数据层 | **方案 A**:VPS/NAS + Docker + Astro SSR + SQLite | 需要一台常开机器;浏览器内可编辑;备份=tar |
| D2 | AI 接入 | **OpenAI 兼容 + 独立搜索 API** | 多一个 `SEARCH_API_KEY`;参数可追溯来源 |
| D3 | 组件库 | **先 PoC(Button/Card/Dialog)再定** | M0 先验证 Astro + shadcn 手感,不急着全量采用 |
| D4 | 动效 | **克制型**:View Transitions + Motion,不引 GSAP/Lenis | 首页不做滚动叙事,包体小 |
| D5 | 站点定位 | **公开展示的规格库**,收录任意型号,非个人资产 | 移除购入价/持有状态/时间线;加品牌页、JSON-LD、sitemap |
| D6 | 录入分级 | **high 自动填入 / medium 预填+标黄 / low 预填+阻塞保存** | schema 需 `FieldMeta`;表单需置信度徽章与待核对汇总 |
| D7 | 图片存储 | **本地 + S3 双驱动,DB 只存 key** | 存储抽象层;备份分两条路径 |
| D8 | 芯片 | **独立实体**,设备页引用并可展开、跳转、反查 | 多一张 chips 表与一套维护流程 |
| D9 | 对比 | **同类别 2–4 台**,差异高亮、只看差异、数值条形化 | specs 需强模板与数值归一化 |
| D10 | 参数颗粒度 | **细到传感器型号 / 马达型号 / 扬声器单元** | 手机模板需多摄逐颗建模,录入成本上升(由 AI 缓解) |
### 11.1 已确认 / 待确认
**已确认**
- 语言:**仅中文**,不做多语言;参数值保留英文原文(`LPDDR5X-8533`)。
- 首批范围:**只做手机 + 芯片(SoC)**,笔记本/台式/显卡/外设的模板与路由先留空壳后置。
**待确认**
1. **站点名**:见第 12 节的候选,选定后要查域名与商标。
2. **数据来源声明**:页脚是否常驻"数据由人工与 AI 辅助整理,仅供参考"?(建议加,公开站需要)。
3. **是否允许被搜索引擎收录**:公开站默认是,但如果初期数据还不完整,可以先 `noindex` 到 M5 再放开。
### 11.2 下一步(M0 开工清单)
1. `pnpm create astro`(SSR)+ Tailwind v4 + `@astrojs/node` + `@astrojs/react`
2. shadcn PoC:装 Button / Card / Dialog,写一页 demo 验证手感
3. `src/lib/schema/`:先只做 **phone** 与 **soc** 两套 zod + `FieldMeta`
4. `src/lib/storage.ts`:`local` 驱动先实现,`s3` 留接口
5. `src/lib/db.ts` + `migrations/001_init.sql`(第 4.2 节表结构)
6. `src/lib/repo.ts` 骨架 + 可跑通的 `/devices` 列表页(先读种子数据)
7. Dockerfile / docker-compose,验证卷挂载与备份脚本
M0 完成标志:**本地 `docker compose up` 能打开首页,`/devices` 与 `/chips` 各自从 SQLite 读出种子数据。**
### 11.3 M0 实施记录(已完成)
- 脚手架:Astro 7.4.4 + `@astrojs/node` 11(standalone)+ `@astrojs/react` 7 + Tailwind 4.3.3(`@tailwindcss/vite`)
- 数据库:**改用 Node 内置 `node:sqlite`**(`DatabaseSync`),放弃 better-sqlite3,避免 Windows 原生编译与 Docker 交叉编译问题
- 已落地:`schema/`(phone、soc、FieldMeta、Device/Chip 判别联合)、`db.ts`、`repo.ts`、`storage.ts`(local 已实现,s3 留接口)、`migrations/001_init.sql`、`scripts/seed.mjs`、`scripts/backup.mjs`
- 页面:`/`、`/devices`、`/devices/[slug]`、`/chips`、`/chips/[slug]`、`/poc`、`/uploads/[...path]`
- 验证:`pnpm build` 通过;生产产物 6 个路由全部 200、伪造 slug 返回 404;Dialog island 交互经浏览器验证可开可关;`backup.mjs` 用 `VACUUM INTO` 产出快照
- 环境坑:本机 pnpm 全局 store `D:\.pnpm-store` 写权限不足导致 `ERR_PNPM_EPERM`,已用项目内 `.npmrc`(`store-dir=.pnpm-store`)规避
- **未验证**:本机未安装 Docker,Dockerfile / docker-compose 未实际跑过,需在有 Docker 的环境确认
---
## 12. 站点命名(已定:LFSpecs)
> 已确认:对外站名用 **LFSpecs**。下表保留作为备选,仅当域名 `lfspecs.*` 不可用时再启用。
站名要满足三点:能表达"参数规格"、不绑定单一品类(手机/芯片/电脑都能装进去)、中文念着不别扭。
| 候选 | 域名建议 | 说明 | 风险 |
|---|---|---|---|
| **器谱** | `qipu.app` / `qipu.wiki` | "器物谱系"。一个字表,可扩展全部硬件;中文感强,不像厂商站 | 略抽象,需副标题解释 |
| **SpecDock** | `specdock.dev` | dock = 停靠/汇总坞。英文顺口,SEO 词直白(spec 是核心搜索词) | 英文站名在国内传播弱 |
| **机尺** | `jichi.app` | 手机 + 标尺双关,记忆点最强 | 只贴手机,扩展电脑时尴尬 |
| **规格集** | `specset.io` | 最中性直白,永不过时,搜索友好 | 平庸,没有品牌感 |
| **硬件谱** | `hwpu.app` | 通俗易懂,"硬件"覆盖广 | 商标与域名大概率被占 |
**我的建议:器谱(`qipu.app`)**,理由:
- "谱"天然承接"谱系/参数表",既像一个可查的表,又暗示"收录成体系",比"库""站"高级。
- 不绑定品类——以后加显卡、外设,名字不用改;`机尺` 会卡住。
- 两个音节,中文站点名里属于短的一档,好记也好念。
备选 `SpecDock`:如果你更希望技术上易被检索、且不介意英文名,它的 `spec` 前缀对 SEO 更友好。
> 两个都需要自己去查域名注册与商标情况,我只能给方向,无法保证可注册。选定后告诉我,我同步改 README 与文档标题。