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]>
95 lines
4.6 KiB
Markdown
95 lines
4.6 KiB
Markdown
# dacli 组件处理说明 (components.md)
|
|
|
|
> **P0-9 / E-2 产出 (2026-07-27)** — 文档化 dacli 对 JNPF 表单控件的处理策略,
|
|
> 尤其是 6 个 **pass-through (透传)** 组件的行为与理由。
|
|
>
|
|
> 单一来源: [`../config/components-whitelist.yaml`](../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. 校验
|
|
|
|
```bash
|
|
# 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。
|