shoplazza-shop

shoplazza CLI — shop 模块

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

概述

shop 模块是店铺级的 配置与内容 领域：店铺信息 / 设置、 销售与流量分析、媒体库（文件）、自定义字段（所有三类）、 博客与文章、自定义页面、导航菜单、URL 重定向、市场、店铺语言， 以及实时运费承运商服务。范围广而浅——本文是路由索引；各子领域的 深入内容见 references/。

唯一的快捷命令是 +upload-file——其他所有命令都是规范叶节点 （--params / --data）。三个访问层级均适用（层级规则见 shoplazza-common）。

命令索引

意图 → 命令，按匹配度从高到低排列。权威的标志 / 参数以 shoplazza shop <cmd> --help 和 shoplazza schema shop.<cmd> 为准，而非本表。

用户意图	命令
存储信息 — 查询店铺信息 / domain / currency / plan	shop info get（可选 --params '{"fields":["id","domain"]}'）
更改客服邮箱 / 更改 customer-service email（唯一可编辑字段）	shop info get --jq '.data.id' → shop info update --params '{"shop_id":"<id>"}' --data '{"shop":{"customer_email":"…"}}'
分析 — 指定日期范围内的销售额 / 订单数报表	shop analytics overview --data '{"begin_time":"<unix-str>","end_time":"<unix-str>","indicator":["sales","orders"]}' → references/analytics.md
SKU 销量排行 / 最畅销 SKU	shop analytics by-sku --data '{…,"sort_by":"sales_total","sort_direction":"desc"}'
SPU / 落地页 / UTM 明细	shop analytics by-spu（额外必需参数 type）/ by-land-page（必需参数 dimensions）/ by-utm
搜索词分析 / 零结果搜索词 / 站内搜索关键词	shop analytics search-keyword --data '{…,"sort_by":"count","sort_direction":"desc"}'（has_result 是字符串 "0"/"1"）
流量渠道 / 流量来源 / 按渠道统计流量	shop analytics traffic-channel（必需参数 dimensions + metrics）；有效渠道名称：shop analytics traffic-channel-options
媒体库 — 上传文件到素材库（仅限公开 URL）	shop +upload-file --source-url <url> [--source-url <url> …] [--folder <name>]
检查上传任务 / 上传进度	shop files task --params '{"task_id":"<id>"}'（快捷命令已获取一次任务状态）
浏览媒体库 / 查看素材库	shop files list（文件夹默认为 all_upload；page_size ≤ 300）
文件详情 / 删除文件	shop files {get,delete} --params '{"file_uri":"<uri>"}'
Metafields — 店铺级 metafield	shop metafields-shop create --data '{"namespace":"…","key":"…","type":"string","value":"…"}' → references/metafields.md
商品 / 订单 / 客户上的 Metafield（给商品添加字段）	shop metafields-resource create --params '{"owner_resource":"product","owner_id":"<id>"}' --data '{"definition_id":"…","namespace":"…","key":"…","type":"…","value":…}'
定义 Metafield 架构（元字段定义）	shop metafields-definition create --params '{"owner_resource":"…"}' --data '{"name":"…","namespace":"…","key":"…","type":"…"}'
博客内容 — 发布博客文章 / 新建博客文章	shop articles create --data '{"article":{"title":"…","content":"…","blog_ids":["…"]}}' → references/blogs-articles.md
管理博客（文章的容器）	shop blogs list / shop blogs create --data '{"blog":{"Title":"…"}}'（标题键为大写的 Title）
自定义页面 — 自定义页面 / 关于我们 / 关于我们	shop pages create --data '{"page":{"title":"…","content":"…"}}' → references/pages-redirects.md
导航菜单 — 查看导航菜单 / 列出菜单和菜单项	shop menu list（内置菜单的 id 为 header / footer；指定一个菜单：--params '{"ids":["header"]}'）
新建菜单 / 创建自定义菜单	shop menu create --data '{"title":"…","children":[…]}'（仅适用于自定义菜单）
更改菜单名称 / 更改菜单项 / 编辑菜单	shop menu update --params '{"id":"<menu-id>"}' --data '{"title":"…"}' — 发送 children 会替换整个菜单项树（参见注意事项）
删除菜单 / 删除自定义菜单	shop menu delete --params '{"id":"<menu-id>"}'（无法删除内置的 header / footer）
URL 重定向 — 301 / 跳转	shop redirects create --data '{"redirect":{"from_url":"…","redirect_url":"…","status":"…"}}'（必需参数 status — 参见注意事项）
市场 — 创建市场 / 发布到某个国家	shop markets create --data '{"name":"…","countries":["JP"]}' → references/markets.md
语言 — 开通语言 / 多语言	shop languages supported → add → enable → publish → references/languages.md
承运商服务 — 注册提供实时运费报价的承运商	shop carrier-services create --data '{"carrier_service":{"name":"…","callback_url":"…","carrier_code":"…"}}' → references/carrier-services.md

写入规范

配置领域——没有完整的询问矩阵，但以下写入操作有必填且无默认值的字段。 缺失或含糊不清时 → 使用 AskUserQuestion 一次性批量询问，绝不捏造。绝不询问有默认值或可选的字段。

操作	缺失时必须询问	静默使用默认值 / 绝不询问
+upload-file	一个公开 URL（本地文件 → 降级处理：说明 API 只能获取公开 URL，并询问用户提供链接或托管服务）	--folder（默认值为 all_upload）
pages create	title	url、meta_*、independent_seo——省略；绝不捏造 SEO 字段
redirects create	from_url、redirect_url；如果用户的表述无法确定 status 值，也要询问（该枚举值未包含在 schema 中——参见注意事项）	—
metafields-shop create	namespace、key、type、value	description、definition_id（此处为可选项）
metafields-resource create	owner_resource+owner_id、definition_id、namespace、key、value	description；type——先通过定义（metafields-definition get）确定，再询问
markets create	name、countries	confirm——绝不静默传入 true（这会删除已占用的市场）
carrier-services create	name、callback_url（用户自己的端点——绝不捏造）、carrier_code	active、logo、short_desc
languages add	语言；通过 languages supported 解析 IETF 代码	—
info update	新的 customer_email	shop_id——自行通过 info get 解析，勿询问
menu create	title；每个菜单项的标题和链接目标（自行解析 ID）	category（始终为自定义值 3）、target、disabled
menu update	要更新的菜单（通过 menu list 解析 ID）、要进行的更改	title / category——省略以保留原值

破坏性叶子操作（pages batch-delete、markets delete——不可逆、files delete、 redirects delete、metafields-* delete、menu delete、包含 children 的 menu update）→ 先使用 --dry-run，然后重述确认，遵循 shoplazza-common → 安全协议。

边界

读起来像属于另一个领域（或另一个领域读起来像属于 shop）：

表面上像是	实际所属领域	命令
给商品/订单加元字段 / 商品上的 metafield	此处——所有 metafield 都属于 shop，即便由商品拥有也一样	shop metafields-resource create --params '{"owner_resource":"product",…}'
商品图片 / 主图 / 附加到商品的图片	shoplazza-products	products images create
上传文件 / 素材库 / 媒体库素材	此处	shop +upload-file / shop files …
销量/流量/转化报表 / 销售和流量分析	此处	shop analytics …
订单量统计 / 搜索订单 / 订单数量与搜索	orders domain	orders +count / orders +search
实时运费报价承运商 / 结账时提供运费报价的承运商	此处	shop carrier-services …
物流商查询 / 运单追踪 / 履约追踪承运商、配送区域	orders domain	orders tracking-carriers / orders shipping-schemas
自定义页面 / 关于我们 / 品牌故事页面	此处（内容，而非主题）	shop pages create
导航菜单 / 菜单项 / 在主菜单中添加链接	此处（菜单内容）	shop menu list → shop menu update
页头显示哪个菜单 / 将菜单绑定到页头卡片	shoplazza-themes	themes +edit（卡片的 link_list 设置）
修改模板 / 装修 / 主题和模板编辑、自定义页面布局	shoplazza-themes	themes +page / themes +edit / themes template …
博客/文章	此处（非商品评价）	shop blogs / shop articles
买家评价 / 商品评价	shoplazza-products	products comments …
优惠码 / 折扣 / 折扣码	shoplazza-discounts	discounts +*

权限 · 范围

授权按域（即 --domain 的单位）进行，而不是按命令进行。授权流程见 shoplazza-common → 身份验证。

操作	所需权限	授权方式
读取（info get、analytics *、files list/get/task、* list/get/count）	shop 读取范围	auth login --domain shop
写入（+upload-file、* create/update/delete、languages enable/publish，……）	shop 写入范围	auth login --domain shop

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

注意事项

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

症状	原因	解决方法
分析调用被拒绝／结果为空	每个 analytics 报表都是 POST（只有 traffic-channel-options 是 GET）：筛选条件应放在 --data 中，而不是 --params 中；begin_time／end_time 是以字符串形式传入的 Unix 秒级时间戳（"1782864000"）	计算时间戳，将其加引号作为字符串，并通过 --data 发送
traffic-channel 返回 400 错误：cannot unmarshal object … filters of type string	它的 filters 是编码为字符串的 JSON 对象；search-keyword 的 has_result 也必须是字符串	"filters":"{\"last_referrer_first_show\":{\"operator\":\"in\",\"value\":[\"Social\"]}}"；"has_result":"0"——参见 references/analytics.md
menu update 后菜单项丢失	children 会替换整个菜单项树：未传入的菜单项会被删除，[] 会清空菜单	先读取菜单，编辑完整的树，再将所有内容发回（保留每个现有菜单项的 id）；只需更改标题时，省略 children
嵌套菜单项变成了平铺列表／嵌套关系丢失	menu list 返回的是平铺列表——子项通过 pid 指向其父项；写入时只能通过嵌套的 children 表示层级（没有 pid 字段）	在发送 children 前，根据 pid 重建树
不确定菜单项的 url_obj 应填写什么	Schema 未列出链接 type 的取值	在 menu list 中复制同类现有菜单项的 url_obj（type + source_id + url）；切勿自行编造 type 或 source_id
尝试更新店铺名称／地址	info update 只开放了一个可编辑字段：shop.customer_email	此端点无法更新其他内容；请说明这一点
info update 需要用户无法获知的 shop_id	shop_id 是必填的路径参数	先查询：shop info get --jq '.data.id'
被要求上传本地文件	+upload-file 接受的是公开 URL，而非本地文件（其帮助信息中有明确说明）；API 会获取该 URL	降级处理：不执行写入；请用户提供公开链接，或建议先托管文件
显示上传“完成”，但文件缺失	上传是一个异步任务——POST 会返回 task_id；快捷命令会自动获取一次任务状态	使用 shop files task --params '{"task_id":"…"}' 重新检查，直到 status／success_list 状态稳定
blogs create 忽略／拒绝标题	博客标题键名首字母必须大写，使用 Title（必填，1–100），而不是小写的 title	shop blogs create --data '{"blog":{"Title":"…"}}'——使用 schema shop.blogs.create 确认字段
redirects 的 status 可以取哪些值？	status 必填，但 Schema 未记录枚举值——不要自行编造	检查 schema shop.redirects.create，查看现有规则（shop redirects list --jq '.data.redirects[].status'）或 OpenAPI 文档；若仍不明确，请询问用户
metafields-resource create 被拒绝，而 metafields-shop create 正常	两者存在差异：资源级操作必须提供 definition_id；店铺级操作不需要（可选）。类型枚举也不同（店铺级：JSON／string；资源级：single_line_text_field、integer 等）	参见 references/metafields.md
语言已发布，但市场关联消失	languages publish 会完全替换现有关联——market_ids: [] 会移除所有关联	始终发送完整的目标列表
添加了语言，但店面没有变化	新添加的语言默认处于禁用状态；不支持的代码会被静默丢弃	添加后执行 languages enable；使用 languages supported 验证代码
使用 confirm: true 调用 markets create/update 后，其他市场被删除	一个国家只能属于一个市场；confirm: true 会自动删除已占用该国家的市场	使用 markets preview 和 --dry-run 预览，说明将删除的内容，并征得明确同意
metafields-definition get 在路径中带 ID 时返回 404	它的 id 是查询参数，而不是路径段	shop metafields-definition get --params '{"id":123456}'

操作示例

# 1. Store's primary domain and currency
shop info get --jq '{domain: .data.domain, currency: .data.currency}'

# 2. Change the customer-service email (only editable field; two steps)
SHOP_ID=$(shop info get --jq '.data.id')
shop info update --params "{\"shop_id\":\"$SHOP_ID\"}" --data '{"shop":{"customer_email":"[email protected]"}}'

# 3. Sales + order count, 2026-07-01 .. 2026-07-15 (unix seconds as STRINGS)
shop analytics overview --data '{"begin_time":"1782864000","end_time":"1784159999","indicator":["sales","orders"]}'

# 4. Best-selling SKU over a window (sort desc by sales metric)
shop analytics by-sku --data '{"begin_time":"1782864000","end_time":"1784159999","sort_by":"sales_total","sort_direction":"desc","page_size":10}'

# 5. Upload a public image to the media library (async task; folder defaults to all_upload)
shop +upload-file --source-url https://example.com/banner.png

# 6. Create an "About Us" custom page
shop pages create --data '{"page":{"title":"关于我们","content":"我们是一家来自杭州的 DTC 品牌"}}'

# 7. Permanent URL redirect (status REQUIRED — pin the value via schema/existing rules first)
shop redirects list --jq '.data.redirects[].status'   # see what values live rules use
shop redirects create --data '{"redirect":{"from_url":"/old-sale","redirect_url":"/new-sale","status":"<verified-value>"}}'

# 8. Shop-level metafield (no definition_id needed at shop level)
shop metafields-shop create --data '{"namespace":"global","key":"support_phone","type":"string","value":"400-800-1234"}'

# 9. Product-level metafield (owner in --params, definition_id REQUIRED in --data)
shop metafields-resource create --params '{"owner_resource":"product","owner_id":"66880"}' \
  --data '{"definition_id":"D8899","namespace":"specs","key":"material","type":"single_line_text_field","value":"cotton"}'

# 10. Launch Japanese and publish it to the Japan market
shop languages supported --jq '.data.languages'   # find the exact IETF code
shop languages add --data '{"codes":["ja-JP"]}'
shop languages enable --params '{"language_code":"ja-JP"}'
MARKET_ID=$(shop markets list --jq '.data.markets[] | select(.name=="Japan") | .id')
shop languages publish --params '{"language_code":"ja-JP"}' --data "{\"market_ids\":[\"$MARKET_ID\"]}"

# 11. Rename a custom menu without touching its items (no children = items kept)
shop menu list --jq '[.data.menus[] | {id, title, category}]'   # category 3 = custom
shop menu update --params '{"id":"<menu-id>"}' --data '{"title":"Footer links"}'

参考资料

• references/analytics.md — 7 个 POST 报告及渠道选项查询、指标/维度、排序枚举、时间戳规则
• references/metafields.md — 定义、资源和店铺元字段，owner_resource 枚举、类型枚举
• references/blogs-articles.md — 博客（容器）与文章（帖子）；博客标题键为大写 Title
• references/pages-redirects.md — 自定义页面的 CRUD/批量操作、重定向和未公开的状态枚举
• references/markets.md — 市场生命周期、国家/地区占用与确认、价格/税费/域名/语言
• references/languages.md — 添加 → 启用 → 发布流程、全量替换语义
• references/carrier-services.md — 运费报价承运商注册
• 各命令的标志：shoplazza shop <cmd> --help
• 规范叶节点的参数/请求体/响应：shoplazza schema shop.<cmd>（嵌套命令：schema shop.metafields-resource.create）
• 跨领域机制（身份验证/层级/信封/--dry-run/--jq/安全）：../shoplazza-common/SKILL.md