auto(6f177c177d02): session end @ 2026-06-12T18:14:48 (+17f)

This commit is contained in:
ssw committed 2026-06-12 18:14:48 +08:00
1 parent 3579e98f48
commit 0b937d63d2
19 files changed
+33 -4307

No files matched your search

+24 -15
View File
@@ -48,11 +48,15 @@
> **架构演进 (2026-06-06)**:1) **Redis → SQLite 迁移**(`SqliteCacheService` 替代 `RedisCacheService`,缓存文件 `~/.dacli/cache.db`,无需外部 Redis 容器);2) **GraalVM Native 编译**(启动 800ms→100ms,输出 `target/dacli` 原生二进制);3) **dacli codegraph 新增**(基于 `codegraph.db` 静态分析 JNPF 源码,7 子命令:search/calls/trace/impact/contains/implements/route)。
>
> **dacli form 高频能力内化 (2026-06-09)**:高频场景已直接做进 `dacli form create` 参数:`--webType=4`(视图,无物理表)/ `--enableFlow=1 --flowId=X`(工作流绑定)/ `--fields` JSON 加 `interfaceId`(数据接口字段)。**`form template` 子命令族已下线**——长尾场景(联动/JS增强/列表样式/套打/i18n)由 `form-development` 技能里的速查表指引:找 ID → `dacli form info <id>` 读结构 → 仿造。备份/迁移用 `form export/import`,结构修复用 `form fix`。
>
> **dacli 迁移到 TS 版 (2026-06-12)**:Java 版(`boot/ssw-dacli/`,261 mvn test 已成熟)已**废弃**,源码归档到 `docs/dacli/ssw-dacli/` 备查(无 `target/`,需手动 `mvn package` 才能跑 jar)。**当前 CLI 改用 TS 版**(`$ccWorkDir/dacli/`,v0.7,8 父命令 / 26+ 子命令,启动 < 500ms)。TS 版功能对照见 `.claude/skills/dacli-ts/SKILL.md` v0.7 校准段。Java 版仅在 TS 版没实现的边缘场景(报表/门户/portal/codegen)兜底。
### 别名配置
### 别名配置(TS 版)
```bash
alias dacli='java -jar $ccWorkDir/boot/ssw-dacli/target/ssw-dacli-*.jar'
alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts'
```
> 首次使用:`cd $ccWorkDir/dacli && npm install`
> 项目结构变更:原 `test/dacli/` 升级为 `$ccWorkDir/dacli/`(顶层独立项目)。
### 常用命令
```bash
@@ -320,19 +324,26 @@ $ccWorkDir/
│ └── skills/ # 技能定义
├── boot/ # 后端 Spring Boot
│ ├── jnpf-admin/ # 主模块
│ ├── ssw-dacli/ # CLI工具(独立JAR)
│ └── ssw-{app_code}/ # 业务模块
├── dacli/ # ✅ TS 版 dacli (v0.7, 0 差错 baseline)
│ ├── src/ # CLI 源码 (npx tsx src/cli.ts)
│ ├── tests/ # vitest + Playwright
│ ├── doc/ # 架构/plan/api/extractors 等文档
│ ├── .claude/skills/dacli-ts/ # 教 AI 何时用哪个命令
│ └── package.json
├── web/ # 前端 Vue3
├── test/ # E2E测试 (Playwright)
├── jnpf/ # jnpf开发平台源代码
├── docs/ # 文档
│ └── {app_code}/ # 应用文档(HTML输出)
│ ├── assets/ # CSS/JS/Mermaid
│ ├── design.html # 详细设计方案
│ ├── testcase.html # 测试用例
│ ├── plan.html # 开发计划(上下文恢复用)
│ ├── debug.html # 问题记录
│ └── summary.html # 总结报告
│ ├── {app_code}/ # 应用文档(HTML输出)
│ │ ├── assets/ # CSS/JS/Mermaid
│ │ ├── design.html # 详细设计方案
│ │ ├── testcase.html # 测试用例
│ │ ├── plan.html # 开发计划(上下文恢复用)
│ │ ├── debug.html # 问题记录
│ │ └── summary.html # 总结报告
│ └── dacli/
│ └── ssw-dacli/ # 📦 Java 版 dacli 归档(已废弃, 仅备查, 无 target/)
```
---
@@ -343,14 +354,12 @@ $ccWorkDir/
# 编译打包
cd $ccWorkDir/boot && mvn clean package -DskipTests
# 编译 dacli 独立工具
cd $ccWorkDir/boot && mvn clean package -DskipTests -pl ssw-dacli -am
# 启动 JNPF(Web服务,端口30000)
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 使用(TS 版)
alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts'
cd $ccWorkDir/dacli && npm install # 首次需装依赖
dacli login --account=admin --password=123456 --appCode=developSystem
# E2E测试(playwright-cli)
+9 -13
View File
@@ -15,34 +15,30 @@ set -u # 不用 -e:单步失败要继续后续步骤
CCWORKDIR="/home/ubuntu/ccWorkDir"
BASHRC="$HOME/.bashrc"
NATIVE_BIN="$CCWORKDIR/boot/ssw-dacli/target/dacli"
DACLI_SRC="$CCWORKDIR/dacli/src/cli.ts"
PLAYWRIGHT_CLI_BIN="/usr/lib/node_modules/@playwright/cli/playwright-cli.js"
PLAYWRIGHT_CLI_LINK="/usr/local/bin/playwright-cli"
log() { echo "[init.sh] $*"; }
# ============ 1. dacli 命令(软链到 /usr/local/bin,PATH 自动命中) ============
log "① 配置 dacli 命令"
# ============ 1. dacli 命令(TS 版 npx tsx wrapper,PATH 自动命中) ============
log "① 配置 dacli 命令 (TS 版)"
DACLI_LINK="/usr/local/bin/dacli"
# 顺手清掉旧 alias(避免 .bashrc 残留干扰 type/which 输出)
if [ -f "$BASHRC" ]; then
sed -i '/^# dacli alias (JNPF CLI)/d; /^alias dacli=/d' "$BASHRC"
fi
# native 比 jar 新就软链 native,否则写 jar wrapper:让 dacli 命令在两种产物下都能用
DCLI_JAR=$(ls "$CCWORKDIR/boot/ssw-dacli/target"/ssw-dacli-*.jar 2>/dev/null | head -1)
if [ -f "$NATIVE_BIN" ] && { [ -z "$DCLI_JAR" ] || [ "$NATIVE_BIN" -nt "$DCLI_JAR" ]; }; then
ln -sf "$NATIVE_BIN" "$DACLI_LINK"
log " ✅ native: $DACLI_LINK → $NATIVE_BIN"
elif [ -n "$DCLI_JAR" ]; then
# TS 版:通过 npx tsx 调 cli.ts,写 wrapper 脚本到 /usr/local/bin
if [ -f "$DACLI_SRC" ]; then
cat > "$DACLI_LINK" <<EOF
#!/bin/bash
exec java -jar "$DCLI_JAR" "\$@"
exec npx --prefix "$CCWORKDIR/dacli" tsx "$DACLI_SRC" "\$@"
EOF
chmod +x "$DACLI_LINK"
log " ✅ jar wrapper: $DACLI_LINK → java -jar $DCLI_JAR"
log " 💡 跑 dacli-native-build.sh 可改用 native(启动 ~100ms)"
log " ✅ TS 版 wrapper: $DACLI_LINK → npx tsx $DACLI_SRC"
log " 💡 首次使用需 cd $CCWORKDIR/dacli && npm install"
else
log " ⚠️ 既无 native 也无 jar: mvn package -pl ssw-dacli -am"
log " ⚠️ 找不到 TS 版入口: $DACLI_SRC(应位于 \$ccWorkDir/dacli/)"
fi
log " ✅ $(command -v dacli 2>/dev/null || echo '(未在 PATH 中)')"
-1
View File
@@ -84,7 +84,6 @@ if (toolName === 'Write' || toolName === 'Edit') {
'web/apps/jnpf-web-apps-main/src/views/ssw/',
'web/apps/jnpf-web-apps-main/public/ssw',
'uniapp/pages/ssw/',
'boot/ssw-dacli/src/main/java/com/jnpf/' // ssw-dacli module
];
for (const { path: denied } of deniedPaths) {
-1
View File
@@ -35,7 +35,6 @@
"Read(//home/ubuntu/**)",
"Bash(bash -ic 'type dacli; dacli --version')",
"Bash(rm -f *.json)",
"Bash(rmdir /home/ubuntu/ccWorkDir/boot/ssw-dacli/src/main/resources/dacli/templates)",
"Bash(mkdir -p /home/ubuntu/ccWorkDir/.claude/skills/design-jnpf-execute/scripts)",
"Bash(mkdir -p /home/ubuntu/ccWorkDir/.claude/skills/ssw-e2e-test/scripts)",
"Bash(git mv *)",
BIN
View File
Binary file not shown.
-349
View File
@@ -1,349 +0,0 @@
---
name: dacli-architecture
description: Use when modifying dacli, adding new commands, or integrating dacli with ssw-* business modules. Documents the post-Picocli + post-nested-class architecture (2026-06-05 refactor).
---
# dacli 架构 (Picocli + 嵌套类)
## 适用场景
修改/扩展 dacli 工具、添加新命令、调试 dacli 与 ssw 业务模块的集成时必读。
## 演进历史 (2026-06-05 重构)
| 阶段 | 状态 | 关键变更 |
|------|------|---------|
| 阶段 0 | ✅ 完成 | 提取 `DacliKit` 静态工具类;删除 `BaseCommand.java`;所有命令 `implements Callable<Integer>` |
| 阶段 1 | ✅ 完成 | `DacliRoot` + 5 个无子命令命令(login/status/logs/initapp/codegen)迁移到 Picocli |
| 阶段 2 | ✅ 完成 | `form` 全套子命令迁移(list/info/create/release/delete)作为模式示例 |
| 阶段 3 | ✅ 完成 | role(8) + datasource(12) + org(12) + dict(14) + user(17) + file(22) + menu(10)/workflow/di/dm/portal/report 共 100+ 子命令迁移到 Picocli |
| 阶段 4 | ✅ 完成 | e2e(17 actions) + test(复杂路由) 通过 call() 包装原命令类 |
| 阶段 5 | ✅ 完成 | 删除 `Dacli.commands Map`、内部类、`printHelp()`、`help.txt`、`RedisCacheService.getHelp/setHelp`;`scripts/verify.sh --full` 34/34 通过 |
| **阶段 6** | ✅ **完成** | **嵌套类重构**:13 父命令的 109 个子命令合并为 `static nested class`;文件数 143→19(**-87%**) |
| **阶段 7** | ✅ **完成** | **新增 `dacli doc` 子命令**:HTML 文档缓存,AI 读取 token 降低 80%。详见 `.claude/skills/dacli-doc-cache/SKILL.md` |
| **阶段 8** | ✅ **完成** | **移除 curl/playwright-cli 包装**:删除 `dacli test` 和 `dacli e2e`,直接用系统原生 `curl` + `playwright-cli`(更标准、跨平台、无版本耦合) |
| **阶段 9** | ✅ **完成** | **新增 `dacli apis` 子命令**:从 `/v3/api-docs` 拉 JNPF 全量 OpenAPI 写入 SQLite(PID 变化 + 12h TTL 自动失效),提供 list/info/search/status 给 AI 快速查 JNPF 平台 API |
| **阶段 10** | ✅ **完成** | **架构演进**:1) GraalVM Native 编译(启动 800ms→100ms,输出 `target/dacli` 原生二进制);2) **Redis → SQLite 迁移**(`SqliteCacheService` 替代 `RedisCacheService`,缓存文件 `~/.dacli/cache.db`,无需外部 Redis 容器);3) 新增 `dacli codegraph` 子命令(基于 `codegraph.db` 静态分析,7 子命令:search/calls/trace/impact/contains/implements/route) |
| **阶段 11** | ✅ **完成** | **新增 `dacli form export/import` 子命令**:备份/迁移表单结构(完整 formData/columnData/tables/buttonData/flowTemplateJson)。**`form template` 子命令族已在 2026-06-09 重做时下线**——AI 应在 `form-development` 技能里查官方示例速查表,用 `dacli form info <id>` 读真实结构后仿造,比"一键 apply"更可控。 |
完整计划:`docs/dacli/dacli-fix-plan.md`、`docs/dacli/h5doc-plan.md`
## 当前架构(阶段 6+7 完成后)
```
src/main/java/com/jnpf/dacli/
├── Dacli.java # 精简入口:直接 new CommandLine(new DacliRoot()).execute(args)
├── DacliRoot.java # Picocli 根命令 @Command(name="dacli"),注册 20 个子命令
├── DacliKit.java # 静态工具类(替换原 BaseCommand)
├── DacliConfig.java # 配置加载(含 doc.cache.ttl)
├── SqliteCacheService.java # SQLite 缓存(替代原 RedisCacheService,文件 `~/.dacli/cache.db`;+ deleteByPattern 方法,dacli doc/apis 用)
├── SswCodeGenerator.java # ssw 业务包生成
├── FormBuilder.java # 表单构造器
│
├── 顶级 @Command 类(共 20 个):
│ ├── 5 工具/包装命令: LoginCommand, StatusCommand, LogsCommand,
│ │ InitAppCommandWrapper, CodegenCommandWrapper
│ │
│ └── 15 业务父命令(**含嵌套子命令**):
│ ├── FormCommand (5 nested: List/Info/Create/Release/Delete)
│ ├── RoleCommand (8 nested: List/Info/Create/Update/Delete/Selector/...)
│ ├── DatasourceCommand (12 nested: List/Selector/Create/Update/.../Sync/...)
│ ├── OrgCommand (12 nested: List/AsyncList/Info/Create/Update/.../Import/Export)
│ ├── DictCommand (14 nested: TypeList/TypeInfo/.../DataList/.../DataExport)
│ ├── UserCommand (17 nested: List/Info/Create/Update/.../Import/Export/...)
│ ├── FileCommand (22 nested: DownloadUrl/Preview/ChunkMerge/.../DocList/.../DocShare/...)
│ ├── MenuCommand (10 nested: List/Info/Create/Update/Delete/Cleanup/Move/Clone/Export/Import)
│ ├── WorkflowCommand (6 nested: List/Create/Launch/Approve/Reject/Pending)
│ ├── DiCommand (3 nested: List/Create/Preview)
│ ├── DmCommand (6 nested: List/Table/Query/Create/Update/Drop)
│ ├── PortalCommand (2 nested: List/Create)
│ ├── ReportCommand (2 nested: List/Create)
│ ├── DocCommand (5 nested: List/Get/Scan/Refresh/Clear) — HTML 文档缓存
│ └── ApiCommand (5 nested: List/Info/Search/Refresh/Status) — OpenAPI/Swagger 查询(SQLite 缓存)
│ └── CodegraphCommand (7 nested: Search/Calls/Trace/Impact/Contains/Implements/Route) — JNPF 代码图谱查询(基于 codegraph.db)
│ └── FormCommand (10 nested: List/Info/Create/Release/Delete/Clone/Fix/MsRelation/Export/Import) — 阶段 11 新增 export/import(template 子命令族已下线)
│
└── commands/ # 仅保留 1 个被 wrapper 引用的类
└── InitAppCommand.java # v10.6.1 加 --restart 标志 + restartJnpf + isJnpfHealthy
└── DacliConf.java # v10.6.1 新增 - dacli.conf 配置文件读取器 (jar-pattern/port/health-url)
```
**结构变化**:
- 阶段 6:143 个独立 Command 文件 → 19 个 Command 文件(-87%)
- 阶段 8:移除 `TestCommand` / `E2eCommand`(curl/playwright-cli 包装),用系统原生命令替代
## 关键约束
### 1. 入口已极简化(阶段 5)
```java
public class Dacli {
public static void main(String[] args) {
int exitCode = new CommandLine(new DacliRoot()).execute(args);
System.exit(exitCode);
}
}
```
所有命令通过 `DacliRoot` 的 `@Command` 注册后由 Picocli 路由。
### 2. DacliKit 静态方法
所有命令类调用的 HTTP/Token/JSON 工具方法都从 `BaseCommand` 移到 `DacliKit`:
```java
import com.jnpf.dacli.DacliKit;
// HTTP
DacliKit.doGet(path)
DacliKit.doPost(path, body)
DacliKit.doPut(path, body)
DacliKit.doDelete(path)
// Token
DacliKit.loadToken() -> Map<String,Object>
DacliKit.getToken() -> String
DacliKit.getAppCode() -> String
DacliKit.tokenFile() -> String (路径)
// 参数
DacliKit.parseArgs(args) -> Map<String,String>
DacliKit.getArgValue(args, key, pos) -> String
DacliKit.getDbLinkId(m, "dbLinkId") -> String
DacliKit.parseJson(json) -> Map<String,Object>
// 密码
DacliKit.encryptPassword(plain) -> String (md5 + AES)
DacliKit.isEncryptedPassword(p) -> boolean
```
### 3. 新增 Picocli 命令的模板(嵌套类模式)
**当前推荐**:在父命令文件中用 `static class` 嵌套类。Picocli 自动发现嵌套子命令。
```java
@Command(name = "my",
description = "...",
mixinStandardHelpOptions = true,
subcommands = {
MyCommand.ListCommand.class,
MyCommand.GetCommand.class,
})
public class MyCommand implements Callable<Integer> {
@Override
public Integer call() {
new CommandLine(this).usage(System.out);
return 0;
}
// ──── 嵌套子命令 ────
@Command(name = "list", description = "...", mixinStandardHelpOptions = true)
static class ListCommand implements Callable<Integer> {
@Option(names = {"--foo"}, required = true, description = "...")
private String foo;
@Override
public Integer call() throws Exception {
String result = DacliKit.doGet("/api/.../" + foo);
System.out.println(result);
return 0;
}
}
@Command(name = "get", description = "...", mixinStandardHelpOptions = true)
static class GetCommand implements Callable<Integer> {
// ...
}
}
```
**关键规则**:
- ✅ 嵌套类用 `static class`(**不是** inner class)
- ✅ 嵌套类默认 package-private 访问即可
- ✅ 父命令的 `subcommands = {...}` 引用嵌套类
- ✅ DacliRoot 注册父命令 `MyCommand.class`,Picocli 自动发现嵌套子命令
- ❌ 不要为每个子命令单独建文件(旧模式,已废弃)
- ❌ 不要修改 DacliRoot(除非新增父命令)
## Token 路径(2026-06-05 修正)
**实际路径**:`$ccWorkDir/.dacli-token/token.json`(运行时由 `DacliKit.java:41` 写死)
**不要**用 `~/.dacli/token.json`(CLAUDE.md 老路径,2026-06-05 已纠正)
**覆盖**:用 `$DACLI_TOKEN_DIR` 环境变量。
**快速定位**:`dacli status` 输出 token 路径。
## JNPF API 行为备注(dacli 开发必读)
### VisualDev 表单 API 端点差异
| 端点 | 返回范围 | 用途 |
|------|---------|------|
| `/api/visualdev/Base/list` | 仅已发布表单(state=1) | **不要用于 diff 检测** |
| `/api/visualdev/Base`(无 /list) | 全部表单(含未发布 state=0) | dacli form list 用此端点 |
### Copy API 行为
- `POST /api/visualdev/Base/{id}/Actions/Copy` 返回 `{code:200, msg:"Replicating Success"}`,**不返回新表单 ID**
- 克隆后表单默认 state=0(未发布),需单独调 `/Actions/Release` 发布
- dacli form clone 通过 diff 全量表单快照(before/after)检测新 ID
### Form 仿造工作流(替代 template apply)
`dacli form template` 子命令族在 2026-06-09 二次打磨时全部下线。AI 写新表单应:
1. 在 `.claude/skills/form-development/SKILL.md` 里的「workSystem 官方示例速查」表里找一个最接近的示例(id/enCode/特色)
2. `dacli switch-app --appCode=workSystem && dacli form info <示例ID>` 拿完整 formData/columnData/tables
3. 照思路写自己的字段,再用 `dacli dm create` + `dacli form create` 建出来
需要"几乎照搬"时,用 `dacli form export <id>` + `dacli form import` 走备份/恢复路径(不预建表,纯 JSON 复制)。结构出问题再 `dacli form fix` 走内置 baseline。
**为什么删 template apply**:一键 apply 整段照搬 formData 看起来快,但子表 vModel 命名跟新表对不上、字段语义跟新需求不符、改起来要回头读完整 JSON,**总成本 ≥ 看示例后手写**。dacli 只保留"基础骨架内化"(`FormBuilder.buildCreatePayload` + `baseline-schema.json`),结构灵活度交给 AI。
### 其他注意
- 表单列表默认 pageSize=20,需传 `?pageSize=N` 获取更多
- 中文 keyword 需 URL 编码(`URLEncoder.encode(keyword, "UTF-8")`)
## 编译验证
```bash
cd $ccWorkDir/boot
mvn -pl ssw-dacli -am clean package -DskipTests
# 自动验证(29 项 + --full 时 35 项)
bash ssw-dacli/scripts/verify.sh --full
# 快速测试
java -jar ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar <command> --help
java -jar ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar form list
```
## 不要做
- ❌ 不要新建 `BaseCommand` 兼容层(已彻底删除)
- ❌ 不要修改 `jnpf/` `web/` `uniapp/`(CLAUDE.md 禁止)
- ❌ 不要用 Java 11+ 特性(jnpf-admin 仅支持 Java 8,但 ssw-dacli 是 Java 21,**两者独立**)
- ❌ 不要在 `DacliRoot` 注册未实现的子命令(编译会失败)
- ❌ 不要为子命令单独建文件(用嵌套类,**阶段 6 之后的标准**)
- ❌ 不要在 `commands/` 包新增类(用顶级 @Command + 嵌套类更易管理)
## 相关技能
- **`.claude/skills/dacli-doc-cache/SKILL.md`** — `dacli doc` 缓存读取 HTML 文档(阶段 7 新增)
- **`.claude/skills/dacli-codegraph/SKILL.md`** — `dacli codegraph` JNPF 平台代码图谱查询(阶段 10 新增)
- **`.claude/skills/dacli-architecture/SKILL.md`**(本文件)— dacli 整体架构
- **`.claude/skills/api-test/SKILL.md`** — API 集成测试(用 curl + jq + dacli 业务命令,**不再用 `dacli test`**)
- **`.claude/skills/ssw-e2e-test/SKILL.md`** — E2E 测试(用原生 `playwright-cli -s=dacli`,**不再用 `dacli e2e`**)
- **`.claude/skills/ssw-e2e-test/scripts/test_dacli_e2e.sh`** — dacli API+CLI 套件(v10.3 = 26 项:P3-A/B + P4-B + P5 + P6 + P7 + P18 OLD 漂移 + P19 v10.2 columnData + P20 C.5.9 引用,可入 CI)
## 引用
- 完整 Picocli 迁移计划:`docs/dacli/dacli-fix-plan.md`
- 嵌套类 + dacli doc 计划:`docs/dacli/h5doc-plan.md`
- DacliKit 源码:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/DacliKit.java`
- 嵌套类模式示例:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/FormCommand.java`
- dacli doc 服务实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/DocService.java`
- dacli apis 服务实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/ApiService.java`(阶段 9 新增)
- dacli codegraph 实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/CodegraphCommand.java`(阶段 10 新增)
- GraalVM Native 实施记录:`docs/dacli/me.md`(仅维护者)
- **`references/dacli-conf-usage.md`** — `dacli.conf` 配置文件 + `dacli initapp --restart` 端到端配置
---
## 附录:阶段 10 实施细节(仅 dacli 维护者参考)
> **AI 工作流用不到本节**,但接手 dacli 维护 / 重新生成 native binary 时需要。本节是从 `docs/dacli/me.md` 提取的关键操作指引。
### A. GraalVM 23 下载(Oracle CDN 加速)
GitHub Releases 极慢(~12MB/min),用 Oracle CDN 替代:
```bash
# 推荐:GraalVM 23(21 CE 有 HTTP 协议 bug)
wget https://download.oracle.com/graalvm/23/latest/graalvm-jdk-23_linux-x64_bin.tar.gz
# 不推荐:GraalVM 21(有 bug)
# https://download.oracle.com/graalvm/21/archive/graalvm-jdk-21.0.2+13.1_linux-x64_bin.tar.gz
tar -xzf graalvm-jdk-23_linux-x64_bin.tar.gz -C /usr/local/
# 解压路径:/usr/local/graalvm-jdk-23.0.2+7.1/
# native-image 工具已内置
```
### B. Jar 编译(常规)
```bash
export JAVA_HOME=/usr/local/graalvm-jdk-23.0.2+7.1
export PATH=$JAVA_HOME/bin:$PATH
cd $ccWorkDir/boot/ssw-dacli
mvn package -q
# 输出:target/ssw-dacli-6.2.0-RELEASE.jar(~19MB fat-jar)
```
### C. Native 二进制编译
**⚠️ 坑:不要用 `native-maven-plugin` 自动编译**
`mvn package` 默认会触发 `native:compile`,但生成的命令**缺少关键参数**(`--enable-url-protocols` / `--initialize-at-run-time`),导致编译成功但运行时报错。**必须手动执行 `native-image`**:
`$ccWorkDir/boot/ssw-dacli/dacli-native-build.sh`(3002 字节,2026-06-06 验证可用):
```bash
#!/bin/bash
set -e
export JAVA_HOME=/usr/local/graalvm-jdk-23.0.2+7.1
export PATH=$JAVA_HOME/bin:$PATH
cd "$(dirname "$0")"
# 1. 生成 fat-jar(不触发 native 编译)
mvn package -DskipTests -q
FAT_JAR="target/ssw-dacli-6.2.0-RELEASE.jar"
OUT="target/dacli"
# 2. 手动 native-image
native-image \
--no-fallback \
--enable-url-protocols=http,https \
--initialize-at-run-time=org.sqlite \
-H:DeadlockWatchdogInterval=0 \
-H:+ReportUnsupportedElementsAtRuntime \
-jar "$FAT_JAR" \
-o "$OUT"
```
执行:`./dacli-native-build.sh` → `target/dacli`(~50MB 原生二进制,启动 ~100ms)
### D. 关键编译参数说明
| 参数 | 作用 | 必须? |
|------|------|--------|
| `--no-fallback` | 生成纯原生二进制,不依赖 JVM | 是 |
| `--enable-url-protocols=http,https` | 允许 `new URL("http://...")`(GraalVM 默认禁 HTTP) | 是 |
| `--initialize-at-run-time=org.sqlite` | SQLite JDBC 延迟初始化(避免构建时初始化报错) | 是(用 SQLite 时) |
| `-H:DeadlockWatchdogInterval=0` | 禁用死锁看门狗(避免被误杀) | 建议 |
| `-H:+ReportUnsupportedElementsAtRuntime` | 构建时不报错,运行时再报 | 建议 |
### E. 验证产物
```bash
./target/dacli --version # 验证 native binary 可运行
ldd target/dacli # 确认依赖(理想:纯静态或少量系统库)
```
### F. 已知坑
- **Jedis 兼容性差** → 阶段 10 已迁移到 SQLite,避开 reflect-config 维护
- **GraalVM 21 HTTP 协议 bug** → 强制使用 GraalVM 23
- **`native-maven-plugin` 自动编译缺参** → 必须手动 `native-image`(见 C 节)
- **构建时间长(5-10 分钟)** → `target/dacli` 不应频繁重建,CI 缓存或按需发布
### G. 维护者 CheckList
- [ ] 新增子命令后必须 `mvn package` 验证 jar 启动
- [ ] 重大依赖变更(加/减依赖)后必须 `./dacli-native-build.sh` 重新出 native binary
- [ ] 重新生成 `codegraph.db` 后 `dacli.conf` 的 `codegraph.dbPaths` 路径不变即可
- [ ] 缓存格式变更(`SqliteCacheService` 表结构)需要考虑老 db 兼容,必要时加 version 字段
@@ -1,140 +0,0 @@
# 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`
-293
View File
@@ -1,293 +0,0 @@
---
name: dacli-codegraph
description: 通过 dacli codegraph 查询 JNPF 平台源码的代码图谱(基于 codegraph.db 静态分析结果)。能力:全文搜索、调用链追踪、跨模块路径、修改影响分析、API 反查 Controller。触发词:JNPF 源码、调用链、codegraph、controller 反查、影响分析
---
# dacli codegraph — JNPF 平台代码图谱查询
> **⚠️ 仅适用于 JNPF 平台。** `codegraph.db` 是对 JNPF 低代码平台自身源码(后端 Java + 前端 Vue/TypeScript)的静态解析结果。所有查询结果均为 JNPF 平台的代码实体(Controller / Service / Mapper / 组件 / 路由等),不适用于其他项目。
---
## 1. 数据来源
| 表 | 行数级别 | 说明 |
|----|---------|------|
| `nodes` | ~15 万 | 代码实体(类/方法/字段/组件/路由) |
| `edges` | ~38 万 | 关系(calls/contains/references/imports/implements/instantiates) |
| `nodes_fts` | ~15 万 | FTS5 全文搜索索引(基于 name/qualified_name/docstring) |
`codegraph.db` 实际大小约 400MB,存放在:
- `~/.dacli/codegraph.db`(默认用户级)
- `$ccWorkDir/jnpf/.codegraph/codegraph.db`(项目级,由 `project:jnpf` 简写解析)
---
## 2. 7 个子命令
### 2.1 `search` — 全文搜索
```bash
dacli codegraph search <query> [-k kind] [-l lang] [-n limit]
```
- `query`(必填):FTS5 搜索词,支持 `prefix*` 前缀匹配
- `-k/--kind`:过滤节点类型,可选 `class` / `method` / `interface` / `field` / `component` / `route`
- `-l/--lang`:过滤语言,可选 `java` / `python` / `vue` / `typescript` / `javascript`
- `-n/--limit`:返回条数(默认 20)
输出字段:`id, kind, name, qualified_name, file_path, start_line, end_line, signature, docstring, visibility, is_static, is_abstract, highlight`
```bash
# 示例:搜 JNPF 用户管理 Controller
dacli codegraph search "UserController" -k class
# 限定 java
dacli codegraph search "UserController" -k class -l java
# 前缀匹配(所有 User 开头的方法)
dacli codegraph search "User*" -k method -l java -n 50
```
### 2.2 `calls` — 单层调用链
```bash
dacli codegraph calls <qualified_name> [-d in|out] [-n limit]
```
- `qualified_name`(必填):节点完整名,如 `jnpf.permission.controller::UserController`
- `-d/--direction`:
- `out`(默认):谁调用了它(incoming callers)
- `in`:它调用了谁(outgoing callees)
> **注意**:方向命名是**从目标节点视角**看 — `out` = 反向追溯 callers,`in` = 正向展开 callees。
```bash
# 找谁调用了 UserController(反向)
dacli codegraph calls "jnpf.permission.controller::UserController" -d out
# UserController 内部调用了哪些方法(正向)
dacli codegraph calls "jnpf.permission.controller::UserController" -d in -n 50
```
### 2.3 `trace` — 多跳 BFS 路径追踪(最强能力)
```bash
dacli codegraph trace <from> <to> [-d depth] [-e edge-types]
```
- `<from>` `<to>`(必填):起始 / 目标 qualified_name
- `-d/--depth`:最大搜索深度(默认 8)
- `-e/--edge-types`:遍历的边类型,逗号分隔(默认 `calls,references,imports,instantiates`)
```bash
# 跨模块追踪:Controller → Service → ServiceImpl
dacli codegraph trace \
"jnpf.permission.controller::UserController::getList" \
"jnpf.permission.service.impl::UserServiceImpl::getList"
# 限制深度为 3
dacli codegraph trace "X::Controller::a" "Y::Service::b" -d 3
# 只走调用边
dacli codegraph trace "X" "Y" -e calls
```
### 2.4 `impact` — 修改影响分析
```bash
dacli codegraph impact <qualified_name> [-n limit] [-g]
```
- 找出**所有引用 / 调用 / 导入 / 继承 / 实现**该符号的节点
- `-g/--group`:按文件分组(默认不分组,展开所有引用)
**改动前必跑** — 一键列出所有受影响位置。
```bash
# 我要改 UserService,看看谁引用了它
dacli codegraph impact "jnpf.permission.service::UserService"
# 按文件分组(看改动涉及多少文件)
dacli codegraph impact "jnpf.permission.service::UserService" --group
```
### 2.5 `contains` — 类/文件成员
```bash
dacli codegraph contains <qname> [-k kind]
```
- 列出类或文件的成员(方法 / 字段 / 内部类 / import)
- `-k/--kind`:过滤成员类型,可选 `method` / `field` / `class` / `import`
```bash
# 看 UserController 有哪些方法
dacli codegraph contains "jnpf.permission.controller::UserController" -k method
# 看 UserService 的字段
dacli codegraph contains "jnpf.permission.service::UserService" -k field
```
### 2.6 `implements` — 接口实现类
```bash
dacli codegraph implements <interface_qname> [-n limit]
```
```bash
# 找所有实现 UserService 接口的类
dacli codegraph implements "jnpf.permission.service::UserService"
```
### 2.7 `route` — API 路径反查 Controller
```bash
dacli codegraph route <keyword> [-n limit]
```
- 通过 API 路径关键词反查是哪个 Controller 方法处理的
```bash
# /user/list 接口是哪个 Controller?
dacli codegraph route "/user/list"
# 按方法名反查
dacli codegraph route "getList"
```
---
## 3. DB 路径配置(`dacli.conf`)
`dacli.conf` 中的 `codegraph.dbPaths` 控制查找路径,多路径用逗号分隔,**按顺序查找第一个存在的文件**:
```properties
# 内置简写:project:<名> → $ccWorkDir/<名>/.codegraph/codegraph.db
codegraph.dbPaths=/home/ubuntu/.dacli/codegraph.db,project:jnpf
```
| 格式 | 示例 | 解析结果 |
|------|------|---------|
| 绝对路径 | `/home/ubuntu/.dacli/codegraph.db` | 直接使用 |
| `project:<名>` | `project:jnpf` | `$ccWorkDir/jnpf/.codegraph/codegraph.db` |
**查找顺序**(从前往后,找第一个存在的):
1. `dacli -Dcodegraph.db=<path>` 命令行临时覆盖
2. `./config/dacli.conf`(当前目录)
3. `$ccWorkDir/config/dacli.conf`(项目级)
4. jar 内置默认 `dacli.conf`(包含 `project:jnpf`)
```bash
# 临时指向其他 db
dacli -Dcodegraph.db=/tmp/test.db codegraph search "..."
```
---
## 4. qualified_name 命名规范
完整节点标识符格式:`<package>::<ClassName>` 或 `<package>::<ClassName>::<methodName>`
```bash
# 类级别
jnpf.permission.controller::UserController
# 方法级别
jnpf.permission.controller::UserController::getList
jnpf.permission.service.impl::UserServiceImpl::save
```
**如何获取准确的 qualified_name**:
1. 先 `dacli codegraph search <关键词> -k class` 找到类,输出里 `qualified_name` 字段就是
2. 再用 `dacli codegraph contains <qname> -k method` 拿方法级别 qname
3. 也可以从 JNPF 源码的 `package + class` 直接拼出(Java 包用 `.`,codegraph 用 `.`)
---
## 5. AI 典型查询范式
### 范式 1:定位某 Controller 的所有方法
```bash
dacli codegraph search "CommentController" -k class
# → 拿到 qname: jnpf.flowable.controller::CommentController
dacli codegraph contains "jnpf.flowable.controller::CommentController" -k method
# → 列出所有方法及 qname
```
### 范式 2:跨模块调用链(最强)
```bash
dacli codegraph trace \
"jnpf.flowable.controller::CommentController::list" \
"jnpf.flowable.service.impl::CommentServiceImpl::list"
# 输出: Controller --calls--> Service --calls--> ServiceImpl 全链路 + 文件名+行号
```
### 范式 3:改动前影响评估
```bash
dacli codegraph impact "jnpf.permission.service::UserService" --group
# 输出:按文件分组的所有引用者 → 改动前风险一览
```
### 范式 4:前端找后端实现
```bash
dacli codegraph search "setPosition" -l vue -k component
# → 找到前端组件
dacli codegraph route "setPosition"
# → 找到后端 Controller 方法
```
### 范式 5:架构理解
```bash
dacli codegraph search "jnpf" -k interface -n 50
# → 所有接口定义(理解 JNPF 平台抽象层)
dacli codegraph search "jnpf" -k class -n 50
# → 核心类清单
```
---
## 6. 与 `dacli apis` 联动
> 联动仅适用于 JNPF 平台代码的查询场景。
```
AI 提问:"JNPF 平台的流程评论怎么实现的?"
↓
① dacli apis info "/api/flowable/comment/list"
→ 拿到 API 定义 + 中文字段(response/requestBody)
② dacli codegraph search "CommentController" -k class
→ 定位 Controller 文件:行号
③ dacli codegraph trace \
"jnpf.flowable.controller::CommentController::list" \
"jnpf.flowable.service.impl::CommentServiceImpl::list"
→ Controller --calls--> Service --calls--> ServiceImpl 全链路
④ 返回完整调用链 + 文件名 + 行号 + AI 即可读懂 JNPF 平台实现
```
**快捷模式(改动前评估)**:
```bash
dacli codegraph impact "jnpf.flowable.service::CommentService" --group
→ 一键列出所有引用此 Service 的文件 → 改动风险评估
```
---
## 7. 已知问题与局限
1. **静态分析 ≠ 运行时行为**:codegraph 不包含 Spring AOP / 动态代理 / 反射调用。Spring 注解生成的 Bean(如 `@Autowired` 注入)能看到声明,但运行时实际行为需结合其他手段验证。
2. **生成的代码可能缺失**:MyBatis Generator / Lombok 生成的代码、Vue 编译产物等通常不在分析范围内。
3. **db 文件较大(~400MB)**:首次 search 会有 100ms 量级 FTS 索引加载延迟;后续查询毫秒级。
4. **db 需要单独构建**:codegraph.db 不是自动生成的,需通过 codegraph 工具对 JNPF 源码做静态分析。生成周期长,db 一般 1-2 周更新一次。
5. **qualified_name 大小写敏感**:JNPF 后端类名严格匹配;前端组件名通常是 PascalCase,搜索时注意。
---
## 8. 相关技能
- **`.claude/skills/dacli-architecture/SKILL.md`** — dacli 整体架构(含 codegraph 在阶段 10 的引入)
- **`.claude/skills/dacli-doc-cache/SKILL.md`** — `dacli doc` 文档缓存(与 codegraph 配合:先查文档理解设计,再查 codegraph 看实现)
- **`.claude/skills/api-test/SKILL.md`** — API 集成测试(与 `dacli apis` 配合:apis 找 API 定义 → curl 验证实现)
-178
View File
@@ -1,178 +0,0 @@
---
name: dacli-doc-cache
description: 通过 dacli doc 缓存读取 HTML 文档(plan.html/design.html/testcase.html),避免直接 Read 整个 HTML 导致的 token 暴增。触发词:恢复上下文、读取文档、dacli doc、HTML 文档
---
# dacli doc 缓存使用指南
## 适用场景
会话中断/上下文压缩后,需要快速恢复对 `docs/{app_code}/` 下 HTML 文档(plan.html / design.html / testcase.html / debug.html / summary.html)的阅读理解。**核心目标:把每个 HTML 文档读取的 token 用量从 ~25K 降到 ~5K(-80%)**。
直接用 `Read` 工具读 HTML 会被 `<style>`、`<script>`、导航栏等噪声污染。`dacli doc` 提取纯文本、按 section/行号切片、Redis 缓存命中后 <50ms 返回。
---
## 5 个子命令
```
dacli doc list [--dir=<path>] | [--file=<path>] # 列索引(JSON)
dacli doc get --file=<path> --section=<id> # 按 section 取纯文本 ⭐
dacli doc get --file=<path> --from=<N> --lines=<N> # 按行号取
dacli doc scan [--dir=<path>] # 扫描建索引(自动触发)
dacli doc refresh [--dir=<path>] | [--file=<path>] # 强制刷新
dacli doc clear [--dir=<path>] | [--file=<path>] # 清除缓存(含所有 section)
```
---
## 典型工作流:上下文恢复
### 步骤 1:快速了解文档结构(1 个命令搞定)
```bash
dacli doc list --dir=docs/tds
```
输出 JSON 索引:文件、section ID、section 标题、**行数(与 getSection 实际返回一致)**、mtime。
### 步骤 2:按需读取 plan.html(核心)
```bash
# 完整 plan.html 纯文本
dacli doc get --file=docs/tds/plan.html
# 只取 plan.html 第 10-60 行
dacli doc get --file=docs/tds/plan.html --from=10 --lines=50
```
### 步骤 3:按需读其他文档的特定 section
```bash
# design.html 的架构设计节
dacli doc get --file=docs/tds/design.html --section=arch
# testcase.html 的 TC1(逻辑空间)节
dacli doc get --file=docs/tds/testcase.html --section=tc1
# debug.html 的"问题记录"节
dacli doc get --file=docs/tds/debug.html --section=h2_0
```
### 步骤 4:文档更新后刷新缓存
```bash
# 编辑了 plan.html/design.html 后
dacli doc refresh --dir=docs/tds
```
---
## section ID 命名规则
| HTML 结构 | sectionId 来源 | 示例 |
|----------|----------------|------|
| `<div id="xxx" class="module">` | 直接用 `id` | `overview`、`arch`、`tc1` |
| `<section id="xxx">` | 直接用 `id` | `business`、`flow` |
| `<h2>`(无 div/section 容器) | 自动生成 `h2_0`、`h2_1`... | `h2_0`(第 1 个 h2) |
用 `dacli doc list` 输出的 `sections[].id` 就是正确的 sectionId。
---
## 缓存机制
| Key | 内容 | TTL |
|-----|------|-----|
| `dacli:doc:index:{dirHash}` | 目录下文件索引 JSON | 3600s |
| `dacli:doc:section:{fileHash}:{sectionId}` | 单 section 纯文本(保留 Mermaid) | 3600s |
| `dacli:doc:mtime:{fileHash}` | 文件 mtime(epoch millis) | 3600s |
| `dacli:doc:raw:{fileHash}` | 整个文件纯文本行(保留 Mermaid) | 3600s |
- **路径哈希**:绝对路径的 SHA-1 前 16 位
- **mtime 感知**:每次读取检查源文件 mtime,不一致自动重新提取
- **降级**:Redis 不可用时直接读源 HTML 并解析(功能不中断)
- **路径解析**:`--file` 支持相对路径(优先 $ccWorkDir)和绝对路径
- **缓存清除**:`dacli doc clear --file=...` 用 `KEYS` pattern 批量删除该文件的所有 section 缓存
---
## 高级选项
**Mermaid 处理**(**默认保留**):
- `--strip-mermaid=false`(**默认**)→ 保留 Mermaid 块(架构图、流程图、时序图等),对 AI 理解系统结构至关重要
- `--strip-mermaid=true` → 显式剥离 Mermaid(**不推荐**,仅在 token 极紧张时使用)
### 已知 trade-off
`parseHtml` 始终保留 Mermaid(缓存原文本),剥离延迟到输出时。**默认情况**下 `sections[].lines` 与 `getSection` 实际返回行数完全一致。
**但**:如果用户显式用 `--strip-mermaid=true`:
- `getSection` 返回的行数 < `sections[].lines`(因为 Mermaid 已被剥离)
- `--from/--lines` 模式同理
这是预期行为,需要跨模式统一行号时请用默认(`--strip-mermaid=false`),或 `dacli doc refresh` 后重新读 `sections[].lines`。
---
## 行号一致性保证
| 路径 | 行号基准 |
|------|---------|
| `sections[].lines`(list 输出) | 含 Mermaid 的纯文本行数 |
| `getSection` 默认返回 | 含 Mermaid(与 sections[].lines 一致)|
| `getSection --strip-mermaid=true` | 剥离 Mermaid(少于 sections[].lines)|
| `getRawLines --from/--lines` | `--from=1` 对应文件首行;`totalLines` = 含 Mermaid 行数 |
| `getRawLines --from/--lines --strip-mermaid=true` | 剥离 Mermaid(行号偏移)|
**结论**:`--from/--lines` 模式的行号与 `sections[].lines`、默认 `getSection` 完全一致。切换 `--strip-mermaid=true` 时需要自行调整行号。
---
## 高级示例
```bash
# 保留 Mermaid 代码块(**默认**,对 AI 理解架构/流程有帮助)
dacli doc get --file=docs/tds/design.html --section=arch
# 显式剥离 Mermaid(不推荐 - 损失结构信息)
dacli doc get --file=docs/tds/design.html --section=arch --strip-mermaid=true
# 清除单个文件缓存(清掉所有 section + mtime + raw 缓存)
dacli doc clear --file=docs/tds/plan.html
# 查看某个文件的 section 索引
dacli doc list --file=docs/tds/design.html
```
---
## 与 ssw-h5dev-flow 集成
在 `ssw-h5dev-flow` 流程中:
| 阶段 | 使用 `dacli doc` 的方式 |
|------|---------------------|
| 阶段 2:设计 | 生成 design.html/testcase.html 后 `dacli doc scan --dir=docs/{app_code}` 建索引 |
| 阶段 4:执行 | 用 `dacli doc get --file=plan.html` 读计划,`dacli doc refresh` 刷新 |
| 阶段 5:测试 | 用 `dacli doc get --file=testcase.html --section=tc1` 定位待测项 |
| 上下文恢复 | `dacli doc list` → `dacli doc get` 按需读 |
---
## 故障排查
| 症状 | 原因 | 解决 |
|------|------|------|
| `section 不存在: xxx` | sectionId 写错 | 先 `dacli doc list` 看正确的 id |
| `目录不存在: xxx` | 路径解析失败 | 用绝对路径,或确认 $ccWorkDir 环境变量 |
| 返回内容过期 | mtime 检查未触发 | `dacli doc refresh --file=...` 强制刷新 |
| `doc clear` 后还看到旧内容 | 旧版本 bug:section 缓存未清 | 升级到当前版本(用 `deleteByPattern`) |
| Redis 不可用 | 服务未启动 | 降级为直读文件,功能仍可用 |
---
## Token 用量对比
| 读取方式 | 5 个 HTML 文档 token | 延迟 |
|----------|---------------------|------|
| 直接 `Read` 工具 | ~25K | ~3s |
| `dacli doc get`(按需,默认保留 Mermaid)| ~5K(-80%) | ~50ms(缓存命中) |
| `dacli doc get` + `--strip-mermaid=true` | ~3K(-88%) | ~50ms(缓存命中) |
**结论**:所有 HTML 文档读取场景都应优先用 `dacli doc`,仅在纯文本不够直观时再用 `Read` 工具打开原 HTML。**默认保留 Mermaid** 是因为它对 AI 理解架构/流程/时序有结构性帮助。
File diff suppressed because it is too large. Load diff
@@ -1,85 +0,0 @@
# C.5.6 详细参考:OLD → NEW 约定自动迁移工具
> 主 SKILL.md 中 C.5.6 段只列核心规则;本文档是详细参考(工具细节、实测案例、已知限制)。
**位置**:`.claude/skills/design-jnpf-execute/scripts/polish-convention.py`(P17 + P28 + v10.3 双模式扩展,396 行 Python)
## 三种模式
### 1. OLD 约定迁移(默认,dry-run)
```bash
# 单文件 dry-run(输出 *.new.html)
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/workSystem/design-jnpf.html
# 单文件 in-place(直接覆盖原文件)
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/workSystem/design-jnpf.html --in-place
# 目录批量 dry-run
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/ --glob='design-jnpf*.html'
# 目录批量 in-place(CI 自动修复用)
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/ --in-place --glob='design-jnpf*.html'
```
### 2. v10.3 columnData 完整性体检(--validate)
```bash
# 单文件:扫 design-jnpf.html 的 #form-* 锚点 → 查 formId → 调 dacli form validate
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/tds/design-jnpf.html --validate
# 目录批量
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/ --validate --glob='design-jnpf*.html'
```
### 3. v10.3 C.5.9/C.5.10 引用卡点(--require-c59)
```bash
# 单文件
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/tds/design-jnpf.html --require-c59
# 目录批量(CI 卡点)
python3 .claude/skills/design-jnpf-execute/scripts/polish-convention.py docs/ --require-c59 --glob='design-jnpf*.html'
```
## 检测的 4 类 OLD 约定
| 类型 | 匹配正则 | 修复动作 |
|------|---------|---------|
| `--fieldsJson` | `r'--fieldsJson'` | 改 `--fields` |
| `"vModel":` | `r'"vModel":\s*"f_\w+"'` | 改 `field` + 加 `fieldName`(从 4.2 表查中文名)|
| `--columnDataJson` | `r'\s*--columnDataJson='\[.*?\]'\s*\\\n'` | 删整段 |
| `<th>vModel</th>` | `r'<th>vModel</th>'` | 改 `<th>field</th>` |
## 退出码(CI 卡点用)
| 码 | 含义 |
|----|------|
| 0 | 全部 OK(NEW 约定 + columnData PASS + 引用 C.5.9)|
| 1 | dry-run 模式有 OLD 残留 / columnData FAIL / 缺 C.5.9 引用 |
| 2 | 输入路径不存在 |
| 3 | IO 错误 |
| 4 | 部分文件迁移失败 |
## 已知限制
- 字段 `fieldName` 自动从 4.2 表取,但**不是所有 design 都有 4.2 表**(如 tds design.html 阶段 0 拆解前的综合设计)→ fallback 用 field 同名(需手动改)
- `--columnDataJson` 段只删 `'[...]' `\`` 多行格式,其他格式(如单行或带变量)会漏
- `--validate` 模式依赖 `dacli` 在 PATH(v10.2 起内化)
- `--require-c59` 用 5 种 pattern 启发式判断(C.5.9 / C.5.10 / 列表页空白 / columnData 缺 / validate),可能误报
## 实测案例(v9.2 / v10.3)
| 文件 | 修复前 | 修复后 |
|------|------|------|
| `docs/workSystem/design-jnpf.html` | 9 处 OLD(1 fieldsJson + 6 vModel + 1 columnDataJson + 1 表头)| 0 处 |
| `docs/developSystem/design-jnpf.html` | 1 处(vModel 表头)| 0 处 |
| `docs/tds/design-jnpf.html` | 0 处(v9 整改已 NEW)| 0 处 |
| `docs/tds/design-jnpf-pilot.html` | 0 处(v9 整改已 NEW)| 0 处 |
| **tds 7 forms validate (v10.3)** | — | **7/7 PASS** |
## 关联工具
- `dacli form validate <id>` — 单 form 完整性校验(退出码 0/1)
- `dacli form fix-columndata <id>` — 老 form 缺 `__config__` 修复
- `dacli form validate <id> --fix` — 校验+自动修
@@ -1,85 +0,0 @@
# C.5.7 详细参考:JNPF POST bug workaround 通用模式
> 主 SKILL.md 中 C.5.7 段只列核心模式;本文档是详细参考(4 类 workaround 实战代码 + 触发条件 + 根治方向)。
## 问题
JNPF 全局 POST 路径可能 NPE,返 `{"code":400,"msg":"System abnormality"}`(msg code `AD102`)。
**实测涉及 endpoint**:
- `POST /api/visualdev/Base`(`dacli form create` / `dacli form import`)
- `POST /api/visualdev/Base/{id}/Actions/Release`(`dacli form release`)
- `DELETE /api/system/Menu/{id}`(`dacli menu delete` 返 "System abnormality" P5-A 已知)
- 任何调用 `infoByEnCode.getId()` 但 appCode 在 `base_system` 表缺失的 POST
**PUT 路径不受影响**(实测):
- `PUT /api/visualdev/Base/{id}`(`dacli form fix`)
- `PUT /api/system/Menu/{id}/Actions/State {enabled: 0}`(`dacli menu` 禁用)
- `PUT /api/system/Menu/{id}`(`dacli menu` 改 type/propertyJson 绕过 `--formId` 限制)
## 通用 workaround 模式
### 1. 创建 form:dacli form fix 替代 dacli form create
```bash
# 选任意 state=0/1/2 form 当 target(test artifacts 优先)
TARGET_ID=832344878624020549 # 已知可用
dacli form fix \
--target=$TARGET_ID \
--enCode="<新 enCode>" \
--name="<新中文名>" \
--fieldsJson='[{"field":"f_xxx","label":"中文","jnpfKey":"input","required":true}]' \
--release
```
**注意**:
- target form 的 **data table 必须有 `f_id` primary key**(否则 Step 8 PUT 返 "Table has no primary key!")
- 推荐 target:state=2 的 test artifacts(已发布过,data table 完整)
- 避免 target:state=0 的极简 form(如 `table_name_test_001` 只有 1 field)
### 2. 菜单 formId 绑定:curl PUT 替代 dacli menu update
```bash
TOKEN=$(cat .dacli-token/token.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('token',''))")
curl -s -X PUT \
-H "Authorization: $TOKEN" \
-H "App-Code: $APP_CODE" \
-H "Content-Type: application/json" \
"http://127.0.0.1:30000/api/system/Menu/$MENU_ID" \
-d "{\"enCode\":\"$MENU_EN\",\"type\":3,\"propertyJson\":\"{\\\"moduleId\\\":\\\"$FORM_ID\\\",\\\"iconBackgroundColor\\\":\\\"\\\",\\\"isTree\\\":0,\\\"webType\\\":2}\"}"
```
**优势**:
- 不依赖 `dacli menu update --formId`(dacli 命令集盲点)
- 可同时改 type=7→3、propertyJson.moduleId 等多个字段
- idempotent:re-run 跳过已绑 menu
### 3. 物理表清理:dacli dm drop 替代 SQL DROP
```bash
dacli dm drop --table=tds_space
# 等价于:DROP TABLE tds_space
```
**优势**:
- 不需要 DB 访问权限
- 释放 P27 release 时的 "table name conflict" 阻塞
### 4. 实战记录(v9.3 tds 7 forms)
v10.1 之前的 workaround 演示脚本(已合并入 form fix 实战):
- `auto-gen-tds-workaround.sh` — 7 form fix 拓扑并行
- `update-tds-menu-formids.sh` — 7 menu PUT 绑 formId
- **结果**:6/7 forms state=1 + 1/7 state=0(data table 阻塞,**form 字段完整**) + 7/7 menus formId ✅
## 根治方向(v9.4+ → v10.1 已部分根治)
- **DB 修复**:`INSERT INTO base_system (f_en_code, f_full_name, f_state) VALUES ('<appCode>', '<中文>', 1)` 然后重启 JNPF
- **JNPF 源码修复**:`VisualdevController.create:519` 加 `if (infoByEnCode == null) return error;` NPE guard
- **dacli 改进**:加 `--use-put` 全局开关,自动用 PUT 路径替代 POST
**v10.1 实战进展**(C.5.8):`dacli initapp -- --appCode=X --force-rebuild` + 重启 JNPF 修复**全局 P27 NPE**(两层根因:infoByEnCode NPE + dataSourceMod NPE)。详见 C.5.8。
**v10.3 边界收敛**:tds_space (userSelect 必填) POST 仍 System abnormality,但其他 4 控件(input/select/relationForm/datePicker/radio/textarea)CRUD 全稳定。**P27 已非全局 bug,而是 userSelect 控件特定路径**。
@@ -1,241 +0,0 @@
# 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 目标**。
@@ -1,268 +0,0 @@
# 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 校验结果 / 脚本路径
```
@@ -1,245 +0,0 @@
#!/usr/bin/env python3
"""
create_form.py - 单表功能表单创建脚本
用法:
1. 修改下方 CONFIG 段(name, enCode, table, fields)
2. 预建物理表:dacli dm create --table=<table> --tableName=<中文名> --dbLinkId=<id> --fields='[...]'
3. 运行本脚本:python3 create_form.py
前置:dacli login --account=admin --password=<密码> --appCode=tdd
原理:JNPF Create API + 完整 tables JSON + formData + columnData
参考:developSystem 主子表测试A (833737463619919749) 作为模板基线
"""
import json, subprocess, sys, urllib.request, urllib.error, uuid
from pathlib import Path
# ========== CONFIG ==========
TEMPLATE_FORM_ID = '833737463619919749' # developSystem 主子表测试A(基线)
TARGET_APP_CODE = 'tdd' # 目标应用
NAME = '设备登记模板' # 表单名称
ENCODE = 'equipment_template' # 表单编码
TABLE = 'equipment_template_main' # 物理表名(必须已预建)
DESCRIPTION = '由create_form.py生成'
# 业务字段:每个含 {field, fieldName, jnpfKey, dataType, dataLength, required?, options?}
FIELDS = [
{'field': 'f_name', 'fieldName': '名称', 'jnpfKey': 'input', 'dataType': 'varchar', 'dataLength': '100', 'required': True},
{'field': 'f_status', 'fieldName': '状态', 'jnpfKey': 'select', 'dataType': 'varchar', 'dataLength': '50', 'required': False,
'options': [{'fullName': '启用', 'id': '1'}, {'fullName': '禁用', 'id': '0'}]},
{'field': 'f_date', 'fieldName': '日期', 'jnpfKey': 'datePicker', 'dataType': 'datetime', 'dataLength': '0', 'required': False},
{'field': 'f_remark', 'fieldName': '备注', 'jnpfKey': 'textarea', 'dataType': 'varchar', 'dataLength': '500', 'required': False},
]
# ========== HELPERS ==========
def load_token():
"""读 dacli token + dbLinkId(从 $ccWorkDir/.dacli-token/token.json)"""
token_path = Path('/home/ubuntu/ccWorkDir/.dacli-token/token.json')
if not token_path.exists():
sys.exit('❌ token.json 不存在,请先 dacli login')
with open(token_path) as f:
tk = json.load(f)
if TARGET_APP_CODE not in (tk.get('appCode'), None) and tk.get('appCode') != TARGET_APP_CODE:
print(f'⚠️ 当前登录 appCode={tk.get("appCode")},期望 {TARGET_APP_CODE}')
return tk['token'], tk['dbLinkId']
def fetch_template(template_id, src_app='developSystem'):
"""从 developSystem 拉模板"""
print(f'→ 切换 {src_app} 拉取模板 {template_id}')
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={src_app}'],
capture_output=True, text=True)
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'form', 'info', template_id],
capture_output=True, text=True)
return json.loads(proc.stdout)['data']
def login_target(app_code):
"""切回目标 app"""
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={app_code}'],
capture_output=True, text=True)
def build_form_data(template_form_data, fields, table):
"""从模板 formData 生成新 formData(替换 fields)"""
fd = dict(template_form_data)
fd['tableName'] = table
new_fields = []
for i, f in enumerate(fields):
cfg = {
'formId': 101 + i,
'visibility': ['pc', 'app'],
'jnpfKey': f['jnpfKey'],
'noShow': False, 'tipLabel': '', 'dragDisabled': False, 'className': [],
'label': f['fieldName'],
'showLabel': True, 'required': f.get('required', False),
'tableName': table,
'renderKey': 1780900000000 + i,
'layout': 'colFormItem',
'tagIcon': f'icon-ym icon-ym-generator-{f["jnpfKey"].lower()}',
'tag': 'JnpfInput' if f['jnpfKey'] in ('input', 'textarea') else f'Jnpf{f["jnpfKey"][0].upper()}{f["jnpfKey"][1:]}',
'regList': [], 'span': 24, 'dictionaryType': '',
'trigger': 'blur' if f['jnpfKey'] == 'input' else '',
}
new_fields.append({
'__config__': cfg,
'__vModel__': f['field'],
'field': f['field'],
'clearable': True,
'style': {'width': '100%'},
'placeholder': f'请输入{f["fieldName"]}' if f['jnpfKey'] in ('input', 'textarea') else f'请选择{f["fieldName"]}',
'id': f['field'],
'fullName': f['fieldName'],
'fullNameI18nCode': ['']
})
fd['fields'] = new_fields
fd['idGlobal'] = 100 + len(fields)
return fd
def build_tables(template_tables, fields, table, name):
"""从模板 tables 生成新 tables(替换主表字段)"""
new_tables = []
for t in template_tables:
if t.get('typeId') != '1':
continue
nt = dict(t)
nt['table'] = table
nt['tableName'] = name
nt['comment'] = '主表'
# 保留系统字段,替换业务字段
new_t_fields = []
for f in t.get('fields', []):
ff = dict(f)
if f.get('field') == 'f_name':
# 用第一个 input 字段替换 f_name
first_input = next((x for x in fields if x['jnpfKey'] == 'input'), fields[0])
ff['field'] = first_input['field']
ff['fieldName'] = first_input['fieldName']
ff['dataLength'] = first_input['dataLength']
new_t_fields.append(ff)
else:
new_t_fields.append(ff)
# 在 f_id 之前插入其他业务字段
business = [f for f in fields if f['field'] != next((x for x in fields if x['jnpfKey'] == 'input'), fields[0])['field']]
for i, biz in enumerate(business):
new_t_fields.insert(1 + i, {
'allowNull': 0 if biz.get('required') else 1,
'autoIncrement': 0,
'dataLength': biz['dataLength'],
'dataType': biz['dataType'],
'field': biz['field'],
'fieldName': biz['fieldName'],
'primaryKey': 0, 'identity': 0
})
nt['fields'] = new_t_fields
new_tables.append(nt)
return new_tables
def build_column_data(template_column_data, fields, name):
"""从模板 columnData 生成新 columnData"""
cd = dict(template_column_data)
cd['columnOptions'] = [{'value': f['field'], 'label': f['fieldName'], 'width': 120, 'sort': i}
for i, f in enumerate(fields)]
cd['searchList'] = [{'field': fields[0]['field'], 'label': fields[0]['fieldName'], 'jnpfKey': 'input',
'prop': fields[0]['field'], 'sourceType': 2, 'searchType': 2, 'searchMultiple': False,
'isKeyword': False, 'id': fields[0]['field'], 'fullName': fields[0]['fieldName'],
'fullNameI18nCode': [''], 'search': 1, 'searchPop': 0}]
cd['formData'] = {
'formRef': 'formRef', 'formModel': 'query', 'size': 'default',
'labelPosition': 'right', 'labelWidth': 100, 'gutter': 15, 'disabled': False,
'span': 6, 'formBtns': True,
'fields': [{'__config__': {'label': fields[0]['fieldName'], 'jnpfKey': 'input',
'tag': 'JnpfInput', 'formId': 201, 'visibility': ['pc', 'app']},
'__vModel__': fields[0]['field']}],
'idGlobal': 201
}
cd['columnList'] = [{'label': f['fieldName'], 'prop': f['field'], 'jnpfKey': 'input',
'fixed': 'none', 'headerAlign': 'left', 'align': 'left', 'sortable': False,
'width': None, 'id': f['field'], 'fullName': f['fieldName'], 'fullNameI18nCode': ['']}
for f in fields]
cd['defaultColumnList'] = cd['columnList']
return cd
def call_api(url, payload, auth_header, method='POST'):
req = urllib.request.Request(url,
data=json.dumps(payload, ensure_ascii=False).encode('utf-8'),
headers={'Authorization': auth_header, 'App-Code': TARGET_APP_CODE, 'Content-Type': 'application/json'},
method=method)
try:
resp = urllib.request.urlopen(req, timeout=60)
return json.loads(resp.read().decode('utf-8'))
except urllib.error.HTTPError as e:
return {'code': e.code, 'msg': e.read().decode('utf-8')[:500]}
# ========== MAIN ==========
def main():
print(f'=== 单表表单创建:{NAME} ({ENCODE}) ===')
auth_header, db_link_id = load_token()
# 1. 拉模板
template = fetch_template(TEMPLATE_FORM_ID)
template_fd = json.loads(template['formData'])
template_tables = json.loads(template['tables'])
template_cd = json.loads(template['columnData'])
# 2. 构建
new_fd = build_form_data(template_fd, FIELDS, TABLE)
new_tables = build_tables(template_tables, FIELDS, TABLE, NAME)
new_cd = build_column_data(template_cd, FIELDS, NAME)
payload = {
'fullName': NAME, 'enCode': ENCODE, 'type': 1, 'description': DESCRIPTION,
'webType': 2, 'state': 0, 'sortCode': 0,
'category': uuid.uuid4().hex.replace('-', ''),
'dbLinkId': db_link_id,
'tables': json.dumps(new_tables, ensure_ascii=False),
'formData': json.dumps(new_fd, ensure_ascii=False),
'columnData': json.dumps(new_cd, ensure_ascii=False),
'appColumnData': json.dumps(new_cd, ensure_ascii=False),
'enableFlow': 0
}
# 3. 切回目标 app,调 API
login_target(TARGET_APP_CODE)
auth_header, _ = load_token()
print(f'→ POST /api/visualdev/Base (dbLinkId={db_link_id})')
result = call_api('http://127.0.0.1:30000/api/visualdev/Base', payload, auth_header)
print(f' Create: code={result.get("code")} msg={result.get("msg")}')
if result.get('code') != 200:
print('❌ 创建失败,请检查:1) 物理表是否预建 2) dbLinkId 是否正确 3) category 是否为 UUID')
return 1
form_id = result['data']['id']
print(f' Form ID: {form_id}')
# 4. Release
print(f'→ POST /api/visualdev/Base/{form_id}/Actions/Release')
result2 = call_api(f'http://127.0.0.1:30000/api/visualdev/Base/{form_id}/Actions/Release', {}, auth_header)
print(f' Release: code={result2.get("code")} msg={result2.get("msg")}')
if result2.get('code') == 200:
print(f'\n✅ Form {form_id} CREATED+RELEASED!')
# 5. 创建菜单
print(f'→ dacli menu create --name="{NAME}" --formId={form_id}')
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'menu', 'create', f'--name={NAME}', f'--formId={form_id}'],
capture_output=True, text=True)
print(proc.stdout[-200:])
return 0
if __name__ == '__main__':
sys.exit(main())
@@ -1,309 +0,0 @@
#!/usr/bin/env python3
"""
create_subtable_form.py - 主子表表单创建脚本
前置:
1. 已预建主表 + 子表(含 f_id PK + f_tenant_id PK)
2. dacli login --account=admin --password=123456 --appCode=tdd
用法:
1. 修改下方 CONFIG
2. python3 create_subtable_form.py
"""
import json, subprocess, sys, urllib.request, urllib.error, uuid
from pathlib import Path
# ========== CONFIG ==========
TEMPLATE_FORM_ID = '833737463619919749' # developSystem 主子表测试A(基线)
TARGET_APP_CODE = 'tdd'
NAME = '订单模板'
ENCODE = 'order_template'
TABLE = 'order_template_main' # 主表(必须已预建)
SUBTABLE = 'ct_order_template_1' # 子表(必须已预建,含 f_foreignId)
# 主表字段
MAIN_FIELDS = [
{'field': 'f_order_no', 'fieldName': '订单编号', 'jnpfKey': 'input', 'dataType': 'varchar', 'dataLength': '50', 'required': True},
{'field': 'f_customer', 'fieldName': '客户名称', 'jnpfKey': 'input', 'dataType': 'varchar', 'dataLength': '100', 'required': True},
]
# 子表字段
SUB_FIELDS = [
{'field': 'f_goods', 'fieldName': '商品', 'jnpfKey': 'input', 'dataType': 'varchar', 'dataLength': '100'},
{'field': 'f_qty', 'fieldName': '数量', 'jnpfKey': 'inputNumber', 'dataType': 'int', 'dataLength': '0'},
]
# 子表容器 vModel(决定 dataMap key)
SUB_VMODEL = 'orderItems'
# 子表容器 formId
SUB_FORM_ID = 200
# ========== HELPERS(复用 create_form.py)==========
def load_token():
token_path = Path('/home/ubuntu/ccWorkDir/.dacli-token/token.json')
if not token_path.exists():
sys.exit('❌ token.json 不存在,请先 dacli login')
with open(token_path) as f:
tk = json.load(f)
return tk['token'], tk['dbLinkId']
def fetch_template(template_id, src_app='developSystem'):
print(f'→ 切换 {src_app} 拉取模板 {template_id}')
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={src_app}'],
capture_output=True, text=True)
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'form', 'info', template_id], capture_output=True, text=True)
return json.loads(proc.stdout)['data']
def login_target(app_code):
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={app_code}'],
capture_output=True, text=True)
def make_field(f, table, idx):
return {
'__config__': {
'formId': 101 + idx, 'visibility': ['pc', 'app'], 'jnpfKey': f['jnpfKey'],
'noShow': False, 'tipLabel': '', 'dragDisabled': False, 'className': [],
'label': f['fieldName'], 'showLabel': True, 'required': f.get('required', False),
'tableName': table, 'renderKey': 1780900000000 + idx, 'layout': 'colFormItem',
'tagIcon': f'icon-ym icon-ym-generator-{f["jnpfKey"].lower()}',
'tag': 'JnpfInput' if f['jnpfKey'] in ('input', 'textarea') else f'Jnpf{f["jnpfKey"][0].upper()}{f["jnpfKey"][1:]}',
'regList': [], 'span': 24, 'dictionaryType': '',
'trigger': 'blur' if f['jnpfKey'] == 'input' else '',
},
'__vModel__': f['field'], 'field': f['field'], 'clearable': True,
'style': {'width': '100%'},
'placeholder': f'请输入{f["fieldName"]}' if f['jnpfKey'] in ('input', 'textarea') else f'请选择{f["fieldName"]}',
'id': f['field'], 'fullName': f['fieldName'], 'fullNameI18nCode': ['']
}
def make_subtable_container(sub_fields, sub_table, sub_vmodel, sub_form_id):
"""子表容器"""
children = []
for i, f in enumerate(sub_fields):
children.append({
'clearable': True,
'__config__': {
'formId': sub_form_id + 1 + i, 'visibility': ['pc', 'app'], 'jnpfKey': f['jnpfKey'],
'noShow': False, 'parentVModel': sub_vmodel, 'tipLabel': '', 'dragDisabled': False,
'className': [], 'label': f['fieldName'], 'showLabel': True, 'required': False,
'tableName': '{主表名}', # ⚠️ 错位(设计器 bug)
'relationTable': sub_table, 'renderKey': 1780900000100 + i, 'layout': 'colFormItem',
'tagIcon': f'icon-ym icon-ym-generator-{f["jnpfKey"].lower()}',
'isSubTable': True, # 必填
'tag': 'JnpfInputNumber' if f['jnpfKey'] == 'inputNumber' else 'JnpfInput',
'regList': [], 'span': 24
},
'__vModel__': f['field'],
'style': {'width': '100%'},
'placeholder': f'请输入{f["fieldName"]}' if f['jnpfKey'] in ('input', 'textarea') else f'请选择{f["fieldName"]}'
})
return {
'showSummary': 0, 'actionText': '添加', 'tableConf': {}, 'defaultValue': [],
'footerBtnsList': [
{'label': '添加', 'btnIcon': 'icon-ym icon-ym-btn-add', 'show': True, 'btnType': 'primary', 'value': 'add'},
{'value': 'batchRemove', 'showConfirm': True, 'btnType': 'danger',
'btnIcon': 'icon-ym icon-ym-btn-clearn', 'label': '批量删除', 'show': True}
],
'addTableConf': {'hasPage': True, 'interfaceName': '', 'popupWidth': '800px',
'interfaceId': '', 'pageSize': 20, 'popupTitle': '选择数据',
'templateJson': [], 'relationOptions': [], 'columnOptions': [], 'popupType': 'dialog'},
'columnBtnsList': [
{'label': '复制', 'btnIcon': 'icon-ym icon-ym-btn-edit', 'show': True, 'btnType': 'primary', 'value': 'copy'},
{'value': 'remove', 'showConfirm': True, 'btnType': 'danger',
'btnIcon': 'icon-ym icon-ym-btn-clearn', 'label': '删除', 'show': True}
],
'summaryField': [], 'showDeleteBtn': True, 'addType': 0,
'__config__': {
'formId': sub_form_id, 'visibility': ['pc', 'app'], 'jnpfKey': 'table',
'defaultValue': [], 'noShow': False, 'tipLabel': '', 'dragDisabled': False,
'className': [], 'label': '明细', 'type': 'table', 'showLabel': False,
'tableName': sub_table, 'renderKey': 1780900000050, 'layout': 'rowFormItem',
'tagIcon': 'icon-ym icon-ym-generator-table',
'children': children, 'showTitle': True, 'complexHeaderList': [],
'tag': 'JnpfInputTable', 'componentName': f'table{sub_form_id}', 'span': 24
},
'showAddBtn': True, '__vModel__': sub_vmodel, 'layoutType': 'table', 'disabled': False
}
def build_form_data(template_fd, main_fields, sub_container):
fd = dict(template_fd)
fields = [make_field(f, TABLE, i) for i, f in enumerate(main_fields)]
fields.append(sub_container)
fd['fields'] = fields
fd['idGlobal'] = SUB_FORM_ID + 10
fd['tableName'] = TABLE
return fd
def build_tables(template_tables, main_fields, sub_fields, table, subtable, name):
new_tables = []
for t in template_tables:
if t.get('typeId') == '1':
nt = dict(t)
nt['table'] = table
nt['tableName'] = name
nt['comment'] = '主表'
new_t_fields = []
for f in t.get('fields', []):
ff = dict(f)
if f.get('field') == 'f_name':
first = main_fields[0]
ff['field'] = first['field']
ff['fieldName'] = first['fieldName']
ff['dataLength'] = first['dataLength']
new_t_fields.append(ff)
else:
new_t_fields.append(ff)
for i, biz in enumerate(main_fields[1:]):
new_t_fields.insert(1 + i, {
'allowNull': 0 if biz.get('required') else 1, 'autoIncrement': 0,
'dataLength': biz['dataLength'], 'dataType': biz['dataType'],
'field': biz['field'], 'fieldName': biz['fieldName'],
'primaryKey': 0, 'identity': 0
})
nt['fields'] = new_t_fields
new_tables.append(nt)
elif t.get('typeId') == '0':
nt = dict(t)
nt['table'] = subtable
nt['tableName'] = '明细'
nt['relationTable'] = table
nt['relationField'] = 'f_id'
nt['tableField'] = 'f_foreignId'
nt['tableKey'] = 'f_id'
new_t_fields = []
for f in t.get('fields', []):
ff = dict(f)
# 替换业务字段
matched = next((sf for sf in sub_fields if sf['field'] == ff.get('field')), None)
if matched:
ff['fieldName'] = matched['fieldName']
ff['dataType'] = matched['dataType']
ff['dataLength'] = matched['dataLength']
new_t_fields.append(ff)
else:
new_t_fields.append(ff)
# 添加未在模板中的子表字段
for sf in sub_fields:
if not any(ff.get('field') == sf['field'] for ff in new_t_fields):
new_t_fields.append({
'allowNull': 1, 'autoIncrement': 0,
'dataLength': sf['dataLength'], 'dataType': sf['dataType'],
'field': sf['field'], 'fieldName': sf['fieldName'],
'primaryKey': 0, 'identity': 0
})
nt['fields'] = new_t_fields
new_tables.append(nt)
return new_tables
def build_column_data(template_cd, main_fields):
cd = dict(template_cd)
cd['columnOptions'] = [{'value': f['field'], 'label': f['fieldName'], 'width': 120, 'sort': i}
for i, f in enumerate(main_fields)]
cd['searchList'] = [{'field': main_fields[0]['field'], 'label': main_fields[0]['fieldName'],
'jnpfKey': 'input', 'prop': main_fields[0]['field'], 'sourceType': 2,
'searchType': 2, 'searchMultiple': False, 'isKeyword': False,
'id': main_fields[0]['field'], 'fullName': main_fields[0]['fieldName'],
'fullNameI18nCode': [''], 'search': 1, 'searchPop': 0}]
cd['formData'] = {
'formRef': 'formRef', 'formModel': 'query', 'size': 'default',
'labelPosition': 'right', 'labelWidth': 100, 'gutter': 15, 'disabled': False,
'span': 6, 'formBtns': True,
'fields': [{'__config__': {'label': main_fields[0]['fieldName'], 'jnpfKey': 'input',
'tag': 'JnpfInput', 'formId': 301, 'visibility': ['pc', 'app']},
'__vModel__': main_fields[0]['field']}],
'idGlobal': 301
}
cd['columnList'] = [{'label': f['fieldName'], 'prop': f['field'], 'jnpfKey': 'input',
'fixed': 'none', 'headerAlign': 'left', 'align': 'left', 'sortable': False,
'width': None, 'id': f['field'], 'fullName': f['fieldName'],
'fullNameI18nCode': ['']} for f in main_fields]
cd['defaultColumnList'] = cd['columnList']
return cd
def call_api(url, payload, auth_header, method='POST'):
req = urllib.request.Request(url,
data=json.dumps(payload, ensure_ascii=False).encode('utf-8'),
headers={'Authorization': auth_header, 'App-Code': TARGET_APP_CODE, 'Content-Type': 'application/json'},
method=method)
try:
resp = urllib.request.urlopen(req, timeout=60)
return json.loads(resp.read().decode('utf-8'))
except urllib.error.HTTPError as e:
return {'code': e.code, 'msg': e.read().decode('utf-8')[:500]}
# ========== MAIN ==========
def main():
print(f'=== 主子表表单创建:{NAME} ({ENCODE}) ===')
auth_header, db_link_id = load_token()
template = fetch_template(TEMPLATE_FORM_ID)
template_fd = json.loads(template['formData'])
template_tables = json.loads(template['tables'])
template_cd = json.loads(template['columnData'])
sub_container = make_subtable_container(SUB_FIELDS, SUBTABLE, SUB_VMODEL, SUB_FORM_ID)
# ⚠️ 修正:把子表内字段的 tableName 改为主表名
for child in sub_container['__config__']['children']:
child['__config__']['tableName'] = TABLE
new_fd = build_form_data(template_fd, MAIN_FIELDS, sub_container)
new_tables = build_tables(template_tables, MAIN_FIELDS, SUB_FIELDS, TABLE, SUBTABLE, NAME)
new_cd = build_column_data(template_cd, MAIN_FIELDS)
payload = {
'fullName': NAME, 'enCode': ENCODE, 'type': 1, 'description': '由create_subtable_form.py生成',
'webType': 2, 'state': 0, 'sortCode': 0,
'category': uuid.uuid4().hex.replace('-', ''),
'dbLinkId': db_link_id,
'tables': json.dumps(new_tables, ensure_ascii=False),
'formData': json.dumps(new_fd, ensure_ascii=False),
'columnData': json.dumps(new_cd, ensure_ascii=False),
'appColumnData': json.dumps(new_cd, ensure_ascii=False),
'enableFlow': 0
}
login_target(TARGET_APP_CODE)
auth_header, _ = load_token()
print(f'→ POST /api/visualdev/Base (dbLinkId={db_link_id})')
result = call_api('http://127.0.0.1:30000/api/visualdev/Base', payload, auth_header)
print(f' Create: code={result.get("code")} msg={result.get("msg")}')
if result.get('code') != 200:
print('❌ 创建失败:1) 主/子表是否预建 2) dbLinkId 3) 子表 f_foreignId')
return 1
form_id = result['data']['id']
print(f' Form ID: {form_id}')
print(f'→ POST /api/visualdev/Base/{form_id}/Actions/Release')
result2 = call_api(f'http://127.0.0.1:30000/api/visualdev/Base/{form_id}/Actions/Release', {}, auth_header)
print(f' Release: code={result2.get("code")} msg={result2.get("msg")}')
if result2.get('code') == 200:
print(f'\n✅ Master-Subtable form {form_id} CREATED+RELEASED!')
# 菜单
print(f'→ dacli menu create --name="{NAME}" --formId={form_id}')
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'menu', 'create', f'--name={NAME}', f'--formId={form_id}'],
capture_output=True, text=True)
print(proc.stdout[-200:])
return 0
if __name__ == '__main__':
sys.exit(main())
@@ -1,246 +0,0 @@
#!/usr/bin/env python3
"""
create_workflow_form.py - 工作流表单创建脚本
前置:
1. 已预建物理表
2. dacli workflow create --name=X --enCode=y 创工作流模板
3. dacli login --account=admin --password=123456 --appCode=tdd
用法:
1. 修改下方 CONFIG(特别是 WF_ID)
2. python3 create_workflow_form.py
"""
import json, subprocess, sys, urllib.request, urllib.error, uuid
from pathlib import Path
# ========== CONFIG ==========
TEMPLATE_FORM_ID = '833737463619919749'
TARGET_APP_CODE = 'tdd'
NAME = '请假模板'
ENCODE = 'leave_template'
TABLE = 'leave_template_main' # 必须已预建
WF_ID = 'YOUR_FLOW_TEMPLATE_ID_HERE' # ⚠️ 必须修改!用 dacli workflow list 获取
# 业务字段
FIELDS = [
{'field': 'f_name', 'fieldName': '申请人', 'jnpfKey': 'input', 'dataType': 'varchar', 'dataLength': '100', 'required': True},
{'field': 'f_start', 'fieldName': '开始', 'jnpfKey': 'datePicker', 'dataType': 'datetime', 'dataLength': '0', 'required': True},
{'field': 'f_end', 'fieldName': '结束', 'jnpfKey': 'datePicker', 'dataType': 'datetime', 'dataLength': '0', 'required': True},
{'field': 'f_reason', 'fieldName': '事由', 'jnpfKey': 'textarea', 'dataType': 'varchar', 'dataLength': '500', 'required': False},
]
# 审批人(userId,可多个)
APPROVERS = [{'approverUserId': '349057407209541', 'name': 'admin'}] # admin userId
# ========== HELPERS ==========
def load_token():
token_path = Path('/home/ubuntu/ccWorkDir/.dacli-token/token.json')
if not token_path.exists():
sys.exit('❌ token.json 不存在,请先 dacli login')
with open(token_path) as f:
tk = json.load(f)
return tk['token'], tk['dbLinkId']
def fetch_template(template_id, src_app='developSystem'):
print(f'→ 切换 {src_app} 拉取模板 {template_id}')
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={src_app}'],
capture_output=True, text=True)
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'form', 'info', template_id], capture_output=True, text=True)
return json.loads(proc.stdout)['data']
def login_target(app_code):
subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'login', '--account=admin', '--password=123456', f'--appCode={app_code}'],
capture_output=True, text=True)
def make_field(f, table, idx):
return {
'__config__': {
'formId': 101 + idx, 'visibility': ['pc', 'app'], 'jnpfKey': f['jnpfKey'],
'noShow': False, 'tipLabel': '', 'dragDisabled': False, 'className': [],
'label': f['fieldName'], 'showLabel': True, 'required': f.get('required', False),
'tableName': table, 'renderKey': 1780900000000 + idx, 'layout': 'colFormItem',
'tagIcon': f'icon-ym icon-ym-generator-{f["jnpfKey"].lower()}',
'tag': 'JnpfInput' if f['jnpfKey'] in ('input', 'textarea') else f'Jnpf{f["jnpfKey"][0].upper()}{f["jnpfKey"][1:]}',
'regList': [], 'span': 24, 'dictionaryType': '',
'trigger': 'blur' if f['jnpfKey'] == 'input' else '',
},
'__vModel__': f['field'], 'field': f['field'], 'clearable': True,
'style': {'width': '100%'},
'placeholder': f'请输入{f["fieldName"]}' if f['jnpfKey'] in ('input', 'textarea') else f'请选择{f["fieldName"]}',
'id': f['field'], 'fullName': f['fieldName'], 'fullNameI18nCode': ['']
}
def build_form_data(template_fd, fields, table):
fd = dict(template_fd)
fd['tableName'] = table
fd['fields'] = [make_field(f, table, i) for i, f in enumerate(fields)]
fd['idGlobal'] = 100 + len(fields)
return fd
def build_tables(template_tables, fields, table, name):
new_tables = []
for t in template_tables:
if t.get('typeId') != '1':
continue
nt = dict(t)
nt['table'] = table
nt['tableName'] = name
nt['comment'] = '主表'
new_t_fields = []
for f in t.get('fields', []):
ff = dict(f)
if f.get('field') == 'f_name':
first = fields[0]
ff['field'] = first['field']
ff['fieldName'] = first['fieldName']
ff['dataLength'] = first['dataLength']
new_t_fields.append(ff)
else:
new_t_fields.append(ff)
for i, biz in enumerate(fields[1:]):
new_t_fields.insert(1 + i, {
'allowNull': 0 if biz.get('required') else 1, 'autoIncrement': 0,
'dataLength': biz['dataLength'], 'dataType': biz['dataType'],
'field': biz['field'], 'fieldName': biz['fieldName'],
'primaryKey': 0, 'identity': 0
})
nt['fields'] = new_t_fields
new_tables.append(nt)
return new_tables
def build_column_data(template_cd, fields):
cd = dict(template_cd)
cd['columnOptions'] = [{'value': f['field'], 'label': f['fieldName'], 'width': 120, 'sort': i}
for i, f in enumerate(fields)]
cd['searchList'] = [{'field': fields[0]['field'], 'label': fields[0]['fieldName'],
'jnpfKey': 'input', 'prop': fields[0]['field'], 'sourceType': 2,
'searchType': 2, 'searchMultiple': False, 'isKeyword': False,
'id': fields[0]['field'], 'fullName': fields[0]['fieldName'],
'fullNameI18nCode': [''], 'search': 1, 'searchPop': 0}]
cd['formData'] = {
'formRef': 'formRef', 'formModel': 'query', 'size': 'default',
'labelPosition': 'right', 'labelWidth': 100, 'gutter': 15, 'disabled': False,
'span': 6, 'formBtns': True,
'fields': [{'__config__': {'label': fields[0]['fieldName'], 'jnpfKey': 'input',
'tag': 'JnpfInput', 'formId': 201, 'visibility': ['pc', 'app']},
'__vModel__': fields[0]['field']}],
'idGlobal': 201
}
cd['columnList'] = [{'label': f['fieldName'], 'prop': f['field'], 'jnpfKey': 'input',
'fixed': 'none', 'headerAlign': 'left', 'align': 'left', 'sortable': False,
'width': None, 'id': f['field'], 'fullName': f['fieldName'],
'fullNameI18nCode': ['']} for f in fields]
cd['defaultColumnList'] = cd['columnList']
return cd
def build_flow_template(wf_id, wf_name, approvers):
"""BPMN: start → approve → end"""
nodes = [
{'id': 'node_start', 'type': 'start', 'name': '发起', 'x': 100, 'y': 100, 'property': {}}
]
for i, app in enumerate(approvers):
nodes.append({
'id': f'node_approve_{i}', 'type': 'approver',
'name': app.get('name', f'审批{i+1}'),
'x': 300 + i * 200, 'y': 100,
'property': {'approverUserId': app['approverUserId']}
})
nodes.append({'id': 'node_end', 'type': 'end', 'name': '结束', 'x': 500, 'y': 100, 'property': {}})
lines = [{'from': 'node_start', 'to': nodes[1]['id']}]
for i in range(1, len(nodes) - 1):
lines.append({'from': nodes[i]['id'], 'to': nodes[i + 1]['id']})
return {
'flowId': wf_id, 'flowName': wf_name,
'nodes': nodes, 'lines': lines
}
def call_api(url, payload, auth_header, method='POST'):
req = urllib.request.Request(url,
data=json.dumps(payload, ensure_ascii=False).encode('utf-8'),
headers={'Authorization': auth_header, 'App-Code': TARGET_APP_CODE, 'Content-Type': 'application/json'},
method=method)
try:
resp = urllib.request.urlopen(req, timeout=60)
return json.loads(resp.read().decode('utf-8'))
except urllib.error.HTTPError as e:
return {'code': e.code, 'msg': e.read().decode('utf-8')[:500]}
# ========== MAIN ==========
def main():
if WF_ID == 'YOUR_FLOW_TEMPLATE_ID_HERE':
sys.exit('❌ 请先在 CONFIG 中设置 WF_ID(dacli workflow list 获取)')
print(f'=== 工作流表单创建:{NAME} ({ENCODE}) flow={WF_ID} ===')
auth_header, db_link_id = load_token()
template = fetch_template(TEMPLATE_FORM_ID)
template_fd = json.loads(template['formData'])
template_tables = json.loads(template['tables'])
template_cd = json.loads(template['columnData'])
new_fd = build_form_data(template_fd, FIELDS, TABLE)
new_tables = build_tables(template_tables, FIELDS, TABLE, NAME)
new_cd = build_column_data(template_cd, FIELDS)
flow_template = build_flow_template(WF_ID, NAME, APPROVERS)
payload = {
'fullName': NAME, 'enCode': ENCODE, 'type': 1, 'description': '由create_workflow_form.py生成',
'webType': 3, # 3 = 表单+列表+工作流
'state': 0, 'sortCode': 0,
'category': uuid.uuid4().hex.replace('-', ''),
'dbLinkId': db_link_id,
'tables': json.dumps(new_tables, ensure_ascii=False),
'formData': json.dumps(new_fd, ensure_ascii=False),
'columnData': json.dumps(new_cd, ensure_ascii=False),
'appColumnData': json.dumps(new_cd, ensure_ascii=False),
'enableFlow': 1, # 启用工作流
'flowTemplateJson': json.dumps(flow_template, ensure_ascii=False)
}
login_target(TARGET_APP_CODE)
auth_header, _ = load_token()
print(f'→ POST /api/visualdev/Base (dbLinkId={db_link_id}, webType=3, enableFlow=1)')
result = call_api('http://127.0.0.1:30000/api/visualdev/Base', payload, auth_header)
print(f' Create: code={result.get("code")} msg={result.get("msg")}')
if result.get('code') != 200:
print('❌ 创建失败:1) 物理表是否预建 2) WF_ID 是否正确 3) dbLinkId')
return 1
form_id = result['data']['id']
print(f' Form ID: {form_id}')
print(f'→ POST /api/visualdev/Base/{form_id}/Actions/Release')
result2 = call_api(f'http://127.0.0.1:30000/api/visualdev/Base/{form_id}/Actions/Release', {}, auth_header)
print(f' Release: code={result2.get("code")} msg={result2.get("msg")}')
if result2.get('code') == 200:
print(f'\n✅ Workflow form {form_id} CREATED+RELEASED!')
# 菜单
print(f'→ dacli menu create --name="{NAME}" --formId={form_id}')
proc = subprocess.run(['java', '-jar', '/home/ubuntu/ccWorkDir/boot/ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar',
'menu', 'create', f'--name={NAME}', f'--formId={form_id}'],
capture_output=True, text=True)
print(proc.stdout[-200:])
return 0
if __name__ == '__main__':
sys.exit(main())
@@ -1,396 +0,0 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
polish-convention.py — OLD → NEW 约定自动迁移工具(v6.1.3 / P17,P28 扩展,v10.3 防御卡点)
背景:
dacli form create 用 `--fields` + 物理层 `field` + `fieldName`(NEW 约定)
v6.0 时代的设计文件用 `--fieldsJson` + 渲染层 `vModel` + `--columnDataJson`(OLD 约定)
两者混用导致 dacli form create 失败(Unknown option: --fieldsJson)
v10.3 新增(columnData 缺 __config__ 防御):
JNPF 前端 getFormSchemaItem 强假设 columnData.searchList/columnList/defaultColumnList/columnOptions
每项都有 __config__.jnpfKey 包装,否则列表页空白。
新增 --validate 模式:扫 design-jnpf.html 的 #form-* 锚点,调 dacli form validate 检查已部署 form。
功能:
1. 替换 --fieldsJson → --fields
2. 替换字段 JSON 中 "vModel" → "field" + 自动加 "fieldName"(从 4.2 表查中文名)
3. 删除 --columnDataJson 整段(dacli 不支持)
4. 替换 4.2 字段表表头 vModel → field
5. 输出 NEW 约定文件(同目录 *.new.html 或 --in-place 直接覆盖)
6. v10.3 --validate: 扫 design-jnpf.html 的 #form-* 锚点 + app 内 form list,调 dacli form validate
7. v10.3 --require-c59: 检查 design-jnpf.html 是否引用 C.5.9/C.5.10(缺则警告)
P28 扩展:
- 目录批量模式:python3 polish-convention.py docs/ # 扫描所有 design-jnpf*.html
- --in-place 标志:直接覆盖原文件(不输出 .new.html)
- 退出码规范化(CI 卡点用)
用法:
# 1. OLD 约定迁移:单文件 dry-run(默认,输出 *.new.html)
python3 polish-convention.py docs/workSystem/design-jnpf.html
# 2. OLD 约定迁移:单文件 in-place(直接覆盖)
python3 polish-convention.py docs/workSystem/design-jnpf.html --in-place
# 3. 目录批量 dry-run
python3 polish-convention.py docs/ --glob='design-jnpf*.html'
# 4. 目录批量 in-place(CI 自动修复用)
python3 polish-convention.py docs/ --in-place --glob='design-jnpf*.html'
# 5. v10.3 columnData 完整性体检(设计文件 → form list → dacli form validate)
python3 polish-convention.py docs/tds/design-jnpf.html --validate
# 6. v10.3 全 app 设计文件 + 全 form 体检(CI 卡点)
python3 polish-convention.py docs/ --validate --glob='design-jnpf*.html'
# 7. v10.3 检查设计文件是否引用 C.5.9/C.5.10(缺则警告)
python3 polish-convention.py docs/ --require-c59 --glob='design-jnpf*.html'
退出码:
0 = 全部文件已 NEW 约定 + columnData PASS + 引用 C.5.9/C.5.10
1 = 有文件残留 OLD 约定(dry-run 模式)/ columnData FAIL / 缺 C.5.9/C.5.10 引用
2 = 输入路径不存在
3 = IO 错误
4 = 部分文件迁移失败
"""
import argparse
import json
import re
import subprocess
import sys
from pathlib import Path
# === v10.3 防御卡点:columnData 缺 __config__ 检测 ===
def check_c59_referenced(text: str) -> dict:
"""
检查设计文件是否引用 SKILL.md C.5.9/C.5.10(v10.2 columnData 防御)
返回 {'referenced': bool, 'positions': [int, ...]}
"""
positions = []
for pattern in [r'C\.5\.9', r'C\.5\.10', r'列\s*表\s*页\s*空\s*白', r'columnData\s*缺', r'validate']:
for m in re.finditer(pattern, text):
positions.append(m.start())
return {'referenced': len(positions) > 0, 'positions': positions}
def extract_form_anchors(text: str) -> list:
"""从 design-jnpf.html 提取 <a id="form-X"> 锚点 → enCode 列表"""
return re.findall(r'<a id="form-(\w+)"></a>', text)
def run_dacli_form_validate(form_id: str) -> dict:
"""
调 dacli form validate <id>,返回 {'id': str, 'pass': bool, 'output': str}
dacli 已固化退出码 0=PASS, 1=FAIL
"""
try:
proc = subprocess.run(
['dacli', 'form', 'validate', form_id],
capture_output=True, text=True, timeout=30
)
output = (proc.stdout or '') + (proc.stderr or '')
return {
'id': form_id,
'pass': proc.returncode == 0,
'output': output.strip()[:500],
}
except FileNotFoundError:
return {'id': form_id, 'pass': None, 'output': 'dacli not found in PATH'}
except subprocess.TimeoutExpired:
return {'id': form_id, 'pass': None, 'output': 'dacli form validate timeout'}
except Exception as e:
return {'id': form_id, 'pass': None, 'output': str(e)}
def get_dacli_form_id(encode: str) -> str:
"""dacli form list --keyword=encode 找 form id"""
try:
proc = subprocess.run(
['dacli', 'form', 'list', f'--keyword={encode}'],
capture_output=True, text=True, timeout=30
)
out = proc.stdout or ''
# Strip ANSI
out = re.sub(r'\x1b\[[0-9;]*[a-zA-Z]', '', out)
# Find id from JSON
m = re.search(r'"id":\s*"?(\d+)"?', out)
if m:
return m.group(1)
# Try table format: | <id> | <name> | <encode> |
m2 = re.search(r'\|\s*(\d{15,})\s*\|[^\|]*\|[^\|]*' + re.escape(encode) + r'\s*\|', out)
if m2:
return m2.group(1)
return ''
except Exception:
return ''
def check_file_validate(path: Path) -> dict:
"""
对 design-jnpf.html 跑 v10.3 防御卡点:
1. 提取 #form-* 锚点
2. 对每个 enCode → 查 formId → 调 dacli form validate
3. 返回 {'form_count': int, 'pass_count': int, 'fail_count': int, 'results': [...]}
"""
try:
text = path.read_text(encoding='utf-8')
except Exception as e:
return {'error': f'读取失败: {e}'}
encodes = extract_form_anchors(text)
results = []
pass_n = 0
fail_n = 0
for en in encodes:
form_id = get_dacli_form_id(en)
if not form_id:
results.append({'enCode': en, 'id': '', 'pass': None, 'msg': 'formId 找不到(form 未创建或 app 不对)'})
fail_n += 1
continue
r = run_dacli_form_validate(form_id)
r['enCode'] = en
if r['pass']:
pass_n += 1
else:
fail_n += 1
results.append(r)
return {
'form_count': len(encodes),
'pass_count': pass_n,
'fail_count': fail_n,
'results': results,
}
def check_file_c59(path: Path) -> dict:
"""检查 design-jnpf.html 是否引用 C.5.9/C.5.10"""
try:
text = path.read_text(encoding='utf-8')
except Exception as e:
return {'error': f'读取失败: {e}'}
r = check_c59_referenced(text)
return {
'referenced': r['referenced'],
'positions': len(r['positions']),
}
def detect_old_convention(text: str) -> dict:
"""检测 OLD 约定残留,返回发现位置"""
issues = {
'fieldsJson': [],
'vModel_field_def': [],
'columnDataJson': [],
'vModel_header': [],
}
for m in re.finditer(r'--fieldsJson', text):
issues['fieldsJson'].append(m.start())
for m in re.finditer(r'"vModel":\s*"f_\w+"', text):
issues['vModel_field_def'].append(m.start())
for m in re.finditer(r'--columnDataJson', text):
issues['columnDataJson'].append(m.start())
for m in re.finditer(r'<th>vModel</th>', text):
issues['vModel_header'].append(m.start())
return issues
def extract_field_chinese_names(text: str) -> dict:
"""从 4.2 字段表提取 field → 中文名 映射"""
mapping = {}
pattern = re.compile(r'<tr><td>(f_\w+)</td><td>([^<]+)</td><td>(\w+)</td>', re.MULTILINE)
for m in pattern.finditer(text):
field, name, _ = m.group(1), m.group(2), m.group(3)
if field and name:
mapping[field] = name
return mapping
def migrate(text: str):
"""执行 OLD → NEW 约定迁移,返回 (新文本, 修改计数 dict)"""
out = text
counts = {}
field_names = extract_field_chinese_names(text)
# 1. --fieldsJson → --fields
counts['fieldsJson'] = len(re.findall(r'--fieldsJson', out))
out = re.sub(r'--fieldsJson', '--fields', out)
# 2. "vModel" → "field" + "fieldName"
def replace_vmodel(m):
field = m.group(1)
name = field_names.get(field, field)
return f'"field": "{field}", "fieldName": "{name}"'
counts['vModel'] = len(re.findall(r'"vModel":\s*"(f_\w+)"', out))
out = re.sub(r'"vModel":\s*"(f_\w+)"', replace_vmodel, out)
# 3. 删除 --columnDataJson 整段
pattern = re.compile(r"\s*--columnDataJson='\[.*?\]'\s*\\\n", re.DOTALL)
matches = pattern.findall(out)
counts['columnDataJson'] = len(matches)
out = pattern.sub('', out)
# 4. 字段表表头
counts['vModel_header'] = len(re.findall(r'<th>vModel</th>', out))
out = re.sub(r'<th>vModel</th>', '<th>field</th>', out)
return out, counts
def process_file(path: Path, in_place: bool) -> dict:
"""
处理单个文件,返回结果字典:
{'status': 'clean'|'migrated'|'migrated_dryrun'|'error', 'counts': {...}, 'msg': str}
"""
try:
text = path.read_text(encoding='utf-8')
except Exception as e:
return {'status': 'error', 'msg': f'读取失败: {e}'}
issues = detect_old_convention(text)
total = sum(len(v) for v in issues.values())
if total == 0:
return {'status': 'clean', 'counts': {}, 'msg': '无 OLD 约定'}
if not in_place:
new_path = path.with_suffix('.new.html')
try:
new_text, counts = migrate(text)
new_path.write_text(new_text, encoding='utf-8')
return {'status': 'migrated_dryrun', 'counts': counts,
'msg': f'已生成 {new_path}(请检查后手动覆盖)'}
except Exception as e:
return {'status': 'error', 'msg': f'写入 .new.html 失败: {e}'}
try:
new_text, counts = migrate(text)
path.write_text(new_text, encoding='utf-8')
return {'status': 'migrated', 'counts': counts, 'msg': f'已覆盖 {path}'}
except Exception as e:
return {'status': 'error', 'msg': f'覆盖失败: {e}'}
def main():
ap = argparse.ArgumentParser(
description='OLD → NEW 约定自动迁移工具(v6.1.3 / P17 + v10.3 防御卡点)',
formatter_class=argparse.RawDescriptionHelpFormatter,
)
ap.add_argument('path', help='文件路径或目录')
ap.add_argument('--in-place', action='store_true', help='OLD 约定迁移:直接修改原文件(默认 dry-run)')
ap.add_argument('--glob', default='design-jnpf*.html',
help='目录模式下匹配的文件 pattern(默认 design-jnpf*.html)')
# v10.3 新增
ap.add_argument('--validate', action='store_true',
help='v10.3 columnData 防御卡点:扫 #form-* 锚点 → 调 dacli form validate')
ap.add_argument('--require-c59', action='store_true',
help='v10.3 检查设计文件是否引用 SKILL.md C.5.9/C.5.10(缺则退出 1)')
args = ap.parse_args()
target = Path(args.path)
if not target.exists():
print(f'X 路径不存在: {target}', file=sys.stderr)
sys.exit(2)
if target.is_file():
files = [target]
else:
files = sorted(target.rglob(args.glob))
if not files:
print(f'! 目录 {target} 下未找到 {args.glob} 文件')
sys.exit(0)
print('=== polish-convention.py ===', file=sys.stderr)
print(f'目标: {target}', file=sys.stderr)
print(f'文件数: {len(files)}', file=sys.stderr)
mode_parts = []
if args.in_place: mode_parts.append('in-place')
else: mode_parts.append('dry-run')
if args.validate: mode_parts.append('validate')
if args.require_c59: mode_parts.append('require-c59')
print(f'模式: {", ".join(mode_parts)}', file=sys.stderr)
print(file=sys.stderr)
total_clean = 0
total_migrated = 0
total_error = 0
total_validate_pass = 0
total_validate_fail = 0
total_c59_pass = 0
total_c59_fail = 0
has_issue = False
for f in files:
result = process_file(f, args.in_place)
print(f' [{result["status"]:18}] {f}', file=sys.stderr)
if result['msg'] and result['status'] != 'clean':
print(f' {result["msg"]}', file=sys.stderr)
if result['counts']:
for k, n in result['counts'].items():
if n > 0:
print(f' [count] {k}: {n}', file=sys.stderr)
if result['status'] == 'clean':
total_clean += 1
elif result['status'] in ('migrated', 'migrated_dryrun'):
total_migrated += 1
if not args.in_place:
has_issue = True
elif result['status'] == 'error':
total_error += 1
# v10.3 --validate
if args.validate:
vr = check_file_validate(f)
if 'error' in vr:
print(f' [validate] 错误: {vr["error"]}', file=sys.stderr)
continue
print(f' [validate] forms={vr["form_count"]}, pass={vr["pass_count"]}, fail={vr["fail_count"]}', file=sys.stderr)
total_validate_pass += vr['pass_count']
total_validate_fail += vr['fail_count']
for r in vr['results']:
sym = '✅' if r['pass'] else ('❌' if r['pass'] is False else '⚠️')
print(f' {sym} {r["enCode"]:25s} id={r["id"]} {r.get("output", "")[:200]}', file=sys.stderr)
if r['pass'] is False:
has_issue = True
# v10.3 --require-c59
if args.require_c59:
cr = check_file_c59(f)
if 'error' in cr:
print(f' [c59] 错误: {cr["error"]}', file=sys.stderr)
continue
if cr['referenced']:
print(f' [c59] ✅ 引用 C.5.9/C.5.10({cr["positions"]} 处)', file=sys.stderr)
total_c59_pass += 1
else:
print(f' [c59] ❌ 未引用 C.5.9/C.5.10(缺 v10.2 防御卡点说明)', file=sys.stderr)
total_c59_fail += 1
has_issue = True
print(file=sys.stderr)
print('=== 汇总 ===', file=sys.stderr)
print(f' OLD 约定 OK 干净: {total_clean}', file=sys.stderr)
print(f' OLD 约定 >> 迁移: {total_migrated}', file=sys.stderr)
print(f' OLD 约定 X 错误: {total_error}', file=sys.stderr)
if args.validate:
print(f' v10.3 validate PASS: {total_validate_pass}', file=sys.stderr)
print(f' v10.3 validate FAIL: {total_validate_fail}', file=sys.stderr)
if args.require_c59:
print(f' v10.3 C.5.9 引用 ✅: {total_c59_pass}', file=sys.stderr)
print(f' v10.3 C.5.9 引用 ❌: {total_c59_fail}', file=sys.stderr)
print(file=sys.stderr)
if total_error > 0:
sys.exit(3)
if has_issue:
sys.exit(1)
sys.exit(0)
if __name__ == '__main__':
sys.exit(main())