diff --git a/.DS_Store b/.DS_Store index b413b01..c30f447 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/CLAUDE.md b/CLAUDE.md index 10a4cd2..8f976ca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,8 @@ ## 统一入口(nginx) +**默认入口**: `http://nginx/`(容器内自动解析) + | URL | 目标 | |-----|------| | `http://nginx/` | 前台首页 | @@ -13,6 +15,22 @@ | `http://nginx/ssw/{app}/` | 静态扩展页面 | | `http://nginx/api/` | 后端API | +**默认凭据**: `admin` / `123456`(dacli login / JNPF 浏览器登录通用) + +**nginx 不可用 fallback**(容器外或 nginx 挂了时): + +| 服务 | 备用入口 | 备注 | +|------|----------|------| +| 后端 API | `http://127.0.0.1:30000` | JNPF admin 端口(`dacli 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` → 存在则前端已编译 +> 3. `python3 -m http.server 8080 --directory web/apps/jnpf-web-apps-main/dist &` → 本地访问 `http://127.0.0.1:8080` +> 4. 浏览器/curl 验证 JNPF 主页能加载(不依赖 nginx 容器) + --- ## CLI 使用(dacli) @@ -38,7 +56,7 @@ alias dacli='java -jar $ccWorkDir/boot/ssw-dacli/target/ssw-dacli-*.jar' ### 常用命令 ```bash -dacli login --account=admin --password=<密码> --appCode=developSystem +dacli login --account=admin --password=123456 --appCode=developSystem dacli status dacli form list dacli form info --id=<表单ID> @@ -254,6 +272,43 @@ python3 .claude/skills/design-jnpf-execute/scripts/create_workflow_form.py # 工 ### 8. 后端 Java 8 jnpf-admin **仅支持 Java 8**,后端代码禁止使用 Java 11+ 特性(如 `var`、records、text blocks)。 +### 9. 默认凭据 admin / 123456 +- 浏览器登录 / dacli 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/-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 轮改动一次提(出问题难回滚) + --- ## 项目结构 @@ -296,7 +351,7 @@ java -jar jnpf-admin/target/jnpf-admin-*.jar --spring.profiles.active=dev # dacli 使用 alias dacli='java -jar $ccWorkDir/boot/ssw-dacli/target/ssw-dacli-*.jar' -dacli login --account=admin --password=<密码> --appCode=developSystem +dacli login --account=admin --password=123456 --appCode=developSystem # E2E测试(playwright-cli) cd $ccWorkDir/test && playwright-cli test --project=chromium @@ -354,7 +409,7 @@ cd $ccWorkDir/test && playwright-cli test --project=chromium ### dacli 常见问题恢复 - **code 600**:先检查 API 地址是否正确(`dacli status` 看 baseUrl),再查 JNPF 是否启动,最后才是 token 过期 - `dacli status` 检查登录状态和当前 app_code -- `dacli login --account=admin --password=<密码> --appCode=` 重新登录(token 7天过期) +- `dacli login --account=admin --password=123456 --appCode=` 重新登录(token 7天过期) - `dacli form list` 确认表单已发布(state=1) - `dacli menu list` 确认菜单 systemId 匹配当前应用 - `dacli form list` 验证 API 可用性(curl + jq 详见 `api-test` 技能) diff --git a/skills/dacli-architecture/references/dacli-conf-usage.md b/skills/dacli-architecture/references/dacli-conf-usage.md new file mode 100644 index 0000000..df48e88 --- /dev/null +++ b/skills/dacli-architecture/references/dacli-conf-usage.md @@ -0,0 +1,140 @@ +# dacli.conf 配置文件使用文档 (v10.6.1) + +> **来源**: 从 `docs/dacli/2/dacli-conf-usage.md` 融合到本技能。 +> **何时读**: 用 `dacli initapp --restart` 需要配置 jar 匹配模式 / 端口 / 健康检查端点时。 + +--- + +## 0. 快速开始 + +```bash +# 1. 复制模板到项目根 +ls /home/ubuntu/ccWorkDir/dacli.conf +# 已存在则跳过 + +# 2. 编辑配置(按需) +vim /home/ubuntu/ccWorkDir/dacli.conf + +# 3. 一条命令完成 initapp + 自动重启 +dacli initapp -- --appCode=tds --appName="可信数据空间" --force-rebuild --restart +``` + +--- + +## 1. 查找顺序 + +`dacli` 按优先级找 dacli.conf: + +1. **`--dacliConf `** 命令行参数(最高优先) +2. **`$DACLI_CONF`** 环境变量 +3. **`$ccWorkDir/dacli.conf`** 项目根 +4. **`~/.dacli/dacli.conf`** 用户级 + +找不到时返内置默认值(jar-pattern=`jnpf-admin-.*-RELEASE\.jar`, port=30000, health-url=/, wait-seconds=90, poll-interval=5),不报错。 + +--- + +## 2. 配置项详解([jnpf] 段) + +| Key | 默认 | 说明 | +|-----|------|------| +| `jar-pattern` | `jnpf-admin-.*-RELEASE\.jar` | JNPF 进程匹配正则(pgrep -f 用,`\.` 要转义)| +| `port` | `30000` | HTTP 端口(lsof -ti + 健康检查)| +| `health-url` | `/` | 健康检查端点(GET )| +| `start-log` | `/tmp/jnpf-restart.log` | 启动日志路径(nohup `&> {start-log}`)| +| `wait-seconds` | `90` | 等待健康检查通过的最大秒数 | +| `poll-interval` | `5` | 健康检查轮询间隔(秒)| +| `start-cmd` | (空 = 默认)| 自定义启动命令模板,占位符 `{jar}` `{port}` `{log}` `{yml}` | + +--- + +## 3. 默认 start-cmd + +```bash +nohup java -Dfile.encoding=utf8 \ + -Djava.security.egd=file:/dev/./urandom \ + -jar {jar} \ + --spring.profiles.active=dev \ + &> {log} & +``` + +自动 `ls -t boot/jnpf-admin/target/ | grep 'jnpf-admin-.*\.jar$' | head -1` 找最新 jar。 + +--- + +## 4. 自定义 start-cmd 示例 + +```ini +[jnpf] +# 示例 1: 自定义 JVM 参数 + 指定端口 +start-cmd = nohup java -Xms1g -Xmx2g -jar {jar} --server.port={port} > {log} 2>&1 & + +# 示例 2: 启动多个服务 +start-cmd = nohup java -jar {jar} > {log} 2>&1 & nohup redis-server --port 6379 > /tmp/redis.log 2>&1 & + +# 示例 3: 自定义 yml 路径 +start-cmd = nohup java -jar {jar} --spring.config.additional-location=file:{yml} > {log} 2>&1 & +``` + +--- + +## 5. 端到端流程 + +`dacli initapp --restart` 触发: + +``` +1. 健康检查 (curl http://127.0.0.1:{port}{health-url}) + ↓ 不健康 +2. pgrep -f '{jar-pattern}' 找旧 PID + ↓ 有 PID +3. lsof -ti:{port} 二次确认端口占用 +4. kill + 等待退出(最多 10s) +5. ls -t boot/jnpf-admin/target/ | grep 找最新 jar +6. nohup & 启动 +7. 轮询 health-url(间隔 {poll-interval}s,最多 {wait-seconds}s) + ↓ 200 +8. 继续 initapp 7 步骤 + 自动重登 +``` + +--- + +## 6. 跨项目复用 + +复制 `dacli.conf` 到新项目根,改 `jar-pattern` 和 `port`: + +```bash +# 例如新项目用 jnpf-app-server-1.0.jar + 端口 31000 +cat > /path/to/new-project/dacli.conf <<'CONF' +[jnpf] +jar-pattern = jnpf-app-server-1\.0\.jar +port = 31000 +health-url = /actuator/health +start-log = /tmp/jnpf-app-restart.log +CONF + +cd /path/to/new-project +dacli initapp -- --appCode=newapp --appName="新应用" --restart +``` + +--- + +## 7. 故障排查 + +| 现象 | 可能根因 | 修复 | +|------|---------|------| +| `没找到匹配 的旧进程` | 进程名与正则不匹配 | 检查 `pgrep -f ''` | +| `没找到 jnpf-admin-*.jar` | 没 `mvn package` | `cd boot && mvn package -pl jnpf-admin -DskipTests` | +| `健康检查超时` | JVM 启动慢 / 端口被占 | 加大 `wait-seconds` 或 `tail -f {start-log}` 看启动日志 | +| `lsof 找不到 port` | 端口被其他进程占 | `lsof -i:{port}` 查 + 杀 | +| `--restart 预重启失败` | 启动 jar 缺失或路径错 | 检查 `boot/jnpf-admin/target/` 目录 | + +--- + +## 8. 相关文件 + +- `boot/ssw-dacli/src/main/java/ssw/dacli/DacliConf.java` (109 行配置读取器) +- `boot/ssw-dacli/src/main/java/ssw/dacli/commands/InitAppCommand.java` (restartJnpf + isJnpfHealthy 实现) +- `/home/ubuntu/ccWorkDir/dacli.conf` (项目根配置) +- `.claude/skills/design-jnpf-execute/SKILL.md` (C.7 场景 2.5 配套) +- `docs/tds/polish-changes-v10.6.md` (v10.6.1 修复闭环) +- MEMORY: `dacli-initapp-restart-fix.md` diff --git a/skills/design-jnpf-execute/references/c58-v11-todo.md b/skills/design-jnpf-execute/references/c58-v11-todo.md new file mode 100644 index 0000000..24449b5 --- /dev/null +++ b/skills/design-jnpf-execute/references/c58-v11-todo.md @@ -0,0 +1,241 @@ +# C.58 v11 待办 — 反向打磨 design-jnpf-execute 技能 (4 目标) + +> **来源**: 从 `docs/tds/polish-design-jnpf-execute-v11.md` (2026-06-11) 融合,作为本技能的"v11 打磨清单"。 +> **何时读**: 实战 7 阶段时,按 v11 4 目标顺序执行;每完成 1 个目标回填 plan.html + v11 polish-changes-v11.md。 +> **起点状态(2026-06-11)**: v10.6.3 已固化 3 个 dacli 候选(盲点 18/21/22 修复);C.5.11-C.5.16 沉淀 6 段规则;**v11 重点**:从「沉淀已知盲点」转向「用 SKILL.md 防御设计期盲点带 + 实战验证 E2E 失败回退闭环」。 + +--- + +## 上下文恢复 (必做 8 步,10 分钟内完成) + +```bash +# 1. 读 ssw-h5dev-flow 主流程技能 +dacli doc get --file=/home/ubuntu/ccWorkDir/.claude/commands/ssw-h5dev-flow.md + +# 2. 读 design-jnpf-execute 技能 (重点 C.5.11-C.5.16 + C.6) +dacli doc get --file=/home/ubuntu/ccWorkDir/.claude/skills/design-jnpf-execute/SKILL.md + +# 3. 读本文 (v11 4 目标) + +# 4. 读 v10.6 实战经验 +dacli doc get --file=/home/ubuntu/ccWorkDir/docs/tds/v10.6/polish-changes-v10.6.md +# 重点: v10.6.1 修复闭环 5/5 + v10.6.2 实战盲点 21/22/23 + v10.6.3 修复闭环 3/3 + +# 5. 读 form-development 技能 +dacli doc get --file=/home/ubuntu/ccWorkDir/.claude/skills/form-development/SKILL.md + +# 6. 读 platform-mechanism 技能 (JNPF 运行时硬约束) +dacli doc get --file=/home/ubuntu/ccWorkDir/.claude/skills/platform-mechanism/SKILL.md + +# 7. 读 tds 需求文档 +dacli doc scan --dir=/home/ubuntu/ccWorkDir/docs/tds/参考 +dacli doc list --dir=/home/ubuntu/ccWorkDir/docs/tds/参考 +# 重点: 功能清单.md (93 二级功能项) + 整体设计.md (系统架构) + +# 8. 健康度预检 (C.7 段场景判定) +dacli login --account=admin --password='123456' --appCode=tds +dacli status +dacli form list # 期望 200 + total=0 (数据已清空) +dacli menu list # 期望 200 + list_len=0 (v10.6.3 候选 I 修复后返完整树) +dacli dm list # 期望 200 (v10.6.3 候选 J 修复后含复合 PK) +``` + +--- + +## 目标 1 🟡 P1: design-jnpf.html 模板必含 3 个 v10.6 新段 + +**背景**: v10.6 加了 C.5.11/C.5.13/C.5.15 3 段规则,但 3 个 .tmpl 模板均未同步。 + +**v11 任务**: +1. 修改 3 个 .tmpl 模板(在 `.claude/templates/`): + - `jnpf-design-card.tmpl` (118 行): line 32 后插入「## 复用 baseline 关系表」骨架;line 43 字段表末尾加「□ 含 datePicker 字段」勾选行;line 89 后插入「## 菜单统计清单」骨架 + - `jnpf-design-workflow.tmpl` (74 行): 同步 3 段插入点(工作流卡片需含工作流版本字段勾选) + - `jnpf-design-master-sub.tmpl` (49 行): 同步 3 段插入点(主子表必含主子表关系图) +2. 修改 design-jnpf-execute SKILL.md: + - C.5.11/C.5.13/C.5.15 末尾各加"模板必含"要求 +3. tds 实战验证: `docs/tds/design-jnpf.html` 含 3 段(grep 验证) + +**验收**: +- [ ] 3 个 .tmpl 文件已加 3 段 +- [ ] SKILL.md C.5.11/C.5.13/C.5.15 末尾加"模板必含"要求 (3 处) +- [ ] `docs/tds/design-jnpf.html` 含 3 段 +- [ ] polish-convention.py 0 报错 +- [ ] 子代理 C 实际引用过 C.5.11 + +--- + +## 目标 2 🟡 P1: 4 子代理 prompt 模板强引用 C.5.11-C.5.16 + +**背景**: v10.6 加了 6 条 C.5.x 规则,但 4 子代理 prompt 模板只字未提。 + +**v11 任务**: +1. **子代理 A 字典 prompt**: C.5.16 强引用"读设计用 `dacli doc get` 不 `Read` 整文件" +2. **子代理 B DI prompt**: C.5.16 同上 +3. **子代理 C 表单 prompt (重点)**: + - 步骤 0 强化: `dacli dm table --table=<物理表>` 拉真实字段(防盲点 17) + - **步骤 0.5 新增**: grep `--fields` JSON 看有无 `jnpfKey.*datePicker` → 无则补 hidden 字段 + - 步骤 1 form create 后必加 `dacli form validate ` 验证 columnData + - 步骤 2 release 后必跑 E2E smoke + - **步骤 2.1 关键修正**: subagent 写 POST body 时**必须用 JSON 字符串的 `data` 字段**,不是 dict! + + ```bash + # ❌ 错: {"f_name":"test1"} → 400 + # ✅ 对: {"menuId":"...", "data":"{\"f_name\":\"test1\"}"} + curl -s -X POST "http://127.0.0.1:30000/api/visualdev/OnlineDev/$FORM_ID" \ + -H "App-Code: $APP" -H "Authorization: $TOKEN" -H "Content-Type: application/json" \ + -d "{\"menuId\":\"$MENU_ID\", \"data\":\"{\\\"f_\\\":\\\"smoke_test\\\"}\"}" + ``` +4. **子代理 D 菜单 prompt**: + - 步骤 0.5: 跑 `dacli menu list` 验证(v10.6.3 候选 I 修复后返完整树) + - 步骤 1 跑完菜单后 SQL 校验 count vs design.html 清单(C.5.15 防盲点 23) + - C.5.16 同上 +5. tds 实战验证: 14/14 forms CREATE PASS + 25 menus count 一致 + +**验收**: +- [ ] 4 子代理 prompt 模板各加 ≥ 1 条 C.5.x 引用 +- [ ] 子代理 C prompt 必加 0.5 datePicker 检测 + 步骤 2 E2E smoke + **步骤 2.1 API body JSON 字符串格式** +- [ ] tds 14/14 forms CREATE PASS(盲点 21 真因修复验证) +- [ ] tds 25 menus count 一致(v10.6.2 盲点 23 防御) + +--- + +## 目标 3 🟢 P2: 新增 C.5.17 段「polish → skill 迁移规则」(边界定义) + +**背景**: v10.6 polish 实战时**误把 tds 字段名 / tds DB 连接串 / tds 14 forms 清单写进了 skill 草稿**(已修复)。这种"应用特定 vs 通用规则"边界问题**没有专门段**说明,未来还会有人犯。 + +**v10.6.3 实战反例(什么不能入 skill)**: +- ❌ 盲点 21 误判 NPE 真因 → 实际是 API body 格式(v10.6.3 修正) +- ❌ tds 14 forms 各自的具体 form ID(`834520428356575877` 等) +- ❌ tds DB 凭证(`mariadb/root/2213`) +- ❌ tds 25 menus 的具体 enCode 列表 + +**v10.6.3 实战正例(什么应该入 skill)**: +- ✅ candidate H: `FormBuilder.buildFormFields` 默认加 hidden datePicker(通用工具方法,与 tds 无关) +- ✅ candidate I: `MenuCommand` 改 `Selector/All` 端点(通用 API 调用模式) +- ✅ candidate J: `DmCommand.ensureRuntimeColumns` 加复合 PK(通用建表规范) +- ✅ 盲点 21 真因: "API body data 字段是 JSON 字符串"(通用 JNPF API 行为) + +**v11 任务**: +1. **新增 C.5.17 段**(在 design-jnpf-execute SKILL.md, line 707 后 C.6 之前): + - **入 skill**(通用规则、平台机制、工具方法、命令模板、复现命令的占位符 ``/``/`` 等) + - **留 polish doc**(具体应用字段、菜单结构、修复记录、起点/终点状态表、加速比数据、进度表) + - **4 类边界判断**: + - 这条规则在另一个应用也能用吗? → 入 skill + - 这条规则依赖具体 DB 凭证 / 具体 form ID 吗? → 留 polish doc + - 这条是设计期硬约束还是实战记录? → 前者入 skill,后者留 polish doc + - 这条能让下次实战少踩坑吗? → 入 skill(即使是"反向经验") +2. tds 实战验证: v11 polish-changes-v11.md 每条标 `[skill]` 或 `[polish]` 标签 + +**验收**: +- [ ] SKILL.md C.5.17 段已加(4 边界判断 + v10.6.3 实战对照表) +- [ ] v11 polish-changes-v11.md 每条标 `[skill]` 或 `[polish]` +- [ ] 边界比例: ~60% 入 skill / ~40% 留 polish doc +- [ ] **反例**也列: v10.6.2 盲点 21 误判 → 修正后入 skill(API body 格式) + +--- + +## 目标 4 🟡 P1: E2E smoke 失败 → BLOCKED 流程闭环(C.5.12 增强) + +**背景**: C.5.12 "Stage 4 必跑 E2E smoke" 只说"必跑",**没说失败怎么办**。盲点 21 v10.6.2 实战就是"跑了但误判 NPE 真因" → 修复方向错 → 浪费一轮实战。v10.6.3 修正真因后,失败回退流程必须**显式列出 4 类 + BLOCKED 原则**。 + +**v10.6.3 实战修正(盲点 21 真因)**: +- ❌ v10.6.2 误判: JNPF `OnlineSwapDataUtils.swapDatetime:433` NPE → 实际**不是 NPE 根因** +- ✅ v10.6.3 真因: API body `data` 字段格式错(应是 JSON 字符串,不是 dict) +- ✅ v10.6.3 仍保留 hidden datePicker 作为**纵深防御**(candidate H) + +**v11 任务**: +1. **C.5.12 末尾加"失败回退流程"**(line 627 后): + + | 现象 | 真因(v10.6.3 修正后) | 修复 | + |------|---------------------|------| + | 400 "System abnormality" | **API body `data` 字段是 dict 不是字符串** | 用 `{"menuId":"...","data":"{\"f_x\":\"v\"}"}` 格式(双层 JSON 转义) | + | 400 "Unknown column 'f_flow_task_id'" | 老表(v10.6.1 之前)缺系统列 | `ALTER TABLE ... ADD COLUMN f_flow_task_id VARCHAR(50) NULL` | + | 400 "Unknown column 'f_flow_id'" | 同上 | `ALTER TABLE ... ADD COLUMN f_flow_id VARCHAR(50) NULL` | + | NPE in `OnlineSwapDataUtils.swapDatetime` | form 无 date 字段 + body 错(纵深) | 业务字段加 datePicker;或 v10.6.3 candidate H 兜底 | + | List API total=0 但 DB 有行 | tenant/menuId filter 不匹配 | DB 直查兜底 + 排查 mybatis-plus 行为 | + +2. **新增 troubleshooting 引用**: C.5.12 末尾引用 `troubleshooting` SKILL.md "调试方法论 3 原则": + - 原则 1: **从最具体的错误信息反推**("Unknown column 'X'" → 先看 X 是不是 v10.6.3 已自动加的列 → 是 → 老表 ALTER) + - 原则 2: **不要相信"看起来对的"修复**(盲点 21 NPE 误判教训: 先看错误堆栈的根 method,不要被中间 NPE 误导) + - 原则 3: **失败必 BLOCKED,禁"算了跳过"**(每 form CREATE 必须 PASS 才算 Stage 4 验收通过) + +3. tds 实战验证(设计期故意构造 1 个失败): 14 forms 中**故意** 1 个 form 字段全部是 input(无 datePicker)→ 跑 E2E smoke → 必失败 → 按 v10.6.3 真因判定流程修好 → PASS + +**验收**: +- [ ] C.5.12 末尾加"失败回退流程"5 类 + BLOCKED 原则 + troubleshooting 3 原则引用 +- [ ] tds 14 forms 中 1 个 form 故意失败 → 按 v10.6.3 真因判定流程修好 → PASS +- [ ] v11 polish-changes-v11.md "失败回退"段有完整 stack → 诊断 → 修复 → 重跑 记录 + +--- + +## v11 7 阶段(融合 4 目标) + +| 阶段 | 目标对应 | 预计 | +|------|---------|------| +| 1 初始化(C.7 场景判定) | — | 5min | +| 2 设计(**目标 1 模板改造 + 设计文件生成**) | 1, 3 | 30min | +| 3 审核(polish-convention 0 报错) | 1, 3 | 10min | +| 4 执行(**目标 2 子代理 prompt 改造 + 14 forms + 25 menus**) | 2 | 30min | +| 5 测试(**目标 4 E2E smoke 失败回退闭环**) | 4 | 20min | +| 6 总结(summary.html) | — | 10min | +| 7 迭代(v11 polish-changes-v11.md + **目标 3 边界自检**) | 3 | 15min | + +**预计总计**:~2h + +--- + +## 严格边界(与 v10.6 polish 共识) + +> **本轮 v11 不入 skill 的内容**(明确): +> - tds 14 forms 字段名(`f_space_name` 等) +> - tds DB 连接凭证(`mariadb/root/2213` 等) +> - tds 25 menus 菜单结构 +> - v11 实战进度表 / 加速比数据 +> - v11 起点/终点状态对比 +> +> **本轮 v11 入 skill 的内容**(明确): +> - 4 子代理 prompt 模板的通用增强(不引用 tds) +> - jnpf-design-*.tmpl 模板的通用段落 +> - C.5.12 失败回退流程(4 类错误 + BLOCKED 原则) +> - C.5.17 polish → skill 迁移边界规则 +> - C.5.11/C.5.13/C.5.15 末尾的"模板必含"要求 +> +> **判别公式**: 本条规则换一个应用(如 workSystem)也能直接用 → 入 skill;需要 tds 特定信息才能复现 → 留 polish doc。 + +--- + +## v11 预期发现(盲点候选) + +> v11 主动实战,预期发现以下盲点。**每发现 1 个新盲点**,必同时沉淀到 SKILL.md(**不只**留 polish doc)。 + +| v11 盲点候选 | 触发场景 | 防御位置 | +|-------------|---------|---------| +| **24**: 模板没强制 3 段时 subagent 漏写 | 目标 1 第一次跑实战 | C.5.11/13/15 + 模板改造 | +| **25**: 4 子代理 prompt 不引用 C.5.x 时漏执行 | 目标 2 第一次派子代理 | 4 子代理 prompt 改造 | +| **26**: C.5.17 边界不清导致误沉淀 | 目标 3 polish → skill 时 | C.5.17 新段 | +| **27**: C.5.12 失败不 BLOCKED 而是"算了跳过" | 目标 4 故意构造失败 | C.5.12 失败回退流程(v10.6.3 真因) | + +--- + +## 启动 + +```bash +# 1. 健康度预检 + 场景判定 +dacli login --account=admin --password='123456' --appCode=tds +dacli status +dacli form list # 期望 200 + total=0 +dacli menu list # 期望 200 + list_len=0 (v10.6.3 候选 I 修复后返完整树) +dacli dm list # 期望 200 (v10.6.3 候选 J 修复后含复合 PK) + +# 2. C.7 场景修复(如果是场景 2/2.5, v10.6.1 已支持 --restart 端到端) +dacli initapp -- --appCode=tds --appName='可信数据空间' + +# 3. 4 目标按 P 排序执行 +# 4. 启动设计阶段: 先改 3 个 .tmpl 模板(C.5.11/13/15 段落),再写 design-jnpf.html +# 5. 派 4 子代理(用 dacli doc get 拉设计,不用 Read 整文件 — C.5.16) +# 6. 14 forms + 25 menus 全部 state=1 后跑 E2E smoke +# 7. 故意让 1 个 form 失败 → 按 C.5.12 失败回退流程修 → 重跑 → PASS +# 8. 总结 + 迭代 + C.5.17 边界自检 +``` + +按 `polish-design-jnpf-execute.md`(v10.6 提示词)的 7 阶段节奏执行,但**每阶段必回归 4 目标**。 diff --git a/skills/design-jnpf-execute/references/subagent-prompts.md b/skills/design-jnpf-execute/references/subagent-prompts.md new file mode 100644 index 0000000..e0df67e --- /dev/null +++ b/skills/design-jnpf-execute/references/subagent-prompts.md @@ -0,0 +1,268 @@ +# 4 子代理 A/B/C/D Prompt 模板 + +> **来源**: 从 `.claude/skills/design-jnpf-execute/SKILL.md` 第 1168-1430 行抽出,作为独立子文档。 +> **何时读**: ssw-h5dev-flow 阶段4 主线程派子代理时,主线程按本文件模板把 prompt 喂给子 agent。 +> **约束引用**: C.5.x 规则在主 SKILL.md,本文件只放 4 个可复制的 prompt 模板。 +> **v11 必读硬约束**: C.5.11/13/14/15/16(实战防御 5 条) + C.5.20(datePicker 毫秒数) + C.5.21(menu 缓存)+ 步骤 2.1 API body data 字段是 JSON 字符串(盲点 21 真因)。 + +--- + +## 子代理 A: 字典生成 + +> ⚠️ **v6.1 修正**(来自 某应用 实战): +> 1. dacli dict 实际是 **type + data 二级**——`dacli dict type-create` 创建类型,`dacli dict data-create` 创建数据项 +> 2. type JSON **必填** `parentId="0"` / `isTree=0`(int)/ `category=0`(int,不是 string) +> 3. data JSON **必填** `parentId="0"` + `dictionaryTypeId=""`(全拼,注意 "dictionary") +> 4. `dacli dict list` 命令**不存在**——验证用 `dacli dict type-list`(嵌套 `data.list[].children[]` 结构) +> 5. dacli create 返 "New created successfully" 但**不返 ID**——必须 type-list 回查 ID 传给 data-create +> 6. **创建后立即 list 验证**(防 dacli 静默假成功:dictionaryTypeId 空时返 200 但实际未写入) + +**Prompt 模板**: + +``` +你是 dacli 字典生成子代理。从 design-jnpf.html 的 #dict-* 段读取字典定义,产出 dacli dict bash 脚本。 + +输入文件:docs/{app_code}/design-jnpf.html(只读 #dict-* 段,不要读其他段) +输出文件:docs/{app_code}/scripts/auto-gen/dict.sh + +🛡️ v11 必读(C.5.16 — 节省 80% token): +- 读设计用 `dacli doc get --file=docs/{app_code}/design.html --section=`,**不要** `Read` 整 HTML +- 历史经验:`dacli doc get --file=docs/{app_code}/polish-changes-v10.6.md` + +任务步骤: +1. 读 #dict-* 段所有字典定义(每个字典含 enCode / fullName / 字典项列表) +2. 对每个字典,分两步: + a) 创建类型(dacli dict type-create --data=JSON): + { + "enCode": "<编码>", + "fullName": "<名称>", + "parentId": "0", # 必填,顶级=0 + "isTree": 0, # 必填 int + "category": 0, # int:0=业务字典 / 1=系统字典 + "sortCode": , + "description": "<描述>" + } + b) 回查类型 ID:`dacli dict type-list` → 解析 data.list[].children[] 找 enCode 匹配 + c) 对字典每项创建数据(dacli dict data-create --data=JSON): + { + "enCode": "<项编码>", + "fullName": "<项名称>", + "parentId": "0", # 必填,顶级数据项=0 + "dictionaryTypeId": "<上一步查到的类型ID>", # 必填,全拼 + "sortCode": + } +3. 生成 bash 脚本,每步独立 + set -e +4. **强制验证**:脚本末尾用 `dacli dict type-list | grep ` + `dacli dict data-list | python3 -c "import sys,json; print(len(json.loads(sys.stdin.read())['data']))"` 确认字典项数 == 期望项数 +5. 任何验证失败立即 exit 1 + +约束: +- enCode 必须 snake_case +- 同一 enCode 多次执行会报错,加 set -e 早停 +- 输出脚本前用 bash -n 语法检查 +- **不要相信 dacli 返 200**——必须 list 验证 + +完成后回报:生成字典数(type+data)/ 验证项数 / 脚本路径 +``` + +--- + +## 子代理 B: 数据接口生成 + +> ⚠️ **v6.1 修正**(来自实战): +> 1. `dacli di create` 在某应用下**一律 400 "System abnormality"**(dacli 内部硬编码 category ID) +> 2. 子代理 B **必须先** `dacli di list` 验证当前 appCode 下 di 服务可用 +> 3. 失败回退策略:把 #di-* 标记的字段改用 **JNPF 内置组件**(userSelect / currOrganize / popupTableSelect 等)替代 +> 4. **不要重试 dacli di create**——3 次失败就报告 BLOCKED 让主线程改设计 + +**Prompt 模板**: + +``` +你是 dacli 数据接口生成子代理。从 design-jnpf.html 的 #di-* 段读取接口定义,产出 dacli di bash 脚本。 + +输入文件:docs/{app_code}/design-jnpf.html(只读 #di-* 段) +输出文件:docs/{app_code}/scripts/auto-gen/di.sh + +🛡️ v11 必读(C.5.16 — 节省 80% token): +- 读设计用 `dacli doc get --file=docs/{app_code}/design.html --section=di`,**不要** `Read` 整 HTML +- 历史经验:`dacli doc get --file=docs/{app_code}/polish-changes-v10.6.md` + +任务步骤: +1. 读 #di-* 段所有接口定义(每个含 enCode / fullName / type=sql|api / sql 或 url) +2. **【关键】预检 di 服务可用性**: + dacli di list --keyword=user_options + - 返回 200 + 非空 data.list → 继续 + - 返回 400/500 或空 list → **报告 BLOCKED**,主线程会改设计 +3. 对每个接口生成 di create 命令: + dacli di create \ + --enCode="<编码>" \ + --name="<名称>" \ + --dbLinkId=default \ + --sql="" # sql 模式;api 模式用 --url(参考 dacli di create --help) +4. SQL 模式需转义单引号(用 \" 转义) +5. **创建后立即 list 验证**: + dacli di list | grep "" || exit 1 +6. 任何验证失败立即 exit 1 + +约束: +- 失败回退方案:在 #di-* 字典项标注 fallback="userSelect" 时,子代理 C 看到 fallback 会自动用 userSelect +- enCode 必须 snake_case +- set -e 早停 +- 输出脚本前 bash -n 语法检查 +- **不要相信 dacli 返 200**——必须 list 验证 + +完成后回报:生成接口数 / 验证结果 / 失败时的 fallback 字段列表 +``` + +--- + +## 子代理 C: 表单生成 + +> ⚠️ **v6.1 修正**(来自 某应用 实战): +> 1. **dacli form create 字段用 `field`(不是 `vModel`)**——v6.0 写的 `vModel` 是 JNPF 渲染层字段名,但 dacli form create 用物理层 `field`(dacli 自动根据 jnpfKey 推断 dataType / dataLength) +> 2. **dacli form create 用 `--fields`(不是 `--fieldsJson`)** +> 3. **没有 `--columnDataJson` 参数**——列表列由 jnpfKey 自动推断默认列;自定义需用 `dacli form update` / `dacli form fix` +> 4. **webType=2 + --autoTable 在 某应用 下报 DB 异常**——若收到 DB exception,**回退 webType=4(视图)**并报告主线程 +> 5. **关联字段的 interfaceId**:当 #di-* 失败回退到 userSelect 时,**删除 interfaceId 字段**(userSelect 不需要 interfaceId) +> 6. **创建后立即 list 验证**(防 dacli 假成功:返 200 但 form list 查不到) + +**Prompt 模板**: + +``` +你是 dacli 表单生成子代理。从 design-jnpf.html 的 #form-* 段读取表单定义,产出 dacli form create bash 脚本。 + +输入文件: +- docs/{app_code}/design-jnpf.html(只读 #form-* 段) +- docs/{app_code}/scripts/auto-gen/dict.sh(字典 ID 引用,**只读**,从中 grep -oP 'dacli dict type-create.*?enCode.*?"\K[^"]+' 提取) +- docs/{app_code}/scripts/auto-gen/di.sh(接口 ID 引用,同上) + +输出文件:docs/{app_code}/scripts/auto-gen/form.sh + +🛡️ v11 必读(C.5.11/13/14/16/20/21 — 实战防御 6 条盲点): +- **C.5.11**:读 #form-* 段时,**先看是否含「## 复用 baseline 关系表」段**?如有 → 用 `dacli form info ` 拉 formData/columnData 模板,**只改 enCode/name/业务字段**,不动 __config__/columnOptions/relationForm 结构 +- **C.5.13**:每 form 必含 ≥1 个 datePicker 字段(业务字段或 hidden `f_default_datetime`) +- **C.5.14**:对每个 form enCode,先跑 `dacli dm table --table=<物理表名> --dbLinkId=` 拉真实字段名映射,**禁止**按通用命名(`f_name`/`f_code`)假设! +- **C.5.16**:读设计用 `dacli doc get --file=docs/{app_code}/design.html --section=form`,**不要** `Read` 整 HTML +- **C.5.20**:datePicker 字段值必须 Unix 毫秒时间戳(如 `1749398400000`),不能是 `"2026-06-09"` 字符串 +- **C.5.21**:`dacli menu list` 当前缓存可能不返完整树,主线程已用 `Selector/All` 端点解决;子代理 C 不直接调 menu list + +任务步骤: +0. **【v10.6 盲点 17 防御】对每个 form enCode,先跑 `dacli dm table --table=<预期表名> --dbLinkId=` 拉真实字段名映射**,**禁止**按通用命名(`f_name`/`f_code`)假设! + - 实际案例(应用特定):`` / `` / ``(**不是** `` / `` / ``) + - 字段名不对 → form create 返 400 "Database exception"(盲点 15 触发但真因是字段不匹配) +0.5. **【v11 新增】datePicker 检测**:grep `--fields` JSON 看有无 `jnpfKey.*datePicker` → 无则补 hidden 字段(C.5.13 防御) + - v10.6.3 `FormBuilder.buildFormFields` 已自动加 hidden datePicker(纵深防御)— 此步是设计期自检 +1. 读所有 #form-* 段 +2. 对每个表单: + a) 校验 9 条规则(详见功能设计模板.md 附录 D) + b) 生成 dacli form create 命令(关键 schema): + dacli form create \ + --name="<中文名>" \ + --enCode="" \ + --webType=2 \ + --dbLinkId=default \ + --fields='[ + { + "field": "", # 物理字段名(不是 vModel!) + "fieldName": "<中文名>", + "jnpfKey": "<控件>", + "config": { ... } + } + ]' \ + --autoTable \ + --autoRelease + c) 若 di.sh 不存在或空,关联字段的 jnpfKey 改用 userSelect(不传 interfaceId) + d) 若 webType=2 + --autoTable 报 DB exception,回退 webType=4(视图)重试 +3. 主子表用 create_subtable_form.py 脚本 +4. 工作流表单加 --enableFlow=1 --flowId={flowId} +5. **【v10.6 新增 C.5.12】创建后必跑 E2E smoke 验证 runtime 兼容性**(防盲点 21): + ```bash + FORM_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="") | .id') + MENU_ID=$(jq -r '.[""]' docs/{app_code}/scripts/auto-gen/menu-id-map.json) + # ⚠️ 步骤 5.1 关键修正:data 字段是 JSON 字符串(v10.6.3 盲点 21 真因)! + curl -s -X POST "http://127.0.0.1:30000/api/visualdev/OnlineDev/$FORM_ID" \ + -H "App-Code: $APP" -H "Authorization: $TOKEN" -H "Content-Type: application/json" \ + -d "{\"menuId\":\"$MENU_ID\", \"data\":\"{\\\"f_\\\":\\\"smoke_test\\\"}\"}" + # ❌ 错: {"f_name":"test1"} → 400 + # ✅ 对: {"menuId":"...","data":"{\"f_name\":\"test1\"}"} → 200 + ``` +6. **创建后立即 list 验证**: + dacli form list | grep "" || exit 1 +7. 任何验证失败立即 exit 1(BLOCKED 原则:见 troubleshooting 3 原则) + +约束(实施前 0 试错关键): +- 关联字段必须用 jnpfKey=relationForm(dacli 不可用时回退 userSelect) +- relationForm.columnOptions ≤ 5 +- 严禁 f_version 字段 +- 后端代码**仅用 Java 8**(jnpf-admin 不支持 Java 11+ 特性,如 var / records / text blocks) +- 必走 ssw-code-gen 代码生成(复杂功能),生成后必做 fix_class_names 类名前缀修复 +- 字段 JSON 用 `field`(物理字段名)不用 `vModel` +- 参数用 `--fields` 不用 `--fieldsJson` +- 不传 `--columnDataJson`(dacli 不支持) +- **不要相信 dacli 返 200**——必须 list 验证 +- **🛡️ v11 E2E smoke body 用 JSON 字符串 data 字段**(盲点 21 真因) +- **🛡️ v11 datePicker 值用 Unix 毫秒**(C.5.20) + +完成后回报:生成表单数 / 校验通过率 / 是否有 webType 回退 / E2E smoke PASS 数 / 脚本路径 +``` + +--- + +## 子代理 D: 菜单/权限生成 + +> ⚠️ **v6.1 修正**(来自 某应用 实战): +> 1. **dacli menu create 已"内化"7 字段必填**——用 `--formId` 高层 API,**不要手填 propertyJson + isButtonAuthorize 等 4 个 isAuthorize 参数** +> 2. 参数名是 `--name`(不是 `--fullName`) +> 3. 父菜单 ID 用 `-1`(顶级)或 `dacli menu list` 查询 appCode 根菜单 +> 4. `--authorize` 参数自动授权 admin 角色(替代手动赋权) +> 5. **dacli menu create 也是"假成功"**(返 200 但 menu list 查不到)——必须 list 验证 +> 6. 菜单不显示时用 `dacli menu update --id= --fixDisplay=true` 修复(兜底) + +**Prompt 模板**: + +``` +你是 dacli 菜单/权限生成子代理。从 design-jnpf.html 的 #menu-* 段读取菜单定义,产出 dacli menu bash 脚本。 + +输入文件: +- docs/{app_code}/design-jnpf.html(只读 #menu-* 段) +- docs/{app_code}/scripts/auto-gen/form.sh(表单 ID 引用,从中 grep -oP 'dacli form create.*?--enCode="\K[^"]+' + 'dacli form list.*?"id":"\K[0-9]+' 配对提取) + +输出文件:docs/{app_code}/scripts/auto-gen/menu.sh + +🛡️ v11 必读(C.5.15/16 — 实战防御 2 条盲点): +- **C.5.15**:先读 design.html「## 菜单统计」段(**完整枚举**)→ 跑完菜单后用 SQL `SELECT COUNT(*)` 逐层校验(防盲点 23) +- **C.5.16**:读设计用 `dacli doc get --file=docs/{app_code}/design.html --section=menu`,**不要** `Read` 整 HTML +- v10.6.3 候选 I 修复:`dacli menu list` 改用 `Selector/All` 端点 + flatten,**返完整嵌套树**(修复前只返 1 个顶级) + +任务步骤: +0.5. **【v11 新增】菜单 count 校验**:从 design.html 提取期望菜单数(按顶级/一级/二级/三级),记为 EXPECTED_MENU_COUNT +1. 读所有 #menu-* 段 +2. 查父菜单 ID:`dacli menu list | python3 -c "解析 data.list[] 找 enCode= 且 parentId=-1 的 ID"` +3. 对每个菜单生成命令(高层 API,dacli 内化 7 字段必填): + dacli menu create \ + --name="<菜单名称>" \ + --enCode="" \ + --parentId="<父菜单ID 或 -1>" \ + --type=3 \ + --formId="<关联表单ID>" \ + --authorize +4. **创建后立即 list 验证**: + dacli menu list | grep "" || exit 1 +5. **【v11 新增】菜单 count 校验(盲点 23 防御)**: + ```bash + ACTUAL_COUNT=$(dacli menu list --keyword="_" | python3 -c "import sys,json; print(len(json.loads(sys.stdin.read())['data']['list']))") + [ "$ACTUAL_COUNT" = "$EXPECTED_MENU_COUNT" ] || { echo "✗ 菜单数不符 design=$EXPECTED_MENU_COUNT, db=$ACTUAL_COUNT"; exit 1; } + ``` +6. 任何验证失败立即 exit 1 +7. 兜底:菜单不显示时用 `dacli menu update --id= --fixDisplay=true` 修复 + +约束: +- **不要手填 7 字段必填**(dacli menu create 已内化) +- **不要用 `--fullName`**(参数名是 `--name`) +- **不要传 `--category=Web` `--linkTarget=_self` `--propertyJson` 等**(dacli 自动处理) +- set -e 早停 +- 输出脚本前 bash -n 语法检查 +- **不要相信 dacli 返 200**——必须 list 验证 +- **🛡️ v11 菜单 count 必须与 design.html 一致**(C.5.15 防御) + +完成后回报:生成菜单数 / list 验证结果 / 菜单 count 校验结果 / 脚本路径 +``` diff --git a/skills/platform-mechanism/references/jnpf-form-data-model.md b/skills/platform-mechanism/references/jnpf-form-data-model.md new file mode 100644 index 0000000..3528a60 --- /dev/null +++ b/skills/platform-mechanism/references/jnpf-form-data-model.md @@ -0,0 +1,521 @@ +# JNPF 表单数据模型速查 + +> **来源**: 从 `docs/dacli/dev-rs.md` (2026-06-09) 融合到本技能,作为详细参考。 +> **何时读**: 写 `dacli form create/fix/update` 涉及深结构(JSON 字符串/嵌套配置/主子表),或排查 JNPF runtime 报 NPE 缺列。 +> **不读也行**: 99% 场景用 `form-development` 速查 + `dacli form info --expand-subtable` 已够。 +> **数据口径**: JNPF 6.2.0 (本仓库版本)。 + +--- + +## 1. 表单 JSON 结构总览 + +``` +Form (VisualdevEntity) + ├── formData 表单配置(控件树 + 布局 + 校验 + 脚本) + ├── tables 物理表元数据(主表/子表/副表的字段定义) + ├── columnData PC 端列表配置(搜索/列/按钮/卡片) + ├── appColumnData 移动端列表配置(结构同 columnData) + ├── buttonData 自定义按钮 + └── appButtonData 移动端自定义按钮 +``` + +> **关键**: `formData`/`tables`/`columnData` 在 API 传参时都是 **JSON.stringify 后的字符串**,不是嵌套对象。 + +**运行时保存流程**: +``` +POST /api/visualdev/OnlineDev/{modelId} + → VisualdevModelDataController.create() + → VisualdevModelDataServiceImpl.visualCreate() + ├─ FormCloumnUtil.recursionFormGen() 控件树 → FormAllModel + ├─ formCheckUtils.checkForm() 必填/唯一/业务主键校验 + └─ FlowFormDataUtil.create() + ├─ createMast() INSERT 主表 + ├─ createTable() INSERT 子表(外键 = 主表.f_id) + └─ createMastTable() INSERT 副表(外键 = 主表.f_id) +``` + +**主表/子表/副表区别**: + +| 类型 | typeId | 命名 | 关系字段 | 说明 | +|------|--------|------|---------|------| +| 主表 | `"1"` | `mt{ID}` | — | 必有 | +| 子表 | `"0"` | `ct{ID+1}` | `f_foreignId` → 主表.`f_id` | 1:N | +| 副表 | `"2"` | `at{ID+2}` | `f_foreignId` → 主表.`f_id` | 1:1 | + +> **子表 ID = 主表 ID + 1**(绝对规则) + +--- + +## 2. 表与字段命名规则 + +### 2.1 表名 + +``` +主表: mt + 表单ID mt294376098702073541 +子表: ct + 表单ID + 1 ct294376098702073542 +副表: at + 表单ID + 2 at294376098702073543 +``` + +### 2.2 业务字段名(vModel) + +设计器自动生成,格式:`{控件缩写}Field{formId}` + +| jnpfKey | 缩写 | 示例 | +|---------|------|------| +| input | comInput | `comInputField102` | +| textarea | textarea | `textareaField104` | +| inputNumber | numInput | `numInputField108` | +| datePicker | date | `dateField106` | +| select | select | `selectField103` | +| radio | radio | `radioField103` | +| uploadFile | uploadFz | `uploadFzField123` | +| userSelect | userSelect | `userSelectField102` | +| currOrganize | currOrganize | `currOrganizeField103` | +| billRule | billRule | `billRuleField101` | + +### 2.3 子表容器 vModel + +`tableField{formId}` — 例:`tableField117` + +### 2.4 系统字段(自动追加) + +**主表**:`f_id`(PK), `f_tenant_id`(PK), `f_flow_id`, `f_flow_task_id`, `f_flow_state`, `f_inte_assistant` + +**子表**:`f_id`(PK), `f_foreignId`(FK→主表.f_id), `f_tenant_id` + +> **v10.6.1+ 自动化**: `dacli dm create` 自动补 9 系统列(`f_flow_task_id`/`f_flow_id`/`f_flow_state`/`f_sort_code`/`f_create_user`/`f_create_time`/`f_modify_user`/`f_modify_time`/`f_description`),dacli 还会加复合 PK `PRIMARY KEY (f_id, f_tenant_id)`。 +> +> **v10.6.1 之前的老表**:见 `platform-mechanism` 主 SKILL.md 「JNPF 运行时硬约束」段,需要 `ALTER TABLE` 兜底。 + +--- + +## 3. formData 控件树(vModel 配置层) + +### 3.1 顶层结构 + +```json +{ + "formRef": "formRef", + "formModel": "dataForm", + "size": "default", + "labelPosition": "right", + "labelWidth": 100, + "formRules": "rules", + "popupType": "general", + "gutter": 15, + "disabled": false, + "span": 24, + "primaryKeyPolicy": 1, + "concurrencyLock": false, + "logicalDelete": false, + "dataLog": false, + "useBusinessKey": false, + "businessKeyList": [], + "funcs": { "onLoad": "", "beforeSubmit": "", "afterSubmit": "" }, + "fields": [ /* 控件树 */ ], + "tableName": "主表名" +} +``` + +### 3.2 字段结构(FieldItem) + +完整示例(input 控件): +```json +{ + "__config__": { + "formId": 102, + "visibility": ["pc", "app"], + "jnpfKey": "input", + "noShow": false, + "tipLabel": "", + "dragDisabled": false, + "className": [], + "label": "客户名称", + "trigger": "blur", + "showLabel": true, + "required": true, + "tableName": "mt294376098702073541", + "renderKey": 1717833600102, + "layout": "colFormItem", + "tagIcon": "icon-ym icon-ym-generator-input", + "tag": "JnpfInput", + "regList": [], + "span": 24, + "dictionaryType": "" + }, + "__vModel__": "comInputField102", + "field": "comInputField102", + "clearable": true, + "suffixIcon": "", + "addonAfter": "", + "readonly": false, + "showPassword": false, + "style": { "width": "100%" }, + "disabled": false, + "placeholder": "请输入客户名称", + "prefixIcon": "", + "addonBefore": "", + "on": { "change": "", "blur": "" }, + "id": "comInputField102", + "fullName": "客户名称", + "fullNameI18nCode": [""] +} +``` + +**各控件特有属性**: + +| jnpfKey | 特有属性 | +|---------|---------| +| select / radio / checkbox | `options: [{fullName, id}]`, `props: {label:"fullName", value:"id"}`, `multiple: false` | +| inputNumber | `step: 1`, `controls: true`, `min: null`, `max: null` | +| datePicker | `format: "yyyy-MM-dd"`, `valueFormat: "yyyy-MM-dd"`, `defaultValue: null` | +| timePicker | `format: "HH:mm:ss"`, `valueFormat: "HH:mm:ss"` | +| textarea | `rows: 4`, `maxlength: null` | +| switch | `activeValue: 1`, `inactiveValue: 0` | +| relationForm | `modelId: ""`, `relationField: ""`, `hasPage: false`, `pageSize: 20`, `columnOptions: []`, `popupType: "dialog"`, `popupTitle: "选择数据"`, `popupWidth: "800px"` | +| billRule | (无特殊属性,系统自动生成编号) | + +### 3.3 客户端提交 dataMap 格式 + +```json +{ + "comInputField102": "张三", + "selectField103": "男", + "billRuleField101": "DD20240608001", + "tableField117": [ + { + "dateField117": "2020-01-01", + "dateField118": "2022-01-01", + "comInputField119": "某公司" + // 后端自动补: f_id(UUID), f_foreignId(主表.f_id), f_tenant_id + } + ] + // 系统字段 f_id/f_tenant_id/f_flow_* 由后端生成,前端不传 +} +``` + +> **关键**: datePicker 值是 **Unix 毫秒时间戳**(`1749398400000`),不是字符串(`"2026-06-09"` 会 NPE)。详见 `platform-mechanism` 主 SKILL.md 段 2。 + +--- + +## 4. tables[] 表元数据(建表 DDL 层) + +每个 table 节点**必须包含以下 7 个基础字段**(缺一 Release 会 NPE): + +| 字段 | 类型 | 说明 | +|------|------|------| +| `table` | string | 物理表名 | +| `tableName` | string | 中文名 | +| `tableKey` | string | 主键字段名(`"f_id"`) | +| `aliasName` | string/null | 别名 | +| `comment` | string | 备注 | +| `initName` | string/null | 初始化名 | +| `tableTag` | string/null | 标签 | + +子表额外字段:`typeId`(`"0"`), `tableField`(`"f_foreignId"`), `relationTable`(主表名), `relationField`(`"f_id"`) + +> **dacli 已自动填**: `dacli form create` 走内置 `FormBuilder` 拼 tables,7 字段不缺;用户手写 JSON 时必须保证完整。 + +--- + +## 5. columnData 列表配置(list 渲染层) + +**JNPF 前端强假设**:`columnData.searchList/columnList/defaultColumnList/columnOptions` 每项都有 `__config__` 包装(否则列表页白屏,见 C.5.9)。 + +### 5.1 按钮配置 + +**工具栏按钮(btnsList)**: +```json +"btnsList": [ + { "value": "add", "label": "新增", "type": "primary", "onClick": "add()" }, + { "value": "batchRemove", "label": "批量删除", "type": "danger", "onClick": "batchRemove()" }, + { "value": "export", "label": "导出", "type": "", "onClick": "export()" } +] +``` + +**行操作按钮(columnBtnsList)**: +```json +"columnBtnsList": [ + { "value": "edit", "label": "编辑", "type": "", "onClick": "edit(row)" }, + { "value": "remove", "label": "删除", "type": "danger", "onClick": "remove(row)" }, + { "value": "detail", "label": "详情", "type": "", "onClick": "detail(row)" } +] +``` + +### 5.2 列配置(columnList) + 搜索项配置(searchList) + +**结构**:每项必须含 `__config__` 包装(见 `design-jnpf-execute` C.5.9 段)。dacli `form create` 自动填,老 form 缺 `__config__` 用 `dacli form validate --fix` 修。 + +--- + +## 6. 子表配置规则(重点) + +### 6.1 tableName 错位规则 + +| 场景 | `__config__.tableName` | 真实物理表 | +|------|----------------------|-----------| +| 主表字段 | 主表名 `mt{ID}` | 主表 | +| **子表容器** | **子表名 `ct{ID+1}`** | 子表 | +| **子表内字段** | **主表名 `mt{ID}`** ⚠️ | 由 `relationTable` 标识 | + +> 子表内字段的 `tableName` 写的是主表名(设计器逻辑),判断真实物理表必须看 `isSubTable=true` + `relationTable`。 + +### 6.2 子表容器 + 内字段 + +**容器**:`__config__.jnpfKey = "table"`,`__config__.children = [子表字段]` + +**子表内字段**: +```json +{ + "__config__": { + "jnpfKey": "input", + "label": "商品名", + "tableName": "mt_order_1", // ⚠️ 主表名(错位) + "relationTable": "ct_order_1", // 真实物理表 + "parentVModel": "tableField105", // 父容器 vModel + "isSubTable": true + }, + "__vModel__": "comInputField106" +} +``` + +### 6.3 不允许放入子表的控件 + +`divider, text, link, alert, groupTitle, button, barcode, qrcode, iframe, editor, radio, checkbox, colorPicker, table`(子表不能嵌子表) + +### 6.4 必填/唯一校验:仅主表 + +后端 `FormCheckUtils.checkForm` **只校验主表字段**,不校验子表内字段(子表行数据校验靠 DB NOT NULL + 前端 `formRules`)。 + +--- + +## 7. 控件类型清单(jnpfKey) + +### 7.1 基础/选择/时间 + +| jnpfKey | 控件 | 后端常量 | DB 类型 | +|---------|------|---------|---------| +| input | 单行输入 | COM_INPUT | varchar(255) | +| textarea | 多行输入 | TEXTAREA | varchar(255) | +| inputNumber | 数字 | NUM_INPUT | decimal | +| select | 下拉 | SELECT | varchar(255) | +| radio | 单选 | RADIO | varchar(255) | +| checkbox | 多选 | CHECKBOX | varchar(255) | +| cascader | 级联 | CASCADER | varchar(255) | +| treeSelect | 树形 | TREESELECT | varchar(255) | +| datePicker | 日期 | DATE | datetime | +| timePicker | 时间 | TIME | datetime | +| switch | 开关 | SWITCH | int | + +### 7.2 上传/高级 + +| jnpfKey | 控件 | 后端常量 | DB 类型 | +|---------|------|---------|---------| +| uploadFile | 附件 | UPLOADFZ | longtext | +| uploadImg | 图片 | UPLOADIMG | longtext | +| editor | 富文本 | EDITOR | longtext | +| relationForm | 关联表单 | RELATIONFORM | varchar | +| popupSelect | 弹窗选择 | POPUPSELECT | varchar | +| calculate | 计算 | CALCULATE | — | + +### 7.3 系统控件 + +| jnpfKey | 控件 | DB 类型 | +|---------|------|---------| +| userSelect | 选用户 | varchar | +| organizeSelect | 选组织 | varchar | +| roleSelect | 选角色 | varchar | +| currOrganize | 当前组织 | varchar | +| createUser | 创建人 | varchar | +| createTime | 创建时间 | datetime | +| modifyUser | 修改人 | varchar | +| modifyTime | 修改时间 | datetime | +| billRule | 单据规则 | varchar(255) | + +### 7.4 布局/容器 + +| jnpfKey | 控件 | +|---------|------| +| **table** | **子表容器** | +| groupTitle | 分组标题 | +| divider | 分割线 | +| button | 按钮 | +| link | 链接 | +| alert | 提示 | +| iframe | 内嵌 | +| row / card / tab / collapse | 布局容器 | + +### 7.5 jnpfKey → 运行态组件映射 + +| jnpfKey | tag(运行态) | 设计态组件 | +|---------|--------------|-----------| +| input | JnpfInput | RInput.vue | +| inputNumber | JnpfInputNumber | RInputNumber.vue | +| select | JnpfSelect | RSelect.vue | +| datePicker | JnpfDatePicker | RDatePicker.vue | +| uploadFile | JnpfUploadFz | RUploadFz.vue | +| table | JnpfTable | RTable/index.vue | +| relationForm | JnpfRelationForm | RRelationForm/index.vue | + +--- + +## 8. jnpfKey → DB 类型映射 + +| jnpfKey | dataType | dataLength | +|---------|----------|------------| +| input / select / radio / textarea | varchar | 255 | +| inputNumber | decimal | — | +| datePicker / timePicker | datetime | — | +| uploadFile / editor / sign | longtext | — | +| billRule | varchar | 255 | +| 系统字段 | varchar | 50 | + +--- + +## 9. API 参考(dacli 内部已封装,这里给契约) + +### 9.1 OnlineDev 数据提交(POST /api/visualdev/OnlineDev/{modelId}) + +**请求体**:`data` 字段必须是 JSON **字符串**(非嵌套对象),日期用 **Unix 毫秒时间戳**。 + +```json +// ✅ 正确 +{"data": "{\"f_name\":\"设备A\",\"f_date\":1749398400000}", "menuId": "xxx"} + +// ❌ 错误(→ swapDatetime NPE) +{"f_name": "设备A", "f_date": "2026-06-09"} +``` + +| 日期格式 | 结果 | +|---------|------| +| Unix 毫秒 `1749398400000` | ✅ | +| 字符串 `"2026-06-09"` | ❌ NPE | +| 空字符串 `""` | ❌ NPE | +| `null` / 不传 | ✅ 跳过 | + +> 源码:`VisualdevModelDataController.java:526` — `JsonUtil.stringToMap(visualdevModelDataCrForm.getData())` + +### 9.2 VisualDev CRUD(/api/visualdev/Base) + +**Create**:`POST /api/visualdev/Base` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| fullName | string | ✅ | 表单名称 | +| enCode | string | ✅ | 表单编码 | +| type | int | ✅ | 1=应用开发, 2=系统表单 | +| webType | int | ✅ | 1=纯表单, 2=表单+列表, 3=表单+列表+工作流, 4=视图 | +| formData | string | ✅ | 表单配置 JSON 字符串 | +| tables | string | ✅ | 物理表元数据 JSON 字符串 | +| columnData | string | — | PC 列表配置 JSON 字符串 | +| appColumnData | string | — | APP 列表配置 JSON 字符串 | +| dbLinkId | string | — | 数据源 ID(默认从 token.json 读) | +| state | int | — | 0=未发布, 1=已发布 | +| category | string | — | 分类(UUID 无横线格式) | +| enableFlow | int | — | 0=无流程, 1=启用流程 | +| flowTemplateJson | string | — | 流程定义 JSON | + +> `formData`/`tables`/`columnData` 都是 **JSON.stringify 后的字符串**,不是嵌套对象(用 `om.writeValueAsString(map)` 而不是 `om.convertValue(map, Map.class)`)。 + +**Update**:`PUT /api/visualdev/Base/{id}` — 同 Create 字段 + `id` + +**Release**:`POST /api/visualdev/Base/{id}/Actions/Release` + +**Clone**:`POST /api/visualdev/Base/{id}/Actions/Copy` — **不返回新 ID**,需轮询 `/api/visualdev/Base`(无 /list)diff 检测 + +### 9.3 Menu API(POST /api/system/Menu) + +type=3(VisualDev 表单菜单)必填字段: + +```json +{ + "fullName": "菜单名称", + "enCode": "菜单编码", + "parentId": "-1", + "type": 3, + "enabledMark": 1, + "sortCode": 0, + "category": "Web", + "linkTarget": "_self", + "isButtonAuthorize": 1, + "isColumnAuthorize": 1, + "isDataAuthorize": 1, + "isFormAuthorize": 1, + "moduleId": "表单ID", // ⚠️ 必须顶层,不能嵌在 propertyJson 内 + "propertyJson": "{\"iconBackgroundColor\":\"\",\"isTree\":0,\"webType\":2}", + "urlAddress": "model/{enCode}", + "pageAddress": "model/{enCode}", // ⚠️ 必填 + "icon": "icon-ym icon-ym-webForm" +} +``` + +Menu 类型:`1`=目录, `2`=Vue扩展页面, `3`=VisualDev表单, `7`=外链, `8`=门户, `11`=回传表单 + +> ⚠️ **常见 bug**:`moduleId` 放在 propertyJson 内部 → 前端找不到关联表单 → 内容区空白。详见 `menu-configuration` SKILL.md。 + +### 9.4 DataModel 建表 API(POST /api/system/DataModel/{linkId}/Table) + +```json +{ + "tableInfo": { "table": "表名", "tableName": "中文名", "newTable": "表名" }, + "tableFieldList": [ + { "field": "f_id", "fieldName": "主键", "dataType": "varchar", "dataLength": "50", "primaryKey": 1, "allowNull": 0, "autoIncrement": 0, "identity": 0, "index": "0" } + ] +} +``` + +> `tableInfo.newTable` 必填(否则 NPE)。`dataLength` 必填(`@NotBlank`),datetime/text 给 `"0"`。 + +### 9.5 工作流表单(webType=3) + +创建时额外设置:`webType=3`, `enableFlow=1`, `flowTemplateJson=` + +`flowTemplateJson` 包含:`nodeName`, `nodeType`(startEvent/userTask/endEvent), `nodeProperty`, `childNode` + +> CLI 无法自动生成 BPMN JSON,需 UI 设计器创建后导出复用。 + +启用后自动增加字段:`f_flow_id`, `f_flow_task_id`, `f_flow_state` + +--- + +## 10. 关键结论速记 + +1. **子表 ID = 主表 ID + 1**(绝对规则) +2. **外键**:子表 `f_foreignId` ↔ 主表 `f_id` +3. **子表内字段 tableName 错位**:`__config__.tableName` 写的是主表名,真实表看 `relationTable` +4. **子表内字段不参与后端 checkForm 校验**:只靠 DB NOT NULL 约束 +5. **前端添加子表字段**:必须 `isSubTable=true, parentVModel, relationTable` +6. **OnlineDev API data 格式**:`data` 是 JSON 字符串,日期用 Unix 毫秒时间戳 +7. **Menu moduleId**:必须顶层字段,不能嵌在 propertyJson 内 +8. **tables[] 完整性**:7 个基础字段缺一 Release NPE +9. **formData/tables/columnData**:API 传参时是 JSON 字符串,不是嵌套对象 +10. **唯一约束**:仅 input 控件支持 `unique=true` + +--- + +## 11. 源码索引(给 `dacli codegraph trace` 用) + +### 11.1 后端 Java + +| 功能 | 文件路径 | 关键方法 | +|------|---------|---------| +| **保存入口** | `后端/jnpf-java-boot/jnpf-visualdev/jnpf-visualdev-onlinedev/jnpf-visualdev-onlinedev-biz/src/main/java/jnpf/onlinedev/service/impl/VisualdevModelDataServiceImpl.java` | `visualCreate:296`, `visualUpdate:387`, `getInfo` | +| **保存 Controller** | `后端/jnpf-java-boot/jnpf-visualdev/jnpf-visualdev-onlinedev/jnpf-visualdev-onlinedev-controller/src/main/java/jnpf/onlinedev/controller/VisualdevModelDataController.java` | `create:513`, `update:545` | +| **校验** | `后端/jnpf-java-boot/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/src/main/java/jnpf/base/util/FormCheckUtils.java` | `checkForm:111` | +| **SQL 写库** | `后端/jnpf-java-boot/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/src/main/java/jnpf/base/util/FlowFormDataUtil.java` | `create:519`, `createMast:820`, `createTable:717`, `createMastTable:637` | +| **数据解析** | `后端/jnpf-java-boot/jnpf-visualdev/jnpf-visualdev-onlinedev/jnpf-visualdev-onlinedev-biz/src/main/java/jnpf/onlinedev/util/OnlineSwapDataUtils.java` | `swapDatetime:418` | +| **控件树解析** | `后端/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/model/visualjson/FormCloumnUtil.java` | `recursionFormGen:46`, `model:169` | +| **jnpfKey 常量** | `后端/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/util/visiual/JnpfKeyConsts.java` | — | + +### 11.2 前端 Vue3 + +| 功能 | 文件路径 | +|------|---------| +| **设计器主入口** | `前端/jnpf-web-apps-main/src/components/FormGenerator/src/FormGenerator.vue` | +| **设计器类型定义** | `前端/jnpf-web-apps-main/src/components/FormGenerator/src/types/genItem.ts` | +| **控件库定义** | `前端/jnpf-web-apps-main/src/components/FormGenerator/src/helper/componentMap.ts` | +| **配置规则** | `前端/jnpf-web-apps-main/src/components/FormGenerator/src/helper/config.ts`(`noTableAllowList`) | +| **子表设计器** | `前端/jnpf-web-apps-main/src/components/FormGenerator/src/rightComponents/RTable/index.vue`(`addComponent:117`) | +| **API 调用** | `前端/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts` | + +> ⚠️ 源码路径是 JNPF 官方仓库的,本仓库 `jnpf/` `web/` 不可改(CLAUDE.md 禁止)。**仅用于 `dacli codegraph search/trace` 查实现**。