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

package/src/commands/native/points/account/get/command.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+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 command = 'points.account.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('查询一个已知客户的当前积分，不查询流水、规则或客户档案')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId；不是手机号、微信 openId 或员工 ID')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId，非总部不可跨店')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览积分请求与店铺核验请求，不读凭证、不联网')
+    .addHelpText('after', `
+输出仅 data.account.points，保留 0 和负安全整数；缺值不能补成 0。
+固定账号类型 5；最多一次店铺核验与一次账户查询，不重试、不换身份或店铺。
+不查询账户版本，保留服务端扩展点默认行为，不承诺冻结、过期或累计积分。
+支持主、辅 API 已证明范围的交集：微商城/零售单店、连锁 D 总部、连锁 L 总部及 L 总部高级版；不扩展到连锁网店/分店。
+真实执行需有效四字段上下文及同店授权凭证；店铺核验不证明员工 OAuth 或连锁账本独立性。
+契约：zan-saas schema points.account.get --format json
+示例：zan-saas points account get --yz-open-id customer-1 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try {
+        input = { ...scope, yzOpenId: options.yzOpenId.trim() };
+        validateCommandValue(schema, 'input', input);
+      } catch { throw reject('parameter', 'input', scope); }
+      const preview = {
+        method: 'POST', path: schema.api.path,
+        body: { user: { account_type: 5, account_id: input.yzOpenId } },
+        scope, prerequisites: [{ method: 'POST', path: bindingPath, body: {} }]
+      };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const { data, facts } = await read(preview.path, preview.body, 'account');
+        if (!object(data) || !Number.isSafeInteger(data.point)) {
+          throw reject('protocol', 'account-model', scope, 'sent', facts);
+        }
+        output = { data: { account: { points: data.point } } };
+        validateCommandValue(schema, 'output', output);
+      }
+      console.log(JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/points/account/get/schema.json

@@ -0,0 +1,303 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "yzOpenId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "yzOpenId": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^\\S(?:[\\s\\S]*\\S)?$",
+        "description": "去除首尾空白后的单个客户 yzOpenId，不是手机号、微信 openId 或员工 ID。"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "account"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "account": {
+            "type": "object",
+            "required": [
+              "points"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "points": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "客户当前积分，单位积分；保留 0 和负安全整数，不表示冻结、过期或累计积分。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body",
+      "scope",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.crm.customer.points.get/1.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "user"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "user": {
+            "type": "object",
+            "required": [
+              "account_type",
+              "account_id"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "account_type": {
+                "const": 5
+              },
+              "account_id": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^\\S(?:[\\s\\S]*\\S)?$"
+              }
+            }
+          }
+        }
+      },
+      "scope": {
+        "type": "object",
+        "required": [
+          "kdtId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": {
+            "$ref": "#/definitions/shopId"
+          }
+        }
+      },
+      "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
+            }
+          }
+        }
+      }
+    }
+  },
+  "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"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string",
+            "enum": [
+              "validation",
+              "configuration",
+              "parameter",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "enum": [
+              "validation",
+              "context",
+              "scope",
+              "input",
+              "configuration",
+              "shop-binding",
+              "account",
+              "account-model",
+              "transport",
+              "http",
+              "response"
+            ]
+          },
+          "command": {
+            "const": "points.account.get"
+          },
+          "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": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?\\d{1,12}$"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?\\d{1,12}$"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          },
+          "request_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "显式 --kdt-id 优先，否则取本次有效上下文 shopId。默认值是动态来源，不是授权证明；实际执行必须与同次凭证回读的店铺一致。"
+    }
+  },
+  "modules": {
+    "account": {
+      "base": true,
+      "upstreamPath": "data.point",
+      "required": true,
+      "description": "仅投影客户当前积分 points，缺失或错型失败；未选择的扩展字段忽略。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.crm.customer.points.get/1.0.0"
+  },
+  "success": {
+    "description": "店铺核验通过且当前积分明确为安全整数后输出 data.account.points。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "只返回 data.account.points，单位积分，保留 0 和负安全整数；不表示冻结、过期或累计积分。",
+    "缺失、null、字符串、小数或不安全整数失败，不补 0，也不解释为客户不存在。",
+    "最多一次店铺核验和一次积分读取；核验失败不继续查询，不读取客户档案、流水或规则。",
+    "支持微商城和零售单店、连锁 D 总部、L 总部及 L 总部高级版，不承诺连锁网店或分店。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/points/commands.index.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 3,
+  "domain": "points",
+  "businessCommands": [
+    {
+      "path": "points.account.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "points/account/get/command.js",
+      "fingerprint": "08172715d6faca6425edceca180b47e3259f321ac96f3bba04b59cd186f82865"
+    },
+    {
+      "path": "points.log.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "points/log/list/command.js",
+      "fingerprint": "c93bc006243ed608efa288b9fe14e9503b1fe072bab969796c7045cde671aff4"
+    },
+    {
+      "path": "points.rule.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "points/rule/list/command.js",
+      "fingerprint": "d6a0a0fa10e2417aefa31a4110e866ffb9f106f1c8e3a3591a160cd9c3bc1cb1"
+    }
+  ]
+}

package/src/commands/native/points/domain.json

@@ -0,0 +1,3 @@
+{
+  "description": "积分：客户积分、积分流水与规则"
+}

package/src/commands/native/points/log/list/command.js

@@ -0,0 +1,141 @@
+'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 { inputIssue, 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 { parseDateTime, formatDateTime, apiDateTime } = require('../../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../../execution/range');
+const schema = require('./schema.json');
+
+const command = 'points.log.list';
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const SHANGHAI_OFFSET = 8 * 3600 * 1000;
+const types = { all: 0, income: 1, expense: 2, frozen: 3 };
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function earliestBegin(now) {
+  const local = new Date(now + SHANGHAI_OFFSET);
+  const year = local.getUTCFullYear() - 1;
+  const month = local.getUTCMonth();
+  const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+  return Date.UTC(year, month, Math.min(local.getUTCDate(), lastDay),
+    local.getUTCHours(), local.getUTCMinutes(), local.getUTCSeconds(), local.getUTCMilliseconds()) - SHANGHAI_OFFSET;
+}
+
+function buildInput(options, scope, now) {
+  let createdAt;
+  try { createdAt = parseDateTimeRange(options.createdAt,
+    { precision: 'seconds', requireBoth: true, strictOrder: true }); }
+  catch { throw inputIssue('/createdAt', 'invalid_format', { format: '北京时间 YYYY-MM-DD HH:mm:ss..YYYY-MM-DD HH:mm:ss，必须两端且开始早于结束；不接受非零毫秒' }); }
+  const begin = parseDateTime(createdAt.start);
+  const end = parseDateTime(createdAt.end);
+  const input = { ...scope, yzOpenId: options.yzOpenId.trim(),
+    createdAt,
+    type: options.type, pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo'), pageSize: parseIntegerOption(options.pageSize, schema, '/pageSize') };
+  if (end > now || end - begin >= 31 * 86400000 ||
+      begin < earliestBegin(now)) throw inputIssue('/createdAt', 'constraint', { format: '结束不晚于当前时刻；跨度须小于31天；开始不早于当前北京时间日历减12个月' });
+  validateCommandValue(schema, 'input', input);
+  return input;
+}
+
+function project(data, input, scope, facts) {
+  const invalid = () => reject('protocol', 'logs-model', scope, 'sent', facts);
+  const paginator = data?.paginator;
+  if (!object(data) || !Array.isArray(data.items) || data.items.length > input.pageSize ||
+      !object(paginator) || paginator.page !== input.pageNo || paginator.page_size !== input.pageSize) throw invalid();
+  const reportedTotal = readTotal(paginator, 'total_count', invalid);
+  const total = reportedTotal === null ? null : BigInt(reportedTotal);
+  const offset = BigInt(input.pageNo - 1) * BigInt(input.pageSize);
+  if (total !== null && (data.items.length ? offset + BigInt(data.items.length) > total : offset < total)) throw invalid();
+  const logs = data.items.map(item => {
+    if (!object(item)) throw invalid();
+    const log = {};
+    for (const [source, target, required] of [
+      ['amount', 'amount', true], ['current', 'current', true], ['created_at', 'createdAt', true],
+      ['expired_at', 'expiredAt', false], ['description', 'description', false], ['biz_value', 'bizValue', false]
+    ]) {
+      if (!Object.hasOwn(item, source)) {
+        if (required) throw invalid();
+        continue;
+      }
+      const value = item[source];
+      if (['description', 'biz_value'].includes(source) ? typeof value !== 'string' : !Number.isSafeInteger(value)) {
+        throw invalid();
+      }
+      try {
+        log[target] = ['created_at', 'expired_at'].includes(source) ? formatDateTime(value * 1000) : value;
+      } catch { throw invalid(); }
+    }
+    return log;
+  });
+  const output = { data: { logs, pagination: { pageNo: input.pageNo, pageSize: input.pageSize,
+    ...(reportedTotal === null ? {} : { total: reportedTotal }),
+    hasMore: total === null ? null : BigInt(input.pageNo) * BigInt(input.pageSize) < total } } };
+  try { validateCommandValue(schema, 'output', output); } catch { throw invalid(); }
+  if (Buffer.byteLength(JSON.stringify(output), 'utf8') > MAX_OUTPUT_BYTES) {
+    throw reject('budget_exceeded', 'output-budget', scope, 'sent', facts);
+  }
+  return output;
+}
+
+function createCommand({ context, now = () => Date.now() } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('分页查询一个已知客户在指定北京时间窗口内的积分流水（微商城单店）')
+    .allowExcessArguments(false)
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId，不是手机号或微信 openId')
+    .option('--kdt-id <id>', '目标店铺正安全整数；默认 context.shopId，非总部不可跨店')
+    .requiredOption('--created-at <range>', '必填：流水创建时间 START..END，必须两端，北京时间，秒精度；开始 < 结束 <= 当前时刻')
+    .addOption(new Option('--type <type>', '积分变动类型').choices(Object.keys(types)).default('all'))
+    .option('--page-no <n>', '页码，1..2147483647', '1')
+    .option('--page-size <n>', '每页条数，1..50，默认20', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览请求及店铺核验，不读凭证、不联网')
+    .addHelpText('after', `
+窗口严格小于31天，开始不得早于当前 Asia/Shanghai 日历时间减12个月（月底截断）。
+所有时间固定为北京时间（Asia/Shanghai），输入 YYYY-MM-DD HH:mm:ss，可追加1至3位毫秒。
+输出 createdAt/expiredAt 固定为 YYYY-MM-DD HH:mm:ss.SSS，不重复附带时区后缀。
+区间必须包含 ..，必须两端，省略边界不补值，不承诺端点包含性。
+API仅接受秒精度字符串：非零毫秒在请求前拒绝，全零毫秒可无损规范化，预览展示实际请求。
+返回 data.logs 与四字段 pagination；amount 保留正负号和0，current 是变更后的积分而非当前余额。
+单页最多50条，紧凑 JSON 输出预算5MiB；pretty使用同一预算，超额整体失败，不截断。
+最多一次同凭证店铺核验和一次日志请求，不重试、不自动翻页、不切换身份或API。
+hasMore=true 时保持客户、窗口、type和pageSize，将pageNo加1；达到页码上限必须停止。
+分页不保证快照，短页不代表结束；不排序去重、不生成流水ID、不计算余额。
+首期仅微商城单店，不提供全店、其他产品、事件筛选、全量导出或资产写入。
+at: all 只是组织位置声明，不扩展产品或跨店权限；真实执行需有效上下文与同店凭证。
+失败 stdout 为空，stderr 为安全错误JSON；停止并核对原客户、窗口和授权。
+契约：zan-saas schema points.log.list --format json
+示例：zan-saas points log list --yz-open-id customer-1 --kdt-id 63077 --created-at "2026-11-01 10:30:00..2026-11-01 11:30:00" --dry-run
+`)
+    .action(async options => {
+      const startedAt = now();
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try { input = buildInput(options, scope, startedAt); }
+      catch (error) { error.inputScope = scope; throw error; }
+      const preview = { method: 'POST', path: schema.api.path,
+        body: { user: { account_type: 5, account_id: input.yzOpenId }, page: input.pageNo,
+          page_size: input.pageSize, begin_time: apiDateTime(input.createdAt.start), end_time: apiDateTime(input.createdAt.end),
+          type: types[input.type] }, scope,
+        prerequisites: [{ method: 'POST', path: bindingPath, body: {} }] };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const { data, facts } = await read(preview.path, preview.body, 'logs');
+        output = project(data, input, scope, facts);
+      }
+      console.log(JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };