xyfcli-order-guide

肥料订单下单与客户/供应商管理技能。使用 xyfcli CLI 执行：(1) 下单/订货/采购肥料；(2) 查询产品信息/价格/库存；(3) 查询客户/供应商/经销商信息；(4) 解析订货单图片。触发词：下单、订货、买肥料、查产品、查客户、供应商信息、产品列表、客户编码。

# 交互式下单引导

## 核心原则

### 交互式三原则

1. **提示完整清晰**：每步提示和引导信息必须完整清晰，所有可选项、操作步骤、输入格式都要完整呈现，清晰完整的提示 = 高效率
2. **用户输入精简**：需要用户输入的流程尽可能精简，能自动查询的不追问
3. **领导交代任务模式**：用户一句话交代任务，OpenClaw 自动完成验证和下单，展示完整精确的结果

---

## 能力清单（明确告知用户）

**你可以帮用户做这些事：**

| 能力           | 触发词/示例                                                                                                        | 说明           |
| ------------ | ---------------------------- | ------------ |
| 🛒 **快速下单**  | "帮吉林市文英化肥经销有限责任公司下26吨Y14002510160020000，吉林新洋丰基地出发，汽运，统派车（客户付款），到吉林省吉林市蛟河市公安局乌林派出所八家子警务室，邱文英收，联系方式13394403131" | 一句话下单，自动验证   |
| 📦 **查产品**   | "看看有什么复合肥"、"查 45% 的产品"                                                                                        | 查询客户可购买的产品列表 |
| 👥 **查客户**   | "我有哪几个客户"、"查客户列表"                                                                                             | 查询你名下的所有客户   |
| 📍 **查地址**   | "牛建建的地址在哪"                                                                                                    | 查询客户的收货地址    |
| ➕ **新增地址** | "给牛建建新增一个地址"                                                                                                  | 新增客户收货地址     |
| ✏️ **修改地址** | "修改牛建建的地址"                                                                                                   | 修改客户收货地址     |
| 🏭 **查基地**   | "这个产品从哪发货"                                                                                                    | 查询产品的发货基地    |
| 🖼️ **图片下单** | (发送订货单图片)                                                                                                     | OCR 识别订货单并下单 |

**首次引导时明确告知：**
> "我可以帮你：①**快速下单** ②查产品 ③**查客户列表** ④查/新增/修改地址 ⑤图片下单。需要什么？"

---

## 工作流程

### 阶段 1：解析用户意图

```
用户输入 → 识别意图类型
    ├─ 下单类 → 提取：客户、销售业务员、产品列表（每个产品包含编码、名称、数量）、发货基地、收货信息（运输方式、提货方式、收货地址ID、收货人、收货人电话）
    ├─ 查询产品类 → 见 #如何查询产品 模块
    ├─ 查询客户类 → 直接调用 xyfcli shop getdealercode
    ├─ 查地址类 → 获取客户收货地址信息
    │    1. 先通过 getsalercode 获取当前销售员编码
    │    2. 再通过 getdealercode 查找客户，获取客户编码
    │    3. 最后通过 getdealeraddresses 获取该客户的地址列表
    ├─ 查询基地库存类 → 调用 getstock 查询库存和子公司信息
    └─ 图片类 → 调用 OCR 解析订货单
```

### 阶段 2：并行验证（下单前验证）

并行执行所有前置验证（客户、业务员、产品、基地、库存、地址等）

✓ 全部通过 → 阶段 3  
✗ 有问题 → 一次性告知 + 提供解决方案

⚠️ 验证规则详见 [关键约束](#关键约束) 模块

### 阶段 3：汇总确认

验证结果 → 格式化展示（✓/✗标注）
         ↓
    用户确认 → xyfcli order place → 展示订单地址URL
    用户取消 → 结束
---

## 输入模式与处理

### 模式 1：完整信息下单

**触发**：用户一句话包含所有必要信息

**处理**：
1. 解析关键信息（客户、销售业务员、产品、数量、发货基地、收货信息）
2. 执行并行验证
3. 展示完整确认信息
4. 等待用户确认

**示例**：
```
用户："帮吉林市文英化肥经销有限责任公司下26吨Y14002510160020000，吉林新洋丰，汽运，统派车（客户付款），吉林省吉林市蛟河市公安局乌林派出所八家子警务室，邱文英，13394403131"

OpenClaw 自动验证并展示：
---
订单确认
---
客户：吉林市文英化肥经销有限责任公司 (J220000033) ✓
销售业务员：涂晓鹏 (EZB2019063) ✓
发货基地：吉林新洋丰 ✓
子公司：吉林新洋丰肥业有限公司
运输方式：汽运
提货方式：统派车（客户付款）
收货地址：吉林省吉林市蛟河市公安局乌林派出所八家子警务室 ✓
收货人：邱文英
收货人电话：13394403131
产品：Y14002510160020000 - 洋·高塔 51%(25-10-16)40KG 低氯 ✓
数量：26 吨
承运人信息：陈龙福 鄂 H08282 13872908039
---
确认下单？（回复"确认"或"取消"）
```

---

### 模式 2：部分信息下单

**触发**：用户提供部分信息（缺少基地/地址等）

**处理**：
1. 验证已有信息
2. 自动查询缺失信息的可选值
3. **一次性**展示所有缺失项及选项
4. 用户补充后继续

**示例**：
```
用户："帮吉林市文英化肥经销有限责任公司下26吨Y14002510160020000"

OpenClaw：
"产品验证通过 ✓
请补充以下信息：

1. 发货基地（选择一个）：
   [1] 吉林新洋丰
   [2] 长春配送中心

2. 运输方式（选择一个）：
   [1] 汽运
   [2] 铁运
   [3] 船运
   [4] 集装箱运输

3. 提货方式（选择一个）：
   [1] 自派车
   [2] 统派车（公司付款）
   [3] 统派车（客户付款）

4. 收货地址（选择一个）：
     [1] 湖北省荆门市东宝区泉口街道馨梦缘公寓
     [2] 甘肃省天水市秦安县叶堡镇新阳村

     如果没有合适的地址，可以[3]新增地址

5. 收货人（默认使用地址中的联系人，如需修改请提供）：
6. 收货人电话（默认使用地址中的电话，如需修改请提供）：

请按顺序回复，用逗号分隔。
例如："1,1,2,1"（使用默认收货人和电话）或 "1,1,2,1,张三,13800138000"（指定收货人和电话）"
```

**如果客户没有已保存的地址：**
```
✗ 该客户没有已保存的收货地址

请先到精准营销系统维护收货地址后再下单：
1. 登录精准营销系统
2. 进入客户管理 → 找到对应客户
3. 添加收货地址（省/市/区/详细地址/联系人/电话）
4. 维护完成后重新下单

精准营销系统地址：http://xxx.xxx.xxx
```

---

### 模式 3：搜索式下单

**触发**：用户需要浏览产品（"看看能买什么肥料"、"复合肥有哪些"）

**处理**：
1. 查询客户可购买的产品列表
2. 格式化展示（编号 + 产品编码 + 名称）
3. 用户选择后进入模式 1 或 2

**示例**：
```
用户："看看牛建建能买什么复合肥"

OpenClaw：
"找到 5 个复合肥产品：

[1] Y163U1305276020000 - 洋丰复合肥 45% 15-15-15
[2] Y163U1305276020001 - 洋丰复合肥 45% 16-16-16
[3] Y163U1305276020002 - 洋丰复合肥 40% 16-16-8
[4] Y163U1305276020003 - 洋丰复合肥 42% 18-12-12
[5] Y163U1305276020004 - 洋丰复合肥 38% 14-14-10

回复产品编号或编码，并告诉我数量。"
```

---

### 模式 4：订货单图片下单

**触发**：用户发送订货单/采购单图片

**处理**：
1. OCR 识别图片内容
2. 提取关键信息（客户、销售业务员、产品列表、发货基地、收货信息等）
3. 执行验证
4. 展示识别结果和验证状态
5. 用户确认后下单

**示例**：
```
用户：（发送订货单图片）

OpenClaw：
"订货单识别结果：
---
客户：吉林市文英化肥经销有限责任公司 ✓
销售业务员：涂晓鹏 ✓
发货基地：吉林新洋丰
子公司：吉林新洋丰肥业有限公司
运输方式：汽运
提货方式：统派车（客户付款）
收货地址：吉林省吉林市蛟河市公安局乌林派出所八家子警务室
收货人：邱文英
收货人电话：13394403131

产品列表：
| # | 产品编码 | 产品名称 | 数量 |
|---|----------|----------|------|
| 1 | Y14002510160020000 | 洋·高塔 51%(25-10-16)40KG 低氯 ✓ | 26 吨 |

---
以上信息是否正确？（确认/修改）"
```

---

### 模式 5：查询客户列表

**触发**：用户问"我有哪几个客户"、"查客户"、"客户列表"

**处理**：
1. 获取当前销售员编码
2. 查询客户列表
3. 格式化展示（表格形式，含余额）

**示例**：
```
用户："我有哪几个客户"

OpenClaw：
"你名下有 28 个客户：

| 编号 | 客户编码   | 客户名称       | 联系电话     | 地址     | 余额 (元)  |
|------|------------|----------------|--------------|----------|------------|
| 1    | J620522007 | 牛建建         | 18093818192  | 叶堡村   | 97044.01   |
| 2    | J620522010 | 甘谷县...      | 15693868887  | 磐安镇   | 383705.39  |
| 3    | J999000747 | 甘谷县...      | 13399386884  | 甘谷县...| 405057.93  |
...

要下单的话，直接告诉我：客户名称 + 产品 + 数量
例如："帮牛建建下 5 吨 Y163U1305276020000""
```

---
## 如何查询产品
### 方法 1
下单人提供描述信息后，通过xyfcli shop getproducturibydesc语义查询最接近的清单uri，然后通过xyfcli shop getproductdetailbyuri获取详细产品信息
### 方法 2
下单人提供描述信息后，通过xyfcli shop getproductlist 通过关键词匹配查询到产品信息
### 方法 3
下单人提供产品编号后通过xyfcli shop getgoodsinfo查到具体产品信息

## 如何查询基地库存和子公司
1. 获取客户编码：通过 `xyfcli shop getdealercode` 获取客户列表，选择对应的客户编码
2. 获取产品编号：通过 `xyfcli shop getproductlist` 或 `xyfcli shop getgoodsinfo` 获取产品编号
3. 获取发货基地编码：通过 `xyfcli shop getdeliverybase` 获取产品可发货的基地列表
4. 查询库存和子公司：调用 `xyfcli shop getstock` 查询产品在指定基地的库存信息和所属子公司名称

示例：
```bash
# 查询产品在指定基地的库存和子公司信息
xyfcli shop getstock -logincode "J620522007" -productcode "Y68000500000023100" -sendbase "10"
```

返回信息包含：
- `companyName`: 子公司名称
- `companyCode`: 子公司编码
- `productNum`: 库存数量
- `productName`: 产品名称
- `productCode`: 产品编号

## 关键约束

### 单订单约束（重要）

⚠️ **一个订单只能有一组以下信息**：
- 发货基地
- 收货地址
- 收货人
- 运输方式
- 提货方式
- 承运车主（不同承运人不能是同一个单）

如果订单包含多组不同的以上信息，**必须拆分成多个订单**。

**示例**：
```
用户：帮牛建建下10吨Y163U1305276020000到湖北，再下5吨到甘肃

✗ 不能在一个订单中下单（两个不同的收货地址）

需要拆分为两个订单：
订单1：10吨 → 湖北省荆门市东宝区
订单2：5吨 → 甘肃省天水市秦安县
```

### 地址验证（重要）

⚠️ **必须验证**：收货地址必须是客户已保存的地址（通过 `getdealeraddresses` 查询）

如果没有地址，可以：
1. 使用 `shop addaddress` 新增地址
2. 使用 `shop editaddress` 修改现有地址

```bash
# 获取客户已保存的地址列表
xyfcli shop getdealeraddresses "客户编码"

# 新增地址
xyfcli shop addaddress -dealercode "客户编码" -name "客户名称" -contact "联系人" -phone "电话" ...
```

**地址不存在时的处理：**
```
✗ 客户没有已保存的收货地址

我可以帮你新增地址，请提供：
- 联系人、联系电话、省市区、详细地址

或修改现有地址后重新下单。
```

⚠️ 现在可以直接通过 CLI 新增或修改地址，无需登录其他系统。

### 必传参数说明

⚠️ **以下7个参数为必传项，必须全部提供：**

1. **客户编码（`-dealer`）**：客户在系统中的唯一标识
2. **客户名称（`-name`）**：与客户编码对应的客户名称
3. **业务员编码（`-sales`）**：负责该客户的业务员编码
4. **商品编号（`-products`）**：商品编号列表，逗号分隔
5. **发货基地编码（`-base`）**：产品发货基地
6. **地址ID（`-addr-id`）**：系统中已保存的地址ID
7. **商品数量（`-q`）**：商品数量列表，逗号分隔，与商品编号一一对应

**可选参数（可直接回车跳过）：**
- `-transport` - 运输方式（默认：汽运）
- `-pickup` - 提货方式（默认：统派车）
- `-receiver` - 收货人（不传则使用地址中的默认值）
- `-phone` - 收货人电话（不传则使用地址中的默认值）

**校验规则：**
- 所有7个必传参数必须提供，缺一不可
- `-q` 数量必须与 `-products` 商品数量一一对应
- `-addr-id` 必须精确匹配系统中已保存的地址

### 运输方式和提货方式约束

⚠️ **只能选择以下选项：**

**运输方式（只能选择以下选项，下单时自动映射为代码）：**
- 汽运 → 01
- 铁运 → 02  
- 船运 → 03
- 集装箱运输 → 04

**提货方式（只能选择以下选项，自动映射为代码）：**
- 自派车 → Z001
- 统派车（客户付款） → Z002
- 统派车（公司付款） → Z003

其他选项无效，不接受自定义输入。

### 产品权限验证

⚠️ **必须验证**：只有 `getproductlist` 接口能查到的产品才能下单

```bash
# 精确验证（验证客户是否有权购买此产品）
xyfcli shop getproductlist -dealercode "客户编码" -search "产品编码"

# 模糊查询（查询客户可购买的产品清单）
xyfcli shop getproductlist -dealercode "客户编码" -search "45% 复合肥 15-15-15"
# ↑ 只有在返回的产品清单中才能下单
```

### 产品基地库存验证

⚠️ **必须验证**：只有库存大于下单数量的基地才能下单

```bash
# 查询产品基地库存
xyfcli shop getstock -logincode "客户编码" -productcode "产品编码" -sendbase "基地编码"

# 返回示例：
# {"stock": 100, "base_name": "新洋丰中磷", "subsidiary": "湖北新洋丰"}
# ↑ stock 必须 >= 下单数量才能选择该基地
```

### 错误处理原则

1. **一次性告知**：所有问题一次性列出，不要逐个追问
2. **提供选项**：出错时给出可选方案（如相似产品、其他基地）
3. **清晰标注**：用 ✓/✗ 标注验证状态


### 错误处理示例

**场景 1：产品不可用**
```
✗