From 052fb32b3c72f29ae5a3f05ac6ce2882f3c19cda Mon Sep 17 00:00:00 2001 From: ssw Date: Sun, 28 Jun 2026 13:15:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(dacli-ts):=20test=20run=20v0.11+=20?= =?UTF-8?q?=E7=9C=9F=E5=AE=9E=E4=B8=9A=E5=8A=A1=E6=95=B0=E6=8D=AE=20CRUD?= =?UTF-8?q?=20=E6=A8=A1=E5=BC=8F=E6=96=87=E6=A1=A3=20(=E9=98=B6=E6=AE=B5?= =?UTF-8?q?=207.2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - references/commands.md §8: 新增 8.1 test run, 11 个 option + 5 真实例子 + 模式对比表 - references/anti-patterns.md AP-12: 'test fixture 不能当业务验证' 反模式 - SKILL.md: test run 段同步更新 (commit 21fd363 配套) - templates/flow-jxcj-rerun-process.md: 流程规范 (撤回 TC-D/TC-E) 为什么: 配套 dacli commit 21fd363, AI 学习材料同步更新, 避免文档落后于源码 Refs: dacli commit 21fd363, MEMORY dacli-test-run-real-data-upgrade-2026-06-28 --- skills/dacli-ts/SKILL.md | 40 ++++++ skills/dacli-ts/references/anti-patterns.md | 57 ++++++++ skills/dacli-ts/references/commands.md | 62 ++++++++- templates/flow-jxcj-rerun-process.md | 139 ++++++++++++++++++++ 4 files changed, 297 insertions(+), 1 deletion(-) create mode 100644 templates/flow-jxcj-rerun-process.md diff --git a/skills/dacli-ts/SKILL.md b/skills/dacli-ts/SKILL.md index 5c43ca3..0f42982 100644 --- a/skills/dacli-ts/SKILL.md +++ b/skills/dacli-ts/SKILL.md @@ -404,6 +404,46 @@ dacli dict typeCreate --fullName="TestDup2" --enCode="tdd10duptestv1" --parentId - B 铁律对应: B1 列表渲染 / B2 表单渲染 / B3 详情渲染 / B4 更新后状态 - Phase B 计划: menu / workflow / di 等模块 +**⭐ v0.11g+ form module 真实渲染契约升级 (2026-06-28, §TC-C 真实业务)**: + +升级前问题: 旧 TC-C 只对比 vue 字段 ⊆ API 字段, PASS 但 relationForm 弹窗可能空, 必填字段缺 vmodel 不验, columnList 缺列不验 → 浏览器实测 "弹窗空 → 外键填不完 → 保存失败" 但旧 TC-C 仍 PASS. + +升级后新增 4 类真实契约校验 (默认全 ON, 都可 `--no-xxx` 关): + +| 校验 | 检查内容 | 失败影响 | +|------|---------|---------| +| **必填字段 vmodel** | formData.fields 中所有 `__config__.required=true` 字段都有 `__vModel__` | FAIL (退出码 1) | +| **relationForm 配置完整性** | 每个 relationForm 三必填: `modelId` (enCode) + `propsValue` (字段名) + `relationField` (显示字段) | FAIL (退出码 1) | +| **relationForm 弹窗数据可达性** | 每个 relationForm 关联表调 `getVisualDevList + getModelList` 验证有 ≥1 条数据 | 默认 **WARN** (不阻断), 加 `--relation-form-data-strict` 改 FAIL | +| **columnList 列配置完整性** | webType≠1 时 columnList ≥1 + 字段名匹配 API 返回 | FAIL (退出码 1) | + +镜像 web 端契约: +- 必填 vmodel: web `FormGenerator.getData()` 控件校验 + `form/_validate.ts:validateFormData` +- relationForm 配置: web `RRelationForm/index.vue` + `form/_validate.ts:validateRelationForm` +- 弹窗数据可达: web `RRelationForm/index.vue` 调 `OnlineDev/{modelId}/List` 分页 +- columnList: web `ColumnDesign.getData()` line 278-282 + +新增选项: +```bash +# 默认 ON: 全开真实契约校验 (弹窗数据空时 WARN, 不阻断) +dacli test render --module=form --formId=X + +# 严格模式: 弹窗数据空也 FAIL (CI 用) +dacli test render --module=form --formId=X --relation-form-data-strict + +# 单独关闭某项 (向后兼容) +dacli test render --module=form --formId=X --no-required-field-check +dacli test render --module=form --formId=X --no-relation-form-data-check +dacli test render --module=form --formId=X --no-column-list-required + +# 验证场景 (jxcj): team 表的 relationForm (jxcj_competition_info) 0 条记录 +# 旧 TC-C: PASS +# 新 TC-C (默认 WARN): ⚠ relationForm 弹窗数据可达性: WARN (0 可达 / 1 空 / 0 错) +# 新 TC-C (--relation-form-data-strict): ✗ FAIL +``` + +⚠️ **TC-C 默认 WARN 的原因**: relationForm 弹窗空常因为"关联表还没数据" (阶段 7.4 跑 TC-A 真实业务数据时会先填关联表), 不应在 TC-C 阻断. 但用 `--relation-form-data-strict` 可在 CI 强约束. + ## 📚 详细文档(按需加载,按用途查 references/) > **🧹 v0.11+ 收纳 (2026-06-27)**: 原 12 个独立技能(form-development / menu-configuration / diff --git a/skills/dacli-ts/references/anti-patterns.md b/skills/dacli-ts/references/anti-patterns.md index 46388e1..6fd19ed 100644 --- a/skills/dacli-ts/references/anti-patterns.md +++ b/skills/dacli-ts/references/anti-patterns.md @@ -509,3 +509,60 @@ dacli form create --ai-json='[{ - 缺一个会导致运行时 popup 弹不出来 / 数据存不进 DB - v0.11e+ (2026-06-28) step machine 已镜像前端校验, AI 一次提交就能看到 3 个 `VS-RELATION-*` 错误码 - 见 [commands.md §1.3 form create step machine 表](commands.md#13-dacli-form-create--v011e-step-machine-严格镜像-prefer--ai-json) + + +--- + +## AP-12. test fixture 不能当业务验证 (2026-06-28 阶段 7.2) + +**反模式**: +```bash +# ❌ 旧 fixture 模式: 形式 PASS 但实际不验业务 +dacli test run --formId=840790355585531909 +# POST 数据: {"f_team_name": "_TEST__", ...} ← 无业务意义 +# 即创即删, 真实数据 0 条 +# 16 张含 relationForm 表 POST 失败因 sample 跳过 +``` + +**正确**: +```bash +# ✅ v0.11+ 真实业务数据模式 (默认 ON, 2026-06-28 升级) +dacli test run --formId=840790355585531909 +# mode=real-data, keep-data=ON (数据保留供 TC-B) +# varchar: "测试值_<语义>_" 字段语义化值 +# relationForm: 关联表前 N 条拉真实 ID (而非跳过) +# 跨表 join 校验 + 业务规则校验自动可用 + +# ✅ 自定义真实业务数据 +dacli test run --formId=840790355585531909 \ + --real-fields='{"f_team_name":"数据先锋队","f_team_code":"TEAM001"}' + +# ✅ 旧 fixture 模式仍然可用 (向后兼容) +dacli test run --formId=840790355585531909 --no-real-data --no-keep-data +``` + +**为什么**: +- **fixture 模式盲点**: `_TEST_` 后缀污染业务数据, 即创即删真实数据 0 条, 浏览器层 TC-B 无数据可验 +- **relationForm 跳过**: 旧 fixture 跳过 relationForm 字段 → POST "Field cannot be empty" 失败但不告诉你 +- **无跨表 join 校验**: FK 字段瞎填, 不验证关联表记录存在 +- **无业务规则校验**: 团队人数 / 日期范围 / 跨表 join 都没跑 + +**真实业务验证场景** (jxcj 实战): +```bash +# 创建 competition_info 真实大赛 +dacli test run --formId=840792667196489733 \ + --real-fields='{"f_competition_name":"测试大赛","f_start_time":1748736000000,"f_end_time":1780272000000,"f_state":1}' + +# 验证 team FK → competition_info (跨表 join) +dacli test run --formId=840790355585531909 \ + --real-fields='{"f_competition_id":"<真实 competition_id>"}' \ + --join-check --join-rules='[{"fkField":"f_competition_id","targetEnCode":"competition_info","checkField":"f_competition_name"}]' + +# 验证团队人数下限 +dacli test run --formId=840790355585531909 \ + --business-rules='[{"field":"f_team_size","rule":">=3","msg":"团队人数下限 3 人"}]' +``` + +**why 升级** (v0.11+ 阶段 7.2, 2026-06-28): +- 用户原话: "TC-A TC-C 应该直接完成数据层面真实跑通验证, 如果不行就修改他们, 不要再来 TC-D TC-E 了" +- 撤回 TC-D / TC-E workaround 思路, 直接升级 TC-A 到真实业务数据 CRUD diff --git a/skills/dacli-ts/references/commands.md b/skills/dacli-ts/references/commands.md index 2fdbc8d..194d8a4 100644 --- a/skills/dacli-ts/references/commands.md +++ b/skills/dacli-ts/references/commands.md @@ -768,7 +768,67 @@ openapiSize : 1099520 bytes (1073.8 KB) --- -## 8. AI 提示 +## 8. test (测试用例 — form API CRUD + 真实业务数据模式) — v0.11+ (2026-06-28 升级) + +### 8.1 `dacli test run --formId=` (v0.11+ 阶段 7.2: 真实业务数据 CRUD) + +| 参数 | 必填 | 默认 | 说明 | +|------|------|------|------| +| `--formId ` | ✅ | - | 目标 form id | +| `--output ` | - | stdout | 输出报告文件路径 (Markdown) | +| `--keep-data / --no-keep-data` | - | **keep** | 保留 / 删除测试数据 (默认 ON 留数据供 TC-B 浏览器验证) | +| `--real-data / --no-real-data` | - | **real-data** | 真实业务数据模式 / test fixture 模式 (默认 real-data) | +| `--real-fields ` | - | - | 自定义真实业务数据 JSON (优先级最高, 例: `'{"f_team_name":"数据先锋队"}'`) | +| `--relation-form-lookup / --no-relation-form-lookup` | - | **ON** | relationForm 自动 lookup 关联表真实 ID (而非跳过) | +| `--relation-form-sample ` | - | `1` | 关联表拉前 N 条 (最大 5) | +| `--join-check` | - | OFF | POST 后跑跨表 join 校验 (FK → 关联表) | +| `--join-rules ` | - | - | join 规则 (例: `'[{"fkField":"f_team_id","targetEnCode":"jxcj_team","checkField":"f_team_name"}]'`) | +| `--business-rules ` | - | - | 业务规则 (例: `'[{"field":"f_team_size","rule":">=3","msg":"团队人数下限 3 人"}]'`) | +| `--json` | - | OFF | 原始 JSON 输出 | + +**7 步流程**: 拉 schema → POST create → GET info → PUT update → 跨表 join → 业务规则 → DELETE + +**示例** (5 个真实例子): + +```bash +# 1. 默认: 真实业务数据模式 + 保留数据 +dacli test run --formId=840790355585531909 + +# 2. 自定义真实业务数据 +dacli test run --formId=840790355585531909 \ + --real-fields='{"f_team_name":"数据先锋队","f_team_code":"TEAM001"}' + +# 3. 跨表 join 校验 (验证 FK 字段能查到关联表记录) +dacli test run --formId=840790907757264901 \ + --join-check \ + --join-rules='[{"fkField":"f_team_id","targetEnCode":"team","checkField":"f_team_name"}]' + +# 4. 业务规则校验 +dacli test run --formId=797437045977907781 \ + --business-rules='[{"field":"inputNumberField564350","rule":">=100","msg":"数值必须 >= 100"}]' + +# 5. 旧 fixture 模式 (向后兼容 v0.11e) +dacli test run --formId=797437045977907781 --no-real-data --no-keep-data +``` + +**模式对比** (test fixture vs real-data): + +| 维度 | test fixture (`--no-real-data`) | real-data (`--real-data` 默认) | +|------|---------------------------------|--------------------------------| +| varchar 值 | `t_f_team_name` 短前缀 | `测试值_teamname_xxxx` 语义化 | +| 时间戳 | `_TEST_` 后缀 | 无后缀 (干净业务数据) | +| relationForm | 跳过 (BS-49/50 复发) | 关联表前 N 条拉真实 ID | +| 数据保留 | `--no-keep-data` 默认 (即创即删) | `--keep-data` 默认 ON (供 TC-B) | +| 适用场景 | 回归冒烟 (5s 完成) | 真实业务验证 (供浏览器层验证) | + +**why 升级** (2026-06-28 阶段 7.2): +- ❌ 旧 fixture 模式: 形式 PASS 实际不验业务 (16 张含 relationForm 表 POST 失败因 sample 跳过, 即创即删真实数据 0 条) +- ✅ 新 real-data 模式: 字段语义化 + 关联表真实 ID + 跨表 join 校验 + 业务规则校验 +- ✅ 数据保留默认 ON: 供浏览器层 TC-B 端到端验证 + +--- + +## 9. AI 提示 - **每个命令都支持 `--help`**: `dacli form create --help` - **每个命令支持 `--ai-help`**: 输出可喂给 LLM 的 markdown diff --git a/templates/flow-jxcj-rerun-process.md b/templates/flow-jxcj-rerun-process.md new file mode 100644 index 0000000..57f513a --- /dev/null +++ b/templates/flow-jxcj-rerun-process.md @@ -0,0 +1,139 @@ +# jxcj 重建流程规范 (派子代理四步法纪律, 2026-06-28 复盘 v2) + +> **本文档是 /ssw-h5dev-flow 的扩展纪律**, 针对 jxcj 11 模块 / 28 表规模, 解决"TC-A/TC-C 形式 PASS 但实际不可用"的盲点. + +## ⚠️ 关键纠偏 (2026-06-28 v2) + +**❌ 旧思路 (已撤回)**: 发明 TC-D / TC-E 维度解决"TC-A/TC-C 形式通过问题" +**✅ 新思路**: 直接升级 TC-A / TC-C 到**数据层面真实跑通**, 不行就改这两个命令本身 + +理由: TC-D / TC-E 是绕过 dacli 限制的 workaround, 增加概念负担. 用户原话: "如果不行就修改他们, 不要再来 TC-D TC-E 了". + +## 一、TC-A 升级: 真实业务数据 CRUD + +### 现状 (test fixture 模式, 不验业务) +```bash +dacli test run --formId=X +# POST 数据: {"f_team_name": "_TEST__", ...} ← 无业务意义 +# 即创即删, 真实数据 0 条 +# 跨表 FK 校验: 跳过 +# 业务规则校验: 跳过 +``` + +### 升级目标 +1. **真实业务数据**: 不用 timestamp 后缀, 用真实业务值 +2. **留数据不删**: 数据保留供浏览器层 TC-B 用 + 跨表验证 +3. **跨表 join 校验**: team 含 competition_id 能查到 competition_info 记录 +4. **业务规则校验**: 团队人数 3-5 人 / 截止日期 > 起始日期 等 +5. **依赖链完整跑通**: 从主表 (competition_info) 沿依赖链跑到末梢 (final_ranking) + +### 修改路径 (派子代理改 dacli test run) + +`dacli/src/commands/test/run.ts` 当前逻辑: +- `buildSampleData()` 加 timestamp 后缀 +- 跑完立即 DELETE 清理 + +升级方案: +- 加 `--keepData` 选项 (或默认改为 keep, 留数据供浏览器 TC-B 用) +- 加 `--realData --fields='{f_team_name:"数据先锋队",...}'` 选项让用户传真实业务值 +- 加 `--joinCheck --fkField=f_competition_id --targetForm=enCode` 选项做跨表 join 校验 +- 加 `--businessRule='team_size>=3 && team_size<=5'` 选项做业务规则校验 +- 默认行为: 跑完给一份"清理建议" (curl DELETE 列出), 让用户决定保留/删除 + +### 验证场景 (jxcj) +1. competition_info POST 1 条真实大赛 (2026 江财数据要素大赛) +2. topic_direction POST 6 条赛题方向 (金融风控/医疗健康/智慧城市/...) +3. team POST 1 条团队 (数据先锋队) 含 f_competition_id +4. **跨表 join**: GET team 含 competition_info 完整数据 (relationForm 弹窗能查到) +5. team_member POST 3 条成员 (队长/队员1/队员2) +6. **业务规则**: team_member count = 3 ≥ 3 ✅ (团队人数下限) +7. develop_project POST 1 条含 team_id + direction_id +8. review_assignment + review_score + final_ranking 完整链路 + +## 二、TC-C 升级: 真实渲染契约 (含弹窗数据可达性) + +### 现状 (字段对齐模式, 不验渲染可用) +```bash +dacli test render --module=form --formId=X +# 对比 vue 字段 ⊆ API 字段 +# 不验 relationForm 弹窗数据是否够 +# 不验字段值是否合理 +``` + +### 升级目标 +1. **弹窗数据可达**: 关联表 (team, data_resource, etc.) 必须有真实数据 +2. **relationForm 配置完整**: modelId/propsValue/relationField 必填 +3. **必填字段渲染完整**: 所有 required 字段在 formData.fields 都有 +4. **列配置正确**: columnList 字段与 API 字段对齐 +5. **PC + 移动端**: 双端 schema 渲染契约都过 + +### 修改路径 (派子代理改 dacli test render) + +`dacli/src/commands/test/render.ts` 当前逻辑 (430 行, 已镜像 web 端): +- 解析 web 端 .vue 文件 (BasicColumn / useForm) +- 对比 vue 渲染字段 ⊆ API 字段 + +升级方案: +- 加 `--relationFormDataCheck` 选项: 对每个 relationForm 字段, 验证关联表有 ≥ 1 条数据 +- 加 `--requiredCheck` 选项: 验证 formData.fields 中所有 required 字段都有控件配置 +- 加 `--columnListRequired` 选项: 验证 columnList 至少包含 1 个字段 + 字段名匹配 API +- 默认行为: 弹窗数据不足时返回 "WARN: relationForm X 关联表 0 条, 浏览器弹窗空", 不只 PASS + +### 验证场景 (jxcj) +- develop_project 含 f_team_id (relationForm → team): **如果 team 表 0 条, TC-C 应 FAIL/WARN** +- 当前: team 表 0 条, 旧 TC-C 仍 PASS ← 这就是问题 + +## 三、派子代理四步法实施 (改 dacli test run + test render) + +### 子代理任务清单 + +#### 子代理 1: 升级 dacli test run (TC-A 真实业务) + +派单 prompt 必含: +1. 读 `dacli/src/commands/test/run.ts` 完整源码 +2. 读 `dacli/src/commands/test/generate.ts` 完整源码 (buildSampleData 逻辑) +3. 修改方案: + - 默认改为 keepData (不删) + 加 `--deleteAfter` 选项 + - 加 `--realData --fields='{...}'` 选项 + - 加 `--joinCheck` 选项做跨表 join + - 加 `--businessRule` 选项做业务规则校验 +4. developSystem / workSystem 跑回归: 旧 test 模式仍可用, 新真实数据模式跑通 + +#### 子代理 2: 升级 dacli test render (TC-C 真实渲染) + +派单 prompt 必含: +1. 读 `dacli/src/commands/test/render.ts` 完整源码 +2. 读 web 端 FormGenerator + ColumnDesign 渲染契约 +3. 修改方案: + - 加 `--relationFormDataCheck` 选项 + - 加 `--requiredCheck` 选项 + - 默认行为: 弹窗数据不足返回 WARN (不只 PASS) +4. developSystem / workSystem 跑回归 + +## 四、jxcj 待办 (用升级后的 TC-A/TC-C 跑通) + +1. **派子代理升级 dacli test run + test render** (P0) +2. **跑 TC-A 真实业务数据**: 11 条主链 CRUD + 跨表 join + 业务规则 +3. **跑 TC-C 真实渲染**: 28 张 form 全部跑 (升级后 relationForm 弹窗数据可达性应 FAIL for 16 张表, 因为关联表空 → 这才是真实情况) +4. **如发现 schema 问题**: 派子代理修 form schema (走 `dacli form update --fields`) +5. **如发现 enCode/category 问题**: 用阶段 7.1 修复后的 dacli (commit 634ae10) 拦截新 form, 老 form 跑 `dacli form update --enCode=Y --category=Z` +6. **跑 TC-B 浏览器层**: 真实数据 + 真实渲染都 PASS 后, 用 playwright 验证 UI + +## 五、关键纪律 (强制) + +- ❌ **禁止** 发明 TC-D / TC-E / TC-F 等新维度 (撤回) +- ❌ **禁止** 把 test fixture (timestamp 后缀 + 即创即删) 当作"业务可用" +- ❌ **禁止** 跳过跨表 join 校验 +- ❌ **禁止** 浏览器层 TC-B 跳过 (除非业务简单且 TC-A + TC-C 全 PASS) +- ✅ **必须** 升级 TC-A 到真实业务数据 CRUD +- ✅ **必须** 升级 TC-C 到真实渲染契约 (含弹窗数据可达) +- ✅ **必须** 用升级后的 TC-A/TC-C 跑 jxcj, 失败就修 schema, 不绕过 + +## 六、文档索引 + +- 本文: `/home/ubuntu/ccWorkDir/.claude/templates/flow-jxcj-rerun-process.md` (v2, 已撤回 TC-D/TC-E) +- ssw-h5dev-flow 原始: `/home/ubuntu/ccWorkDir/.claude/CLAUDE.md` §阶段 5 +- dacli 严格校验镜像: `/home/ubuntu/ccWorkDir/dacli/src/commands/form/_validate.ts` (commit 634ae10) +- dacli test run 待升级: `/home/ubuntu/ccWorkDir/dacli/src/commands/test/run.ts` +- dacli test render 待升级: `/home/ubuntu/ccWorkDir/dacli/src/commands/test/render.ts` +- jxcj 当前状态: `/home/ubuntu/ccWorkDir/docs/jxcj/{plan,design,testcase,summary,debug}.html` \ No newline at end of file