本仓 2026-08-12 从 ssw main (192.168.1.18:13300/ssw/ssw-mvp) 的 dacli/ subpath 抽取,作为独立仓托管到 gitea:3000/ssw/dacli.git。 - 工作树为 ssw main dacli subpath 最新版 (110 commit, 08-12) - 历史未带 ssw main 整体历史(避免大仓污染) - 此为新仓基线 commit,未来以本仓历史为主
4.6 KiB
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.tsL2.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(镜像 webcomponentMap.ts) 经loadComponentMap()取得,tagIcon来自 create.ts 内联JNPF_ICON_MAP(值同步自 webcomponentMap.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) 类型 textareaJnpfInputTextareaJnpfTextareatag 漂移 (旧 tag 在 web 根本不存在) inputNumber...generator-inputNumber...generator-numbertagIcon 漂移 uploadJnpfUpload(无此控件) 幽灵项 — check-parsers 误命中导入按钮 value:'upload'修复: create.ts 的 tag 映射改为
loadComponentMap()消费src/data/component-map.json(镜像 webcomponentMap.ts, 60+ 项), 不再维护内联副本。tagIcon 内联映射同步自 web 并修正漂移。
权威优先级:
web/.../FormGenerator/src/helper/componentMap.ts— 平台源码, 最终权威dacli/src/data/component-map.json— 上者的镜像 (jnpfKey → tag)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。