Files
LFSpecs/DESIGN.md
T
2026-11-06 15:07:02 +08:00

1036 lines
63 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 实际部署方式(已上线)
服务器内存只有 1.6G,Docker 多阶段构建会触发 `kcompactd0` 长时间阻塞(load 40+,构建停在 “Rearranging server assets” 十几分钟不动),因此实际采用「宿主构建 + 容器挂载」:
```
/opt/lfspecs
├─ dist/ # 宿主 pnpm build 产物
├─ node_modules/ # 宿主 pnpm install(Linux,hoisted 结构)
├─ data/ # 持久化:app.db + uploads
└─ .env
```
容器只负责运行:`node:24-slim` + `node dist/server/entry.mjs`,挂载上面三个目录。部署脚本 `scripts/deploy.sh` 串起「拉代码 → install → build → compose 重启 → 健康检查」。
普通机器 / CI 仍可用仓库里的 `Dockerfile` 构建单镜像(`docker compose build`),不依赖挂载。
- `data/app.db`(SQLite)、`data/uploads/`(图片)
- **备份**:`pnpm backup` → `VACUUM INTO` 快照 + 打包 uploads → `backups/<时间戳>/`
- **迁移**:新机器解包 `data/` → 重新 `pnpm install && pnpm build` → 起容器
- **导出**:`GET /api/export` 输出版本化的全量 JSON(含 `formatVersion`),作为长期归档格式(M4 实现)
- **定时**: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 阻塞)+ 差异预览 | 录入效率(✅ 已完成,mock + 浏览器验证) |
| 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:本地未安装;已在 ECS 上完成容器化运行验证,但构建方式改为「宿主构建 + 容器挂载」(见 9.3 / 11.5)
### 11.4 M1 实施记录(已完成并上线)
- 搜索:`brand / model / aliases_json / summary` 的 LIKE 匹配,参数化 SQL,无 JS
- 筛选与排序:品牌 chip 列表 + 最新发布 / 按型号 / 按品牌三种排序,全部是 GET 链接
- 品牌页:`/brands`、`/brands/[brand]`(品牌参数 URL 编码 + `decodeURIComponent`)
- SEO:`/sitemap.xml` 动态端点(首页 / 列表 / 详情 / 芯片 / 品牌全覆盖)、`robots.txt`、详情页 `Product` JSON-LD、`site` 固定为 `https://specs.atie.fun`
- 详情页补充:上市日期、生命周期、标签、字段级来源列表(只对 low 显示徽章与 hover 说明,high/medium 不常驻标记,见 11.11)
- 验证:本地 `pnpm build` 通过;线上 10 个路由与筛选组合均为 200,sitemap 与 JSON-LD 内容正确
### 11.5 运行环境与踩坑记录(供换机后参考)
**AliECS**
- SSH:`atie.fun:22`(root);公网 `47.108.80.132`;内网 `172.29.109.56`;Tailscale `100.64.0.4`
- Docker 24.0.7 / compose v2.21;内存 1.6G,磁盘 40G(约 62% 已用)
- 宿主 3000 被 frps 占用,应用映射到 **3010**;80/443 由 openresty 接管(1panel)
- 代码 `/opt/lfspecs`,数据 `/opt/lfspecs/data`,容器名 `lfspecs`
- 宿主原本没有 Node,已装到 `/opt/node`(v24.22.2),`deploy.sh` 会自动加 PATH
**已修改的系统配置**
- `/etc/resolv.conf` 改为 `223.5.5.5 / 119.29.29.29`(原阿里云内网 DNS 100.100.2.136/138 整体超时,导致 Docker 连镜像加速器都解析不了);原文件备份在 `/etc/resolv.conf.bak`
- `ufw allow 3010/tcp`(阿里云安全组尚未放行 3010,公网直连不通;本机反代不受影响)
- `/etc/hosts` 加了 `47.108.80.132 gitea.atie.fun`(Gitea 域名在 ECS 上无法解析,用于 clone)
**坑位清单**
1. 本机 pnpm 全局 store 在 `D:\.pnpm-store`,无写权限 → 全部下载报 `ERR_PNPM_EPERM`;改用项目内 `.npmrc` 的 `store-dir=.pnpm-store`
2. 沙箱模式下 pnpm 生成的 junction 被重定向到 `…/trae cn/modulardata/…` 虚拟路径,命令结束即失效,Node 报 `Cannot find package`;改用 `node-linker=hoisted`,且安装需在非沙箱下执行
3. ECS 内存 1.6G 跑不动 Docker 多阶段构建(`kcompactd0` 阻塞);且**绝不能并发跑两个 build**,会直接把机器压到近乎无响应
4. Gitea 在 AtieFN 的群晖套件里(`/opt/1panel` 与 `/vol1/@appcenter/Gitea`,端口 8418),**未启用内置 SSH**(`START_SSH_SERVER` 未开),`gitea.atie.fun:22` 实际落在 ECS 的 sshd → Deploy Key / SSH push 不可用
5. 推送只能用 HTTPS 凭据;环境里的 `GITEA_TOKEN` 受安全策略限制无法被自动使用,**代码同步需人工 `git push`**,服务器侧只做 `git fetch --depth 1 && git reset --hard origin/main`
### 11.6 当前状态与后续待办
**仓库**
- `8430e53` M0 脚手架(已推送)
- `0c30c79` M1 只读增强(已推送)
- `22aa0ef` 部署方式改为宿主构建 + 挂载(**本地已提交,待 `git push`**)
- 当前工作区:M2 编辑后台、M3 AI 补全、M4 对比 / 导入导出(未提交)
**线上**
- `https://specs.atie.fun` 待用户配置反代(目标 `127.0.0.1:3010`)
- 可直接访问 `http://<ECS>:3010`(需安全组放行)或内网/Tailscale 地址
**下一步(收尾)**
1. 提交并推送 M2–M5,按 `scripts/deploy.sh` 部署到 ECS
2. 线上验收:OG 图、打印样式、对比页、导入导出、AI 真实供应商
3. 可选增强:对比页增加“复制链接 / 分享”按钮、更多数值字段的归一化评分
4. 换机续作时先执行 `pnpm install`(注意 `.npmrc` 的 hoisted 配置),再 `pnpm db:seed` 起本地数据
### 11.7 M2 实施记录(已完成,本地验证)
**登录与保护**
- `src/lib/auth.ts`:`ADMIN_PASSWORD` 常量时间比较(sha256 后 `timingSafeEqual`),`SESSION_SECRET` 签发 HS256 JWT,7 天有效
- Cookie:`HttpOnly` + `SameSite=Lax` + `Path=/`,`COOKIE_SECURE=1` 时加 `Secure`
- 登录失败按 IP 限速:1 分钟内 3 次后返回 `?error=rate`
- `src/middleware.ts` 拦截 `/admin/**`,未登录跳 `/admin?next=...`
- 写接口统一 `guardWrite`:登录态 + 同源校验;`/api/auth/logout` 直接清 cookie
**页面与接口**
- `/admin`:未登录显示登录表单,已登录显示仪表盘(设备/芯片列表、最近修订、新增入口)
- `/admin/devices/[slug]`(`new` 为新增)、`/admin/chips/[slug]`:React island 表单
- 设备表单:基本信息、SoC 引用、封面图上传、9 个规格分组、前后摄逐颗增删、扬声器单元增删、扩展字段 JSON、字段来源徽章与“已核实”勾选
- 芯片表单:基本信息、GPU/NPU/ISP/DSP/基带、内存存储显示支持、编解码;核心簇/跑分/扩展字段用 JSON
- `POST /api/devices`、`POST /api/chips`:zod 校验,`?create=1` 时 slug 冲突返回 409,成功返回完整实体
- `POST /api/upload`:登录 + 同源,允许 jpg/png/webp/avif,≤10MB,key 形如 `devices/<slug>/<时间戳>-<随机>.<ext>`
**修订记录**
- `saveDevice` / `saveChip` 与 `revisions` 插入放在同一事务;保存失败整体回滚
- 修订存保存后的完整快照;编辑页展示最近 10 条(`diff_json` 暂留空,回滚 UI 未做)
**安全配置**
- 关闭 Astro 内置 `security.checkOrigin`:`@astrojs/node` 在未配置 `allowedDomains` 时会把 `request.url` 的 origin 回退到 `localhost`,导致反代后的表单提交被误判跨站
- 自实现 `sameOrigin`:把 `Origin` 的 host 与 `Host` / `X-Forwarded-Host` 比对;所有写接口均已接入
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- 用独立验证库(`DB_PATH=data/verify.db`、`UPLOADS_DIR=data/verify-uploads`)启动 standalone 产物:`node dist/server/entry.mjs`
- 未登录访问编辑页 302 到登录;无 cookie 写接口 401;错误 Origin 403;空 payload 400;重复 slug 409
- 登录成功后保存设备/芯片,前台详情同步更新;`revisions` 生成快照;图片上传后 `/uploads/<key>` 返回 200 与正确 content-type
- 浏览器端到端:登录 → 仪表盘 → 编辑 Xiaomi 14 → 修改简介 → 保存 → 出现“已保存”
- 连续 3 次错误密码后第 4 次正确密码返回 `?error=rate`
- 本机受限沙箱内 `astro dev` 首次 SSR 模块读取耗时 90s+ 并触发 `transport invoke timed out`,故本地验证走生产构建产物;普通终端如遇同样问题可用 `pnpm build && node dist/server/entry.mjs`
### 11.8 M3 实施记录(已完成,mock + 浏览器验证)
**字段注册表**
- 新增 `src/lib/spec-fields.ts`:手机规格分组、摄像头字段、扬声器字段、路径读写(支持 `rearCamera[0].sensorModel` 这类扁平路径)、字段标签、AI 白名单判定
- `DeviceEditor` 改为从注册表渲染,不再内嵌字段定义
**AI 管线(`src/lib/ai/`)**
- `search.ts`:Tavily 兼容搜索,取前 5 条(标题 / URL / 内容摘要);未配置 key、无结果、请求失败都降级为模型知识并返回提示
- `prompt.ts`:系统提示要求只输出 JSON;用户提示注入品牌、型号、白名单路径、资料正文;明确 high/medium/low 判定与“无资料不得 high”
- `lookup.ts`:OpenAI 兼容 `chat/completions`(`response_format: json_object`,120s 超时),解析失败自动修复一轮
- 字段校验:只接受注册表白名单;bool / number / list / position 强转;非法路径与类型丢弃;`sourceUrl` 必须命中本次搜索 URL,否则丢来源并把 high 降为 medium;无搜索时 high 统一降 medium;按 high→medium→low 排序,最多 200 项
- 缓存:按 `phone|品牌|型号` 写入 `ai_cache`;支持 `force` 绕过并覆盖缓存
- `apply.ts`:把扁平字段合入设备 specs(摄像头 / 扬声器单元自动补槽),同步写 `meta[]`(confidence / sourceUrl / verified=false / capturedAt);提供清空字段与展示格式化
**接口与阻塞**
- `POST /api/ai/lookup`:登录 + 同源,参数 zod 校验;未配置返回 503,模型/搜索异常返回 502
- 保存接口(设备 / 芯片)新增服务端 low 检查:存在 low 且未核实且有值的字段时返回 400,附带 `path` 列表
- 前端保存前同样检查;底部显示待核对清单,可「确认全部 low」「清空全部 low」;来源区支持「全部接受 high」
**表单交互**
- 基本信息后新增 AI 补全区:品牌/型号、忽略缓存、加载态、错误提示
- 结果预览逐项显示字段标签、置信度徽章、当前值 → AI 值、是否有变化、来源链接
- 默认全选,可逐项取消;应用后写入表单与 meta,字段右侧徽章立即更新
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- 本地 mock 服务同时模拟 Tavily `/search` 与 OpenAI `/v1/chat/completions`,用独立验证库跑 standalone 产物
- 返回 10 个字段:真实来源的 high 保留;伪造来源的 high 丢来源并降 medium;无来源 high 降 medium;`specs.evil` 被丢弃;`speakers.count` 字符串 "2" 转为数字 2
- 第二次请求 `cached=true`;`force=true` 返回 `cached=false`;`ai_cache` 只有一条记录
- 无 AI 配置的服务实例返回 503,并列出缺失变量
- 种子设备的 low 字段使保存返回 400;把该字段 `verified` 置 true 后保存 200
- 浏览器端到端:登录 → Xiaomi 14 → AI 补全 → 预览 high 2 / medium 7 / low 1 → 应用 10 个字段 → 保存被客户端拦截 → 确认全部 low → 保存成功(`?saved=1`,修订 #2)
- 保存后核对数据库:刷新率 144Hz、电池 5000mAh、配色数组、`rearCamera[1]` 更新为 tele + S5KJN1、扬声器数量 2,meta 来源与置信度完整
### 11.9 M4 实施记录(已完成,本地验证)
**对比页**
- `/compare`:无 ids 或不足 2 款时显示选择器;支持 `?ids=a,b` 与重复 `ids=a&ids=b`;校验 2–4 款、同类目、slug 存在
- `src/lib/compare.ts` 从字段注册表生成分组;后置影像按位置(主摄/超广角/长焦/潜望/微距/景深/黑白)分组,前置单独;扬声器单元聚合
- 差异高亮(圆点 + 行底色),缺失值 `—` 置灰;`?diff=1` 只看差异
- 每组 `<details>` 可折叠;首列 sticky;横向滚动
- 数值条形:重量、屏幕尺寸、典型/峰值亮度、刷新率、电池容量、有线/无线充电、扬声器数量;宽度按组内最大值归一
- 导航加入「对比」,详情页加入「加入对比」,选择器自动预选
**导出**
- `GET /api/export` 公开下载,`formatVersion: 1`,包含 devices / chips / exportedAt / generator
- `content-disposition` 文件名带时间戳,`cache-control: no-store`
**导入**
- `POST /api/import`:登录 + 同源;支持 JSON body 或 multipart(`file` / `json` 字段)
- 格式 `{formatVersion:1, devices, chips}`;逐条 zod 校验,全部通过才进入事务
- `repo.importEntities` 在同一事务内 upsert,任一失败回滚;保留 created_at,更新 updated_at,并写 revisions
- 上限 5000 条 / 20MB;错误返回带 `path` 的 issues
- `/admin/import` 页面:选择文件或粘贴 JSON、格式化、错误列表、导入结果;仪表盘加入导入/导出入口
**备份**
- 复用 `pnpm backup`:`VACUUM INTO` 生成一致性 DB 快照 + 复制 uploads;本次用验证库跑通并确认快照可查询
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- 导出返回 formatVersion=1、devices=1、chips=1
- 将导出 JSON 克隆出 Xiaomi 14 Pro(改 slug/型号/尺寸/重量/电池/主摄)后导入,返回 devices=2/chips=1;前台详情与对比页均 200
- `/compare`(空 / 1 款)显示选择器;2 款对比页含字段列、差异圆点、数值条、分组;`diff=1` 从 10 项缩到 6 项
- 浏览器验证:表头与两款机型、只看差异切换、数值条、分组折叠均通过
- 脏数据导入 400(4 处 issue),未写入合法的那一半(`/devices/should-not-exist` 仍 404)
- formatVersion=2 返回 400;未登录导入 401
- 备份脚本产出 `backups/<时间戳>/app.db` 快照
### 11.10 M5 实施记录(本地完成,线上部署待执行)
**动效**
- BaseLayout 引入 Astro `<ClientRouter />`,`<main transition:animate="fade">` 做页面淡入
- 列表网格加 `.reveal-grid`:CSS `reveal-up` 0.35s + 40ms 级联(最多 8 个),无额外 JS
- `prefers-reduced-motion: reduce` 下关闭列表动画与 View Transition 动画;未引入 GSAP / Lenis
**OG 图**
- 新增 `src/pages/og/[slug].png.ts`:设备 slug 生成 1200×630 PNG,`site` 为通用站点卡;未知 slug 404,进程内缓存 5 分钟
- `src/lib/og.ts`:SVG 卡片模板 + sharp(density 72)转 PNG;设备卡展示品牌型号、生命周期、SoC / 屏幕 / 电池 / 重量
- OG 文字只用 Latin 字符(型号/芯片名含中文时回退 slug,尺寸/电池/重量抽取数字后统一单位),避免容器缺中文字体出现方框
- BaseLayout 输出 canonical、`og:type/title/description/url/image`、`og:image:alt`、`twitter:summary_large_image`
- 设备详情页传入 `/og/<slug>.png` 与 canonical 路径;其他页面默认 `/og/site.png`
**打印**
- 全局 `@media print`:浅色配色、隐藏 `.print-hidden`(导航、页脚、操作按钮)、取消 sticky / 横向滚动 / 阴影、`break-inside: avoid`
- 设备详情页加「打印 / 保存 PDF」按钮,调用 `window.print()`
- 对比页的切换按钮与面包屑打印时隐藏
**主题与交互细节(反馈修正)**
- 黑白主题通过 `html[data-theme]` + 同一套语义变量实现;右上角按钮切换,`localStorage` 记忆,首次访问跟随系统
- 头部主题脚本在 `<head>` 内联执行,避免首屏闪烁;切换按钮用事件委托,ClientRouter 导航后仍有效
- ClientRouter 换页会带入服务端渲染的 `<html data-theme="dark">`,因此监听 `astro:before-swap` / `astro:after-swap` / `astro:page-load`,把 `localStorage` 中的选择重新写回,避免跨页后主题失效
- 详情页关键参数卡、影像卡、规格表行增加 hover:行底色 + 字段名切强调色
- 修复手机列表卡嵌套 `<a>` 导致的布局错乱:卡片改为单一链接,品牌改为纯文本,卡片恢复紧凑网格布局
**部署**
- `sharp` 升为直接依赖
- 标准 Dockerfile runtime 阶段安装 `fontconfig` / `ttf-dejavu`
- 宿主构建 + `node:24-slim` 方案在 compose 中只读挂载宿主 `/usr/share/fonts` 与 `/etc/fonts`;线上主机需有 DejaVu 字体
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- `/og/site.png`、`/og/xiaomi-14.png` 返回 200 / image/png / 1200×630,未知 slug 返回 404;读取 PNG 确认标题、四个参数卡与底部文字无重叠溢出
- 详情页 HTML 含 canonical、`og:type=article`、设备专属 `og:image`、twitter 卡;首页使用 `/og/site.png`
- 页面含 `astro-view-transitions-enabled`,列表页含 `.reveal-grid`,构建 CSS 含 `.print-hidden` 与 `reveal-up`
- 浏览器验证:首页卡片、手机列表、Xiaomi 14 详情、加入对比与打印按钮均正常;详情标题已去除“Xiaomi Xiaomi”重复
- 黑白主题实测:`data-theme` 与 `localStorage` 在 dark/light 间正确切换;手机列表卡恢复为正常紧凑卡片
- 跨页主题实测:`/devices` 切到 light 后进入 `/devices/xiaomi-14` 仍为 light,返回列表与整页刷新后也保持
- 详情页 hover 实测(dark / light 两套配色):规格行背景高亮、字段名变为强调色
- 未执行线上部署:需要先提交/推送代码,并在 ECS 安装/挂载字体后按 `scripts/deploy.sh` 上线
### 11.11 详情页参数展示改造(反馈修正)
**顶部参数卡**
- 从 6–8 张扩展到 19 张,分多排展示:SoC、屏幕、电池、主摄、超广角、长焦、影像场景、内存、存储、充电、无线充电、系统、马达、扬声器、Wi-Fi、USB、指纹、重量、防护
- 屏幕卡同时展示尺寸与分辨率,内存卡展示 RAM + 类型,充电卡展示有线/无线功率,USB 卡展示版本 + 实际速率
- 卡片改为 `<a href="#specs-…">`,点击平滑滚动到对应详细分组;分组与 `SoC` 卡均加 `scroll-mt-6`,避免被粘性头部遮挡
**详细参数**
- 分组拆为:外观、屏幕、平台、内存与存储、振动、扬声器、连接、电池与充电、传感器、系统与更新;前后摄单独分组
- 屏幕新增面板厂商 `display.vendor`(如 TCL 华星)与技术代号 `display.technology`(如 C8)
- 双扬声器按 `speakers.units[].position` 拆成“扬声器(上)/(下)”两行,分别展示型号、尺寸、功率
- 振动新增实际体积 `vibration.volume`
- 连接新增 `connectivity.bands`、`satellite`、`satelliteProvider`、`satelliteBands`、`usbSpeed`、`usbVideoOut`
- 系统新增 `software.currentVersion` 与 `software.updateTimeline`,更新时间线逐条展开为“更新记录 1/2…”
- 内存新增 `memory.storageSpeed`
**Hover 弹层与低置信度标记**
- 新增 `HoverInfo.astro`:连接分组内的“移动网络频段(N)”和“卫星通信频段”支持 hover / 键盘聚焦弹出面板;卫星面板显示运营商与频段 chip
- 新增 `LowBadge.astro`:只对 `confidence === 'low'` 渲染 `low` 徽章;hover / 聚焦显示字段名、路径、已核实/待核实、来源链接;`high` 与 `medium` 不标记
- 顶部卡片、影像字段、规格行与数据来源列表统一使用 `LowBadge`;数据来源列表移除了 high/medium/low 颜色标签,只保留核实状态与 low 徽章
**数据与后台**
- `phoneSpecsSchema` 与 `spec-fields.ts` 同步新增字段;AI 白名单、表单、路径读写自动覆盖
- 后台设备表单的 list 字段改用 `ListInput` 提交到 `specs`;`ListInput` 在外部值变化时同步输入框(AI 应用/回填)
- 扬声器单元行新增“位置”选择(上/下/左/右)
- `scripts/seed.mjs` 更新 Xiaomi 14 示例数据并重新执行 `pnpm db:seed`
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- 顶部参数卡布局正常;点击“屏幕”卡后 `#specs-display` 滚动到距顶部约 24px
- 屏幕厂商/技术、上/下扬声器型号、马达体积、USB 速率/视频输出、系统更新记录均正确渲染
- “移动网络频段(18)”hover 正常显示 18 个频段
- 用临时数据库把 Xiaomi 14 改为卫星机型(天通 + T1/T2/T3),hover“卫星通信频段”正常显示运营商与频段 chip;验证后已删除临时库与测试服务器
- low 徽章 hover 显示“振动 · 马达型号 待核实”及来源;high 字段不再出现标记
### 11.12 对照“手机性能排行”补充参数(三扬声器 / 附加说明)
**数据修正(Xiaomi 14)**
- 屏幕比例改为 `20.0:9`,补 OLED 等效 PPI `375`,峰值亮度改称“局部峰值亮度”;屏幕特性补“柔性直屏”“支持类DC调光”
- 充电协议补 `QC2.0`
- 超广角补 `115°` 视场角;长焦改为 `2.6x 光学(60mm)/ 3.2x(75mm)`,对焦补“10cm 以上”
- 设备跑分补 GFXBench 曼哈顿 3.1 High、Aztec Ruins High 与综合效能;备注补玻璃版/素皮版的厚度与重量;补耳机接口说明
- SoC 补 `6 MB` 系统缓存
**新增字段与能力**
- 新增 `display.equivalentPpi`、`cameraModule.fov`、`socDetail.systemCache`
- 复用 `display.refreshNote` 表达附加说明,如“1-165Hz 自适应刷新率,最高支持 185Hz(185Hz 只在部分游戏场景生效)”
- `speakers.units[].label` 支持“上 / 下 / 中置 / 第三单元”等任意标识,`speakers.units` 可超过两个单元
**验证**
- 临时数据库将 Xiaomi 14 改为三扬声器(上 / 下 / 中置)并写入 185Hz `refreshNote`
- 页面正确渲染“扬声器(上 / 下 / 中置)”、顶部卡片“3 单元”、刷新附加说明、等效 PPI、视场角、系统缓存、QC2.0、GFXBench、备注与耳机接口
- `specs.benchmarks` 的 low 徽章 hover 正常显示说明;`pnpm typecheck`、`pnpm build` 通过;临时库与测试服务已删除
### 11.13 AI 添加设备与三机型排版优化
**AI 补全**
- `.env` 接入 DeepSeek(`AI_BASE_URL=https://api.deepseek.com/v1`、`AI_MODEL=deepseek-chat`);未配置 Tavily,仍可走模型知识
- 实测无参考资料时只返回 8 个泛化字段(且全为 low),不满足最新机型录入
- 编辑页「AI 补全」新增“补充参考资料”:官方链接 + 官网参数文本;后端 `sourceText` 随请求进入提示词,并参与缓存键,避免与无资料结果串缓存
- 提示词补全 `PHONE_TOP_LEVEL_FIELDS`(手机特点 / 影像功能 / 跑分 / 售价 / 官网),扬声器单元扩展到 `0..4`,要求逐单元用 `label` 区分上 / 下 / 中置 / 低音单元,附加条件写入 `display.refreshNote`
- 实测:K90 Pro Max 返回 76 个字段、Find X10 Pro Max 返回 80 个字段,均为 medium;应用后可用人工修正补齐
**新增设备**
- `redmi-k90-pro-max`:第五代骁龙 8 至尊版、6.9 英寸 120Hz、7560mAh、100W + 50W、BOSE 2.1 三扬声器(上 / 下 / 低音炮)、5x 潜望长焦
- `oppo-find-x10-pro-max`:天玑 9600 Pro、6.78 英寸 144Hz(1-120Hz 智能切换,144Hz 仅部分游戏)、8000mAh、80W + 50W、三颗 2 亿像素镜头 + 丹霞色彩镜头、冰河散热
- 新增 `scripts/seed-devices.json` 保存两台设备的完整规格,`seed.mjs` 改为按 slug 循环 upsert 三台设备
**排版**
- 顶部卡片改为等高、两行截断;电池 / 充电 / Wi-Fi / 相机使用短值,避免长文本溢出
- 卡片上方新增分组快捷导航
- 详情分区调整为:屏幕与外观 → 性能(SoC + 平台 + 内存 + 跑分)→ 影像 → 电池与充电 → 音频与振动 → 连接与网络 → 传感器 → 系统与更新 → 售价与补充
- 分区加编号与分组小标题,表格包进圆角卡片;相机位置改为中文标签,新增 `color`(色彩镜头)枚举与标签
- 未关联芯片库的设备显示“芯片库暂未收录”,不再出现空白性能区
**验证**
- 三台设备详情页 200;卡片、快捷导航、分区顺序、K90 三扬声器、OPPO 色彩镜头均正常
- K90 / OPPO 数据来源从 76/80 条字段级记录收敛为 1 条整机来源 + 售价记录
- `pnpm typecheck`、`pnpm build`、`pnpm db:seed` 通过
### 11.14 AI 多源检索、快速创建与字段级补全
**多来源检索**
- Tavily 仍为优先;未配置 `SEARCH_API_KEY` 时改为 Bing / Baidu 公开检索 + 白名单抓取
- 白名单:厂商官网、ZOL、PConline、Kalvo、GSMArena、IT之家、快科技、Notebookcheck、SMZDM、知乎等
- 同一域名最多 2 条,避免官网泛化页占满结果;官方 URL 按品牌 / 型号直接猜测(如 `mi.com/prod/{slug}/specs`、OPPO Find X 系列参数页)
- Kalvo 搜索作为稳定补充源:`zh.kalvo.com/search?q=型号`,可补到 ZOL / PConline 未覆盖的机型
- 检索失败才降级为模型知识;抓到的来源全部进入提示词做交叉验证
**快速创建流程**
- `/admin/devices/new` 只保留 slug 输入 + 单按钮;提交后调用 `POST /api/ai/prospect`
- 服务端从 slug 推断品牌 / 型号(redmi-k90-pro-max → Redmi / K90 Pro Max),多源补全后直接创建初稿
- 创建成功跳转 `/admin/devices/{slug}?created=1`,进入原有详细编辑页
**字段级补全**
- 每个规格字段(含摄像头字段、扬声器单元、设备补充、振动等)旁新增 `AI` 按钮
- 调用 `POST /api/ai/field`,只检索当前字段;字段旁的“补充参考资料”文本也会传入
- 适合官网不公开的扬声器单元型号、尺寸、马达型号、体积;实测 K90 Pro Max:
- 扬声器单元:`AAC 1115K`
- 马达:`瑞声 0809B`
- 均以 `medium` 写回,并保留“仅拆解资料提及”的 note
**稳定性处理**
- `max_tokens` 提升到 8192;提示词要求 `note` 只在冲突/必要补充时填写,减少输出体积
- 输出被截断时用 `salvageFields` 保留已完整的字段对象,避免整批失败
- 多来源 URL 合并为 `sourceUrls`,最多 3 个;`note` 在编辑预览中展示
**实测**
- OPPO Find X10 Pro Max:6 个来源(官网 ×2 / ZOL ×2 / PConline / Kalvo),返回 100 个字段
- REDMI K90 Pro Max:5 个来源(ZOL / Kalvo / SMZDM 等),返回 68 个字段
- OnePlus 15:公开资料不足,仅 4 个字段,仍可创建初稿后手动补充
- 浏览器验证快速创建:输入 `oneplus-15` → 生成初稿 → 自动跳转详细编辑页;每个字段的 `AI` 按钮正常渲染
- `pnpm typecheck`、`pnpm build` 通过
### 11.15 中国市场本地化与二次补全修复
**问题**
- OnePlus 16 快速创建只返回 20~41 个字段,大量英文,售价为 `€800`
- 编辑页输入官网 URL 二次补全仍缺失;ZOL 参数页正文在导航/概览后约 3600 字符才进入详细参数,3500 字符截断导致只拿到概览
**修复**
- 单来源正文上限 3500 → 9000 字符;ZOL / PConline 详细参数表可完整进入提示词
- 提示词新增中国市场规则:文本值简体中文(芯片/协议/接口/传感器代号保留英文),`pricing` 只写国行人民币;只有 EUR / USD / GBP 时直接省略
- 服务端对 `pricing` 做二次过滤,含 `€/£/$/EUR/USD/GBP/欧元/美元/英镑` 的条目直接丢弃
- 手动补充链接改为真正抓取正文:`fetchManualSources()` 不受白名单限制(仍拒绝内网),支持多行 URL(最多 4 条),并入 `sources` 后按 URL 去重
- 纯数字型号的关键词筛选回退为品牌词,避免 OnePlus 16 抓到 iPhone 16 / Meizu 16 / realme 16
- Kalvo 站内搜索改用“品牌 型号”,字段级检索同样修正
- `officialUrl` 从已抓取来源里按“官方域名 + 路径含型号 + 具体参数页”打分选出,替代模型输出的品牌列表页
- AI 缓存键加版本前缀 `v2`,检索/提示词规则变更后不再命中旧结果
**实测(OnePlus 16)**
- 整机检索:6 个来源(官网 / ZOL ×2 / PConline / OPPO shop 等),96 个字段,中文 + 人民币,
`officialUrl = https://www.oneplus.com/cn/oneplus-16/specs`
- 手动补充官网 + ZOL:93 个字段,官网来源优先,高置信度字段明显增多
- 字段级 `specs.vibration.volume` 返回 `null`:官网 / ZOL 不公开马达体积,属于资料缺失而非流程失败
- 已用最新结果刷新测试草稿 `oneplus-16`:159 个非空值,售价为 5999 / 6799 / 7499 / 8499 元
- `pnpm typecheck`、`pnpm build` 通过;详情页 200,售价、扬声器、官网链接正常渲染
### 11.16 编辑页字段核验与详情页顶部展示带
**编辑页**
- 每个带 `FieldMeta` 的输入框增加「核验」按钮:一次点击把该路径 `verified` 置为 true,low 字段保存阻塞随之解除,无需滚到底部清单
- AI 按钮与核验按钮统一放大到 `text-xs` + `px-3 py-1.5`;置信度徽章改为 `text-xs`、带底色,待核 / 已核状态更易读
- 摄像头位置、视频模式、扬声器单元等动态路径也接入同一套 AI + 核验按钮
**详情页**
- 标题下方新增 `device-hero` 展示带:配色圆点 + 中文色名;售价按版本拆成卡片,最低价高亮「起售价」
- 顶部渐变取自首个配色(`--device-accent`),叠加细网格纹理;浅色主题自动降低透明度,打印时隐藏纹理
- 初始售价从底部「售价与补充」移出,该节更名为「发布与补充」;配色从外观表移出
- 移除底部「数据来源」字段清单,字段级来源只在编辑页保留;低置信字段仍保留 hover 徽章
- 参数卡数值从 15px 提升到 17px 并加粗,标签增加字重;分组标题提升到 20~24px,表格正文 15px,镜头卡标题与分辨率加粗
- 详情页卡片网格启用 `reveal-grid` 渐入;打印仍保持浅色且隐藏装饰背景
**验证**
- `pnpm typecheck`、`pnpm build` 通过
- 浏览器验证 `oneplus-16`:顶部展示 3 个配色与 4 档售价,底部无「数据来源」清单,卡片数值层级正常
### 11.17 配色推断与字段级 AI 状态修正
**配色**
- 一加 16「明日星光」原先未命中关键词,走哈希色相得到浅蓝;新增「星光 / 星芒 / 星耀」→ 银白 `#d8dce2`
- 把绿色关键词组提到黑色之前:「黑暗森林」按森林绿而不是按“黑”取深灰
- 未知名称仍用稳定哈希色相兜底
**字段级 AI**
- 原先 `found=false` 也把按钮置为红色 `!`,与真正的接口/解析失败混淆;现在拆成三种状态:
- `✓`:成功补全
- `无`(黄色)+「无公开数据」:检索到来源但没有明确依据,hover 显示完整 notice
- `!`(红色)+「检索失败」:HTTP 错误或模型输出无法解析
- 字段补全会复用整机补全缓存里的来源 URL(过滤品牌首页 / 系列页 / 搜索页),即使 Bing / Baidu 临时限流,仍能用 ZOL / PConline / 官网正文
- 模型返回 `null` 时抛出 502,不再被误判为“无数据”
**实测(OnePlus 16)**
- 马达型号、扬声器尺寸在复用整机来源后可以补全;马达体积 / 扬声器功率 / 屏幕厂商仍返回「无公开数据」
- 字段请求 notice 会写明「复用了整机补全的 4 个来源」以及公开检索结果
- `pnpm typecheck`、`pnpm build` 通过;详情页 `--device-accent` 已变为 `#d8dce2`
### 11.18 真实配色字段与区块级 AI 补全
**配色**
- 文字色名无法稳定映射(“黑暗森林”实际为黑色),新增 `specs.body.colorHexes`,与 `colors` 顺序一一对应;AI 依据官方描述、产品图和色名语义给出 #RRGGBB
- 展示页优先使用 `colorHexes`,缺失时回退到色名推断;一加 16 实测:
- 明日星光 `#E8E8E6`(银白)
- 黑暗森林 `#1C1C1E`(近黑)
- 火星杰作 `#B5543A`(橙红)
- 已刷新 `oneplus-16` 草稿,并补入用户确认的「京东方(BOE)/ X4 发光材料」
**区块 AI**
- 新增 `POST /api/ai/section` 和 `lookupPhoneSection()`:按 `PHONE_SPEC_SECTIONS` 一次补全一个分区(外观、屏幕、平台、内存与存储、振动、连接、电池与传感器等)
- 区块 prompt 只列该分区路径,允许跨字段推导(如分辨率 + 尺寸 → PPI),并保留交叉验证与 `colorHexes` 规则
- 编辑页分区标题旁新增「区块 AI」按钮;结果以内联预览展示,可勾选后应用
- 来源策略:整机缓存来源 + 区块定向检索 + 手动链接,最多 8 个;按主域限流,过滤品牌首页 / 系列页
- Baidu 公开检索跳转链接解析从 5 条提升到 8 条并过滤广告位;Bing 中文结果噪声较大时由品牌关键词过滤兜底
**实测(OnePlus 16)**
- 外观区块:8 个字段 + `colorHexes` 三色,medium;屏幕区块:20 个字段,补到边框 1.15mm,但仍未找到面板厂商
- 面板厂商 / 发光材料主要出现在新闻稿;公开检索受限时可在「补充参考资料」粘贴对应链接后再跑区块 AI,或人工填写
- `pnpm typecheck`、`pnpm build` 通过;详情页 accent 为 `#E8E8E6`,黑暗森林色块显示为近黑
---
## 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 与文档标题。