# 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 `,包括完整的章节 (371-398 行) - 该命令在 v0.11+ Phase 2 重构中已**删除** - 应替换为 `dacli form info --expand-subtable` **修改建议**: ```bash # ❌ 旧 (skill 当前内容) dacli form msrelation # ✅ 新 (v0.11+) dacli form info --expand-subtable ``` **具体替换位置**: 1. **行 309**: 删除 `> 用 dacli form msrelation 一键查主子表名+ER关系` 2. **行 371-398**: **整段删除** (## 🔍 dacli form msrelation (2026-06-08 新增)章节) 3. **行 562**: 删除 `dacli form msrelation` 引用 4. **行 597-599**: 替换为: ```bash 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 参数 ``` **新增章节建议** (应添加到 §"表单克隆" 前): ```markdown ## 🔧 dacli form update (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 --fields='[{"field":"f_new","fieldName":"新字段",...}]' # 更新主子表 children (替换指定 vModel 的子表字段) dacli form update --subtable='orderItems' --children='[...]' # 更新 formData 配置项 (logicDelete / dataLog 等) dacli form update --formData='{"logicalDelete":true}' # 更新 columnData (列表列配置) dacli form update --columnData='{...}' # 干跑 (只打印 diff, 不提交) dacli form update --fields='[...]' --dry-run ``` ### 主子表注入示例 (替换 365 行临时方案) ```bash # Step 1: 建主子表 (dm create) dacli dm create --table=ct_order_items --tableName="订单明细" \ --dbLinkId= --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 # 看现有 schema # Step 3: 注入主子表 children (替换手工编辑) dacli form update --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 ``` ### 注意事项 - **必传 --release**: update 修改 schema 后必须调 release,否则前端拿到旧 schema - **字段冲突保护**: update 会校验 fields 冲突,避免覆盖系统字段 (f_id / f_tenant_id / f_version) - **主子表命名**: 子表名 = `ct{主表ID+1}` (见 §"主子表命名规则") - **列数限制**: relationForm columnOptions ≤ 5 列 (见 §"relationForm 规范") ### 与其他命令配合 ```bash # 完整 CRUD 闭环 dacli form create --fullName=X --enCode=Y --fields='[...]' --autoRelease dacli form update --fields='[{...新字段...}]' # 增量改 dacli form release # 必须重新发布 dacli form info --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= (挂菜单) # 4. 或 workflow create --formId= (工作流起始节点) # 典型用例: 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 后添加): ```markdown > **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 行): ```bash # ❌ 旧 (skill 当前内容, 引用不存在的命令) dacli form e2e-smoke --formId= --menuId= \ --fields='{"f_amount":100.50,"f_quantity":5}' # ✅ 新 (v0.11+ 正确方式) # 1. 用 dacli form codegen 生成测试脚本 (含 CRUD API) dacli form codegen --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 行): ```markdown ### 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+ 重要命令 **建议新增章节** (放在 §"字段定义" 前): ```markdown ## 其他 form 子命令 (v0.11+) ### form bindflow 绑定工作流到已存在的表单 (commit 9c14cda webapi 化): ```bash dacli form bindflow # bind 后需 release dacli form bindflow --unbind # 解绑 ``` ### form lint [--fix] 检查 form schema 完整性 (字段缺失 / 引用错误): ```bash dacli form lint # 检查 dacli form lint --fix # 自动修复 + release dacli form lint --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 (2026-06-08 新增) > 📦 **新增子命令**:`dacli form msrelation ` — 一键查主子表 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) ``` **修改后**: ```markdown ## 🔍 dacli form info --expand-subtable(v0.11+ 推荐) > **替代已删除的 `form msrelation`**:通过 `--expand-subtable` 标志展开主子表 ER 关系 > **Webapi 化**: ✅ (commit 9c14cda) **使用方式**: ```bash dacli form info --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 (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 后) **新增内容**: ```markdown ## 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 同步完成后重新审计 (验证修复效果)