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

package/src/commands/native/benefit/card-definition/get/schema.json

@@ -0,0 +1,545 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "cardAlias",
+      "include"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/positiveInteger"
+      },
+      "cardAlias": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f](?:[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f])?$",
+        "description": "完整定义 alias，去首尾空白，拒绝控制字符；不是卡号或商品 ID。"
+      },
+      "include": {
+        "$ref": "#/definitions/include"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "card"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "card": {
+            "$ref": "#/definitions/card"
+          },
+          "rights": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/right"
+            },
+            "description": "仅 include rights 时出现；请求后数组必需，真实空数组允许。"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "scope",
+      "prerequisites",
+      "requests",
+      "selection"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "$ref": "#/definitions/scope"
+      },
+      "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.scrm.card.get/4.0.0"
+            },
+            "body": {
+              "type": "object",
+              "required": [
+                "params"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "params": {
+                  "type": "object",
+                  "required": [
+                    "card_alias"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "card_alias": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "description": "对象 {card_alias:cardAlias}，不把 params 再序列化为字符串；2026-10-30 用户确认替代初版 curl 字符串编码。"
+                }
+              }
+            }
+          }
+        }
+      },
+      "selection": {
+        "type": "object",
+        "required": [
+          "include"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "include": {
+            "$ref": "#/definitions/include"
+          }
+        }
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "required": [
+      "success",
+      "code",
+      "message",
+      "details"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "success": {
+        "const": false
+      },
+      "code": {
+        "const": -10001
+      },
+      "message": {
+        "type": "string"
+      },
+      "details": {
+        "type": "object",
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "enum": [
+              "parameter",
+              "validation",
+              "configuration",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "not_found"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "benefit.card-definition.get"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/positiveInteger"
+              }
+            }
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string"
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "businessCode": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string"
+          },
+          "request_id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "integer": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "positiveInteger": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "nonnegativeInteger": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "include": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "rights"
+        ]
+      }
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/positiveInteger"
+        }
+      }
+    },
+    "card": {
+      "type": "object",
+      "required": [
+        "cardAlias",
+        "name",
+        "cardType",
+        "status",
+        "activateMode",
+        "termType"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "cardAlias": {
+          "type": "string",
+          "minLength": 1,
+          "description": "权益卡定义别名，须精确等于请求 alias。"
+        },
+        "name": {
+          "type": "string",
+          "description": "权益卡名称，允许已取得的空文本。"
+        },
+        "cardType": {
+          "$ref": "#/definitions/integer",
+          "description": "卡类型：1 无门槛、2 规则、3 付费；未知整数保留，不与列表 grantType 混用。"
+        },
+        "status": {
+          "$ref": "#/definitions/integer",
+          "description": "定义状态：1 可用、2 禁用、3 删除；未知整数保留，不推导领取资格。"
+        },
+        "activateMode": {
+          "$ref": "#/definitions/integer",
+          "description": "激活方式：0 无需激活、1 手机、2 手机及资料；未知整数保留。"
+        },
+        "termType": {
+          "$ref": "#/definitions/integer",
+          "description": "有效期类型：1 永久、2 固定时间、3 领取后天数；未知整数保留。"
+        },
+        "termDays": {
+          "$ref": "#/definitions/nonnegativeInteger",
+          "description": "领取后有效天数，单位天；不计算客户实际有效期。"
+        },
+        "termStartTime": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "beijing-date-time-ms"
+            },
+            {
+              "const": ""
+            }
+          ],
+          "$comment": "upstream-time:text:empty",
+          "description": "固定有效期起点；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+        },
+        "termEndTime": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "beijing-date-time-ms"
+            },
+            {
+              "const": ""
+            },
+            {
+              "const": "永久有效"
+            }
+          ],
+          "$comment": "upstream-time:text:empty:permanent",
+          "description": "固定有效期终点；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['', '永久有效']。"
+        },
+        "termToCardAlias": {
+          "type": "string",
+          "description": "关联权益卡定义别名，允许空串，不递归查询。"
+        },
+        "description": {
+          "type": "string",
+          "description": "权益卡使用须知。"
+        },
+        "cardUrl": {
+          "type": "string",
+          "description": "权益卡链接，仅返回，不访问。"
+        }
+      }
+    },
+    "right": {
+      "type": "object",
+      "required": [
+        "type",
+        "name",
+        "isAvailable"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/integer",
+          "description": "1 包邮、2 折扣、3 优惠券、4 积分、7 积分倍率、10 赠品、12 好友体验卡；未知整数保留。"
+        },
+        "name": {
+          "type": "string"
+        },
+        "isAvailable": {
+          "type": "boolean",
+          "description": "is_available 配置标记，不表示客户已获得或可使用。"
+        },
+        "discount": {
+          "$ref": "#/definitions/integer",
+          "description": "原编码；1 表示 0.01 折，不转百分比。"
+        },
+        "rate": {
+          "$ref": "#/definitions/integer",
+          "description": "原倍率编码；15 表示 1.5 倍，不转换。"
+        },
+        "points": {
+          "$ref": "#/definitions/nonnegativeInteger"
+        },
+        "coupon": {
+          "type": "array",
+          "maxItems": 30,
+          "items": {
+            "$ref": "#/definitions/coupon"
+          }
+        },
+        "presents": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/present"
+          }
+        },
+        "salesman": {
+          "$ref": "#/definitions/salesman"
+        },
+        "custom": {
+          "$ref": "#/definitions/custom"
+        },
+        "experienceCard": {
+          "$ref": "#/definitions/experienceCard"
+        }
+      }
+    },
+    "coupon": {
+      "type": "object",
+      "required": [
+        "couponId",
+        "number"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "couponId": {
+          "$ref": "#/definitions/positiveInteger"
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "present": {
+      "type": "object",
+      "required": [
+        "presentId",
+        "number"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "presentId": {
+          "$ref": "#/definitions/positiveInteger"
+        },
+        "number": {
+          "$ref": "#/definitions/nonnegativeInteger"
+        }
+      }
+    },
+    "salesman": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "cpsRate": {
+          "$ref": "#/definitions/integer",
+          "description": "cps_rate 原百分比编码，2 表示 2%。"
+        }
+      }
+    },
+    "custom": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "仅返回，不抓取。"
+        }
+      }
+    },
+    "experienceCard": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sharedRewardGiftId": {
+          "$ref": "#/definitions/positiveInteger"
+        },
+        "experienceDays": {
+          "$ref": "#/definitions/nonnegativeInteger"
+        },
+        "stockNum": {
+          "$ref": "#/definitions/nonnegativeInteger"
+        },
+        "rewardPoints": {
+          "$ref": "#/definitions/nonnegativeInteger"
+        }
+      }
+    }
+  },
+  "modules": {
+    "card": {
+      "base": true,
+      "upstreamPath": "data",
+      "required": true,
+      "description": "固定基础定义视图，alias 精确匹配，六个核心字段必需。"
+    },
+    "rights": {
+      "base": false,
+      "upstreamPath": "data.rights",
+      "required": true,
+      "description": "按 include 追加递归配置数组；缺失/null/错型失败，不强求未取得的可选 payload。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.card.get/4.0.0"
+  },
+  "success": {
+    "description": "cardAlias 精确匹配，基础 card 及所请求 rights 满足模型后整体成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。 明确业务拒绝 141502105 为 not_found；错 alias 或矛盾成功结果为 protocol。"
+  },
+  "notes": [
+    "查询已知 alias 的权益卡定义，不是客户持卡实例；不推导客户持卡状态、领取资格或列表字段。",
+    "默认返回 card，--include rights 追加权益配置；已选模块缺失或错型整体失败，可选字段缺失保持省略。",
+    "支持微商城单店、零售单店、连锁 D 总部、网店及合伙人；不承诺教育多校区总部。",
+    "不返回付费金额、完整发卡规则、适用店铺或联系人；未知类型整数保留，不据此推断状态。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/benefit/card-definition/list/command.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { parseIntegerOption } = require('../../../../../execution/error-details');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+const { object } = require('../../../../../execution/query-api');
+const schema = require('./schema.json');
+const { normalizeTimes } = require('../../../../../execution/datetime');
+
+const command = 'benefit.card-definition.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function project(data, pageNo) {
+  if (!object(data) || !Array.isArray(data.items) ||
+      !Number.isSafeInteger(data.page) || !Number.isSafeInteger(data.page_size) ||
+      data.items.some(card => !object(card))) {
+    throw new Error('Invalid card list');
+  }
+  const total = readTotal(data, 'total');
+  const output = { data: {
+    cards: data.items.map(card => ({
+      cardAlias: card.card_alias,
+      cardId: card.card_id,
+      name: card.name,
+      isAvailable: card.is_available,
+      grantType: card.grant_type,
+      ...(Object.hasOwn(card, 'card_url') ? { cardUrl: card.card_url } : {}),
+      ...(Object.hasOwn(card, 'create_time') ? { createdAt: card.create_time } : {})
+    })),
+    pagination: { pageNo: data.page, pageSize: data.page_size, returned: data.items.length,
+      ...(total === null ? {} : { total }), hasMore: null, nextPageNo: null, windowLimitReached: false }
+  } };
+  output.data.cards = normalizeTimes(output.data.cards,
+    schema.output.properties.data.properties.cards, schema.definitions);
+  validateCommandValue(schema, 'output', output);
+  const { cards } = output.data;
+  const end = data.page * data.page_size;
+  if (data.page !== pageNo || !Number.isSafeInteger(end) ||
+      cards.length > data.page_size || (total === 0 && cards.length !== 0) ||
+      new Set(cards.map(card => card.cardAlias)).size !== cards.length) {
+    throw new Error('Invalid card pagination or aliases');
+  }
+  const hasMore = total === null ? null : end < total;
+  Object.assign(output.data.pagination, { hasMore,
+    nextPageNo: hasMore === true && pageNo < 100 ? pageNo + 1 : null, windowLimitReached: hasMore !== false && pageNo === 100 });
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('分页查询店铺配置的权益卡定义列表')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .option('--page-no <n>', '页码，十进制整数 1..100；仅查询指定单页', '1')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验和单页查询，不读凭证、不联网')
+    .addHelpText('after', `
+total 只描述本次筛选的接口总数，不保证跨页快照；按 nextPageNo 继续并保留店铺、筛选和容量。
+nextPageNo=null 不能单独解释为结束；windowLimitReached=true 表示达到页码上限，仍有后续。
+时间点统一输出北京时间 YYYY-MM-DD HH:mm:ss.SSS，字段声明的业务哨兵保留。
+输出 data.cards 和 data.pagination（含 total、nextPageNo、windowLimitReached），容量使用实际响应，不自动翻页或重试。
+仅查询商家卡定义，不表示客户持卡、发卡资格或详情权益；不按名称、类型或状态过滤。
+hasMore 表示是否还有下一页；空页或短页不表示耗尽，不承诺跨页快照。
+服务端最多允许 100 页；第 100 页仍有 hasMore=true 时不能继续遍历，不请求第 101 页。
+不提供 --name、--page-size 或 scan；最多一次店铺核验与一次业务请求。
+真实执行需有效四字段上下文和同店授权凭证；店铺核验不证明员工 OAuth。
+支持微商城单店、零售单店、有赞连锁 D 总部/网店/合伙人，不承诺教育多校区总部。
+契约：zan-saas schema benefit.card-definition.list
+示例：zan-saas benefit card-definition list --page-no 1
+示例：zan-saas benefit card-definition list --kdt-id 63077 --page-no 2 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try {
+        input = { ...scope, pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo') };
+        validateCommandValue(schema, 'input', input);
+      } catch (error) { error.inputScope = scope; throw error; }
+      const preview = {
+        scope,
+        prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [{ method: 'POST', path: schema.api.path, body: { page: input.pageNo } }]
+      };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const { data, facts } = await read(schema.api.path, preview.requests[0].body, 'card-list');
+        try { output = project(data, input.pageNo); }
+        catch { throw reject('protocol', 'card-list-model', scope, 'sent', facts); }
+      }
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };