# dacli — AI 驱动 JNPF CLI > ⚠️ **修改 dacli 前必读**: 本文件是 dacli 基本原则速查 (10 分钟读完), 写代码前过一遍. > 权威源: **web 源码** (铁律 1) + 本文件速查 + `dacli/src/webapi/*` 镜像注释 --- ## 🔒 5 大铁律 (违反任一 = 重做) ### 1. **web/ 源码永远是权威** (绝对原则) ``` ✅ DO: 看 web/apps/jnpf-web-apps-main/src/{api,views,components}/ 实际代码 ❌ DON'T: 凭"经验"猜 API 路径/默认值/校验规则 ``` 如果 dacli 文档与 web/ 不一致 → **以 web 为准**,直接读源码。 **权威文件 (按使用频率)**: - `web/.../views/onlineDev/formDesign/Form.vue` — form 创建的精确字段默认值 - `web/.../api/onlineDev/visualDev.ts` — 所有 visualdev API 端点 - `web/.../api/systemData/dataModel.ts` — 数据模型 API - `web/.../FlowProcess/src/helper/config.ts` — 工作流 globalFormMap / flowNodes 默认值 ### 2. **不写 LLM prompt** (跟 NCPF backend 透传) `dacli/src/commands/form/_ai.ts:3-9`: > "dacli 设计上**不写 LLM prompt** (跟 NCPF backend 透传)。自写 prompt 必与后端漂移 (两个 prompt 源, 升级时一方动一方不动)。" `--ai "<描述>"` 走 NCPF backend `/api/visualdev/ai/form`,prompt 在后端,不在 dacli。 **字段名错误处理**: AI 路径默认 camelCase (无 f_ 前缀), 用 `--column-naming=snake` 后处理重命名 (默认开启, 见 `create.ts:255`)。 ### 3. **镜像架构 0 复刻 0 漂移** (dacli/webapi) ``` ✅ DO: 直接 import web 端源码到 dacli/src/webapi/* (用 _loader.ts 替换 import) ❌ DON'T: 抄 web 端代码自己写一遍 (历史教训: 6 周修 50+ 漂移问题) ``` 已镜像 18 个 webapi 模块, 100+ 函数. 单进程缓存避免重复 load. ### 4. **新会话必跑 3 步** (避免凭印象猜) ```bash dacli app context --json # Step 1: 拿 dbLinkId / systemId / existingEnCodes dacli form list # Step 2: 看已有 form (避免重名) dacli --help # Step 3: 标准 commander 帮助 (含选项 + 描述) ``` ### 5. **不绕过 dacli 调 curl** (CLAUDE.md 强制) ```bash ✅ DO: 所有 JNPF 操作走 dacli (form/dm/dict/menu/workflow/role/di/log/...) ❌ DON'T: 用 curl 直调 /api/* (绕过 schema 校验/auto_fix/日志) ``` --- ## 📁 必读文档 (按场景) > **策略**: 优先读 web 源码 (铁律 1). dacli 端文档作辅助. | 场景 | 权威源 | |------|------| | 控件类型映射 (jnpfKey/dataType) | `web/.../utils/src/helpers/formUtils.ts:14-77` + `web/.../FormGenerator/src/componentMap.ts` | | Form schema 三件套 (formData/columnData/tables) | `web/.../views/onlineDev/formDesign/Form.vue` + `Generator.getData` + `ColumnDesign.getData` | | Workflow 节点 / globalFormMap | `web/.../FlowProcess/src/helper/config.ts` + `web/.../views/onlineDev/flowEngine/index.vue` | | 30+ 错误码 (EXIST/VS/WF/SYS) | 后端 `jnpf/.../constant/MsgCode.java:50-783` | | 命名规范 (snake/camelCase/f_ 前缀) | `dacli/docs/decisions/0001-fk-relation-form-required.md` + `0002-form-create-ai-4-limitations.md` | | 找 web 源码位置 | 用 IDE 全局搜索 (`Cmd+Shift+F` / `grep -rn`) 找 `formData` / `flowNodes` / `columnList` | | 命令评审历史 | `dacli/docs/cmd-review/` | | 历史决策 | `dacli/docs/decisions/` (0001-0010 系列, 决策记录) | | 历史漂移分析 | `dacli/docs/drift/` (round7/10 等修复记录) | | 跨项目教训 | `dacli/docs/尚数网基本开发规范v3.0.md` (公司规范) | | 反模式 | `dacli/docs/anti-patterns.md` (Web 组件 / 后端约束踩坑) | --- ## 🏗️ 架构核心 ### v0.13+ 镜像架构 (2026-07-01 大改) ``` dacli form create --ai "..." ↓ [1] callAiForm → POST /api/visualdev/ai/form (NCPF backend, 走 JNPF 配置的 LLM) ↓ 返回 VisualAiModel [2] web buildFormData (webapi 镜像) → 构造 50+ formConf 字段 ↓ [3] loadVisualDev.create → POST /api/visualdev/Base [4] loadVisualDev.release (默认 ON, type=1 真正发布) → POST /api/visualdev/Base/{id}/Actions/Release ↓ ✅ form state=1, 可用 ``` ### webapi 模块清单 (`dacli/src/webapi/`) > **机制**: 每个文件 `export const loadXxx = new Proxy(...)`, 懒加载镜像 web 端**全部函数** (dacli 端只需 init 一次, 之后 `loadXxx.fn(args)` 调 web 端原版). 因此函数数 = web 端全部导出, 不在 dacli 端 grep 数. | 模块 | 镜像 web 文件 | 用途 | |------|---------------|------| | `visualDev.ts` ★ | `web/.../api/onlineDev/visualDev.ts` | form / work CRUD | | `workflow.ts` ★ | `web/.../api/workFlow/template.ts` | work CRUD | | `dict.ts` ★ | `web/.../api/systemData/dict.ts` | 字典 | | `dataModel.ts` ★ | `web/.../api/systemData/dataModel.ts` | 数据模型 | | `dataSource.ts` | `web/.../api/systemData/dataSource.ts` | 数据源 | | `menu.ts` | `web/.../api/permission/menu.ts` | 菜单 | | `role.ts` | `web/.../api/permission/role.ts` | 角色 | | `log.ts` | `web/.../api/system/log.ts` | 系统日志 | | `monitor.ts` | `web/.../api/system/monitor.ts` | 监控 | | `schedule.ts` | `web/.../api/system/schedule.ts` | 定时任务 | | `message.ts` | `web/.../api/system/message.ts` | 消息/通知 | | `report.ts` | `web/.../api/system/report.ts` | 报表 | | `onlineUser.ts` | `web/.../api/permission/onlineUser.ts` | 在线用户 | | `flowMonitor.ts` | `web/.../api/workFlow/flowMonitor.ts` | 流程监控 | | `user.ts` | `web/.../api/permission/user.ts` | 用户 | | `di.ts` | `web/.../api/systemData/dataInterface.ts` | 数据接口 | | `visualdata.ts` | 大屏 (独立子项目) | 大屏 | | `datascreen.ts` | 大屏 (visual.js 相对路径) shim | 大屏备选 | ### 输出过滤模式 (v2.0+ quiet mode) — **第一层处理: stdout 流向** **核心**: `dacli/src/core/log.ts:23-77` 实现 `setQuiet` / `flush` / `discard` / `printJson`. ```ts // form 命令模板 (dacli/src/commands/form/create.ts:248-262) .option('--verbose', '完整输出 (含 step machine、API 调用等过程日志)', false) .option('--json', '原始 JSON 输出', false) .action(async (opts) => { log.setQuiet(!opts.verbose && !opts.json) // ... 业务逻辑 ... if (opts.verbose) log.flush() else log.discard() process.stdout.write(` 详情: dacli log last\n`) }) ``` **3 种 stdout 模式**: | 模式 | 触发 | 行为 | AI 用法 | |------|------|------|---------| | 默认 quiet | 不传 flag | `info/ok/warn/dim/raw` → buffer → `discard()` (默认); `error` 永远即时 | 默认操作 (AI 不需要过程日志) | | `--verbose` | `dacli form create --verbose` | 所有日志即时输出 (含 step machine/API 调用过程) | 调试时开启, 看完整 trace | | `--json` | `dacli form list --json` | 原始 JSON 直接 stdout (不受 quiet 影响) | pipe 到 `jq` / `grep` 解析 | **stdout 详情查询**: `dacli log last` (摘要) / `--detail` (含回滚命令+原始请求响应) / `--level=fix` (只看修正) / `--raw` (原始 JSON). ### 错误修正三重处理 — **第二层处理: 异常恢复策略** **核心**: `dacli/src/core/logfile.ts:33-54` 定义 `CommandLog` 的 3 种 fix 数组. 实现见 `dacli/src/commands/_auto_fix.ts` + `_error_codes.ts`. ```ts // dacli/src/core/logfile.ts:33-54 export interface CommandLog { result: 'success' | 'failure' | 'partial' summary: { silent_fixes: number // ← 自动处理 (用户无感知) assertive_fixes: number // ← 警告级 (有回滚命令) suggestions: number // ← 提示级 (AI 修复建议) } silent_fixes: FixEntry[] // [{id, level: 'silent', summary, ...}] assertive_fixes: FixEntry[] // [{id, level: 'assertive', summary, rollback, ...}] suggestions: FixEntry[] // [{id, level: 'suggest', summary, ...}] } ``` **3 级 fix 策略**: | 级别 | 触发条件 | 行为 | AI 感知 | 查询命令 | |------|---------|------|--------|---------| | **silent** (自动) | 后端报 EXIST002 (重名) 等可自动恢复 | 自动改名 `_v2` 重试, **不报错** | 无感知 (默认成功) | `dacli log last --level=fix` | | **assertive** (警告) | 后端报 VS401/VS402 等必须修正 | 强制改 schema + 输出回滚命令 | 看到警告 + 回滚命令 | `dacli log last --level=fix --detail` | | **suggest** (提示) | 数据/配置有问题但可继续 | 输出 `[step N name] field: CODE - message (suggestion)` | AI 根据 suggestion 自修复 | `dacli log last` 摘要 | **典型输出样例** (AI 必须能解析这 3 种格式): ```text # silent (自动处理, 默认 stdout 无输出) ✓ formCreate 成功 (silent_fixes=1: 重名 _v2) # assertive (警告级, stdout 显示 ⚠) ✗ [step 1 formData] relationForm.modelId: VS401 - 关联功能不能为空 ✅ assertive fix: modelId 自动设置为 formId=848864086438446021 回滚: dacli form update --fields='[{"__vModel__":"f_team_id","jnpfKey":"input"}]' # suggest (提示级, stdout 显示 💡) 💡 suggest: form update 时显式传 --fields='[...]' 包含 modelId (BS-新117) ``` **AI 调用流程** (错误恢复): ```bash # 1. 默认跑 (auto-fix 自动处理 silent) dacli form create --enCode=X --fullName=X ... # 2. 失败时查详情 dacli log last # 摘要: silent_fixes / assertive_fixes / suggestions 计数 dacli log last --level=fix # 只看 fix (含 rollback 命令) dacli log last --detail # 含原始请求/响应 # 3. 按 suggestion 修复 (AI 自修复) dacli form update --fields='[...]' # 按 suggestion 建议的修正 ``` **修改点** (AI 修改这三层时的入口): | 想改什么 | 文件 | |---------|------| | 新加 silent fix 策略 | `dacli/src/commands/_auto_fix.ts` | | 新加 assertive fix + rollback | `dacli/src/commands/_auto_fix.ts` (entry 加 `rollback` 字段) | | 改 G-X1 重名查的列表 (form/dict/menu/role/**workflow**) | `dacli/src/commands/_auto_fix.ts:fetchExistingLists` (v2.1+ workflows 扩展) | | 改错误码分类 | `dacli/src/commands/_error_codes.ts` (30+ 错误码 EXIST/VS/WF/SYS) | | 改 CommandLog 结构 | `dacli/src/core/logfile.ts:33-54` | ### 三层处理总结 (AI 速查) ``` 第一层 (stdout 流向): 静默 (默认) | --verbose | --json ↓ 错误发生 第二层 (异常恢复): silent (自动) | assertive (警告+回滚) | suggest (提示) ↓ 历史归档 第三层 (历史查询): dacli log last | --level=fix | --detail | --raw ``` **设计原则**: - 不打扰 (默认静默 + 自动 silent fix) - 可观测 (--verbose + dacli log last) - 可回滚 (assertive 必有 rollback 命令) - 可学习 (suggestion 给 AI 修复方向) --- ## ✏️ 修改 dacli 前的 5 项检查 1. **✅ 读过 web/ 源码?** 至少读 1 个相关 `web/.../api/*` 文件 + 1 个 `web/.../views/*` 文件 2. **✅ 查过 `dacli/docs/decisions/`?** 看相关历史决策避免重蹈覆辙 3. **✅ TS 编译 0 错误?** `npx tsc --noEmit --project dacli/tsconfig.json` 4. **✅ 跑过端到端?** `npx tsx dacli/src/cli.ts ` 真实创建 1 个 form/menu 验证 5. **✅ 跑过 4 关卡?** `bash .claude/skills/ssw-loop/scripts/check_*.sh docs//` --- ## 🚀 高频命令 (10 个) | 命令 | 用途 | |------|------| | `dacli app login --account=admin --password=123456 --appCode=X` | 登录 | | `dacli app context --json` | **新会话必跑**, 拿 dbLinkId/systemId/existingEnCodes | | `dacli form list` / `dacli form info ` | 列/查表单 | | `dacli form create --ai "<描述>" --autoRelease` | **推荐**: 建表单 (NCPF AI + web buildFormData + 自动发布) | | `dacli form update --fields='[...]'` | 改 schema (修正 AI 4 限制: 控件选错/幻觉字段/required 误标/relationForm 缺失) | | `dacli menu create --formId= --fullName=X --parentId=Y --type=3` | 绑 form 到 menu (sidebar 显示) | | `dacli dm list` / `dacli dm create --table=X --fields='[...]'` | 数据模型 | | `dacli workflow create --ai "<描述>" --fullName=X --category=Y` | **v0.13+**: 走 6 步 webapi 路径 (AI → create → version → buildFlowNodes → save) | | `dacli log last` | 看最近命令详情 (含回滚命令+原始请求) | | `dacli log exception --lines=100` | 查后端异常 (AI 调试核心入口) | --- ## ⚠️ AI 已知 4 限制 (2026-07-15 jxcj M1 实战) | 限制 | 现象 | 修复 | |------|------|------| | 控件类型选错 | `f_organizer` 被选 `depSelect` (应是 input) | `dacli form update` 改 jnpfKey | | 幻觉字段 | 多生 `input_num001` 等业务外字段 | `dacli form update` 删除 | | required 误标 | 上传控件被误标 required | `dacli form update` 改 required | | 未生成 relationForm | `f_*_id` 字段用 input 不用 relationForm | `dacli form update` 改 jnpfKey=relationForm + 补 modelId | **强制验证**: 生成后立即 `dacli form info ` 检查 4 项全对才完成。 --- ## 🆕 Step Machine 校验 (v0.11d+) `dacli form create` 完整校验链 (镜像 web 端 handleNext + handleSubmit + Generator.getData + ColumnDesign.getData): - step0 基础信息 (fullName/enCode 必填 + 格式) - step1 formData 字段 (formFields ≥ 1, 关联控件 modelId/propsValue/relationField) - step2 columnData 列表 (webType≠1 && columnList ≥ 1) 校验失败 → exit 1 + 错误信息, **不发 API**。 --- ## 📋 修改 dacli 文件路径速查 | 想做什么 | 改哪个文件 | |---------|----------| | 加新 form 命令 | `dacli/src/commands/form/*.ts` | | 加新 workflow 命令 | `dacli/src/commands/workflow/*.ts` | | 加新 report 命令 | `dacli/src/commands/report/*.ts` (8 文件, 已三层接入) | | 加新 datasource 命令 | `dacli/src/commands/datasource/*.ts` (4 文件, v2.1+ 已接) | | 加新 storage 命令 | `dacli/src/commands/storage/*.ts` (2 文件, v2.1+ 已接, yml 读) | | 加新 integration 命令 (email/sms/webhook test) | `dacli/src/commands/integration/*.ts` (3 文件, v2.1+ 已接) | | 加 webapi 镜像 | `dacli/src/webapi/*` + `_loader.ts` (动态 import 替换) | | 改输出过滤 | `dacli/src/core/log.ts` | | 改命令输出 helper (含 saveCommandLog 集成) | `dacli/src/commands/_output_filter.ts` (跨命令通用, v2.1+) | | 改命令级 auto-fix (enCode/fullName/BS-47) | `dacli/src/commands/_auto_fix.ts:runCommandAutoFix` (跨命令通用, v2.1+) | | 改 G-X1 重名查的列表 (form/dict/menu/role + workflow) | `dacli/src/commands/_auto_fix.ts:fetchExistingLists` (v2.1+ workflows 扩展 2026-07-21) | | 改 field-level auto-fix (jnpfKey/FK/datetime 等) | `dacli/src/commands/_auto_fix.ts:runAutoFix` (form 专用) | | 改校验规则 | `dacli/src/commands//_validate.ts` (per-module, 无公共 _validate.ts) | | 改公共 precheck | `dacli/src/commands/_precheck.ts` | | 改错误码 | `dacli/src/commands/_error_codes.ts` | | 改字典/字典数据 | `dacli/src/commands/dict/*.ts` | | 改菜单 | `dacli/src/commands/menu/*.ts` | | 改数据模型 | `dacli/src/commands/dm/*.ts` (create/drop/list/fields 已接) | | 改报表 | `dacli/src/commands/report/*.ts` (8 文件, BACKEND-7 已修 2026-07-21) | | 加新模块接入 (三层模式) | 跟 `report/create.ts` 同样 4 步 pattern: imports → addOutputOptions → setupOutputFilter + runCommandAutoFix → printCommandEnd | --- ## 📝 关键命名规范 (JNPF 6.x) - **enCode**: camelCase 无下划线 (BS-56, NCPF 后端强制) — 例: `auditrecord` 不是 `audit_record` - **表名**: = enCode (BS-55 同步规则) — 例: 表名 `auditrecord` 而不是 `audit_record` - **字典 enCode**: camelCase + jxcj 前缀 — 例: `jxcjcompetitionstatus` - **字段名**: 默认 snake_case (AI 路径下用 `--column-naming=snake` 默认加 f_ 前缀) - **类名**: PascalCase (包名已带 appCode, 不重复) **避坑**: - ❌ `f_version` (JNPF 关键字, 改名 `f_revision` / `f_v`) - ❌ `f_description` (JNPF 系统列, 改名 `f_brief` / `f_summary` / `f_remark`) - ❌ enCode 含 `_` (BS-56) — `audit_record` 改成 `auditrecord` **v2.1+ 自动修正** (2026-07-21): - ✅ enCode 含 `-`/`_` → **自动 strip** (S-X1 silent) — 不要再 inline 调 `autoStripEnCode` - ✅ fullName 含 BS-56 禁字符 → **自动 soften** (S-X2 silent) — 不要再 inline 调 `autoStripFullName` - ✅ enCode/fullName 与 existing{Forms,Dicts,Menus,Roles,**Workflows**} 冲突 → **G-X1 suggest** 含 `` 前缀建议 - 入口: `commands/_auto_fix.ts:runCommandAutoFix(opts, ctx)` — 跨命令通用 (form/dict/di/menu/role/workflow/bigscreen/portal/user/datasource/integration 等) - **G-X1 workflow 扩展** (2026-07-21): `fetchExistingLists` 也拉 `GET /workflow/template` 走 web 端镜像, workflow enCode 重名也能触发 suggest - 详见 `dacli/docs/decisions/0010-dacli-v2-self-correcting-cli.md` §3 + §5 --- **最后更新**: 2026-07-21 **版本**: v0.13+ 镜像架构 + v2.0+ 输出过滤 + v2.1+ 跨命令 auto-fix