9. 接口定义

接口列表

以下定义 v1.0.0 核心业务接口，按实体模块组织。所有接口返回统一格式 { code: number, data: any, message: string }。

采购管理

POST /api/purchases —— 创建采购开单

Method： POST 描述： 创建采购开单，记录供应商、成本、采购日期。

请求参数：

参数	类型	必填	说明
supplier_name	string	是	供应商名称
cost_cny	number	是	采购总成本（CNY）
purchase_date	string	是	采购日期（YYYY-MM-DD）
items	array	是	采购商品列表 [{brand, category, unit_cost}]

响应数据：

{
  "code": 0,
  "data": {
    "purchase_id": "PO-20260512-001",
    "status": "待入库"
  },
  "message": "success"
}

入库登记管理

POST /api/inbound —— 登记入库

Method： POST 描述： 为采购开单下的商品进行入库登记，录入商品信息，系统自动生成条码。

请求参数：

参数	类型	必填	说明
purchase_id	string	是	关联采购开单 ID
items	array	是	商品列表 [{name, brand, category, grade, images, description, purchase_price}]

响应数据：

{
  "code": 0,
  "data": {
    "items": [
      {
        "product_id": "PROD-001",
        "barcode": "LS202605120001",
        "sku": "LV-BAG-20260512-001",
        "status": "在库"
      }
    ]
  }
}

库存管理

GET /api/inventories —— 查询库存

Method： GET 描述： 按仓库、品牌、品类、状态查询库存。

请求参数：

参数	类型	必填	说明
warehouse_id	string	否	仓库 ID 筛选
status	string	否	库存状态筛选
brand	string	否	品牌筛选
page	number	否	页码，默认 1
size	number	否	每页数量，默认 20

响应数据：

{
  "code": 0,
  "data": {
    "total": 156,
    "items": [
      {
        "sku": "LV-BAG-20260501-001",
        "brand": "LV",
        "category": "包包",
        "grade": "95新",
        "warehouse": "纽约销售仓",
        "status": "在库"
      }
    ]
  }
}

POST /api/inventories/inbound —— 扫码入库

Method： POST 描述： 商品扫码入库到指定仓库（入库登记完成后自动调用，也可手动补充）。

请求参数：

参数	类型	必填	说明
barcode	string	是	商品条码（LS+日期+流水号）
warehouse_id	string	是	目标仓库 ID

调拨管理

POST /api/transfers —— 创建调拨单

Method： POST 描述： 发起跨境仓间调拨。

请求参数：

参数	类型	必填	说明
from_warehouse	string	是	源仓 ID
to_warehouse	string	是	目标仓 ID
sku_list	array	是	调拨商品 SKU 列表
logistics_no	string	否	物流单号

POST /api/transfers/{id}/confirm —— 确认入库

Method： POST 描述： 目标仓确认调拨入库。

销售管理

POST /api/sales —— 销售开单

Method： POST 描述： 扫码销售开单，自动扣减库存和记录销售池收入。

请求参数：

参数	类型	必填	说明
channel	string	是	whatnot / offline / private
items	array	是	销售商品 [{barcode, amount_usd}]
customer_id	string	否	客户 ID

响应数据：

{
  "code": 0,
  "data": {
    "order_id": "SO-20260512-001",
    "platform_fee": 18.00,
    "net_revenue": 132.00,
    "status": "待发货"
  }
}

成本管理

POST /api/costs —— 创建成本记录

Method： POST 描述： 创建成本记录，系统根据 warehouse_id 自动确定归属资金池和币种。

请求参数：

参数	类型	必填	说明
category	string	是	成本大类：product / general
sub_category	string	是	子类：maintain / repair / scrap / operating / other
product_id	string	否	关联商品 ID（商品挂载成本必填）
warehouse_id	string	是	发生仓库 ID
amount	number	是	成本金额
description	string	否	成本描述

GET /api/costs —— 查询成本记录

Method： GET 描述： 按成本大类、子类、仓库、日期范围筛选成本记录。

请求参数：

参数	类型	必填	说明
category	string	否	成本大类筛选
warehouse_id	string	否	仓库筛选
start_date	string	否	开始日期
end_date	string	否	结束日期

资金池

GET /api/pools —— 查询资金池状态

Method： GET 描述： 获取双资金池当前余额和流水。

响应数据：

{
  "code": 0,
  "data": {
    "cny_pool": {
      "current_balance": 320000,
      "target_balance": 400000,
      "warn_line": 150000,
      "status": "正常"
    },
    "usd_pool": {
      "current_balance": 18500,
      "status": "正常"
    }
  }
}

分润

POST /api/profit-sharing/calculate —— 计算分润

Method： POST 描述： 对指定日期范围内的已完成订单计算分润金额（预览，不执行）。

请求参数：

参数	类型	必填	说明
start_date	string	是	开始日期
end_date	string	是	结束日期
share_ratio	number	否	分润比例，默认取全局配置

POST /api/profit-sharing/execute —— 执行分润

Method： POST 描述： 确认执行分润，资金从销售池划出。

请求参数：

参数	类型	必填	说明
order_ids	array	是	参与分润的订单 ID 列表
share_ratios	object	否	逐单分润比例，不传则用全局默认