# 数据模型

这门生意的领域模型：实体、字段、关系。只列对外可见的字段。机器读的 JSON-LD 在 `/ontology`。

## 关系

| | | | |
| --- | --- | --- | --- |
| `Product` | hasMany | `Sku` | 一款含多个色码 / 尺码变体 |
| `Sku` | hasStockIn | `Warehouse` | SKU 在各仓有库存（Stock） |
| `Stock` | refersTo | `Sku` | 库存记录对应一个 SKU |
| `Stock` | belongsTo | `Warehouse` | 库存行自带 warehouse_code |
| `Channel` | hasAccessTo | `Warehouse` | 渠道可访问的仓（仓白名单） |
| `Channel` | hasPriceFor | `Product` | 渠道对款的专属价（Price） |
| `Order` | belongsTo | `Channel` | 订单归属渠道（归属校验） |
| `DropshipOrder` | belongsTo | `Channel` | 代发单归属渠道 |
| `Shipment` | belongsTo | `Channel` | 发货单归属渠道 |
| `Shipment` | belongsTo | `Order` | 发货单来自批发订单（order_id） |
| `StockReservation` | belongsTo | `Order` | 锁单来自批发订单（order_id）；订单审核后生成锁单，发货后生成发货单 |
| `StockReservation` | belongsTo | `Channel` | 锁单归属渠道 |
| `Cart` | belongsTo | `Channel` | 购物车（经 account）归属渠道 |
| `Transaction` | belongsTo | `Channel` | 一笔流水记在某个渠道的账上 |
| `Transaction` | refersTo | `Order` | 流水多半挂着一张订货单（order_id）与一张配单（reservation_id） |

## Product (产品（款）)

一个款号，含多个色码 / 尺码变体（SKU）。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `product_code` | string | 款号 |
| `product_name` | string | 英文品名 |
| `product_name_zh` | string | 中文品名（有值才出；目前上游未接） |
| `brand` | string | 品牌 |
| `price_wholesale` | number | 批发价 |
| `price_retail` | number | 零售价 |
| `currency` | string | 币种（AUD / CNY） |
| `weight_grams` | integer | 克重（有值才出；目前上游未接） |
| `image_urls` | array | 产品图片 URL 列表 |
| `description` | string | 规格描述 |
| `skus` | array | 这一款的全部变体（Sku） |

## Sku (SKU（条码 / 变体）)

一个具体条码 = 款 × 颜色 × 尺码。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sku` | string | SKU / 条码 |
| `product_code` | string | 所属款号 |
| `color_code` | string | 色码 |
| `color_name` | string | 颜色名 |
| `color_name_zh` | string | 颜色中文名（有值才出；目前上游未接） |
| `size` | string | 尺码 |

## Warehouse (仓库)

库存所在的仓。warehouse_code 是唯一标识，路径、参数、响应里都叫它：AU = 澳洲（全部仓合计）（合计视图）；AUSYD2 = 悉尼主仓（Rosehill）；AUSYD1 = 悉尼配件仓；CN = 中国（全部仓合计）（合计视图）；CHNZJ1 = 中国镇江仓

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warehouse_code` | string | 仓库编码：AU / AUSYD2 / AUSYD1 / CN / CHNZJ1 |
| `name` | string | 仓库名（英文） |
| `name_zh` | string | 仓库名（中文） |
| `country` | string | 国家（AU / CN） |
| `company_code` | string | 所属公司编码（100003 澳洲 / 500001 中国） |
| `type` | string | group = 公司级合计视图；physical = 真实仓 |
| `can_ship` | boolean | 能否从该仓直接发货 |
| `currency` | string | 币种 |

## Stock (库存)

某 SKU 在某仓的实时库存（含价格快照）。整仓、按款、按 SKU、增量口返回的都是它。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warehouse_code` | string | 所在仓（每行自带） |
| `sku` | string | SKU |
| `product_code` | string | 款号 |
| `product_name` | string | 品名 |
| `color_code` | string | 色码 |
| `color_name` | string | 颜色 |
| `size` | string | 尺码 |
| `brand` | string | 品牌 |
| `quantity_on_hand` | integer | 在库数量 |
| `quantity_available` | integer | 可用数量（在库 − 已锁） |
| `price_wholesale` | number | 批发价 |
| `price_retail` | number | 零售价 |
| `currency` | string | 币种 |
| `expected_arrival_date` | string | 预计到货日（有在途才出） |
| `quantity_incoming` | integer | 在途数量（有在途才出） |

## Channel (渠道（客户）)

批发客户。token 里带渠道号；能调什么由角色和仓白名单决定。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `channel_code` | string | 渠道号（客户身份） |
| `region` | string | 默认区域 au / cn |
| `roles` | array | 角色（reader / trader / full） |

## Price (渠道价)

某渠道对某款的价格（按渠道算，不是库存里那个统一价）。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warehouse_code` | string | 仓 |
| `channel_code` | string | 渠道 |
| `product_code` | string | 款号 |
| `price_wholesale` | number | 本渠道批发价 |
| `price_retail` | number | 零售价 |
| `price_settlement` | number | 结算价 |

## Order (批发订单)

批发下单 / 查单，归属某渠道。下单发什么、查单拿回什么，同一个形状。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `order_id` | string | 订单号 |
| `warehouse_code` | string | 仓 |
| `lines` | array | 明细 [{sku, quantity}] |
| `status` | string | 状态：draft 未审核 / confirmed 已审核 / cancelled 作废 |
| `status_raw` | integer | 状态原值 |
| `created_date` | string | 单据日期 |
| `note` | string | 备注 |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

## DropshipOrder (代发订单)

代发下单 / 查单，归属某渠道，带收件人。一张代发单只有一个 SKU。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `dropship_order_id` | string | 代发订单号 |
| `serial_number` | string | 流水号 |
| `client_order_number` | string | 客户自己的单号 |
| `warehouse_code` | string | 仓 |
| `sku` | string | SKU |
| `quantity` | integer | 件数 |
| `quantity_allocated` | integer | 已配货 |
| `quantity_shipped` | integer | 已发货 |
| `recipient` | object | 收件人 {name, phone, address, country_code, state, city, postal_code} |
| `sender` | object | 发件人 {name, phone} |
| `shipping_method` | string | 运输方式 normal / express |
| `carrier` | string | 承运商 |
| `tracking_number` | string | 运单号 |
| `shipped` | boolean | 是否已发货 |
| `shipped_date` | string | 发货日期 |
| `status` | string | 状态：pending 新建未配货 / shipped 已发货 / intercepted 已拦截 / cancelled 已取消 |
| `status_raw` | integer | 状态原值 |
| `paid` | boolean | 是否已付款 |
| `price_settlement` | number | 结算价 |
| `amount_shipping` | number | 运费 |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

## Shipment (发货单)

发货单，归属某渠道；物流轨迹挂在它下面。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `shipment_id` | string | 发货单号 |
| `order_id` | string | 来源批发订单号 |
| `reservation_id` | string | 来源锁单号 |
| `warehouse_code` | string | 仓 |
| `status` | string | 状态：shipped 已发货 |
| `tracking_number` | string | 运单号 |
| `lines` | array | 明细 |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

## StockReservation (锁单 / 预留库存)

渠道锁定的库存，归属某渠道。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `reservation_id` | string | 锁单号 |
| `order_id` | string | 来源批发订单号 |
| `warehouse_code` | string | 仓 |
| `status` | string | 状态：reserved 锁定中 / cancelled 已作废 / confirmed 已审核 |
| `shipped` | boolean | 是否已发货 |
| `lines` | array | 明细 [{sku, quantity}] |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

## Cart (购物车)

按 OMS 账号的购物车（账号归属某渠道）。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `account` | string | OMS 账号 |
| `lines` | array | 明细 [{sku, quantity}] |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

## Transaction (账户流水)

渠道账户的一笔资金变动：充值 / 扣款 / 退款。余额是它们的累计结果。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `transaction_id` | string | 流水号（14 位纯数字，与代发流水号同形——认号要给候选） |
| `transaction_type` | string | 类型：recharge 充值 / payment 支付 / refund 退款 |
| `amount` | number | 金额（正负号按类型） |
| `currency` | string | 币种 |
| `balance_after` | number | 这一笔之后的余额——余额链首尾可验算 |
| `order_id` | string | 关联的订货单号（有才出） |
| `reservation_id` | string | 关联的配单号（有才出） |
| `created_at` | string | 上游处理时间（不是业务发生时间：补录会落在补录那天） |
| `channel_code` | string | 归属渠道（归属校验用：只能看到自己的） |

```bash
curl "https://connect.everugg.net.au/ontology" -H "Accept: application/ld+json"
curl "https://connect.everugg.net.au/ontology?format=plain"
```

`/ontology` 默认给 JSON-LD（W3C 标准）；`?format=plain` 给普通 JSON，`?format=rdf` 给 N-Quads。

---
Markdown 源: https://connect.everugg.net.au/reference/ontology.md?lang=zh · 网页版: https://connect.everugg.net.au/reference?sec=ontology&lang=zh