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

package/src/commands/native/customer/customer-tag/get/schema.json

@@ -0,0 +1,317 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "yzOpenId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "yzOpenId": {
+        "$ref": "#/definitions/customerId"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "customer_tag"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "customer_tag": {
+            "type": "object",
+            "description": "指定客户本次可见的标签关系视图；不承诺全集、稳定排序、唯一性或历史快照。",
+            "required": [
+              "yz_open_id",
+              "tags"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "yz_open_id": {
+                "$ref": "#/definitions/customerId",
+                "description": "本次查询的客户 ID，必须精确匹配目标。"
+              },
+              "tags": {
+                "type": "array",
+                "description": "本次返回的关系内容；保持顺序和重复项。空数组合法，缺失和 null 拒绝。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "tag_id",
+                    "tag_name"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "tag_id": {
+                      "$ref": "#/definitions/positiveId",
+                      "description": "标签定义 ID，类型为安全整数，不接受字符串或失真整数。"
+                    },
+                    "tag_name": {
+                      "type": "string",
+                      "description": "标签名称，保留空字符串，不是客户备注。"
+                    },
+                    "tag_category_id": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "标签组 ID，缺失省略，0 原样保留，不推断为未分组。"
+                    },
+                    "tag_category_name": {
+                      "type": "string",
+                      "description": "标签组名称，缺失省略，空字符串保留，不补 null 或默认名称。"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "targetScope",
+      "request"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "targetScope": {
+        "$ref": "#/definitions/scope"
+      },
+      "request": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "body"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "method": {
+            "const": "POST"
+          },
+          "path": {
+            "const": "youzan.scrm.tagrelation.query/1.0.0"
+          },
+          "body": {
+            "type": "object",
+            "required": [
+              "account",
+              "filter_invalid_tag",
+              "filter_category_tag",
+              "display_type"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "account": {
+                "type": "object",
+                "required": ["account_type", "account_id"],
+                "additionalProperties": false,
+                "properties": {
+                  "account_type": { "const": 5 },
+                  "account_id": { "type": "string", "minLength": 1 }
+                },
+                "description": "客户标识对象。"
+              },
+              "filter_invalid_tag": {
+                "const": false,
+                "description": "不主动排除禁用标签。"
+              },
+              "filter_category_tag": {
+                "const": false,
+                "description": "不主动排除标签组内标签。"
+              },
+              "display_type": {
+                "const": 2,
+                "description": "请求隐藏和展示标签，仍遵守服务端授权。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+            "enum": [
+              "parameter",
+              "configuration",
+              "authentication",
+              "permission",
+              "http",
+              "transport",
+              "business_rejected",
+              "protocol"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "customer.customer-tag.get"
+          },
+          "targetScope": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/scope"
+              },
+              {
+                "type": "object",
+                "maxProperties": 0
+              }
+            ],
+            "description": "只含安全店铺范围，不回显客户 ID。"
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ],
+            "description": "本地拒绝为 not_sent；取得响应为 sent；传输中断无法确定结果为 unknown。"
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "const": "youzan.scrm.tagrelation.query/1.0.0"
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?\\d{1,12}$"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "oneOf": [
+              {
+                "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": {
+    "positiveId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "shopId": {
+      "$ref": "#/definitions/positiveId",
+      "description": "显式目标店铺；真实调用前须独立确认凭证与目标店铺绑定。"
+    },
+    "customerId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "客户 yzOpenId 字符串，不是手机号、微信 openId 或员工 ID。"
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/shopId"
+        }
+      }
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.tagrelation.query/1.0.0"
+  },
+  "success": {
+    "description": "客户 ID 精确匹配，完整保留本次响应中的标签集合及已取得的分组字段，每项满足模型后成功；不据此声明历史全集或跨时点快照。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "获取一个客户的标签集合推荐本命令，返回 data.customer_tag；已有 list 保留原契约，不互为别名或失败降级入口，不以此区分时效性或历史范围。",
+    "只接受一个已知客户，不提供标签筛选、分页、关键词或 include；不改变客户详情的 tags 模块。",
+    "集合范围为本次接口在授权可见范围内返回的标签关系；不截断、不分页。分类缺失省略，0 原样保留，不推断未分组；不承诺历史全集、固定顺序或跨时点快照。",
+    "真实调用前须确认凭证与目标店铺绑定；本地上下文和客户匹配不证明该绑定或远端授权。",
+    "响应读取后检查 10 MiB、最终 stdout 文本含换行检查 5 MiB；json 与 pretty 按各自实际字节数判定。超限整体失败，不截断，不是流式内存上限。",
+    "省略 --kdt-id 时使用当前选中店铺；显式指定时使用指定店铺，权限由服务端校验。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/customer/customer-tag/list/command.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command } = require('commander');
+const { requestApi, ApiConfigurationError } = require('../../../../../transport/api');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const schema = require('./schema.json');
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function failure(category, stage, requestState = 'not_sent', facts = {}) {
+  const error = new Error('客户标签查询失败；请查看错误分类和失败步骤。');
+  error.cliDetails = {
+    category, stage, command: 'customer.customer-tag.list', targetScope: {}, requestState,
+    nextStep: '核对本命令契约、目标店铺和服务端授权；不自动切换身份或重试。',
+    ...facts
+  };
+  return error;
+}
+
+async function listCustomerTags(options, context) {
+  if (!/^[1-9]\d*$/.test(options.kdtId) || !Number.isSafeInteger(Number(options.kdtId))) {
+    throw failure('input', 'kdtId');
+  }
+  const yzOpenId = options.yzOpenId.trim();
+  if (!yzOpenId) throw failure('input', 'yzOpenId');
+  if (!['json', 'pretty'].includes(options.format)) throw failure('input', 'format');
+  const input = { kdtId: Number(options.kdtId), yzOpenId };
+  validateCommandValue(schema, 'input', input);
+  if (context?.orgType === 'shop' && String(input.kdtId) !== context.shopId) {
+    throw failure('permission', 'context');
+  }
+  const request = {
+    method: 'POST',
+    path: schema.api.path,
+    body: {
+      account: { account_id: yzOpenId, account_type: 5 },
+      display_type: 2,
+      filter_invalid_tag: false,
+      filter_category_tag: false
+    }
+  };
+  if (options.dryRun) {
+    validateCommandValue(schema, 'preview', request);
+    return request;
+  }
+  let response;
+  try {
+    response = await requestApi(request);
+  } catch (error) {
+    if (error instanceof ApiConfigurationError) throw failure('configuration', 'configuration');
+    throw failure('transport', 'request', 'unknown');
+  }
+  const facts = { api: request.path, httpStatus: response.httpStatus };
+  if (!response.ok) {
+    const category = response.httpStatus === 401 ? 'authentication' :
+      response.httpStatus === 403 ? 'permission' : 'http';
+    throw failure(category, 'response', 'sent', facts);
+  }
+  let result;
+  try {
+    result = JSON.parse(response.body);
+  } catch {
+    throw failure('protocol', 'response', 'sent', facts);
+  }
+  if (!object(result)) throw failure('protocol', 'response', 'sent', facts);
+  if (Number.isSafeInteger(result.code)) facts.businessCode = result.code;
+  if (object(result.gw_err_resp) &&
+      (Number.isSafeInteger(result.gw_err_resp.err_code) ||
+       (typeof result.gw_err_resp.err_code === 'string' && /^-?\d{1,12}$/.test(result.gw_err_resp.err_code)))) {
+    facts.gatewayCode = result.gw_err_resp.err_code;
+  }
+  const traceId = result.trace_id ?? result.gw_err_resp?.trace_id;
+  if (typeof traceId === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(traceId)) facts.trace_id = traceId;
+  if (facts.gatewayCode !== undefined) {
+    throw failure(result.success === true || [0, 200].includes(result.code) ? 'protocol' : 'business_rejected',
+      'response', 'sent', facts);
+  }
+  if (result.success === false || !(result.success === true || [0, 200].includes(result.code))) {
+    throw failure('business_rejected', 'response', 'sent', facts);
+  }
+  if (!object(result.data) || result.data.yz_open_id !== yzOpenId ||
+      !Array.isArray(result.data.tags) || result.data.tags.some(tag => !object(tag))) {
+    throw failure('protocol', 'response', 'sent', facts);
+  }
+  const output = {
+    data: {
+      yzOpenId: result.data.yz_open_id,
+      tags: result.data.tags.map(tag => ({
+        tagId: tag.tag_id,
+        tagName: tag.name,
+        tagCategoryId: tag.category_id,
+        ...(tag.category_name === null || tag.category_name === undefined ? {} :
+          { tagCategoryName: tag.category_name })
+      }))
+    }
+  };
+  try {
+    validateCommandValue(schema, 'output', output);
+  } catch {
+    throw failure('protocol', 'response', 'sent', facts);
+  }
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  return new Command('list')
+    .description('按既有 list 契约读取一个客户的标签关系；新调用推荐 customer-tag get')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw failure('input', 'arguments');
+    })
+    .option('--kdt-id <id>', '目标店铺 ID，须为正安全整数；省略时使用当前上下文店铺')
+    .requiredOption('--yz-open-id <id>', '客户 yzOpenId，去除首尾空白后须非空')
+    .option('--format <format>', 'json 或 pretty，仅改变缩进', 'json')
+    .option('--dry-run', '仅本地预览请求，不读凭证、不联网')
+    .addHelpText('after', `
+查询客户标签关系；标签定义与标签组须使用各自入口，不执行写入或回退到客户详情。
+新调用查询单个客户的标签集合时，推荐使用 customer-tag get。
+本入口保留既有输出契约，不代表更新更及时或提供历史视图。
+在服务端允许的范围内，包含可见与隐藏、启用与禁用、有分组与无分组的关系。
+从单次响应返回 data.yzOpenId 和 data.tags，不分页，也不保证快照一致性。
+
+示例：
+  zan-saas customer customer-tag list --kdt-id 63077 --yz-open-id customer-1
+  zan-saas customer customer-tag list --kdt-id 63077 --yz-open-id customer-1 --format pretty
+  zan-saas customer customer-tag list --kdt-id 63077 --yz-open-id customer-1 --dry-run
+
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+ZAN_SAAS_CONTEXT 包含 userId、hq、shopId 和 orgType，orgType 为 hq 或 shop。
+店铺上下文中，--kdt-id 必须与 context.shopId 一致；总部目标仍须服务端授权。
+接口请求与响应均无 kdt_id 字段，本地检查不证明目标店铺已授权。
+缺少上下文时 --dry-run 仍仅本地预览；失败仅向 stderr 写入结构化脱敏错误。
+最多发送一次请求，不重试、重定向、更换编码或改用其他接口。`)
+    .action(async options => {
+      const result = await listCustomerTags(options, context);
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };