shoplazza-customers

shoplazza CLI — customers 模块

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

概述

customers 模块用于管理客户（买家）资料及其收货地址。三种访问层级均适用（层级选择规则见 shoplazza-common — 优先使用 +shortcut）。

快捷命令仅有 +create 和 +search。没有 +count — 计数命令是 count 规范叶节点 — 也没有 +update／+delete；更新命令是 update 叶节点，并且本模块完全没有删除客户的命令（只有地址支持 delete）。

命令一览

意图 → 命令，按匹配度最高的层级优先。权威标志／参数以 shoplazza customers <cmd> --help 和 shoplazza schema customers.<cmd> 为准，而非本表。

用户意图	命令
创建客户	customers +create (--email <e> | --phone <p>) [--first-name --last-name --tags --no-marketing]
按邮箱／电话查找客户	customers +search --email <e> / customers +search --phone <p>
客户总数	customers count（叶节点 — 没有 +count）
按 ID 获取单个客户	customers get --params '{"customer_id":"<id>"}'
列出／筛选客户（游标分页、ID、联系信息）	customers list --params '{…}'
更新姓名／标签／营销订阅	customers update --params '{"customer_id":"<id>"}' --data '{"customer":{…}}'
列出客户的地址	customers addresses list --params '{"customer_id":"<id>"}'
添加地址	customers addresses create --params '{"customer_id":"<id>"}' --data '{"address":{…}}'
获取／更新／删除单个地址	customers addresses {get,update,delete} --params '{"customer_id":"<cid>","address_id":"<aid>"}'
设置默认收货地址	customers addresses set-default --params '{"customer_id":"<cid>","address_id":"<aid>"}'（无需 --data）

处理请求

“新建客户”／“add a new customer”／“给客户打标签”／“unsubscribe them”属于操作，不是问题：

1. 根据触发词表将意图匹配到命令。
2. 对照用户自己的表述，检查必填且无默认值的字段。缺失或含糊 → 使用 AskUserQuestion 提问，绝不编造 — 尤其是联系标识符： 绝不虚构邮箱地址或电话号码。
3. 对于 CLI 有默认值的内容，绝不提问（营销订阅默认为订阅；姓名和 标签为可选项）。由默认值处理。
4. 所有必填信息齐全 → 执行。本模块中的写入操作都是非破坏性的单条记录更新； 仅在用户要求时才先运行 --dry-run（参见 shoplazza-common → 安全协议）。

触发短语 → 命令

用户说	命令	如何提取值
新建客户 / 建个客户档案 / add a new customer	+create	必须且只能提供 --email / --phone 中的一个；像 "Jane Doe" 这样的全名应拆分为 --first-name Jane --last-name Doe
不要订阅营销 / 不订阅邮件 / don't subscribe to marketing	+create … --no-marketing	默认订阅——用户明确表示选择退出时，必须设置该标志
按邮箱查客户 / find the customer by email	+search --email <e>	用户要查的是客户档案，而不是他们的订单
按手机号查客户 / look up by phone	+search --phone <p>	不要臆造 --since / --until 时间范围
一共多少客户 / 注册客户数 / how many customers	count	叶节点命令，无标志；使用 --jq '.data.count' 提取
给客户 X 打标签 / tag customer X	update	标签会整体替换数组——先读取、合并，再写入（参见注意事项）
退订邮件营销 / unsubscribe email marketing	update with {"customer":{"accepts_marketing":false}}	仅限邮件——不要更改 accepts_sms_marketing
退订短信营销 / unsubscribe SMS marketing	update with {"customer":{"accepts_sms_marketing":false}}	仅限短信——不要更改 accepts_marketing
加一个收货地址 / add a shipping address	addresses create	请求正文必须包含 country + country_code
把地址设为默认 / set the default address	addresses set-default	两个 ID 都是通过 --params 传入的路径参数；无请求正文

必填项与询问矩阵

只有没有默认值的项目才需要询问。

命令	未指定时必须询问	尽可能推断	静默使用默认值
+create	联系方式标识符——--email / --phone 中必须且只能提供一个（询问时应提供两种选项，并说明只需其中一个）	根据明确提供的姓名推断 --first-name / --last-name；根据选择退出的措辞推断 --no-marketing；用户提及标签时推断 --tags	营销订阅（默认订阅）、--tags（省略）、姓名（可选——绝不询问）
+search	用户想查询特定客户却未提供邮箱或手机号时，询问要查哪位客户	根据用户提供的信息选择筛选标志（邮箱或手机号）	--page-limit、--since、--until（全部省略）
update	customer_id；如果用户没有说明，则询问新值	根据措辞确定字段（标签→tags，邮件营销→accepts_marketing，短信→accepts_sms_marketing）	用户未提及的所有字段——绝不发送
addresses create	customer_id；country + country_code（必需的请求正文字段）	根据措辞推断其他地址字段	default 和所有可选字段（省略）
addresses set-default	customer_id + address_id	—	—（完全不传请求正文）

绝不询问清单

可选或有默认值的项目——绝不询问：--first-name / --last-name / --tags（+create 中可选） · 营销订阅（+create 默认订阅；仅在用户明确表示选择退出时设置 --no-marketing，绝不询问）· --page-limit / --since / --until （+search；省略——绝不臆造时间范围）· 可选地址字段，包括 default。

范围边界

看起来与客户有关，实际属于其他模块（反之亦然）：

看起来与客户有关	实际所属领域	命令
该客户下过的订单 / order history for [email protected]	shoplazza-orders	按该客户筛选的订单搜索
按邮箱找到这个客户 / customer profile for an email	本模块（不是订单）	customers +search --email <e>

由查询目标决定：资料（profile/record）→ customers；订单（orders placed）→ orders。 在此处解析客户 ID，并将其作为订单查询的中间步骤没有问题——最终答案必须来自对应的所属领域。

权限 · 范围

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

操作	需要	授权方式
读取（get / list / count / +search / addresses get|list）	customers 读取范围	auth login --domain customers
写入（+create / create / update / addresses create|update|delete|set-default）	customers 写入范围	auth login --domain customers

使用 shoplazza auth scopes 查询确切的范围字面值；--domain customers 会展开为这些范围。

注意事项

仅列出特定于域的注意事项（通用注意事项——.data 前缀、未搭配 -r 使用 --jq——见 shoplazza-common）。

症状	原因	解决方法
customers +count → 未知命令	仅提供 +create / +search 快捷命令（不同于 products/orders，customers 没有 +count）	使用 customers count（叶子命令），通过 --jq '.data.count' 提取——不要手动遍历列表并计数
+create 被拒绝：“exactly one of --email or --phone is required”	严格的异或规则——两个参数都给了，或者都没给	只传一个；如果用户两者都没提供，请询问——绝不要捏造联系方式
规范叶子命令 create 缺少 contact_type 时失败	叶子命令的请求体需要 contact_type；+create 会自动填充（根据标志匹配 email / phone）	优先使用 +create；使用叶子命令时，将 "contact_type" 设为与所传标识符匹配的值
添加标签后，客户原有的标签消失	update 的 tags 会替换整个数组	读取后合并再写入：使用 get 获取当前标签，追加后，再使用合并后的数组调用 update
取消订阅的范围超出用户要求	邮件（accepts_marketing）和短信（accepts_sms_marketing）是独立的布尔值	只更改指定的那一项；不要将另一项放入请求体
尝试通过 update 更改邮箱 / 电话	update 请求体只接受 first_name / last_name / accepts_marketing / accepts_sms_marketing / tags	无法通过 update 实现——查看 schema customers.update
叶子命令 list 忽略 phone 参数	list 文档记录了 email 和 contact 查询参数，而非 phone	优先使用 +search --phone（它会发送 contact）；使用叶子命令时传入 "contact"（匹配客户的主要联系方式——邮箱或电话）
customers +search 出现 unknown flag: --fields	customers 列表端点的文档中没有 fields 参数，因此该标志已被移除，而不是作为无操作保留	使用 --jq 进行投影
想要删除客户	此模块没有删除客户的命令（只有 addresses delete）	第 1–2 层级无法实现；使用 api rest 前先确认存在对应端点
使用 addresses update 并设置 "default":true 来设为默认地址	此功能由专用端点处理	addresses set-default --params '{"customer_id":…,"address_id":…}'——仅路径参数，不使用 --data
+search --since/--until 返回“错误”的客户	它们映射到 created_at_min / created_at_max——即客户创建时间的上下限	仅当用户要求按注册时间筛选时才传入

操作示例

# 1. New customer with email, opted out of marketing emails
customers +create --email [email protected] --first-name Jane --last-name Doe --no-marketing

# 2. Find a customer by phone (project with --jq; +search has no --fields)
customers +search --phone 13800138000 --jq '.data.customers[] | {id, name, email, phone}'

# 3. Total registered customers
customers count --jq '.data.count'

# 4. Tag customer 424242 as VIP without clobbering existing tags (read-merge-write)
customers get --params '{"customer_id":"424242"}' --jq '.data.customer.tags'
# → e.g. ["wholesale"]; append and write the MERGED array back:
customers update --params '{"customer_id":"424242"}' --data '{"customer":{"tags":["wholesale","VIP"]}}'

# 5. Unsubscribe email marketing only (SMS untouched)
customers update --params '{"customer_id":"887766"}' --data '{"customer":{"accepts_marketing":false}}'

# 6. Set the default shipping address
customers addresses set-default --params '{"customer_id":"335577","address_id":"ADDR99"}'

# 7. List a customer's address book
customers addresses list --params '{"customer_id":"335577"}' --jq '.data.addresses[] | {id, name, address1, default}'

参考资料

• 各命令的标志：shoplazza customers <cmd> --help
• 规范叶子命令的参数 / 请求体 / 响应：shoplazza schema customers.<cmd>（地址：schema customers.addresses.<cmd>）
• 跨领域机制（身份验证 / 层级 / 输出封装 / --dry-run / --jq / 安全）：../shoplazza-common/SKILL.md
• 快捷命令的权威来源：shortcuts/customers/*.go