# 丰田 EPC 本地查询接口交付说明

交付日期：2026-06-19

## 1. 交付目标

这份交付包用于搭建一个本地或内网查询服务。第一版目标是：

- 输入 OE 号码，返回丰田 EPC 本地数据里的车型目录、地区、零件名、图号、原厂示意图、候选互换号。
- 输入 VIN，返回丰田 EPC 本地数据里的地区、目录、MODEL、底盘号、发动机、生产年月。
- 输入 MODEL，返回 EPC 车型目录、发动机、底盘号、生产年月范围。

数据来源只使用本地 Toyota EPC 原始文件，不依赖外部网站。

## 2. 交付包文件

| 文件/目录 | 用途 |
|---|---|
| `database/toyota_epc_validation.sqlite` | 已转换好的 SQLite 数据库 |
| `scripts/toyota_epc_query_part_db.py` | OE 查询示例脚本 |
| `scripts/toyota_epc_query_validation_db.py` | VIN 查询示例脚本 |
| `scripts/toyota_epc_extend_parts_db.py` | OE/图号/零件名索引构建脚本 |
| `docs/toyota_epc_part_query_service_path.md` | OE 查询链路说明 |
| `docs/toyota_epc_api_handoff_README.md` | 本说明文件 |
| `images/part_images/*.png` | 已抽出的原厂示意图样例 |

## 3. 数据库概况

SQLite 数据库大小约 2.33GB。

核心表：

| 表名 | 行数 | 说明 |
|---|---:|---|
| `epc_vin_index` | 460,518 | VIN 前 9 位、目录、MODEL 入口 |
| `epc_vehicle_detail` | 341,466 | MODEL、底盘号、发动机、生产年月、方向盘等 |
| `epc_vehicle_name` | 1,437 | EPC 内部车名、目录名 |
| `epc_frame_month_point` | 1,259,570 | 车架流水号推生产年月 |
| `epc_catalog_frame_range` | 210,045 | 目录对应底盘号范围 |
| `epc_part_index` | 10,770,116 | OE -> 参考号、图号、目录 |
| `epc_part_name` | 1,148,341 | 参考号 -> 零件名 |
| `epc_figure_image` | 577,520 | 图号 -> 原厂示意图编号 |
| `epc_image_index` | 212,336 | 示意图编号 -> 图片包位置 |

## 4. 推荐接口

### 4.1 OE 查询接口

接口示例：

`GET /api/toyota/oe/48510-8Z205`

建议返回：

```json
{
  "oe": "48510-8Z205",
  "source": "local Toyota EPC raw files only",
  "hit_groups": 54,
  "groups": [
    {
      "market": "EU",
      "catalog": "672590",
      "vehicle_name_epc": "HILUX",
      "model_family": "GUN12#,135",
      "reference_code": "48510",
      "part_name": "右前减振器总成",
      "figure_group": "4803",
      "candidate_same_position_oe": ["48510-8Z205", "48510-8Z207"],
      "images": ["EU_672590_4803_0001_484157D.png"]
    }
  ]
}
```

查询逻辑：

```mermaid
flowchart LR
  OE["OE 号码"] --> FGI["epc_part_index"]
  FGI --> NAME["epc_part_name"]
  FGI --> CAR["epc_vehicle_name"]
  FGI --> DETAIL["epc_vehicle_detail"]
  FGI --> IMG["epc_figure_image + epc_image_index"]
  FGI --> SAME["同位置候选 OE"]
```

关键 SQL 方向：

```sql
SELECT *
FROM epc_part_index
WHERE oe_no = '48510-8Z205';
```

同位置候选 OE：

```sql
SELECT DISTINCT q.oe_no
FROM epc_part_index q
JOIN epc_part_index p
  ON p.market = q.market
 AND p.catalog = q.catalog
 AND p.reference_code = q.reference_code
 AND p.figure_group = q.figure_group
WHERE p.oe_no = '48510-8Z205'
ORDER BY q.oe_no;
```

### 4.2 VIN 查询接口

接口示例：

`GET /api/toyota/vin/JTEBN99J900077939`

建议返回：

```json
{
  "vin": "JTEBN99J900077939",
  "market": "EU",
  "catalog": "781540",
  "vehicle_name_epc": "LAND CRUISER 90",
  "model": "VZJ95L-GKPNKW",
  "frame_code": "VZJ95",
  "frame_serial": "0077939",
  "engine_epc": "VZFE",
  "production_month_epc": "200008"
}
```

### 4.3 MODEL 查询接口

接口示例：

`GET /api/toyota/model/VZJ95L-GKPNKW`

建议返回：

- EPC 内部车名
- 地区
- 目录号
- 底盘号
- 发动机
- 生产年月范围
- 方向盘/目的地等 EPC 原始字段

## 5. 已验证样例

### 5.1 OE：`48510-8Z205`

本地 EPC 查询结果：

- 命中原始位置：54 条
- 市场分布：
  - `EU`：12 条，6 个目录
  - `GR`：20 条，10 个目录
  - `JP`：2 条，1 个目录
  - `US`：20 条，10 个目录
- EPC 内部车型：`HILUX`、`HILUX (DOUBLE CAB)`、`HILUX (DCB/SCB/XTR)`
- 零件名：
  - `48510`：右前减振器总成
  - `48520`：左前减振器总成
- 同位置候选 OE：44 个

### 5.2 VIN：`JTEBN99J900077939`

本地 EPC 查询结果：

- 市场：`EU`
- 目录：`781540`
- EPC 内部车名：`LAND CRUISER 90`
- MODEL：`VZJ95L-GKPNKW`
- 底盘号：`VZJ95`
- 流水号：`0077939`
- 发动机：`VZFE`
- 生产年月：`200008`

## 6. 当前准确度边界

已经可以确认：

- OE 可以查询到 EPC 目录、地区、图号、零件名、原厂示意图。
- VIN 可以查询到 EPC 内部 MODEL、底盘号、发动机、生产年月。
- EPC 内部车名来自 `SHAMEI.ACD`，不是外部网站名称。
- 查询结果可用于内部查询第一版。

需要继续增强：

- 当前互换号是“同地区 + 同目录 + 同参考号 + 同图号”的候选互换。
- 严格互换还需要继续解析条件文件，例如：
  - 左舵/右舵
  - 发动机
  - 目的地
  - 驾驶室类型
  - 生产年月
  - 其他 EPC 条件码
- 这些条件主要来自 `KIG*.Dxx / TKM*.Dxx / KPT*.DAT / HCD*.DAT` 等文件。

## 7. 技术落地建议

第一版服务建议直接用 SQLite：

- 后端：Python FastAPI、Node.js、Java、Go 都可以。
- 数据库：直接读取 `toyota_epc_validation.sqlite`。
- 图片：把 `images/part_images` 作为静态图片目录。
- 接口返回时保留 `market`，不要把不同地区混在一起。
- 左舵/右舵未严格解析前，不要把候选 OE 标记为“100% 通用”。

对外公开前需要额外评估：

- EPC 数据版权/授权风险。
- 图片和零件目录数据是否允许公开展示。
- 是否只做内部服务或受控会员查询。

## 8. 技术验收标准

技术搭好后，可以用下面两个号码验收：

| 输入 | 期望 |
|---|---|
| `48510-8Z205` | 能返回 HILUX、EU/GR/JP/US、右前/左前减振器、图号 4803、候选 OE |
| `JTEBN99J900077939` | 能返回 LAND CRUISER 90、VZJ95L-GKPNKW、VZFE、200008 |

如果这两个样例一致，说明第一版接口路径正确。