Files
2026-11-06 15:07:02 +08:00

208 lines
19 KiB
Markdown
Raw Permalink 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
公开硬件规格库:收录手机、芯片等设备的详细参数,支持横向对比。设计文档见 [DESIGN.md](./DESIGN.md)。
## 技术栈
Astro 7(SSR / Node adapter)+ Tailwind CSS 4 + shadcn/ui(React islands)+ SQLite(`node:sqlite`,无原生依赖)+ sharp(OG 图生成)
## 本地开发
```bash
pnpm install
cp .env.example .env # Windows: Copy-Item .env.example .env
pnpm db:seed # 建表 + 写入种子数据(Xiaomi 14 / REDMI K90 Pro Max / OPPO Find X10 Pro Max / 骁龙 8 Gen 3)
pnpm dev # http://localhost:4321
pnpm typecheck # tsc --noEmit
```
组件自检页:`/poc`(验证 Button / Card / Dialog 可用,M0 验收后可删)。
## 编辑后台(M2)
访问 `/admin`,输入 `.env` 中的 `ADMIN_PASSWORD` 登录。登录态是 7 天有效的 HttpOnly 签名 cookie;连续 3 次密码错误会按 IP 限速 1 分钟。
- 登录后是仪表盘:设备/芯片列表、最近修订记录、新增入口。
- 设备编辑:`/admin/devices/[slug]`,新增用 `/admin/devices/new`。新增页只需输入 slug,AI 会多源检索生成初稿并跳转到详细编辑;表单覆盖手机全部规格分组,多摄逐颗编辑,扬声器单元可增删;字段来源徽章与“已核实”勾选会保留。
- 芯片编辑:`/admin/chips/[slug]`,基础信息、GPU/NPU/内存等结构化字段,CPU 核心簇、跑分、扩展字段用 JSON 编辑。
- 封面图上传:`POST /api/upload`,仅 jpg / png / webp / avif,单张 ≤ 10MB;M2 存原图,不做压缩转码。
- 每次保存写入 `revisions` 快照(与主表同一事务),编辑页底部展示最近 10 条。
写接口(`/api/devices`、`/api/chips`、`/api/upload`)都要求登录态,并校验 `Origin` 与 `Host` / `X-Forwarded-Host` 同源;读页面完全公开。
> 生产环境务必替换 `ADMIN_PASSWORD` 与 `SESSION_SECRET`,并在 HTTPS 下设置 `COOKIE_SECURE=1`。
> M2 只实现本地图片驱动;S3 驱动仍是接口占位(M4 或需要时再接)。
## AI 补全(M3)
编辑页的「AI 补全」会按当前品牌 + 型号调用 `POST /api/ai/lookup`,返回带置信度的扁平字段。
- 新增页「AI 快速创建」只需输入 slug:服务端推断品牌 / 型号,多源检索后写入初稿并跳转详细编辑页(`POST /api/ai/prospect`)。
- 未配置 Tavily 时使用 Bing / Baidu / DuckDuckGo 公开检索 + ZOL / GSMArena / Kalvo 站内直查,并只抓取白名单站点:厂商官网、ZOL、PConline、Kalvo、GSMArena、IT之家、快科技、Notebookcheck 等;按域名限流并做多源交叉验证。
- 详细编辑页每个规格分区标题旁有「区块 AI」(`POST /api/ai/section`),一次检索该区块的全部字段(如屏幕、内存与存储、电池、连接),结果可勾选后应用;比单字段补全多了区块上下文,更容易拿到面板厂商、发光材料等分散信息。
- 详细编辑页每个规格字段旁有 `AI` 按钮(`POST /api/ai/field`),只针对该字段重新检索;适合官网不公开的扬声器单元型号、尺寸、马达型号、体积等。字段旁的「补充参考资料」文本也会参与该字段检索。
- 「补充参考资料」支持多行 URL:每行一个官网 / ZOL / PConline 链接,服务端会抓取正文并与公开检索结果合并(按 URL 去重);缓存键包含 URL 与补充文本的摘要,二次补全不会命中旧结果。
- 面向中国大陆:提示词要求简体中文与国行人民币价格,`pricing` 会过滤 EUR / USD / GBP 与海外版本;`officialUrl` 从已抓取来源中自动选具体产品页,避免写成品牌首页或系列列表。
- 字段级补全会复用整机补全已抓取的来源(如 ZOL / PConline),公开检索临时失败时仍能继续;确实没有公开数据时按钮显示 `无` 并标注「无公开数据」,与真正的检索失败区分。
- 公开检索按型号做来源筛选;纯数字型号(如 `OnePlus 16`)改用品牌词排除 iPhone / Meizu 16 等同名干扰。
- 新增大模型输出截断保护:JSON 被截断时保留已完整的字段对象,避免整批结果丢失。
配置 `.env`:
```bash
AI_BASE_URL=https://api.deepseek.com/v1 # 任何 OpenAI 兼容接口
AI_API_KEY=
AI_MODEL=deepseek-chat
SEARCH_API_KEY= # 可选:Tavily 兼容搜索
SEARCH_BASE_URL=https://api.tavily.com
```
- 有搜索 key 时:优先走 Tavily,把标题 / URL / 摘要塞进提示词;抓取失败的来源会被跳过。
- 没有搜索 key 时:使用 Bing / Baidu / DuckDuckGo 公开检索 + ZOL / GSMArena / Kalvo 站内直查,只抓取白名单站点(官网、ZOL、PConline、Kalvo、GSMArena 等),同一域名最多 2 条;页面正文按"规格密度"取窗(优先参数表而非页头导航);检索完全失败才降级为模型知识,并将 `high` 降为 `medium`。资料未覆盖但属于公开常识的字段,模型可给 low 置信度并注明「模型知识,待核实」。
- 字段级与区块级补全走**全网自由检索**:不限白名单站点(评测、百科、论坛等均可作依据,白名单站仍优先排序),接受的置信度下限为 low;整机补全仍保持白名单交叉验证。
- 拆机视频通道:三处检索都会附加 `site:bilibili.com 机型 拆解` 查询,B 站视频页走官方接口获取标题 + 简介;在 `.env` 配置 `BILIBILI_SESSDATA`(B 站登录态)后还会拉取**字幕全文**——马达型号、扬声器单元等官网不公开的细节主要在拆机视频的口播里(如微机分等拆解 UP 主)。未配置 SESSDATA 时字幕接口返回空,来源价值有限。
- 编辑页「AI 补全」下方提供可选的「补充参考资料」:可粘贴官网参数文本并填写官方链接。最新机型未进模型知识库时,用它可显著提高字段覆盖;补充文本会参与缓存键,避免与无资料结果串缓存。
- 提示词覆盖全部规格分组与设备补充字段(手机特点 / 影像功能 / 跑分 / 售价 / 官网),摄像头逐颗、扬声器最多 5 个单元;`display.refreshNote` 用于表达“185Hz 仅部分游戏场景生效”这类附加条件。
- 只接受白名单路径(`src/lib/spec-fields.ts`),值类型按路径定义强转;摄像头位置只允许 `wide/ultrawide/tele/periscope/macro/depth/mono/color/front`。
- 预览显示「当前值 → AI 值」、置信度徽章与来源,可逐项勾选后应用。
- 应用后 `low` 字段阻塞保存;底部提供「确认全部 low」「清空全部 low」,来源区可「全部接受 high」。
- 结果按 `phone|品牌|型号`(有补充资料时追加文本哈希)缓存到 `ai_cache`;勾选「忽略缓存」可强制刷新。字段级检索按 `field|品牌|型号|路径` 单独缓存。
- AI 关键配置缺失时接口返回 503,页面会直接显示原因;AI key 只在服务端读取。
> M3 验收曾使用本地 mock;本轮已用 DeepSeek 实测:多源检索 OPPO Find X10 Pro Max 时抓取官网 / ZOL / PConline / Kalvo 共 6 个来源,返回 100 个字段;来源不足的机型(如 OnePlus 15)只返回少量字段,说明覆盖度取决于公开资料质量。
## 对比(M4)
设备列表和详情页的「加入对比」会把机型放进底部固定托盘(最多 4 款,选择保存在 localStorage),托盘里可直接移除或点「开始对比」进入结果页。直接访问 `/compare` 时是搜索 + 品牌筛选 + 分页的设备选择器,点「+ 加入」加入当前选择;已选 2 款以上时可从顶部「查看对比」进入结果。
- 差异项高亮并显示圆点,缺失值显示 `—` 并置灰。
- 「只看差异」用 `?diff=1` 切换,只保留有差异的行。
- 分组默认展开,可点击分组标题折叠;首列字段名在横向滚动时保持粘性。
- 重量、屏幕尺寸、亮度、刷新率、电池容量、充电功率等数值字段带相对条形图。
## 导出与导入(M4)
- `GET /api/export`:公开下载全量 JSON,`formatVersion: 1`,包含 `devices` 与 `chips`。
- `/admin/import`:登录后粘贴或选择 JSON 导入;按 slug upsert,已存在的 slug 会被覆盖,未出现在文件里的数据不会删除。
- 导入会先对整批数据跑 zod 校验,只要有一条不合法就整批拒绝,不会写入半份数据。
- 限制:单次最多 5000 条、请求体 ≤ 20MB。
> JSON 不包含图片。迁移或恢复时请同时拷贝 `data/app.db`(或备份)与 `data/uploads/`。
### 从 phonerecommend.top 同步
```bash
pnpm sync:phonerecommend # 只产出 data/import/phonerecommend-<时间>.json
pnpm sync:phonerecommend -- --write # 同时按 slug upsert 到 data/app.db
pnpm sync:phonerecommend -- --write --images # 并下载封面 / 相册到 data/uploads
pnpm sync:phonerecommend -- --brand 华为 --brand 小米
```
- 源站列表接口 `/api/phones?limit=100&page=N` 已包含完整规格组,需要带浏览器 UA 与 `Referer`。
- 品牌转英文规范名,中文型号转拼音 slug;输出结构与本项目 `formatVersion: 1` 一致。
- 源站个别记录型号只写了品牌(如 `OPPO / OPPO`),会回退到 `product_model` 并去掉品牌前缀;同名同发布时间的重复机型会被跳过。
- 源站缺少的结构化字段(传感器型号、马达体积、无线充电等)会留空,可继续用字段级 AI 补全。
- 屏幕亮度会区分「典型亮度 / 局部峰值亮度 / 全局峰值亮度」,不再按数字出现顺序猜测;源站 `navigation` 等文本中混入的商城推荐内容会被截断。
- `--images` 会下载封面 / 相册并转成 WebP,落到 `data/uploads/devices/<slug>/`,页面通过 `/uploads/devices/<slug>/...` 读取;下载后会清理本地不存在的图片引用。slug 冲突以源站为准覆盖本地记录,执行前建议先 `pnpm backup`。
### 从 phonerecommend.top 同步处理器
```bash
pnpm sync:processors # 只产出 data/import/processors-<时间>.json
pnpm sync:processors -- --write # 写入 chips,并按芯片名回填设备的 SoC 引用
pnpm sync:processors -- --limit 10 # 只处理前 10 颗
```
- 列表接口 `/api/processors?limit=100&page=N` 共 224 条,按 `key` 去重后为 203 颗;详情接口补充跑分、别名、来源与官方规格表。
- `chips.detail` 新增 `overview / cpuBlock / gpuBlock / npuBlock / cameraBlock / displayBlock / connectivityBlock / benchmarkInfo / traits / caveats / sourceUrls / specGroups`;芯片列表按档位分与年份排序,详情页展示 CPU 簇、跑分、内存/影像/连接与可折叠的完整规格。
- `--write` 会按 `specs.platform.chipset` 与芯片名称 / 别名匹配,回填 `devices.chipRefs.soc`,芯片详情页可直接列出搭载机型。
- 源站对高频请求返回 429 / 403,脚本已内置退避重试与低并发;个别旧处理器详情失败时仍保留列表字段。
### 从酷安补充 / 覆盖手机参数
```bash
pnpm sync:coolapk # 只产出 data/import/coolapk-<时间>.json
pnpm sync:coolapk -- --write # 合并进 data/app.db
pnpm sync:coolapk -- --limit 10 # 只处理前 10 款
pnpm sync:coolapk -- --slug oneplus-16 # 只处理指定 slug(含自动创建的新机型)
```
- 先分页读取酷安机型目录(缓存在 `data/cache/coolapk-products.json`,当前 1505 条,去重后 1504 款),按品牌别名 + 型号匹配本地设备;名称拼接未命中时会再按「推断品牌 + 型号」精确匹配一次。
- 本地没有的酷安机型也会自动创建:从产品名前缀推断品牌与型号,用拼音生成 slug,读取「发布时间」写入上市 / 发布与状态,并生成列表摘要;封面与相册留空,后续可继续补图。
- 读取每个机型的版本列表,取基础版本参与每 4 台一组的配置对比,解析完整参数表,再映射到机身、屏幕、平台、内存、电池、网络、马达、扬声器、传感器与摄像头等字段。
- **覆盖策略**:酷安为权威源,但不让低信息度内容覆盖高信息度内容——先比较数字、单位与文本完整度,酷安更完整才覆盖;两边数值明显冲突时视为不一致,采用酷安。分辨率(防止「1.5K」覆盖精确像素)、摄像头像素、长焦焦距、传感器型号、视频规格都有单独的保护规则;频段与传感器清单使用并集。
- `specs.coolapk` 只保留产品 ID、配置 ID、价格、同步时间与酷安评分(总评 / 机主 / 续航 / 影像 / 性能 / 屏幕 / 外观质感 / 性价比);原始参数表不再入库,详情页标题下方直接展示评分与同步日期。
- 执行 `--write` 前建议先 `pnpm backup`。
## 动效、OG 图与打印(M5)
- **页面动效**:Astro `<ClientRouter />` + 主内容淡入;列表网格用 CSS `reveal-grid` 做轻量渐入与 40ms 级联。`prefers-reduced-motion: reduce` 时全部关闭,未引入 GSAP / Lenis。
- **黑白主题**:右上角按钮切换日间 / 夜间主题;首次访问跟随系统,之后用 `localStorage` 记住,跨页导航和刷新都保持。打印时强制浅色。
- **详情页参数 hover**:关键参数卡、影像卡和规格表行在鼠标悬停时高亮背景并把字段名切为强调色,便于定位当前参数;顶部参数卡可点击跳转到对应详细分组。
- **OG 图**:`GET /og/[slug].png` 动态生成 1200×630 PNG,设备页自动使用 `/og/<slug>.png`,其他页面默认 `/og/site.png`;详情页同时输出 `og:*`、`twitter:card`、canonical。
- **打印**:设备详情页有「打印 / 保存 PDF」按钮;`@media print` 切换浅色配色、隐藏导航/页脚/按钮、取消 sticky 与横向滚动,并尽量避免表格跨页断行。
- **字体依赖**:OG 图文字只使用 Latin 字符,避免容器缺中文字体时出现方框。`sharp` 通过系统字体渲染,需要 `fontconfig` + DejaVu:
- 标准 Dockerfile 已安装 `fontconfig` / `ttf-dejavu`。
- 宿主构建 + `node:24-slim` 挂载方式会把宿主机的 `/usr/share/fonts` 与 `/etc/fonts` 只读挂进容器。
## 详情页参数展示
- 标题下方是「配色 + 初始售价」展示带:配色用圆形色块 + 中文色名,售价按版本拆成卡片并高亮起售价;背景渐变取自首个配色,作为该机型的页面色彩主题。色块优先使用 `body.colorHexes`(与 `body.colors` 顺序一致,AI / 人工维护);缺失时按中文色名推断(星光→银白、森林→绿、火星→橙等),未知名称用稳定哈希色相。
- 顶部参数卡分多排展示:SoC、屏幕、电池、主摄、超广角、长焦、影像场景、内存、存储、充电、无线充电、系统、扬声器、马达、Wi-Fi、USB、指纹、重量、防护。卡片高度统一,数值加大加粗,长文本两行截断;电池、充电、Wi-Fi、相机卡使用短值 + 关键副标题,避免整段参数无法阅读。
- 卡片上方提供分组快捷导航;详细参数按“屏幕与外观 → 性能 → 影像 → 电池与充电 → 音频与振动 → 连接与网络 → 传感器 → 系统与更新 → 发布与补充”排序,每节带编号与分组小标题。
- 性能节合并 SoC 卡片、平台、内存与存储及跑分;未关联芯片库时显示芯片名与“芯片库暂未收录”,避免空白区块。影像节按后置 / 前置分组,镜头头衔使用中文位置(主摄 / 超广角 / 长焦 / 潜望式长焦 / 色彩镜头等),并显示传感器营销名。
- 屏幕补充面板厂商(如 TCL 华星)与技术代号(如 C8),并展示挖孔形态、刷新附加说明(如“最高 185Hz 仅部分游戏场景生效”)、瞬时触控采样率、色深、色域、像素密度、OLED 等效 PPI、屏占比、边框、16:9 等效尺寸、屏幕特性与其它说明。
- 扬声器按 `speakers.units[]` 任意数量拆行,支持上 / 下 / 中置 / 第三单元等自定义标识,不再限定双扬声器;每单元给出型号、尺寸与功率。马达给出型号、尺寸与实际体积;USB 给出型号、实际速率与视频输出;系统列出出厂版本、当前版本及更新时间线。
- 前后摄新增传感器营销名(如“光影猎人 900”)与视场角;影像功能、手机特点、设备跑分、官网、备注与耳机接口等补充信息单独展示;初始售价在顶部展示带中呈现。
- 连接分组内,“移动网络频段”和“卫星通信频段”在 hover / 聚焦时弹出频段面板;卫星面板同时显示运营商(天通 / 北斗等)。
- 字段级置信度只标记 `low`:低置信字段旁显示 `low` 徽章,hover / 聚焦显示字段名、路径、核实状态与来源;`high` 与 `medium` 不做常驻标记。页面底部不再展示字段级来源清单,避免信息过载。
## 部署
### 小内存服务器(当前 ECS 方案)
ECS 只有 1.6G 内存,Docker 多阶段构建会触发 `kcompactd` 长时间阻塞(load 飙到 40+)。因此改为「宿主构建 + 容器挂载」:
```bash
bash scripts/deploy.sh
```
脚本依次执行:拉代码 → `pnpm install` → `pnpm build` → `docker compose up -d --force-recreate`。容器用 `node:24-slim` 镜像,挂载 `dist` / `node_modules` / `data`,只有 `./data` 需要持久化。
前提:服务器 Node 装在 `/opt/node`(脚本会自动加进 PATH),且已存在 `.env`。
### 普通机器 / CI
`docker compose build && docker compose up -d` 仍可用仓库里的 `Dockerfile` 构建单镜像,不需要挂载。
## 运维
```bash
pnpm backup # VACUUM INTO 快照 + 打包 uploads 到 backups/<时间戳>/
pnpm db:seed # 重跑种子数据(幂等,按 slug upsert)
pnpm typecheck # 类型检查
```
## 目录
```
src/lib/schema/ zod 数据模型(phone / soc / FieldMeta)
src/lib/db.ts SQLite 连接 + 迁移
src/lib/repo.ts 唯一数据出入口(含修订快照)
src/lib/storage.ts 图片存储驱动(local / s3 接口)
src/lib/auth.ts 登录、签名 cookie、限速、写接口守卫
src/lib/env.ts 运行时读取 .env(standalone / 脚本共用)
src/lib/spec-fields.ts 手机字段注册表 + 路径读写工具(表单 / AI / 对比共用)
src/lib/compare.ts 对比分组、差异判定与数值提取
src/lib/og.ts OG 卡片 SVG -> PNG(sharp)
src/lib/ai/ 搜索、提示词、模型调用、字段校验、置信度与合并规则
src/middleware.ts /admin/** 登录拦截
src/pages/admin/ 登录/仪表盘、设备与芯片编辑页、导入页
src/components/admin/ 编辑表单(React islands,含 AI 差异预览、导入面板)
src/pages/api/ auth / devices / chips / upload / ai / export / import
migrations/ SQL 迁移,按文件名顺序执行
scripts/ seed / backup / sync-phonerecommend / sync-processors / sync-coolapk
```
> 在受限沙箱里 `pnpm dev` 首次 SSR 模块加载可能极慢;可改用 `pnpm build && node dist/server/entry.mjs` 在本地验证生产路径(设置 `HOST` / `PORT` 即可)。