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

package/src/commands/native/org/unit/get/schema.json

@@ -0,0 +1,478 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "include"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "include": {
+        "type": "array",
+        "uniqueItems": true,
+        "items": {
+          "enum": [
+            "address",
+            "contact",
+            "operation-status"
+          ]
+        },
+        "description": "逗号拆分、去首尾空白并去重；默认空数组；空项和未知模块拒绝。"
+      }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "unit"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "unit": {
+            "type": "object",
+            "required": [
+              "kdtId",
+              "name",
+              "orgRole"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/shopId"
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S",
+                "description": "当前组织名称；名称必须非空，不用上下文名称补值。"
+              },
+              "orgRole": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "组织角色：0 单店；1 总部；2001 门店；2002 网店；3 独立仓；4 合伙人；6 分销供货店铺；7 前置仓。未知合法代码保留，不推断含义；不是员工权限角色或列表筛选组。"
+              },
+              "rootKdtId": {
+                "$ref": "#/definitions/shopId"
+              },
+              "parentKdtId": {
+                "$ref": "#/definitions/shopId"
+              },
+              "lineOfBusiness": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "业务线：10000 微商城；20000 教育；50000 餐饮；60000 美业；70000 零售；140000 供货。未知合法代码原值保留；不是店铺类型。"
+              },
+              "certType": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "认证类型：0 未认证；2 企业认证；3 个人认证；12 个体工商户认证；10 其他组织、政府及事业单位。未知合法代码保留，不代表本次资料变更审核结果。"
+              },
+              "logo": {
+                "type": "string",
+                "description": "Logo 原文，不检查可达性。"
+              },
+              "intro": {
+                "type": "string",
+                "description": "简介，空串保留。"
+              },
+              "url": {
+                "type": "string",
+                "description": "主页链接原文，不访问。"
+              },
+              "physicalUrl": {
+                "type": "string",
+                "description": "线下店铺链接原文，不访问。"
+              },
+              "address": {
+                "type": "object",
+                "required": [
+                  "address"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "address": {
+                    "type": "string",
+                    "description": "详细地址原文，允许空串。"
+                  },
+                  "province": {
+                    "type": "string",
+                    "description": "省原文。"
+                  },
+                  "city": {
+                    "type": "string",
+                    "description": "市原文。"
+                  },
+                  "county": {
+                    "type": "string",
+                    "description": "区县原文。"
+                  },
+                  "countyId": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "地址区县编码，允许 0；不是组织 ID。"
+                  },
+                  "lng": {
+                    "type": "string",
+                    "description": "百度坐标经度文本，不转浮点、不换坐标系。"
+                  },
+                  "lat": {
+                    "type": "string",
+                    "description": "百度坐标纬度文本，不推导缺失坐标。"
+                  }
+                }
+              },
+              "contact": {
+                "type": "object",
+                "required": [
+                  "phoneNumber"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "phoneNumber": {
+                    "type": "string",
+                    "description": "客服电话原文，允许空串；不拼接区号。"
+                  },
+                  "areaCode": {
+                    "type": "string",
+                    "description": "客服电话区号原文，允许空串。"
+                  }
+                }
+              },
+              "operationStatus": {
+                "type": "integer",
+                "enum": [
+                  0,
+                  1,
+                  2,
+                  3
+                ],
+                "description": "运营状态：0 创建未完成；1 筹备中；2 运营中；3 停用。无法确认状态时整体失败。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "scope",
+      "requests",
+      "selection"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "type": "object",
+        "required": [
+          "kdtId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": {
+            "$ref": "#/definitions/shopId"
+          }
+        }
+      },
+      "requests": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 2,
+        "items": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": [
+                "stage",
+                "method",
+                "path",
+                "body"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "stage": {
+                  "const": "unit-basic"
+                },
+                "method": {
+                  "const": "POST"
+                },
+                "path": {
+                  "const": "youzan.shop.basic.get/3.0.0"
+                },
+                "body": {
+                  "type": "object",
+                  "required": [],
+                  "additionalProperties": false,
+                  "properties": {}
+                }
+              }
+            },
+            {
+              "type": "object",
+              "required": [
+                "stage",
+                "method",
+                "path",
+                "body"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "stage": {
+                  "const": "operation-status"
+                },
+                "method": {
+                  "const": "POST"
+                },
+                "path": {
+                  "const": "youzan.shop.configs.get/2.0.0"
+                },
+                "body": {
+                  "type": "object",
+                  "required": [
+                    "keys",
+                    "node_kdt_ids"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "keys": {
+                      "type": "array",
+                      "minItems": 1,
+                      "maxItems": 1,
+                      "items": {
+                        "const": "shop_operation_status"
+                      }
+                    },
+                    "node_kdt_ids": {
+                      "type": "array",
+                      "minItems": 1,
+                      "maxItems": 1,
+                      "items": {
+                        "$ref": "#/definitions/shopId"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "description": "严格按基础、可选运营状态的顺序；最多两次，无类型补查。"
+      },
+      "selection": {
+        "type": "object",
+        "required": [
+          "include"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "include": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "enum": [
+                "address",
+                "contact",
+                "operation-status"
+              ]
+            },
+            "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",
+              "validation",
+              "configuration",
+              "authentication",
+              "permission",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "input",
+              "context",
+              "scope",
+              "configuration",
+              "unit-basic",
+              "unit-model",
+              "operation-status",
+              "transport",
+              "http",
+              "response"
+            ]
+          },
+          "command": {
+            "const": "org.unit.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": "正安全整数组织标识；目标必须等于当前上下文组织，总部也不可改查分店。资料与运营状态必须属于同一目标。"
+    }
+  },
+  "modules": {
+    "basic": {
+      "base": true,
+      "required": true,
+      "upstreamPath": "data",
+      "description": "组织标识、名称和组织角色必需。可选资料缺省或无值时省略；空串与 0 保留。"
+    },
+    "address": {
+      "base": false,
+      "required": false,
+      "upstreamPath": "data.shop_address",
+      "description": "仅选择时返回；地址对象与详细地址文本必需。"
+    },
+    "contact": {
+      "base": false,
+      "required": false,
+      "upstreamPath": "data.customer_service_phone_number",
+      "description": "仅选择时返回；联系电话对象与电话号码文本必需。"
+    },
+    "operation-status": {
+      "base": false,
+      "required": false,
+      "upstreamPath": "data[].configs.shop_operation_status",
+      "description": "仅选择时追加当前组织的运营状态查询；必须取得唯一匹配目标及已知状态。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.shop.basic.get/3.0.0"
+  },
+  "success": {
+    "description": "当前组织归属已核实，名称非空、组织角色有效，所有选定扩展均已取得并通过模型校验后返回 data.unit。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 单一安全错误信封并退出 1。扩展失败不返回部分资料；不重试、不换身份/目标、不降级模块。中断 requestState=unknown；诊断不包含自由文本。"
+  },
+  "notes": [
+    "at=all 只表示位置准入，不证明员工授权或任意产品支持。",
+    "未选模块整体省略，不验证未消费内容；不返回店铺类型、QQ、升级历史或其他配置。",
+    "可选字段源缺省或 null 时省略，不代表不存在。扩展核心缺失整体失败。",
+    "默认一次请求；address/contact 不增加请求；operation-status 最多两次，传输固定同一网关/token 快照。",
+    "缺少上下文仅允许显式合法目标的本地预览；无效上下文仍拒绝。"
+  ]
+}

package/src/commands/native/org/unit/list/command.js

@@ -0,0 +1,187 @@
+'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, withInputScope, constraints, modelAt, parseIntegerOption } = require('../../../../../execution/error-details');
+const schema = require('./schema.json');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readContext } = require('../../../../../identity/context');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { fromBeijingSeconds } = require('../../../../../execution/beijing-date-time');
+const { object } = require('../../../../../execution/query-api');
+const { createBoundShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+
+const command = 'org.unit.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function integer(value, path) {
+  if (path === '/orgRoles') {
+    if (typeof value !== 'string' || value !== value.trim() || !/^[1-9]\d*$/.test(value)) {
+      throw inputIssue(path, 'invalid_format', constraints(modelAt(schema, 'input', path)));
+    }
+    return Number(value);
+  }
+  return parseIntegerOption(value, schema, path);
+}
+
+function csv(value) {
+  return value === undefined ? [] : [...new Set(value.split(',').map(part => part.trim()))];
+}
+
+function buildInput(options, context) {
+  let scope;
+  try {
+    scope = resolveTargetShop(options, context, command);
+  } catch (error) {
+    if (error.cliDetails?.stage === 'validation') error.cliDetails.stage = 'input';
+    throw error;
+  }
+  const state = readContext(context);
+  const rawTarget = Object.hasOwn(options, 'kdtId') ? options.kdtId : state.context?.shopId;
+  if (String(scope.kdtId) !== rawTarget) {
+    throw reject(Object.hasOwn(options, 'kdtId') ? 'validation' : 'configuration', 'input', scope);
+  }
+  if (state.status === 'ready' && (state.context.orgType !== 'hq' ||
+      state.context.shopId !== state.context.hq || String(scope.kdtId) !== state.context.hq)) {
+    throw reject('permission', 'scope', scope);
+  }
+  return withInputScope(scope, () => {
+    const input = { ...scope, pageNo: integer(options.pageNo, '/pageNo'), pageSize: integer(options.pageSize, '/pageSize'),
+      orgRoles: csv(options.orgRoles).map(value => integer(value, '/orgRoles')), include: csv(options.include) };
+    validateCommandValue(schema, 'input', input);
+    return input;
+  });
+}
+
+function previewFor(input) {
+  const body = { page_num: input.pageNo, page_size: input.pageSize,
+    ...(input.orgRoles.length && { shop_roles: input.orgRoles }),
+    with_dept_info: input.include.includes('departments'),
+    with_shop_status_and_lifecycle_end_time: input.include.some(name => ['status', 'lifecycle'].includes(name)),
+    with_crm_shop: false };
+  return { scope: { kdtId: input.kdtId }, requests: [
+    { stage: 'unit-basic', method: 'POST', path: bindingPath, body: {} },
+    { stage: 'units', method: 'POST', path: schema.api.path, body }
+  ], selection: { orgRoles: input.orgRoles, include: input.include } };
+}
+
+function optionalFields(source, mapping) {
+  const result = {};
+  for (const [field, upstream] of Object.entries(mapping)) {
+    if (source[upstream] !== undefined && source[upstream] !== null) result[field] = source[upstream];
+  }
+  return result;
+}
+
+function projectUnit(source, include) {
+  if (!object(source)) throw new TypeError('Invalid unit');
+  const unit = { kdtId: source.kdt_id, name: source.name, orgRole: source.role,
+    ...optionalFields(source, { joinType: 'join_type', parentKdtId: 'parent_kdt_id', externalCode: 'outer_id' }) };
+  if (include.includes('address')) {
+    if (!object(source.shop_address)) throw new TypeError('Invalid address');
+    unit.address = { address: source.shop_address.address,
+      ...optionalFields(source.shop_address, { county: 'county', countyId: 'county_id' }) };
+  }
+  if (include.includes('departments')) {
+    if (!Array.isArray(source.dept_info_list)) throw new TypeError('Invalid departments');
+    unit.departments = source.dept_info_list.map(department => {
+      if (!object(department)) throw new TypeError('Invalid department');
+      return { departmentId: department.dept_id,
+        ...optionalFields(department, { name: 'dept_name', externalDepartmentId: 'out_dept_id' }) };
+    });
+  }
+  if (include.includes('status')) {
+    unit.status = optionalFields(source, { onlineBusinessStatus: 'access_status',
+      offlineBusinessStatus: 'offline_business_status', storeStatus: 'store_status' });
+  }
+  if (include.includes('lifecycle')) {
+    const value = source.lifecycle_end_time;
+    const normalized = typeof value === 'string' && value.length === 19 && /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}$/.test(value) ?
+      `${value.slice(0, 10)} ${value.slice(11, 13)}:${value.slice(14, 16)}:${value.slice(17, 19)}` : value;
+    unit.lifecycle = { endsAt: fromBeijingSeconds(normalized) };
+  }
+  return unit;
+}
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = category => reject(category, 'units', scope, 'sent', facts);
+  if (!object(data) || !Array.isArray(data.organization_list) ||
+      data.page_num !== input.pageNo || data.page_size !== input.pageSize ||
+      data.organization_list.length > input.pageSize) {
+    throw invalid('protocol');
+  }
+  const rows = data.organization_list;
+  let total;
+  try { total = readTotal(data, 'total'); } catch { throw invalid('protocol'); }
+  if (total !== null && rows.length && (input.pageNo - 1) * input.pageSize + rows.length > total) throw invalid('protocol');
+  if (rows.some(row => object(row) && row.role === 9)) throw invalid('scope_unresolved');
+  if (input.orgRoles.length) {
+    const roles = input.orgRoles.flatMap(role => role === 2 ? [2001, 2002] : [role]);
+    if (rows.some(row => object(row) && Number.isSafeInteger(row.role) && row.role >= 0 &&
+        !roles.includes(row.role))) throw invalid('scope_unresolved');
+  }
+  try {
+    const units = rows.map(row => projectUnit(row, input.include));
+    if (new Set(units.map(unit => unit.kdtId)).size !== units.length) throw new TypeError('Duplicate unit');
+    const output = { data: { units, pagination: { pageNo: data.page_num, pageSize: data.page_size,
+      ...(total === null ? {} : { total }), hasMore: total === null ? null : input.pageNo * input.pageSize < total } } };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch {
+    throw invalid('protocol');
+  }
+}
+
+async function execute(input, preview) {
+  const scope = { kdtId: input.kdtId };
+  const { read, binding } = await createBoundShopQuery(scope, command, 'unit-basic');
+  if (binding.data.role !== 1) {
+    throw reject('scope_unresolved', 'unit-basic', scope, 'sent', binding.facts);
+  }
+  const request = preview.requests[1];
+  const { data, facts } = await read(request.path, request.body, request.stage);
+  return project(data, input, facts);
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('仅从当前连锁总部查询一页下级组织，不含三方 CRM 节点')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '当前总部正安全整数；默认上下文 shopId，不可跨总部')
+    .option('--page-no <n>', '页码 1..2147483647，每次仅一页', '1')
+    .option('--page-size <n>', '每页容量 1..50', '20')
+    .option('--org-roles <codes>', '筛选组 CSV：2 门店/网店、3 独立仓、4 合伙人、6 分销供货店铺、7 前置仓')
+    .option('--include <modules>', '可选 address,departments,status,lifecycle；逗号分隔并去重')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览；零凭证、零网络')
+    .addHelpText('after', `
+筛选组 2 对应返回 orgRole=2001 门店或 2002 网店；筛选组不是响应角色枚举。
+未指定筛选时保留未知合法角色，始终排除 CRM 角色 9；异常返回 9 时整体失败，不过滤后沿用 total。
+基础绑定必须是当前总部且 role=1；绑定后只读一页，最多两次请求，不自动翻页或逐项补查。
+hasMore 由 pageNo * pageSize < total 计算；空页或短页不代表全局无记录。
+status 分别保留网店营业、门店营业和门店状态，不推导综合启停或详情 operationStatus。
+lifecycle.endsAt 固定 UTC+08:00 北京时间 YYYY-MM-DD HH:mm:ss.SSS，秒补 .000。
+API 两种有依据的秒文本在内部严格转换；缺失/非法时间不当作永久有效，未选择时不解析。
+地址仅含 address/county/countyId；部门数组不是完整部门树。本命令不提供店铺类型或 CRM 范围开关。
+真实执行需要总部上下文和同总部凭证；位置准入不代表店铺员工身份授权与权限隔离验收通过。
+无上下文仅显式合法目标可本地预览；失败 stdout 为空，不输出部分结果。
+契约：zan-saas schema org.unit.list
+示例：zan-saas org unit list --kdt-id 63077 --org-roles 2 --include departments,status --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const preview = previewFor(input);
+      validateCommandValue(schema, 'preview', preview);
+      const output = options.dryRun ? preview : await execute(input, preview);
+      console.log(JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'hq', createCommand: withTargetShopDefault(createCommand) };