校验规则管理#

核心概念#

text

校验场景 (ValidateScene)
  └─ 1:N 校验规则组 (ValidateRuleGroup)
           └─ 1:N 校验规则 (ValidateRule)

状态： draft（草稿）/ enabled（启用）/ disabled（禁用）

---

初始化（首次使用必做）#

在使用任何命令前， 先检查 CLI 是否就绪：

bash

npx vr help 2>/dev/null || (cd <skill目录> && npm install)

如果 npx vr help 无输出或报错，说明还未初始化，执行：

bash

cd /path/to/validation-rule-management
npm install

完成后即可在任意目录通过 npx --prefix /path/to/validation-rule-management vr <action> 调用，或直接在 skill 目录下用 npx vr <action>。

---

配置#

方式 1 — 环境变量（推荐，适合脚本/CI）

bash

export VALIDATE_BASE_URL=http://global-masterdata-http.default.yf-bw-test-2.test.51baiwang.com
export VALIDATE_TOKEN=your-token-here

方式 2 — config.json（放在项目根目录或 skill 目录）

json

{
  "baseUrl": "http://global-masterdata-http.default.yf-bw-test-2.test.51baiwang.com",
  "token": "your-token-here"
}

---

命令速查#

所有命令统一格式： npx vr <action> [--key value ...] 值含空格时 shell 自动处理，含 = 等特殊字符时用 --json '{...}'

规则组#

bash

npx vr create-rule-group  --groupName "基础信息校验组" --orderNum 1 [--description "描述"]
npx vr query-rule-groups  [--groupName "关键字"] [--pageNum 1] [--pageSize 10]
npx vr update-rule-group  --id 1 --groupName "新名称" --orderNum 2
npx vr delete-rule-group  --id 1

规则#

bash

npx vr create-rule  --groupId 1 --objectId Invoice --countryCode CN \
                    --ruleCode CN-SELLER-001 --ruleName "卖方名称必填" \
                    --ruleType required [--fieldKey sellerName] [--errorMessage "{field}不能为空"]

npx vr query-rules  [--groupId 1] [--status enabled] [--countryCode CN] [--pageSize 20]
npx vr enable-rule  --id 42 --status enabled|disabled
npx vr delete-rule  --id 42

场景#

bash

npx vr create-scene  --sceneCode CN_VAT_SPECIAL --sceneName "中国增值税专票场景" \
                     [--errorStrategy stop_on_error|continue_all]

npx vr query-scenes  [--sceneCode CN_VAT] [--status enabled] [--pageSize 10]
npx vr enable-scene  --id 10 --status enabled|disabled
npx vr delete-scene  --id 10

---

目录结构#

text

validation-rule-management/
├── SKILL.md
├── package.json              # 定义 bin: { "vr": "./cli.js" }
├── cli.js                    # 入口：解析 action → 路由到对应命令模块
├── commands/                 # 按业务域划分的命令模块
│   ├── scenes.js             #   场景操作
│   ├── rule-groups.js        #   规则组操作
│   └── rules.js              #   规则操作
├── lib/                      # 基础设施
│   ├── api-client.js         #   HTTP 客户端 + 配置加载
│   ├── arg-parser.js         #   命令行参数解析
│   └── utils.js              #   公共工具函数
└── references/               # 参考文档（按需读取）
    ├── data-model.md         #   完整 DTO 定义 + API 端点汇总
    └── examples.md           #   典型使用示例

查阅字段定义或 API 路径时，读取 references/data-model.md。

---

常见问题#

错误信息原因解决npx vr 无响应未执行 npm install在 skill 目录执行 npm install未找到配置没有环境变量或 config.json设置环境变量或创建配置文件缺少必填参数参数不完整运行 npx vr help 查看必填项业务错误token 失效或权限不足刷新 token，确认 appId 正确