Files
dacli/docs/decisions/0010-simulation-registration-form.md
T
sswandClaude 61405e128d fix(dacli): resolve merge conflicts + add v2 architecture spec
- resolve 10 merge conflicts across 4 files (app/init, dict/typecreate, form/create, webapi/_defhttp)
- fix syntax errors in typecreate.ts (commented-out if block)
- add ADR-0010: dacli v2 self-correcting CLI architecture design
- add simulation test comparing v1 vs v2 behavior

Co-Authored-By: Claude <[email protected]>
2026-07-20 10:11:41 +08:00

11 KiB
Raw Blame History

dacli v2 模拟测试:比赛报名表

测试场景: AI 通过 dacli 创建一个"比赛报名表" 输入特征: 6 字段、2 个 FK、1 个 datetime、1 个 int+dict、enCode 含 -、fullName 含 - 目标: 对比 dacli v1(现在)vs dacli v2(设计)的行为


输入

AI 发出命令(含 AI 生成 schema):

dacli form create \
  --ai='[{
    "tableTitle": "比赛报名",
    "tableName": "registration",
    "isMain": true,
    "fields": [
      {"fieldTitle": "用户", "fieldName": "f_user_id", "fieldDbType": "bigint", "fieldComponent": "inputNumber"},
      {"fieldTitle": "比赛", "fieldName": "f_competition_id", "fieldDbType": "bigint", "fieldComponent": "inputNumber"},
      {"fieldTitle": "团队名称", "fieldName": "f_team_name", "fieldDbType": "varchar", "fieldComponent": "input"},
      {"fieldTitle": "报名时间", "fieldName": "f_start_time", "fieldDbType": "datetime", "fieldComponent": "timePicker"},
      {"fieldTitle": "状态", "fieldName": "f_status", "fieldDbType": "int", "fieldComponent": "inputNumber"},
      {"fieldTitle": "备注", "fieldName": "f_remark", "fieldDbType": "text", "fieldComponent": "textarea"}
    ]
  }]' \
  --fullName="比赛报名-表" \
  --enCode="registration-form" \
  --autoRelease

注意这个输入的问题(真实 AI 输出常见):

  1. f_user_id / f_competition_id: FK 字段配了 inputNumber ← 应配 relationForm
  2. f_start_time (datetime): 配了 timePicker ← 应配 datePicker
  3. f_status (int + dictType): 配了 inputNumber ← 应配 select
  4. enCode: 含 - ← 后端 400
  5. fullName: 含 - ← 后端校验失败

对比

dacli v1 行为(现在)

$ dacli form create --ai='[...]' --fullName="比赛报名-表" --enCode="registration-form" --autoRelease

[AI] NCPF backend 生成 schema...
[AI] ✓ AI 生成 1 个主表, 6 个字段

[buildFormData] ✓ 构建 formData...

loadVisualDev.create  formId=...
  [BS-新38] enCode 含 `-`, auto strip: registration-form → registrationform
  [BS-新52] fullName 含特殊符号, auto soften: 比赛报名-表 → 比赛报名·表

[preCheck] 表单预检查:
  [step 0 基础信息] enCode=registrationform ✓   fullName=比赛报名·表 ✓
  [step 1 平台唯一性] enCode 不冲突 ✓
  [step 2 字段校验]
    [WARN] f_user_id: f_*_id 字段应配 relationForm, 当前 inputNumber
            修复: 显式 jnpfKey=relationForm + dictType=<关联表enCode>
    [WARN] f_competition_id: f_*_id 字段应配 relationForm, 当前 inputNumber
            修复: 显式 jnpfKey=relationForm + dictType=<关联表enCode>
    [WARN] f_start_time: datetime 应配 datePicker, 当前 timePicker
            修复: jnpfKey=datePicker, format="yyyy-MM-dd HH:mm:ss"
    [WARN] f_status: int + dictType 应配 select, 当前 inputNumber
            修复: jnpfKey=select
  [step 3 字段名] ✓ 无中文/保留字

[blindspot guard] 检测:
  [BS-54] f_user_id jnpfKey=inputNumber 建议改为 relationForm
           因 f_*_id 关联字段需 relationForm 组件, 否则列表显示 ID 数字
  [BS-54] f_competition_id jnpfKey=inputNumber 建议改为 relationForm
  [BS-60] f_start_time 缺 format, 建议 datePicker + format="yyyy-MM-dd HH:mm:ss"
  [BS-61] f_status int+dictType jxcjcompetitionstatus 但 jnpfKey 不是 select

✓ 表单创建: id=847134936094737350  enCode=registrationform

━━ 创建成功但需手动修正 4 处:
  1. f_user_id → relationForm (关联 user)
  2. f_competition_id → relationForm (关联 competition)
  3. f_start_time → datePicker (format=yyyy-MM-dd HH:mm:ss)
  4. f_status → select (dictType=jxcjcompetitionstatus)

  运行: dacli form update 847134936094737350 --fields='[修正后的字段JSON]'

统计:

  • stdout 行数: ~35 行
  • 表单能创建: ✓
  • 数据能保存: ✗(f_user_id / f_competition_id 存的是数字,POST 报 "Field cannot be empty" 如果物理列是 varchar FK)
  • AI 需要: 读 35 行 → 理解 4 个 WARN → 手写修正 JSON → 跑 form update → 可能还要 form import --autoTable 重建物理表

dacli v2 行为(设计)

$ dacli form create --ai='[...]' --fullName="比赛报名-表" --enCode="registration-form" --autoRelease

✓ registration_form 已创建 (id=8471...)  修正 6 处  建议 1 项  [3.2s]
  测试: dacli test run --formId=8471...
  详情: dacli log --last

AI 看到的: 1 行。表单已可用。

如果需要了解更多:

$ dacli log --last
━━ dacli form create — 2026-07-20 14:30:52

  结果: ✓ 成功
  表单: registration_form (id=8471...)  6 字段 / 2 子表 / 1 主表

━━ 修正 6 处:
  [silent] enCode: registration-form → registration_form
  [silent] fullName: 比赛报名-表 → 比赛报名·表

  ✅ f_user_id:        inputNumber → relationForm (关联 user)
     回滚: dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'
  ✅ f_competition_id: inputNumber → relationForm (关联 competition)
     回滚: dacli form update 8471... --set='[{"field":"f_competition_id","jnpfKey":"inputNumber"}]'
  ✅ f_start_time:     timePicker → datePicker (format=yyyy-MM-dd HH:mm:ss)
     回滚: dacli form update 8471... --set='[{"field":"f_start_time","jnpfKey":"timePicker"}]'
  ✅ f_status:         inputNumber → select (dictType=jxcjcompetitionstatus)
     回滚: dacli form update 8471... --set='[{"field":"f_status","jnpfKey":"inputNumber"}]'

━━ 建议 1 项:
  💡 f_competition_id: relationForm 回显列可选
     [1] f_competition_name (比赛名称) ← 默认
     [2] f_competition_code (比赛编码)
     调整: dacli form columnOptions 8471... --field=f_competition_id --columns='["f_competition_name","f_competition_code"]'

━━ 原始请求/响应用于调试:
  dacli log --last --detail

统计:

  • stdout 行数: 6 行
  • 表单能创建: ✓
  • 数据能保存: ✓(FK 字段已修正为 relationForm,物理表列正确)
  • AI 需要: 看 1 行确认成功 → 跑 test → 根据建议决定是否调整 columnOptions
  • 如果修正错了: 复制一条回滚命令

关键差异总结

dacli v1(现在) dacli v2(设计)
AI 阅读行数 ~35 ~6
表单可运行 ✗(FK 未设 relationForm 存数据报错) ✓
AI 操作步骤 创建 → 读 WARN → 手写 JSON → 修正 → 可能重建表 创建 → 测试
回滚 手动重建表单 一行命令
信息查找 grep stdout 历史 dacli log --last 结构化查询
开发人员体验 需要深入理解 JNPF 组件体系 创建即用,不满意可回滚

日志文件示例

{
  "timestamp": "2026-07-20T14:30:52.123+08:00",
  "command": "form create",
  "duration_ms": 3200,
  "result": "success",
  "summary": {
    "enCode": "registration_form",
    "formId": "847134936094737350",
    "fields_count": 6,
    "silent_fixes": 2,
    "assertive_fixes": 4,
    "suggestions": 1
  },
  "silent_fixes": [
    {
      "id": "S1",
      "field": "enCode",
      "original": "registration-form",
      "fixed": "registration_form",
      "reason": "含特殊字符 `-`,后端校验会 400"
    },
    {
      "id": "S2",
      "field": "fullName",
      "original": "比赛报名-表",
      "fixed": "比赛报名·表",
      "reason": "含特殊符号 `-`,后端校验不允许"
    }
  ],
  "assertive_fixes": [
    {
      "id": "A1",
      "field": "f_user_id",
      "from": {"jnpfKey": "inputNumber"},
      "to": {"jnpfKey": "relationForm", "modelId": "user_form_id_xxx", "dictType": "user"},
      "rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_user_id\",\"jnpfKey\":\"inputNumber\"}]'",
      "confidence": "high",
      "reason": "f_*_id 字段名 + 找到匹配表单 user"
    },
    {
      "id": "A1",
      "field": "f_competition_id",
      "from": {"jnpfKey": "inputNumber"},
      "to": {"jnpfKey": "relationForm", "modelId": "competition_form_id_xxx", "dictType": "competition"},
      "rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_competition_id\",\"jnpfKey\":\"inputNumber\"}]'",
      "confidence": "high",
      "reason": "f_*_id 字段名 + 找到匹配表单 competition"
    },
    {
      "id": "A2",
      "field": "f_start_time",
      "from": {"jnpfKey": "timePicker"},
      "to": {"jnpfKey": "datePicker", "format": "yyyy-MM-dd HH:mm:ss"},
      "rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_start_time\",\"jnpfKey\":\"timePicker\"}]'",
      "confidence": "extremely_high",
      "reason": "datetime 类型应配 datePicker,timePicker 只能选时间不能选日期"
    },
    {
      "id": "A4",
      "field": "f_status",
      "from": {"jnpfKey": "inputNumber"},
      "to": {"jnpfKey": "select", "dictType": "jxcjcompetitionstatus"},
      "rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_status\",\"jnpfKey\":\"inputNumber\"}]'",
      "confidence": "high",
      "reason": "int 类型且 dictType=jxcjcompetitionstatus 已存在,应配 select 下拉框"
    }
  ],
  "suggestions": [
    {
      "id": "G3",
      "field": "f_competition_id",
      "message": "relationForm 回显列可选",
      "current": ["f_competition_name"],
      "available": [
        {"field": "f_competition_name", "label": "比赛名称"},
        {"field": "f_competition_code", "label": "比赛编码"}
      ],
      "action": "dacli form columnOptions 847134936094737350 --field=f_competition_id --columns='[\"f_competition_name\",\"f_competition_code\"]'"
    }
  ]
}

回滚场景演练

假设 A1 规则把 f_user_id 错误地关联到了 user 表(实际应该关联 sys_user 表):

$ dacli form create --ai "..."

✓ registration_form 已创建 (id=8471...)  修正 6 处  建议 1 项
  测试: dacli test run --formId=8471...
  详情: dacli log --last

$ dacli log --last --detail | grep "f_user_id" -A3

  ✅ f_user_id: inputNumber → relationForm (关联 user)
     回滚: dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'

# 开发人员发现关联错了 → 回滚 + 重指定
$ dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'
# 或者直接指定正确的关联表:
$ dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"relationForm","dictType":"sys_user"}]'

开发人员体验: 复制日志里的一行回滚命令 → 跑。10 秒内修正,不需要重建表单。


结论

问题 dacli v1 dacli v2
知识在哪里 7 个防御文件 + CLAUDE.md + ssw-loop registry.ts(单一源)
AI 看什么 ~35 行混合输出 ~6 行结果摘要
检测到问题怎么办 WARN → 期望 AI 读+改+重试 自动修 → 通知+回滚命令
表单能用吗 不一定 保证可运行
修错了怎么办 不存在(没修) 一行回滚命令
细节去哪了 全部 stdout 结构化日志文件

核心变化: dacli 从"检测+提醒"变成"修正+回滚"。AI 不需要学 JNPF 规则,只需要确认结果。