@optima-chat/commerce-cli 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,13 +5,9 @@ description: Order fulfillment and shipping management. Process orders, ship pac
5
5
 
6
6
  # Commerce CLI - Order Fulfillment
7
7
 
8
- ## Overview
9
-
10
8
  订单履行模块,用于处理订单、发货、售后和物流跟踪。
11
9
 
12
- ## Instructions
13
-
14
- ### 自然语言映射
10
+ ## 典型场景
15
11
 
16
12
  当用户说:
17
13
  - "查看待发货订单" → `commerce order list --status paid`
@@ -21,9 +17,102 @@ description: Order fulfillment and shipping management. Process orders, ship pac
21
17
  - "查询运费" → `commerce shipping calculate --country XX --weight YY`
22
18
  - "处理退款" → `commerce refund create --order-id XX --amount YY`
23
19
 
24
- ### 核心功能
20
+ ### 场景决策表
21
+
22
+ | 用户需求 | 推荐命令 | 关键注意点 |
23
+ |---------|---------|-----------|
24
+ | 查看待发货订单 | `order list --status paid` | 按付款时间升序,优先处理早期订单 |
25
+ | 批量发货 | 循环 `order ship` | 必须有真实tracking号,避免虚假发货 |
26
+ | 取消订单 | `order cancel --yes` | 检查是否已发货,避免错误取消 |
27
+ | 处理退款 | `refund create` → `refund approve` | 先创建后审批,保留审计记录 |
28
+ | 运费查询 | `shipping calculate` | 提供准确重量和邮编,避免运费纠纷 |
29
+ | 物流异常 | `shipping track` → `shipping update-status` | 主动更新状态,及时通知客户 |
30
+
31
+ ### 标准订单履行流程
32
+ 1. **查看待发货** - `commerce order list --status paid` 按时间升序
33
+ 2. **验证订单** - 检查库存、地址、特殊要求
34
+ 3. **批量打包** - 准备商品、包装材料、打印面单
35
+ 4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY --carrier ZZ`
36
+ 5. **物流跟踪** - 定期 `commerce shipping track` 监控异常
37
+ 6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`
38
+
39
+ ### 退款处理流程
40
+ 1. **创建退款** - `commerce refund create` 填写详细原因
41
+ 2. **审核评估** - 检查商品状态、退货凭证、历史记录
42
+ 3. **批准/拒绝** - `commerce refund approve/reject` 并通知客户
43
+ 4. **跟踪反馈** - 记录退款原因,优化产品和服务
44
+
45
+ ## 卓越标准
46
+
47
+ ### 订单处理质量指标
48
+ - **发货及时性**: 付款后24小时内发货(标品),48小时内发货(定制品)
49
+ - **物流信息准确性**: 100%订单有tracking number,无虚假单号
50
+ - **客户满意度**: 退款率 < 5%,客服投诉响应 < 2小时
51
+ - **订单完成率**: 取消率 < 3%,拒收率 < 2%
52
+
53
+ ### 订单状态管理原则
54
+ - **3-5-7原则**: 3分钟确认订单,5小时内完成打包,7天内跟踪售后
55
+ - **自动化优先**: 批量处理相同状态订单,优先处理付款时间早的订单
56
+ - **数据完整性**: 发货前验证库存、收货地址、物流商可达性
57
+ - **客户沟通**: 关键状态变更后及时通知(发货、延迟、退款、取消)
58
+ - **审计留痕**: 所有操作记录原因和操作人,便于问题追溯
59
+
60
+ ## 常见问题
61
+
62
+ ### 批量发货错误
63
+
64
+ ❌ **危险做法 - 不验证就批量发货**:
65
+ ```bash
66
+ # 可能发错货或虚假发货
67
+ for order_id in $(commerce order list --status paid --json | jq -r '.[].id'); do
68
+ commerce order ship --id $order_id --tracking FAKE123 --carrier DHL
69
+ done
70
+ ```
71
+
72
+ ✅ **正确做法 - 先验证再批量发货**:
73
+ ```bash
74
+ # 先查看订单列表
75
+ commerce order list --status paid
76
+
77
+ # 准备好所有真实tracking号后,逐个发货
78
+ commerce order ship --id order_123 --tracking DHL123456 --carrier DHL
79
+ commerce order ship --id order_456 --tracking DHL123457 --carrier DHL
80
+ commerce order ship --id order_789 --tracking DHL123458 --carrier DHL
81
+ ```
82
+
83
+ ### 订单取消场景
84
+
85
+ ❌ **错误操作 - 已发货还取消**:
86
+ - 不检查订单状态直接取消,导致客户收到货但订单已取消
87
+
88
+ ✅ **正确处理**:
89
+ - **客户主动取消** → 检查是否已发货,未发货立即取消
90
+ - **地址错误无法送达** → 联系客户更新地址或取消退款
91
+ - **库存不足** → 立即通知客户,协商补货或退款
92
+
93
+ ### 退款处理错误
94
+
95
+ ❌ **错误流程 - 直接批准未审核的退款**:
96
+ - 不检查商品状态、退货凭证就批准,容易被恶意退款
97
+
98
+ ✅ **正确流程**:
99
+ - **商品质量问题** → 无需退货,直接全额退款
100
+ - **客户不满意** → 要求退货,收到货后退款
101
+ - **物流丢失** → 联系物流商理赔,先行退款给客户
102
+
103
+ ### 物流延迟处理
104
+
105
+ ❌ **错误做法 - 不主动通知客户**:
106
+ - 物流延迟不告知客户,导致客户投诉和差评
107
+
108
+ ✅ **正确处理**:
109
+ - **国内延迟 > 3天** → 主动联系客户说明情况
110
+ - **国际延迟 > 7天** → 提供物流追踪链接,协商解决方案
111
+ - **物流丢失** → 联系物流商查询,必要时补发或退款
112
+
113
+ ## 命令参考
25
114
 
26
- **订单管理**:
115
+ ### 订单管理
27
116
  - `commerce order list` - 查看订单列表
28
117
  - `commerce order get` - 查看订单详情
29
118
  - `commerce order ship` - 标记订单发货
@@ -31,19 +120,19 @@ description: Order fulfillment and shipping management. Process orders, ship pac
31
120
  - `commerce order complete` - 完成订单
32
121
  - `commerce order mark-delivered` - 标记已送达
33
122
 
34
- **退款管理**:
123
+ ### 退款管理
35
124
  - `commerce refund create` - 创建退款
36
125
  - `commerce refund list` - 查看退款列表
37
126
  - `commerce refund get` - 查看退款详情
38
127
  - `commerce refund approve` - 批准退款
39
128
  - `commerce refund reject` - 拒绝退款
40
129
 
41
- **物流管理**:
130
+ ### 物流管理
42
131
  - `commerce shipping calculate` - 计算运费
43
132
  - `commerce shipping track` - 物流追踪
44
133
  - `commerce shipping update-status` - 更新物流状态
45
134
 
46
- ## Examples
135
+ ## 详细示例
47
136
 
48
137
  ### 查看待处理订单
49
138
  ```bash
@@ -102,7 +191,7 @@ commerce refund approve --id refund_456
102
191
  commerce shipping track --tracking-number DHL123456
103
192
  ```
104
193
 
105
- ## Notes
194
+ ## 重要提示
106
195
 
107
196
  - 订单状态流转:pending → paid → shipped → delivered → completed
108
197
  - 取消和删除操作需要 `--yes` 确认
@@ -5,11 +5,180 @@ description: Product catalog management for e-commerce stores. Create and update
5
5
 
6
6
  # Commerce CLI - Product Management
7
7
 
8
- ## Overview
9
-
10
8
  商品管理模块,用于电商商品目录的创建、编辑和组织。
11
9
 
12
- ## Instructions
10
+ ## 典型场景
11
+
12
+ ### 场景1:单个商品上架
13
+ **流程**: 准备素材 → 上传图片 → 创建商品 → 验证
14
+ ```bash
15
+ # 1. 上传商品图片
16
+ commerce upload image --path ./tshirt-main.jpg # 获得 media_123
17
+
18
+ # 2. 创建商品
19
+ commerce product create \
20
+ --title "纯棉T恤" \
21
+ --price 99 \
22
+ --stock 20 \
23
+ --description "100% 纯棉,舒适透气" \
24
+ --media-id media_123
25
+ ```
26
+
27
+ ### 场景2:多规格商品上架
28
+ **流程**: 创建主商品 → 创建所有变体 → 关联图片
29
+ ```bash
30
+ # 1. 创建主商品
31
+ commerce product create --title "T恤" --price 99
32
+ # 获得 product_id: prod_123
33
+
34
+ # 2. 创建所有变体
35
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
36
+ --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50
37
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
38
+ --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 50
39
+ commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
40
+ --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
41
+ ```
42
+
43
+ ### 场景3:批量商品导入
44
+ **流程**: 先上传共享资源 → 循环创建商品
45
+ ```bash
46
+ # 1. 上传品牌logo(所有商品共享)
47
+ commerce upload image --path ./brand-logo.jpg # 获得 media_shared
48
+
49
+ # 2. 批量创建商品(复用media_id)
50
+ for product in "T恤" "衬衫" "卫衣"; do
51
+ commerce product create --title "$product" --price 99 --media-id media_shared
52
+ done
53
+ ```
54
+
55
+ ### 场景4:促销活动准备
56
+ **任务**: 批量更新价格和标签
57
+ ```bash
58
+ # 1. 查找目标商品
59
+ commerce product list --query "T恤" --limit 50
60
+
61
+ # 2. 批量更新价格和促销标签
62
+ commerce product update --id prod_123 --price 79 --tags "featured,sale"
63
+ commerce product update --id prod_456 --price 79 --tags "featured,sale"
64
+ ```
65
+
66
+ ### 场景5:商品图片更新
67
+ **任务**: 更换主图或添加详情图
68
+ ```bash
69
+ # 1. 上传新图片
70
+ commerce upload image --path ./new-photo.jpg # 获得 media_new
71
+
72
+ # 2. 添加到商品
73
+ commerce product add-images --id prod_123 --media-id media_new
74
+ ```
75
+
76
+ ### 场景决策表
77
+
78
+ | 用户需求 | 推荐命令 | 关键注意点 |
79
+ |---------|---------|-----------|
80
+ | 单个商品 | `product create` | 先上传图片,准备好所有必填字段 |
81
+ | 多规格商品 | `product create` + `variant create` | 主商品设置基础价格,变体设置差异价 |
82
+ | 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id,避免重复上传 |
83
+ | 更新价格 | `product update --price` | 如有变体,需逐个更新变体价格 |
84
+ | 促销标签 | `product update --tags` | 用逗号分隔,保留原有标签 |
85
+ | 图片更新 | `upload` + `add-images` | 先上传再关联,不要直接删除旧图 |
86
+
87
+ ## 卓越标准
88
+
89
+ ### 商品质量维度
90
+ - **图片质量**: 至少3张不同角度,主图尺寸 ≥ 1200x1200px
91
+ - **描述完整性**: 必填字段100%填写,描述文字 ≥ 50字
92
+ - **SEO优化**: 标题包含核心关键词,使用3-5个相关标签
93
+ - **变体规范**: 使用统一的attributes key(如"颜色"、"尺寸"),避免同义词混用
94
+ - **库存准确**: 创建时设置真实库存,避免超卖和缺货
95
+
96
+ ### 上架流程原则
97
+ - **图片先行**: 先批量上传所有图片获取media_id,再创建商品(避免重复上传)
98
+ - **主商品后变体**: 先创建主商品获取product_id,再创建所有变体
99
+ - **数据完整性**: 每个变体必须有独立SKU、库存、价格
100
+ - **标签策略**: 精选(featured)、新品(new)、促销(sale)等核心标签要及时更新
101
+
102
+ ### 质量检查清单
103
+ - [ ] 商品标题简洁有力,包含关键词
104
+ - [ ] 描述文字 ≥ 50字,突出卖点
105
+ - [ ] 至少3张图片,主图清晰
106
+ - [ ] 价格和库存准确无误
107
+ - [ ] 变体SKU不重复
108
+ - [ ] 标签使用合理(3-5个)
109
+
110
+ ## 常见问题
111
+
112
+ ### ❌ 问题1:重复上传图片
113
+ **错误做法**:
114
+ ```bash
115
+ # 每个商品都上传相同的logo
116
+ for product in products; do
117
+ commerce upload image --path ./logo.jpg
118
+ commerce product create --title "$product" --media-id $NEW_ID
119
+ done
120
+ ```
121
+
122
+ **正确做法**:
123
+ ```bash
124
+ # 先上传一次,复用media_id
125
+ commerce upload image --path ./logo.jpg # 获得 media_123
126
+ for product in products; do
127
+ commerce product create --title "$product" --media-id media_123
128
+ done
129
+ ```
130
+
131
+ ### ❌ 问题2:忘记创建变体
132
+ **症状**: 多规格商品只有主商品,无法选择颜色/尺寸
133
+ **解决**: 创建主商品后,立即创建所有变体
134
+
135
+ ```bash
136
+ # 错误:只创建主商品
137
+ commerce product create --title "T恤" --price 99
138
+
139
+ # 正确:创建主商品 + 所有变体
140
+ commerce product create --title "T恤" --price 99 # 获得 prod_123
141
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" ...
142
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" ...
143
+ ```
144
+
145
+ ### ❌ 问题3:变体attributes不一致
146
+ **症状**: 规格筛选混乱,如"颜色"、"color"、"Color"混用
147
+ **解决**: 统一使用中文或英文,全局保持一致
148
+
149
+ ```bash
150
+ # 错误:同义词混用
151
+ --attributes '{"颜色":"红色"}'
152
+ --attributes '{"color":"蓝色"}'
153
+
154
+ # 正确:统一使用
155
+ --attributes '{"颜色":"红色"}'
156
+ --attributes '{"颜色":"蓝色"}'
157
+ ```
158
+
159
+ ### ❌ 问题4:批量更新时覆盖标签
160
+ **症状**: 更新标签时把原有标签清空
161
+ **解决**: 先查看原有标签,追加新标签
162
+
163
+ ```bash
164
+ # 错误:直接覆盖
165
+ commerce product update --id prod_123 --tags "sale" # featured标签丢失
166
+
167
+ # 正确:先查看再追加
168
+ commerce product get --id prod_123 # 查看原有标签: featured,new
169
+ commerce product update --id prod_123 --tags "featured,new,sale"
170
+ ```
171
+
172
+ ### ❌ 问题5:库存设置不准确
173
+ **症状**: 超卖或缺货
174
+ **解决**: 创建时设置真实库存,定期同步ERP数据
175
+
176
+ ```bash
177
+ # 先确认真实库存,再创建
178
+ commerce product create --title "T恤" --price 99 --stock 50 # 确保真实有50件
179
+ ```
180
+
181
+ ## 命令参考
13
182
 
14
183
  ### 自然语言映射
15
184
 
@@ -41,9 +210,9 @@ description: Product catalog management for e-commerce stores. Create and update
41
210
  - `commerce product add-images` - 关联图片到商品
42
211
  - `commerce product remove-images` - 移除商品图片
43
212
 
44
- ## Examples
213
+ ## 详细示例
45
214
 
46
- ### 创建商品
215
+ ### 示例1:创建单个商品
47
216
  ```bash
48
217
  # 用户说:"创建T恤商品,99美元,库存20"
49
218
  commerce product create \
@@ -53,7 +222,7 @@ commerce product create \
53
222
  --description "100% 纯棉T恤"
54
223
  ```
55
224
 
56
- ### 上传商品图片
225
+ ### 示例2:上传商品图片
57
226
  ```bash
58
227
  # 用户说:"上传商品主图"
59
228
  commerce upload image --path ./tshirt-main.jpg
@@ -65,7 +234,7 @@ commerce product add-images \
65
234
  --media-id media_123
66
235
  ```
67
236
 
68
- ### 创建商品变体
237
+ ### 示例3:创建商品变体
69
238
  ```bash
70
239
  # 用户说:"给商品添加红色S码的变体"
71
240
  commerce variant create \
@@ -76,7 +245,7 @@ commerce variant create \
76
245
  --attributes '{"颜色":"红色","尺寸":"S"}'
77
246
  ```
78
247
 
79
- ### 管理商品标签
248
+ ### 示例4:管理商品标签
80
249
  ```bash
81
250
  # 用户说:"把商品标记为精选和新品"
82
251
  commerce product update \
@@ -87,7 +256,7 @@ commerce product update \
87
256
  commerce product list --tags "featured"
88
257
  ```
89
258
 
90
- ### 批量更新价格
259
+ ### 示例5:批量更新价格
91
260
  ```bash
92
261
  # 用户说:"把所有T恤价格改成89"
93
262
  # 1. 先查找T恤商品
@@ -98,7 +267,35 @@ commerce product update --id prod_123 --price 89
98
267
  commerce product update --id prod_456 --price 89
99
268
  ```
100
269
 
101
- ## Notes
270
+ ### 示例6:完整的多规格商品上架
271
+ ```bash
272
+ # 完整流程演示
273
+ # 1. 上传图片
274
+ commerce upload image --path ./tshirt-red.jpg # media_red
275
+ commerce upload image --path ./tshirt-blue.jpg # media_blue
276
+
277
+ # 2. 创建主商品
278
+ commerce product create --title "纯棉T恤" --price 99
279
+ # 获得 product_id: prod_123
280
+
281
+ # 3. 创建变体
282
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
283
+ --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50
284
+
285
+ commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
286
+ --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 30
287
+
288
+ commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
289
+ --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 40
290
+
291
+ # 4. 关联图片
292
+ commerce product add-images --id prod_123 --media-id media_red,media_blue
293
+
294
+ # 5. 验证
295
+ commerce product get --id prod_123
296
+ ```
297
+
298
+ ## 重要提示
102
299
 
103
300
  - 所有命令默认 JSON 输出,便于 AI 解析
104
301
  - 图片需要先上传获取 `media_id`,再关联到商品
@@ -106,3 +303,5 @@ commerce product update --id prod_456 --price 89
106
303
  - 标签使用逗号分隔的字符串
107
304
  - 支持的图片格式:JPG, PNG, WebP
108
305
  - 使用 `--help` 查看命令详细参数
306
+ - 删除商品会同时删除所有变体和图片关联
307
+ - 价格单位默认为美元(USD),可通过后台配置修改