43 KiB
CLAUDE.md
本项目使用 JNPF 低代码平台 + dacli 实现 AI 驱动的快速应用开发。
注意,使用浏览器截图查看比较消耗token,尽量在数据层跑通后,截图验证时使用
统一入口(nginx)
默认入口: http://nginx/(容器内自动解析)
| URL | 目标 |
|---|---|
http://nginx/ |
前台首页 |
http://nginx/jnpf_app_{app} |
应用入口 |
http://nginx/jnpf_app_backend_{app} |
应用后台配置管理界面(表单/菜单/流程/门户/权限/大屏/报表)配置 |
http://nginx/ssw/{app}/ |
静态扩展页面 |
http://nginx/api/ |
后端API |
默认凭据: admin / 123456(dacli app login / JNPF 浏览器登录通用)
nginx 不可用 fallback(容器外或 nginx 挂了时):
| 服务 | 备用入口 | 备注 |
|---|---|---|
| 后端 API | http://127.0.0.1:30000 |
JNPF admin 端口(dacli app status 看 baseUrl) |
| 前端 SPA | web/apps/jnpf-web-apps-main/dist/ |
index.html 入口 |
| 前端静态扩展 | web/apps/jnpf-web-apps-main/public/ 或 web/apps/jnpf-web-apps-main/dist/ssw/{app}/ |
部署后走 nginx 代理, 无 nginx 时直接开 HTTP server |
fallback 验证步骤:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:30000/→ 应 200ls web/apps/jnpf-web-apps-main/dist/index.html→ 存在则前端已编译
CLI 使用(dacli)
dacli 是独立的 CLI 工具,通过 HTTP 调用已运行的 JNPF。
dacli AI 防御体系 (2026-06-22 v0.10+ → 2026-06-25 v0.11+ 镜像架构):解决 AI 误用根因 G(舍近求远)+ B/C/D(盲猜参数/状态)+ E(长任务副作用):
dacli app context命令(P0.1):AI 新会话必跑的环境快照(appCode/dbLinkId/token/existingEnCodes/草稿 vs 发布/表/菜单)- 三层防御体系:L1
_precheck.ts静态检查 + L2_blindspot_guards.ts22 条运行时 guard + L3client.diagnoseError()错误诊断- web/ 源码权威参照:SKILL.md 顶部强制规则——参数/API 不确定时,优先读
web/.../views/onlineDev/+web/.../api/,不读 dacli 文档web-source-map.md:dacli 命令 → web/ 源码精确定位速查表(149 行)form-type-rules.json(已删除 v0.11+):7 个 type×webType 合法组合 + 6 类常见错误(从 web/ 源码提取,非凭空编写)— 现由webapi/_buildformdata.ts直接 import web 端buildFormData内置规则保证webapi/镜像架构 (v0.11+):dacli/src/webapi/_loader.ts直接 dynamic importweb/.../api/onlineDev/visualDev.ts+web/.../helper/formUtils.ts,0 复刻 0 快照 0 漂移(已替换 extract-web-schema.py + extract-all.mjs + data/*.json)
⚡ v0.11+ webapi 镜像 + 30+ NEW-CMD (2026-06-25 闭环)
架构核心:dacli 不再"复刻 + 提取快照" web 端 API,而是直接 dynamic import web 端源码:
18 个 webapi 模块(累计 100+ 函数,消除 ~600 行硬编码):
- visualDev.ts (30) · dataModel.ts (10) · dataSource.ts (11) · dict.ts (15) · menu.ts (15) · workflow.ts (14)
- role.ts (8) · log.ts (9) · monitor.ts (7) · schedule.ts (8) · message.ts (9) · visualdata.ts (8) · report.ts (7)
- onlineUser.ts (3) · flowMonitor.ts (3) · user.ts (5) · di.ts (5) ·
_loader.ts+_defhttp_shim.ts
30+ NEW-CMD (P0 必学,2026-06-25 全部 commit):
| 父命令 | NEW-CMD | 用途 / commit |
|---|---|---|
| form | form update |
高需求:增量改 schema · 801a204 |
| form | form selector |
AI 引用 form 替代盲猜 enCode · 5f663eb |
| log | log exception |
P0 杀手锏:AI 调试核心入口 · 59a6b4a |
| log | log request / login / operate |
API 请求 / 登录 / 操作日志 |
| di | di info/test/update/delete |
数据接口 CRUD (5 个) · 59a6b4a d1284c4 |
| role | role info/update/selector |
权限管理闭环 · 6effbcb 51b1f04 |
| apis | apis tags |
API tag 分类 · 6effbcb |
| apis | apis search --field= |
字段盲猜 · 7b8f9b1 |
| workflow | workflow info/update/delete |
工作流 CRUD · 5ec47e3 4669e35 |
| workflow | workflow selector |
AI 引用 workflow · 5f663eb |
| schedule | schedule update/delete |
定时任务 CRUD · 6be66cb bd11e1b |
| msg | msg noticeList/Update/Delete + templateList/Update/Delete |
消息管理 6 个 · 6be66cb 4505a6f |
| monitor | monitor server/online/flow |
性能诊断 · af9e5a6 cbe6a1e |
| bigscreen | bigscreen update/delete |
大屏 CRUD · af9e5a6 4669e35 |
| dict | dict typeUpdate/typeDelete/dataUpdate/dataDelete |
字典管理闭环 · d31fa51 bed941b |
| doc | doc toc |
P0 杀手锏:上下文恢复,节省 40-60% token · 5f663eb |
| doc | doc search |
文档搜索 · 5f663eb |
| user | user list/create/delete |
用户管理 · 7224156 |
3 处 P0 端点错误修复(假 PASS,90a8b4e):
integration emailTest→/message/AccountConfig/testSendMailintegration smsTest→/message/AccountConfig/testSendSmsintegration webhookTest→/message/AccountConfig/testSendWebhookmsg templateCreate→/message/MessageTemplateConfig
已删除文件(v0.11+,避免 AI 引用):
scripts/extract-all.mjs(350 行) +scripts/extract-web-schema.py(220 行) +data/*.json(4 个)data/web-derived-schemas.json(v0.10 静态快照,2026-06-25 删)src/commands/form/_browser_construct.ts(未用,2026-06-25 删)
22 盲点 → 5 高频精简(webapi 化后):
- ✅ 已自动消除:BS-51 / BS-52 / BS-54(webapi 镜像保证 schema 完整性)
- ⚠️ 仍重要:BS-5 (AppContext) · BS-8 (token) · BS-48 (dbLinkId) · BS-49 (enCode) · BS-50 (主表)
- 完整 22 条表:
dacli/src/commands/_blindspot_guards.ts
errors.md决策树:26 段按错误关键词分类的修复步骤(v0.10+ 吸收了历史 36 条错误;v0.11+ 进一步吸 troubleshooting.md)详见
.claude/skills/dacli-ts/SKILL.md(148 行) +references/{errors,commands,patterns,web-source-map}.md。
dacli 架构原则(工具 + 状态 + 诊断 + 帮助 + 示例)
dacli 应该是 工具 + 状态 + 诊断 + 帮助 + 示例 +源码映射 的架构,为 AI 更好的服务。
每个 dacli 命令(父/子)都应该具备这 5 要素:
| 要素 | 含义 | 体现(v0.10+) |
|---|---|---|
| 工具 (Tool) | 真正干活的子命令 | 22 父命令 / 116 子命令, dacli form create/info/list/update/release/codegen |
| 状态 (State) | 当前环境快照 | dacli app context --json(appCode/dbLinkId/token/existingEnCodes/草稿 vs 发布/表/菜单) |
| 诊断 (Diagnostics) | 出错时定位 + 修复指引 | 三层防御体系(L1 _precheck.ts 静态检查 + L2 _blindspot_guards.ts 22 条运行时 guard + L3 client.diagnoseError() 错误诊断)+ errors.md 决策树 |
| 帮助 (Help) | 自动生成的文档 | Commander.js 自动 --help + .claude/skills/dacli-ts/SKILL.md |
| 示例 (Examples) | 真实调用过的例子 | dacli help 输出 + references/commands.md + references/patterns.md |
为什么:AI 用 dacli 是「输入命令 → 看输出 → 决策下一步」的循环。
- 没有 状态 → AI 盲猜参数(盲点根因 B/C/D,22+ 历史案例)
- 没有 诊断 → AI 卡在错误不知道下一步(盲点 8 / 15 / 38 / 47 / 48)
- 没有 帮助 → AI 发明不存在的子命令
- 没有 示例 → AI 编 API
- 没有 工具 → AI 自己写 curl 绕过 dacli(违反 §2.6 完善优先)
新命令开发 checklist(参考 .claude/skills/writing-skills + .claude/skills/dacli-ts/SKILL.md):
- 子命令实现(工具)
--json输出 +dacli app context列出(状态)- 错误路径触发
client.diagnoseError()或返回错误码 + 决策树引用(诊断) --help自动生成(Commander.js annotation)+ SKILL.md 段落(帮助)references/commands.md加 1-3 个真实例子(示例)- 至少在 developSystem 或 workSystem 跑通验证(§13)
别名配置(TS 版)
alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts'
首次使用:
cd $ccWorkDir/dacli && npm install
常用命令
# ⭐ v0.10+ 新会话必跑第一步:环境快照(消除盲猜参数/状态)
dacli app context --json # AI 必看 dbLinkId/existingEnCodes/草稿 vs 发布
dacli app login --account=admin --password=123456 --appCode=developSystem
dacli app status
dacli form list
dacli form info <表单ID> # 位置参数 (不是 --id=)
# v0.11+ 默认 ★ AI 快速建表单 (一条命令完整, 不建物理表):
dacli form create --ai-json='[{"tableTitle":"X","tableName":"X","isMain":true,"fields":[...]}]' \
--webType=1 --dbLinkId=<id> --autoRelease # type=1 (formDesign), dacli 自动 fallback schema
# v0.11+ 高级: 物理表已存在, 需要挂表单:
dacli dm create --table=X --tableName="中文名" --dbLinkId=<id> --fields='[...]' # 1. 物理表 (独立工具, 非 form 前置)
dacli form create --ai-json='[{"tableTitle":"X","tableName":"X","isMain":true,"fields":[...]}]' \
--dbLinkId=<id> --tables='[{...}]' --autoRelease # 2. form (--tables 显式引用)
# 注: v0.11+ 已删除 `dacli form lint/validate/fixcolumndata` 3 个旧命令 (webapi 镜像 + buildFormData 自动保证)
# 注: --fields 简化版已废弃, 改用 --ai-json (走 web 端 buildFormData, schema 自动完整)
dacli form create --fullName=X --enCode=Y --webType=4 # 数据视图 (无物理表, 兜底用)
dacli form create --fullName=X --enCode=Y --enableFlow=1 --flowId=<wfId> # 工作流表单
dacli form export <id> --out=file.json # 导出表单 (备份/迁移)
dacli form import <file> --enCode=X --name=Y # 导入表单 (从备份恢复)
# 仿造官方长尾示例:先查 dacli-ts/references/jnpf-design-rules.md §13 速查表找 ID,再:
# dacli app switch --appCode=workSystem
# dacli form info <示例ID> # 读完整结构 (formData/columnData/tables 等)
# dacli form info <示例ID> --expand-subtable # 主子表 ER 展开
dacli menu list
dacli tool logs --level=error --lines=50
dacli apis list --tag=visualdev # 查 JNPF API 列表
dacli apis info "GET /api/visualdev/Base/list" # 查 API 中文字段 (v0.7+ ✅ TS 版有, 递归展开 $ref)
dacli apis refresh # 强制重拉 OpenAPI (忽略 12h TTL)
dacli apis status # 看缓存状态 (pathCount/ageMs/loadedAt)
dacli app clear --app-code=tds --dry-run # 清除应用 (备份→history_bak 库; 实跑需 TTY+双重确认)
# v0.10+ 长任务自检(每 5 步跑一次,强制 TS 编译 + 后端错误日志)
bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/scripts/self-check.sh [form_id]
dacli help
dacli doc 命令(HTML 文档扫描, v0.7+ 2 子命令)
# 列文档索引(结构 + section 列表)
dacli doc list --dir=docs/tds
# 切片读取(v0.7+ 新 P0 上下文恢复核心, mtime 感知 SQLite 缓存 7 天 TTL)
dacli doc get --file=docs/tds/plan.html --section=h2_1 # 按 sidebar nav id 切片
dacli doc get --file=docs/tds/plan.html --from=200 --lines=50 # 按行号切片
dacli doc get --file=docs/tds/plan.html --strip-mermaid # 全文去 Mermaid
适用场景:上下文恢复时读取 plan.html/design.html/testcase.html,替代直接 Read 整个 HTML。
详细文档:.claude/skills/dacli-doc-cache/SKILL.md
dacli apis 命令(Swagger/OpenAPI 查询,AI 快速查 JNPF API)
从 JNPF /v3/api-docs 拉取全量 OpenAPI(含 1000+ API + 1159 个 schema),写本地缓存(PID 变化或 12h TTL 自动失效),AI 一次性掌握 JNPF 平台所有 API 拓扑。
# 列出接口(按 tag/method/keyword 过滤)
dacli apis list --tag=visualdev
dacli apis list --method=GET --keyword=用户
# 杀手特性:拿单 endpoint 详情 + 递归展开 $ref + 自动展开 ActionResult.data
dacli apis info "GET /api/visualdev/Base/list" # 含中文字段
dacli apis info "POST /api/permission/Users" --json
# 强制刷新 / 看状态
dacli apis refresh # 忽略 12h TTL 重拉
dacli apis status # 看 pathCount/ageMs
适用场景:写后端 / 调 API / 排查接口字段时直接查,避免手敲 curl 试探。
详细文档:.claude/skills/dacli-architecture/SKILL.md
dacli app clear 命令(清除应用 + 自动备份到 history_bak 库)
内化自 docs/tool/clear_app.py(v10.6),把 app 的本地文件 / pom 依赖 / yml 数据源 / 主库平台行 / 业务库表 / token 一次性清除,全部先备份:
- DB 备份:表 RENAME 到
history_bak库(业务库),或 CREATE LIKE+INSERT SELECT(主库平台表),命名D{yyyyMMddHHmmss}-{原表名},回滚就是反向 RENAME/INSERT - 文件备份:
docs/{app-code}/history-bak/{yyyyMMdd-HHmmss}/files/<相对路径>+pom-yml/+token.json - MANIFEST.txt:每个备份目录都有完整还原指引(rsync / cp / RENAME TABLE / INSERT SELECT)
# 预览 (无副作用, 无需 TTY, AI 也可调用看影响范围)
dacli app clear --app-code=tds --dry-run
# 实际执行 (必须在交互式 TTY 中, 必须双重人工确认 "tds" + "DELETE")
dacli app clear --app-code=tds
# 仅清本地文件 + 构建配置, 不动 DB
dacli app clear --app-code=tds --skip-db
# 清理后询问是否立即 initapp 重建 (推荐场景: tds 已删, 想从空白重新搭)
dacli app clear --app-code=tds --restart
# 清理成功后, 提示: "是否立即运行 `dacli app create` 重建一个新 app? [y/N]"
# Y → 再问 appCode/appName, 调子进程: npx tsx src/cli.ts app create --appCode=X --appName=Y --force-rebuild (TS v0.9+)
# N → 打印手动 create 用法
# --no-restart 跳过询问
# 注意: --no-restart 是 TS v0.9+ 新选项 (Java 版用 negatable --restart + fallbackValue="true")
严格安全约束(AI 必读):
- 真实执行强制 TTY(
System.console() != null),管道/Heredoc/重定向一律拒绝 - AI 助手严禁替操作员键入
app-code或DELETE完成确认 - AI 只允许:解释步骤 / 演示
--dry-run/ 协助回滚 - 误删数据由操作者承担
回滚示例(业务库表反向 RENAME):
CREATE DATABASE IF NOT EXISTS `tds`;
RENAME TABLE `history_bak`.`D20260610211904-tds_billing` TO `tds`.`tds_billing`;
-- 主库平台表反向 INSERT
INSERT INTO `j62`.`base_visual_dev` SELECT * FROM `history_bak`.`D20260610211904-base_visual_dev`;
Token 说明
- 存储路径:
$ccWorkDir/.dacli-token/token.json(运行时由 dacli TSsrc/core/token-store.ts写, 不是~/.dacli/)- ⚠️ 历史备注: Java 版 v10.6 时代由
DacliKit.java:41写死路径, TS 版后由$DACLI_TOKEN_DIR环境变量可覆盖(2026-06-05 fix)
- ⚠️ 历史备注: Java 版 v10.6 时代由
- 可用
$DACLI_TOKEN_DIR环境变量覆盖(2026-06-05 fix) - 有效期: 7天
- 快速定位:
dacli app status会输出 token 路径
当前应用 (app_code)
| # | 应用 | system_id | 说明 |
|---|---|---|---|
| 1 | developSystem | 664077319056394183 | 开发系统示例(21个表单/3个流程等) |
| 2 | workSystem | — | 工作系统示例(53个表单,含工作流) |
核心行为准则
1. CLI 使用 dacli
所有 JNPF 平台操作通过 dacli 命令。
2. DI 限制多,复杂需求走后端开发
DI SQL 有较多限制。扩展功能时触发 backend-dev 技能,在 ssw-{app_code} 业务模块创建后端代码。
2.5. 创建功能表单/主子表/工作流(2026-06-26 v0.11d update — 默认 ★ 场景 A AI 快速建表单)
✅ v10.6.1 / v0.11+ 已闭环 4 类盲点(无需重复提):
- BS-14:
dacli form create --autoReleasebare flag 现在正确生效(state=1)- BS-15:
dacli dm create自动补 9 列系统列- BS-16:
f_flow_id列修复 JNPF List API 返 0 问题- BS-8:
dacli app init --restart自动 kill+start+健康+重登
✅ 2026-06-26 v0.11d 改 (★ 默认场景 A, 不再推荐 dm→form 两步):
- type 默认值:
--type默认2(系统/sysForm) →1(自定义/formDesign)。tdd10 复盘:默认 type=2 是历史遗留错误,导致创建的表单出现在 sysForm 而非 formDesign。- AI 快速建表单一条命令完整:
dacli form create --ai-json --autoRelease默认走 formDesign Web 设计器构建 + 验证,不建物理表,dacli 自动 fallback schema。dm create 不再是 form create 的前置。- dm 命令定位重塑:从"form 前置步骤" → "独立物理表管理工具"(建库、迁移、import、挂载已有物理表)。
- BS-44 警告:默认禁用 fallback 警告(误报修正,旧版措辞"Database exception"已删)。
★ 场景 A — 默认推荐:AI 快速建表单(一条命令完整)
dacli form create --ai-json='[{
"tableTitle":"X","tableName":"X","isMain":true,
"fields":[{"field":"f_name","fieldTitle":"名称","dataType":"varchar","dataLength":"100"}]
}]' --webType=1 --dbLinkId=<id> --autoRelease
# type=1 (formDesign 列表) + state=1 + dacli 自动 fallback schema
# 后续: 在 formDesign Web 设计器拖拽调字段、加校验、设权限 → 浏览器端到端验证
场景 B — 高级:物理表已存在,需要挂表单
# 1. 建物理表 (dacli v10.6.1 自动补 9 系统列 + 2 PK)
dacli dm create --table=X --tableName="中文名" --dbLinkId=<id> --fields='[
{"field":"f_name","fieldName":"名称","dataType":"varchar","dataLength":"100","allowNull":0}
]'
# 2. form create --tables=... 显式引用已建好的物理表
dacli form create --ai-json='[{
"tableTitle":"X","tableName":"X","isMain":true,
"fields":[{"field":"f_name","fieldTitle":"名称","dataType":"varchar","dataLength":"100"}]
}]' --dbLinkId=<id> --tables='[{"table":"X","typeId":"1","fields":[{"dataType":"varchar","field":"f_name","fieldName":"名称","primaryKey":0,"allowNull":0}]}]' --autoRelease
注意:
--ai-json --autoRelease一条命令完整(场景 A 默认):少参数、错误少、用平台 Web 设计器构建和验证--tables降为高级选项(场景 B):仅在已存在物理表需要挂表单时使用dacli dm create独立:建库、迁移、import、挂载,不是 form create 的前置--autoReleasebare flag 现在生效(v10.6.1 fix),不需要--autoRelease=true- 场景 A 的 schema 是 dacli fallback 生成,DB 不存在该物理表,数据走 form 不入库;想持久化必须升级到场景 B
- v0.11+ 推荐
--ai-json路径:AI 描述 →List<AiFormModel>JSON → web 端 buildFormData → schema 自动完整 - v0.11+ 已删除 design-jnpf-execute 整个技能 + form lint/validate/fixcolumndata 3 个旧命令
--fields简化版已废弃(走 --ai-json, web 端 buildFormData 自动保证 50+ formConf keys)
2.5.1. dacli 是 webapi 完整规则体系镜像 (2026-06-26 v0.11d 基础原则)
核心: dacli 不是"单方法提交"的 CLI 工具, 而是 webapi 完整规则体系镜像 + 复用。每次提交触发完整的 web 端校验链 + 错误反馈 + 授权机制, 而不是绕过它们直接调单个 API。
这是对源码的最大尊重: web 端多年迭代沉淀的"有价值的机制" (校验规则 / 错误反馈 / 状态机 / 授权 / schema 生成 / 数据流), 都不是冗余代码, 都是 JNPF 业务规则的体现. dacli 必须复用而不是复刻或绕过.
web 端有价值的机制清单 (按复用优先级排序):
| 机制 | web 端位置 | dacli 复用状态 | 实现方式 |
|---|---|---|---|
| schema 生成 (buildFormData/buildFields) | web/.../formUtils.ts:14-77 |
✅ webapi import | webapi/_buildformdata.ts 直接 import |
| 校验规则 (vmodel 正则/控件必填/关联字段) | FormGenerator.getData():237-300 + ColumnDesign.getData():278 |
✅ step machine 镜像 (v0.11e+ 2026-06-28 加 billRule/relationForm/popupSelect/upload/树形 7 类校验) | form/_validate.ts:validateFormData/validateColumnData |
| 错误反馈 (validatePopoverRef + errorList 字段级定位) | Form.vue:419 validatePopoverRef.setVisible |
✅ JSON 结构化输出 | step machine 输出 {step, field, message} |
| 菜单自动授权 (Actions/Module 给当前角色授权) | VisualdevController.createModule |
✅ webapi 直调 | webapi/menu.ts |
| import/export 链路 (web 端 schema 导入导出) | web/.../api/visualDev.ts export/import |
✅ webapi | webapi/visualDev.ts |
| 基础信息校验 (validate + 必填 + 格式) | Form.vue:324 handleNext step 0 validate() |
✅ step machine 镜像 | form/_validate.ts:validateBasicInfo |
| 步骤间状态机 (handleNext step 0→1→2) | Form.vue:322-377 |
✅ step machine 状态机 | _validate.ts:validateFormCreate |
| 保存流校验 (handleSubmit) | Form.vue:404-466 |
✅ step machine | step 3 (create API) |
| dirty checking (form 是否被外部修改) | web 设计器 state.isReload |
❌ 未镜像 | 设计中 (v0.11d+) |
| 预览模式 (formDesign 实时预览) | web/.../FormPreview |
❌ 未镜像 | 设计中 (v0.11d+) |
| 代码生成 (form → 后端代码) | VisualdevGenController |
⚠️ dacli codegen 部分做 | 增强中 |
| 权限/数据权限 (role/dataAuthorize) | web permission/* |
⚠️ 部分 webapi | 增强中 |
| i18n 多语言 | web useI18n |
❌ 未复用 | 优先级低 |
| undo/redo | web 设计器 | ❌ CLI 不适用 | — |
| 缓存管理 (generatorStore) | web store |
❌ 未复用 | 优先级低 |
5 个核心要素 (实现机制复用的指导原则):
-
webapi import (引用): 不复刻 web 端业务规则, 直接 dynamic import web 端源码
webapi/_buildformdata.ts→ 直接 importweb/.../FormGenerator/src/helper/formUtils.ts的buildFormData/buildFields- 任何新 webapi 模块走
webapi/_loader.ts模式, 不复制 web 端 JS 逻辑 - 修改 web 端业务规则时, dacli 自动同步 (因为直接 import)
-
step machine 校验 (规则触发): 镜像 web 端多步骤校验流程, 每步独立捕获错误
- dacli form create step machine (3 step):
- step 0 基础信息 (镜像
Form.vue handleNext step 0:validate()+ tables 长度 +exist()子表外键) - step 1 formData 字段 (镜像
FormGenerator.getData()line 250-300) - step 2 columnData 列表 (镜像
ColumnDesign.getData()line 278)
- step 0 基础信息 (镜像
- 失败时不发 API, 错误反馈精准到 formId/字段名
- dacli form create step machine (3 step):
-
结构化错误反馈 (web 用
validatePopoverRef, dacli 输出 JSON):- 字段级定位 (
{step, field: formId, message}) - AI 不需要看完整错误日志就能定位
- 失败时输出
{ok: false, validation: steps}给--json模式
- 字段级定位 (
-
复用 web 端状态机 (handleNext 多步骤):
- 单次提交触发完整规则链 (不是单方法提交)
- 步骤间有依赖关系 (前一步失败不进入下一步)
- 与 web 设计器 UI 状态机对齐 (step 0/1/2)
-
不 mirror UI 行为: drag/drop/click handlers 不在 dacli 范围 (那是 web 设计器职责), 但 校验规则 / schema 生成 / 错误反馈 / 授权 镜像, 因为是 JNPF 业务规则不是 UI 行为
反模式 (必须避免):
- ❌ 单方法提交:
dacli form create直接调loadVisualDev.create()跳过所有前端校验 - ❌ 复刻 web 业务规则: 在 dacli 写
if (vmodel.match(/.../))而不是 import web 端VMODEL_REGEXP - ❌ 假装校验通过: API 返回 200 就 ✓, 不验证 schema 完整性
- ❌ 绕过 web 状态机: 跳过 handleNext 直接调 create API
对应 web 端代码位置 (权威规则源):
web/apps/jnpf-web-apps-main/src/components/FormGenerator/src/FormGenerator.vue:237-300Generator.getData()— 控件校验web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:322-377handleNext— 步骤间状态转换web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:404-466handleSubmit— 保存时校验web/apps/jnpf-web-apps-main/src/components/ColumnDesign/src/components/Main.vue:278-282getData()— 列表字段校验 (BS-50)web/apps/jnpf-web-apps-main/src/components/FormGenerator/src/helper/formUtils.ts:14-77buildFields/buildFormData— schema 生成
复用全景图 (未来扩展):
- ✅ form create → step machine + webapi (已实现)
- ⚠️ form update → 镜像 dirty checking + 增量校验 (设计阶段)
- ⚠️ menu create --formId → 镜像 Actions/Module 完整流程 (已部分实现, 加 step machine)
- ⚠️ dm create → 镜像 dm/Index step machine: 字段白名单 + 9 系统列 + PK 策略 (设计阶段)
- ⚠️ workflow create → 镜像 flowDesign step machine: 节点完整性 + onLineformId 关联 (设计阶段)
- ⚠️ dict typeCreate → 镜像 dict/Index step machine: enCode 全平台唯一 (设计阶段)
- ⚠️ form preview → 复用 web FormPreview 组件 (设计阶段)
- ⚠️ form codegen → 增强复用 web VisualdevGenController (增强中)
Why: 单方法提交绕过 web 端规则, AI 必须去浏览器试错才能发现 "列表字段不允许为空" 这种问题. 完整规则链镜像让 dacli 一次提交就能暴露所有问题, 闭环. 同时避免 v0.11+ 反思的"复刻 + 偏移"陷阱.
How to apply: 新增任何 dacli create/update 命令时, 必读 web 端对应页面源码, 找出 (1) handleSubmit/handleNext/getData 校验链 (2) 状态机 (3) 错误反馈机制 (4) 授权/数据流, 在 dacli 镜像 step machine 或 webapi 直调, 不直接调单个 API. 这是对源码的最大尊重.
2.6. 完善 dacli 优先(异常停下派子代理)
主任务中遇到 dacli 任何异常(命令报错、参数缺失、返回结构不对、文档与代码脱节、token 过期、JNPF API 变更等),立即停下当前任务,派子代理修复 dacli 后再继续。
禁止行为:
- ❌ 在主任务里打补丁绕过去(curl 调 JNPF / 临时 Python 脚本 / 调低层 API)
- ❌ "先记下来下次修"——主任务已被 workaround 污染
- ❌ 改 web/ 源码绕过 dacli 缺陷(违反 §15 代码修改权限)
- ❌ 替操作员键入确认信息(违反 §dacli app clear 安全约束)
正确做法:
- ✅ 停主任务,保留重现步骤 + 期望输出 + 实际输出
- ✅ 派子代理到
$ccWorkDir/dacli/修复(修命令 / 修.claude/skills/dacli-ts/文档 / 修webapi/模块) - ✅ 在 developSystem / workSystem 跑通验证后再回到主任务(§13)
- ✅ 记入 MEMORY(盲点编号 + dacli 候选)
为什么:workaround 是 dacli 永远补不齐的债务;不修复会让下一轮 AI 重新踩同样的坑。
2.7. web/ 源码优先(JNPF/dacli 参数唯一权威)
任何 JNPF 或 dacli 相关参数、API 路径、默认值、校验逻辑,必须优先从 web/ 源码提取。
优先级排序:
web/apps/jnpf-web-apps-main/src/views/onlineDev/— 可视化设计器(form / list / 弹窗的__config__渲染规则)web/apps/jnpf-web-apps-main/src/api/— API 调用(method / path / params / body schema)jnpf/后端源码 — 仅当 web/ 没有时(运行时行为 / 隐藏默认值)- ❌ 不读 dacli 文档 / MEMORY / 历史经验推断——这些可能过时
为什么:JNPF 平台每年迭代几十次,dacli 文档和 MEMORY 落后于 web/ 源码是常态。从过时文档推断的参数 = 盲点根因 B/C/D(盲猜参数/状态)。
实践工具:dacli/src/webapi/_loader.ts(v0.11+ 直接 dynamic import web 端源码)、dacli apis info(递归展开 $ref + 自动展开 ActionResult.data)。
2.7.1. dacli 改动 4 步流程(强制纪律,2026-06-26 v0.11d+)
架构前提: dacli 不是单方法提交工具, 而是 webapi 完整规则体系镜像 + 用户浏览器操作模拟. 所以任何改动必须先读 web 源码 + 后端源码, 不能猜.
漂移主因: 绕开"读源码"就开始改 dacli → 错位累积 → 偏离 web 真实行为. 2026-06-26 session 4 次 user "没读源码"提醒都源于此.
4 步流程 (缺一不可, 跳过任何一步都算违规):
-
读源码 (前置)
- web 端:
web/.../views/.../Form.vue+web/.../components/FormGenerator/+web/.../components/ColumnDesign/+web/.../helper/formUtils.ts+web/.../CommonModal/DataSetModal/TableConfigDrawer.vue - 后端:
jnpf/.../VisualdevController.java(create / publish) +VisualdevServiceImpl.java(createTable / getPrimaryDbField) +VisualDevTableCre.java - 输出: 完整数据流 (state mutation → submit → backend → DB), 标注行号
- web 端:
-
理解意图 (不只读代码)
- 用户浏览器操作流 (handleNext step 0/1/2 各自做什么)
- 哪些 state mutation 触发表单变化 (FormAttrPane.onTableNameChange 等)
- 哪些校验在哪一步跑 (validate / Generator.getData / ColumnDesign.getData)
- 哪些后端逻辑负责建表/保存 (publish line 628-635 createTable)
- 输出: 设计意图 (commit message 或 design doc 段落)
-
镜像设计 (基于理解, 不是猜测)
- web schema 生成 (buildFormData/buildFields) → webapi import (不写 JS)
- web 用户输入 (FormAttrPane.onTableNameChange) → dacli 模拟 (例:
formData.tableName = cleanTable55) - web 状态机 (handleNext step 0/1/2) → dacli step machine
- web 提交 (handleRequest 1 次 API) → 1 次 create API (不拆)
- web 发布 (Actions/Release) → 1 次 release API (autoRelease)
- 后端自动建表 (publish line 628-635) → 触发 publish → 后端从 formData.fields 推 schema
-
实现 + 文档同步 (不后置)
- 代码:
dacli/src/... --help: Commander.js 注解, 描述"为什么这样设计" + "对应 web 端什么行为"- SKILL.md / references/: AI 学习材料, 标注 web + 后端行号
- MEMORY: drift 防御, 记录"为什么这样设计" + 复用代码行号
- 一次提交完整提交, 不分批
- 代码:
反模式 (必须避免):
- ❌ 猜测先行: 先猜 web 行为 → 写 dacli → 跑测试 → 失败 → 找根因 (drift 主因)
- ❌ 增量修补: user 提示 → 修一个点 → 引入新问题 → 再修
- ❌ 文档后置: 写完代码才补文档, AI 看不到"为什么"
- ❌ --help 不更新: dacli 用法变化但 help 没改
自检清单 (改前必答):
□ 1. 我读了哪个 web 端源文件? 行号是?
□ 2. 我读了哪个后端源文件? 行号是?
□ 3. web 端的状态流转 + 后端校验都理解了吗?
□ 4. 用户浏览器操作流我能讲清楚吗? (handleNext step 0/1/2)
□ 5. 我为什么用 mirror JS 而不是 webapi import? (或反之)
□ 6. --help 描述更新了吗? 含 "对应 web 端什么行为"?
□ 7. SKILL.md / references/ 同步了吗?
□ 8. MEMORY 记录这次的"为什么这样设计"了吗?
为什么: dacli 改一次错, AI 长期按错的指令跑, drift 累积到后面要花几倍精力修. 而 4 步流程 5-10 分钟读完源码, 一次性写对, 长期省成本.
详细记录: MEMORY dacli-source-first-discipline-2026-06-26.md (含 2026-06-26 session 的 4 个反例: type 默认 / columnList 来源 / formData.tableName / --tables 路径)
3. 建表命名规范
- 表名:
snake_case,无前缀 (dacli dm create --table=jxcj_xxx自动去jxcj_前缀 →xxx,CLAUDE.md 强制) - 字段名:
f_前缀 + snake_case - 注意:
f_version是系统关键字,不能使用
3.5. 类名 PascalCase(无 appCode 前缀,2026-06-24 闭环)
- Java 类名:
PascalCase(不重复 appCode,包名已带)- 表
jxcj_announcement+ 包ssw.jxcj.entity→ 类AnnouncementEntity(非JxcjAnnouncementEntity)
- 表
- 字段名同表名(
f_user_name→userNamegetter/setter) - dacli 自动推导:
dacli form codegen <id> --module=jxcj --mainClassName=DevelopProject一条命令搞定--auto-alias默认 ON(写base_visual_alias,JNPF 用别名生成 PascalCase 类名)- 关闭:
--no-auto-alias - 默认从 enCode 推导 mainClassName,PascalCase + 丢 appCode 前缀
- web/uniapp 文件名小写(
Detail.vue→detail.vue,对齐现有jxcj/TeamInfo/detail.vue约定)
3.6. ssw-common 共享 MapperConfig(2026-06-24 BS-14 集中化)
- JNPF
MybatisPlusConfig的@MapperScan只扫jnpf.*.mapper/jnpf.mapper/com.xxl.job.admin.dao,不扫 ssw.*.mapper - 共享
ssw-common/ssw-common-biz/.../config/SswMapperConfig.java:@MapperScan("ssw.**.mapper")一处覆盖所有 ssw 包 - 业务包
ssw-{app_code}-biz/pom.xml只需加ssw-common-biz依赖,零 MapperConfig 配置 - 检测:
python3 .claude/skills/ssw-pack-init/scripts/check_ssw_pack.py {app_code}→ BS-14 PASS
4. dacli 自动登录
首次执行时自动登录,后续命令复用登录状态。切换 appCode 自动重新登录。
5. dbLinkId 默认规则
涉及数据库链接的命令(dm/form create/di create),默认使用当前应用的业务库(从 token.json 读取 dbLinkId),传 dbLinkId=default 表示主库(平台库)。
6. relationForm 必须用关联控件
关联字段必须用 relationForm 组件,禁止用 input 文本框代替。relationForm 的 columnOptions ≤ 5 列,否则弹窗列表无法正常显示。
7. UI 组件库:Ant Design Vue
JNPF 平台使用 Ant Design Vue,禁止使用 Element Plus! 混用会导致样式冲突或组件不生效。
8. 后端 Java 8
jnpf-admin 仅支持 Java 8,后端代码禁止使用 Java 11+ 特性(如 var、records、text blocks)。
9. 默认凭据 admin / 123456
- 浏览器登录 / dacli app login / E2E 测试统一用
admin/123456 - 不再用
<密码>占位符(除非要换密码) - 不写到 MEMORY 或 skill(防下轮被"清理"时误删)
10. nginx 不可用 fallback
- 默认入口
http://nginx/,nginx 容器挂了或外部不可达时 fallback:- 后端:
http://127.0.0.1:30000 - 前端:
web/apps/jnpf-web-apps-main/dist/或web/apps/jnpf-web-apps-main/public/
- 后端:
- 验证方法:
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:30000/→ 200 - 前端无 nginx 时:
python3 -m http.server 8080 --directory web/apps/jnpf-web-apps-main/dist &
11. 不在 CLAUDE.md / 技能里写应用特定信息
- 通用规则 / 命令用法 / 注意事项 → 写 CLAUDE.md / skill 主 SKILL.md
- 应用特定(form ID / 菜单结构 / DB 凭证 / 字段名 / 修复记录 / 起点-终点表 / 加速比)→ 写
docs/{app_code}/或 MEMORY - 下轮"清理 docs/"时这些应用信息会删,不能入 CLAUDE.md / skill
- 应用特定 vs 通用判别: 换一个应用(如 workSystem → tds)能否直接用? 能 → 入 skill;不能 → 入 docs/{app_code}/
12. 主 skill 文件不搞大
- 主 SKILL.md 只保留"规则/用法/注意项"
- 详细参考/长文/prompt 模板/工具使用文档 →
references/<子文档>.md - 判定阈值: SKILL.md > 800 行 → 检查低频内容抽出
- 主 SKILL.md 不放"未来 todo" / "项目计划" / "起点状态表" → 这些放
references/<version>-todo.md或 polish doc
13. 复现的盲点固化前先验证
- 发现重复出现的 bug / 盲点 → 想"固化到 dacli 命令或技能"
- 先在测试 app(developSystem / workSystem)或 tds 跑通验证 → 写最小复现命令 + 期望输出
- 验证通过 → 才提交到 dacli 源码 / 技能主 SKILL.md
- 没复现验证的"理论修复" → 不入主代码,只入 polish doc 备查
14. 一轮一提交(git hooks 已注册)
- 改完一段就
git add -A && git commit -m "..."+ push - 本仓库 git 在
.claude/目录(非顶层),auto-push hook 已注册 - 验证:
git log -3 --oneline看到 "auto(session end) @ {时间}" 即钩子工作 - 手动补提交:
git add -A && git commit -m "描述" && git push origin main - 不要累积 N 轮改动一次提(出问题难回滚)
项目结构
$ccWorkDir/
├── .claude/
│ ├── CLAUDE.md # 本文件
│ └── skills/ # 技能定义 (含 dacli-ts 教 AI 何时用哪个命令)
├── boot/ # 后端 Spring Boot
│ ├── jnpf-admin/ # 主模块
│ └── ssw-{app_code}/ # 业务模块
├── dacli/ # ✅ TS 版 dacli (v0.7, 0 差错 baseline)
│ ├── src/ # CLI 源码 (npx tsx src/cli.ts)
│ ├── tests/ # vitest + Playwright
│ ├── doc/ # 架构/plan/api/extractors 等文档
│ ├── .claude/skills/dacli-ts/ # 教 AI 何时用哪个命令
│ └── package.json
├── web/ # 前端 Vue3
├── test/ # E2E测试 (Playwright)
├── jnpf/ # jnpf开发平台源代码
├── docs/ # 文档
│ ├── {app_code}/ # 应用文档(HTML输出)
│ │ ├── assets/ # CSS/JS/Mermaid
│ │ ├── design.html # 详细设计方案
│ │ ├── testcase.html # 测试用例
│ │ ├── plan.html # 开发计划(上下文恢复用)
│ │ ├── debug.html # 问题记录
│ │ └── summary.html # 总结报告
│ └── dacli/
│ └── ssw-dacli/ # 📦 Java 版 dacli 归档(已废弃, 仅备查, 无 target/)
常用命令
# 编译打包
cd $ccWorkDir/boot && mvn clean package -DskipTests
# 启动 JNPF(Web服务,端口30000)
java -jar jnpf-admin/target/jnpf-admin-*.jar --spring.profiles.active=dev
# dacli 使用(TS 版)
alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts'
cd $ccWorkDir/dacli && npm install # 首次需装依赖
dacli app login --account=admin --password=123456 --appCode=developSystem
# E2E测试(playwright Node.js)
cd $ccWorkDir/test && npx playwright test --project=chromium
技能索引
🧹 v0.11+ 收纳 (2026-06-27): 原 12 个独立技能(form-development / menu-configuration / workflow-development / dict-management / data-management / data-interface / data-screen / code-generator / platform-mechanism / api-test / ai-debug-export / ai-debug-import / troubleshooting)已全部收纳到
dacli-ts技能 + references/ 体系。 判定标准: 单命令说明书被dacli X --help替代;JNPF 平台机制进dacli-ts/references/platform-mechanisms.md;JNPF 设计规则进dacli-ts/references/jnpf-design-rules.md;formData 深 schema 进dacli-ts/references/form-data-model.md。
| 技能 | 触发词 | 用途 |
|---|---|---|
| dacli-ts | dacli / JNPF CLI / form / menu / workflow / dict / dm / di / bigscreen / portal / role / log | JNPF 单命令入口(22 父命令 / 116 子命令 + 5 要素 + step machine + 错误码 + 9 个 references) |
| ssw-h5dev-flow | ssw-h5dev-flow | H5开发主流程(v0.11g+, 7阶段 + 4关卡 CI + 子代理派发, 模板+脚本在 skill 目录) |
| ssw-onlinedev | ssw-onlinedev | 快速创建在线功能表单(自动发布) |
| ssw-code-gen | ssw-code-gen | JNPF代码生成与菜单挂载 |
| ssw-e2e-test | ssw-e2e-test | E2E测试(基于Playwright + dacli, 含 ssw-test 已并入) |
| ssw-pack-init | ssw-pack-init | boot模块编译打包 |
| backend-dev | backend-dev | 后端业务类开发 |
| frontend-dev | frontend-dev | 复杂前端页面开发 |
| no-spa-page | no-spa-page | JNPF独立页面/非SPA页面开发 |
| mmx-cli | mmx-cli | mmx-cli技能 |
| jnpf-browser-automation | jnpf-browser-automation | JNPF浏览器自动化 |
| webapp-testing | webapp-testing | Web应用测试 |
开发流程(ssw-h5dev-flow)
使用 /ssw-h5dev-flow 进行完整功能开发,7个阶段 + 4 关卡 CI:
初始化(dacli app init) → 设计(design.html+testcase.html) → 审核 → 执行(子代理派发,1 form=1代理) → 测试(TC-A→TC-C→TC-B三层 ladder) → 总结(关卡 B 防假 PASS)
4 关卡 CI(写在 .claude/skills/ssw-h5dev-flow/scripts/):
- 关卡 A
check_required_docs.sh- 5 HTML 必填 (design/testcase/plan/debug/summary) - 关卡 B
check_summary_no_fake_pass.sh- 4 铁律 (按钮存在性/skip modal≠PASS/CREATE failed≠PASS/截图去重) - 关卡 C
check_subagent_learnings.sh- 子代理 learnings.md 强制写入 - 关卡 F
check_html_assets.sh- HTML 必引../_assets/style.css不内联
模板/参考/脚本全部在 skill 目录, 零应用信息硬编码, 用
dacli app context --json动态获取.
HTML 输出规范
所有设计/计划/测试/总结文档输出为 HTML 格式到 docs/{app_code}/:
- plan.html 每完成一个关键步骤立即更新,会话中断后第一件事读取它恢复上下文
- design.html 详细设计,testcase.html 测试用例
问题处理
- dacli tool logs --level=error 查看后端日志
- dacli app status 确认登录状态
- 使用技能进行业务开发
- 使用 ssw-h5dev-flow 进行完整功能开发
dacli 常见问题恢复
- code 600:先检查 API 地址是否正确(
dacli app status看 baseUrl),再查 JNPF 是否启动,最后才是 token 过期 dacli app status检查登录状态和当前 app_codedacli app login --account=admin --password=123456 --appCode=<app>重新登录(token 7天过期)dacli form list确认表单已发布(state=1)dacli menu list确认菜单 systemId 匹配当前应用dacli form list验证 API 可用性(curl + jq 详见dacli-ts/references/commands.md)- JNPF 下线恢复(v10.6.1+):
dacli app init -- --appCode=<app> --restart自动 kill+nohup+健康检查+重登(JNPF 状态由dacli.conf的jar-pattern/port匹配;详见docs/dacli/2/dacli-conf-usage.md) - dm list 400 "Database connection failed"(盲点 8 场景 2.5):
dacli app init -- --appCode=<app> --force-rebuild --restart一条命令搞定 C.5.8 三步法 dacli tool logs --level=error --lines=100查看最近错误- dict typeCreate "The name cannot be repeated"(盲点 47):全平台唯一,enCode 和 fullName 都查重。先
dacli dict dataList看已有字典,复用或加<app>_前缀 - form create "Database exception"(盲点 48):必传
--tables='[{table,tableName,fields}]',dacli 自动推导的 tables 简化版缺 use*Permission 等关键字段 - form create "Encoding cannot be repeated"(盲点 49):失败残留 enCode 占用,二选一:改名加
_v2/form delete重建 - menu create --formId "主表不存在"(盲点 50):form schema 缺主表信息时走低级模式
dacli menu create --type=3 --urlAddress=model/{enCode} --parentId=... - 浏览器层 list 白屏(盲点 51):dacli 简化 columnList 缺完整字段,二选一:①
dacli form info <workSystem_form_id>拉完整 schema ② 用 no-spa-page 静态 HTML 兜底
JNPF 关键机制
App-Code 多应用
请求头 App-Code: {app_code} → 后端解析 systemId → 自动写入表单/菜单
webType 类型
| 值 | 说明 |
|---|---|
| 1 | 仅表单 |
| 2 | 表单+列表 |
| 3 | 表单列表(树) - 可绑定工作流 |
发布流程
create(state=0) → release(state=1) → 创建菜单 → 前端可见
db_link_id 说明
| 值 | 说明 |
|---|---|
"0" |
主库(平台库) |
"非0" |
业务库 |
代码修改权限
- ✅
.claude/boot/docs/ - ❌ JNPF 平台源码 (
jnpf/web/uniapp/) 禁止修改 - ✅
web/apps/jnpf-web-apps-main/src/views/ssw特别授权可修改