Skip to content

COMPARISON_TABLE_GUIDE.md

Latest commit

 

History

History
306 lines (221 loc) · 7.25 KB

COMPARISON_TABLE_GUIDE.md

File metadata and controls

306 lines (221 loc) · 7.25 KB
Raw

📊 对比表格设置指南

本文档说明如何在 Google Sheets 中设置产品对比表格数据。

🎯 概述

对比表格数据现在可以直接在 Google Sheets 中维护，同步脚本会自动提取并生成到 JSON 文件中。

优势：

  • ✅ 无需手动编辑 JSON 文件
  • ✅ 对比数据与产品数据统一管理
  • ✅ 不同榜单可以有不同的对比字段
  • ✅ 运行 npm run sync 自动更新

📋 Google Sheets 结构

列结构说明

列范围 用途 说明
A-L 主产品数据 所有产品的基本信息
M-Z 对比表格数据 前 5 个产品的对比字段

详细列说明

A-L 列（必需）：

A: ID
B: Brand
C: Title
D: ASIN
E: Image
F: Rating
G: Reviews
H: Price
I: Score
J: Features
K: Pros
L: Cons

M-Z 列（可选，用于对比表格）：

M: 对比字段 1（例如：peakAmps）
N: 对比字段 2（例如：batteryCapacity）
O: 对比字段 3（例如：airCompressor）
... 以此类推

🔧 设置步骤

步骤 1：在第一行添加对比字段表头

在 M1 单元格开始，添加对比字段的名称。

示例（jump-starter）：

M1 N1 O1 P1 Q1 R1
peakAmps batteryCapacity airCompressor fastCharge price score

字段命名规则：

  • ✅ 使用 camelCase（驼峰命名）：peakAmps, batteryCapacity
  • ✅ 或使用有空格的格式：Peak Amps, Battery Capacity
  • ✅ 简洁明了，容易理解
  • ❌ 不要使用特殊字符或下划线

步骤 2：填写前 5 个产品的对比数据

只需填写前 5 个产品（第 2-6 行）的对比字段数据。

示例数据：

ID Brand Title ... peakAmps batteryCapacity airCompressor fastCharge price score
1 WOLFBOX 4000A Jump... ... 4000A 20000mAh 160PSI 65W USB-C $159.99 9.8/10
2 WOLFBOX 4000A Jump... ... 4000A 24000mAh 160PSI 65W USB-C $179.99 9.6/10
3 NOCO Boost Plus... ... 1000A 12000mAh No USB $99.95 9.4/10
4 ... ... ... ... ... ... ... ... ...
5 ... ... ... ... ... ... ... ... ...
6 ... ... ... (留空) (留空) (留空) (留空) (留空) (留空)

⚠️ 重要：

  • 第 6 行及以后的产品不需要填写对比数据
  • 对比表格只显示前 5 个产品

📝 不同榜单的对比字段示例

Jump Starter（汽车应急启动电源）

字段 显示名称 示例值
peakAmps Peak Amps 4000A
batteryCapacity Battery Capacity 20000mAh
airCompressor Air Compressor 160PSI
fastCharge Fast Charge 65W USB-C
price Price $159.99
score Expert Score 9.8/10

Tire Inflator（车载充气泵）

字段 显示名称 示例值
maxPressure Max Pressure 150PSI
inflationSpeed Inflation Speed 3 min
powerSource Power Source DC 12V
portability Portability Cordless
price Price $79.99
score Expert Score 9.5/10

Dash Cam（行车记录仪）

字段 显示名称 示例值
resolution Resolution 4K
viewAngle View Angle 170°
nightVision Night Vision Yes
gSensor G-Sensor Built-in
price Price $129.99
score Expert Score 9.3/10

Car Vacuum（车载吸尘器）

字段 显示名称 示例值
suctionPower Suction Power 6000PA
batteryLife Battery Life 30 min
weight Weight 1.2 lbs
cordless Cordless Yes
price Price $79.99
score Expert Score 9.5/10

🚀 使用流程

完整操作步骤

# 1. 在 Google Sheets 中设置对比字段
#    - 在 M1 开始添加对比字段名称
#    - 填写前 5 个产品的对比数据

# 2. 运行同步脚本
npm run sync

# 3. 查看生成的对比表格
cat frontend/public/data/jump-starter.json | grep -A 20 "comparisonTable"

# 4. 测试前端显示
npm run dev
# 访问 http://localhost:5173/jump-starter

📊 自动提取逻辑

同步脚本会自动：

  1. 读取表头（第 1 行）

    • 从 M 列开始识别所有非空表头
    • 自动生成 specs 数组

  2. 提取数据（第 2-6 行）

    • 提取前 5 个产品的对比字段值
    • 生成 products 数组

  3. 格式化标签

    • peakAmps → Peak Amps
    • batteryCapacity → Battery Capacity
    • 已有空格的保持原样

  4. 生成 JSON 结构

    {
  "comparisonTable": {
    "title": "Quick Comparison",
    "specs": [
      { "key": "peakAmps", "label": "Peak Amps" },
      { "key": "batteryCapacity", "label": "Battery Capacity" }
    ],
    "products": [
      {
        "id": 1,
        "peakAmps": "4000A",
        "batteryCapacity": "20000mAh"
      }
    ]
  }
}

✅ 验证对比表格

检查同步日志

运行 npm run sync 后，会显示对比表格信息：

📥 Syncing jump-starter...
   📋 Preserved: buyingGuide (6 sections), FAQs (5 items)
   📊 ComparisonTable: 6 specs, 5 products
   ✅ 10 products synced → jump-starter.json

说明：

  • 6 specs - 有 6 个对比字段
  • 5 products - 有 5 个产品的对比数据

检查 JSON 文件

# 查看对比表格 specs
cat frontend/public/data/jump-starter.json | jq '.comparisonTable.specs'

# 查看对比表格 products
cat frontend/public/data/jump-starter.json | jq '.comparisonTable.products[0]'

🛠️ 故障排除

问题 1：对比表格为空

症状：

📊 ComparisonTable: 0 specs, 0 products

原因： M 列开始没有表头或数据

解决：

  1. 检查第 1 行 M 列及之后是否有表头
  2. 确保表头单元格不为空
  3. 确保至少有一个产品有对比数据

问题 2：对比数据显示为 "N/A"

原因： 对应单元格为空

解决：

  1. 检查 Google Sheets 中对应位置是否有数据
  2. 确保数据格式正确（无多余空格）
  3. 重新运行 npm run sync

问题 3：字段名称显示不正确

原因： 表头命名不规范

解决：

  1. 使用 camelCase：peakAmps 会自动转换为 Peak Amps
  2. 或直接使用格式化名称：Peak Amps
  3. 避免使用特殊字符

💡 最佳实践

1. 字段选择

  • 选择最重要的 4-6 个对比维度
  • 确保字段值简洁明了
  • 使用统一的单位（如都用 PSI 或都用 Bar）

2. 数据填写

  • 保持格式一致性
  • 使用简短的值（如 Yes/No 而不是长句子）
  • 数值带上单位（如 4000A 而不是 4000）

3. 维护更新

  • 新产品上榜时，检查是否需要更新前 5 名的对比数据
  • 定期review对比字段是否还relevant
  • 确保所有榜单都有对比数据

📚 相关文档

创建时间： 2025-12-17 版本： 1.0