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

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

@@ -0,0 +1,82 @@
+'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.rule.list';
+const outputLimit = 5 * 1024 * 1024;
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function project(data) {
+  if (!object(data) || !Array.isArray(data.rules) || data.rules.some(rule => !object(rule))) {
+    throw new Error('Invalid rules');
+  }
+  const output = { data: { rules: data.rules.map(rule => ({
+    ruleId: rule.rule_id,
+    ruleName: rule.rule_name,
+    givePoints: rule.give_points,
+    ...(Object.hasOwn(rule, 'trade_limit') ? { tradeLimit: rule.trade_limit } : {}),
+    ...(Object.hasOwn(rule, 'fans_follow') ? { fansFollow: rule.fans_follow } : {}),
+    ...(Object.hasOwn(rule, 'is_send_notice') ? { isSendNotice: rule.is_send_notice } : {}),
+    ...(Object.hasOwn(rule, 'item_ids') ? { channel_item_ids: rule.item_ids } : {})
+  })) } };
+  validateCommandValue(schema, 'output', output);
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  return new Command('list')
+    .description('读取商家自定义积分奖励及部分条件配置，不包含默认规则或完整触发条件')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId，非总部不可跨店')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览规则及店铺核验请求，不读凭证、不联网')
+    .addHelpText('after', `
+输出仅 data.rules；ruleId、ruleName、givePoints 必需，tradeLimit、fansFollow、isSendNotice、channel_item_ids 可选。
+fansFollow：数字0不要求关注公众号，1要求；它是规则配置，不是客户实际关注状态。
+isSendNotice：数字0不发通知，1配置发送获得积分的微信模板消息；不证明已发送或送达。
+保留规则及商品引用的顺序和重复；明确空数组仅表示本接口未返回商家自定义规则。
+不输出金额阈值 amountLimit，不解析名称中的金额，不承诺完整规则条件或实际发放、通知结果。
+没有客户、分页、fields 或商品详情请求；最多一次店铺核验与一次主查询，不重试或换店。
+选定输出按紧凑 UTF-8 JSON 限制 5MiB（json/pretty 相同）；超额整体失败，不截断规则或 channel_item_ids。
+真实执行需四字段上下文和同店授权凭证；店铺核验不证明员工 OAuth。
+产品范围限主辅 API 交集：微商城单店、零售单店及有赞连锁 D 总部/网店/合伙人。
+契约：zan-saas schema points.rule.list --format json
+示例：zan-saas points rule list
+示例：zan-saas points rule list --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      validateCommandValue(schema, 'input', scope);
+      const preview = {
+        method: 'POST', path: schema.api.path, body: {}, 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, 'rules');
+        try { output = project(data); }
+        catch { throw reject('protocol', 'rules-model', scope, 'sent', facts); }
+        if (Buffer.byteLength(JSON.stringify(output), 'utf8') > outputLimit) {
+          throw reject('budget_exceeded', 'output-budget', 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) };

package/src/commands/native/points/rule/list/schema.json

@@ -0,0 +1,294 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "$ref": "#/definitions/scope",
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "rules"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "rules": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/rule"
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body",
+      "scope",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.customer.points.rule.list/1.0.0"
+      },
+      "body": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "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
+            }
+          }
+        }
+      }
+    }
+  },
+  "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",
+        "additionalProperties": false,
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep"
+        ],
+        "properties": {
+          "category": {
+            "enum": [
+              "parameter",
+              "validation",
+              "configuration",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "budget_exceeded"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "points.rule.list"
+          },
+          "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",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "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}$"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "positiveInteger": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "safeInteger": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/positiveInteger"
+        }
+      }
+    },
+    "rule": {
+      "type": "object",
+      "required": [
+        "ruleId",
+        "ruleName",
+        "givePoints"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "ruleId": {
+          "$ref": "#/definitions/positiveInteger",
+          "description": "本店铺规则 ID，不跨店关联或要求集合唯一。"
+        },
+        "ruleName": {
+          "type": "string",
+          "description": "源规则名称，保留空串，不解析金额或规则类别。"
+        },
+        "givePoints": {
+          "$ref": "#/definitions/safeInteger",
+          "description": "奖励积分值，保留 0 和明确返回的负整数，不等于账户余额。"
+        },
+        "tradeLimit": {
+          "$ref": "#/definitions/safeInteger",
+          "description": "达到该交易次数才发放；不根据数值推断规则类别。"
+        },
+        "fansFollow": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ],
+          "description": "是否配置领取积分前须关注公众号：数字0不要求，1要求；不表示客户实际关注状态。"
+        },
+        "isSendNotice": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ],
+          "description": "是否配置发送获得积分的微信模板消息通知：数字0否，1是；不证明已发送或送达。"
+        },
+        "channel_item_ids": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/positiveInteger"
+          },
+          "description": "旧模型渠道商品 ID 引用，保留顺序及重复；不是OneID，不承诺引用商品当前仍存在。缺失省略。"
+        }
+      }
+    },
+    "diagnosticCode": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/safeInteger"
+        },
+        {
+          "type": "string",
+          "pattern": "^-?\\d{1,12}$"
+        }
+      ]
+    }
+  },
+  "modules": {
+    "rules": {
+      "base": true,
+      "upstreamPath": "data.rules",
+      "required": true,
+      "description": "商家自定义积分奖励及部分条件配置；不包含默认规则或完整触发条件，明确空数组成功，缺失失败。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.customer.points.rule.list/1.0.0"
+  },
+  "success": {
+    "description": "店铺核验通过，规则列表明确取得、满足递归模型及 5 MiB 输出预算后成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "仅查询商家自定义积分规则，不分页、不读取客户或商品详情；空数组不表示没有默认规则。",
+    "可选字段缺失省略，已选字段 null、错型或非安全整数整体失败；保留 0、空名称、顺序和重复。",
+    "不返回金额阈值，不能还原完整规则触发条件；不覆盖所有积分获取渠道、积分抵现、积分商城开关或实际发放与通知结果，不从规则名称解析条件。",
+    "紧凑 UTF-8 JSON 输出最多 5 MiB，json/pretty 使用同一预算，超额整体失败；不是流式内存限制。",
+    "支持微商城单店、零售单店和连锁 D 总部、网店及合伙人。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

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

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 3,
+  "domain": "privacy",
+  "businessCommands": [
+    {
+      "path": "privacy.field.decrypt",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "preview_only",
+      "at": "all",
+      "module": "privacy/field/decrypt/command.js",
+      "fingerprint": "6cef4a999c9a3536435b2f2d4df98e702f7d45edaf97640c8ef69854bb39f289"
+    }
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "隐私数据：订单字段受控解密，仅支持离线预览"
+}

package/src/commands/native/privacy/field/decrypt/command.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { InputIssueError, inputIssue, constraints, modelAt } = require('../../../../../execution/error-details');
+const { readContext } = require('../../../../../identity/context');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readJsonInput } = require('../../../../../execution/bounded-input');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { discloseFields, privacyError, OUTPUT_LIMIT } = require('../../../../../execution/privacy');
+const { loadOrderSource } = require('../../shared/order-source');
+const schema = require('./schema.json');
+
+const command = 'privacy.field.decrypt';
+
+function reject(category, stage, scope = {}, state = 'not_sent') {
+  return privacyError(command, category, stage, scope, state);
+}
+
+function documentIssue(reason, expected) {
+  return new InputIssueError([{ source: 'input', option: '--input-file', reason, expected }]);
+}
+
+async function buildInput(options, context, stdin) {
+  let input;
+  try {
+    let document;
+    try { document = await readJsonInput(options.inputFile, { stdin }); }
+    catch {
+      throw documentIssue('invalid_format', {
+        format: '可读取的 UTF-8 JSON 文件或 stdin，最多64KiB，不含重复 JSON 成员'
+      });
+    }
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+      throw documentIssue('invalid_type', { type: 'object' });
+    }
+    if (Object.keys(document).some(key => !['object', 'values'].includes(key))) {
+      throw documentIssue('unexpected_property', { additionalProperties: false });
+    }
+    if (typeof options.reason !== 'string' || /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(options.reason)) {
+      throw inputIssue('/reason', typeof options.reason === 'string' ? 'invalid_format' : 'invalid_type',
+        constraints(modelAt(schema, 'input', '/reason')));
+    }
+    input = { kdtId: options.kdtId, object: document.object, values: document.values,
+      reason: options.reason.trim(), format: options.format, dryRun: options.dryRun === true };
+    validateCommandValue(schema, 'input', input);
+    if (!Number.isSafeInteger(Number(input.kdtId))) {
+      throw inputIssue('/kdtId', 'out_of_range', {
+        type: 'string', pattern: '^[1-9]\\d*$', maximum: Number.MAX_SAFE_INTEGER
+      });
+    }
+    if (new Set(input.values.map(item => item.key)).size !== input.values.length ||
+        new Set(input.values.map(item => item.field)).size !== input.values.length) {
+      throw inputIssue('/values', 'constraint', { format: '每项 key 和 field 分别唯一' });
+    }
+    for (const [index, item] of input.values.entries()) {
+      if (Buffer.byteLength(item.ciphertext) > 16384) {
+        throw inputIssue(`/values/${index}/ciphertext`, 'out_of_range', {
+          type: 'string', minLength: 1, maxLength: 16384, format: 'UTF-8 最多16384字节'
+        });
+      }
+    }
+  } catch (error) {
+    // Keep field diagnostics, while preserving the direct buildInput error contract.
+    if (error.section === 'input') {
+      error.cliDetails = reject('validation', 'input').cliDetails;
+      throw error;
+    }
+    throw reject('validation', 'input');
+  }
+  try { resolveTargetShop({ kdtId: input.kdtId, dryRun: input.dryRun }, context, command); }
+  catch (error) {
+    throw reject(error.cliDetails?.category || 'configuration', 'scope');
+  }
+  return input;
+}
+
+function preview(input) {
+  const output = { plan: { kdtId: input.kdtId, object: input.object,
+    fields: input.values.map(item => item.field), itemCount: input.values.length,
+    maximumApiRequests: 4, requiresSensitiveAuthorization: true } };
+  validateCommandValue(schema, 'preview', output);
+  return output;
+}
+
+function serialize(output, format, scope, limit = OUTPUT_LIMIT) {
+  const json = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`) > limit) throw reject('limit', 'output-model', scope, 'sent');
+  return json;
+}
+
+async function execute(input, context, { provider, outputLimit = OUTPUT_LIMIT } = {}) {
+  const scope = Object.freeze({ kdtId: input.kdtId });
+  const fields = Object.freeze(input.values.map(item => item.field));
+  const expectedCiphertexts = Object.freeze(Object.fromEntries(input.values.map(item => [item.field, item.ciphertext])));
+  const request = Object.freeze({ scope, object: Object.freeze({ ...input.object }), fields,
+    expectedCiphertexts, reason: input.reason, allowEmptyPlaintext: true, preserveStage: true });
+  let serialized;
+  if (!provider || typeof provider.authorize !== 'function') {
+    throw privacyError(command, 'provider_unavailable', 'privacy-authorization', scope);
+  }
+  const adaptedProvider = {
+    authorize: async (fixed, { environment }) => {
+      const session = await provider.authorize(fixed, environment);
+      if (!session || typeof session.bindSource !== 'function' || typeof session.record !== 'function') {
+        return session;
+      }
+      return {
+        verifySource: ({ sourceData, values }) => session.bindSource({
+          sourceData, fields: values.map(value => value.field),
+          ciphertexts: values.map(value => value.value)
+        }),
+        recordAccess: event => session.record({
+          ...event,
+          requestState: event.requestState || 'sent',
+          outcome: event.outcome === 'release_authorized' ? 'prepared_for_cli' :
+            event.outcome === 'unknown' ? 'unknown' : 'rejected'
+        })
+      };
+    }
+  };
+  try {
+    await discloseFields(request, { command, allowedFields: fields, provider: adaptedProvider,
+    readSource: async (read, fixed) => {
+      const loaded = await loadOrderSource(fixed, read, context, command);
+      return {
+        sourceData: loaded.sourceData,
+        values: loaded.ciphertexts.map((value, index) => ({ field: fixed.fields[index], value }))
+      };
+    },
+    validateResult: result => {
+      const output = { data: { values: result.values.map((item, index) =>
+        ({ key: input.values[index].key, ...item })) } };
+      validateCommandValue(schema, 'output', output);
+      serialized = serialize(output, input.format, scope, outputLimit);
+    } });
+  } catch (error) {
+    const stageMap = {
+      source: 'source-binding',
+      'ciphertext-verification': 'verify',
+      decryption: 'decrypt',
+      'sensitive-audit': 'audit'
+    };
+    if (error?.cliDetails) {
+      if (error.cliDetails.stage === 'sensitive-audit') error.cliDetails.category = 'audit_failed';
+      if (error.cliDetails.category === 'transport') error.cliDetails.stage = 'transport';
+      else if (stageMap[error.cliDetails.stage]) error.cliDetails.stage = stageMap[error.cliDetails.stage];
+      error.message = `查询失败：${error.cliDetails.category}（${error.cliDetails.stage}）`;
+    }
+    throw error;
+  }
+  return serialized;
+}
+
+function createCommand({ context, stdin, privacyDependencies } = {}) {
+  return new DiagnosticCommand('decrypt', { path: command, schema,
+    optionPaths: { '/object': 'inputFile', '/values': 'inputFile' } })
+    .description('核验单笔订单来源后受控解密；员工授权及审计尚未接入，当前仅离线预览')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正十进制安全整数；省略时使用当前上下文店铺')
+    .requiredOption('--input-file <path>', '必填：最多 64KiB UTF-8 JSON；- 为有界 stdin')
+    .requiredOption('--reason <text>', '必填：1 至 200 个 Unicode 码点的用途，不填个人信息')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '校验输入并输出不含密文、key 和用途的计划；零凭证、零网络')
+    .addHelpText('after', `
+仅接受一笔明确订单的一至三个收货姓名、电话或详细地址字段，输入关联 key 与字段须各自唯一。
+密文不证明对象授权，打星值不能恢复；来源不符、非密文、权限或审计失败均拒绝，不输出部分明文。
+当前缺少真实员工字段授权、服务端来源绑定及可靠审计适配，执行在发送业务请求前拒绝，不表示功能验收完成。
+接入后至多四次有赞业务请求，不初始化应用、不重发、重定向、换店、换应用或身份。
+执行需要有效四字段上下文，非总部目标须匹配当前店铺；总部也不表示跨店授权。
+stdout 明文可能被终端、重定向或 Agent 保存。不得据单对象权限推导批量导出或第三方传输权限。
+模型与字段含义见 zan-saas schema privacy.field.decrypt；指引见 zan-saas skills read zan-saas-privacy。
+示例：zan-saas privacy field decrypt --kdt-id 63077 --input-file ciphertext.json --reason "核对本次配送" --dry-run
+`)
+    .action(async options => {
+      const input = await buildInput(options, context, stdin);
+      const output = input.dryRun ? serialize(preview(input), input.format, { kdtId: input.kdtId }) :
+        await execute(input, readContext(context).context, privacyDependencies);
+      console.log(output);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', availability: 'preview_only', createCommand: withTargetShopDefault(createCommand), buildInput, execute, serialize };