# Agent 如何选品

选品系统是一套内部抖音电商选品工具，油猴插件从抖音罗盘实时抓取榜单数据存入数据库，AI 智能体可通过 API 读取全量商品数据（商品信息 + 视频互动数据 + 封面图），结合选品知识自动分析并给出推荐。

---

## 获取 API Token

登录选品系统后，进入右上角 **个人设置 → 个人 API Token**，生成并复制 Token：

```bash
echo "你的真实token字符串" > ~/.xuanpin_token
```

所有接口均需在请求头中加入：

```
Authorization: Bearer 你的真实token字符串
```

curl 示例：

```bash
TOKEN=$(cat ~/.xuanpin_token | tr -d '\n')
curl -H "Authorization: Bearer $TOKEN" ...
```

> Token 为 `personal_token`，持久化存储在数据库中，容器重启后依然有效。

---

## API 基础信息

```
Base URL: http://192.168.8.118:1369/api
```

---

## 数据来源说明

系统包含两套互补数据，联合使用可大幅提升选品准确率：

| 数据 | 接口 | 来源 | 价值 |
|------|------|------|------|
| **选品数据** | `/api/products` | 抖音罗盘公开榜单 | 市场大盘，视频爆款信号，竞争格局 |
| **验证数据** | `/api/sign-products` | 公司包买办实际跑量记录 | 真实签收率、出单量，亲测可跑的品 |

---

## 一、选品数据：榜单商品

```
GET /api/products
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `page` | 页码 | 1 |
| `size` | 每页数量（最大 100） | 50 |
| `sort` | 排序：`score`/`rank`/`pay`/`time` | score |
| `date` | 按入库日期筛选 `YYYY-MM-DD` | — |
| `q` | 搜索商品名或店铺名 | — |

**推荐用法：不加任何筛选，拉全量数据让 AI 自己判断。**

```bash
# 拉最新入库的 100 个商品
TOKEN=$(cat ~/.xuanpin_token | tr -d '\n')
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://192.168.8.118:1369/api/products?size=100&sort=time"
```

### 返回数据结构

每条商品数据如下：

```json
{
  "product_id": "3768070902458220979",
  "name": "草本初色山茶花香氛内衣",
  "shop_name": "草本初色服饰旗舰店",
  "category": "服饰内衣/内衣裤袜",
  "price_bin": "¥70-¥99",
  "price_min": 70,
  "pay_amount": "25.6万",
  "pay_amount_num": 256000,
  "score_total": 7,
  "score_verdict": "强推",
  "rank": 3,
  "newly_on_ranking": false,
  "product_img": "/product_imgs/3768070902458220979.jpg",
  "operator": "王鑫磊",
  "created_at": "2026-04-21 10:30:00",
  "captured_at": "2026-04-21 10:30:00",
  "videos": [
    {
      "video_id": "xxx",
      "title": "视频标题",
      "digg_count": 12500,
      "comment_count": 340,
      "share_count": 89,
      "prev_digg_count": 10200,
      "refreshed_at": "2026-04-21 09:00:00"
    }
  ]
}
```

### 关键字段说明

| 字段 | 含义 | 分析要点 |
|------|------|----------|
| `price_min` | 最低客单价（元） | ≤39.9 最优，≤59.9 可考虑 |
| `pay_amount_num` | 付款金额（数值） | ≥250000 有规模，≥50000 起步量 |
| `score_total` | 系统评分（0-10） | 参考，不作为唯一依据 |
| `videos[].digg_count` | 视频点赞数 | -1=未拉取，-2=拉取失败，-3=已删除 |
| `videos[].prev_digg_count` | 上次刷新点赞数 | 与 digg_count 之差 = 近期增量 |
| `newly_on_ranking` | 是否新上榜 | 24小时内有效 |
| `captured_at` | 最近一次罗盘数据时间 | 判断数据新鲜度 |

### 查看商品封面图

`product_img` 字段为本地路径，直接拼 Base URL 访问：

```
http://192.168.8.118:1369{product_img}
```

> 无需鉴权，本地存储不存在 CDN 防盗链或过期问题。

---

## 二、验证数据：公司自营跑量记录

验证数据来自公司通过**包买办（baomaiban.com）**实际跑量的历史记录，包含真实签收率、出单量、SKU 结构、本地素材视频等。这是判断一个品**实际能否跑量**的第一手内部数据。

```
GET /api/sign-products
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `page` | 页码 | 1 |
| `size` | 每页数量 | 20 |
| `q` | 搜索商品名 | — |
| `source` | 平台筛选：`快手` / `视频号` / `抖音` | — |
| `date_type` | 日期维度：`1`=添加日期，`2`=出单日期 | 1 |
| `start_date` | 开始日期 `YYYY-MM-DD` | — |
| `end_date` | 结束日期 `YYYY-MM-DD` | — |
| `order_symbol` + `order_num` | 订单数过滤（`<` / `=` / `>`） | — |
| `sign_symbol` + `sign_rate_val` | 签收率过滤（`<` / `=` / `>`） | — |

```bash
# 拉抖音平台签收率 > 70% 的品
TOKEN=$(cat ~/.xuanpin_token | tr -d '\n')
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://192.168.8.118:1369/api/sign-products?source=抖音&sign_symbol=>&sign_rate_val=70&size=100"
```

### 返回数据结构

```json
{
  "bmb_id": 12345,
  "name": "草本初色山茶花香氛内衣",
  "item_id": 3768070902458220979,
  "img": "/product_imgs/sign_xxx.jpg",
  "source": "抖音",
  "sign_rate": "78%",
  "total_order": 1250,
  "wait_deliver_num": 30,
  "add_price": "15.00",
  "first_order_time": "2026-04-10 09:00:00",
  "bmb_created_at": "2026-04-08 14:00:00",
  "username": "王鑫磊",
  "sku": [
    { "name": "颜色", "value": "黑色" }
  ],
  "videos": [
    { "url": "/videos/xxx.mp4", "local": true }
  ]
}
```

### 关键字段说明

| 字段 | 含义 | 分析要点 |
|------|------|----------|
| `sign_rate` | 签收率（字符串如 `"78%"`） | ≥70% 健康，<50% 需警惕退货风险 |
| `total_order` | 累计出单数 | 量越大，验证越充分 |
| `wait_deliver_num` | 待发货数量 | >0 说明当前仍在跑量 |
| `add_price` | 成本进价（元） | 结合选品数据 `price_min` 可算毛利空间 |
| `source` | 跑量平台 | 跨平台出量说明品类通用性强 |
| `first_order_time` | 首单时间（出单日期） | 反映品的生命周期起点 |
| `bmb_created_at` | 添加到包买办的日期 | |
| `item_id` | 抖音商品 ID | 可与选品数据 `product_id` 字段关联 |
| `videos` | 本公司使用的本地素材视频 | `local: true` 说明已下载，可直接访问 |
| `sku` | SKU 结构列表 | 了解商品规格复杂度 |

---

## 三、两套数据联合分析

**推荐分析路径（从公开市场到内部验证）：**

1. **找信号**：从选品数据中找有爆款视频（`digg_count` 高）、市场有规模（`pay_amount_num` 大）的商品
2. **查历史**：用商品名或 `item_id` 在验证数据中查是否有跑量记录
3. **判断**：
   - 验证数据有记录 + `sign_rate ≥ 70%` + `total_order > 500` → **经过验证的可跑品**
   - 选品数据有但验证数据无记录 + 视频互动好 → **待测试品**，可推荐优先试跑
   - 验证数据有记录但签收率低（<50%）→ **慎重**，退货率高
4. **毛利核算**：验证数据 `add_price`（成本）vs 选品数据 `price_min`（客单价）→ 判断利润空间

```bash
# 查验证数据中签收率高、量大的标杆品
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://192.168.8.118:1369/api/sign-products?sign_symbol=>&sign_rate_val=70&order_symbol=>&order_num=500&size=100"

# 查近 30 天出单的新品（按出单日期）
START=$(date -v-30d +%Y-%m-%d)
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://192.168.8.118:1369/api/sign-products?date_type=2&start_date=$START&size=100"
```

---

## AI 选品分析流程

智能体调用 API 后，按以下逻辑分析：

### 第一步：看视频数据质量（选品数据）

- 有多少视频的 `digg_count > 0`（真实有互动）
- 最高点赞视频的 `digg_count` 是多少（爆款信号）
- `digg_count - prev_digg_count` > 0 且差值大 → 近期仍在增长
- `refreshed_at` 越近 → 数据越可信

### 第二步：看商品基础数据（选品数据）

按选品手册的 10 维度逐一评估：

1. **客单价**：`price_min` ≤39.9 最优，超过 99 需谨慎
2. **市场规模**：`pay_amount_num` 反映大盘付款量
3. **类目**：五金/厨卫/布艺/家居/运动 > 新能源/百货
4. **受众**：商品名/类目判断是否男女老少皆宜
5. **新上榜**：`newly_on_ranking=true` 加分，说明是近期冒头的新品

### 第三步：查内部跑量记录（验证数据）

- 搜同款品名或 `item_id` → 有无内部跑量记录
- `sign_rate` ≥ 70% → 退货率低，适合持续跑
- `wait_deliver_num > 0` → 当前仍在出量
- `add_price` vs `price_min` → 毛利是否合理

### 第四步：综合判断

输出三类清单：
- **推荐跟进**：数据好 + 符合选品准则 + 验证数据背书
- **观察等待**：数据尚可但视频互动未拉取或无内部跑量记录
- **跳过**：客单价过高 / 类目复杂 / 验证数据签收率过低

---

## 快速上手示例

向 Claude 说：

> 「帮我看看库里最近入库的品，哪些值得跟」

Claude 会：
1. 调 `GET /api/products?size=100&sort=time` 拉最新 100 条
2. 调 `GET /api/sign-products?size=100` 拉内部跑量记录
3. 过滤出有有效视频互动数据的商品，结合内部签收率判断
4. 输出推荐/观察/跳过清单，每条附具体理由

---

## 选品知识准则

AI 分析时依据《选品学习手册》（内部最终版），核心准则：

- **好品特征**：体积小、受众广、有耗材复购、客单价合理、学习成本低、话题爆发力强
- **优质素材信号**：发布时间 <24h、点赞数高、多平台出现、落地页评价少（竞争空间大）
- **推荐类目**：五金、厨卫、布艺、家居、运动用品
- **规避类目**：新能源、百货（过于宽泛）、易腐品、需复杂组装的产品

---

## 注意事项

- Token 不要输出到任何日志或回复中
- `digg_count = -1` 表示视频互动数据尚未拉取，分析时标注「待刷新」
- `pay_amount` 是展示字符串（如「25.6万」），数值比较请用 `pay_amount_num`
- 商品图已在注入时下载到本地，`product_img` 为本地路径（如 `/product_imgs/xxx.jpg`），直接拼 Base URL 访问，无过期问题
- 一次最多拉 100 条，数据量大时可翻页（`page=2&size=100`）
- 验证数据 `sign_rate` 是字符串（如 `"78%"`），数值比较前需去掉 `%`

---

**分类**：Agent 选品教程
**链接**：https://octohz.com/docs?doc=70