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

package/src/commands/native/benefit/card-grant/list/schema.json

@@ -0,0 +1,758 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "pageNo",
+      "pageSize"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "pageNo": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 2147483647,
+        "description": "本次请求的页码，从 1 开始；按单页读取，不自动获取后续页。"
+      },
+      "pageSize": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 50,
+        "description": "本次单页最多返回的发放记录条数，不表示历史记录总数。"
+      },
+      "yzOpenId": {
+        "$ref": "#/definitions/identifier",
+        "description": "可选客户的有赞稳定标识，用于限定该客户的发放记录；省略表示本店记录，显式空值拒绝。"
+      }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "cardGrants",
+          "pagination"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "cardGrants": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/cardGrant"
+            },
+            "description": "本页权益卡发放记录，逐条保留来源、顺序和重复，不按客户或卡号合并。"
+          },
+          "pagination": {
+            "$ref": "#/definitions/pagination"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "scope",
+      "requests"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "type": "object",
+        "required": [
+          "kdtId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": {
+            "$ref": "#/definitions/shopId"
+          }
+        },
+        "description": "本次固定的查询店铺。"
+      },
+      "requests": {
+        "type": "array",
+        "minItems": 2,
+        "maxItems": 2,
+        "additionalItems": false,
+        "description": "先核验同店凭证，再读取一页发放记录；预览不执行请求。",
+        "items": [
+          {
+            "type": "object",
+            "required": [
+              "stage",
+              "method",
+              "path",
+              "body"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "stage": {
+                "const": "shop-binding",
+                "description": "本次计划中的店铺核验或发放记录读取阶段。"
+              },
+              "method": {
+                "const": "POST",
+                "description": "该阶段的 HTTP 请求方法。"
+              },
+              "path": {
+                "const": "youzan.shop.basic.get/3.0.0",
+                "description": "该阶段实际调用的接口路径。"
+              },
+              "body": {
+                "type": "object",
+                "required": [],
+                "additionalProperties": false,
+                "properties": {}
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "stage",
+              "method",
+              "path",
+              "body"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "stage": {
+                "const": "card-grant-list",
+                "description": "本次计划中的店铺核验或发放记录读取阶段。"
+              },
+              "method": {
+                "const": "POST",
+                "description": "该阶段的 HTTP 请求方法。"
+              },
+              "path": {
+                "const": "youzan.scrm.card.search.grantlog/1.0.0",
+                "description": "该阶段实际调用的接口路径。"
+              },
+              "body": {
+                "type": "object",
+                "required": [
+                  "params"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "params": {
+                    "type": "object",
+                    "required": [
+                      "page",
+                      "page_size"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "page": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "page_size": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 50
+                      },
+                      "user": {
+                        "type": "object",
+                        "required": [
+                          "account_type",
+                          "account_id"
+                        ],
+                        "additionalProperties": false,
+                        "properties": {
+                          "account_type": {
+                            "const": 5
+                          },
+                          "account_id": {
+                            "const": "***"
+                          }
+                        }
+                      }
+                    },
+                    "description": "分页与可选客户条件，预览中的客户标识固定显示为 ***。"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "required": [
+      "success",
+      "code",
+      "message",
+      "details"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "success": {
+        "const": false
+      },
+      "code": {
+        "const": -10001
+      },
+      "message": {
+        "type": "string",
+        "minLength": 1
+      },
+      "details": {
+        "type": "object",
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep",
+          "errorVersion",
+          "recovery",
+          "execution"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "enum": [
+              "parameter",
+              "validation",
+              "configuration",
+              "authentication",
+              "permission",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "limit"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "input",
+              "validation",
+              "context",
+              "scope",
+              "configuration",
+              "shop-binding",
+              "card-grant-list",
+              "card-grant-list-model",
+              "transport",
+              "http",
+              "response"
+            ]
+          },
+          "command": {
+            "const": "benefit.card-grant.list"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/shopId"
+              }
+            }
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string"
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "businessCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "gatewayCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "trace_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,128}$"
+          },
+          "request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,128}$"
+          },
+          "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": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "查询店铺的正安全整数标识，必须与当前查询所用凭证绑定；不是记录中的领卡来源店铺。"
+    },
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S",
+      "description": "对应业务对象的稳定非空文本标识，保留完整字符和前导零。"
+    },
+    "diagnosticCode": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "string",
+          "pattern": "^-?\\d{1,12}$"
+        }
+      ]
+    },
+    "cardGrant": {
+      "type": "object",
+      "required": [
+        "yzOpenId",
+        "cardAlias",
+        "cardNo",
+        "originKdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "yzOpenId": {
+          "$ref": "#/definitions/identifier",
+          "description": "本次发放记录关联的客户有赞标识；不能替代员工标识。"
+        },
+        "cardAlias": {
+          "$ref": "#/definitions/identifier",
+          "description": "本次记录关联的权益卡定义别名，不是客户持卡卡号。"
+        },
+        "cardNo": {
+          "$ref": "#/definitions/identifier",
+          "description": "本次记录关联的完整权益卡号，按文本保留，不推断当前可用状态。"
+        },
+        "originKdtId": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "领卡来源门店标识，允许不同于查询店铺；不据此切换查询范围。"
+        },
+        "grantId": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "源已返回的客户卡日志记录标识，不据此提供独立详情、去重或重放操作。"
+        },
+        "cardName": {
+          "type": "string",
+          "description": "记录携带的权益卡模板名称，空串保留，不保证是定义当前名称。"
+        },
+        "bizType": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "领取来源业务类型：1 用户无限制主动领取；2 管理员直接发放；3 系统发放；4 规则卡升级；5 付费购买；61 三方开放平台操作；71 储值发卡；81 客户导入；91 参数二维码发卡；100 销售员升级同步发卡；101 销售员购买付费卡重新定级；110 通过领卡链接领卡；111 通过扫码领卡；112 领取体验卡；113 体验卡转正式卡；114 积分兑换付费卡。未知合法整数保留，不推断其业务含义。"
+        }
+      },
+      "description": "一次发放或领取的历史记录；不证明客户当前持卡、卡有效或权益已使用。可选字段缺失或 null 时省略。"
+    },
+    "pagination": {
+      "type": "object",
+      "required": [
+        "pageNo",
+        "pageSize",
+        "returned",
+        "hasMore",
+        "nextPageNo",
+        "windowLimitReached"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "pageNo": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "本次结果对应的页码。"
+        },
+        "pageSize": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "本次生效的每页容量，由请求指定。"
+        },
+        "returned": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "本次响应中 data.cardGrants 的数组长度，不是匹配总数、累计条数或嵌套记录数。"
+        },
+        "hasMore": {
+          "type": ["boolean", "null"],
+          "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。"
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。"
+        },
+        "nextPageNo": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1,
+          "maximum": 2147483647,
+          "description": "已确认且未超过页码上限的下一页；无法确认或到达上限时为 null。"
+        },
+        "windowLimitReached": {
+          "type": "boolean",
+          "description": "仍有后续但已到本入口页码上限时为 true；不能宣称已取完或继续请求下一页。"
+        }
+      },
+      "description": "本次查询范围的分页信号；total 不保证跨页快照。"
+    },
+    "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": "本地已进入发送边界的观测次数下界，不是服务端执行次数。"
+        }
+      }
+    }
+  },
+  "modules": {
+    "card-grants": {
+      "base": true,
+      "required": true,
+      "upstreamPath": "data",
+      "description": "单页发放记录及分页信息，区分客户、卡定义、卡实例和来源店铺。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.card.search.grantlog/1.0.0"
+  },
+  "success": {
+    "description": "凭证与查询店铺一致，分页及每条记录的核心关联有效；客户筛选存在时每条记录属于该客户。"
+  },
+  "errors": {
+    "description": "业务拒绝、缺少关联字段、分页矛盾、超出响应预算或读取失败均整体失败；stdout 为空，不输出部分记录或伪造空列表。",
+    "diagnosticsVersion": 2
+  },
+  "notes": [
+    "当前接口配置覆盖微商城单店、微商城连锁总部和网店、零售单店及零售连锁总部、总部高级版、网店、网店 Lite、合伙人；实际产品与员工授权仍由服务端校验。",
+    "省略客户条件查询本店记录；显式空客户标识失败，不自动扩大范围。每次只取一页，不补查客户、卡定义或当前持卡。",
+    "先核验同店凭证，再查询记录，最多两次请求。每次响应最多 8 MiB，超限整体失败，不截断或自动重试。",
+    "可选记录标识、卡名称和来源类型在源缺失或 null 时省略；不输出未选择的领取时间字段。",
+    "预览不读凭证或联网；真实读取需要有效上下文和同店授权。来源门店可以不同于查询店铺，不触发跨店读取。",
+    "total 是接口报告的本次筛选总数；继续读取 nextPageNo，windowLimitReached=true 时停止该入口，不把当前页当成全量。",
+    "总数为接口报告的匹配领取记录数，不保证实时快照；零值存在无法区分的回退语义时省略 total，hasMore 为 null。"
+  ]
+}