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

package/src/commands/native/member/growth/get/schema.json

@@ -0,0 +1,283 @@
+{
+  "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": "trim 后的客户 yzOpenId，不是手机号、微信 openId 或员工 ID。"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "growth_account"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "growth_account": {
+            "type": "object",
+            "required": [
+              "growth"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "growth": {
+                "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.growth.get/2.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "params"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "params": {
+            "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"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "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",
+              "not_found",
+              "target_mismatch",
+              "ambiguous"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "member.growth.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"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string"
+          },
+          "request_id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.crm.customer.growth.get/2.0.0"
+  },
+  "success": {
+    "description": "店铺核验通过且当前成长值满足模型后成功，不能用缺失结果代替零。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "查询一个已知客户的当前成长值，不查询客户档案、流水或规则；错误 141503101 不能解释为成长值 0。",
+    "--kdt-id 省略取有效上下文 shopId；缺少上下文时只有显式合法店铺的本地预览可运行。",
+    "缺必需内容、null 或错型整体失败，不补零；最多一次店铺核验和一次成长值读取。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/member/growth-log/list/command.js

@@ -0,0 +1,203 @@
+'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, constraints, modelAt } = require('../../../../../execution/error-details');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { parseDateTime, apiDateTime, normalizeTimes } = require('../../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../../execution/range');
+const { createBoundShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+const { object } = require('../../../../../execution/query-api');
+const schema = require('./schema.json');
+
+const command = 'member.growth-log.list';
+const MAX_PAGE_NO = 2147483647;
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const nextStep = '核对原店铺、客户标识、时间窗口和服务端授权；不自动重放、翻页、切换身份或店铺。';
+
+function reject(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, requestState, facts);
+  error.cliDetails.nextStep = nextStep;
+  return error;
+}
+
+function parseWindow(value, now) {
+  let range;
+  try {
+    range = parseDateTimeRange(value, { precision: 'seconds', requireBoth: true });
+  } catch {
+    throw inputIssue('/createdAt', 'invalid_format', { format: '北京时间 YYYY-MM-DD HH:mm:ss..YYYY-MM-DD HH:mm:ss，必须两端且开始不晚于结束；不接受非零毫秒' });
+  }
+  const start = parseDateTime(range.start);
+  const end = parseDateTime(range.end);
+  if (start < now - 360 * DAY_MS || end > now || end - start > 90 * DAY_MS) {
+    throw inputIssue('/createdAt', 'constraint', { format: '开始须在最近360天内，结束不晚于当前时刻，跨度不超过90天' });
+  }
+  return { start: range.start, end: range.end };
+}
+
+function body(input) {
+  return { params: JSON.stringify({
+    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)
+  }) };
+}
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = (category, path, reason = 'constraint', stage = 'logs-model') => {
+    const error = reject(category, stage, scope, 'sent', facts);
+    if (path) error.issues = [{ source: 'output', path, reason,
+      expected: constraints(modelAt(schema, 'output', path)) }];
+    return error;
+  };
+  try {
+    if (!object(data) || !Array.isArray(data.items)) throw invalid('protocol', '/data/logs', 'invalid_type');
+    if (data.items.length > input.pageSize) throw invalid('limit', '/data/logs', 'out_of_range');
+    const invalidPage = (field = '') => invalid('protocol', `/data/pagination${field}`, 'constraint', 'pagination');
+    if (!object(data.paginator)) throw invalidPage();
+    const paginator = data.paginator;
+    const total = readTotal(paginator, 'total_count', () => invalidPage('/total'));
+    if (!Number.isSafeInteger(paginator.page) || paginator.page !== input.pageNo) throw invalidPage('/pageNo');
+    if (!Number.isSafeInteger(paginator.page_size) || paginator.page_size !== input.pageSize) throw invalidPage('/pageSize');
+    if (total !== null && (total > MAX_PAGE_NO || data.items.length > total)) throw invalidPage('/total');
+    const logs = data.items.map((item, index) => {
+      const path = `/data/logs/${index}`;
+      if (!object(item)) throw invalid('protocol', path, 'invalid_type');
+      if (!Number.isSafeInteger(item.amount)) throw invalid('protocol', `${path}/amount`, 'invalid_type');
+      if (!Number.isSafeInteger(item.event_type)) throw invalid('protocol', `${path}/eventType`, 'invalid_type');
+      if (item.event_type < -2147483648 || item.event_type > 2147483647) {
+        throw invalid('protocol', `${path}/eventType`, 'out_of_range');
+      }
+      if (!Number.isSafeInteger(item.created_at)) throw invalid('protocol', `${path}/createdAt`, 'invalid_format');
+      let createdAt;
+      try {
+        createdAt = normalizeTimes(item.created_at, modelAt(schema, 'output', `${path}/createdAt`), schema.definitions);
+      } catch {
+        throw invalid('protocol', `${path}/createdAt`, 'invalid_format');
+      }
+      const log = { amount: item.amount, eventType: item.event_type, createdAt };
+      for (const [source, target] of [['description', 'description'], ['biz_value', 'bizValue']]) {
+        if (Object.hasOwn(item, source)) {
+          if (typeof item[source] !== 'string') throw invalid('protocol', `${path}/${target}`, 'invalid_type');
+          log[target] = item[source];
+        }
+      }
+      return log;
+    });
+    const raw = { data: { logs, pagination: {
+      pageNo: paginator.page,
+      pageSize: paginator.page_size,
+      ...(total === null ? {} : { total }),
+      hasMore: total === null ? null : BigInt(paginator.page) * BigInt(paginator.page_size) < BigInt(total)
+    } } };
+    validateCommandValue(schema, 'output', raw);
+    return raw;
+  } catch (error) {
+    if (error?.cliDetails) throw error;
+    const failed = invalid('protocol');
+    if (error.issues) failed.issues = error.issues;
+    if (error.issuesTruncated) failed.issuesTruncated = true;
+    throw failed;
+  }
+}
+
+function createCommand({ context, now = () => Date.now() } = {}) {
+  const leaf = new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('分页查询指定客户在时间窗口内的成长值变更记录')
+    .allowExcessArguments(false)
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId；不是手机号、员工 ID 或微信 openId')
+    .requiredOption('--created-at <range>', '必填：北京时间 YYYY-MM-DD HH:mm:ss[.SSS]..YYYY-MM-DD HH:mm:ss[.SSS]，非零毫秒拒绝')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId')
+    .option('--page-no <n>', '页码 1..2147483647；每次只读一页', '1')
+    .option('--page-size <n>', '每页容量 1..50；默认 10', '10')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览请求计划，不读取凭证、不联网')
+    .addHelpText('after', `
+输出固定为 data.logs 和 data.pagination，保留源顺序、重复、0 与有符号 amount。
+createdAt 将 Unix 秒转换为北京时间三位毫秒；不按数字位数猜测毫秒，不解释增减方向或等级变化。
+时间窗口必须显式提供两端，允许相等；起点不早于当前时刻前 360 天，跨度不超过 90 天，终点不晚于当前时刻。
+主请求固定使用 account_type=5，params 是 JSON 字符串；不提供事件筛选、排序、自动翻页、重试或补查。
+先用同一目标和凭证核验店铺，再读取一页成长流水；失败 stdout 为空，不返回部分结果。
+真实执行需要有效四字段上下文及同店授权；at: all 和店铺核验不证明员工 OAuth 权限。
+最多两次请求，每请求 10 秒；合计响应最多 10 MiB，输出含缩进及换行最多 5 MiB，超限整体失败。
+契约：zan-saas schema member.growth-log.list
+示例：zan-saas member growth-log list --yz-open-id customer-1 --created-at "2026-11-01 00:00:00..2026-11-05 23:59:59" --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      let scope;
+      try {
+        scope = resolveTargetShop(options, context, command);
+      } catch (error) {
+        if (error?.cliDetails?.stage === 'validation') error.cliDetails.stage = 'input';
+        if (error?.cliDetails?.stage === 'scope') error.cliDetails.stage = 'context';
+        throw error;
+      }
+      let input;
+      try {
+        if (/[\u0000-\u001f\u007f-\u009f]/u.test(options.yzOpenId) ||
+            !options.yzOpenId.trim()) throw inputIssue('/yzOpenId', 'invalid_format', constraints(modelAt(schema, 'input', '/yzOpenId')));
+        input = {
+          ...scope,
+          yzOpenId: options.yzOpenId.trim(),
+          pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo'),
+          pageSize: parseIntegerOption(options.pageSize, schema, '/pageSize'),
+          createdAt: parseWindow(options.createdAt, now())
+        };
+        validateCommandValue(schema, 'input', input);
+      } catch (error) {
+        error.inputScope = scope;
+        if (error.issues?.some(issue => issue.path === '/createdAt')) error.cliDetails = reject('validation', 'input', scope).cliDetails;
+        throw error;
+      }
+      const request = { method: schema.api.method, path: schema.api.path, body: body(input) };
+      const preview = {
+        scope: { kdtId: input.kdtId },
+        requests: [
+          { method: 'POST', path: bindingPath, body: {} },
+          request
+        ]
+      };
+      validateCommandValue(schema, 'preview', preview);
+      if (options.dryRun) {
+        process.stdout.write(`${JSON.stringify(preview, null, options.format === 'pretty' ? 2 : 0)}\n`);
+        return;
+      }
+      let responseBytes = 0;
+      const { read } = await createBoundShopQuery({ kdtId: input.kdtId }, command, 'shop-binding', {
+        onResponse: response => { responseBytes += response.responseBytes; },
+        transportOptions: { maxResponseBytes: () => MAX_RESPONSE_BYTES - responseBytes, shopApp: false }
+      });
+      const response = await read(request.path, request.body, 'logs');
+      if (responseBytes > MAX_RESPONSE_BYTES) {
+        throw reject('limit', 'logs', { kdtId: input.kdtId }, 'sent', response.facts);
+      }
+      const output = project(response.data, input, response.facts);
+      const text = `${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`;
+      if (Buffer.byteLength(text) > MAX_OUTPUT_BYTES) {
+        throw reject('limit', 'output', { kdtId: input.kdtId }, 'sent', response.facts);
+      }
+      process.stdout.write(text);
+    });
+  const seen = new Set();
+  for (const option of leaf.options) {
+    leaf.on(`option:${option.name()}`, () => {
+      if (seen.has(option.name())) throw reject('parameter', 'input');
+      seen.add(option.name());
+    });
+  }
+  return leaf;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };