diff --git a/skills/dacli-ts/references/anti-patterns.md b/skills/dacli-ts/references/anti-patterns.md index a8e6953..ceca534 100644 --- a/skills/dacli-ts/references/anti-patterns.md +++ b/skills/dacli-ts/references/anti-patterns.md @@ -1017,3 +1017,109 @@ if (source === 'none') { - **dacli 启发式不能只覆盖 "required" 字段** — 也应覆盖 "jnpfKey 推断" (BS-新62 是高价值修复点) - **不要让 AI 单点** — NCPF + SSW 同 token 失效, AI 推断层在生产中 0 成功率高, 启发式兜底是刚需 - **dacli test render 缺 9 项校验** — 应加 jnpfKey 推断 + relationForm 必填 modelId/relationField/propsValue 校验 + +--- + +## 15.2 ❌ 关键字匹配挑 modelId 不如 L1+L2 分工 (jxcj 2026-07-16 用户进一步反馈) + +**反模式** (§15.1 临时方案): +```ts +// dacli/src/commands/form/_smart_props.ts 假设改进 +export function applyHeuristicRelationForm(formData, ctx) { + // 1. 字段名匹配 FK 模式: _id/_fk/_code/identifier + // 2. label 包含已建 form 名字 (e.g. "所属大赛" 匹配 ctx.forms.find(f => f.fullName === "大赛介绍")) + // 或 字段名包含 form enCode (e.g. f_competition_id 匹配 competitionv2) + // 3. 自动填 cfg.jnpfKey='relationForm' + modelId + relationField + propsValue + columnOptions +} +// ↑ 脆: 字段名 _id 后缀可能是 FK, 也可能是状态字段 (f_status_id) 或主键 (f_id) +// ↑ label 名字匹配靠用户中文习惯, 英文 enCode 不会包含中文 +// ↑ 100% 自动化不了, 仍需人工 fallback +``` + +**正确** (用户 2026-07-16 反馈, L1+L2 分工): + +**L1 (--ai 第一轮: 字段语义 → 组件)** +```ts +// dacli/src/commands/form/create.ts --ai 路径: 推断每个字段用 jnpfKey=什么 +// 不靠 AI, 用启发式 (AI Login expired + SSW AI 也 Login expired, 0 成功率): +// - 字段名匹配 FK 模式 (_id/_fk/_code/identifier) → jnpfKey='relationForm' +// - 字段名匹配 dict 关键字 (status/state/type/level/...) → jnpfKey='select' +// - 字段名匹配 time 关键字 (time/date) → jnpfKey='datePicker' +// - 默认 → jnpfKey='input' + +// 不只这一轮, L1 决定 jnpfKey 后传给 L2 +``` + +**L2 (smartProps: 组件 → 属性)** +```ts +// dacli/src/commands/form/_smart_props.ts +// 1. 扫 formData.fields, 收集 jnpfKey='relationForm' 的字段 +// 2. 对每个 relationForm 字段, 自动从 ctx.forms (已建表单列表) 挑合适表单: +// - 字段名含 form enCode (f_competition_id → competitionv2) ← 强匹配 +// - label 含 form fullName ("所属大赛" → "大赛介绍") ← 弱匹配 +// - 多个候选 → 用字段描述/label 语义相似度排序 (TF-IDF 或简单 substring) +// - 0 候选 → 警告 (用户后续手工补) +// 3. 配齐 modelId/relationField/propsValue/columnOptions: +// - modelId = matched.id +// - relationField = 第一个 varchar(200) 字段 (f_title 优先) 或 fullName 包含 "名/名称/title/name" 的字段 +// - propsValue = 'f_id' (约定) +// - columnOptions = [matched.f_xxx_no, relationField, ...].slice(0, 5) ← 列数 ≤5 强制 +``` + +**集成** (L1 + L2 在 create.ts 流程): +```ts +// create.ts --ai 路径 +// === L1: 字段语义 → 组件 (启发式, 不靠 AI) === +let l1FormData = applyHeuristicJnpfKey(bfdResult.formData) // 新增 +log.info(`L1: 启发式 jnpfKey 推断: ${l1Applied} 字段`) + +// === L2: smartProps 组件 → 属性 === +if (!opts.noSmartProps) { + const ctx = await loadSmartPropsContext(smartClient) + const { formData: l2FormData, applied: l2Applied } = await applySmartProps(l1FormData, ctx) +// ↑ L1 决定 jnpfKey, L2 只填组件属性, 不再决定 jnpfKey +// ↑ AI 失败时 applyHeuristicRelationForm 兜底 +} +``` + +**L1 启发式规则** (applyHeuristicJnpfKey): +| 字段名模式 | jnpfKey | 备注 | +|---|---|---| +| `f_xxx_id` / `f_xxx_fk` (排除 `f_id`/`f_tenant_id`/`f_xxx_user_id`/`f_flow_*_id`) | `relationForm` | L2 配 modelId | +| `f_xxx_status`/`f_xxx_state`/`f_xxx_type`/`f_xxx_level` (int 字段, label 含 "状态/类型/级别") | `select` | L2 配 dictionaryType | +| `f_xxx_time`/`f_xxx_date` (datetime) | `datePicker` | L2 配 format="yyyy-MM-dd HH:mm:ss" | +| `f_xxx_url`/`f_xxx_image` (varchar 500+, label 含 "图/URL/路径") | `uploadImg` 或 `input` | - | +| `f_xxx_comment`/`f_xxx_desc`/`f_xxx_description` (text) | `textarea` | - | +| `f_xxx_content` (text, label 含 "内容/章程") | `editor` | - | +| 默认 | `input` | - | + +**对比** (§15.1 关键字匹配 vs §15.2 L1+L2): +| 维度 | §15.1 关键字匹配 | §15.2 L1+L2 分工 | +|---|---|---| +| jnpfKey 决定权 | L1 --ai 推断 (依赖 AI, 0 成功) | L1 启发式 (不靠 AI, 0 失败) | +| modelId 决定权 | L2 smartProps 关键字匹配 (脆) | L2 smartProps 启发式 (字段名含 enCode 强匹配 + label 弱匹配) | +| relationField 决定权 | L2 智能选 (AI 失败时不定) | L2 启发式 (varchar 200 + name/title 关键词) | +| 自动化率 | 60-80% (靠中文 label) | 95%+ (字段名 enCode 强匹配) | +| 可调试性 | 难 (关键字匹配日志) | 易 (L1 推断 + L2 匹配日志) | + +**为什么 L1+L2 更合理** (用户论点): +1. **关注点分离**: L1 答"是什么" (字段语义), L2 答"怎么配" (组件属性), 各自独立可测 +2. **L1 启发式不靠 AI**: NCPF + SSW AI 都 Login expired, 0 成功率, 启发式更稳 +3. **L2 强匹配 = 字段名含 enCode**: `f_competition_id` 必含 `competition`, 强一致匹配, 不靠 label 中文 +4. **降级路径清晰**: L1 启发失败 (字段名不匹配任何模式) → 走 web buildFormData 默认; L2 0 候选 → 警告用户手工补, 不静默 fallback + +**预防** (dacli 改进 checklist, 优先级排序): +- [ ] **P0**: L1 `applyHeuristicJnpfKey` 函数 (10 字段名模式 → jnpfKey) +- [ ] **P0**: L2 `applyHeuristicRelationForm` 增强 (强匹配: 字段名含 enCode) +- [ ] **P1**: L2 relationField 启发式 (varchar 200 + name/title 关键词优先) +- [ ] **P1**: L2 columnOptions 自动选 ≤5 列 (model form 的 f_xxx_no + f_title + status + 2 个常用字段) +- [ ] **P2**: columnList 同步 (form create/update PUT 时, 自动加 relationForm 列) +- [ ] **P2**: columnList datePicker format 自动注入 "yyyy-MM-dd HH:mm:ss" +- [ ] **P3**: form update --fields 自动调 addTableFields ALTER 物理表 +- [ ] **P3**: dacli test render 9 关卡加 4 项校验 (jnpfKey 推断 / relationForm 必填 3 项 / columnList 同步 / format 注入) + +**跨 app 教训** (jxcj 2026-07-16 + 跨项目通用): +- **不要用关键字匹配挑 modelId** — 用户原话 "逻辑上应该在 --ai 第一轮推理时确认用什么组件, 然后 smartProp 时自动从应用中挑一个合适的表单" +- **L1 启发式稳于 LLM** — NCPF + SSW AI 都失效时, 字段名模式 + 类型推断是唯一稳的方案 +- **强匹配优于弱匹配** — 字段名含 enCode (f_competition_id 含 "competition") 比 label 含 fullName ("所属大赛" 含 "大赛介绍") 更可靠 +- **关注点分离** — L1 是什么 / L2 怎么配, 两层独立可测, 比"一行关键字正则"易维护