docs(dacli-ts): test run v0.11+ 真实业务数据 CRUD 模式文档 (阶段 7.2)

- 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
This commit is contained in:
ssw committed 2026-06-28 13:15:26 +08:00
1 parent d38a68b865
commit 052fb32b3c
4 files changed
+297 -1

No files matched your search

+40
View File
@@ -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 /
@@ -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_<timestamp>_", ...} ← 无业务意义
# 即创即删, 真实数据 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: "测试值_<语义>_<random>" 字段语义化值
# 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_<timestamp>` 后缀污染业务数据, 即创即删真实数据 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
+61 -1
View File
@@ -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=<ID>` (v0.11+ 阶段 7.2: 真实业务数据 CRUD)
| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `--formId <id>` | ✅ | - | 目标 form id |
| `--output <file>` | - | 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>` | - | - | 自定义真实业务数据 JSON (优先级最高, 例: `'{"f_team_name":"数据先锋队"}'`) |
| `--relation-form-lookup / --no-relation-form-lookup` | - | **ON** | relationForm 自动 lookup 关联表真实 ID (而非跳过) |
| `--relation-form-sample <n>` | - | `1` | 关联表拉前 N 条 (最大 5) |
| `--join-check` | - | OFF | POST 后跑跨表 join 校验 (FK → 关联表) |
| `--join-rules <json>` | - | - | join 规则 (例: `'[{"fkField":"f_team_id","targetEnCode":"jxcj_team","checkField":"f_team_name"}]'`) |
| `--business-rules <json>` | - | - | 业务规则 (例: `'[{"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_<timestamp>` 后缀 | 无后缀 (干净业务数据) |
| 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
+139
View File
@@ -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_<timestamp>_", ...} ← 无业务意义
# 即创即删, 真实数据 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`