shoplazza-customers

shoplazza CLI — 顧客モジュール

最初に、何よりも先に ../shoplazza-common/SKILL.md を Read してください。 ここでは、横断的な仕組み（3 つのアクセス階層、出力エンベロープ（.data）、 --dry-run、--jq（-r を渡さないことを含む）、--fields、schema、api rest、認証／プロファイル、 安全プロトコル）をすべて扱います。このファイルでは顧客ドメインのみを扱い、これらの内容を繰り返しません。

概要

customers モジュールでは、顧客（購入者）のプロフィールと配送先住所を管理します。3 つすべての アクセス階層が適用されます（階層の選択ルールは shoplazza-common に記載されています。+shortcut を優先してください）。

ショートカットは +create と +search のみです。+count はありません。件数の取得には count spec リーフを使います。また、+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 で顧客を 1 件取得する	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":{…}}'
住所を 1 件取得／更新／削除する	customers addresses {get,update,delete} --params '{"customer_id":"<cid>","address_id":"<aid>"}'
既定の配送先住所を設定する	customers addresses set-default --params '{"customer_id":"<cid>","address_id":"<aid>"}'（--data は不要）

リクエストへの対応

「新建客户」／「新しい顧客を追加する」／「顧客にタグを付ける」／「配信登録を解除する」は質問ではなく、アクションです。

1. トリガーテーブルを使って、目的に合ったコマンドを選びます。
2. 必須で、デフォルト値のない項目をユーザー自身の発言と照らし合わせます。不足している、または曖昧な場合は → AskUserQuestion で確認し、決して捏造しないでください。特に連絡先識別情報については、 メールアドレスや電話番号を決して作り上げないでください。
3. CLI のデフォルト値がある項目については、決して質問しないでください（マーケティング登録はデフォルトで購読、名前と タグは任意です）。デフォルト値を適用してください。
4. 必須項目がすべてそろったら実行します。ここでの書き込みは破壊的ではない単一レコードの更新です。 ユーザーから求められた場合にのみ、最初に --dry-run を実行してください（shoplazza-common → 安全プロトコルを参照）。

トリガーフレーズ → コマンド

ユーザーの発言	コマンド	値の抽出方法
新建客户 / 建个客户档案 / 新しい顧客を追加	+create	--email / --phone のどちらか一方のみを指定します。完全な氏名（「Jane Doe」など）は --first-name Jane --last-name Doe に分割します
不要订阅营销 / 不订阅邮件 / マーケティングの配信に登録しない	+create … --no-marketing	デフォルトでは登録されます。明示的に配信を拒否する表現があれば、必ずこのフラグを設定します
按邮箱查客户 / メールアドレスで顧客を検索	+search --email <e>	求めているのは顧客レコードであり、注文ではありません
按手机号查客户 / 電話番号で検索	+search --phone <p>	--since / --until の期間を勝手に指定しないでください
一共多少客户 / 登録顧客数 / 顧客は何人いますか	count	サブコマンドで、フラグはありません。--jq '.data.count' で抽出します
给客户 X 打标签 / 顧客 X にタグを付ける	update	タグは配列全体の置き換えです。読み取り・マージ・書き込みを行います（「注意点」を参照）
退订邮件营销 / メールマーケティングの配信を停止	{"customer":{"accepts_marketing":false}} を指定して update	メールのみを対象とし、accepts_sms_marketing には触れないでください
退订短信营销 / SMS マーケティングの配信を停止	{"customer":{"accepts_sms_marketing":false}} を指定して update	SMS のみを対象とし、accepts_marketing には触れないでください
加一个收货地址 / 配送先住所を追加	addresses create	リクエストボディには country と country_code が必要です
把地址设为默认 / 住所をデフォルトに設定	addresses set-default	2 つの ID は --params でパスパラメーターとして指定します。リクエストボディはありません

必須項目と確認事項のマトリックス

確認が必要なのは、デフォルト値がない項目のみです。

コマンド	指定がない場合に必ず確認する項目	可能であれば推測する項目	暗黙的にデフォルト設定する項目
+create	連絡先識別子。--email / --phone のどちらか一方のみです（確認する場合は両方を提示し、必要なのはどちらか一方のみだと説明します）	明示された氏名から --first-name / --last-name を推測します。配信停止を希望する表現から --no-marketing を推測します。ユーザーがタグを指定した場合は --tags を推測します	マーケティング（デフォルトで登録）、--tags（省略）、氏名（任意のため、確認しないでください）
+search	特定の顧客を検索したいのにメールアドレスも電話番号も指定されていない場合、どの顧客かを確認します	入力内容からフィルターフラグ（メールアドレスか電話番号か）を推測します	--page-limit、--since、--until（すべて省略）
update	customer_id。表現から新しい値がわからない場合は、その値	表現から対象フィールドを判断します（タグ→tags、メールマーケティング→accepts_marketing、SMS→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 を含む）。

対象範囲

顧客に関する内容に見えても、実際には別の領域に属する場合があります（その逆も同様です）。

顧客に関するように見える内容	実際の対象	コマンド
该客户下过的订单 / [email protected] の注文履歴	shoplazza-orders	その顧客で絞り込んだ注文検索
按邮箱找到这个客户 / メールアドレスから顧客プロフィールを検索	このモジュール（注文ではありません）	customers +search --email <e>

対象は依頼の方向で決まります。資料（プロフィール／レコード）→ customers、订单（注文）→ 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 が拒否される：「--email または --phone のいずれか一方が必要です」	厳密な XOR です — 両方が指定されているか、どちらも指定されていません	どちらか一方だけを渡してください。ユーザーがどちらも指定していない場合は、必ず確認してください — 連絡先情報を捏造しないでください
仕様リーフの create が contact_type なしでは失敗する	リーフのリクエストボディでは contact_type が必須です。+create はフラグに合わせて自動入力します（email / phone）	+create を優先してください。リーフを使う場合は、送信する識別子に合わせて "contact_type" を設定してください
タグ付け後に顧客の古いタグが消えた	update の tags は配列全体を置き換えます	読み取り・マージ・書き込みを行います。現在のタグを get で取得し、追加してから、マージした配列で update してください
ユーザーの依頼より多くの配信登録を解除してしまった	メール（accepts_marketing）と SMS（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 のみです）	Tier 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>（addresses：schema customers.addresses.<cmd>）
• 共通の仕組み（認証／Tier／出力エンベロープ／--dry-run／--jq／安全性）：../shoplazza-common/SKILL.md
• ショートカットの信頼できる情報源：shortcuts/customers/*.go