shoplazza-orders

shoplazza CLI — 订单模块

重要 — 首先使用 Read 读取 ../shoplazza-common/SKILL.md。 其中定义了所有跨领域机制：三个访问层级、输出封装（.data）、 --dry-run、--jq（包括“不要传入 -r”）、--fields、schema、 api rest、身份验证 / 配置文件以及安全协议。本文件仅涵盖订单领域，不会重复这些内容。

概述

orders 模块用于管理订单生命周期（搜索、计数、获取、创建、更新、取消、 付款、删除）及其子资源：履约（配送记录）、退款、欺诈风险、 支付交易、售后记录、配送区域 / 费率以及物流承运商。三个访问层级均适用（层级选择 规则见 shoplazza-common — 优先使用 +shortcut）。

仅 +search / +count / +ship / +refund / +update-tracking 提供快捷方式 — 其他所有操作（获取、取消、创建、付款以及所有子资源）均为规范叶节点。 订单是一个大型领域：本文件是路由器，并包含高频操作； 各子资源的详细内容见 references/。

命令索引

意图 → 命令，按匹配度从高到低排列。权威的标志/参数请查阅 shoplazza orders <cmd> --help 和 shoplazza schema orders.<cmd>，而非此表。

用户意图	命令
搜索/筛选订单	orders +search [--email <addr>] [--keyword <no/name/email>] [--status …] [--financial-status …] [--fulfillment-status …] [--customer-id <id>] [--since <t>] [--until <t>]
统计订单数量	orders +count — 筛选条件与 +search 相同，但不包括 --page-limit
发货	orders +ship --order-id <id> --tracking <no> [--company <name>] [--company-code <code>] [--line-items id:qty,…] [--notify]
为买家退款（退款；资金操作 → 先使用 --dry-run）	orders +refund --order-id <id> --amount <n> [--note <txt>] [--return-items] [--payment-line-id <id>]
修正/更新追踪信息	orders +update-tracking --order-id <id> --fulfillment-id <id> --tracking <no> [--company <name>] [--tracking-url <url>] [--notify]
按内部 ID 获取单个订单	orders get --params '{"order_id":"<id>"}'
按订单号（#…）获取订单	orders get-by-number --params '{"number":"<number>"}'
使用 +search 不支持的筛选条件列出订单（多状态数组、ID、SKU、标签、模糊搜索……）	orders list --params '{…}'（参见 schema orders.list）
代表客户创建订单（手工建单/代客下单）	orders create --data '{"order":{…}}' — 嵌套请求体较复杂 → references/orders-create.md
更新订单备注/标签/收货地址	orders update --params '{"order_id":"<id>"}' --data '{"order":{…}}'
取消订单（破坏性操作 → 先使用 --dry-run）	orders cancel --params '{"order_id":"<id>"}' [--data '{"reason":"…"}']
将订单标记为已付款	orders pay --params '{"order_id":"<id>"}' --data '{"payment_line":{"payment_channel":"<channel>","payment_method":"<method>","transaction_no":"<txn>"}}' — 空请求体会生成虚假的 TEST 付款；实际渠道/方式/交易号填写在 payment_line 中，自定义显示名称填写在 gateway 中（schema orders.pay）
删除订单（破坏性操作 → 先使用 --dry-run）	orders delete --params '{"order_id":"<id>"}'
履约记录 CRUD / 取消 / 完成	orders fulfillments … → references/fulfillments.md
退款记录（单个订单/整个店铺/完成退款）	orders refunds … → references/refunds.md
欺诈风险记录（标记高风险）	orders risks … → references/risks.md
订单付款交易流水（支付流水）	orders transactions list --params '{"order_id":"<id>"}' → references/transactions.md
售后记录	orders post-sales … → references/post-sales.md
配送区域/费率/可用线路（运费区域）	orders shipping-schemas … → references/shipping-schemas.md
查询追踪号码对应的承运商（承运商识别）	orders tracking-carriers detect --params '{"tracking_number":"<no>"}' → references/tracking-carriers.md

执行请求

“发货 / 退款 / 取消订单 / ship / refund / cancel”属于操作，而不是问题：

1. 通过下方的触发词表，将意图匹配到快捷操作（子资源末级操作见 references/）。
2. 检查必填字段（各快捷操作中标记为 无默认值 的参数）。缺失或含糊不清时 → 使用 AskUserQuestion 提问，绝不捏造——尤其是 --amount（金额）和 --tracking（真实世界的物流单号，不能凭空编造）。将缺失字段合并到同一批次的 一个问题中。
3. **绝不要询问有 CLI 默认值或可通过省略来禁用的参数。**采用默认值。
4. 所有必填项均已提供 → 按 shoplazza-common 的安全要求执行：
   • +refund 会转移资金——必须先使用 --dry-run，用通俗语言重述操作内容 （哪个订单、金额、备注、是否退回库存），等待用户同意后再实际执行。
   • 具有破坏性的末级操作（orders cancel / orders delete / fulfillments cancel / risks delete / post-sales delete / shipping-schemas delete-zone）——先使用 --dry-run， 再重述操作内容，等待用户同意后执行。
   • orders pay 会写入付款记录——与 +refund 一样处理：先使用 --dry-run， 再重述操作内容（哪个订单、渠道、交易编号），等待用户同意。 绝不要发送空请求体——空请求体会悄悄记录一笔虚假的 TEST 付款。 payment_line 的 payment_channel / payment_method / transaction_no 是自由 字符串，而不是枚举值——根据用户的措辞填写（例如“走的 PayPal” → "payment_channel":"paypal","payment_method":"paypal"），transaction_no 按原样填写； 不要因为需要选择枚举值而暂停操作并提问。
   • 确认必填值后，可直接安全执行 +ship / +update-tracking / +search / +count。

触发短语 → 快捷方式

用户说	快捷方式	如何提取值
查订单 / 找订单 / 今天有没有新订单 / 搜索或列出订单	+search	已知邮箱 → --email；部分姓名 / 订单号片段 / 其他内容 → --keyword；“今天/最近 N 天” → 仅用 --since（--until 留空）；状态词 → 下方枚举表
还没发货的订单 / 未发货的订单	+search --fulfillment-status waiting	未发货 = waiting — 没有 unfulfilled 这个值
某客户 / 某邮箱的订单 / 客户 X 的订单	+search	客户 ID → --customer-id；完整邮箱地址 → --email（精确匹配，这是精确路径）；若有专用标志，绝不要将 ID 或地址塞进 --keyword
有多少订单 / 订单总数 / 订单数量	+count	“总共” = 不添加筛选条件，不要询问时间范围；从 .data.count 获取数量
发货 / 标记发货 / 发货订单 X	+ship	运单号 → 原样填入 --tracking；承运商名称 → --company；“通知买家” → --notify；发货整个订单 = 省略 --line-items
部分发货 / 只发部分商品	+ship --line-items id:qty,…	每个订单项的数量以 line-id:qty 键值对表示
退款 / 给买家退 X 元 / 给买家退款	+refund	金额 → 原样填入 --amount；说明的原因 → --note；“库存退回去/补回库存” → --return-items
改运单号 / 运单号填错了 / 修正运单号	+update-tracking	三项都需要：--order-id、--fulfillment-id、--tracking
订单号 #… 的详情 / 按订单号查找订单	get-by-number（叶节点）	去掉开头的 # → --params '{"number":"…"}'；内部 ID 应使用 get
手工建单 / 代客下单 / 为客户创建订单	create（叶节点）	order 下包含大量嵌套内容 → references/orders-create.md；通过 products +search 解析 variant_id；绝不要编造买家身份、地址或价格
取消订单 / 取消订单 X	cancel（叶节点）	ID → --params；说明的原因 → --data '{"reason":"…"}'（可选）；不是 fulfillments cancel
取消发货记录 / 取消一条发货记录	fulfillments cancel（叶节点）	--params 中要同时包含 order_id 和 fulfillment_id；不是 orders cancel
标记高风险 / 像欺诈单 / 标记为欺诈	risks create（叶节点）	高/中/低 → level high/medium/low；说明的原因 → details 数组 → references/risks.md
订单支付流水 / 支付交易	transactions list（叶节点）	订单 ID → --params；这是买家付款，不是账单
运单号 X 是哪家承运商 / 查询承运商	tracking-carriers detect（叶节点）	--params '{"tracking_number":"…"}' — 不要使用 list 后再手动匹配
设置运费区域 / 邮费 / 配送区域和费率	shipping-schemas 叶节点	→ references/shipping-schemas.md

如果匹配多行，询问用户要选哪一个。不要猜测。

必须询问与可推断对照表

只有没有默认值的标志可以询问。

快捷操作	用户未指定时必须询问	尽可能推断	静默使用默认值
+refund	--amount（金额——绝不可捏造；对于全额退款，可以提出通过 orders get 查询订单总额，但仍须确认金额）；缺失时询问 --order-id	根据用户说明的原因推断 --note；根据库存退回/restock 的措辞推断 --return-items	--payment-line-id（仅当订单有多条付款明细时才需要——CLI 会报错并列出候选项；届时选择或询问）
+ship	--tracking（绝不可编造追踪号）；缺失时询问 --order-id	根据用户提到的承运商推断 --company（保留用户的命名）；根据通知买家的措辞推断 --notify	--line-items（省略 = 所有可履行的商品）、--company-code
+update-tracking	缺失的 --order-id / --fulfillment-id / --tracking	仅在用户提供时填写 --company、--tracking-url	--notify（仅在用户明确要求重新通知时设置）
+search / +count	（无需询问——所有筛选条件均为可选；绝不询问）	根据措辞，通过枚举表推断筛选条件	--page-limit；时间范围仅根据用户自己的时间表述设置
cancel（叶节点）	缺失时询问订单 ID	仅当用户说明了原因时，填写 reason 正文	reason（可选——未提供时省略）
create（叶节点）	缺失的任何必需买家/地址子字段（last_name、email、country_code、province_code、city、address、zip）以及商品项——绝不可捏造身份、地址或价格；询问或通过 products +search 查询 variant_id	从商店推断 currency_code（shop info get --jq '.data.currency'）；使用中性的 shipping_name 标签（"标准配送"）；省略目录中的 price（由变体定价）	通知标志、tags、note、discount_application、payment_line（通过 orders pay 记录付款）

绝不询问清单

具有 CLI 默认值或省略即可禁用的标志——绝不会在问题中出现： --notify（除非用户要求通知，否则省略） · --line-items（默认：所有可履行的商品） · --company / --company-code（可选的承运商信息） · --payment-line-id（仅在出现多条 付款明细错误后询问） · --note（仅在用户说明了原因时填写） · --return-items（仅在用户 明确提出时填写） · --tracking-url · --page-limit · --since / --until（仅根据 用户自己的时间表述设置——绝不编造时间范围）。

决策示例

用户说	判断
"订单 111222 退 15.50 给买家，备注 wrong size，库存退回"	REFUND — +refund --order-id 111222 --amount 15.50 --note "wrong size" --return-items；先运行 --dry-run，复述操作内容，等待用户确认后再执行
"给订单 333444 退个款"	ASK — 退款金额（金额绝不能臆造）。不要询问订单号——用户已在表述中提供。可以提出查询全额退款金额，但仍须确认
"订单 555 可以发货了，运单号 YT123，中通，通知买家"	SHIP — +ship --order-id 555 --tracking YT123 --company 中通 --notify；可直接安全执行
"把订单 666 标记发货"	ASK — 询问运单号（必填，绝不能编造）；承运商为可选项，可一并询问，但不要因此阻止后续操作
"找最近 7 天还没发货的订单"	SEARCH — +search --fulfillment-status waiting --since <today-7d>；不使用 --until
"取消订单 777，原因是买家申请"	CANCEL — orders cancel --params '{"order_id":"777"}' --data '{"reason":"买家申请"}'；先运行 --dry-run 并复述操作内容
"订单 888 像欺诈单，标成高风险"	RISK — orders risks create --params '{"order_id":"888"}' --data '{"risk":{"level":"high","details":["…"]}}'；写入前复述操作内容
"手工帮客户下个单：1 件 variant V123，单价 29.9，寄给 John Doe ([email protected])，美国加州洛杉矶 123 Main St 90012"	CREATE — 构建嵌套的 order 请求体（line_items 包含 variant_id、quantity 和 price，完整的 shipping_address 包含 province_code，以及 shipping_line、tax_total、currency_code），复述操作内容并先运行 --dry-run → 参考资料/orders-create.md
"帮客户下个单"（未提供商品／买家信息）	ASK — 询问 variant 和数量，以及买家的配送信息（姓名、电子邮件、地址）；绝不臆造。shipping_price／tax_total 属于金额——使用用户提供的金额；只有在用户表示无需收费时才能使用 "0.00"，并复述这一点

状态枚举（记住这三种）

来自 schema orders.list——供 +search / +count / list 使用：

字段	值
--status（订单）	opened（待付款） · placed（进行中） · finished · cancelled
--financial-status	waiting · paying · authorized · partially_paid · paid · cancelled · failed · refunding · refund_failed · refunded · partially_refunded
--fulfillment-status	initialled · waiting（未发货 / waiting to ship） · partially_shipped · shipped · partially_finished · finished · cancelled · returning · partially_returned · returned

unfulfilled / fulfilled 不是有效值——“还没发货”对应 waiting。 每个快捷标志只接受一个值；若要同时筛选多个值，请使用 list 叶节点，其 status / financial_status / fulfillment_status 参数接受 JSON 数组。 时间范围——使用哪个字段。 +search --since/--until 限定的是下单时间 （placed_at_min/placed_at_max），格式为 ISO 日期或 Unix 时间戳——这是销售时间，也是正确的默认选项。若要按其他时间筛选，请使用 list 叶节点，它为每个时间字段提供一组 _min/_max 参数；根据用户的动词选择：

用户的表述	参数
下单 / 支付 / 成交 / 售出 / 卖 / 卖了多少 / 销量 / 销售额 / placed / paid / sold	placed_at_min / placed_at_max
创建 / 新增 / created	created_at_min / created_at_max
更新 / 修改 / 最后交互 / updated / last changed	updated_at_min / updated_at_max
完成 / 订单完成 / finished	finished_at_min / finished_at_max
发货完成 / 履约完成 / fulfilled	fulfilled_at_min / fulfilled_at_max

created_at ≠ placed_at（很容易弄错）。 Shoplazza 订单记录会在买家进入结账流程时创建——早于付款，因此 created_at 也会统计已放弃 / 未付款的购物车。placed_at 表示订单实际下单（已付款）的时间。对于衡量实际销售额的任何查询（销量 / 卖了多少 / 成交量 / 销售额 / how much sold），都应筛选 placed_at_*，而不是 created_at_*，否则会把已放弃的购物车也计入数量。只有当用户明确询问创建 / 新增了多少订单时，才使用 created_at_*。如果完全没有表示时间的动词：若存在 financial_status 或 fulfillment_status 筛选条件，意图就是查询销售数据 → 使用 placed_at_*；否则使用 created_at_*。

重述解析后的时间范围。 将相对时间表述（最近 7 天 / 这个月）转换为 --since / --until 时，告知用户所用的具体时间范围（例如 2026-09-10 至 2026-09-17）——这样边界或时区错误就会显现，而不是悄悄导致计数偏差。

精确搜索订单

orders list 提供三种方式来匹配同一字段。选择最能表达请求的最精确方式——用本领域的术语来说，就是 shoplazza-common 的精度阶梯：

层级	参数	适用情况
精确匹配数组	customer_emails、shipping_emails、shipping_phones、order_tags、skus、spus、product_ids、browser_ips、ids	你拥有完整值。+search --email 是 customer_emails 的快捷方式。
关键词	keyword（可选使用 keyword_scope_fields 缩小搜索字段范围）	只有片段，或用户没有说明具体字段。+search --keyword 对应此项。
模糊三元组	fuzzy_fields + fuzzy_keywords + fuzzy_relation	在指定字段上进行前缀 / 片段匹配，或对多个字段组合使用 AND/OR。仅限叶节点。

keyword_scope_fields 和 fuzzy_fields 使用相同的词汇——字段名称列表可在 schema orders.list --view request 的 fuzzy_fields 下找到（name、number、id、 shipping_email、tracking_number、discount_code 等）。请在那里查看，不要猜测。

边界

看起来像订单操作、实际上属于其他领域的事项（以及本领域负责的相似事项）：

看起来像	实际属于	命令
退款 / 给顾客退钱 / refund a buyer	本领域（不是折扣——折扣/优惠码用于计算购物车价格；也不是账单——那是应用收费）	orders +refund
订单支付流水 / buyer payment transactions	本领域	orders transactions list
应用收费流水 / app-charge transactions billed to the merchant	shoplazza-billing	billing transactions
快递承运商查询 / 运单号识别 / tracking carrier lookup	本领域	orders tracking-carriers {detect,list}
注册实时运费报价承运商 / real-time rate quote carriers	shoplazza-shop	shop carrier-services
运费区域 / 邮费方案 / shipping zones & rates	本领域	orders shipping-schemas …
按邮箱查某客户的订单 / a customer's orders	本领域（+search --email <addr> 或 --customer-id）	先通过 customers +search 查询 ID 也可以——最终查询仍然是订单查询
客户资料本身 / the customer record	shoplazza-customers	customers +search / customers get
库存 / 补货 / product stock	shoplazza-products	products +stock / products inventory
退款时库存退回 / restock on refund	本领域	orders +refund --return-items

权限 · 范围

授权按领域（即 --domain 的单位）进行，而非按命令进行。授权流程见 shoplazza-common → Authentication。

操作	需要	授权方式
读取（get / get-by-number / list / +search / +count / 子资源读取）	orders 读取范围	auth login --domain orders
写入（+ship / +refund / +update-tracking / create / update / cancel / pay / delete / 子资源写入）	orders 写入范围	auth login --domain orders

使用 shoplazza auth scopes 查看确切的范围字面值；--domain orders 会扩展为这些范围。

易错点

仅列出特定领域的易错点（通用问题——.data 前缀、使用 --jq 时未加 -r——见 shoplazza-common）。

症状	原因	解决方法
使用 unfulfilled / fulfilled 筛选	不在枚举值中	未发货 = waiting；见上方枚举表
orders get 对 #… 订单号查无结果	get 接收内部 order_id；订单号是另一种键	get-by-number --params '{"number":"…"}'（去掉 #）
+refund 报错“order has N payment_lines”	多支付行订单需要明确选择	使用列出的候选项中的 --payment-line-id 重新运行
+refund / +ship 试运行打印了两个请求	这些快捷命令会先 GET 订单（解析支付行 / 可履约商品），再 POST	这是预期行为。试运行的 POST 请求体会省略查询得到的数据（例如 refund_line_items、空的 payment_line_id）——实际运行时会填入
只想取消发货记录，却取消了订单（或反之）	取消订单 ≠ 取消发货记录	订单 → orders cancel；履约 → orders fulfillments cancel（两个路径 ID）
为简单退款手动编写 refunds create 请求体	该叶级命令需要完整请求体，包括 refund_payments	优先使用 +refund；叶级命令仅用于拆分 / 分项退款 → references/refunds.md
使用店铺范围的 refunds list 查询单个订单的退款记录	这是两个不同的端点	单个订单 → refunds list-by-order --params '{"order_id":"…"}'
在 +search 中使用包含逗号列表的 --status	快捷命令的标志只接受单个值	多状态 → orders list --params '{"status":["opened","placed"]}'
搜索“某个买家”却返回整个店铺的数据	筛选条件被丢弃，或只是页面看起来很短	回复前，用带筛选条件和不带筛选条件的 orders +count 交叉核对——见 shoplazza-common →“读取筛选后的列表”
keyword_scope_fields=["email"] 或 ["order_no"] 返回 0 条结果	这些是架构描述中的示例字符串，并非可接受的词汇	使用 fuzzy_fields 字段名（shipping_email、number、name 等）——见“精确搜索订单”
unknown flag: --fields	没有任何 orders 命令支持 --fields	使用 --jq 投影
orders create 因缺少字段而被拒绝	整个请求体需嵌套在 order 包装对象下；line_items[].quantity、shipping_address（last_name、email、country_code、province、province_code、city、address、zip）、shipping_line（shipping_name、shipping_price）、tax_total、currency_code 均为必填	构建完整的嵌套请求体 → references/orders-create.md（已通过 schema orders.create --view request 验证）
设置了 country / province，orders create 仍失败	必须使用 country_code / province_code（ISO：US、CA）——显示名称 country / province 为可选项	同时传入两个代码；见 references/orders-create.md
将 orders pay 的 payment_line 对象复制到 orders create 中	在 orders create 中，架构将 payment_line 定义为字符串（注册表扁平化所致）；而在 orders pay 中，它是对象	创建时省略 payment_line；之后使用 orders pay 记录付款
不传请求体的 orders pay 意外地“成功”了	空请求体 = 虚假的测试付款	对真实支付渠道传入 payment_line（payment_channel、payment_method、transaction_no），或为自定义方式传入 gateway
架构摘要中写着“shopping zone”	注册表拼写错误——实际指的是 shipping zone	忽略；命令为 shipping-schemas {create,update,delete}-zone

操作示例

# 1. Orders placed in the last 7 days that are not yet shipped
orders +search --fulfillment-status waiting --since <today-7d, e.g. 2026-07-16>

# 2. Paid orders for one customer
orders +search --customer-id 100200 --financial-status paid

# 3. All orders from a buyer email — exact, complete, and checked against the store total
orders +search --email [email protected] --page-limit 250
orders +count --email [email protected] --jq '.data.count'   # must be < the unfiltered count
orders +count --jq '.data.count'

# 4. Total order count, no filters
orders +count --jq '.data.count'

# 5. Order detail by order number
orders get-by-number --params '{"number":"2026071500123"}' --jq '.data.order'

# 6. Ship the whole order and notify the buyer
orders +ship --order-id 4300123 --tracking SF0011223344 --company "顺丰" --notify

# 7. Fix a mistyped tracking number (no re-notify)
orders +update-tracking --order-id 991100 --fulfillment-id 77001 --tracking YT5544332211

# 8. Partial refund + return inventory — dry-run, restate, wait for go-ahead, then run
orders +refund --order-id 887799 --amount 19.90 --note "wrong size" --return-items --dry-run
orders +refund --order-id 887799 --amount 19.90 --note "wrong size" --return-items

# 9. Cancel an order with a reason — dry-run first
orders cancel --params '{"order_id":"660011"}' --data '{"reason":"买家重复下单"}' --dry-run
orders cancel --params '{"order_id":"660011"}' --data '{"reason":"买家重复下单"}'

# 10. Flag an order as high fraud risk with a reason
orders risks create --params '{"order_id":"445500"}' \
  --data '{"risk":{"level":"high","details":["收货地址与 IP 所在国家不一致"]}}'

# 11. Which carrier owns this tracking number?
orders tracking-carriers detect --params '{"tracking_number":"9400111899223344556677"}'

# 12. Payment transactions on an order
orders transactions list --params '{"order_id":"778899"}'

# 13. One order's refund records
orders refunds list-by-order --params '{"order_id":"220033"}' --jq '.data.records'

参考资料

• references/orders-create.md — 手动/草稿订单创建：完整的嵌套请求体（必填项与可选项）、必填项与询问项、精简示例和更完整的示例
• references/fulfillments.md — 履约记录：叶节点 CRUD、取消/完成、请求体结构
• references/refunds.md — 退款记录请求体（拆分/逐项退款）、全店与单笔订单列表、针对自定义渠道退款的 finish
• references/risks.md — 欺诈风险记录：级别枚举、详情、CRUD
• references/transactions.md — 买家付款交易、状态枚举
• references/post-sales.md — 售后记录：列表筛选条件、删除
• references/shipping-schemas.md — 通用架构、区域、可用配送线路（GB 特殊情况）
• references/tracking-carriers.md — 检测/列出承运商
• 各命令的标志：shoplazza orders <cmd> --help
• 规范叶节点的参数/请求体/响应：shoplazza schema orders.<cmd>（嵌套：schema orders.fulfillments.create）
• 跨领域机制（身份验证/层级/输出封装/--dry-run/--jq/安全）：../shoplazza-common/SKILL.md
• 快捷命令的权威来源：shortcuts/orders/*.go