🤖 国际物流比价系统 · AI 只读数据 API 文档

1 AI 快速理解指南

📋 系统名称和定位

系统名称：国际物流比价系统 (International Logistics Price Comparison System)

一句话定位：录入多家物流商的产品报价，按重量/体积等参数一键比价，找到最优发货方案。

🔄 核心业务循环

📊 主要业务线

👥 组织架构和权限模型

admin（管理员）：拥有所有权限，可管理用户、配置系统、增删改所有数据

user（普通用户）：只能操作自己录入的数据，可查看和比价，不可管理用户

权限分为模块权限（home/mgmt/price/cmp/batch）和操作权限（add/edit/del）

🧭 推荐分析路径

2 基本信息 & 鉴权方式

📌 基本信息

🔑 鉴权方式

X-API-Key Header（唯一允许的方式）

GET /data.php?action=overview HTTP/1.1
Host: wl.omejia.com
X-API-Key: wl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📦 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1696876800
}

3 系统全貌

📝 系统一句话总结

国际物流比价系统是一个用于管理多家物流商产品报价并进行智能比价的工具，支持空运和海运两种运输方式，帮助用户快速找到最优物流方案。

👤 角色说明

📦 功能模块列表

🌐 前端入口列表

4 业务流程详解

📥 数据创建流程

说明：必须先有公司，才能在公司下创建产品；必须先有产品，才能在产品下录入报价。一个公司可以有多个产品，一个产品可以有多条报价（不同国家/不同类型）。

🔍 比价查询流程

📋 批量比价流程

🔒 权限控制规则

• 数据归属：每条数据记录 created_by 字段标识创建者
• 普通用户：只能查看、编辑、删除自己创建的数据
• 管理员：可以查看和操作所有数据
• 模块权限：由 perms 字段控制，数组形式，如 ["home","mgmt","price","cmp","batch"]
• 操作权限：由 ops 字段控制，数组形式，如 ["add","edit","del"]
• 状态控制：status 为 inactive 的物流公司/产品不会出现在比价结果中

5 数据模型 ER 图

📐 文字版 ER 图

┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
│  logistics_         │         │  logistics_         │         │  pricing_           │
│  companies          │         │  products           │         │  records            │
│  (物流公司)         │1      n │  (物流产品)         │1      n │  (报价记录)         │
├─────────────────────┤◄────────┤                     ├────────►│                     │
│ 🔑 id (varchar)     │         │ 🔑 id (varchar)     │         │ 🔑 id (varchar)     │
│    name             │         │ 🔵 company_id       │         │ 🔵 company_id       │
│    code             │         │    name             │         │ 🔵 product_id       │
│    status           │         │    type             │         │    destination_     │
│    service_area     │         │    pricing_type     │         │    country          │
│    tracking         │         │    battery          │         │    type             │
│    reliable         │         │    status           │         │    base_pricing     │
│    phone/website    │         │    created_by       │         │    additional_fees  │
│    created_by       │         │    created_at       │         │    weight_limits    │
│    created_at       │         │                     │         │    length_limits    │
│                     │         │                     │         │    girth_limits     │
└─────────────────────┘         └─────────────────────┘         │    created_by       │
                                                                 │    created_at       │
                                                                 └─────────────────────┘

┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
│  users              │  │  batch_orders       │  │  remote_zipcodes    │
│  (用户表)           │  │  (批量订单)         │  │  (偏远邮编)         │
├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
│ 🔑 id (int)         │  │ 🔑 id (int)         │  │ 🔑 id (int)         │
│ ✨ username         │  │    order_no         │  │ ✨ zipcode          │
│ 🔒 password         │  │    params           │  │                     │
│    role             │  │    imported_at      │  │                     │
│    perms            │  │                     │  │                     │
│    ops              │  └─────────────────────┘  └─────────────────────┘
│    status           │
│    created_at       │  ┌─────────────────────┐  ┌─────────────────────┐
│                     │  │  data_urls          │  │  settings           │
└─────────────────────┘  │  (数据源URL)        │  │  (系统配置)         │
                         ├─────────────────────┤  ├─────────────────────┤
                         │ 🔑 id (int)         │  │ 🔑 skey             │
                         │    url              │  │    svalue           │
                         │    sort_order       │  │                     │
                         │                     │  │                     │
                         └─────────────────────┘  └─────────────────────┘

  🔑 PK (主键)    🔵 FK (外键)    ✨ UNIQUE (唯一)    🔒 敏感字段(已过滤)

🔗 表关系详细列表

📝 冗余字段说明

• pricing_records.company_id：虽然可以通过 product_id 关联到公司，但为了查询效率做了冗余存储
• pricing_records.type：报价类型，与产品的 type 可能一致，也可能因不同目的地而异
• JSON 字段（base_pricing, additional_fees, weight_limits 等）：存储结构化的报价配置数据，避免创建过多子表

6 状态字段速查表

7 所有表字段详解 + 数据样例

🏢 logistics_companies - 物流公司表

业务说明：存储所有合作的物流公司基础信息。一个公司可以有多个物流产品，是产品和报价的上级归属。

数据来源：管理员或有权限的用户在「物流公司管理」模块手动录入

数据样例

{
  "id": "1770000959359",
  "name": "际通",
  "code": "JT",
  "status": "active",
  "phone": "",
  "website": "",
  "address": "",
  "service_area": "us",
  "tracking": "yes",
  "reliable": "100",
  "reliable_note": "",
  "notes": "",
  "created_by": "",
  "created_at": "2026-02-02T02:55:59.359Z"
}

📦 logistics_products - 物流产品表

业务说明：存储各物流公司提供的具体物流产品（如美森大包、空运专线等）。每个产品归属于一个物流公司。

数据来源：用户在「快递产品管理」模块手动录入

数据样例

{
  "id": "1770000978688",
  "company_id": "1770000959359",
  "name": "美森大包",
  "type": "sea",
  "pricing_type": "type1",
  "battery": "no",
  "status": "active",
  "created_by": "",
  "created_at": "2026-02-02T02:56:18.688Z"
}

💰 pricing_records - 报价记录表

业务说明：存储具体的报价规则，是比价计算的核心数据。每条报价关联一个产品和一个目的国家，包含基础定价、附加费、重量/尺寸限制等。

数据来源：用户在「报价管理」模块手动录入

JSON 字段说明

• base_pricing：基础价格配置，type1为首重续重，type2为公斤段数组，type3为最低消费
• additional_fees：包含操作费、体积重系数、超尺寸费、偏远费、税费、末端派送等
• weight_limits：最小/最大重量限制
• length_limits：最小/最大长度限制
• girth_limits：最小/最大围长限制

数据样例（type1 首重续重）

{
  "id": "1770026053836",
  "company_id": "1770000959359",
  "product_id": "1785205383708",
  "destination_country": "美国",
  "type": "type1",
  "base_pricing": {
    "firstWeight": "6.1",
    "firstPrice": "295",
    "additionalWeight": "",
    "additionalPrice": ""
  },
  "additional_fees": {
    "handlingFee": "",
    "volumeFactor": "8000",
    "deliveryTime": "",
    "oversizeSegments": [
      {"minLen": 120, "fee": 120},
      {"minLen": 240, "fee": 750}
    ],
    "girthFeeSegments": [
      {"minG": 325, "fee": 750}
    ],
    "remoteFee": "",
    "taxFee": "0",
    "lastMile": "UPS、FedEx"
  },
  "weight_limits": {"minWeight": "6.1", "maxWeight": "10.1"},
  "length_limits": {"minLength": "0", "maxLength": "270"},
  "girth_limits": {"minGirth": "0", "maxGirth": "400"},
  "created_by": "",
  "created_at": "2026-02-02T09:54:13.836Z"
}

📋 batch_orders - 批量订单表

业务说明：存储批量比价的订单数据，用于批量导入多个包裹信息后统一比价。

数据来源：用户在「批量比价」模块手动添加或从外部数据源导入

📮 remote_zipcodes - 偏远邮编表

业务说明：存储偏远地区的邮政编码，比价时如果收货邮编在此库中，会额外计算偏远费。

数据来源：用户在「偏远地区邮编库」模块批量录入

🔗 data_urls - 数据源URL表

业务说明：存储外部数据源的 API 地址，系统可定时从这些地址拉取报价数据进行同步。

数据来源：管理员在「数据源管理」模块配置

⚙️ settings - 系统配置表

业务说明：存储系统级配置项，使用 key-value 结构。

数据来源：系统初始化时生成，管理员可修改

数据样例

{
  "skey": "agreement",
  "svalue": "欢迎使用国际物流比价系统！\n\n一、服务条款\n1. 本系统仅供内部使用..."
}

👥 users - 用户表

业务说明：存储系统用户账号信息，用于登录鉴权和权限控制。

数据来源：管理员在「用户管理」模块创建

权限字段说明

• perms（模块权限）：home(首页), mgmt(公司/产品管理), price(报价管理), cmp(比价), batch(批量比价)
• ops（操作权限）：add(新增), edit(编辑), del(删除)

8 API 接口详情

{
  "code": 0,
  "message": "success",
  "data": {
    "table_counts": {
      "logistics_companies": 23,
      "logistics_products": 52,
      "pricing_records": 45,
      "batch_orders": 0,
      "remote_zipcodes": 1,
      "data_urls": 0,
      "settings": 1,
      "users": 1
    },
    "status_stats": {
      "logistics_companies": {
        "active": 20,
        "inactive": 3
      },
      "logistics_products": {
        "active": 48,
        "inactive": 4
      },
      "users": {
        "active": 1
      }
    },
    "today_stats": {
      "logistics_companies": 0,
      "logistics_products": 0,
      "pricing_records": 0,
      "batch_orders": 0
    },
    "system_info": {
      "name": "国际物流比价系统",
      "version": "3.1",
      "tables": 8
    }
  },
  "timestamp": 1696876800
}

{
  "code": 0,
  "message": "success",
  "data": {
    "table": "logistics_companies",
    "table_comment": "物流公司表",
    "engine": "InnoDB",
    "rows": 23,
    "columns": [
      {
        "field": "id",
        "type": "varchar(32)",
        "null": "NO",
        "key": "PRI",
        "default": null,
        "extra": "",
        "is_sensitive": false
      },
      {
        "field": "name",
        "type": "varchar(128)",
        "null": "NO",
        "key": "",
        "default": null,
        "extra": "",
        "is_sensitive": false
      }
    ],
    "primary_keys": ["id"]
  },
  "timestamp": 1696876800
}

{
  "code": 0,
  "message": "success",
  "data": {
    "table": "logistics_companies",
    "total": 23,
    "page": 1,
    "page_size": 20,
    "total_pages": 2,
    "list": [
      {
        "id": "1770000959359",
        "name": "际通",
        "code": "JT",
        "status": "active",
        "..."
      }
    ]
  },
  "timestamp": 1696876800
}

{
  "code": 0,
  "message": "success",
  "data": {
    "table": "pricing_records",
    "days": 7,
    "total_in_period": 12,
    "daily_data": [
      {"date": "2026-10-02", "count": 3},
      {"date": "2026-10-03", "count": 0},
      {"date": "2026-10-04", "count": 5},
      {"date": "2026-10-05", "count": 2},
      {"date": "2026-10-06", "count": 1},
      {"date": "2026-10-07", "count": 0},
      {"date": "2026-10-08", "count": 1}
    ]
  },
  "timestamp": 1696876800
}

9 AI 数据分析最佳实践

🧭 推荐分析路径：5 步法

📊 典型场景 1：每日运营简报

快速生成每日数据概览，了解系统整体运营状况。

// 1. 获取整体概览
GET /data.php?action=overview

// 2. 获取核心表今日趋势
GET /data.php?action=daily_stats&table=pricing_records&days=7
GET /data.php?action=daily_stats&table=logistics_products&days=7

// 3. 按状态分布
GET /data.php?action=group_stats&table=logistics_companies&group_by=status

📉 典型场景 2：效率分析（找瓶颈）

分析各物流公司的产品丰富度和报价覆盖情况，找出数据空白点。

// 1. 按公司分组统计产品数量
GET /data.php?action=group_stats&table=logistics_products&group_by=company_id

// 2. 按公司分组统计报价数量
GET /data.php?action=group_stats&table=pricing_records&group_by=company_id

// 3. 按运输方式分布
GET /data.php?action=group_stats&table=logistics_products&group_by=type

// 4. 找出产品少的公司
GET /data.php?action=list&table=logistics_companies&status=active&sort_by=id
// 然后对比各公司产品数量，找出低于平均值的公司

📈 典型场景 3：增长预测

基于历史数据趋势，预测未来数据增长。

// 获取近 90 天报价录入趋势
GET /data.php?action=daily_stats&table=pricing_records&days=90

// 获取近 90 天产品新增趋势
GET /data.php?action=daily_stats&table=logistics_products&days=90

// 分析：
// 1. 计算日均新增量
// 2. 观察周内波动规律
// 3. 预测未来 30 天增长
// 4. 给出数据完善建议

⚖️ 典型场景 4：对比分析

对比不同公司的产品结构和报价策略。

// 1. 获取所有活跃公司
GET /data.php?action=list&table=logistics_companies&status=active&page_size=100

// 2. 按公司分组产品数量
GET /data.php?action=group_stats&table=logistics_products&group_by=company_id

// 3. 按公司分组报价数量
GET /data.php?action=group_stats&table=pricing_records&group_by=company_id

// 4. 空运 vs 海运产品分布
GET /data.php?action=group_stats&table=logistics_products&group_by=type

// 5. 报价方式分布
GET /data.php?action=group_stats&table=logistics_products&group_by=pricing_type

10 错误码说明