diff --git a/docs/anti-patterns.md b/docs/anti-patterns.md new file mode 100644 index 0000000..8e75fcf --- /dev/null +++ b/docs/anti-patterns.md @@ -0,0 +1,214 @@ +# 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=` +- **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/ --moduleId=` +- **Rationale**: 走 Actions/Module 时 form schema 缺主表信息报 "主表不存在" +- **Source**: blindspots/BS-50 + +### AP-mc-3 [P1] + +- **Wrong**: `跨 app 引用未传 --urlAddress` +- **Right**: `传 --urlAddress=model/` +- **Rationale**: SPA 找不到 form 路由 404 +- **Source**: drift/R5 + +## dict typeCreate + +### AP-dt-1 [P0] + +- **Wrong**: `dict typeCreate 不查就建` +- **Right**: `先 `dacli dict dataList` 看已有字典, 复用或加 _ 前缀` +- **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=` +- **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 + diff --git a/scripts/extract_anti_patterns.ts b/scripts/extract_anti_patterns.ts new file mode 100644 index 0000000..55e1547 --- /dev/null +++ b/scripts/extract_anti_patterns.ts @@ -0,0 +1,20 @@ +// Extracts ANTI_PATTERNS from _anti_patterns.ts and outputs markdown to stdout. +import { ANTI_PATTERNS } from '../src/commands/_anti_patterns' + +for (const [cmd, patterns] of Object.entries(ANTI_PATTERNS)) { + if (patterns.length === 0) continue + console.log(`## ${cmd}`) + console.log('') + for (const p of patterns) { + console.log(`### ${p.id} [${p.severity}]`) + console.log('') + console.log(`- **Wrong**: \`${p.wrong}\``) + console.log(`- **Right**: \`${p.right}\``) + console.log(`- **Rationale**: ${p.rationale}`) + console.log(`- **Source**: ${p.source}`) + if (p.crossRefs && p.crossRefs.length > 0) { + console.log(`- **Cross-refs**: ${p.crossRefs.join(', ')}`) + } + console.log('') + } +} diff --git a/scripts/gen-anti-patterns-md.sh b/scripts/gen-anti-patterns-md.sh new file mode 100755 index 0000000..456a148 --- /dev/null +++ b/scripts/gen-anti-patterns-md.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# Generate dacli/docs/anti-patterns.md from _anti_patterns.ts (single source of truth). +# Usage: bash scripts/gen-anti-patterns-md.sh [--check] +# --check: diff against dacli/docs/anti-patterns.md, exit non-zero if stale + +set -euo pipefail + +DACLI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +OUT="$DACLI_DIR/docs/anti-patterns.md" + +# Extract ANTI_PATTERNS entries via npx tsx +TMP=$(mktemp) +npx tsx "$DACLI_DIR/scripts/extract_anti_patterns.ts" > "$TMP" 2>/dev/null + +# Wrap with markdown header +{ + echo "# dacli Anti-Patterns (Auto-Generated)" + echo "" + echo "> **Source**: \`dacli/src/commands/_anti_patterns.ts\` (single source of truth)" + echo "> **Generator**: \`scripts/gen-anti-patterns-md.sh\`" + echo "> **DO NOT EDIT MANUALLY.** Run \`bash scripts/gen-anti-patterns-md.sh\` to regenerate." + echo "" + cat "$TMP" +} > "$OUT" + +rm -f "$TMP" + +if [ "${1:-}" = "--check" ]; then + REGEN=$(mktemp) + npx tsx "$DACLI_DIR/scripts/extract_anti_patterns.ts" > "$REGEN" 2>/dev/null + { + echo "# dacli Anti-Patterns (Auto-Generated)" + echo "" + echo "> **Source**: \`dacli/src/commands/_anti_patterns.ts\` (single source of truth)" + echo "> **Generator**: \`scripts/gen-anti-patterns-md.sh\`" + echo "> **DO NOT EDIT MANUALLY.** Run \`bash scripts/gen-anti-patterns-md.sh\` to regenerate." + echo "" + cat "$REGEN" + } > "$REGEN.md" + if ! diff -q "$OUT" "$REGEN.md" > /dev/null; then + echo "ERROR: $OUT is stale. Run: bash scripts/gen-anti-patterns-md.sh" >&2 + rm -f "$REGEN" "$REGEN.md" + exit 1 + fi + rm -f "$REGEN" "$REGEN.md" + echo "OK: $OUT is up to date" +else + echo "Generated: $OUT" +fi