JNPF v7 打开 config.MultiTenancy 后, 账号必须带租户号, 否则 admin 把整个 account 当 tenantCode 去查 base_tenant → 「租户不存在」。 核心认知: 租户是**登录态的属性**, 不是请求参数。只体现在 POST /oauth/Login 的账号串里; 后端签发的 token 其 loginId 形如 `zhangsan:349057407209541`, 之后每个请求由 admin 按 token 自己切数据源。所以不需要给任何 API 加租户 参数, 适配全是本地状态和 CLI 的事。 - core/config: 新增 DEFAULT_TENANT(JNPF_TENANT env, 默认 host) 与纯函数 loginAccount() / splitAccount(); loginAccount 见到 '@' 就不重复拼租户号, 老写法 `--account 'zhangsan@admin'` 继续可用 - core/client: ClientOptions.tenant / JnpfClient.tenant; doLogin 发拼好的串, fromToken 从缓存恢复, persist 落 tenant。**account 自带的租户优先于 opt.tenant** —— 反过来 token.json 会把租户错记成 --tenant 的默认值 - core/types: TokenFile 加可选 tenant; account 原样保存, 老 token.json 照样能读 - app/login|switch|status|logout: 加 --tenant; switch 的 --appCode 降为可选 (两者至少给一个, 没给的沿用 token 里的) - app/create: 重新登录时带上 tenant —— app create 是在当前租户里建应用 - app/_check_system: PLATFORM_APPS 白名单 + keyword 查不到时回退全量列表。 /api/system/System 只返回门户/自建应用, 平台应用 mainSystem/workFlow/ teamwork 不在里面, 也没有列全表的端点, 原来的精确匹配一律判成「不存在」 - DEFAULT_APP_CODE 'testspace' → 'mainSystem'(本地集群 base_system 里没 testspace) - app/logout: --tenant 仅二次确认(token 是单文件, 清掉就是当前租户被登出); 租户对不上时 warn **同时**进 JSON 和 ctx.success —— log.warn 在默认 quiet 模式下会被 _output_filter 丢进 buffer 再丢掉 - di/create: tenantId 保持 '0', 只订正注释。实测 public 与 jnpf_tenant_l1d9xv905q31 两个 schema 的种子数据各 119 行 f_tenant_id 全是 '0'; 只有列隔离(f_type=1)才拿它当隔离键, 本部署是 schema 隔离 已在 wuguirong 集群实测: 跨租户落库正确(zhangsan → jnpf_tenant_l1d9xv905q31, host → public), dbPing/llmPing/menuIntegrity 三项全通。 Co-Authored-By: Claude Code <[email protected]>
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— 数据模型 APIweb/.../FlowProcess/src/helper/config.ts— 工作流 globalFormMap / flowNodes 默认值
2. 不写 LLM prompt (LLM prompt 在 ssw-common, 不在 dacli)
dacli/src/commands/form/_ai.ts:
"dacli 设计上不写 LLM prompt (prompt 在 ssw-common
boot/ssw-common/, 不在 dacli)。dacli 仅消费 LLM 响应 + 构造 formData/workflow."
v0.22+ (2026-07-25) 路径:
dacli form create --ai "<描述>"走 ssw-common/api/ssw/ai/build-form(form) +/api/ssw/ai/build-workflow(workflow)- ssw-common
boot/ssw-common/.../AIRepairServiceImpl.java含BUILD_FORM_PROMPT+BUILD_WORKFLOW_PROMPT, 镜像 web 端 schema, prompt 我们写
注: "NCPF" 是 JNPF 后端 AI 端点的历史叫法, v0.22+ 已旁路 (SSW 直调 LLM, 无 NCPF 4+3 限制). 详见 docs/decisions/.
字段名错误处理: 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 步 (避免凭印象猜)
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 强制)
✅ 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/ 整体已归档 (2026-07-23) → dacli/docs/archive/cmd-review-2026-07/ (25 文件历史快照) |
| 历史决策 | dacli/docs/decisions/ (0001-0016 系列, 决策记录; ADR 0014 app clear + ADR 0015 源码遗留清单 + ADR 0016 eventhub blocker 设计) |
| 历史漂移分析 | ⚠️ dacli/docs/drift/ round summary 整体已归档 (2026-07-23) → dacli/docs/archive/drift-rounds-2026-07/ (20 round 历史快照); 顶层 drift/ 保留 README/USAGE/fetch-baseline.sh 基础设施 |
| 跨项目教训 | dacli/docs/尚数网基本开发规范v3.0.md (公司规范) |
| 反模式 | dacli/docs/anti-patterns.md (Web 组件 / 后端约束踩坑) |
🏗️ 架构核心
v0.13+ 镜像架构 (2026-07-01 大改)
dacli form create --ai "..."
↓
[1] callAiForm → POST /api/ssw/ai/build-form (v0.22+ SSW 直调 LLM, prompt 我们写)
↓ 返回 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.
// 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.
// 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 种格式):
# 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 调用流程 (错误恢复):
# 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 项检查
🔒 质量门自动强制 (P3, 2026-07-24):
git config core.hooksPath scripts/githooks后, pre-commit 自动跑scripts/quality-gate.sh(tsc --noEmit + vitest unit + backend smoke), 编译或单测失败直接阻塞 commit — 第 3 项已从"靠自觉"变"门强制"。新 clone 先跑sh scripts/install-hooks.sh激活。仪式门_gate_webapi降级为 advisory (只报告 webapi 引用率, 不阻塞)。
- ✅ 读过 web/ 源码? 至少读 1 个相关
web/.../api/*文件 + 1 个web/.../views/*文件 - ✅ 查过
dacli/docs/decisions/? 看相关历史决策避免重蹈覆辙 - ✅ TS 编译 0 错误?
npx tsc --noEmit --project dacli/tsconfig.json— 质量门已自动强制 - ✅ 跑过端到端?
npx tsx dacli/src/cli.ts <cmd>真实创建 1 个 form/menu 验证 - ✅ 跑过 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 |
推荐: 建表单 (v0.22+ 走 SSW /build-form, prompt 我们写) |
dacli form update --fields='[...]' |
改 schema (兜底补 7 字段 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) |
改 app clear --clean-docs 行为 |
dacli/src/commands/app/clear.ts (P1-2d 2026-07-21, docs/{app}/ 整体清理) + dacli/docs/decisions/0014-app-clear-docs-coverage.md |
| 加新模块接入 (三层模式) | 跟 report/create.ts 同样 4 步 pattern: imports → addOutputOptions → setupOutputFilter + runCommandAutoFix → printCommandEnd |
📝 关键命名规范 (JNPF 6.x)
- enCode: camelCase 无下划线 (BS-56, JNPF 全平台强制) — 例:
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 + v2.2+ wrapCommand helper