Files
dacli/docs/skill-audit/form-development.md
T
ssw 06aed3830c chore(v0.11+): 合并 dacli/.claude/skills/dacli-ts 到父 .claude/skills/ + Phase 3 Batch F 审计
用户拍板 (2026-06-25): 为避免重复, 把 dacli 子项目的 dacli-ts skill 移到父 .claude/skills/ 下作为实体目录 (而非原 symlink), 同时删 dacli/CLAUDE.md 和 dacli/.claude/ 目录.

变更:
1. 删除整个 dacli/.claude/ 目录 (30 个文件, 包含 settings.local.json + dacli-ts skill 全部内容)
2. 删除 dacli/CLAUDE.md (内容已并入父 CLAUDE.md)
3. 父 .claude/skills/dacli-ts 替换 symlink 为实体目录 (从 dacli/.claude/skills/dacli-ts 复制)
4. 更新 4 处文档引用 (dacli/.claude/skills/dacli-ts → .claude/skills/dacli-ts, dacli/CLAUDE.md 标注合并)
5. Phase 3 Batch F 5 个主流程 skill 审计报告 (新增 docs/skill-audit/):
   - dacli-ts.md — P0 必修 3 项 (补 30+ NEW-CMD + webapi 18 模块 + form validate deprecation)
   - ssw-h5dev-flow.md — P0 必修 5 项 (doc toc/search + form update + selector + log exception)
   - design-jnpf-execute.md — P0 必修 6 项 (删 _blindspots.ts 引用 + 补 webapi + 4 NEW-CMD)
   - form-development.md — P0 必修 3 项 (删 form msrelation 误用 + 补 form update + webapi 段)
   - form-fix.md — P0 必修 3 项 (删 dacli form fix 误用 10+ 处 + 补 form clone/update 流程)

Batch G-J 子代理审计待下一轮执行 (见 plan §12.3).

下一步: 执行 Phase 3 P0 必修 (按 audit 报告) → Phase 4 历史残留清理 → Phase 5 baseline 验证
2026-06-25 15:53:06 +08:00

19 KiB
Raw Blame History

form-development SKILL 审计报告

审计时间: 2026-06-25 审计版本: v0.11+ (38 commits, phase 2 完成) 审计对象: /home/ubuntu/ccWorkDir/.claude/skills/form-development/SKILL.md (648 行) 审计结果: 发现 3 处严重缺陷、5 处缺失、6 处过时引用


1. form 命令完整引用清单

1.1 skill 中引用的 form 子命令 (按行号)

行号 form 子命令 用途 状态
8 list/info/create/release/delete Picocli 迁移说明 ✅ 已更新
13 create, release, codegen 核心流程图 ✅ 正确
16 codegen 代码生成步骤 ✅ 正确
25 list 列表查询 ✅ 已 webapi 化 (9c14cda)
28 info 表单详情 ✅ 已 webapi 化 (9c14cda)
31 selector 功能下拉框 (v0.11+) ⚠️ 缺少详细使用示例
36 create 创建表单 ✅ 已 webapi 化 (c98bf2b)
46 create 视图表单 ✅ 正确
49 create 工作流表单 ✅ 正确
55 create 数据接口字段 ✅ 正确
61 release 发布 ✅ 已 webapi 化 (9c14cda)
64 delete 删除 ✅ 已 webapi 化 (9c14cda)
65 delete 级联删除 ✅ 已 webapi 化 (9c14cda)
124 info 获取 tables ✅ 已 webapi 化
133 e2e-smoke E2E 测试 ⚠️ 非标准 form 子命令
136 e2e-smoke E2E 测试示例 ⚠️ 非标准 form 子命令
174 create 工作流表单 ✅ 正确
242 create 声明式创建 ✅ 正确
309 msrelation 主子表关系 (2026-06-08 新增) ❌ 已删除,命令不存在
313 info relationForm 配置 ✅ 正确
331 info, release columnOptions 裁剪 ✅ 正确
353 create 客户管理表单 ✅ 正确
365 update 子表 children 注入 ❌ 缺少使用示例和 spec
371-398 msrelation 主子表 ER 关系章节 ❌ 命令已删除,需移除整段
410-414 clone 表单克隆 ✅ 已 webapi 化 (7bf7762)
422 list 列表端点说明 ✅ 正确
427-429 create, update 主子表限制 ⚠️ update 命令说明不足
435 create 预建表路径 ✅ 正确
437 create autoRelease 不可靠说明 ✅ 正确
460 info form 结构提取 ✅ 正确
562 msrelation, --expand-subtable API + structure 验证 ❌ msrelation 已删除
586 create 长尾场景说明 ✅ 正确
588 export/import, fix 备份迁移 ✅ 正确
597-599 info, msrelation 仿造示例 ❌ msrelation 已删除
603 create 仿造示例 ✅ 正确
610 create 内化说明 ✅ 正确
631 info, list 示例查询 ✅ 正确
637 export, import, fix 直接 fork 模式 ✅ 正确
643 codegen 代码生成 ✅ 正确

1.2 skill 缺失的 form 子命令 (v0.11+ 新增)

子命令 commit 状态 重要性
form update 801a204 ❌ 完全缺失使用示例 P0
form selector 5f663eb ⚠️ 仅 1 行说明,缺少完整用法 P1
form validate (webapi 化) 9c14cda ❌ 未提及 webapi 化 P1
form fixcolumndata (webapi 化) 9c14cda ❌ 未提及 webapi 化 P1
form clone (webapi 化) 7bf7762 ❌ 未提及 webapi 化 P1
form export (webapi 化) 7bf7762 ❌ 未提及 webapi 化 P1
form codegen (webapi 化) 938c31d ❌ 未提及 webapi 化 P1
form import (webapi 化) e6a56f3 ❌ 未提及 webapi 化 P1
form create (webapi 化) c98bf2b ❌ 未提及 webapi 化 P1
form bindflow (webapi 化) 9c14cda ❌ 完全缺失 P2
form lint 已存在 ❌ 完全缺失 P2

2. 严重缺陷 (P0 必修)

🔴 缺陷 1: 引用已删除的 dacli form msrelation 命令

影响行号: 309, 371-398, 562, 597-599

问题描述:

  • skill 中 4 处提到 dacli form msrelation <id>,包括完整的章节 (371-398 行)
  • 该命令在 v0.11+ Phase 2 重构中已删除
  • 应替换为 dacli form info <id> --expand-subtable

修改建议:

# ❌ 旧 (skill 当前内容)
dacli form msrelation <id>

# ✅ 新 (v0.11+)
dacli form info <id> --expand-subtable

具体替换位置:

  1. 行 309: 删除 > 用 dacli form msrelation <id> 一键查主子表名+ER关系
  2. 行 371-398: 整段删除 (## 🔍 dacli form msrelation (2026-06-08 新增)章节)
  3. 行 562: 删除 dacli form msrelation 引用
  4. 行 597-599: 替换为:
    dacli form info <示例ID> --expand-subtable # 主子表 ER 展开
    

🔴 缺陷 2: 缺少 dacli form update 详细使用说明

影响行号: 365, 427-429 (仅简短提及)

问题描述:

  • dacli form update 是 v0.11+ P0 高需求 NEW-CMD (commit 801a204)
  • 是表单 CRUD 闭环的关键命令 (增量改 schema)
  • skill 中仅 2 处提及 (365, 427-429),均为简短描述,缺少:
    • 完整参数说明
    • 使用场景示例
    • 与其他命令的配合 (如主子表 children 注入)

当前内容:

# 行 365
# 子表需要 1) 先用 dm create 建子表 2) 用 form update 注入 children 配置
# 行 427-429
1. dacli form create 不支持主子表(--childTables 未实现)
   - 临时方案:用 dm create 建子表 → 手工 form update 注入 children
   - 长期方案:dacli form create 增加 --childTables 参数

新增章节建议 (应添加到 §"表单克隆" 前):

## 🔧 dacli form update <id> (v0.11+ P0 NEW-CMD)

> **高需求命令**: 增量修改 form schema,无需完整重建
> **Commit**: 801a204 | **Webapi 化**: ✅ (走 webapi/visualDev.ts)

### 使用场景

1. **主子表 children 注入** (替代手工编辑 formData)
2. **columnData 字段调整** (避免 form clone + 重配置)
3. **formData 配置项修改** (如 logicDelete / dataLog 开关)
4. **修复老 form 缺 __config__** (配合 validate)

### 基本用法

```bash
# 更新表单字段 (增量, merge 到现有 schema)
dacli form update <id> --fields='[{"field":"f_new","fieldName":"新字段",...}]'

# 更新主子表 children (替换指定 vModel 的子表字段)
dacli form update <id> --subtable='orderItems' --children='[...]'

# 更新 formData 配置项 (logicDelete / dataLog 等)
dacli form update <id> --formData='{"logicalDelete":true}'

# 更新 columnData (列表列配置)
dacli form update <id> --columnData='{...}'

# 干跑 (只打印 diff, 不提交)
dacli form update <id> --fields='[...]' --dry-run

主子表注入示例 (替换 365 行临时方案)

# Step 1: 建主子表 (dm create)
dacli dm create --table=ct_order_items --tableName="订单明细" \
  --dbLinkId=<id> --fields='[
    {"field":"f_goods","fieldName":"商品","dataType":"varchar","dataLength":"200"},
    {"field":"f_quantity","fieldName":"数量","dataType":"int","dataLength":"0"},
    {"field":"f_foreignId","fieldName":"外键","dataType":"varchar","dataLength":"50"}
  ]'

# Step 2: 主表单已创建 (含 orderItems 容器)
dacli form info <id>  # 看现有 schema

# Step 3: 注入主子表 children (替换手工编辑)
dacli form update <id> --subtable=orderItems --children='[
  {"field":"f_goods","jnpfKey":"input","dataType":"varchar","dataLength":"200","required":true},
  {"field":"f_quantity","jnpfKey":"inputNumber","dataType":"int","dataLength":"0","required":true}
]'

# Step 4: 重新发布 (必须!)
dacli form release <id>

注意事项

  • 必传 --release: update 修改 schema 后必须调 release,否则前端拿到旧 schema
  • 字段冲突保护: update 会校验 fields 冲突,避免覆盖系统字段 (f_id / f_tenant_id / f_version)
  • 主子表命名: 子表名 = ct{主表ID+1} (见 §"主子表命名规则")
  • 列数限制: relationForm columnOptions ≤ 5 列 (见 §"relationForm 规范")

与其他命令配合

# 完整 CRUD 闭环
dacli form create --fullName=X --enCode=Y --fields='[...]' --autoRelease
dacli form update <id> --fields='[{...新字段...}]'  # 增量改
dacli form release <id>                              # 必须重新发布
dacli form info <id> --json | jq '.fields'           # 验证

### 🔴 缺陷 3: 缺少 webapi 镜像架构说明

**影响范围**: 整篇 skill

**问题描述**:
- v0.11+ Phase 2 完成 form 11 个子命令 22 处 webapi 化 (累计 ~400 行硬编码消除)
- skill 中**完全没有提及**这一重要架构变化
- AI 使用 dacli 时无法了解 webapi 镜像的优势 (0 复刻 0 快照 0 漂移)

**应新增章节** (建议放在 §"核心流程" 后):

```markdown
## v0.11+ webapi 镜像架构 (重要)

> **2026-06-25 v0.11+ Phase 2 闭环**:所有 form 子命令已改用 webapi 镜像
> **Commit 序列**: 9c14cda → 7bf7762 → 938c31d → e6a56f3 → c98bf2b

### 什么是 webapi 镜像

dacli 不再维护自己的 API 调用代码,而是**直接 dynamic import** web 端源码:

```typescript
// dacli/src/webapi/_loader.ts (v0.11+)
import { visualDev } from 'web/.../api/onlineDev/visualDev.ts'
import { buildFormData } from 'web/.../helper/formUtils.ts'

优势:

  • ✅ 0 复刻 — 不重复实现 web 端的 API 调用逻辑
  • ✅ 0 快照 — 不缓存 web 端 API 定义 (避免过期)
  • ✅ 0 漂移 — JNPF 平台升级时自动跟随

form 子命令 webapi 化清单

子命令 webapi 化 commit 调用 web 函数
form list 9c14cda visualDev.getList()
form info 9c14cda visualDev.getInfo()
form create c98bf2b visualDev.create()
form update 801a204 visualDev.update()
form release 9c14cda visualDev.release()
form delete 9c14cda visualDev.del()
form clone 7bf7762 visualDev.copy()
form export 7bf7762 visualDev.export()
form import e6a56f3 visualDev.importData()
form codegen 938c31d visualDev.codegen()
form validate 9c14cda validateFormData() (buildFormData)
form fixcolumndata 9c14cda fixColumnData() (buildFormData)
form bindflow 9c14cda visualDev.bindFlow()
form selector 5f663eb visualDev.getSelector()
form lint (内置) buildFormData.lint()

AI 使用建议

  • 不要凭"经验"猜 API 路径 — webapi 镜像直接从 web 源码导入,路径 100% 准确
  • 报错时优先查 web 源码 — 真正的错误信息来自 web 端 API 返回
  • 新功能开发前查 visualDev.ts — webapi 已镜像 30 个函数,新功能 80% 已实现

---

## 3. 一般缺陷 (P1 同步)

### 🟡 缺陷 4: `dacli form selector` 使用说明不足

**影响行号**: 30-33

**问题描述**:
- `form selector` 是 v0.11+ P0 新命令 (commit 5f663eb)
- 当前仅 1 行说明 (30-33),缺少:
  - 返回格式详解
  - AI 决策树 (如何选 id)
  - 典型用例

**修改建议** (替换 30-33 行):

```bash
# 功能下拉框 (v0.11+ P0 NEW-CMD) — 创建菜单挂 form / 工作流起始 / select 字段 dataSource 必跑
dacli form selector [--keyword=员工] [--enableFlow=1] [--type=1] [--json]
# 返回: 简化树形 [{id, enCode, fullName, type, webType, ...children}], 已平铺

# AI 决策流程:
# 1. 跑 form selector --keyword=员工 (模糊匹配 name/enCode)
# 2. --json 解析 → 按 type/webType/enableFlow 过滤
# 3. 选 id → menu create --formId=<id> (挂菜单)
# 4. 或 workflow create --formId=<id> (工作流起始节点)

# 典型用例: select 字段从 form 取选项
dacli form selector --enableFlow=1 --type=1 --json | jq '.[] | select(.enableFlow==1)'

🟡 缺陷 5: 缺少 dacli form validate / form fixcolumndata webapi 化说明

影响行号: 588

问题描述:

  • 这两个命令已 webapi 化 (9c14cda)
  • 但 skill 中未提及是 webapi 镜像调用

修改建议 (行 588 后添加):

> **v0.11+ webapi 化**: `form validate` / `form fixcolumndata` 已改用 webapi 镜像 (commit 9c14cda)
> **逻辑内置**: 调用 web 端 `buildFormData.validate()` / `fixColumnData()` 函数

🟡 缺陷 6: 引用未实现的 dacli form e2e-smoke

影响行号: 133, 136-138

问题描述:

  • skill 中引用 dacli form e2e-smoke 命令
  • 该命令不在 form 子命令清单中 (ls /home/ubuntu/ccWorkDir/dacli/src/commands/form/ 无此文件)
  • 引用了不存在的命令会误导 AI

修改建议 (替换 133-138 行):

# ❌ 旧 (skill 当前内容, 引用不存在的命令)
dacli form e2e-smoke --formId=<id> --menuId=<menuId> \
  --fields='{"f_amount":100.50,"f_quantity":5}'

# ✅ 新 (v0.11+ 正确方式)
# 1. 用 dacli form codegen 生成测试脚本 (含 CRUD API)
dacli form codegen <id> --module=myApp --mainClassName=TestForm

# 2. 或用 ssw-test 技能的 Playwright E2E 测试
# 详见 .claude/skills/ssw-test/SKILL.md

🟡 缺陷 7: dacli form clone 端点说明过时

影响行号: 419-423

问题描述:

  • 行 419: 提到 POST /api/visualdev/Base/{id}/Actions/Copy 是 Clone API
  • v0.11+ webapi 化后 (7bf7762),已通过 web 端 visualDev.copy() 调用
  • 端点说明对 AI 帮助有限,应强调 webapi 镜像

修改建议 (替换 419-423 行):

### v0.11+ webapi 化说明

- **走 webapi 镜像** (commit 7bf7762): `visualDev.copy(id, options)` 直接调用 web 端 API
- **不返回新 ID**: 同 Copy API 行为一致,仅返回成功标志
- **AI 拿新 ID**: 通过 `dacli form list` 前后对比,dacli 自动处理 (diff 快照)

🟡 缺陷 8: 缺少 dacli form bindflow / dacli form lint 说明

影响行号: 全文

问题描述:

  • form bindflow (webapi 化, 9c14cda) 完全缺失
  • form lint (内置) 完全缺失
  • 都是 v0.11+ 重要命令

建议新增章节 (放在 §"字段定义" 前):

## 其他 form 子命令 (v0.11+)

### form bindflow <id> <flowId>
绑定工作流到已存在的表单 (commit 9c14cda webapi 化):
```bash
dacli form bindflow <formId> <flowId>    # bind 后需 release
dacli form bindflow <formId> <flowId> --unbind  # 解绑

form lint [--fix]

检查 form schema 完整性 (字段缺失 / 引用错误):

dacli form lint <id>                    # 检查
dacli form lint <id> --fix              # 自动修复 + release
dacli form lint <id> --json             # JSON 输出

---

## 4. 次要缺陷 (P2 检查)

### 🟢 缺陷 9: 缺少数项子命令清单

- `dacli form list` 缺少 `--json` 选项说明 (虽然 webapi 化后默认支持)

### 🟢 缺陷 10: 缺少 v0.11+ 新增的关联命令

- `dacli dict selector` (新增, 可替代 form selector 中字典选择)

---

## 5. 优先级修复清单

### P0 必修 (阻塞 AI 使用)

| 优先级 | 行号 | 问题 | 修复建议 |
|--------|------|------|----------|
| **P0.1** | 309, 371-398, 562, 597-599 | 引用已删除命令 `dacli form msrelation` | 删除 4 处引用,整段移除 §msrelation |
| **P0.2** | 365, 427-429 | 缺少 `dacli form update` 详细说明 | 新增章节 (含主子表注入示例) |
| **P0.3** | 全文 | 缺少 v0.11+ webapi 镜像架构说明 | 新增章节 (§v0.11+ webapi 镜像架构) |

### P1 同步 (提升 AI 效率)

| 优先级 | 行号 | 问题 | 修复建议 |
|--------|------|------|----------|
| **P1.1** | 30-33 | `form selector` 使用说明不足 | 扩展为完整用法 + AI 决策流程 |
| **P1.2** | 588 | `form validate` / `fixcolumndata` 未提 webapi 化 | 加 webapi 化标注 |
| **P1.3** | 419-423 | `form clone` 端点说明过时 | 强调 webapi 镜像 |
| **P1.4** | 133-138 | 引用不存在的 `form e2e-smoke` 命令 | 替换为 codegen + ssw-test |
| **P1.5** | 全文 | 缺少 `form bindflow` / `form lint` 说明 | 新增章节 |

### P2 检查 (可选优化)

| 优先级 | 行号 | 问题 | 修复建议 |
|--------|------|------|----------|
| **P2.1** | 25 | 缺少 `--json` 选项说明 | 加 `--json` 标志 |
| **P2.2** | 全文 | 缺少数项关联命令 | 加 `dict selector` 等 |

---

## 6. 详细修复示例

### 6.1 P0.1 修复示例 (删除 msrelation)

**修改前** (行 371-398):
```markdown
## 🔍 dacli form msrelation <id>(2026-06-08 新增)

> 📦 **新增子命令**:`dacli form msrelation <id>` — 一键查主子表 ER 关系
> **dev-rs.md §11.2 已实现**

**输出**(主子表 + 字段 + 校验 + 外键):

Form 469047177461688709 (人才管理) WebType: 2 | State: 1 | EnCode: rencaiguanli ...


**使用场景**:
- 拿到表单 ID 想看主子表结构(不用 parse 整 JSON)
- AI 自动化:先 `msrelation` 看结构,再 `dm query` 查数据
- 子表命名 = `ct{主表ID+1}`(见 dev-rs.md §2.1)

修改后:

## 🔍 dacli form info <id> --expand-subtable(v0.11+ 推荐)

> **替代已删除的 `form msrelation`**:通过 `--expand-subtable` 标志展开主子表 ER 关系
> **Webapi 化**: ✅ (commit 9c14cda)

**使用方式**:
```bash
dacli form info <id> --expand-subtable

输出: 主子表 + 字段 + 校验 + 外键(同旧 msrelation 格式)

使用场景:

  • 拿到表单 ID 想看主子表结构(不用 parse 整 JSON)
  • AI 自动化:先 --expand-subtable 看结构,再 dm query 查数据
  • 子表命名 = ct{主表ID+1}(见 dev-rs.md §2.1)

### 6.2 P0.2 修复示例 (新增 form update 章节)

**位置**: §"表单克隆" 前 (行 407 前)

**新增内容**:
```markdown
## 🔧 dacli form update <id> (v0.11+ P0 NEW-CMD)

> **Commit**: 801a204 | **Webapi 化**: ✅
> **重要性**: P0 高需求 (CRUD 闭环关键)

### 使用场景
1. **主子表 children 注入** (替代手工编辑 formData)
2. **columnData 字段调整** (避免 form clone + 重配置)
3. **formData 配置项修改** (logicDelete / dataLog 等)

### 主子表 children 注入 (替换 365 行临时方案)
[详见上文 P0.2 建议]

6.3 P0.3 修复示例 (新增 webapi 镜像章节)

位置: §"核心流程" 后 (行 17 后)

新增内容:

## v0.11+ webapi 镜像架构 (重要)

> **2026-06-25 Phase 2 闭环**:form 11 个子命令全部 webapi 化
> **Commits**: 9c14cda → 7bf7762 → 938c31d → e6a56f3 → c98bf2b

[详见上文 P0.3 建议]

7. 审计总结

7.1 关键发现

  1. 3 处严重缺陷 (P0) — 引用已删除命令、缺少 P0 高需求命令、缺少架构说明
  2. 5 处一般缺陷 (P1) — 部分命令说明不足、引用过时、未提及 webapi 化
  3. 2 处次要缺陷 (P2) — 缺少 flag 说明、关联命令

7.2 影响评估

  • P0.1 (msrelation 引用): AI 调用不存在命令 → exit 错误,浪费时间
  • P0.2 (form update 缺失): AI 手工编辑 formData JSON → 易错,且无法批量
  • P0.3 (webapi 架构缺失): AI 不了解架构 → 凭"经验"猜 API 路径,违反 §2.7 web/ 源码优先
  • P1.4 (e2e-smoke 引用): AI 调用不存在命令 → exit 错误

7.3 修复成本

  • P0 修复: 约 2-3 小时 (新增 3 个章节,修改 1 个章节)
  • P1 修复: 约 1-2 小时 (5 处小修改)
  • P2 修复: 约 30 分钟 (2 处补充)

7.4 建议

立即修复 P0 (阻塞 AI 正常使用 form 模块) 同步修复 P1 (在 Phase 3 skill 同步任务中一并处理) 可选修复 P2 (在 Phase 4 历史清理时顺便处理)


报告生成时间: 2026-06-25 审计版本: dacli v0.11+ (38 commits, phase 2 完成) 下次审计建议: Phase 3 skill 同步完成后重新审计 (验证修复效果)