Files
dacli/docs/decisions/0012-form-create-ai-relationform-fallback.md
T
ssw bbcdf9fab2 dacli: M2 实战固化 (jxcj 2026-07-20)
3 跨项目问题 + 修复 + 文档:

1. ADR 0011 — dm drop DB201 错误信息明确化
   - 旧: 表有数据时报 DB201 "The table has already been used" 误导用户
   - 新: catch DB201 输出修复指引 (TRUNCATE + ADR 0011 P1 待加 dm truncate 命令)
   - 文件: src/commands/dm/drop.ts + docs/cmd-review/dm.md + docs/decisions/0011

2. ADR 0012 — form create --ai relationForm 软降级
   - 旧: AI 生成 relationForm 缺三元组 (~40%) 触发 step machine 硬 FAIL
   - 新: validateFormData 软降级 — 三元组不全时自动改 jnpfKey='input' + 警告 (而非硬错)
   - 测试: 4/4 PASS (含缺 1/2/3 个三元组场景, 均软降级)
   - 文件: src/commands/form/_validate.ts + docs/cmd-review/form.md + docs/decisions/0012

3. ADR 0013 — menu create CurrentUser 缓存阻塞
   - 现象: menu create --formId 成功后 CurrentUser.menuList 不刷新, TC-B 阻塞
   - 修复: P1 待加 menu cache clear + menu create 后自动 invalidate
   - 兜底: test browser fallback 到 /jnpf_app_${appCode}/model/${formEnCode} 直接 URL
   - 文件: docs/cmd-review/menu.md + docs/decisions/0013

jxcj M2 重启 (2026-07-20) 实战产出, 跨项目通用 (testspace/developSystem/workSystem/dos 等)
详见 docs/jxcj/summary.md + docs/jxcj/learnings.md 阶段 4 段
2026-07-20 18:02:38 +08:00

4.7 KiB

0012-form-create-ai-relationform-fallback

日期: 2026-07-20 状态: Accepted 作者: claude-code (jxcj M2 重启实战) 前置: ADR 0001 (FK→relationForm 强制声明) 影响命令: dacli form create --ai

Context

dacli form create --ai "<description>" 走 NCPF backend LLM 生成字段 schema, 但 LLM 对 relationForm 字段的 modelId/propsValue/relationField 三元组生成不稳定:

  • 60% 覆盖率 (NCPF backend 自身文档): "关联" / "FK" / "外键" 关键词能触发
  • 40% 失败率: LLM 生成 jnpfKey: "relationForm" 但 modelId/propsValue/relationField 全空, 触发 dacli step machine 校验失败 (关联功能不能为空 / 存储字段不能为空 / 回显字段不能为空)

ADR 0001 要求 description 显式声明 relationForm 关联 <父表enCode> 显示字段 <字段名>, 实际验证 (jxcj M2 重启):

--ai="字段: f_competition_id (varchar relationForm 关联 competition form_id=848939189058667461 显示字段 f_competition_name)"
# 仍然失败: 3 errors, AI 把 relationField="f_competition_name" 丢了

根因: NCPF backend LLM 看不到父 form 的实际 formId 与字段, 只能从 description 推断, 推断失败率高。

当前绕路 (jxcj M2 实战): 2-step 模式:

  1. --ai 不提 FK 字段 → AI 生成 input 字段
  2. PG ALTER TABLE ADD COLUMN f_xxx_id varchar(50)
  3. dacli form update --fields='[{...jnpfKey:relationForm, modelId, propsValue, relationField...}]'

3 步完成, 可靠但繁琐。

Decision

改进 1 (dacli smartProps 兜底) - 现有 _smart_props.ts BS-18 已启发式注入 relationForm 三元组, 但覆盖率仅匹配 *_space / *_id 命名模式。扩展到:

  • 触发 *_id 命名 → 启发式找 existingEnCodes 表匹配, 自动注入三元组
  • 已存在但 modelId 空 → 用现有 enCode 列表模糊匹配 (*competition* → competition)
  • 不存在 → fallback: 把 jnpfKey: "relationForm" 降级为 jnpfKey: "input", 加警告日志
// dacli/src/commands/form/_relationForm_auto.ts 改进 (伪代码)
if (autoInjectFailed && jnpfKey === 'relationForm') {
  log.warn(`字段 ${vmodel} relationForm 自动注入失败, 降级为 input. 后续 form update --fields 可手动修复.`)
  return { ...field, __config__: { ...field.__config__, jnpfKey: 'input' } }
}

改进 2 (dacli step machine 软化) - 现状: relationForm 缺三元组 → hard FAIL. 改进: 软警告, 让 form create 通过 (用户后续 form update 修复):

// dacli/src/commands/form/_validate.ts 改进 (伪代码)
if (config.jnpfKey === 'relationForm' && (!e.modelId || !e.propsValue || !e.relationField)) {
  warnings.push({
    field: formId,
    message: `relationForm 三元组不全, 降级为 input. 修复: dacli form update --id=<id> --fields='[{...三元组...}]'`,
    code: 'VS-RELATION-INCOMPLETE-FALLBACK'
  })
  config.jnpfKey = 'input'  // 自动降级
}

改进 3 (dacli form update --fields 增强) - 现状 (ADR 0003): 加 FK varchar 字段不会 ALTER 物理表. 改进: 检测字段名 f_*_id (FK 模式) 且表无此列, 自动 ALTER ADD COLUMN:

// dacli/src/commands/form/update.ts 改进 (伪代码)
if (newField.__vModel__.match(/^f_\w+_id$/) && !tableHasColumn(tableName, newField.__vModel__)) {
  await loadDataModel.addTableField(dbLinkId, tableName, {
    field: newField.__vModel__, dataType: 'varchar', dataLength: '50', allowNull: 1
  })
}

Alternatives Considered

  1. 强制 description 写三元组 (当前 ADR 0001 路径): 实测覆盖率仍 ~60%, 不可靠
  2. AI 后处理加正则识别: 已做 (smartProps BS-18), 但扩展到 input 降级需谨慎 (可能误判)
  3. 改 NCPF backend prompt: jnpf 平台只读, 禁止改 (CLAUDE.md §代码修改权限)
  4. 完全删除 relationForm 自动生成: 让用户全部手动 form update --fields, 失去 AI 价值

Consequences

正面

  • 消除 relationForm 校验失败的硬阻塞
  • 2-step 模式可降为 1-step (--ai 描述不提 FK, AI 自动用 input, 后处理升级 relationForm)
  • 跨项目受益

负面

  • 软警告可能掩盖真实业务错误 (用户没看到 warning 直接发布, 后续才发现)
  • 自动降级增加复杂度, 需测试覆盖 (主表无 FK / 多层级 FK / FK 名字不规范等情况)

References

  • jxcj M2 重启: docs/jxcj/learnings.md 阶段 4 §M2 踩坑 3 (2-step form 创建)
  • ADR 0001: dacli/docs/decisions/0001-fk-relation-form-required.md
  • ADR 0003: dacli/docs/decisions/0003-form-update-fields-no-alter-table.md (form update --fields 不 ALTER, 改进 3 待解决)
  • 现有 dacli smartProps: dacli/src/commands/form/_relationForm_auto.ts
  • 现有 dacli validate: dacli/src/commands/form/_validate.ts