Files
dacli/docs/anti-patterns.md
T

19 KiB

dacli Anti-Patterns (Auto-Generated)

Source: dacli/src/commands/_anti_patterns.ts (single source of truth) Generator: scripts/gen-anti-patterns-md.sh DO NOT EDIT MANUALLY. Run bash scripts/gen-anti-patterns-md.sh to regenerate.

form create

AP-fc-1 [P0]

  • Wrong: f_user_id (BIGINT 必填, 未指定FK关联关系)
  • Right: f_user_id (BIGINT FK 必填 relationForm 关联 user 表 显示字段 f_user_name)
  • Rationale: AI 默认推成 inputNumber, 列表显示 ID 数字而非名称
  • Source: drift/R17
  • Cross-refs: decisions/0001-fk-relation-form-required

AP-fc-2 [P0]

  • Wrong: f_status (int 必填)
  • Right: f_status (int 字典 userstatus:0正常/1冻结, 必填 select 组件)
  • Rationale: int + dictType 不会自动转 select 组件 (BS-新117 限制 1)
  • Source: drift/R17
  • Cross-refs: decisions/0002-form-create-ai-4-limitations

AP-fc-3 [P1]

  • Wrong: f_create_time (datetime 必填)
  • Right: f_create_time (datetime 必填 datePicker 列 format=yyyy-MM-dd HH:mm:ss)
  • Rationale: 列缺 format 时显示 ISO 时间戳 (BS-新117 限制 2)
  • Source: drift/R17
  • Cross-refs: decisions/0002-form-create-ai-4-limitations

AP-fc-4 [P0]

  • Wrong: 1 句话建多表 (含 FK 字段)
  • Right: 拆步: 先建被关联表 (不含 FK), 再 form update --fields 补 FK
  • Rationale: 主表先建时 FK 字段无 modelId, step machine 校验失败
  • Source: drift/R17
  • Cross-refs: decisions/0007-dacli-form-ai-not-in-dependency

AP-fc-5 [P1]

  • Wrong: --tables 简化版 (缺 use*Permission 等关键字段)
  • Right: 传完整 JSON (含 usePermission/createPermission 等 16+ 字段)
  • Rationale: dacli 自动推导的 --tables 简化版会报 "Database exception"
  • Source: blindspots/BS-48

AP-fc-6 [P0]

  • Wrong: AI 描述未提 FK 处理
  • Right: AI 描述结尾加 "本表不建FK字段"
  • Rationale: 物理表缺 varchar FK 列, form POST 报 "Field cannot be empty"
  • Source: drift/R17
  • Cross-refs: decisions/0003-form-update-fields-no-alter-table

AP-fc-7 [P1]

  • Wrong: --enCode 含 - / _ / 空格 / 括号
  • Right: camelCase 无下划线, 例: tdsmyform / tdscompetition
  • Rationale: BS-56 正则 [一-龥a-z0-9]+ 严格, 不允许这些字符
  • Source: drift/R12 BS-新38

AP-fc-8 [P0]

  • Wrong: 建表后未跑 dacli form info 验证
  • Right: 必跑 dacli form info 验证 4 项 (字段数/jnpfKey/relationForm/required)
  • Rationale: BS-新117 4 限制入生产会报 "Field cannot be empty"
  • Source: drift/R17
  • Cross-refs: decisions/0002-form-create-ai-4-limitations

form update

AP-fu-1 [P0]

  • Wrong: form update --fields 加 FK 字段 (varchar)
  • Right: form import --autoTable 重建物理表 / dm drop + form delete + form create 重建
  • Rationale: form update --fields 不会 ALTER 物理表 (BS-新117 限制 4)
  • Source: drift/R12
  • Cross-refs: decisions/0003-form-update-fields-no-alter-table

AP-fu-2 [P1]

  • Wrong: --fields 字段名不带 F_ 前缀
  • Right: 所有字段名必带 F_ 前缀
  • Rationale: 列名缺 F_ 前缀, 列表显示异常
  • Source: drift/R12 column_drift

AP-fu-3 [P2]

  • Wrong: --fields 缺 category 字段
  • Right: 必传 category (用于菜单挂载)
  • Rationale: 菜单找不到对应 form
  • Source: blindspots/BS-新44

form info

AP-fi-1 [P1]

  • Wrong: 建表后未跑 form info 验证
  • Right: 必跑 dacli form info 检查字段数/jnpfKey/relationForm/required 4 项
  • Rationale: BS-新117 4 限制只能通过 form info 验证, 提前发现问题
  • Source: drift/R17

form delete

AP-fd-1 [P1]

  • Wrong: form delete 不带 --cascade
  • Right: 删 form 前必带 --cascade 删关联菜单/物理表
  • Rationale: 否则留下孤立菜单和物理表
  • Source: lessons/jxcj1

menu create

AP-mc-1 [P0]

  • Wrong: menu create --type=3 不传 moduleId
  • Right: 必传 --moduleId=<formId>
  • Rationale: 后端 400 (BS-drift-M-1)
  • Source: drift/R5
  • Cross-refs: decisions/0004-menu-create-type3-moduleid

AP-mc-2 [P0]

  • Wrong: menu create --formId + type=3
  • Right: 用 type=3 --urlAddress=model/<enCode> --moduleId=<formId>
  • Rationale: 走 Actions/Module 时 form schema 缺主表信息报 "主表不存在"
  • Source: blindspots/BS-50

AP-mc-3 [P1]

  • Wrong: 跨 app 引用未传 --urlAddress
  • Right: 传 --urlAddress=model/<formEnCode>
  • Rationale: SPA 找不到 form 路由 404
  • Source: drift/R5

dict typeCreate

AP-dt-1 [P0]

  • Wrong: dict typeCreate 不查就建
  • Right: 先 dacli dict dataList 看已有字典, 复用或加 <app>_ 前缀
  • Rationale: enCode 和 fullName 都查重 (全平台唯一, 跨 app)
  • Source: blindspots/BS-47
  • Cross-refs: decisions/0005-dict-typecreate-uniqueness

workflow create

AP-wc-1 [P0]

  • Wrong: workflow create --ai 不传 --startFormId
  • Right: 必传 --startFormId=<formId>
  • Rationale: 浏览器报 workFlowForm/undefined.vue
  • Source: blindspots/BS-E3
  • Cross-refs: decisions/0006-workflow-create-startformid

AP-wc-2 [P1]

  • Wrong: workflow create --ai 不传 --flowXml
  • Right: 传 --flowXml=完整 BPMN XML
  • Rationale: AI 默认生 trivial 3-node BPMN, 不实用
  • Source: drift/R12 F3

dm create

AP-dm-1 [P0]

  • Wrong: 凭印象写 dbLinkId
  • Right: 必跑 dacli app context --json 拿 dbLinkId
  • Rationale: "Database connection failed" (BS-E14)
  • Source: blindspots/BS-E14

di create

AP-di-1 [P0]

  • Wrong: di create 不传 --fieldJson
  • Right: 传 --fieldJson=<完整 schema JSON>
  • Rationale: 后端拿不到字段定义, 报 400
  • Source: drift/R9 BS-DI-1

AP-di-2 [P0]

  • Wrong: di create 不传 --parameterJson
  • Right: 传 --parameterJson=<参数 JSON>
  • Rationale: 后端拿不到参数定义
  • Source: drift/R9 BS-DI-2

AP-di-3 [P0]

  • Wrong: di create 不传 --dataConfigJson
  • Right: 传 --dataConfigJson=<数据配置 JSON>
  • Rationale: 后端拿不到数据源配置
  • Source: drift/R9 BS-DI-3

test run

AP-tr-1 [P0]

  • Wrong: test run 推 sample 数据 f_xxx_id 为空
  • Right: 先 POST 关联表拿真实 ID, 再 POST 主表
  • Rationale: 含 FK 字段的 form POST 报 "Field cannot be empty"
  • Source: lessons/jxcj1
  • Cross-refs: decisions/0008-test-run-no-fk-injection

app context

AP-ac-1 [P0]

  • Wrong: dbLinkId 从印象写
  • Right: 必跑 dacli app context --json 拿 dbLinkId / existingEnCodes
  • Rationale: "Database connection failed" 或 enCode 冲突
  • Source: lessons/jxcj1

form codegen

AP-codegen-error-diagnosis-1 [P1]

  • Wrong: 看到 dacli form codegen 报 CodePreview 请求失败: API code=400: System abnormality 就照提示走 b/c/d 三段式 PATCH —— GET → 解析 formData.fields[*].__config__.trigger == "" → 按 jnpfKey 设值 → PUT → Release。
  • Right: 先 dacli form export <formId> 拿真实 formData, 脚本扫 trigger=="" 个数。若实际 0 个空触发, 说明根因不在 trigger, 单跑三段式 PATCH 无效。应并行看: (1) JNPF 后端 log/jnpf-java-boot/log_error.log | grep FormMarco 的 stack trace, (2) formData 内其它空字段 (customBtns / appCustomBtns / tableConfig / 子表 / funcs.onLoad), (3) dacli log last --detail 拿原始 request payload。
  • Rationale: dacli 自动归因 trigger="" 触发 PublicMacro/FormMarco.vm:1226 substring(0,1) StringIndexOutOfBoundsException, 这是 web 端已知 最常见 根因但不是唯一根因。jxcj 验证回合 (2026-07-22): formData 0 个空 trigger, 仍报同一错误, 真根因待 NCPF 后端 stack trace 才可定。盲目跑三段式 PATCH 会产生"修复 0 处 → 仍是 System abnormality"的伪修复。
  • Source: jxcj 重启/验证回合 (2026-07-22) codegen 失败实战, formId=849667601347904773 (team)
  • Suggested mitigation:
    1. src/commands/form/codegen.ts 在 callWithDiagnosis 后追加 requestPayload 摘要 + 后端 stacktrace 前 5 行 (仅 --verbose 模式输出, 避免默认信息泄漏)
    2. _validate.ts 加 formData 导出诊断: --diagnose <formId> 输出 trigger="" 个数 + funcs/code-btn 空状态, 让 AI 一次性看到全貌而非单点提示
    3. 改"自动 PATCH"为"建议 PATCH": 默认 --fix-on-error=false, 仅 --fix-on-error 显式开启且要求用户提供有效 PATCH 预览
  • Cross-refs: ADR 0016 §3.5 (form --table 失败必须 ctx.fail, 不静默降级) — 本条扩展到 codegen: 失败诊断必须多角度、不单点归因

跨命令反模式 (设计阶段 + 子代理派发, jxcj M2 2026-07-23 实战)

AP-cross-design-overengineering [P1] (BS-新140)

  • Wrong: 设计 spec 写字段级 schema — dataType=varchar(50) / jnpfKey=select / dictType=jxcjxxx / min=0 max=100 / relationForm=enCode / dataLength=50 — 然后派子代理用 dacli form create --fields='[...]' 试图精准落表。
  • Right: spec 只写业务 (描述/约束/ADR), 不写技术 schema。子代理用 dacli form create --ai "<中文业务描述>" 唯一路径 (v0.12+ --fields 已废弃, AI 不读 spec 字段约束, 走自己的设计)。表单跑通后 web 端 FormDesign 兜底: 改字段名 + 补 dictType + 改 jnpfKey。
  • Rationale: jxcj M2 (2026-07-23) 实战: spec 写 f_unit / f_score_innovation 等字段, --ai 重命名为 f_work_unit / f_innovation_score, spec 完全作废。表字段名 ≠ spec 是常态, 不是 bug。过度设计导致 3 个浪费: (1) spec 编写耗时, (2) 用户 review 耗时, (3) 实际跑出来漂移, 用户困惑。
  • Source: jxcj M2 2026-07-23, BS-新140 (元规则). 关联 BS-新131~133 (AI 重命名/dictType 丢/userSelect 误判).
  • Suggested mitigation:
    1. ssw-loop SKILL.md 已加元规则 3 条 (依赖顺序/业务无关/不过度设计), 强制 design 模板只写业务
    2. templates/docs/design.md.tmpl §2 数据模型改"业务视角": 业务描述 + 业务约束 + ADR, 不写技术 schema
    3. templates/subagent/form-create.md.tmpl 加 5 项前置依赖 + 通用骨架 prompt, 子代理不依赖 spec 字段级 schema
    4. web 端 FormDesign 是 schema 修复权威 (dacli form update --fields 间歇报 "System abnormality", 不稳定)
  • Cross-refs: BS-新131 (--ai 重命名字段), BS-新132 (--ai 丢 dictType), BS-新133 (--ai 误判 userSelect). ssw-loop SKILL.md §元规则.

AP-cross-subagent-dependency-violation [P0] (BS-新131~135 关联)

  • Wrong: 主代理并行派多个 form 子代理, 各自跑 dacli app context --json + dacli dict typeList + dacli form create --ai, 不检查依赖 dict/role/dm 是否已建。结果: 子代理开工时 dict enCode 不存在, --ai 丢 dictType; 或 formId 引用空, 后续 workflow/menu create 失败。
  • Right: 严格按拓扑顺序派发 — (1) dict + role + dm 并行, (2) 等所有 dict/dm/role 都验收后再派 form 子代理 (依赖已就绪), (3) 等 form 验收后派 workflow/menu 子代理 (form 已发布), (4) test 跑在最后。详见 references/dependency-order.md。
  • Rationale: jxcj M2 (2026-07-23) 实际踩过 5 次返工: dict 没建 form 引用空 / form 没建 workflow 引用空 / form 没建 menu 引用空 / role 没建 user 引用空 / dm 没建 form 引用空。每次返工 30+ 秒, 累计 5+ 分钟。子代理模板加前置依赖检查 (5 项 grep) 可阻止 90% 此类返工。
  • Source: jxcj M2 2026-07-23, BS-新131~135 关联. 详见 dacli-ts/.claude/skills/ssw-loop/references/dependency-order.md.
  • Suggested mitigation:
    1. ssw-loop SKILL.md 元规则 1: 跨层禁止并行, 派下一层前必跑验收 grep
    2. templates/subagent/form-create.md.tmpl 加"前置依赖 (硬规则, 不满足不开工)" 5 项 grep
    3. references/dependency-order.md 列 8 层拓扑 + 5 条跨层禁止清单 + 4 条验收检查点
    4. 主代理派发流程改为"批次模式": 批次 1 (dict/role/dm) → 验收 → 批次 2 (form) → 验收 → 批次 3 (workflow/menu) → 验收 → 批次 4 (test)
  • Cross-refs: ssw-loop SKILL.md §元规则 1. references/dependency-order.md 跨 app 通用依赖图.

AP-cross-business-info-leak [P1] (BS-新140 关联)

  • Wrong: 模板/skill 文档里出现具体业务术语 — "评委表: 评委扩展信息, 关联 jnpf-user" / "评分审批流: 评委提交 → 评分组长审批 → admin 复核" / 举例用 "jxcjjudgestatus" 等 appCode 前缀字典。
  • Right: 模板只放通用骨架 + 反例引用 ("不写 X" 而不是"写 X")。具体业务信息只入 docs/{app}/ (e.g. docs/jxcj/m2-design.md)。appCode 通用占位符 (<app_code> / <enCode> / <table_name> / <dict_enCode>)。
  • Rationale: 模板一旦带具体业务, 污染跨 appCode 复用 (新 app 用户看到"评委"会困惑是不是必须这样设计)。模板/skill 必须业务无关, 任何 appCode 都该能用。jxcj M2 实战: ssw-loop templates/subagent/form-create.md.tmpl 原版有"评委"反例, 误导用户以为必填字段是 userSelect — 实际是 AI 误判, 应该用 input。
  • Source: jxcj M2 2026-07-23, BS-新140 关联. 详见 .claude/skills/ssw-loop/SKILL.md §元规则 2.
  • Suggested mitigation:
    1. ssw-loop SKILL.md 元规则 2: 模板/skill 禁止含具体业务, 业务信息只入 docs/{app}/
    2. 反例可以保留 ("❌ 不写 X" 帮助理解红线), 但举例必须用占位符 <X> 或 <app_code>
    3. CI check: grep -E "jxcj|评委|团队|评分|judge|team|score" .claude/skills/ssw-loop/templates/*.tmpl 应只命中反例引用 (≤5 处), 真实业务污染 = 0
  • Cross-refs: ssw-loop SKILL.md §元规则 2. BS-新140 (过度设计也是业务污染一种).

AP-cross-smartprops-missing-update [P0] (BS-新141, jxcj M2 2026-07-23 实战)

  • Wrong: 遇到 dacli form create --ai 生成 form 后, dictType / modelId / relationField 全空, 直接用 dacli form update --fields '<手工 JSON>' 补。或: 认为 --ai prompt 含 enCode 就能自动绑, 实测不绑, 反复重写 prompt。
  • Right: dacli form create 的 step machine 已有 smartProps (BS-18/61/62/63/64) 跑 applySmartProps 调 /ssw/ai/infer-component-props + 启发式 fallback。但 dacli form update --fields 没有 smartProps (update.ts:162-200 只做 JSON 合并, 无 AI/启发式)。应:
    1. 短期: 修复时先 dacli form update --fields '<含完整 dictType/modelId/relationField>' (手工 JSON), 间歇报 "System abnormality" 重试
    2. 长期 (ADR 0017): 把 smartProps 抽离成共享模块, form create + form update --fields 都跑; 新增 applyHeuristicDictType (select 字段按字段名模糊匹配 dict enCode)
    3. 不要: 反复改 --ai prompt 加更多 enCode/id — 实测 (jxcj M2 验证实验, 临时 form 849912141677856005/849913609722004741/849914591969281285) prompt 含 enCode 只决定 jnpfKey, 从不绑具体 id. 这是 NCPF backend 设计限制, 不可绕过.
  • Rationale: 用户原话 (2026-07-23): "step machine 有一个配置 ai 自动配置属性环境, dacli form update --fields, 这个是不是应该融合进去"。jxcj M2 验证性实验证实: prompt 含关联 enCode (关联 jxcjteam enCode=jxcjteam) 时 AI 选 relationForm 控件 ✅, 但 modelId/relationField 空 ❌. 同样: dict enCode → AI 选 select ✅, dictType 空 ❌; di enCode → AI 选 select ✅, modelId 空 ❌. 跟 prompt 无关, NCPF backend LLM 不绑具体 id.
  • Source: jxcj M2 2026-07-23, BS-新141 (智能属性缺失). 详见 dacli/docs/decisions/0017-form-smartprops-unification.md.
  • Suggested mitigation:
    1. ADR 0017 改进 1: 把 _smart_props.ts 暴露成 SMART_PROPS stable public API
    2. ADR 0017 改进 2: form update --fields 集成 smartProps (跟 create 一致)
    3. ADR 0017 改进 3: 新增 applyHeuristicDictType (select → 模糊匹配 dict enCode, 写 dictType id)
    4. ADR 0017 改进 4: applyHeuristicRelationForm 扩展到 select → relationForm 升级 (已选 select 的 FK 字段)
    5. 短期手动 fallback: dacli form update --fields '[{"vmodel":"f_xxx","dictType":"<dict_id>","modelId":"<form_id>","relationField":"f_name"}]' — dict/form id 从 dacli dict typeList --json / dacli form list --json 拿
  • Cross-refs: ADR 0017 (smartProps unification), ADR 0012 (relationForm 兜底改进 3), BS-新131 (字段重命名), BS-新132 (dictType 丢, 本 BS 根因), BS-新133 (modelId 丢, 本 BS 根因). ssw-loop templates/subagent/form-create.md.tmpl Step 4 "修 AI 数据源绑定".

BS-新132 (修订, 2026-07-23): --ai 不绑具体数据源 id (跨 dict/relationForm/di)

  • Wrong (原版): "--ai 丢失 dictType (select 字段不绑字典)" — 暗示 AI 偷懒漏写.
  • Right (修订): --ai 决定 jnpfKey 准确率高 (含 enCode 时 select/relationForm 自动选), 但不绑任何具体 id (dictType / modelId / relationField / dataInterfaceId 全空), 跟 prompt 是否含 enCode 无关. 这是 NCPF backend LLM 设计限制, 不可绕过.
  • 修正 1: 把原 BS-新132 描述从 "--ai 丢失 dictType" 改成 "--ai 决定 jnpfKey 对, 但不绑具体 id, 跨 dictType/modelId/relationField".
  • 修正 2: 不要在 --ai prompt 里反复加 enCode/id, 这是无效修复路径 (实测 jxcj M2 验证回合, 临时 form jxcjdicttest 849913609722004741 dictType 仍空).
  • 修正 3: 修复路径是 ADR 0017 (smartProps unification) + applyHeuristicDictType 新启发式.
  • Cross-refs: BS-新141 (smartProps missing), ADR 0017 §改进 3 (applyHeuristicDictType).

BS-新133 (修订, 2026-07-23): --ai 不绑 modelId/relationField (relationForm 三元组缺失)

  • Wrong (原版): "--ai 把 f_user_id 误判 userSelect, 把 f_team_id/f_judge_id 误判 input" — 暗示 AI 选错控件.
  • Right (修订): --ai 在 prompt 含 "关联 jxcjteam" 时确实选 relationForm ✅ (jxcj M2 验证, 临时 form jxcjrelationtest 849912141677856005). 但 modelId (绑哪个 form id) + relationField (显示字段) + columnOptions (列表列) 三个关联细节参数永远空, 跟 prompt 是否含 enCode 无关.
  • 修正 1: BS-新133 不再是 "AI 误判", 而是 "AI 选控件类型对, 不绑 id". 原 "误判 userSelect" 实测是 jxcj M2 prompt 没提 "关联 jnpf-user", AI 走默认 userSelect — 这是 prompt 信息不全, 不是 AI 缺陷.
  • 修正 2: 修复路径是 ADR 0017 §改进 4 (applyHeuristicRelationForm 扩展到 select → relationForm 升级) + form update --fields 集成 smartProps.
  • 修正 3: form update --fields 加 --no-smart-props flag 让用户关掉启发式 (跟 create 一致).
  • Cross-refs: BS-新141 (smartProps missing), ADR 0017 §改进 4 (applyHeuristicRelationForm 扩展), BS-新131 (字段重命名, 仍真实, 跟 smartProps 无关).