Skip to content

UPDATE_DATA.md

Latest commit

 

History

History
305 lines (213 loc) · 6.05 KB

UPDATE_DATA.md

File metadata and controls

305 lines (213 loc) · 6.05 KB
Raw

📝 更新榜单数据 - 使用指南

🎯 工作流程

编辑 Google Sheets → 运行同步脚本 → 提交到 Git → 部署

📋 步骤说明

步骤 1：编辑 Google Sheets 数据

打开 Google Sheets 文档：

https://docs.google.com/spreadsheets/d/1BXwuRvEldz0ceifKjLOdo5zPTvqelVd0_FwjlXRV9HQ/edit

可用的工作表：

  • jump-starter - 汽车应急启动电源
  • tire-inflator - 车载充气泵
  • dash-cam - 行车记录仪
  • air-duster - 压缩空气除尘器

编辑任意产品信息，保存即可。

步骤 2：运行同步脚本

在项目根目录运行：

node scripts/sync-sheets.js

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 Testing Build Plugin Sync (Local)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 Connected to Google Sheets
📋 Sheet ID: 1BXwuRvEldz0ceifKjLO...

📥 Syncing jump-starter...
   ✅ 10 products synced → jump-starter.json
📥 Syncing tire-inflator...
   ✅ 10 products synced → tire-inflator.json
📥 Syncing dash-cam...
   ✅ 10 products synced → dash-cam.json
📥 Syncing air-duster...
   ✅ 1 products synced → air-duster.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Sync Complete: 31 products across 4 categories
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📂 Generated files:
   jump-starter.json (9.38 KB)
   tire-inflator.json (8.73 KB)
   dash-cam.json (9.00 KB)
   air-duster.json (0.71 KB)

脚本会：

  1. 连接到 Google Sheets API
  2. 读取所有类目的数据
  3. 转换为 JSON 格式
  4. 写入 frontend/public/data/*.json

步骤 3：本地预览（可选）

启动开发服务器查看效果：

cd frontend
npm run dev

访问：http://localhost:5173/jump-starter

步骤 4：提交到 Git

# 查看变更
git status

# 添加 JSON 文件
git add frontend/public/data/*.json

# 提交
git commit -m "Update product data from Google Sheets"

# 推送到远程仓库
git push

步骤 5：部署

根据您的部署方式：

Kubernetes：

# 构建镜像
docker build -t bestproductviews:latest .

# 推送到镜像仓库
docker push your-registry/bestproductviews:latest

# 更新 K8s 部署
kubectl rollout restart deployment/bestproductviews

其他静态托管：

  • Vercel / Netlify / CloudFlare Pages：推送到 Git 后自动部署
  • 传统服务器：上传 frontend/dist/ 目录

🔧 环境配置

首次使用前需要配置环境变量

创建 .env 文件：

cp .env.example .env

编辑 .env 并填入：

GOOGLE_CREDENTIALS={"type":"service_account","project_id":"..."}
GOOGLE_SHEET_ID=1BXwuRvEldz0ceifKjLOdo5zPTvqelVd0_FwjlXRV9HQ

⚡ 快捷命令

将这个命令添加到 package.json：

{
  "scripts": {
    "sync": "node scripts/sync-sheets.js"
  }
}

然后可以直接运行：

npm run sync

📊 数据格式说明

Google Sheets 列结构

列 字段 说明
A ID/Rank 排名序号
B Brand 品牌名称
C Title 产品标题
D ASIN Amazon 产品 ID
E Image URL 产品图片链接
F Rating 评分 (1-5)
G Reviews 评论数量
H Price 价格（数字，不带 $）
I Expert Score 专家评分
J Features 功能特点（分号分隔）
K Pros 优点（分号分隔）
L Cons 缺点（分号分隔）

Features 示例：

24000mAh battery;4000A peak current;65W USB-C fast charging;IP64 protection

🛠️ 故障排除

问题 1：环境变量未配置

错误：

❌ Missing GOOGLE_CREDENTIALS environment variable

解决： 确保项目根目录有 .env 文件，并包含正确的凭证。

问题 2：Google Sheets 权限错误

错误：

Error: The caller does not have permission

解决：

  1. 打开 Google Sheets
  2. 点击右上角 "Share"
  3. 添加服务账号邮箱：sheets-reader@bestproductviews.iam.gserviceaccount.com
  4. 权限设置为 "Viewer"

问题 3：产品数量为 0

原因： 数据行不满足最低要求（ID、Brand、Title 必须存在）

解决： 检查 Google Sheets 确保每行至少有：

  • A 列：ID（数字）
  • B 列：Brand（非空）
  • C 列：Title（非空）

💡 最佳实践

1. 批量更新

如果要更新多个产品，建议：

  1. 在 Google Sheets 中完成所有编辑
  2. 运行一次同步脚本
  3. 一次性提交所有变更

2. 备份数据

在重大更新前，备份现有 JSON 文件：

cp -r frontend/public/data frontend/public/data.backup

3. 提交信息规范

使用清晰的提交信息：

git commit -m "Update jump-starter rankings - 2025-12"
git commit -m "Add new tire inflator products"
git commit -m "Update product prices and ratings"

📈 性能说明

加载速度

  • 静态 JSON 文件：< 50ms ⚡
  • 所有数据在部署时打包
  • 无需运行时 API 调用
  • CDN 全球分发（如果使用 CDN）

更新频率

  • 手动控制，按需更新
  • 推荐：每周或每月更新一次
  • 紧急情况：随时更新并重新部署

🚀 完整示例

# 1. 编辑 Google Sheets（在浏览器中）

# 2. 同步数据
node scripts/sync-sheets.js

# 3. 本地测试
cd frontend && npm run dev

# 4. 提交变更
git add frontend/public/data/*.json
git commit -m "Update product data - $(date +%Y-%m-%d)"
git push

# 5. 部署（根据您的环境）
# - K8s: kubectl rollout restart deployment/bestproductviews
# - 静态托管: 自动部署

更新时间： 2025-12-17 方案类型： 手动同步 + Git 版本控制 优势： 简单、可控、快速、适合任何部署环境