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

package/src/commands/native/valuecard/card/list/schema.json

@@ -0,0 +1,780 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "yzOpenId",
+      "statuses",
+      "pageNo",
+      "pageSize",
+      "include"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "yzOpenId": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f](?:[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f])?$",
+        "description": "去首尾空白的单个客户 yzOpenId，拒绝控制字符；不是手机号、员工 ID 或微信 openId。"
+      },
+      "statuses": {
+        "$ref": "#/definitions/statuses"
+      },
+      "pageNo": {
+        "$ref": "#/definitions/pageNo"
+      },
+      "pageSize": {
+        "$ref": "#/definitions/pageSize"
+      },
+      "include": {
+        "$ref": "#/definitions/selection"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "cards",
+          "pagination"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "cards": {
+            "type": "array",
+            "maxItems": 50,
+            "description": "本页客户持卡实例，保留原顺序与同模板的多张卡；不按卡种过滤，不汇总余额。",
+            "items": {
+              "type": "object",
+              "required": [
+                "cardNo",
+                "cardType",
+                "cardStatus",
+                "balance"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "cardNo": {
+                  "$ref": "#/definitions/text"
+                },
+                "cardType": {
+                  "enum": [
+                    "balance",
+                    "gift"
+                  ],
+                  "description": "balance 表示余额卡，gift 表示礼品卡。"
+                },
+                "cardStatus": {
+                  "$ref": "#/definitions/text",
+                  "description": "字符串状态：init 未激活；normal 正常可用；freeze 冻结；close 注销；receding 退卡中；receded 已退卡。未知非空状态原样保留，不据此判断某订单可支付。"
+                },
+                "bizCardStatus": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "minimum": -9007199254740991,
+                  "maximum": 9007199254740991,
+                  "description": "可选数字业务状态：1 购卡未激活；2 赠送；3 撤销；4 获赠；5 激活；6 已兑换未激活；7 批量制卡未兑换；8 失效。缺失省略，显式 null 保留，未来合法整数保留；不据此补造 cardStatus 或支付资格。"
+                },
+                "balance": {
+                  "type": "object",
+                  "required": [
+                    "totalBalance",
+                    "principalBalance",
+                    "bonusBalance"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "totalBalance": {
+                      "$ref": "#/definitions/money",
+                      "description": "总余额，元两位字符串，等于本金加赠送金。"
+                    },
+                    "principalBalance": {
+                      "$ref": "#/definitions/money",
+                      "description": "本金余额，元两位字符串。"
+                    },
+                    "bonusBalance": {
+                      "$ref": "#/definitions/money",
+                      "description": "赠送金余额，元两位字符串。"
+                    }
+                  }
+                },
+                "template": {
+                  "type": "object",
+                  "required": [
+                    "templateNo"
+                  ],
+                  "additionalProperties": false,
+                  "description": "仅选择 template 时出现且必需，不增加请求。",
+                  "properties": {
+                    "templateNo": {
+                      "$ref": "#/definitions/text"
+                    },
+                    "templateName": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "可选模板名，缺失省略，显式 null 或空串保留。"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "pagination": {
+            "type": "object",
+            "required": [
+              "pageNo",
+              "pageSize",
+              "hasMore",
+              "nextPageNo",
+              "windowLimitReached"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "pageNo": {
+                "$ref": "#/definitions/pageNo",
+                "description": "响应页码，必须等于请求页码。"
+              },
+              "pageSize": {
+                "$ref": "#/definitions/pageSize",
+                "description": "响应实际容量，不得超过请求容量。"
+              },
+              "total": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。"
+              },
+              "hasMore": {
+                "type": ["boolean", "null"],
+                "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。"
+              },
+              "nextPageNo": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "minimum": 1,
+                "maximum": 200,
+                "description": "已确认且未超过页码上限的下一页；无法确认或到达上限时为 null。"
+              },
+              "windowLimitReached": {
+                "type": "boolean",
+                "description": "仍有后续但已到本入口页码上限时为 true；不能宣称已取完或继续请求下一页。"
+              }
+            },
+            "description": "本次查询范围的分页信号；total 不保证跨页快照。"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "scope",
+      "prerequisites",
+      "requests",
+      "selection"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "$ref": "#/definitions/scope"
+      },
+      "selection": {
+        "$ref": "#/definitions/selection"
+      },
+      "prerequisites": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1,
+        "items": {
+          "type": "object",
+          "required": [
+            "method",
+            "path",
+            "body"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "const": "POST"
+            },
+            "path": {
+              "const": "youzan.shop.basic.get/3.0.0"
+            },
+            "body": {
+              "type": "object",
+              "additionalProperties": false
+            }
+          }
+        }
+      },
+      "requests": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1,
+        "items": {
+          "type": "object",
+          "required": [
+            "method",
+            "path",
+            "body"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "const": "POST"
+            },
+            "path": {
+              "const": "youzan.cardvoucher.valuecard.info.bypub.search/3.0.2"
+            },
+            "body": {
+              "type": "object",
+              "required": [
+                "yz_open_id",
+                "card_status_list",
+                "page",
+                "page_size"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "yz_open_id": {
+                  "const": "<redacted>"
+                },
+                "card_status_list": {
+                  "$ref": "#/definitions/statuses"
+                },
+                "page": {
+                  "$ref": "#/definitions/pageNo"
+                },
+                "page_size": {
+                  "$ref": "#/definitions/pageSize"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+            "type": "string",
+            "enum": [
+              "validation",
+              "configuration",
+              "parameter",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "not_found"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "valuecard.card.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",
+            "minLength": 1
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "$ref": "#/definitions/code"
+          },
+          "gatewayCode": {
+            "$ref": "#/definitions/code"
+          },
+          "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": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/shopId"
+        }
+      }
+    },
+    "statuses": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 6,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "normal",
+          "init",
+          "freeze",
+          "close",
+          "receding",
+          "receded"
+        ]
+      },
+      "description": "默认 normal；状态 CSV 规范化后的集合，禁止空项、未知值和重复。normal 正常状态；init 未激活；freeze 冻结状态；close 注销；receding 退卡中；receded 已退卡。本筛选不支持 cmpfrz。"
+    },
+    "selection": {
+      "type": "array",
+      "maxItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "const": "template"
+      }
+    },
+    "pageNo": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 200
+    },
+    "pageSize": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50
+    },
+    "text": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "money": {
+      "type": "string",
+      "pattern": "^-?(?:0|[1-9][0-9]*)\\.[0-9]{2}$",
+      "description": "默认人民币（CNY），单位元、固定两位小数的十进制金额文本，不补零、不舍入、不换汇。"
+    },
+    "code": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "string",
+          "pattern": "^-?[0-9]{1,12}$"
+        }
+      ]
+    },
+    "trace": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+    },
+    "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.cardvoucher.valuecard.info.bypub.search/3.0.2"
+  },
+  "notes": [
+    "固定一个客户、一个状态集合和一页，默认状态 normal；--status 接收 CSV，规范化为 statuses，禁止空项、重复、all 或 cmpfrz。",
+    "默认第 1 页、每页 20 条，最多 50 条，容量以本次返回为准；hasMore 按总数判断，不因空页、短页或第 200 页上限改写。第 200 页仍有更多时不得访问第 201 页，不宣称完整历史。",
+    "逐张保留余额卡和礼品卡、状态与余额，同模板多张卡仍分开；不本地过滤卡种或状态后沿用总数，不汇总客户资产或推算支付资格。",
+    "金额为元两位字符串，总额必须等于本金加赠送金；--include template 仅本地追加模板关联，不增加请求，未选择时忽略模板字段。",
+    "支持微商城单店、零售单店、连锁 D 总部及连锁 L 总部高级版，不承诺分店或合伙人直接调用。",
+    "不返回手机号、持有人、创建时间或有效期；无卡不等于客户不存在，机构角色未明确的行内店铺 ID 不输出或当作总部。",
+    "预览遮盖客户 ID，不读凭证、不联网；最多一次同凭证店铺核验和一次持卡分页查询，不自动重试、翻页、逐卡补查或换店。真实调用需有效上下文及同店凭证，at 不证明员工或跨机构权限。",
+    "本命令已定义金额的币种默认人民币（CNY）；字段、结果或明确父对象上下文声明其他币种时按该声明处理，不执行换汇。",
+    "total 是接口报告的本次筛选总数；继续读取 nextPageNo，windowLimitReached=true 时停止该入口，不把当前页当成全量。"
+  ],
+  "success": {
+    "description": "同凭证店铺与目标一致，当前页卡号唯一、状态属于请求集合、各卡余额及所选模板关联有效，分页一致后整体输出。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为单条脱敏错误 JSON，退出非零；不自动重试、换身份或切店。",
+    "diagnosticsVersion": 2
+  }
+}