feat(claude): merge 7 new rules + 4 skill references + slim design-jnpf-execute
CLAUDE.md 融合 (6 条新规则 + 1 条强化): - §9 默认凭据 admin / 123456 (替换 4 处 <密码> 占位符) - §10 nginx 不可用 fallback (127.0.0.1:30000 + web/**/dist + web/**/public) - §11 不在 CLAUDE.md/技能里写应用特定信息 (下轮清理 docs/ 时会删) - §12 主 skill 文件不搞大 (SKILL.md > 800 行 → 抽 references/) - §13 复现盲点固化前先验证 (developSystem/workSystem 跑通再入主) - §14 一轮一提交 (git hooks 已注册,验证: git log 看到 auto(session end)) - 强化: §统一入口 加 admin/123456 默认 + nginx fallback 表 Skills 融合 (4 个新 references 文档): - platform-mechanism/references/jnpf-form-data-model.md (19KB) 从 docs/dacli/dev-rs.md - dacli-architecture/references/dacli-conf-usage.md (4.4KB) 从 docs/dacli/2/dacli-conf-usage.md - design-jnpf-execute/references/c58-v11-todo.md (12.7KB) 从 docs/tds/polish-design-jnpf-execute-v11.md - design-jnpf-execute/references/subagent-prompts.md (268 行) 从 SKILL.md 1168-1430 抽出 4 子代理 prompt 设计-jnpf-execute 瘦身: 1522 → 1288 → 1279 行 (-243, -16%) - 4 子代理 A/B/C/D prompt 模板抽出 → references/subagent-prompts.md - v11 待办表抽出 → 末尾 1-2 行指针 (主 SKILL.md 不放项目计划) - 同步清理自检: 子代理 grep 改指 references,删除已 deprecated 的 docs/dacli/2 检测行 MEMORY 记录 (3 个): - docs-dacli-skill-fusion-2026-06-11.md 融合总览 - design-jnpf-execute-slim-2026-06-11.md 瘦身记录 - skill-no-todo-pollution.md SKILL.md 不放 todo 原则
This commit is contained in:
1 parent
ce85bc563f
commit
d0dcfd0dbc
6 files changed
+1228
-3
No files matched your search
@@ -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/<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 轮改动一次提(出问题难回滚)
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
@@ -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=<app>` 重新登录(token 7天过期)
|
||||
- `dacli login --account=admin --password=123456 --appCode=<app>` 重新登录(token 7天过期)
|
||||
- `dacli form list` 确认表单已发布(state=1)
|
||||
- `dacli menu list` 确认菜单 systemId 匹配当前应用
|
||||
- `dacli form list` 验证 API 可用性(curl + jq 详见 `api-test` 技能)
|
||||
|
||||
@@ -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 <path>`** 命令行参数(最高优先)
|
||||
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 <port><url>)|
|
||||
| `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 <pids> + 等待退出(最多 10s)
|
||||
5. ls -t boot/jnpf-admin/target/ | grep 找最新 jar
|
||||
6. nohup <start-cmd> & 启动
|
||||
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. 故障排查
|
||||
|
||||
| 现象 | 可能根因 | 修复 |
|
||||
|------|---------|------|
|
||||
| `没找到匹配 <jar-pattern> 的旧进程` | 进程名与正则不匹配 | 检查 `pgrep -f '<pattern>'` |
|
||||
| `没找到 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`
|
||||
@@ -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 <id>` 验证 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_<name>\\\":\\\"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**(通用规则、平台机制、工具方法、命令模板、复现命令的占位符 `<db_host>`/`<app_code>`/`<form_id>` 等)
|
||||
- **留 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 目标**。
|
||||
@@ -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="<type_id>"`(全拼,注意 "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=<section_name>`,**不要** `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": <int>,
|
||||
"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": <int>
|
||||
}
|
||||
3. 生成 bash 脚本,每步独立 + set -e
|
||||
4. **强制验证**:脚本末尾用 `dacli dict type-list | grep <enCode>` + `dacli dict data-list <typeId> | 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>" # sql 模式;api 模式用 --url(参考 dacli di create --help)
|
||||
4. SQL 模式需转义单引号(用 \" 转义)
|
||||
5. **创建后立即 list 验证**:
|
||||
dacli di list | grep "<enCode>" || 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 <baseline_id>` 拉 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=<id>` 拉真实字段名映射,**禁止**按通用命名(`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=<id>` 拉真实字段名映射**,**禁止**按通用命名(`f_name`/`f_code`)假设!
|
||||
- 实际案例(应用特定):`<input_field_1>` / `<input_field_2>` / `<user_field>`(**不是** `<generic_name>` / `<generic_code>` / `<generic_user>`)
|
||||
- 字段名不对 → 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="<enCode>" \
|
||||
--webType=2 \
|
||||
--dbLinkId=default \
|
||||
--fields='[
|
||||
{
|
||||
"field": "<f_xxx>", # 物理字段名(不是 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=="<enCode>") | .id')
|
||||
MENU_ID=$(jq -r '.["<enCode>"]' 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_<name>\\\":\\\"smoke_test\\\"}\"}"
|
||||
# ❌ 错: {"f_name":"test1"} → 400
|
||||
# ✅ 对: {"menuId":"...","data":"{\"f_name\":\"test1\"}"} → 200
|
||||
```
|
||||
6. **创建后立即 list 验证**:
|
||||
dacli form list | grep "<enCode>" || 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=<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=<appCode> 且 parentId=-1 的 ID"`
|
||||
3. 对每个菜单生成命令(高层 API,dacli 内化 7 字段必填):
|
||||
dacli menu create \
|
||||
--name="<菜单名称>" \
|
||||
--enCode="<enCode>" \
|
||||
--parentId="<父菜单ID 或 -1>" \
|
||||
--type=3 \
|
||||
--formId="<关联表单ID>" \
|
||||
--authorize
|
||||
4. **创建后立即 list 验证**:
|
||||
dacli menu list | grep "<enCode>" || exit 1
|
||||
5. **【v11 新增】菜单 count 校验(盲点 23 防御)**:
|
||||
```bash
|
||||
ACTUAL_COUNT=$(dacli menu list --keyword="<appCode>_" | 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=<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 校验结果 / 脚本路径
|
||||
```
|
||||
@@ -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 <id> --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=<BPMN JSON>`
|
||||
|
||||
`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` 查实现**。
|
||||
Reference in new issue
Block a user