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

package/src/commands/native/customer/customer/list/schema.json

@@ -0,0 +1,969 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "kdtId",
+      "filters",
+      "pageNo",
+      "pageSize"
+    ],
+    "description": "CLI 解析后的业务输入，不接收此对象作为 JSON 参数。范围表达式规范化为边界对象，控制项不进入业务模型。",
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/id"
+      },
+      "filters": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "省略条件不筛选。keyword 与 mobile 互斥；hasLevel=false 与 levelIds 冲突，hasBenefitCard=false 与 benefitCardIds 冲突。",
+        "properties": {
+          "keyword": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "pattern": "^\\S(?:[\\s\\S]*\\S)?$",
+            "description": "模糊搜索姓名、手机号、昵称，无首尾空白，与 mobile 互斥。"
+          },
+          "mobile": {
+            "type": "string",
+            "pattern": "^\\+?[0-9]{5,20}$",
+            "description": "精确单手机号，保留加号、国家码与前导零；不是稳定客户标识，不接受号码数组。"
+          },
+          "isMember": {
+            "type": "boolean",
+            "description": "true 会员，false 非会员；省略查全部客户，不从等级、卡或时间推算。"
+          },
+          "tagIds": {
+            "$ref": "#/definitions/ids",
+            "description": "必须全部满足的标签定义 ID，按首现去重。CLI 接受 CSV 或 JSON 字符串数组，原始 1..50 项。"
+          },
+          "created": {
+            "$ref": "#/definitions/timeRange",
+            "description": "成为客户时间，北京时间起点..终点，允许单边，不填补省略边界。"
+          },
+          "memberCreated": {
+            "$ref": "#/definitions/timeRange",
+            "description": "成为会员时间，不证明当前仍是会员，可与 isMember=false 组合。"
+          },
+          "lastTrade": {
+            "$ref": "#/definitions/timeRange",
+            "description": "最后购买时间，不表示任意窗口内购买或未下单。"
+          },
+          "tradeCount": {
+            "$ref": "#/definitions/countRange",
+            "description": "历史购次上下限，不保证全渠道口径。"
+          },
+          "tradeAmount": {
+            "$ref": "#/definitions/moneyRange",
+            "description": "累计消费金额上下限，人民币元精确文本，不表示净收入。"
+          },
+          "points": {
+            "$ref": "#/definitions/pointsRange",
+            "description": "搜索积分上下限，非负安全整数，不读取积分流水。"
+          },
+          "storedBalance": {
+            "$ref": "#/definitions/moneyRange",
+            "description": "储值余额上下限，人民币元文本，不等于逐卡可支付余额或客户全部资产。"
+          },
+          "levelIds": {
+            "$ref": "#/definitions/ids",
+            "description": "等级定义数值 ID，非 alias、等级值或客户 ID。CSV 或 JSON 字符串数组，原始 1..50 项；不推定多值 AND/OR。"
+          },
+          "hasLevel": {
+            "type": "boolean",
+            "description": "true 有等级，false 无等级；false 与指定等级 ID 冲突，不自动补 true。"
+          },
+          "benefitCardIds": {
+            "$ref": "#/definitions/ids",
+            "description": "权益卡定义数值 ID，可从 benefit.card-definition.list 的 cardId 取得，非 cardAlias、cardNo 或储值卡号；不推定多值 AND/OR。"
+          },
+          "hasBenefitCard": {
+            "type": "boolean",
+            "description": "true 有卡，false 无卡；false 与指定卡定义 ID 冲突，不证明卡有效或可用，不自动补 true。"
+          }
+        }
+      },
+      "pageNo": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 500,
+        "description": "请求页码，乘页容量不得超过 10000。"
+      },
+      "pageSize": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 50,
+        "description": "本页容量，不表示总数。"
+      }
+    }
+  },
+  "output": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "data"
+    ],
+    "properties": {
+      "data": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "customers",
+          "pagination"
+        ],
+        "properties": {
+          "customers": {
+            "type": "array",
+            "maxItems": 50,
+            "items": {
+              "$ref": "#/definitions/customer"
+            },
+            "description": "本页有限摘要，按观察顺序保留首次 yzOpenId；姓名或手机号相同不合并。明确空页才返回空数组。"
+          },
+          "pagination": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "pageNo",
+              "pageSize",
+              "hasMore"
+            ],
+            "properties": {
+              "pageNo": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 500,
+                "description": "实际请求页码，不自动翻页。"
+              },
+              "pageSize": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50,
+                "description": "实际请求的本页容量。"
+              },
+              "total": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。"
+              },
+              "hasMore": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "requests"
+    ],
+    "description": "纯本地计划，固定先店铺核验再搜索，不读取凭证或发出认证及业务请求，不证明对象、总数或权限。",
+    "properties": {
+      "requests": {
+        "type": "array",
+        "minItems": 2,
+        "maxItems": 2,
+        "additionalItems": false,
+        "items": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "method",
+              "path",
+              "body"
+            ],
+            "properties": {
+              "method": {
+                "const": "POST"
+              },
+              "path": {
+                "const": "youzan.shop.basic.get/3.0.0"
+              },
+              "body": {
+                "type": "object",
+                "additionalProperties": false,
+                "maxProperties": 0
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "method",
+              "path",
+              "body"
+            ],
+            "properties": {
+              "method": {
+                "const": "POST"
+              },
+              "path": {
+                "const": "youzan.scrm.customer.list/1.0.0"
+              },
+              "body": {
+                "$ref": "#/definitions/searchBody"
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "success",
+      "code",
+      "message",
+      "details"
+    ],
+    "properties": {
+      "success": {
+        "const": false
+      },
+      "code": {
+        "const": -10001
+      },
+      "message": {
+        "type": "string",
+        "minLength": 1,
+        "description": "受控诊断，不回显客户条件、自由消息或响应原文。"
+      },
+      "details": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep",
+          "errorVersion",
+          "recovery",
+          "execution"
+        ],
+        "properties": {
+          "category": {
+            "enum": [
+              "validation",
+              "configuration",
+              "authentication",
+              "permission",
+              "scope_unresolved",
+              "http",
+              "business_rejected",
+              "transport",
+              "protocol",
+              "limit"
+            ],
+            "description": "validation 输入错误；configuration 调用配置不可用；authentication 认证失败；permission 权限拒绝；scope_unresolved 店铺未确认；http HTTP 拒绝；business_rejected 业务拒绝；transport 传输失败；protocol 模型不符；limit 超预算。"
+          },
+          "stage": {
+            "enum": [
+              "input",
+              "context",
+              "configuration",
+              "shop-binding",
+              "search",
+              "output"
+            ],
+            "description": "input 输入；context 上下文；configuration 公共环境；shop-binding 同店绑定；search 搜索；output 输出组装。"
+          },
+          "command": {
+            "const": "customer.customer.list"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/id"
+              }
+            },
+            "description": "仅保留已校验的店铺 ID，未确定时为空对象，不包含客户条件。"
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ],
+            "description": "not_sent 相关失败请求未发送；sent 已收到响应，不等于业务成功；unknown 已发送但结果不明。"
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1,
+            "description": "保持原目标排查，不自动重放、换身份或切店。"
+          },
+          "api": {
+            "type": "string",
+            "enum": [
+              "youzan.shop.basic.get/3.0.0",
+              "youzan.scrm.customer.list/1.0.0"
+            ]
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "gatewayCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "trace_id": {
+            "$ref": "#/definitions/trace"
+          },
+          "request_id": {
+            "$ref": "#/definitions/trace"
+          },
+          "errorVersion": {
+            "const": 2,
+            "description": "本命令采用错误诊断协议第二版。"
+          },
+          "issues": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 16,
+            "items": {
+              "$ref": "#/definitions/diagnosticIssue"
+            },
+            "description": "最多十六个已定位问题，不包含收到的原值。"
+          },
+          "issuesTruncated": {
+            "const": true,
+            "description": "问题超过返回上限，当前列表没有穷尽全部问题。"
+          },
+          "recovery": {
+            "$ref": "#/definitions/diagnosticRecovery",
+            "description": "受限的恢复说明，不会自动执行。"
+          },
+          "execution": {
+            "$ref": "#/definitions/diagnosticExecution",
+            "description": "整次调用的请求观察，独立于失败阶段的 requestState。"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "id": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]*$",
+      "maxLength": 16,
+      "description": "正十进制安全整数 ID 文本，最大 9007199254740991，无首尾空白，不接受别名。"
+    },
+    "ids": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/definitions/id"
+      }
+    },
+    "requestIds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991
+      }
+    },
+    "time": {
+      "type": "string",
+      "format": "beijing-date-time-ms",
+      "pattern": "\\.000$",
+      "description": "北京时间 YYYY-MM-DD HH:mm:ss.SSS，输入允许 1..3 位零毫秒；拒绝非零毫秒，时间边界须处于 Unix 秒 0..4102444800。"
+    },
+    "timeRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "start": {
+          "$ref": "#/definitions/time"
+        },
+        "end": {
+          "$ref": "#/definitions/time"
+        }
+      },
+      "description": "起点..终点，至少一端存在且起点不晚于终点。时间必须含 ..，不接受裸时间；不补省略边界。"
+    },
+    "countRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647
+        },
+        "max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647
+        }
+      },
+      "description": "LOW..HIGH、LOW..、..HIGH；裸值规范化为相同双边，min 不大于 max。"
+    },
+    "pointsRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "description": "LOW..HIGH、LOW..、..HIGH；裸值规范化为相同双边，min 不大于 max。"
+    },
+    "money": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{2}$",
+      "description": "人民币 CNY 元，固定两位精确文本；输入最多两位小数，分值不超过 9007199254740991。"
+    },
+    "moneyRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "min": {
+          "$ref": "#/definitions/money"
+        },
+        "max": {
+          "$ref": "#/definitions/money"
+        }
+      },
+      "description": "元金额 LOW..HIGH，可单边或裸值，裸值为相同双边，精确比较 min 不大于 max，不补 0.00。"
+    },
+    "customer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "yzOpenId"
+      ],
+      "description": "有限客户摘要。可选字段未取得时省略，不补空值、零或 false；已返回字段为 null 或错型时整体失败。",
+      "properties": {
+        "yzOpenId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^\\S(?:[\\s\\S]*\\S)?$",
+          "description": "店铺客户稳定标识，非空且无首尾空白；不以内部用户数字 ID、手机号或姓名替代。"
+        },
+        "name": {
+          "type": "string",
+          "description": "客户姓名，合法空文本保留。"
+        },
+        "showName": {
+          "type": "string",
+          "description": "服务端推荐展示名，CLI 不重新排优先级，允许空文本。"
+        },
+        "mobile": {
+          "type": "string",
+          "description": "客户手机号，允许空文本，未取得不推断无手机号。"
+        },
+        "gender": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "0 其他，1 男，2 女；未知安全整数保留原码，不贴新标签。"
+        },
+        "isMember": {
+          "type": "boolean",
+          "description": "true 会员，false 非会员；不从等级、持卡或入会时间推导。"
+        },
+        "tradeCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "description": "搜索服务购次，不保证全渠道订单口径。"
+        },
+        "points": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "搜索服务积分安全整数，不从筛选条件补值。"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "beijing-date-time-ms",
+          "description": "成为客户时间，北京时间三位毫秒；零时间和 null 不可用。"
+        },
+        "memberCreatedAt": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "beijing-date-time-ms"
+            },
+            {
+              "const": 0
+            }
+          ],
+          "description": "成为会员时间，北京时间三位毫秒；额外保留数字 0 哨兵，不独立解释为非会员。"
+        },
+        "isMobileAuthorized": {
+          "type": "boolean",
+          "description": "true 手机号已授权，false 未授权；不是手机号已验证。"
+        }
+      }
+    },
+    "diagnosticCode": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "string",
+          "pattern": "^-?[0-9]{1,12}$"
+        }
+      ]
+    },
+    "trace": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+    },
+    "searchBody": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "page_no",
+        "page_size"
+      ],
+      "properties": {
+        "page_no": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500
+        },
+        "page_size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50
+        },
+        "keyword": {
+          "const": "***"
+        },
+        "mobile": {
+          "const": "***"
+        },
+        "is_member": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ]
+        },
+        "all_match_tag_ids": {
+          "$ref": "#/definitions/requestIds"
+        },
+        "level_ids": {
+          "$ref": "#/definitions/requestIds"
+        },
+        "card_ids": {
+          "$ref": "#/definitions/requestIds"
+        },
+        "has_level": {
+          "type": "boolean"
+        },
+        "has_card": {
+          "type": "boolean"
+        },
+        "created_at_start": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "created_at_end": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "created_member_at_start": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "created_member_at_end": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "last_trade_time_start": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "last_trade_time_end": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4102444800
+        },
+        "total_trade_count_min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647
+        },
+        "total_trade_count_max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647
+        },
+        "total_trade_amount_min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "total_trade_amount_max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "points_min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "points_max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "stored_balance_min": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "stored_balance_max": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "diagnosticExpected": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [],
+      "properties": {
+        "type": {
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "预期的 JSON 类型。"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "description": "预期的 JSON 类型。"
+              }
+            }
+          ],
+          "description": "同版模型允许的类型。"
+        },
+        "enum": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "契约声明的静态标量约束。"
+          },
+          "description": "同版模型允许的静态值。"
+        },
+        "const": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "契约声明的静态标量约束。"
+        },
+        "minimum": {
+          "type": "number",
+          "description": "包含的最小值。"
+        },
+        "maximum": {
+          "type": "number",
+          "description": "包含的最大值。"
+        },
+        "exclusiveMinimum": {
+          "type": "number",
+          "description": "不包含的最小值。"
+        },
+        "exclusiveMaximum": {
+          "type": "number",
+          "description": "不包含的最大值。"
+        },
+        "minLength": {
+          "type": "integer",
+          "description": "最少字符数。"
+        },
+        "maxLength": {
+          "type": "integer",
+          "description": "最多字符数。"
+        },
+        "minItems": {
+          "type": "integer",
+          "description": "最少元素数。"
+        },
+        "maxItems": {
+          "type": "integer",
+          "description": "最多元素数。"
+        },
+        "format": {
+          "type": "string",
+          "description": "同版模型声明的格式。"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "同版模型声明的字符约束。"
+        },
+        "additionalProperties": {
+          "const": false,
+          "description": "对象拒绝契约以外的属性。"
+        },
+        "contains": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "const"
+          ],
+          "properties": {
+            "const": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "契约声明的静态标量约束。"
+            }
+          }
+        },
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enum"
+          ],
+          "properties": {
+            "enum": {
+              "type": "array",
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "契约声明的静态标量约束。"
+              },
+              "description": "元素允许的静态值。"
+            }
+          }
+        }
+      }
+    },
+    "diagnosticIssue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "reason"
+      ],
+      "properties": {
+        "source": {
+          "enum": [
+            "argv",
+            "input",
+            "context",
+            "output",
+            "preview"
+          ],
+          "description": "问题所属的参数、输入、上下文、结果或预览模型。"
+        },
+        "path": {
+          "type": "string",
+          "description": "对应模型中的 JSON Pointer；不含原始输入或动态字典键。"
+        },
+        "option": {
+          "type": "string",
+          "description": "可定位时给出的已注册 CLI 选项。"
+        },
+        "reason": {
+          "enum": [
+            "required",
+            "invalid_type",
+            "invalid_choice",
+            "out_of_range",
+            "invalid_format",
+            "conditional_required",
+            "constraint",
+            "unexpected_property",
+            "unknown_option",
+            "unknown_command",
+            "excess_arguments",
+            "missing_value"
+          ],
+          "description": "字段违反的约束类型，原始值不回显。"
+        },
+        "expected": {
+          "$ref": "#/definitions/diagnosticExpected",
+          "description": "同版契约的静态预期。"
+        },
+        "relatedPaths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "description": "关联字段的 JSON Pointer。"
+          },
+          "description": "触发条件约束的关联字段。"
+        }
+      }
+    },
+    "diagnosticRecovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "automaticBusinessRetry"
+      ],
+      "properties": {
+        "action": {
+          "enum": [
+            "correct_input",
+            "complete_authentication",
+            "request_access_review",
+            "stop_and_inspect"
+          ],
+          "description": "依次表示修正本地输入、补认证、核对权限或停止核查；仅是说明，不执行操作或授予权限。"
+        },
+        "automaticBusinessRetry": {
+          "const": false,
+          "description": "不据此自动重放业务请求。"
+        }
+      }
+    },
+    "diagnosticExecution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestState",
+        "coverage",
+        "observedAttempts"
+      ],
+      "properties": {
+        "requestState": {
+          "enum": [
+            "not_sent",
+            "sent",
+            "unknown"
+          ],
+          "description": "整次调用尚未发送、已有发送记录或无法排除未知请求；不代表业务完成。"
+        },
+        "coverage": {
+          "enum": [
+            "complete",
+            "partial"
+          ],
+          "description": "请求观察覆盖全部已接入路径，或存在未观测路径；部分覆盖不能声明零请求。"
+        },
+        "observedAttempts": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "本地已进入发送边界的观测次数下界，不是服务端执行次数。"
+        }
+      }
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.customer.list/1.0.0"
+  },
+  "success": {
+    "description": "同店核验、搜索、所有客户字段及分页和预算均满足契约后，一次输出有限摘要，不返回部分成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏 JSON，退出码非零。不重试、重定向、切店、换身份或改用批查。",
+    "diagnosticsVersion": 2
+  },
+  "notes": [
+    "15 个筛选直接组合成同一次搜索。固定按创建时间降序；没有任意过滤 JSON、排序、来源渠道、phones 或 lookup。",
+    "数值范围支持 LOW..HIGH、LOW..、..HIGH 和相同双边裸值；时间必须含 ..。拒绝首尾或分隔符旁空白、负数、指数及多个分隔符。省略边界不补零或当前时间。",
+    "执行需要 userId、hq、shopId、orgType 四字段上下文。非总部目标必须匹配 shopId；总部也仅查本次同店核验目标，不遍历分店。at=all 和绑定成功不证明员工授权。",
+    "缺少上下文时只允许显式合法目标的本地 dry-run；无效或冲突上下文即使预览也拒绝。预览不读凭证，不触发认证。",
+    "最多一次店铺核验和一次搜索，每次超时 10 秒，累计响应上限 10MiB，最终 UTF-8 输出含换行上限 5MiB，超限失败不裁切。",
+    "本页不构成全店全集或强一致快照。继续读取使用明确页码和容量；未知总数、短页或空页不证明全部读取完成。",
+    "筛选事实不是摘要事实，不用输入补资产、金额、等级或卡状态；可用 yzOpenId 继续 customer.customer.get，其他命令契约不变。",
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。"
+  ]
+}