Files
claude-config/CLAUDE.md
T

43 KiB
Raw Blame History

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 验证步骤:

  1. curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:30000/ → 应 200
  2. ls 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(长任务副作用):

  1. dacli app context 命令(P0.1):AI 新会话必跑的环境快照(appCode/dbLinkId/token/existingEnCodes/草稿 vs 发布/表/菜单)
  2. 三层防御体系:L1 _precheck.ts 静态检查 + L2 _blindspot_guards.ts 22 条运行时 guard + L3 client.diagnoseError() 错误诊断
  3. web/ 源码权威参照:SKILL.md 顶部强制规则——参数/API 不确定时,优先读 web/.../views/onlineDev/ + web/.../api/,不读 dacli 文档
  4. web-source-map.md:dacli 命令 → web/ 源码精确定位速查表(149 行)
  5. form-type-rules.json (已删除 v0.11+):7 个 type×webType 合法组合 + 6 类常见错误(从 web/ 源码提取,非凭空编写)— 现由 webapi/_buildformdata.ts 直接 import web 端 buildFormData 内置规则保证
  6. webapi/ 镜像架构 (v0.11+):dacli/src/webapi/_loader.ts 直接 dynamic import web/.../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/testSendMail
  • integration smsTest → /message/AccountConfig/testSendSms
  • integration webhookTest → /message/AccountConfig/testSendWebhook
  • msg 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
  1. 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 TS src/core/token-store.ts 写, 不是 ~/.dacli/)
    • ⚠️ 历史备注: Java 版 v10.6 时代由 DacliKit.java:41 写死路径, TS 版后由 $DACLI_TOKEN_DIR 环境变量可覆盖(2026-06-05 fix)
  • 可用 $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 类盲点(无需重复提):

  1. BS-14: dacli form create --autoRelease bare flag 现在正确生效(state=1)
  2. BS-15: dacli dm create 自动补 9 列系统列
  3. BS-16: f_flow_id 列修复 JNPF List API 返 0 问题
  4. BS-8: dacli app init --restart 自动 kill+start+健康+重登

✅ 2026-06-26 v0.11d 改 (★ 默认场景 A, 不再推荐 dm→form 两步):

  1. type 默认值:--type 默认 2 (系统/sysForm) → 1 (自定义/formDesign)。tdd10 复盘:默认 type=2 是历史遗留错误,导致创建的表单出现在 sysForm 而非 formDesign。
  2. AI 快速建表单一条命令完整:dacli form create --ai-json --autoRelease 默认走 formDesign Web 设计器构建 + 验证,不建物理表,dacli 自动 fallback schema。dm create 不再是 form create 的前置。
  3. dm 命令定位重塑:从"form 前置步骤" → "独立物理表管理工具"(建库、迁移、import、挂载已有物理表)。
  4. 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 的前置
  • --autoRelease bare 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 个核心要素 (实现机制复用的指导原则):

  1. webapi import (引用): 不复刻 web 端业务规则, 直接 dynamic import web 端源码

    • webapi/_buildformdata.ts → 直接 import web/.../FormGenerator/src/helper/formUtils.ts 的 buildFormData / buildFields
    • 任何新 webapi 模块走 webapi/_loader.ts 模式, 不复制 web 端 JS 逻辑
    • 修改 web 端业务规则时, dacli 自动同步 (因为直接 import)
  2. 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)
    • 失败时不发 API, 错误反馈精准到 formId/字段名
  3. 结构化错误反馈 (web 用 validatePopoverRef, dacli 输出 JSON):

    • 字段级定位 ({step, field: formId, message})
    • AI 不需要看完整错误日志就能定位
    • 失败时输出 {ok: false, validation: steps} 给 --json 模式
  4. 复用 web 端状态机 (handleNext 多步骤):

    • 单次提交触发完整规则链 (不是单方法提交)
    • 步骤间有依赖关系 (前一步失败不进入下一步)
    • 与 web 设计器 UI 状态机对齐 (step 0/1/2)
  5. 不 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-300 Generator.getData() — 控件校验
  • web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:322-377 handleNext — 步骤间状态转换
  • web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:404-466 handleSubmit — 保存时校验
  • web/apps/jnpf-web-apps-main/src/components/ColumnDesign/src/components/Main.vue:278-282 getData() — 列表字段校验 (BS-50)
  • web/apps/jnpf-web-apps-main/src/components/FormGenerator/src/helper/formUtils.ts:14-77 buildFields / 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/ 源码提取。

优先级排序:

  1. web/apps/jnpf-web-apps-main/src/views/onlineDev/ — 可视化设计器(form / list / 弹窗的 __config__ 渲染规则)
  2. web/apps/jnpf-web-apps-main/src/api/ — API 调用(method / path / params / body schema)
  3. jnpf/ 后端源码 — 仅当 web/ 没有时(运行时行为 / 隐藏默认值)
  4. ❌ 不读 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 步流程 (缺一不可, 跳过任何一步都算违规):

  1. 读源码 (前置)

    • 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), 标注行号
  2. 理解意图 (不只读代码)

    • 用户浏览器操作流 (handleNext step 0/1/2 各自做什么)
    • 哪些 state mutation 触发表单变化 (FormAttrPane.onTableNameChange 等)
    • 哪些校验在哪一步跑 (validate / Generator.getData / ColumnDesign.getData)
    • 哪些后端逻辑负责建表/保存 (publish line 628-635 createTable)
    • 输出: 设计意图 (commit message 或 design doc 段落)
  3. 镜像设计 (基于理解, 不是猜测)

    • 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
  4. 实现 + 文档同步 (不后置)

    • 代码: 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 → userName getter/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 测试用例

问题处理

  1. dacli tool logs --level=error 查看后端日志
  2. dacli app status 确认登录状态
  3. 使用技能进行业务开发
  4. 使用 ssw-h5dev-flow 进行完整功能开发

dacli 常见问题恢复

  • code 600:先检查 API 地址是否正确(dacli app status 看 baseUrl),再查 JNPF 是否启动,最后才是 token 过期
  • dacli app status 检查登录状态和当前 app_code
  • dacli 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) → 创建菜单 → 前端可见

值 说明
"0" 主库(平台库)
"非0" 业务库

代码修改权限

  • ✅ .claude/ boot/ docs/
  • ❌ JNPF 平台源码 (jnpf/ web/ uniapp/) 禁止修改
  • ✅ web/apps/jnpf-web-apps-main/src/views/ssw 特别授权可修改