Files
dacli/README.md
T

335 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <cmd> --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 <id> --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 <id> --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 <cmd>` 真实创建 1 个 form/menu 验证
5. **✅ 跑过 4 关卡?** `bash .claude/skills/ssw-loop/scripts/check_*.sh docs/<app>/`
---
## 🚀 高频命令 (10 个)
| 命令 | 用途 |
|------|------|
| `dacli app login --account=admin --password=123456 --appCode=X` | 登录 |
| `dacli app context --json` | **新会话必跑**, 拿 dbLinkId/systemId/existingEnCodes |
| `dacli form list` / `dacli form info <enCode>` | 列/查表单 |
| `dacli form create --ai "<描述>" --autoRelease` | **推荐**: 建表单 (NCPF AI + web buildFormData + 自动发布) |
| `dacli form update --fields='[...]'` | 改 schema (修正 AI 4 限制: 控件选错/幻觉字段/required 误标/relationForm 缺失) |
| `dacli menu create --formId=<id> --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 <enCode>` 检查 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/<module>/_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** 含 `<appCode>` 前缀建议
- 入口: `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