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

package/src/commands/native/customer/tagcategory/get/schema.json

@@ -0,0 +1,339 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "tagCategoryId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/id"
+      },
+      "tagCategoryId": {
+        "$ref": "#/definitions/id"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "tag_category"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "tag_category": {
+            "$ref": "#/definitions/tagCategory"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "targetScope",
+      "request"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "targetScope": {
+        "$ref": "#/definitions/targetScope"
+      },
+      "request": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "body"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "method": {
+            "const": "POST"
+          },
+          "path": {
+            "const": "youzan.scrm.tag.category.get/1.0.0"
+          },
+          "body": {
+            "type": "object",
+            "required": [
+              "tag_category_id"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "tag_category_id": {
+                "$ref": "#/definitions/id"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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.tagcategory.get"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/id"
+              }
+            }
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "const": "youzan.scrm.tag.category.get/1.0.0"
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?[0-9]{1,12}$"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 999999999999
+              },
+              {
+                "type": "string",
+                "pattern": "^[0-9]{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": {
+    "id": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "正安全整数 ID；拒绝字符串和超出 JavaScript 安全范围的 Long。"
+    },
+    "targetScope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/id"
+        }
+      }
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "integer",
+        "minimum": -2147483648,
+        "maximum": 2147483647
+      },
+      "description": "角色整数数组；0 导购员及部门管理员，1 非导购的一线员工，不扩充为封闭枚举。"
+    },
+    "status": {
+      "type": "integer",
+      "enum": [
+        0,
+        1
+      ],
+      "description": "0 正常，1 已禁用；与独立标签模板 status 的方向不同。"
+    },
+    "tag": {
+      "type": "object",
+      "required": [
+        "tag_id",
+        "tag_name",
+        "tag_status"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "tag_id": {
+          "$ref": "#/definitions/id"
+        },
+        "tag_name": {
+          "type": "string"
+        },
+        "tag_status": {
+          "$ref": "#/definitions/status"
+        }
+      }
+    },
+    "tagCategory": {
+      "type": "object",
+      "required": [
+        "tag_category_id",
+        "kdt_id",
+        "tag_category_name",
+        "tags"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "tag_category_id": {
+          "$ref": "#/definitions/id"
+        },
+        "kdt_id": {
+          "$ref": "#/definitions/id"
+        },
+        "tag_category_name": {
+          "type": "string"
+        },
+        "tag_add_rule": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ],
+          "description": "0 仅唯一添加，1 可重复添加。"
+        },
+        "tag_category_status": {
+          "$ref": "#/definitions/status"
+        },
+        "support_tag_type": {
+          "type": "integer",
+          "enum": [
+            1,
+            2,
+            3
+          ],
+          "description": "1 手动打标，2 自动打标，3 全部。"
+        },
+        "sync_external": {
+          "type": "boolean"
+        },
+        "allow_edit_roles": {
+          "$ref": "#/definitions/roles"
+        },
+        "allow_view_roles": {
+          "$ref": "#/definitions/roles"
+        },
+        "create_source_desc": {
+          "type": "string"
+        },
+        "sync_wecom_helper": {
+          "type": "boolean"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/tag"
+          },
+          "description": "仅代表接口本次返回的组内标签集合；空数组与缺失不同。"
+        }
+      }
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.tag.category.get/1.0.0"
+  },
+  "success": {
+    "description": "组 ID 和店铺 ID 匹配目标，必需字段及出现的可选字段满足模型后成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "指定标签组 ID；店铺省略时使用当前上下文，显式非法值不回退；结果必须匹配目标；可选字段缺失省略，不补零、null 或空数组。",
+    "组和组内标签的状态均为 0 正常、1 禁用；本次 tags 不保证历史或全集完整性。",
+    "支持微商城单店、零售单店、连锁 D 总部、L 总部及 L 总部高级版；at 不代表跨店授权。",
+    "真实调用前须独立核实凭证与目标店铺绑定；本地上下文和结果店铺字段不能替代授权证明，远端链路尚未完成验证。",
+    "响应解析后检查 10 MiB、紧凑输出检查 5 MiB，超限整体失败；不是流式内存上限。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/customer/tagcategory/list/command.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+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 = 'customer.tagcategory.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function integer(text) {
+  if (typeof text !== 'string' || !/^[1-9]\d*$/.test(text) ||
+      !Number.isSafeInteger(Number(text))) throw new Error('invalid integer');
+  return Number(text);
+}
+
+function buildInput(options, context) {
+  const scope = resolveTargetShop(options, context, command);
+  try {
+    const input = { ...scope, pageNo: integer(options.pageNo), pageSize: integer(options.pageSize) };
+    if (options.keyword !== undefined) input.keyword = options.keyword.trim();
+    if (options.status !== undefined) input.status = options.status;
+    if (options.addRule !== undefined) input.addRule = options.addRule;
+    validateCommandValue(schema, 'input', input);
+    return input;
+  } catch { throw reject('parameter', 'input', scope); }
+}
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = () => reject('protocol', 'tag-categories-model', scope, 'sent', facts);
+  if (!object(data) || !object(data.paginator) || !Array.isArray(data.items)) throw invalid();
+  const page = data.paginator;
+  if (page.page !== input.pageNo || page.page_size !== input.pageSize) throw invalid();
+  const offset = (BigInt(input.pageNo) - 1n) * BigInt(input.pageSize);
+  const reportedTotal = readTotal(page, 'total_count', invalid);
+  const total = reportedTotal === null ? null : BigInt(reportedTotal);
+  if (data.items.length > input.pageSize ||
+      (total !== null && ((data.items.length > 0 && offset + BigInt(data.items.length) > total) ||
+      (data.items.length === 0 && offset < total)))) throw invalid();
+  const seen = new Set();
+  const tagCategories = data.items.map(row => {
+    if (!object(row) || row.kdt_id !== input.kdtId) {
+      throw reject('target_mismatch', 'tag-categories-model', scope, 'sent', facts);
+    }
+    if (seen.has(row.tag_category_id) || !Array.isArray(row.tags) ||
+        ![0, 1].includes(row.tag_add_rule)) throw invalid();
+    seen.add(row.tag_category_id);
+    return {
+      tagCategoryId: row.tag_category_id, kdtId: row.kdt_id, tagCategoryName: row.tag_category_name,
+      addRule: row.tag_add_rule === 0 ? 'unique' : 'repeat',
+      tags: row.tags.map(tag => {
+        if (!object(tag)) throw invalid();
+        return { tagId: tag.tag_id, tagName: tag.tag_name };
+      })
+    };
+  });
+  const output = { data: {
+    tagCategories,
+    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(); }
+  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>', '目标店铺正安全整数；须与凭证店铺一致；省略时使用当前上下文店铺')
+    .option('--page-no <n>', '页码正安全整数，从 1 开始', '1')
+    .option('--page-size <n>', '每页 1–50 条，默认 20', '20')
+    .option('--keyword <text>', '标签组名称关键词，去除首尾空白后不能为空')
+    .addOption(new Option('--status <status>', '标签组状态；省略表示全部')
+      .choices(['normal', 'disabled']))
+    .addOption(new Option('--add-rule <rule>', '组内标签添加规则；省略表示全部')
+      .choices(['unique', 'repeat']))
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验、筛选和一页请求，不读凭证、不联网')
+    .addHelpText('after', `
+返回 data.tagCategories 和 data.pagination 的 pageNo/pageSize/total/hasMore。
+hasMore 为 true 时保留筛选和 pageSize，将 pageNo 加 1 继续，不自动翻页。
+组内标签不截断；外层末页不证明组内标签全集，不保证跨请求快照。
+先核验凭证店铺，再发一次列表请求；空页也须通过店铺核验。
+支持微商城单店及官方列明的连锁 L 总部/网店/门店；组织位置 all 不授予跨店权限。
+失败整体为空 stdout；不重试、不切换店铺或身份，不降级为标签或客户关系查询。
+契约：zan-saas schema customer.tagcategory.list
+示例：zan-saas customer tagcategory list --kdt-id 63077 --page-size 20 --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const scope = { kdtId: input.kdtId };
+      const body = { page: input.pageNo, page_size: input.pageSize };
+      if (input.keyword !== undefined) body.tag_category_name = input.keyword;
+      if (input.status !== undefined) body.tag_category_status = input.status === 'normal' ? 0 : 1;
+      if (input.addRule !== undefined) body.tag_add_rule = input.addRule === 'unique' ? 0 : 1;
+      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, body, 'tag-categories');
+        output = project(data, input, 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) };