162 lines
4.9 KiB
Markdown
162 lines
4.9 KiB
Markdown
# 创建订单
|
||
|
||
> 用户提供客户信息 + 商品信息（名称、单位、数量），自动完成订单创建。
|
||
|
||
## 触发条件
|
||
|
||
用户表达以下意图时触发：
|
||
- "帮我下单" / "创建订单" / "录个订单"
|
||
- "我要订货" / "订一批货"
|
||
- 提供商品名称 + 数量时（如"5件鸡肉"）
|
||
|
||
---
|
||
|
||
## 第一步：查询客户
|
||
|
||
用户可能提供：客户名称、客户编码
|
||
|
||
调用客户搜索接口：
|
||
```
|
||
POST https://openapi.77ircloud.com/organization-aggregation/customer/search
|
||
Header: access_token, Content-Type: application/json
|
||
Body: {"pageNum":1,"pageSize":10,"keyword":"客户名称或编码"}
|
||
```
|
||
|
||
返回结果中找到对应客户，记录 `id`（即 `buyerId`）。
|
||
|
||
**注意：**
|
||
- 如果客户不存在，返回错误并告知用户
|
||
- 如果搜索结果有多个，选择第一个（默认取第一个）
|
||
|
||
---
|
||
|
||
## 第二步：查询商品
|
||
|
||
用户提供：商品名称、单位名称（如"包"、"件"、"斤"、"瓶"）、购买数量
|
||
|
||
调用商品搜索接口（见 `product-suite.md`）：
|
||
```
|
||
GET https://suite.77ircloud.com/product-aggregation/v1/products?pageSize=30¤tPage=1&queryTag=true&queryInventories=true&loadSortingTag=true&loadSortingTagName=true&q={商品名称}
|
||
Header: authorization={jwt}, x-exclude-login-mutex=77ircloud
|
||
```
|
||
|
||
在返回结果中找对应商品，**默认取第一个**，记录：
|
||
- `skuId` → 下单用 `productSku`
|
||
- `multiUnitId` → 下单用 `unitId`
|
||
- `unitName` → 与用户提供的单位核对
|
||
|
||
**如果商品有多单位**（如"件"和"包"），根据用户提供的单位名称匹配对应的 `multiUnitId`。
|
||
|
||
---
|
||
|
||
## 第三步：计算金额
|
||
|
||
- `salePrice` = `originalPrice` = 商品的 `basePrice`（第一档价格）
|
||
- `subtotal` = `salePrice` × 购买数量
|
||
- `productTotalAmount` = 所有商品 `subtotal` 之和
|
||
- `orderTotalAmount` = `productTotalAmount`（无额外运费/优惠时）
|
||
|
||
---
|
||
|
||
## 第四步：组装订单参数
|
||
|
||
```json
|
||
{
|
||
"buyerId": "{客户ID}",
|
||
"orderDetails": [{
|
||
"productSku": "{skuId}",
|
||
"productSpu": "{skuId}", // 用 skuId 作为 spuId
|
||
"purchaseNumbers": {购买数量},
|
||
"unitId": "{multiUnitId}",
|
||
"salePrice": {单价},
|
||
"originalPrice": {单价},
|
||
"saleRate": 100.0,
|
||
"subtotal": {小计金额},
|
||
"type": "NORMAL"
|
||
}],
|
||
"productTotalAmount": {商品总金额},
|
||
"orderTotalAmount": {订单总金额},
|
||
"productDiscountAmount": 0,
|
||
"orderDiscountAmount": 0,
|
||
"totalFreight": 0,
|
||
"orderSource": "APP",
|
||
"orderStatus": "ORDER_AUDIT_PENDING",
|
||
"deliveryMethodId": 1
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `deliveryMethodId` | 1（到店自提） | 可选，用户指定则用用户值 |
|
||
| `orderSource` | APP | 固定 |
|
||
| `orderStatus` | ORDER_AUDIT_PENDING | 固定 |
|
||
| `saleRate` | 100.0 | 固定 |
|
||
| `productDiscountAmount` | 0 | 固定 |
|
||
| `orderDiscountAmount` | 0 | 固定 |
|
||
| `totalFreight` | 0 | 固定 |
|
||
|
||
**用户可能指定的额外参数：**
|
||
- `deliveryMethodId`: 1=到店自提, 2=送货上门（需要客户有配送地址）
|
||
|
||
---
|
||
|
||
## 第五步：调用下单接口
|
||
|
||
```
|
||
POST https://openapi.77ircloud.com/order-aggregation/organizations/orders
|
||
Header: access_token, Content-Type: application/json
|
||
Body: 见上面
|
||
```
|
||
|
||
**返回格式：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": 2390029347669600 // 这是订单ID
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 第六步：返回订单编号
|
||
|
||
下单接口只返回订单 ID，不返回订单编号。需要再查一次订单详情：
|
||
|
||
```
|
||
POST https://openapi.77ircloud.com/order-aggregation/organizations/orders/search
|
||
Body: {"pageNum":1,"pageSize":100,"withDetails":true}
|
||
```
|
||
|
||
在结果中用返回的订单 ID 找到对应订单，返回 `orderCode`。
|
||
|
||
---
|
||
|
||
## 完整流程示例
|
||
|
||
**用户输入：** "帮华誉供货链下 3 包嘉吉尚选霸王鸡肉条"
|
||
|
||
**执行：**
|
||
|
||
1. 客户搜索"华誉供货链" → buyerId: 2364948772653120（默认取第一个）
|
||
2. 商品搜索"嘉吉尚选霸王鸡肉条" → 默认取第一个结果：skuId: 2116793372668192, multiUnitId: 2116793372668193, basePrice: 18.9
|
||
3. 组装参数：purchaseNumbers=3, subtotal=56.7, productTotalAmount=56.7
|
||
4. 调用下单接口 → orderId: 2390029347669600
|
||
5. 查询订单详情 → orderCode: CA000000-260331-102428
|
||
|
||
**返回：** "订单创建成功！订单编号：CA000000-260331-102428"
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **用户输入可能是语音转文字**，注意处理口语化表达（如"3件"="3件"、"5斤"="5斤"）
|
||
2. **单位匹配**：商品接口返回 `unitName`，用户可能说"件"或"包"，需匹配
|
||
3. **商品多规格**：用户未指定单位时，默认用第一个单位
|
||
4. **库存检查**：创建订单前不强制检查库存，但可以查一下 `availableAmount` 告知用户
|
||
5. **下单失败常见原因**：
|
||
- 客户未配置配送方式（到店自提也需配置）→ 改用 `deliveryMethodId=1`
|
||
- 必填字段缺失 → 检查 `productSku`, `unitId`, `purchaseNumbers` 等
|