# 酒云网商品搜索与统计参考文档

## 目录
- [商品搜索](#商品搜索)
  - [查询概览](#查询概览)
  - [查询参数](#查询参数)
  - [筛选条件](#筛选条件)
  - [返回数据](#返回数据)
  - [搜索示例](#搜索示例)
- [统计摘要（当日新上）](#统计摘要当日新上)
  - [统计概览](#统计概览)
  - [返回数据](#返回数据-1)
  - [统计示例](#统计示例)
- [统计商品（当日新上）](#统计商品当日新上)
  - [统计商品概览](#统计商品概览)
  - [查询参数](#查询参数-1)
  - [返回数据](#返回数据-2)
  - [统计商品示例](#统计商品示例)
- [注意事项](#注意事项)

---

## 商品搜索

### 查询概览
- **数据来源**: 酒云网（vinehoo.com）专业葡萄酒商品数据库
- **查询方式**: 支持多种条件组合查询
- **数据范围**: 覆盖全球主要葡萄酒产区的丰富酒品

### 查询参数

| 参数名 | 类型 | 必需 | 说明 | 示例 |
|--------|------|------|------|------|
| page | int | 是 | 页码，从1开始 | 1 |
| limit | int | 否 | 每页数量，默认10 | 10 |
| keywords | string | 否 | 搜索关键词（如产区、葡萄品种、酒庄名） | "香槟" |
| price_gte | int/float | 否 | 最低价格（>=） | 100 |
| price_lte | int/float | 否 | 最高价格（<=） | 500 |

### 筛选条件

#### 产地国家（country）
- **类型**: array of string
- **说明**: 支持筛选多个产地国家
- **支持的国家**:
  - 中国、法国、意大利、澳大利亚、葡萄牙、德国、西班牙
  - 新西兰、智利、阿根廷、美国、奥地利、南非、日本
- **示例**:
  ```bash
  # 筛选法国和意大利产地的葡萄酒
  --countries 法国 意大利
  ```

#### 酒类类型（product_category）
- **类型**: array of string
- **说明**: 仅支持筛选一种酒类类型
- **支持的类型**:
  - 红葡萄酒、白葡萄酒、起泡酒、香槟、甜酒、烈酒
  - 白酒/黄酒、清酒、果酒/米酒、食品/生鲜、饮料
  - 自然酒、加强酒、桃红葡萄酒、其他酒、酒具
- **示例**:
  ```bash
  # 筛选白葡萄酒
  --category "白葡萄酒"
  ```

### 返回数据

#### 数据结构
查询结果包含以下信息：
- **total**: 符合条件的商品总数
- **list**: 商品列表

#### 商品信息字段
| 字段 | 说明 |
|------|------|
| url | 商品详情页链接（用户点击链接可查看完整详情或直接购买） |
| title | 商品标题（包含酒款名称、特色描述） |
| brief | 商品简介（包含葡萄品种、产区特点、工艺特色等） |
| price | 商品价格 |
| country | 产地国家 |
| regions | 产区信息（如勃艮第、波尔多、香槟产区等） |
| product_keyword | 商品关键词标签（如精品进阶、推荐、性价比之选等） |

### 搜索示例

#### 示例1：关键词搜索
```bash
# 搜索香槟类商品
node scripts/search_products.js --page 1 --limit 10 --keywords "香槟"
```

#### 示例2：价格区间筛选
```bash
# 查找100-500元价格区间的葡萄酒
node scripts/search_products.js --page 1 --price-gte 100 --price-lte 500
```

#### 示例3：产地筛选
```bash
# 筛选法国和意大利产地的葡萄酒
node scripts/search_products.js --page 1 --limit 10 --countries 法国 意大利
```

#### 示例4：酒类类型筛选
```bash
# 筛选白葡萄酒
node scripts/search_products.js --page 1 --limit 10 --category "白葡萄酒"
```

#### 示例5：组合搜索
```bash
# 搜索法国勃艮第产区的红葡萄酒，价格300-800元
node scripts/search_products.js \
  --page 1 \
  --limit 20 \
  --keywords "勃艮第" \
  --price-gte 300 \
  --price-lte 800 \
  --countries 法国 \
  --category "红葡萄酒"
```

#### 示例6：纯分页查询
```bash
# 获取前50条商品数据
node scripts/search_products.js --page 1 --limit 50
```

---

## 统计摘要（当日新上）

### 统计概览
- **数据来源**: 酒云网（vinehoo.com）当日新上商品统计数据
- **统计方式**: 无需参数，返回当日新上商品的多维度统计
- **统计维度**: 日期、总数、国家分布、类型分布、酒庄分布、产区分布
- **重要**: 统计数据仅包含当日新上的商品，不包含历史商品

### 返回数据

#### 数据结构
统计结果包含以下信息：
- **date**: 统计日期（格式：YYYY-MM-DD，表示当日）
- **total**: 当日新上商品总数
- **country_stats**: 按国家统计（国家名称、数量）
- **category_stats**: 按类型统计（类型名称、数量）
- **winery_stats**: 按酒庄统计（酒庄名称、数量）
- **region_stats**: 按产区统计（产区名称、数量）

#### 统计字段说明

**country_stats（国家统计）**
| 字段 | 说明 |
|------|------|
| name | 国家名称 |
| count | 当日该国家新上的商品数量 |

**category_stats（类型统计）**
| 字段 | 说明 |
|------|------|
| name | 酒类类型名称 |
| count | 当日该类型新上的商品数量 |

**winery_stats（酒庄统计）**
| 字段 | 说明 |
|------|------|
| name | 酒庄名称 |
| count | 当日该酒庄新上的商品数量 |

**region_stats（产区统计）**
| 字段 | 说明 |
|------|------|
| name | 产区名称 |
| count | 当日该产区新上的商品数量 |

### 统计示例

#### 示例1：获取当日新上商品统计
```bash
node scripts/statistics_summary.js
```

**返回示例**：
```json
{
  "error_code": 0,
  "error_msg": "ok",
  "data": {
    "date": "2026-03-12",
    "total": 20,
    "country_stats": [
      {"name": "法国", "count": 7},
      {"name": "意大利", "count": 3},
      {"name": "澳大利亚", "count": 3}
    ],
    "category_stats": [
      {"name": "干红葡萄酒", "count": 12},
      {"name": "干白葡萄酒", "count": 3},
      {"name": "威士忌", "count": 1}
    ],
    "winery_stats": [
      {"name": "天瑞酒庄", "count": 2},
      {"name": "泽维尔酒庄", "count": 2}
    ],
    "region_stats": [
      {"name": "罗讷河谷/隆河谷产区", "count": 3},
      {"name": "猎人谷产区", "count": 2}
    ]
  }
}
```

---

## 统计商品（当日新上）

### 统计商品概览
- **数据来源**: 酒云网（vinehoo.com）当日新上商品数据库
- **查询方式**: 根据统计维度（国家、类型、产区、酒庄）筛选当日新上的具体商品
- **使用场景**: 查看统计摘要后，根据某个维度查看当日新上的具体商品列表
- **返回格式**: 与商品搜索脚本的返回格式完全相同
- **重要**: 查询结果仅包含当日新上的商品，不包含历史商品

### 查询参数

| 参数名 | 类型 | 必需 | 说明 | 示例 |
|--------|------|------|------|------|
| page | int | 否 | 页码，从1开始，默认1 | 1 |
| limit | int | 否 | 每页数量，默认10 | 10 |
| country | string | 否 | 国家名称 | "意大利" |
| category | string | 否 | 酒类类型名称 | "干红葡萄酒" |
| region | string | 否 | 产区名称 | "瓦波利切拉产区" |
| winery | string | 否 | 酒庄名称 | "佩高酒庄" |

**说明**：
- 所有参数均为可选，可以单独使用或组合使用
- 多个参数组合时为 AND 关系（同时满足所有条件）
- 查询结果仅包含当日新上的商品

### 返回数据

#### 数据结构
查询结果包含以下信息：
- **total**: 符合条件的当日新上商品总数
- **list**: 当日新上商品列表

#### 商品信息字段
与商品搜索脚本的返回格式完全相同：
| 字段 | 说明 |
|------|------|
| url | 商品详情页链接（用户点击链接可查看完整详情或直接购买） |
| title | 商品标题（包含酒款名称、特色描述） |
| brief | 商品简介（包含葡萄品种、产区特点、工艺特色等） |
| price | 商品价格 |
| country | 产地国家 |
| regions | 产区信息（如勃艮第、波尔多、香槟产区等） |
| product_keyword | 商品关键词标签（如精品进阶、推荐、性价比之选等） |

### 统计商品示例

#### 示例1：查询当日新上商品中某个国家的商品
```bash
# 查询当日新上的意大利商品
node scripts/statistics_products.js --country "意大利"
```

#### 示例2：查询当日新上商品中某个类型的商品
```bash
# 查询当日新上的干红葡萄酒
node scripts/statistics_products.js --category "干红葡萄酒"
```

#### 示例3：查询当日新上商品中某个产区的商品
```bash
# 查询当日新上的瓦波利切拉产区商品
node scripts/statistics_products.js --region "瓦波利切拉产区"
```

#### 示例4：查询当日新上商品中某个酒庄的商品
```bash
# 查询当日新上的佩高酒庄商品
node scripts/statistics_products.js --winery "佩高酒庄"
```

#### 示例5：组合查询当日新上商品（国家+类型）
```bash
# 查询当日新上的意大利干红葡萄酒
node scripts/statistics_products.js --country "意大利" --category "干红葡萄酒"
```

#### 示例6：组合查询当日新上商品（产区+酒庄）
```bash
# 查询当日新上的瓦波利切拉产区佩高酒庄商品
node scripts/statistics_products.js --region "瓦波利切拉产区" --winery "佩高酒庄"
```

#### 示例7：分页查询当日新上商品
```bash
# 查询当日新上前20个商品
node scripts/statistics_products.js --limit 20
```

---

## 注意事项

### 商品搜索注意事项
1. `page` 参数为必需参数，必须从1开始
2. 价格参数支持整数和浮点数
3. `countries` 参数支持多个国家，使用空格分隔
4. `category` 参数仅支持一个酒类类型
5. `total` 字段表示符合条件的商品总数，可用于计算总页数
6. `regions` 和 `product_keyword` 可能为空数组
7. 所有参数组合均为可选，可以灵活组合使用
8. 传入不支持的产地国家或酒类类型会返回错误提示
9. 建议结合关键词搜索和筛选条件，提高查询精准度
10. **重要**：每次展示商品结果时，必须包含商品详情页链接（url字段），用户点击链接即可查看完整详情或直接购买

### 用户引导注意事项
11. **用户引导**：当用户对葡萄酒了解不多或搜索条件很少时，主动询问并引导用户补充预算、产地、类型等关键信息，提供更好的推荐效果

### 统计摘要注意事项
12. 统计数据为当日新上商品的实时统计，反映最新上架情况
13. 各统计维度（国家、类型、酒庄、产区）可根据数量进行排序分析
14. 建议结合统计数据为用户提供当日推荐和趋势分析
15. 如当日无新上商品，统计数据可能为空或 total 为 0
16. **重要**：统计数据仅包含当日新上的商品，不包含历史商品
17. **统计数据说明**：统计信息中各维度（国家、类型、酒庄、产区）的数量加起来可能与总数不一致，这是正常情况。原因包括：
    - 有些商品可能未绑定产区信息
    - 有些商品可能未绑定酒庄信息
    - 不同维度的统计是独立计算的
    - **仅在用户主动询问"为什么数据对不上"时才解释此原因，否则不主动提及**

### 统计商品注意事项
18. 统计商品脚本用于查询当日新上的具体商品，与商品搜索脚本的返回格式完全相同
19. 统计商品脚本的所有参数均为可选，可以灵活组合使用
20. 统计商品脚本的筛选条件基于统计摘要中的维度，参数值应与统计摘要中的名称完全一致
21. **重要**：统计商品脚本的查询结果仅包含当日新上的商品，不包含历史商品
22. 建议先查看统计摘要，了解当日上新概况，然后根据感兴趣的维度查询当日新上的具体商品