@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/skills/zan-saas-access/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: zan-saas-access
+description: 访问控制领域指引。查询店铺角色定义目录或当前微商城单店员工权限点时使用；区分角色定义、员工角色关联与实际权限。
+---
+
+# 访问控制 access
+
+首次使用或 CLI 版本变化时，先读取 `zan-saas skills read zan-saas-shared`。
+
+## 对象与边界
+
+店铺角色定义是角色名称和标识的目录，员工授角是员工与角色的关联，有效权限是员工能执行的操作。三者不能互相替代。角色说明、能力 DTO 和组织角色不是员工权限证明。
+
+本域的 `role` 是角色定义目录，`staff-perms` 是以员工为主体的权限点读取视图。员工资料及员工角色关联属于组织域；查询“员工持有哪些角色”使用 `zan-saas org staff-role get`，不能用目录或角色名称推算权限。
+
+## 选择入口
+
+| 用户目标 | 命令入口 |
+| --- | --- |
+| 浏览店铺角色定义目录 | `zan-saas access role list` |
+| 查询一个员工的权限点，或核对一个已知权限 key | `zan-saas access staff-perms get` |
+
+不提供授角、修改权限或推导可授予资格的操作。
+
+## 查询目录
+
+使用 `zan-saas access role list`。先看同版 `access --help` 和 `schema access.role.list`；需要跨店或解释空目录时，读 [角色目录的选路与恢复](references/role-list.md)。
+
+默认查询当前店铺，非总部不能跨店。总部跨目标须先核实当前凭证绑定总部和目标属于该总部；本地上下文不是授权证明，服务端仍须允许业务请求。
+
+空目录只表示本次查询没有返回角色，不表示员工无角色、无权限或全系统无角色。名称相同不证明角色相同，也不能从名称推导角色类别或全集。
+
+## 查询员工权限
+
+使用 `zan-saas access staff-perms get`，按员工登录账号手机号定位当前授权微商城单店中的员工，再读取其权限点。先核对同版 schema；需要区分角色与权限、单 key 结果或处理失败时，读[员工权限查询](references/staff-perms-get.md)。
+
+员工标识必须由同店员工资料取得，手机号、管理员标识与客户 OpenID 不能替代。省略权限 key 时读取本次完整权限点，指定 key 时只核对该 key；该筛选下的空结果不能说明员工没有其他权限。前置失败立即停止，不切店、不重放或转用 Raw API。

package/skills/zan-saas-access/references/role-list.md

@@ -0,0 +1,11 @@
+# 店铺角色目录的选路与恢复
+
+需要知道店铺有哪些角色定义时，先读取 `zan-saas schema access.role.list`，再运行 `zan-saas access role list`。不要为了查询目录猜员工 ID 或寻找某员工的授角关系。
+
+需要跨店时，先核对当前处于总部位置及所选目标。预览只说明执行计划，不证明目标归属或已经读取角色。参数、字段和具体预算以同版 help/schema 为准。
+
+总部跨店查询会核实凭证主体及目标归属。归属核验失败或达到预算时停止，不能回答“该目标不属于总部”，也不能把查询改到其他店铺来绕过失败。核对目标和本次身份后处理，不自动重试或换凭证。
+
+得到空目录时，只能回答本次查询没有返回角色。不能因此判断某员工没有权限；没有返回的角色说明也不能补成权限规则。名称相同不代表同一个角色，后续关联必须使用角色标识，而不是按名称合并。
+
+需要判断某员工能做什么时，按本域正文选择 `zan-saas access staff-perms get`；需查员工实际关联的角色时，读取 `zan-saas skills read zan-saas-org`。目录查询成功不能代替这些事实，也不证明店铺员工身份授权与权限隔离已经验收。

package/skills/zan-saas-access/references/staff-perms-get.md

@@ -0,0 +1,11 @@
+# 员工权限查询
+
+先读取 `zan-saas schema access.staff-perms.get` 和命令 help，按同版契约构造调用并解释结果。
+
+以员工登录账号手机号定位对象，不使用客户或联系人手机号。查询员工角色关联应转到 `org staff-role get`，不能把角色名称解释为权限点。
+
+本命令固定当前微商城单店。预览仅展示计划，不证明员工存在或授权通过；真实查询会先核验凭证店铺，再解析同店员工，最后查询权限。前置失败不会继续请求权限。
+
+需要核对某个已知权限 key 时，按契约使用单 key 筛选；省略筛选时读取本次完整权限点。预算超限整体失败，不把截断集合当完整结果。
+
+无权限点只对应成功的空数组，选择一个 key 的空数组也不证明员工完全无权限。失败时读取 stderr 的错误类别与请求状态，核对原店铺、账号和授权，不自动重放或扩大查询范围。

package/skills/zan-saas-aftersale/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: zan-saas-aftersale
+description: 查询同店售后单列表、详情、预算内扫描或指定售后的退款资金记录时使用；售后处理状态、交易商品行和资金到账事实分别表达。
+---
+
+# 售后 aftersale
+
+首次使用或 CLI 版本变化时，读取 `zan-saas skills read zan-saas-shared`。
+
+## 对象与关系
+
+售后单 `case` 是围绕交易订单提出的退款、退货退款或换货处理对象，以售后单号定位。一张订单可以关联多笔售后，订单号与售后单号不能互换。售后流程类型与买家诉求不是同一维度。售后可包含多条交易商品行引用和退款资金记录 `refund`，商品行标识、父售后号和逐笔退款流水号也不能互换。
+
+交易订单及其商品行由订单领域解释，见 `zan-saas skills read zan-saas-order`。售后成功、关闭或查询成功不能证明退款到账。售后成功不代表每笔资金成功，申请退款金额也不代表实际到账；售后处理状态、客服介入状态、发货状态和退货归还库存状态不能互相代替。
+
+## 按目标选择入口
+
+| 用户目标 | 当前入口与判断 |
+| --- | --- |
+| 按订单、客户或处理状态查找一页售后摘要 | `zan-saas aftersale case list`，先读同版 schema，需要解释分页和筛选时读 [单页查询判断](references/case-list.md)。 |
+| 已知售后单号，查看处理详情、商品行及已有运输或资金引用 | `zan-saas aftersale case get`，先读同版 schema；只有需要完整协商记录时才选择 consultation。 |
+| 在明确创建范围与双预算内跨页观察售后摘要 | `zan-saas aftersale case scan`，先读 [预算内扫描](references/case-scan.md) 和同版 schema，不把进度当可靠恢复游标。 |
+| 已知父售后号，查看本次返回的逐笔退款资金记录 | `zan-saas aftersale refund list`，先读同版 schema；不办理退款，不把父售后成功当资金到账。 |
+
+商品行随父售后详情解释，不提供按商品行独立查售后的入口。退款资金记录只证明本次返回的逐笔事实，不保证资金全生命周期全集。若需要库存确认、执行售后处理或发起退款，应停止并说明当前没有对应写入口。
+
+## 结果边界
+
+单页不是售后全集，也不是可靠增量或分页快照。未知总数时不能由空页或短页推断已读完。列表不提供当前诉求，不把用户选择的诉求筛选回填成返回事实。
+
+调用前按同版 schema 核对位置、目标店铺、授权及结果含义；应用身份查询成功不证明店铺员工权限。

package/skills/zan-saas-aftersale/references/case-list.md

@@ -0,0 +1,13 @@
+# 单页售后查询判断
+
+先读 `zan-saas schema aftersale.case.list`。参数、枚举、金额、时间、分页字段和固定限制以同版契约为准。
+
+查询“某订单有哪些售后”时，订单号只是关联条件，输出中的售后单号才标识售后对象；一个订单可能有多个售后单。不从某一页未出现售后推断订单从未售后。
+
+查询“客户提出的退货退款是否已到账”时，诉求只能用于筛选，列表并不返回当前诉求。申请退款金额和售后成功状态都不足以证明逐笔到账；已知父售后单号时，读取 `zan-saas schema aftersale.refund.list` 并用 `zan-saas aftersale refund list` 查询本次逐笔资金记录，按各自状态解释。资金查询不保证全生命周期全集或银行到账时间，缺少对应事实时保留判断缺口。
+
+缺少明确时间条件时不要向用户承诺历史全集。翻页到允许边界而仍有更多记录时，应缩小原查询范围，不尝试越界页码或以脚本绕过限制。缩小范围同样不能形成无遗漏保证。
+
+只按 `pagination.nextPageNo` 给出的页码继续。`hasMore=true` 说明服务端仍有记录，不保证还在 CLI 窗口内；`windowLimitReached=true` 时停止翻页并缩小原范围。`nextPageNo=null` 也可能因为总数未知，不能单凭它判断读完。
+
+结果总数未知时，空页、短页仍然只证明本次页的观察；不把未知改为零，也不自动逐行查详情。出现范围冲突、权限拒绝或协议错误时停止，核对原店铺与条件，不自动切换身份或重放。

package/skills/zan-saas-aftersale/references/case-scan.md

@@ -0,0 +1,31 @@
+# 售后摘要的有界跨页观察
+
+先读取 `zan-saas aftersale case scan --help` 和 `zan-saas schema aftersale.case.scan`。本入口从第一页开始，仅在显式创建时间范围、唯一摘要数量预算与总请求预算内串行读取。更新时间对可叠加，但不构成可靠增量入口。
+
+示例只作本地预览，不使用真实店铺或客户数据：
+
+```sh
+zan-saas aftersale case scan --kdt-id 63077 \
+  --start-created "2026-10-01 00:00:00" --end-created "2026-10-02 00:00:00" \
+  --max-items 40 --max-requests 3 --dry-run
+```
+
+执行只允许当前店铺上下文，显式店铺须与上下文及凭证绑定一致。缺上下文仅允许本地预览；无效或总部上下文不能借预览绕过。预览不取凭证、不联网，客户标识、电话及商品搜索文本会遮盖。
+
+## 如何解释结果
+
+每页先完整验证再提交，页内重复视为协议失败；跨页按店铺和售后号保留首次版本并计数。一张订单的多笔售后会分别保留。页大小固定为 `min(20,maxItems)`；剩余数量不足以容纳下一整页时会提前停止，不裁切页。
+
+| stopReason | 含义 |
+| --- | --- |
+| `range_exhausted` | 依本次观察总数到达页末，是唯一 `paginationExhausted=true` 的情况，仍不保证完整或快照一致。 |
+| `max_items` | 再接收整页可能超出数量预算，结果可能少于预算。 |
+| `max_requests` | 总请求预算用完，包含一次店铺绑定核验及未提交页。 |
+| `page_window` | 下一页将超过100页或页码乘页大小3000的窗口，不越界读取。 |
+| `total_unknown` | 总数缺失或后续失去，提交当前合法页后停止，不根据短页或空页猜末页。 |
+| `collection_changed` | 总数变化，当前变化页不提交，已见数据不表示快照。 |
+| `no_progress` | 非空页没有新售后号，提交本页观察后停止重复翻页。 |
+
+`lastRead` 是最近验证页，可能未提交；`lastCommittedPageNo` 是最近提交整页。二者只解释进度，不是可靠恢复游标。本版无恢复参数，不自动二分、持久化或重试。即使总数不变、结果数吻合或分页走完，也不能据此宣称无遗漏。
+
+预算停止退出0，须同时读取停止原因和完整性边界。协议、权限、网络或资源超限整体失败，stdout没有此前页数据，stderr给出受控错误和可用进度，不自动换店、换身份或重放。

package/skills/zan-saas-benefit/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: zan-saas-benefit
+description: 客户/会员权益领域指引。查询商家权益卡定义、客户持卡实例或历史发放记录时使用；区分卡定义、实际持有与发放过程，不处理等级或成长值。
+---
+
+# 权益 benefit
+
+首次使用或 CLI 版本变化时，读取 `zan-saas skills read zan-saas-shared`。本指引解释权益对象和入口选择，字段及执行约束由同版 help/schema 提供。
+
+## 领域与资源关系
+
+本域负责客户与会员权益。客户档案见 `zan-saas skills read zan-saas-customer`，会员身份、等级和成长值见 `zan-saas skills read zan-saas-member`；本域不拥有支付、退款或触达计划的事实。
+
+- 商家卡定义 `card-definition`。描述一类权益卡及其选定配置，使用定义标识或别名关联。
+- 客户持卡 `customer-card`。某客户实际持有的卡实例，关联卡定义、客户及有效期，使用完整卡号定位实例。
+- 发放记录 `card-grant`。一次权益卡发放或领取的历史记录，关联客户、卡定义、卡号及领卡来源店铺；查询店铺和来源店铺分别表达。
+
+卡定义可关联不同客户的持卡，同一客户也可能返回多个实例，不能按定义合并卡号。发放记录与实际持有分别查询，同客户同卡的多条历史记录逐条保留。记录存在不能证明当前仍持卡、卡可用或权益已使用；发放与使用的写操作当前尚无入口。
+
+例如，查询到“生日卡”定义，不能回答客户甲已领取或可领取。要查客户甲持卡，应查该客户的实例；要查一张已知卡，使用完整实例卡号。订单支付成功也不证明权益已经发放。
+
+## 按目标选择命令
+
+| 用户目标 | 命令入口 |
+| --- | --- |
+| 读取一个已知商家卡定义或选定权益配置 | `zan-saas benefit card-definition get` |
+| 浏览商家卡定义目录 | `zan-saas benefit card-definition list` |
+| 查询指定客户的持卡、状态及有效期 | `zan-saas benefit customer-card list` |
+| 按完整卡号查询持卡关联和有效期 | `zan-saas benefit customer-card get` |
+| 查看店铺或指定客户的一页历史发放记录 | `zan-saas benefit card-grant list` |
+
+持卡详情与持卡列表的可观察内容不同：按卡号的详情不返回当前可用状态，不能仅凭日期推导；需要状态时按已有客户定位信息选择列表，并核对其覆盖范围。
+
+创建、发放、领取、使用或修改资产尚无入口。
+
+## 选定入口后
+
+读取所选 schema，例如 `zan-saas schema benefit.customer-card.get`，核对身份范围、定义或实例标识、前置与结果边界。定义标识、卡号及客户标识不能互换。
+
+持卡列表的参数错误可指出具体选项，恢复判断按 shared 的错误消费规则执行。已发送后的失败须停止核查，不将错误当作客户无卡，也不自动初始化应用或重放查询。
+
+需要区分定义与实际持有时，按目标读 [定义详情](references/card-get.md) 或 [定义目录](references/card-list.md)；需要跨页定位实例时读 [持卡列表](references/customer-card-list.md)，只已知卡号时读 [持卡详情](references/customer-card-get.md)。日期、状态编码和字段精度直接读契约，不在指引重复维护。
+
+查询发放过程、来源店铺或解释与当前持卡不一致时，读[发放记录](references/card-grant-list.md)。来源店铺不同不触发切店或补查；当前持卡与发放日志各有自己的身份和范围。
+
+卡定义与领取记录列表取得可靠总数时返回 `pagination.total`；客户持卡列表不提供可靠总数，不能用本次条数推算；保持店铺、筛选和容量，按 `nextPageNo` 继续。`nextPageNo=null` 不能单独解释为结束；`windowLimitReached=true` 表示入口页码上限，仍有后续，不保证跨页快照或全量。仅适用于契约提供这些字段的列表。

package/skills/zan-saas-benefit/references/card-get.md

@@ -0,0 +1,7 @@
+# 卡定义与客户持卡
+
+查询卡的配置使用 `zan-saas benefit card-definition get`。完整定义别名与实例卡号是不同身份，不用商品 ID、手机号或持卡号替代定义别名。
+
+用户问“客户是否有这张卡”时，应查客户持卡并关联定义；问“是否能领或使用”时，定义存在与配置可用仍不足以证明资格或实际持有。
+
+字段、选定权益与调用前置读 `zan-saas schema benefit.card-definition.get`。未公开的完整发放条件和客户状态不从选定权益摘要补推。

package/skills/zan-saas-benefit/references/card-grant-list.md

@@ -0,0 +1,11 @@
+# 权益卡发放记录
+
+使用 `zan-saas benefit card-grant list` 查看查询店铺或该店铺内指定客户的一页历史记录。调用前读同版 schema，确认店铺、客户筛选和分页范围。
+
+一条记录关联客户、卡定义和卡号。卡定义描述配置，客户持卡描述实例，发放记录描述过去的一次发放或领取。假设同一客户同一卡号返回两条记录，仍逐条保留，不能合并成一次发放，也不能据此重放、撤销或判定当前可用。
+
+省略客户条件表示店铺级查询；明确提供空客户标识会失败，不能退回更大的店铺范围。来源店铺是该记录的领取来源，可以与查询店铺不同，不用它切换身份或查询其他门店。
+
+每次只读一页。短页不能代替分页判断；以本次总条数与分页信息决定是否继续，不能把多次读取称为稳定快照。缺少核心关联、分页矛盾、预算超限或业务拒绝时整体失败，不输出部分记录或补成空列表。
+
+需要客户当前持卡时按已知客户选择 `benefit customer-card list`，只已知完整卡号时选择 `benefit customer-card get`。当前没有发卡、撤销、使用或独立发放记录详情入口。

package/skills/zan-saas-benefit/references/card-list.md

@@ -0,0 +1,7 @@
+# 卡定义目录的使用边界
+
+使用 `zan-saas benefit card-definition list` 浏览店铺卡定义。目录回答“有哪些卡定义”，不能回答某客户已持有哪些卡或是否具备发卡资格。
+
+从 `zan-saas schema benefit.card-definition.list` 读取目录范围和继续方法。需要定义详情时，用已确定的定义标识选择详情；缺少有效定位信息时先澄清，不能为寻找卡而自动枚举全部定义。
+
+一页没有匹配、卡被禁用和客户未持卡是不同事实；只根据本次可观察范围报告。

package/skills/zan-saas-benefit/references/customer-card-get.md

@@ -0,0 +1,7 @@
+# 只知道卡号时查询实例
+
+使用 `zan-saas benefit customer-card get` 读取已知卡实例的客户关联与有效期。实例卡号与定义别名、外部卡号、手机号不互换。
+
+先读 `zan-saas schema benefit.customer-card.get`。本入口不提供当前可用状态；不能因有效期看似覆盖当前日期，就回答卡可用或已激活。
+
+需要状态且已知客户身份时，选择持卡列表并核对实例及覆盖范围。缺少关联或必要授权时报告缺口，不猜客户或枚举卡号。

package/skills/zan-saas-benefit/references/customer-card-list.md

@@ -0,0 +1,7 @@
+# 在客户持卡中定位实例
+
+使用 `zan-saas benefit customer-card list` 查询指定客户持卡。卡实例关联客户与定义；同一定义下的不同卡号仍是不同实例，不能合并。
+
+从 `zan-saas schema benefit.customer-card.list` 确认状态筛选、分页范围和实例字段。用户问“所有持卡”时先核对查询覆盖，不把默认查询或有限页面当成删除历史全集。
+
+需要详情时先固定完整实例卡号。持卡结果不证明已核销或可以发放；查询失败不能解释为无卡。

package/skills/zan-saas-coupon/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: zan-saas-coupon
+description: 查询券发行活动摘要或详情、客户一页持券或已知持券详情时使用。区分发行活动与实际持券、优惠券与权益卡，不把预算或状态当作客户资格及订单可用证明。
+---
+
+# 优惠券 coupon
+
+先读取 `zan-saas skills read zan-saas-shared`，再按本域选择对象。
+
+## 对象与边界
+
+本域负责券发行活动与客户实际持有的券。活动与持券不是同一对象。资源 `activity` 是券发行活动，描述优惠定义、预算和使用范围；资源 `voucher` 是客户实际持有的单张券。一个活动可以产生多张持券，同一客户也可以持有同一活动的多张券。活动 ID、持券 ID 和客户标识不能互换；活动存在不表示某个客户已经领券。持券详情使用形态与持券 ID 的复合身份，不能只凭 ID 猜测卡券或优惠码。
+
+活动归属店铺、领取店铺和使用店铺不能相互代换。当前仅支持凭证店铺与活动归属店铺一致的读取，不支持总部代查其他归属店铺或跨店共享券查询。
+
+客户持券列表只查询所选形态的默认活动类别范围。卡券默认普通优惠券类别，不承诺完整覆盖三方券、兑换券、买赠券或运费抵扣券；优惠码不承诺所有码活动。需要客户全部券资产时，当前入口不能给出完整结果。
+
+例如，假设活动 A 是“会员日满减券”，查询到 A 的领取数量，不表示客户甲持有某张券，更不表示该券可用于客户甲的订单。预算领取数量也不是去重客户数。
+
+客户资料转交 `zan-saas-customer`；会员身份转交 `zan-saas-member`；会员权益卡定义与客户持卡转交 `zan-saas-benefit`；储值资产转交 `zan-saas-valuecard`。本域不拥有订单、支付或交易完成事实。
+
+## 任务与命令
+
+| 用户目标 | 当前入口与判断 |
+| --- | --- |
+| 按名称、时间阶段、展示分类或创建窗口定位活动摘要 | `zan-saas coupon activity list --form card\|code`，读取 [活动列表说明](references/activity-list.md)，再核对同版 help/schema。两组分别分页，不能自动合并。 |
+| 已有活动 ID，需要解释优惠定义、预算或使用范围 | `zan-saas coupon activity get`，先读 [活动详情与范围](references/activity-get.md)，再核对同版 help/schema；不展开关联对象，也不把结果当完整编辑快照。 |
+| 明确客户、店铺及券形态，查询客户有哪些券 | `zan-saas coupon voucher list`，先读 [客户的一页持券](references/voucher-list.md)，再核对同版 help/schema；按持券而不是按活动合并。 |
+| 已知券形态和持券 ID，查询单张券及已有持有人或订单引用 | `zan-saas coupon voucher get`，先读 [单张持券详情](references/voucher-get.md)，再核对同版 help/schema；订单引用不证明交易完成或最终核销。 |
+| 判断某订单可用券、领取资格、跨店持券或完整编辑配置 | 当前查询不提供这些结论。说明能力缺口并停止，不从预算或状态推断，不自动转 Raw API。 |
+| 发券、创建活动、核销或作废 | 当前没有写入命令，不执行这些操作。 |
+
+不因领域职责说明而假设未注册入口存在。
+
+## 执行与结果边界
+
+有效上下文可补全店铺；缺少上下文时只允许显式店铺的本地预览。真实执行先核验同一凭证店铺，再读取一页或一个详情，最多两个请求。核验不证明店铺员工身份授权；各入口的产品支持范围以对应契约为准，不能互相套用。
+
+可选字段缺失保持省略，不提供 `--include`。活动状态、持券状态及列表筛选状态各有含义，按所选契约解释。分页不会自动补查详情或翻页，到达窗口上限不能称为全量。查询活动不能证明客户持券，查询持券也不能证明某笔订单可用。
+
+活动中按渠道返回的商品范围是旧渠道配置引用，不能代替OneID。继续查商品前按活动详情reference核对身份对应；不把历史引用当作商品当前存在或可售的证明。

package/skills/zan-saas-coupon/references/activity-get.md

@@ -0,0 +1,11 @@
+# 已知券活动的详情与范围
+
+已经取得券发行活动 ID，需要解释活动定义时，核对同版 `zan-saas coupon activity get --help` 和 `zan-saas schema coupon.activity.get` 后选择本入口。活动 ID 不是客户持券 ID、券码或活动 alias。
+
+例如，运营人员问“会员日满减券的优惠方式、预算和使用商品范围是什么”，查询的是发行活动。若问“客户甲领了哪张券”或“这笔订单能否用券”，活动详情不能回答，不能用活动正常或存在使用商品引用代替客户持券及交易校验。
+
+预算是活动统计，不是客户余额。使用范围只保留本次返回的配置引用，不展开商品、分组或店铺成员。范围缺字段不代表无限制，空数组也不能代替类型判断；需要完整成员或编辑快照时停止，不把结果直接回写。
+
+活动归属店铺必须与目标及凭证店铺一致，领取店铺和使用店铺不能替代归属店铺。归属不符、规则不支持或协议错误时，核对原目标与同版契约，不换店搜索，不自动追加持券、客户或商品查询。
+
+网店、门店使用范围的 `channel_item_ids` 和可兑换范围的 `exchange_channel_item_ids` 是各自渠道的旧商品配置引用。不能直接填入统一商品 ID 参数，也不能用当前商品档案改写活动配置。跨域关联前读 `zan-saas skills read zan-saas-item references/product-identity.md`。

package/skills/zan-saas-coupon/references/activity-list.md

@@ -0,0 +1,15 @@
+# 券发行活动单页摘要
+
+查询活动目录使用 `zan-saas coupon activity list`，需要客户已持有的券时使用持券查询。先明确优惠卡券或优惠码形态，无法区分时补齐这个选择，不把两种形态拼成一个分页集合。
+
+读取 `zan-saas schema coupon.activity.list`，按用户目标选择名称、阶段、展示分类或创建窗口。筛选阶段与返回的活动状态含义不同，不能直接复制结果状态作为筛选。
+
+创建窗口的格式、精度及端点限制从契约读取，不把时间筛选解释为快照或端点包含保证。
+
+活动创建时间可只给一端；保留该单边条件，不代填另一端。使用单一区间选项，原开始与结束参数已移除；具体写法从同版 schema 取得。
+
+预算只描述活动本次返回的统计，缺失不是零，负数也不能自行解释为不限量。状态只按契约解释；无法区分的失效原因或未来未知值不补成正常。
+
+每次只读取一页。短页不证明结束，按分页契约保留原店铺、形态与条件继续；页窗口耗尽但仍有后续时，说明未覆盖范围并停止。收窄条件是新查询，不承诺无重无漏或同一快照。
+
+已经定位活动且需要优惠定义、预算或使用范围时，选择 `zan-saas coupon activity get`。列表失败时核查原目标与授权，不改形态、切店或逐条查详情代证。

package/skills/zan-saas-coupon/references/voucher-get.md

@@ -0,0 +1,13 @@
+# 单张客户持券详情
+
+已知持券 ID 和形态时，使用 `zan-saas coupon voucher get`。先核对同版 `zan-saas schema coupon.voucher.get`；活动 ID、持券 ID、客户开放 ID 和核销码不能互换，缺少完整复合身份就停止，不靠外观猜类型，也不扫描列表碰撞 ID。
+
+优惠卡券与优惠码按契约选择形态，同店凭证先核验再查询。本命令不自动补查活动、客户或订单，也不因未找到而换形态重查。
+
+结果描述客户实际持有的单张凭证，不是发行活动定义。状态、有效期与字段缺失按同版契约解释，不能用正常状态证明某笔订单可用，也不能把未知有效期当永久有效。
+
+已有持有人和订单引用只说明本次返回的关联，缺失不证明没有持有人或从未使用。冻结、核销等状态不补造未返回的订单，订单引用也不证明支付、交易完成或最终核销。
+
+例如，“客户甲这张券是否已冻结、关联哪个订单”属于持券详情；“这项活动的预算或领取规则”属于活动，不用持券状态回答。客户档案和交易事实由对应领域负责，本命令不补查它们。上游明确凭证不存在时按未找到处理，不切类型重查。
+
+仅承诺凭证店铺与持券归属店铺一致，不以发放店铺替代归属，也不承诺总部代查或跨店共享券。详情和列表的产品范围分别按契约核对，不能因列表成功而推定详情可用。同店核验不证明员工授权或权限隔离。

package/skills/zan-saas-coupon/references/voucher-list.md

@@ -0,0 +1,25 @@
+# 明确客户的一页持券
+
+用户问“这个客户有哪些券”时，先明确客户的 `yzOpenId`、目标店铺及形态。卡券用 `card`，优惠码用 `code`，不能替用户猜形态，也不能把手机号、微信 openId 或员工 ID 当作客户标识。
+
+选择 `zan-saas coupon voucher list` 后，读取 `zan-saas schema coupon.voucher.list`。活动描述发行对象，持券描述客户实际持有的单张凭证；持券 `voucherId`、活动 `activityId` 与客户 `yzOpenId` 不能互换。同一客户可以持有同一活动的多张券，不按活动合并。
+
+只支持凭证所属目标店铺，不因总部位置自动跨店；店铺、产品范围和授权前置按本入口契约核对，不能从持券详情的范围类推。应用凭证验证不证明员工授权。
+
+## 筛选与单券状态
+
+卡券形态默认查询普通优惠券类别，不承诺完整覆盖三方券、兑换券、买赠券或运费抵扣券。优惠码形态仅覆盖该分组默认返回范围，不承诺所有码活动；这不表示未承诺的类别必然不会返回。
+
+列表筛选按领取后的使用与过期阶段选择，返回状态描述单券生命周期，两个字典不可互套。需要查“已使用或已过期”时，不把该筛选解释为商家作废。
+
+具体值和默认覆盖从 schema 取得，未来未知状态不当正常，也不从本地时间推算使用状态、客户资格或订单可用性。
+
+## 一页结果与停止条件
+
+总数只覆盖本入口默认活动范围与当前筛选。“全部状态”也只指这一范围，不是全部券类别或客户全部券资产。短页不表示读完，没有可用的下一页页码也可能是达到页码上限；按契约区分窗口耗尽与结果耗尽。继续时保留店铺、客户、形态、状态及页容量，在明确预算内逐页读取，不自动扫描或承诺快照。
+
+本次结果只解释已声明的券身份、关联及状态。未返回面额、折扣或其他资料时，不能从标题和描述解析出金额、规则或核销码。需要已知单券的已有持有人或订单引用时，选择详情并重新核对形态和标识。
+
+需要指定活动下的客户持券、全店持券、其他未覆盖券类型或订单可用券时，说明能力边界，不靠扫描、Raw API 或补查凑结果。空页不证明客户从未领券，明确客户不存在也不能改成空持券成功。
+
+整页任一身份或固定字段不符均失败，不输出部分结果。按错误的类别、阶段、发送情况和安全下一步核查；不因权限失败、未知结果或店铺核验失败自动重放。

package/skills/zan-saas-customer/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: zan-saas-customer
+description: 客户领域指引。按条件查询一页或有界扫描客户摘要，查询客户档案、标签定义、标签组和客户标签关系时使用；说明客户与会员、权益的边界及当前命令范围。
+---
+
+# 客户 customer
+
+首次使用或 CLI 版本变化时，读取 `zan-saas skills read zan-saas-shared`。本指引用于理解对象和选择入口，调用细节读取同版 help/schema。
+
+## 领域说明
+
+客户是商家范围内的经营对象。客户档案、行为查询、标签与分群属于本域；客户身份不等同于会员身份，领域职责不表示本版已提供全部操作。
+
+会员身份、等级和成长值见 `zan-saas skills read zan-saas-member`。客户/会员权益的定义、发放与持有见 `zan-saas skills read zan-saas-benefit`。分群可引用这些事实作为条件，不拥有其写入规则，也不负责触达计划。
+
+## 资源与关系
+
+- 客户 `customer`。店铺范围内的客户档案，用所属店铺与客户稳定标识 yzOpenId 定位。
+- 标签 `tag`。店铺定义的客户特征标记。标签定义存在，不表示某客户已具有该标签。
+- 标签组 `tagcategory`。组织标签定义的分组；组、组内标签和客户分别有自己的身份。
+- 客户标签关系 `customer-tag`。关联客户与标签的读取视图，用来回答某客户具有哪些标签；不是标签或标签组的定义目录。
+
+例如，标签组“偏好”中有标签“咖啡”，只能说明店铺配置了这个标签。客户甲是否具有“咖啡”标签，需要查询客户甲的标签关系。不能用客户、标签或标签组的 ID 互相替代，也不能用其中一个对象的空结果判断另一个对象不存在。
+
+客户详情可以聚合展示标签、等级、权益或交易摘要。聚合展示不转移相邻领域的维护权，也不据此推导会员身份、卡可用性或权益发放结果；需要这些事实时按对应领域选路。
+
+等级关系与客户身上的单值等级摘要分别读取，不从摘要推算免费、付费等级或会员身份。客户卡摘要中的标识也不能直接当作权益卡定义别名或持卡号；需要卡的配置或持有事实时，转交权益领域并补齐该对象的标识。
+
+分群定义与分群内客户关系是不同对象。`segment-customer` 表示本次观察到的命中客户，可以包含会员和非会员；`member` 仍表示会员。以店铺与分群 ID 定位集合，以同店 yzOpenId 引用客户，不用分群名称自动选群，也不以手机号或昵称合并客户。等级、卡名不证明会员身份、卡当前有效性或可触达性。
+
+客户档案中的余额卡、礼品卡余额摘要沿用储值卡领域术语。两类摘要的归集范围未明确，不能相加为客户总资产，也不能断言等于逐卡余额求和。要查某张卡的余额或状态，读取 `zan-saas skills read zan-saas-valuecard`；一页持卡也不能代证完整资产。
+
+## 按目标选择命令
+
+当前入口以 `zan-saas customer --help` 和 `zan-saas schema customer` 为准。下表同时提供用户目标选路与命令索引：
+
+| 用户目标 | 命令入口 |
+| --- | --- |
+| 查询一个客户的档案，或在档案中追加相关摘要 | `zan-saas customer customer get` |
+| 浏览一页客户，按单手机号、会员、标签、等级、持卡或时间与数值区间筛选 | `zan-saas customer customer list` |
+| 在明确成为客户时间内，按手机号、标签、等级或持卡等条件有界跨页读取客户摘要 | `zan-saas customer customer scan` |
+| 获取一个客户的标签集合及本次返回的分组信息 | `zan-saas customer customer-tag get` |
+| 继续使用已有 list 输出契约的调用 | `zan-saas customer customer-tag list` |
+| 查询一个已知标签的定义 | `zan-saas customer tag get` |
+| 查询一个已知标签组及本次返回的组内标签 | `zan-saas customer tagcategory get` |
+| 浏览标签组目录 | `zan-saas customer tagcategory list` |
+| 按名称发现已保存分群，取得稳定分群 ID 和本次报告人数 | `zan-saas customer segment list` |
+| 查询一个已知自定义分群内的一页客户及其已返回摘要 | `zan-saas customer segment-customer list` |
+
+只问“客户有哪些标签”时选择 `customer-tag get`，结果受本次授权可见范围限制。还需要客户档案及标签摘要时，可以选择客户详情的标签扩展。`list` 保留已有调用契约；两种关系入口不是别名，不宣称 get 更实时或 list 覆盖全部历史，分组缺失的解释也不能互相套用。失败后不切换入口代证。
+`customer-tag get` 省略 `--kdt-id` 时使用当前选中的店铺；也可显式指定目标店铺，实际权限由服务端校验。
+
+`customer list` 每次只查询一页，默认不筛会员，固定按创建时间降序。手机号只接受单值 `--mobile`，可组合其他筛选；不是批量号码查找，也不能用姓名或手机号替代稳定 yzOpenId。需要档案时再用返回的 yzOpenId 调用 `customer get`。
+
+数值区间使用 `LOW..HIGH`、`LOW..`、`..HIGH`，裸值表示相同双边；时间必须含 `..`，固定北京时间，不补省略边界。金额输入为人民币元文本，最多两位小数。实际选项及规范化模型以同版 help/schema 为准。
+
+标签 ID 固定全部满足。等级和卡必须用定义数值 ID，不能用等级 alias、等级值、cardAlias 或客户持卡实例 cardNo 替代。`benefit card-definition list` 的 cardId 可供卡筛选使用；现有等级 get 的 alias 或等级值不能直接当等级定义 ID。多值等级和卡集合不承诺 AND/OR；`has-level=false` 与等级 ID 冲突，`has-benefit-card=false` 与卡 ID 冲突，指定 ID 不自动补 true。等级、持卡和入会时间不独立证明当前会员身份，持卡不证明卡有效或可支付。
+
+分页返回 pageNo、pageSize、hasMore，取得可靠总数时另返回 total，无法判断的继续状态为 null。空页或短页不证明读取全量，达到窗口上限不自动翻页。筛选金额、购次、积分、储值沿用搜索口径，不表示全渠道交易或客户全部资产，也不把输入条件补成返回事实。
+
+`customer scan` 必须有完整成为客户时间范围，且受客户数量与业务请求预算约束。单手机号可叠加筛选，不按同号合并客户；客户的稳定引用仍是店铺与yzOpenId。等级定义ID不是alias或等级值，卡定义ID不是客户持卡实例号。筛选命中不证明卡当前有效，也不把客户变成会员，详见[扫描选路与边界](references/customer-scan.md)。
+
+分群是已保存的客户分群定义，规则形成动态成员。`segment list` 只读一页目录，默认当前有效上下文店铺，可按名称关键词查找。用店铺与字符串 `segmentId` 引用分群，不能用重名的名称、客户 yzOpenId 或标签 ID 替代。目录 `customerCount` 是本次报告人数，不是成员快照；名字也不证明规则正确。需要检查规则或成员时停止，本版没有分群详情或成员入口，不能改用客户列表猜测分群结果。分页与继续读取边界见[分群目录](references/segment-list.md)。
+
+已有分群 ID 时直接用 `segment-customer list`，不先遍历客户或读取分群规则。需要完整档案时，再以本页 yzOpenId 在同店调用 `customer get`。分群客户页是动态观察，不是历史名单；跨页可能新增、删除、重复或遗漏，失败不自动重放。想看“上周分群名单”时停止说明缺少快照能力，不能用当前页代证。
+
+分群规则读取、创建和成员管理尚无入口；缺少分群 ID 时先取得该店的明确 ID，不自动选择同名分群。多手机号批查、来源渠道、后台导出、独立行为查询、标签或分群管理及客户资料修改尚无对应入口。扫描遍历结束也不是快照或无遗漏导出证明，不能用它替代后台导出或全店数量统计。
+
+## 选定入口后
+
+用 `zan-saas schema <点分隔命令路径>` 读取所选命令，例如 `zan-saas schema customer.tagcategory.get`；参数拼写可另查叶子 help。按 schema 确认输入输出、适用范围、授权前置和未覆盖事项，再准备调用。
+
+真实查询须满足所选命令的前置，不能由本地上下文、另一条查询或预览成功代替必要授权证据。集合范围与继续读取方法也按该命令契约处理，不从一页目录或一次关系结果推断完整历史或全域不存在。

package/skills/zan-saas-customer/references/customer-scan.md

@@ -0,0 +1,11 @@
+# 有界客户扫描
+
+需要在明确成为客户时间内组合条件读取有限客户摘要时，选择 `zan-saas customer customer scan`。已经知道稳定客户标识、需要档案或资产等摘要时用 `customer customer get`，不要为了单个客户重扫范围。
+
+先读取 `zan-saas schema customer.customer.scan` 和叶子 help，确认范围语法、筛选含义、预算和错误模型。参数、默认值、类型及字段唯一维护在这两个入口，不在指引复制。
+
+手机号只是精确搜索条件。同号可能有多个yzOpenId，不能自动选第一人。标签固定全部满足；等级条件使用等级定义level_id，不能以alias或等级值代替；持卡条件使用卡定义cardId，可从 `benefit card-definition list` 取得，不能使用cardAlias或客户cardNo。筛选不等于授权或持卡有效性证明，省略摘要明细也不表示业务无值。
+
+扫描按实际请求顺序保留首次观察到的客户，不保证跨窗口全局排序。检查结果中的停止原因和遍历标记；数量或请求预算停止、最小时间桶越窗、总数未知及页不一致都不是读取完整。即使计划中的叶窗全部结束，也不证明快照或无遗漏。
+
+没有恢复游标，重新执行是新的观察，不从最后一个客户推导精确续传。失败不会输出前批客户，不在失败后自动换店、换身份或换查询模式。需要批量手机号、来源渠道、后台导出或全店权威数量时说明此入口未覆盖，不用扩大预算冒充这些能力。

package/skills/zan-saas-customer/references/segment-list.md

@@ -0,0 +1,22 @@
+# 查找已保存分群
+
+用户想按名称找分群、获取稳定分群ID或查看目录报告人数时，选择 `zan-saas customer segment list`，先读取 `zan-saas schema customer.segment.list`。
+
+默认使用本次有效上下文的店铺。`--kdt-id` 可显式指定目标，非法显式值不回退；非总部目标须与上下文店铺一致，总部仍由服务端核验授权。缺少上下文时只能用显式合法目标本地预览；预览不证明对象存在或权限有效。
+
+按名称关键词查找不保证精确匹配。同名分群不能合并，用店铺与 `segmentId` 定位，不把分群ID转为JavaScript Number。
+
+每次只读一页。需要继续时先按同版schema判断分页状态与页码边界，再保留原筛选条件和容量，显式请求下一页。分页状态未知时不能推断还有多少页；空页或短页本身不证明取完。没有稳定排序、快照、扫描或无遗漏导出保证。
+
+参数约束、结果字段、类型代码、空值与预算均以 `zan-saas schema customer.segment.list` 为准。类型代码未知时不要猜测含义；编辑器模式不是规则版本。
+
+目录不承诺覆盖全店所有产品分群。分群规则形成动态成员，`customerCount` 只表示本次报告人数，不是当前成员快照、历史名单或计算截止时间。名称不证明实际规则正确。本版没有分群详情、成员读取或规则写入命令；需要这些事实时停止，不从目录或客户筛选推断。
+
+失败时按stderr的脱敏错误核查原目标，不自动重放、切店、换身份或查详情，不把部分目录当作成功结果。
+
+```sh
+zan-saas customer segment list --keyword '首购'
+zan-saas customer segment list --kdt-id 63077 --keyword '首购' --dry-run
+```
+
+预览可核对目标与请求计划，不读取凭证、不联网，也不证明对象存在或授权有效。

package/skills/zan-saas-fulfillment/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: zan-saas-fulfillment
+description: 履约：查询订单发货单、商品明细、配送单详情及物流运单轨迹，区分货单、配送单与物流运单。
+---
+
+# 履约 fulfillment
+
+首次使用或 CLI 版本变化时先执行 `zan-saas skills read zan-saas-shared`。本领域说明订单如何组织待交付商品及关联配送，不判断交易付款、售后完成或库存出库。
+
+## 对象与关系
+
+本域有发货单 `shipment`、配送单 `delivery` 和物流运单 `waybill` 三个资源，分别表达交付商品的组织、配送执行与承运商运输记录。
+
+一个订单可以关联多张发货单，发货单可以关联多条配送引用。发货单说明交付哪些订单商品、从哪里出货及货单状态。商品明细中的订单条目 ID 不是商品主档 ID，同一商品主档不能用来合并货单商品行。
+
+货单号 `shipmentNo` 与配送单号 `deliveryId` 是不同对象的标识，不能互换。配送可以是快递、同城送或自提，不专指骑手配送。
+
+物流运单是承运商运送包裹的记录，不等同有赞配送单；货单列表中的配送引用不是物流轨迹，也不能据其状态推断签收。
+
+### 假设的拆单例子
+
+假设订单 O 中，同一商品主档 P 对应两个独立交易条目 T1、T2，分别由货单 S1、S2 交付。S1 的商品行保留 T1，关联配送引用 D1；S2 的商品行保留 T2，关联配送引用 D2。不能因商品主档相同就合并两行或两张货单。此例只解释关系，不规定拆单规则或对象数量上限。
+
+S1、S2 是货单号，D1、D2 是配送单号。查订单如何拆单选 shipment list，查 D1 配送详情选 delivery get。若 D1 是支持的快递配送，详情中的运单引用必须同时匹配所属订单、店铺、货单号与配送单号，取得承运商 C 和运单 W 后才能选 waybill get。不能把 S1 或 D1 当作 W，也不能仅从发货单列表推导 C、W；轨迹结果不反向证明订单或配送归属。
+
+## 选择入口
+
+已知订单号，想查分几张货单、每张包含哪些商品或有哪些配送引用时，选择 `zan-saas fulfillment shipment list`。该入口返回订单范围内本次取得的集合，不提供单货单精确查询。
+
+订单号外观只作核对提示，不按前缀或位数排除查询。订单查询成功不证明履约对象存在、接口支持或授权通过；使用原始订单号，核对返回的订单及店铺关联，接口拒绝时按错误停止。
+
+读取 `zan-saas schema fulfillment.shipment.list` 后再调用，核对身份、目标店铺和结果范围。需要判断空集合、追查配送或区别状态时，读 [发货单查询判断](references/shipment-list.md)。
+
+已知有赞配送单号，想查配送执行情况时，选择 `zan-saas fulfillment delivery get`。先读 `zan-saas schema fulfillment.delivery.get`；需要区分快递、同城送与自提，或从配送继续追踪包裹时，读 [配送单查询判断](references/delivery-get.md)。该入口不提供总部跨分店查询能力。
+
+已知承运商 ID 与完整运单号，想查运输状态及轨迹时，选择 `zan-saas fulfillment waybill get`。先读 `zan-saas schema fulfillment.waybill.get`；需要判断轨迹空集合、查询失败或对象归属时，读 [运单查询判断](references/waybill-get.md)。缺少承运商 ID 或运单号时停止轨迹查询，不从公司名称猜测 ID。

package/skills/zan-saas-fulfillment/references/delivery-get.md

@@ -0,0 +1,11 @@
+# 配送单查询判断
+
+用户已知有赞配送单号并要查配送执行情况时，选择 delivery get。货单号、物流运单号及同城服务商单号不是有赞配送单号，不能互换。只知道订单号时，先从 shipment list 读取配送引用，再按引用的配送单号查询。
+
+主响应的所属订单号按原值用于关联及快递补查，不因订单号前缀或位数停止。接口拒绝、关联冲突或必需引用未取得仍按错误停止，不把这些结果解释为无配送或无运单。
+
+配送单不专指骑手单。命令按类型自动返回适用内容，不需要调用者挑选模块。支持的快递配送会查询货单集合，并在订单与店铺范围内精确匹配货单号和配送单号，取得运单引用；不会选择第一条或只按订单号关联。同城配送的服务商信息不能当作物流运单引用，自提与其他类型也不补造快递信息。
+
+配送状态描述配送执行，不是承运商签收状态。“已发货”不证明物流签收或订单完成。已知状态及未来未知值如何保留，以同版 schema 为准，不根据未知数字猜测含义。类型决定的请求上限、默认内容及产品支持范围也从 schema 读取，不将本入口扩大到总部或连锁跨店查询。
+
+只有快递配送详情中取得承运商 ID 和完整运单号后，才能选择 waybill get。关联缺失或重复、条件查询失败时，停止并按错误建议处理，不把不完整详情当作成功，不通过货单号或配送单号代替运单号。轨迹命中本身仍不证明订单或配送归属。

package/skills/zan-saas-fulfillment/references/shipment-list.md

@@ -0,0 +1,11 @@
+# 发货单查询判断
+
+用户要了解订单拆分与待交付商品时，以发货单为观察对象。保留每张货单与其商品、配送的从属关系，不把多张货单合并为一张，也不只读取第一张。
+
+返回空集合只说明本次未取得货单，不能据此断言订单不存在、无需发货或已经履约完成。需要判断交易或售后状态时，应另找所属领域的已发行入口。
+
+订单号格式提示不决定查询资格。调用保留原始订单号，响应必须关联同一订单和店铺；不能把接口拒绝当作空货单，也不能把交易订单可查询扩大为履约支持保证。
+
+货单状态与配送引用状态描述不同对象，不能套用彼此的代码含义。具体值及未知值政策读取同版叶子 schema。
+
+查询配送详情需实际配送单标识，选择 delivery get；物流追踪需承运商与运单标识，选择 waybill get。当前入口只提供配送引用，不承诺取消配送全集、完整历史、配送详情或包裹轨迹。缺少必要标识时明确停止，不从引用或备注推断结果。

package/skills/zan-saas-fulfillment/references/waybill-get.md

@@ -0,0 +1,9 @@
+# 运单查询判断
+
+用户已知承运商与运单，想了解包裹运输状态时，以物流运单为观察对象。选择 `zan-saas fulfillment waybill get` 前读取同版 `zan-saas schema fulfillment.waybill.get`，确认标识、授权、结果范围及状态解释。
+
+运单查询不能替代配送详情，也不是电子面单取号、打印或取消。命中运单不证明其属于某个订单、配送单或售后；关联关系须另有事实依据，不能由时间接近或相同收件信息推断。
+
+轨迹随查询固定返回，不存在关闭轨迹后继续成功的降级入口。成功但轨迹为空只表示本次没有返回轨迹，不证明尚未发货或已经签收。事件按上游顺序保留，时间与状态文本保留原文，不据此猜测时区或重新排序。运输状态的具体值及未知值政策以同版 schema 为准。
+
+查询失败时停止并核对目标店铺、承运商 ID、完整运单号及平台发货记录，不自动切换身份、店铺或接口。不能通过空轨迹或查询失败断言运单在所有范围内不存在；缺少配送关联或当前入口不支持配送详情时明确停止，不拼装未发行命令。

package/skills/zan-saas-interaction/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: zan-saas-interaction
+description: 互动营销领域指引。定位抽奖活动、查看活动配置时使用；不把活动奖项配置当作客户中奖记录或实际到账资产。
+---
+
+# 互动营销 interaction
+
+首次使用或 CLI 版本变化时，读取 `zan-saas skills read zan-saas-shared`。
+
+## 对象与关系
+
+本域拥有互动营销活动的配置视图。抽奖活动 `lottery` 用活动 ID 定位，玩法是活动类型，不是另一套资源，包括刮刮卡 cards、幸运大抽奖 wheel、生肖翻翻看 zodiac、疯狂猜猜猜 crazyguess、有赞摇一摇 shake。已知活动 ID 时直接读取该活动，不要求调用者另选玩法，也不默认 wheel。
+
+按玩法查询列表时必须明确选择，不默认或跨玩法兜底。
+
+活动定义参与时间、状态、次数限制和奖项。奖项 ID 标识活动内的奖项配置，不是活动 ID，也不是发放后的优惠券、权益卡或积分账户标识。活动参与记录、中奖记录和实际奖励资产分别拥有事实，不能从活动汇总计数证明某个客户中奖或奖励到账。
+
+优惠券发行活动和客户持券查询转交 `zan-saas skills read zan-saas-coupon`；积分账户和流水转交 `zan-saas skills read zan-saas-points`；权益定义与持有实例转交 `zan-saas skills read zan-saas-benefit`。
+
+## 按目标选择入口
+
+| 用户目标 | 命令入口及判断 |
+| --- | --- |
+| 已知活动 ID，核对参与规则、奖项或页面配置 | `zan-saas interaction lottery get`；先读取 [单个活动配置指引](references/lottery-get.md) 和同版 schema，不要求 kind，不扫描列表补详情。 |
+| 按一种玩法定位活动，查看一页活动状态、参与限制及奖项摘要 | `zan-saas interaction lottery list`；先明确玩法，不默认wheel，不隐式跨五种玩法查询。 |
+
+先读 `zan-saas schema interaction.lottery.list` 核对选项、四字段分页和递归输出。需要判断空页、状态码或奖项结果时，读[抽奖列表判断](references/lottery-list.md)。
+
+不提供参与或中奖记录入口。用同版 `zan-saas interaction --help` 和 `zan-saas schema interaction` 核对已发行能力，不推测未登记入口。
+
+## 结果与停止条件
+
+列表只证明同店凭证范围内、指定玩法与筛选下的一页结果。需要已知活动配置时转详情；客户是否中奖或奖励到账不能用列表摘要或奖品名称代替，缺少对应入口时停止。输入state与输出status不是同一套数字字典，暂停状态不能当成结束。
+
+没有参与抽奖、创建活动、发奖、签到或客户中奖记录入口。需要这些结果时停止，不能用活动配置、参与人数或奖品名称代替实际业务事实。授权、店铺及产品支持范围以所选命令的同版契约为准。
+
+列表需要总数时读取本次筛选的 `pagination.total`；保持店铺、筛选和容量，按 `nextPageNo` 继续。`nextPageNo=null` 不能单独解释为结束；`windowLimitReached=true` 表示入口页码上限，仍有后续，不保证跨页快照或全量。仅适用于契约提供这些字段的列表。