校验库（Validate）定义编写指南¶

目标：Agent 直接生成/修改 workspace 自定义校验库。知识以本文为准。不写原理；不依赖外链。

术语：JAXB 根 validateRepositoryVO；产品「校验库 / 常用工具-校验库」；落盘后缀 .valid。是软件级**可复用字段校验**，供表单字段「校验库」勾选后写入 validatelibs。**不是**系统内置 checkEmpty_system，**不是**字段 validaterule，**不是**脚本库 .macro。

iScript：写 content 时先读 iscript-usage（含 GraalVM 差异）→ form.md#校验库validatelibs；本文只定 XML 与落盘。

挂到字段：勾选后的 id 写入 JsonTemplate validatelibs，见 generate-form-file「必填控制」。

产出物一览¶

部分	落盘	形态
自定义校验库	`valid/{名称}.valid`	单文件；JAXB 根 `validateRepositoryVO`；`id` 为根属性

storage/workspace/{软件名}.application/valid/{名称}.valid

路径相对 storage/workspace。样例：demo-basic.application/valid/校验字段不能为空.valid。

新建最低配置：

目录已存在：{软件}.application/valid/
写 {name}.valid：根 id、name、parentId=软件 id、非空 content（含 verify）、version（新建 0）、description（可空 CDATA）
在需要该规则的表单字段 validatelibs 中写入本文件根 id（可与系统库同数组）
rebuild-index + clear_cache，设计器字段「校验库」才能勾到

约定：

JAXB；根 validateRepositoryVO（不是 validate / repositoryVO）
id 在 根属性
脚本用 CDATA：content、description
文件名 = name + .valid；同软件 valid/ 下 name 不重名
name 默认中文业务标题（设计器勾选列表可见），除非用户明确指定其它语言
name 勿含 / % \（落盘替换为 =47/=37/=92）
parentId = 软件 id；样例常**不写** applicationid（靠路径归属）
**勿**放到 module/ 下；永远在应用级 valid/
扁平单文件，不是 {name}.valid/{name}.valid 目录型

1. 心智模型¶

软件 Application
  ├─ 系统校验库（平台内置，无 .valid）
  │     core.dynaform.form.formfield.validate.checkEmpty_system
  │     core.dynaform.form.formfield.validate.checkFieldUnique_system
  │
  └─ valid/*.valid          ← 本文；自定义，设计器可勾选
        │
        ▼ 字段「校验库」勾选
  JsonTemplate validatelibs: [ 系统标识…, "__自定义id" ]
        │
        ▼ 保存 / 提交 / instantvalidate
  按数组顺序执行：系统 lib + 各 .valid 的 verify(字段name, 字段discript)

概念	说明
系统默认空值库	`checkEmpty_system`：必填星号 + 空值拦截；不要再做一份同义 `.valid` 去替代它
自定义 `.valid`	可复用业务规则（条件必填、格式、跨字段等）
`validatelibs`	字段上的字符串数组；系统库写全限定名，自定义库写 `.valid` 根 id
`validaterule`	仅该字段一次性脚本；可复用规则一律本文件 + `validatelibs`
`.macro`	脚本库，根是 `repositoryVO`，入口不是 `verify`

2. 属性 → `.valid` XML¶

属性表¶

属性	XML	类型	默认/样例	说明
`id`	根属性	string	须生成	`__` + 短 UUID；即 `validatelibs` 记入值
`name`	子元素	string	—	必填；文件名；应用内唯一；设计器勾选显示名
`parentId`	子元素	string	—	= 软件 id
`applicationid`	样例常不落盘	string		API 侧 = 软件 id
`content`	CDATA	string	—	校验正文；必须定义 `function verify(name, description)`
`version`	子元素	int	`0`	新建 `0`
`description`	CDATA	string	可空	列表描述

基类 uri 运行时计算，一般不手写。

`id` 生成¶

统一规则：__ + 短 UUID。示例：__w1DsV5XNQ30qjzAGBjK。改 id 等于换勾选键，已挂该库的字段 validatelibs 须同步改。

完整 XML 样例（对齐 demo-basic）¶

路径：…/demo-basic.application/valid/校验字段不能为空.valid

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<validateRepositoryVO id="__w1DsV5XNQ30qjzAGBjK">
  <name>校验字段不能为空</name>
  <parentId>sOZu9kthmxyP8qQfq0e</parentId>
  <content><![CDATA[function verify(name, description){
    var val = getItemValueAsString(name);
    if(isBlank(val)){
        return description+"还没有填";
    }
}]]></content>
  <version>0</version>
  <description><![CDATA[]]></description>
</validateRepositoryVO>

无条件必填请挂系统 checkEmpty_system，不要复制本样例去替代系统库。本样例只说明 .valid 形态与 verify 入口。

3. `content`：`verify(name, description)`¶

平台按字段调用 verify，传入：

参数	含义
`name`	当前字段 `name`（英文标识）
`description`	当前字段显示名（`discript`）

契约：

结果	返回
失败	提示字符串（页面展示）
成功	不 `return`，或 `return ""` / `return;`

入口例外（相对表单字段 IIFE 硬规则）：content **必须**是引擎可调用的具名函数 function verify(name, description) { ... }，**禁止**把整段包成 IIFE（否则无法作为校验库入口）。函数体内仍遵守 GraalVM：=== / !==、s.length、禁止顶层裸 return（return 只写在 verify 内）。

可用 API 与表单字段脚本相同（getItemValueAsString、isBlank、queryBySQL 等）。可读取**其它字段**做条件校验。

条件必填示例（自定义库）¶

function verify(name, description) {
  var t = getItemValueAsString("leaveType");
  if (t !== "病假") {
    return "";
  }
  var val = getItemValueAsString(name);
  if (isBlank(val)) {
    return description + "不能为空";
  }
  return "";
}

把该库勾到「附件」字段：仅请假类型为病假时拦截空附件。

4. 挂到表单字段（validatelibs）¶

JsonTemplate（showType=new）：

"validatelibs": [
  "core.dynaform.form.formfield.validate.checkEmpty_system",
  "__w1DsV5XNQ30qjzAGBjK"
]

类型	数组元素
系统空值/必填	`core.dynaform.form.formfield.validate.checkEmpty_system`
系统唯一（仅普通 TLK 表单）	`core.dynaform.form.formfield.validate.checkFieldUnique_system`
自定义	本文件根 `id`（不是 `name`、不是文件路径）

旧 HTML 表单可能把 validatelibs 写成单个 id 字符串；新建 JsonTemplate 必须用数组。多个库按数组顺序执行。

字段勾选入口：设计器该字段属性「校验库」。Agent 落盘时直接写 validatelibs，效果等同勾选。

5. 与系统库、validaterule 的分工¶

需求	做法
无条件必填（红 `*` + 空保存拦截）	只挂系统 `checkEmpty_system`；不写同义 `.valid`，不用 `worklimitchecked`
可复用业务/条件校验	新建 `.valid` → `validatelibs` 追加其 `id`
仅某一字段一次性规则	该字段 `validaterule` IIFE
映射表单编码唯一	禁止 `checkFieldUnique_system`；用 `validaterule` + 保存前置 `queryBySQL`（见 iscript-usage/form.md）

6. 收尾¶

落盘 .valid 后：

rebuild-index（url.index 须有 id=/…/valid/{name}.valid）
clear_cache
在目标字段 validatelibs 写入该 id（若本步未改表单，到设计器勾选）

不投递 .create_form_table（校验库不建动态表）。

附录 A：常见失败¶

现象	原因
设计器勾选列表没有	未 rebuild 索引 / 未 clear_cache / 文件不在 `valid/`
勾了不生效	`validatelibs` 写了 name 或路径，而不是根 `id`
根元素错误	必须 `validateRepositoryVO`（勿写成 `repositoryVO` / `validate`）
id 写成子元素	改为根属性
整段 IIFE	引擎调不到 `verify`
无条件必填无星号	只挂了自定义空值库，没挂系统 `checkEmpty_system`
放进 module	移到应用级 `valid/`
与 `.macro` 混淆	脚本库根是 `repositoryVO`，不是校验库

附录 B：生成检查清单¶

路径：storage/workspace/{软件}.application/valid/{name}.valid（扁平单文件）
根 <validateRepositoryVO id="__…">；name = 文件名去后缀；parentId = 软件 id
content CDATA 含 function verify(name, description)；失败返回字符串；成功空返回
version 有值（新建 0）；description 用 CDATA
同应用 name 不冲突；字段 validatelibs 记 id
无条件必填另挂系统 checkEmpty_system，不拿本库替代
rebuild-index + clear_cache