Files
dacli/docs/components.md
T
sswandClaude 3f1cb3a03b feat(dacli): JNPF7 验证闭环 Stage 0 + P0-6 preview + workflow canvas 回归修复
Stage 0 (验证基础设施):
- 5 层验证工具链 (tools/) + JSON Schema + validate-baseline.sh CI gate
- P0-9: components-whitelist.yaml 单一来源 + parseFlowXml 消漂移 (create.ts tag 改消费 component-map.json)
- E-2: docs/components.md 文档化 6 个 pass-through 组件
- P1-16: validate-baseline 接入 quality-gate.sh
- L3 回归测试 (bs117 / bpmn-bs / antipattern-output) + mock LLM 库

P0-6 (user-in-the-loop):
- form create --ai --preview: 提交前渲染字段表格 (CJK 对齐) + TTY 交互确认 (_preview.ts)

workflow canvas 回归修复 (v0.22+ SSW 迁移引入):
- parseFlowXml 命名空间无关 (flowNodes 缺口)
- _autoLayout 无 DI 时合成完整 BPMNDiagram+Shape+Edge + bpmn2 归一化 (canvas 缺口)
- 真实后端 + 浏览器设计器验证画布渲染; 详见 jnpf7-analysis §14

quality-gate 全绿: tsc 0 · vitest 483 · doc:check · baseline L1-L5

Co-Authored-By: Claude <[email protected]>
2026-07-27 12:49:44 +08:00

4.6 KiB

dacli 组件处理说明 (components.md)

P0-9 / E-2 产出 (2026-07-27) — 文档化 dacli 对 JNPF 表单控件的处理策略, 尤其是 6 个 pass-through (透传) 组件的行为与理由。

单一来源: ../config/components-whitelist.yaml (29 组件覆盖清单, 被 tools/check-parsers.ts L2.2 读取)


1. 三层组件白名单

层 来源 数量 说明
JNPF7 AI 白名单 jnpf7/.../AiConstants.GEN_MODEL_COMPNENT 23 后端 AI 建表允许输出的 fieldComponent
dacli 扩展 dacli 自行支持 +6 cascader / table / relationForm / relationFormAttr / depSelect / upload(别名)
合计 (L2.2 清单) config/components-whitelist.yaml 29 23 handled + 6 pass-through

JNPF7 权威白名单 (AiConstants.java):

input textarea inputNumber switch radio checkbox select datePicker timePicker
uploadFile uploadImg colorPicker rate slider editor
organizeSelect posSelect userSelect roleSelect areaSelect signature sign location

2. handling 分类

  • handled (23) — dacli 在 create.ts (buildColumnListEntry / buildSearchListEntry) 显式构建 tag / tagIcon / 基础 props;tag 从权威 src/data/component-map.json (镜像 web componentMap.ts) 经 loadComponentMap() 取得,tagIcon 来自 create.ts 内联 JNPF_ICON_MAP (值同步自 web componentMap.ts)。
  • pass-through (6) — dacli 不特殊构建其专属 props,列表/查询列走 fallback (JnpfInput / icon-ym icon-ym-generator-input)。原因见下表。

3. 6 个 pass-through 组件

jnpfKey web tag 类别 不特殊处理的理由
relationFormAttr JnpfRelationFormAttr 子表单属性变体 依附于 relationForm 的属性字段, 使用率极低; 需要时随主 relationForm 一并配置
organizeSelect JnpfOrganizeSelect 组织选择器 常见, 但 dacli 现有路径按 depSelect (部门) 归一化处理; 专属 props (选择层级/多选) 未建模
posSelect JnpfPosSelect 职位选择 低使用; 依赖 sys 职位实体, 无业务表单常规需求
roleSelect JnpfRoleSelect 角色选择 低使用; 依赖 sys 角色实体
areaSelect JnpfAreaSelect 省市区选择 低使用; 三级联动 props 复杂, 收益低
location JnpfLocation 地理位置 罕见; 依赖地图组件 + 坐标存储

pass-through 的实际影响

  • AI 建表: 若 LLM 输出上述 jnpfKey, dacli 会把该字段当普通 input 列渲染 (列表能显示原始值), 不会报错, 但设计器中不会呈现该控件的专属交互。
  • 风险等级: 低 — 这 6 个控件在典型业务表单 (CRUD/审批/报名) 中出现频率极低。
  • 升级路径: 若某 appCode 确需其一, 应在 create.ts 的 JNPF_ICON_MAP + 相应 smart_props 中补齐其专属 props, 并在 components-whitelist.yaml 把 handling 改为 handled — L2.2 会自动校验。

4. tag 映射的单一来源 (0 复刻 0 漂移)

历史教训 (P0-9 修复): create.ts 曾内联一份 14 项 JNPF_TAG_MAP 硬编码副本, 与权威 component-map.json 漂移:

jnpfKey 旧内联 (错) 权威 (web) 类型
textarea JnpfInputTextarea JnpfTextarea tag 漂移 (旧 tag 在 web 根本不存在)
inputNumber ...generator-inputNumber ...generator-number tagIcon 漂移
upload JnpfUpload (无此控件) 幽灵项 — check-parsers 误命中导入按钮 value:'upload'

修复: create.ts 的 tag 映射改为 loadComponentMap() 消费 src/data/component-map.json (镜像 web componentMap.ts, 60+ 项), 不再维护内联副本。tagIcon 内联映射同步自 web 并修正漂移。

权威优先级:

  1. web/.../FormGenerator/src/helper/componentMap.ts — 平台源码, 最终权威
  2. dacli/src/data/component-map.json — 上者的镜像 (jnpfKey → tag)
  3. dacli/config/components-whitelist.yaml — 29 组件覆盖清单 + 文档冗余 (tag 冲突以 #2 为准)

5. 校验

# L2.2 覆盖校验 (读 config/components-whitelist.yaml)
npx tsx tools/check-parsers.ts        # 期望: 23/29 handled + 6/6 pass-through documented, exit 0

# 全量 baseline
bash scripts/validate-baseline.sh

pass-through 组件缺引用是已文档化的预期行为, L2.2 不判为失败; 只有 handling: handled 的组件丢失引用 (真正的覆盖回归) 才 exit 1。