Files
dacli/docs/cmd-review/v0.13-webapi-form-workflow-refactor.md
T
sswandClaude 9d390dd8e0 docs(bigscreen): v0.14 端点修正 + 完整构造大屏文档 + 36 组件 metadata
## 文档更新
- docs/cmd-review/bigscreen.md: 加 v0.14 章节 (端点修正 30000 jnpf-visualdata, webapi 镜像, construct 命令 22 options, 7 步流程)
- docs/cmd-review/bigscreen-components.md: 新建, 36 组件 metadata (prop/类型/dataType 推荐/option keys/分类列表)
- docs/cmd-review/v0.14-webapi-rollout-plan.md: §2.1 端点修正 (30000 不是 32000), §2.5 webapi/role.ts 是 loadRole (webapi/permission.ts 是 loadOrg)
- docs/cmd-review/v0.13-webapi-form-workflow-refactor.md: §8.1 端点修正 + web 真实 url 来源

## 端到端验证 (testspace, 2026-07-01)
- 5 组件大屏构造 (bar/text/map/video/table, dataType=0): ✓ PASS
- --from-json 路径 (2 组件): ✓ PASS
- --validate-only 路径: ✓ PASS
- TC-C dacli test render --module=bigscreen (4 关卡 list/form/必填/schema): ✓ PASS
- TC-C dacli test render --module=bigscreen --id=X (5 关卡 + 单条 schema): ✓ PASS
- dataType=1 缺 url 校验 (5 项失败阻断): ✓ PASS

## 端点修正
- 错误: /api/visual/* → 32000 jnpf-datareport-univer (报表)
- 正确: /api/visual/* → 30000 jnpf-visualdata (大屏独立微服务)
- web 端 public/config.js 设 window.$website.url = '/api/blade-visual', nginx 代理转发

Co-Authored-By: Claude <[email protected]>
2026-07-01 17:27:48 +08:00

26 KiB

v0.13+ BS-新28/29 webapi 改造记录 (form/workflow, 2026-07-01)

背景: 用户在 form/workflow 反复报 "drag 配置后 launch 异常" 类 bug. 根因分析发现 dacli 自写逻辑 (LLM prompt, BPMN 解析, field 手动映射) 与 web 端 JNPF 行为漂移. 方法: 全删自写, 走 webapi 镜像 (dacli/src/webapi/*) + web buildFormData (webapi 镜像) + NCPF backend AI (不重复造 LLM prompt). 成果: form/workflow 端到端可用, 删 850+ 行自写逻辑, 跟 web 浏览器 100% 一致.

1. 改造范围

模块 文件 改造点
form dacli/src/commands/form/_ai.ts 删 490 行 (callDirectAi* / parseAi* / LLM HTTP 客户端)
form dacli/src/commands/form/_ai_prompts.ts 整个文件删 (76 行, 自写 LLM prompt 必与 NCPF backend 漂移)
form dacli/src/commands/form/create.ts 删 --ai-json 块 (290 行) + --ai 路径 dead code + aiJsonTables 启发式
workflow dacli/src/commands/workflow/_webapi_helpers.ts 新建 (defaultGlobalForm 模板 + parseFlowXml + buildFlowNodes)
workflow dacli/src/commands/workflow/create.ts 6 步 webapi 路径 (getAiInfo → create → getVersionList → buildFlowNodes → save type=1)

2. form --ai webapi 透传路径 (v0.13+)

dacli form create --ai "<描述>"
  ↓
callAiForm()                [_ai.ts:78, NCPF backend 透传]
  ↓ POST /api/visualdev/ai/form
NCPF backend (jnpf VisualAiController.form)
  ↓ 调 LLM (MiniMax abab6.5s-chat, 2026-07-01 base_ai 表配)
NCPF backend 构造 VisualAiModel (fullName/enCode/aiModelList)
  ↓ 返回
web buildFormData (webapi 镜像 _buildformdata.ts)
  ↓ 构造 50+ formConf keys (formId/renderKey/isSubTable/options 全部注入)
B-15 fix: formData.fields → columnList 自动生成
  ↓
loadVisualDev.create (webapi 镜像 visualDev.ts)
  ↓ POST /api/visualdev/Base
loadVisualDev.release (webapi 镜像)
  ↓ POST .../Actions/Release  (type=1 = 真正发布, 不是 UpDownShelf 状态切换)
✅ form state=1, 可用

3. workflow --ai webapi 6 步路径 (v0.12+)

dacli workflow create --ai "<描述>"
  ↓
[step 1/6] callAiWorkflow()  → NCPF backend /api/workflow/ai  (LLM 返 flowXml)
[step 2/6] POST /workflow/template  (空 flowNodes, 跟 web AiCreateModal 一致)
[step 3/6] GET /workflow/template/Version/{id}  → versionId (flowId)
[step 4/6] buildFlowNodes(flowXml, formId)  → 镜像 web FlowProcess.getData()
                                                defaultGlobalForm 模板 + 解析节点 + start.formId
[step 5/6] POST /workflow/template/Save  type=1  (真正发布+部署, 不是 UpDownShelf)
                                                template.flowId + flowableId
[step 6/6] 验证 status + enabledMark
✅ workflow enabledMark=1, status=1, flowId 可直接 launch

4. autoDeriveCategory webapi 整合 (v0.13+)

form create 无 --category → autoDeriveCategoryFromBusinessType(c, appCode)
  ↓ 1. 查 ~/.dacli-token/category-cache.json  (cache 命中直接返)
  ↓ 2. loadDict.getDictionaryAll()  (webapi 镜像 web baseStore.getDictionaryAll)
        GET /api/system/DictionaryData/All
  ↓ 3. filter(d => d.enCode === 'businessType')  (web baseStore.getDictionaryData 同样的逻辑)
  ↓ 4. AI 多策略匹配 (APP_CODE_HINTS / KEYWORD_HINTS / fullName 子串)
  ↓ 5. 写 cache
✅ 返回 { id, name } 供后续 create 用

改进: 旧版 hardcode BUSINESS_TYPE_ID = '306427078100678661' + 调 id-based 端点 (跨 NCPF 版本不兼容); 新版用 enCode 查 (跨版本稳).

5. 删除的自写逻辑 (drift 源)

类别 删除内容 行数 漂移风险
LLM prompt GEN_MODEL_QUESTION, GEN_FLOW_QUESTION (自写) 76 NCPF backend 升级 prompt, dacli 不跟 → 响应格式错
LLM HTTP callOpenAi, callAnthropic (OpenAI/Anthropic 客户端) ~50 与 NCPF backend com.unfbx.chatgpt 实现漂移
LLM 配置 hasDirectAiConfig, readDirectAiConfig (env 读取) ~20 双源 (dacli + NCPF backend) 配置, 易冲突
LLM 解析 parseAiFormText, parseAiFlowText (LLM 响应 → AiFormModel 转换) ~250 解析逻辑跟 NCPF backend 内部 FlowXmlUtil 漂移
BPMN 解析 extractFlowNodesFromBpmn (--ai-json 路径) ~30 跟 web FlowProcess 解析不一致, 丢 inclusion 节点
field 映射 dead code: aiModelList[0].fields 强制 jnpfKey='input' ~10 强制降级丢 datePicker/select/relationForm
relationForm 启发式 autoDetectAndInjectRelationForm, injectRelationForm (~80 行) ~80 web 端不这么干, dacli 自创启发式 → 漏判误判
子表注入 constructTable + 主子表关联 (~30 行) ~30 web 端走 buildFormData.tables, dacli 另写一套
columns 启发式 旧 columnList 派生 (只对 --tables 路径) ~30 漏 B-15: --ai/--ai-json 路径也该派生
总计 ~580

6. 代码瘦身统计

文件 旧 → 新 Δ
form/_ai.ts 608 → 118 -490 (-81%)
form/_ai_prompts.ts 76 → 0 (删) -76 (-100%)
form/create.ts 1424 → 1117 -307 (-22%)
workflow/_webapi_helpers.ts 0 → 187 (新建) +187
workflow/create.ts 347 → 466 (重写) +119
总计 2455 → 1888 -567 (-23%)

净减 567 行 (-23%), 同时消除了所有 LLM prompt / response parser / 启发式逻辑.

7. 验证 (2026-07-01 端到端)

场景 状态 证据
dacli form create --ai "..." ✅ 创建+发布, form state=1, 可用
dacli form create --ai-field "..." ✅ 打印 AI 建议, 不建表单
dacli workflow create --ai "..." ✅ 6 步 webapi 路径, flowId 可 launch
用户 LC20260701000003 流程 ✅ web AI 创建的流程, 含 8 节点 (含 global)
Bug 3 (flow launch NPE) ✅ 修复 (defaultGlobalForm 注入)
Bug 4 (form list 报 deleted) 部分 relationForm 仍用 enCode, 后续要 --startFormId 自动 enCode→f_id
Bug 5 (portal list 空白) ❌ portal 的 category 过滤未审计, 见 8 节

8. 待审计 (其他模块同样漂移风险)

模块 当前状态 建议
bigscreen 大屏 web 端在独立子项目 jnpf/前端/jnpf-web-datascreen-vue3/, 完整 API client 是 src/api/visual.js (list/copy/detail/save/update/remove/getCategory/uploadImg/updateComponent). /api/extend/BigData 是 JNPF "大数据测试" 端点 (错), /api/blade-visual/visual/* 是后端独立微服务, 主 webapp dataV.ts 只镜像了 getDataVSelector (Selector dropdown), 不完整. 走 webapi/visualdata.ts 或 webapi/datascreen.ts (两者都已镜像 jnpf-web-datascreen-vue3/src/api/visual.js, 走 /api/visual/* nginx 代理 30000 jnpf-visualdata 微服务 (不是 32000 jnpf-datareport-univer, 那是报表微服务, 大屏有自己独立的 jnpf-visualdata 微服务). web 端 public/config.js 设 window.$website.url = '/api/blade-visual', nginx 代理转发到 30000. systemId 自动过滤. 不要 "镜像 web/.../api/onlineDev/dataV.ts" — 那违反 webapi 镜像原则 (dataV.ts 只是 Selector, 镜像它再手动构造数据调后端 = 自己拼接数据接后端 API, 绕开前端成熟能力). 不要 "镜像 /api/blade-visual/visual/*" — 那不是 web 端, 是后端 controller, 镜像了还是直调, 等于自写.
report 未审计 待检查是否有 LLM prompt / 自写解析
portal Bug 5 提到 category 字典过滤 silently drop, 类似 form 旧版问题 待 webapi 化 + B-15 类似 fix (从 formData.fields 推 list)
print 未审计 待检查
di (数据接口) 未审计 待检查
permission 未审计 待检查 web 端角色/权限管理 API 模式

8.1 bigscreen 镜像源选择 (用户 2026-07-01 修正)

错误路线 A (审计中已发现并禁用): "镜像 web/apps/jnpf-web-apps-main/src/api/onlineDev/dataV.ts"

  • 该文件只有 getDataVSelector() (下拉框), 1 个端点 (/api/blade-visual/visual/Selector)
  • 镜像后还要 dacli 手动写 5+ 其他端点 (list/detail/save/update/remove/copy) — 等于自写, 必漂移

错误路线 B (审计中已发现并禁用): "用 jnpf-visualdata/VisualController.java 反推后端端点, 然后 dacli 直调 /api/blade-visual/visual/*"

  • 是后端 controller, 不是 web 端
  • 镜像了还是 dacli 自写, 没碰前端页面能力, 完全违反 webapi 镜像原则

正确路线 (v0.13+ 已落地部分, 2.1 节有完整推进表):

  • 镜像源: jnpf/前端/jnpf-web-datascreen-vue3/src/api/visual.js (大屏 web 端完整 API client, 8 个函数)
  • 镜像器: dacli/src/webapi/visualdata.ts (v0.11+ 已建) 或 dacli/src/webapi/datascreen.ts (v0.13+ 已建, 备 shim 方案)
  • 端点: /api/visual/list /api/visual/detail /api/visual/save /api/visual/update /api/visual/remove /api/visual/copy /api/visual/put-file/:type /api/category/list
  • nginx 代理: /api/visual/* → 30000 jnpf-visualdata 微服务 (大屏独立微服务, 不是 32000 jnpf-datareport-univer 报表微服务). web 端 public/config.js 设 window.$website.url = '/api/blade-visual', nginx 代理转发.
  • 页面能力: src/page/list/index.vue (list 列表 + 创建/编辑/删除/复制对话框), src/page/setup/ (设计器), src/page/group/ (分类管理) — 不在 dacli 命令化范围内 (设计器 drag-drop 复杂, CLAUDE.md 禁止命令化)
  • 命令状态: create 已用 webapi/datascreen.ts (✅ 正确); list/info/release 仍用 webapi/bigscreen.ts (❌ 错误, 见 2.1 推进)

8.2 bigscreen 设计器 drag-drop 构造方法 (用户 2026-07-01 强要求: 不止空壳)

用户强要求: 设计器 drag-drop 复杂, 但要找到构造方法/验证方法, 能够通过命令+镜像webapi来构造大屏, 而不仅仅是建一个空壳. 不能因为复杂就逃避 (CLAUDE.md 原则: 命令化收益低 ≠ 不能做).

8.2.1 镜像源 (3 层数据)

层 源文件 用途 镜像到
基础配置 (config) jnpf-web-datascreen-vue3/src/option/config.js:35-72 大屏基础设置 (width/height/screen/backgroundImage/theme/mark/styles/gradeShow/group/glob/filters/style/before/overflow) webapi/datascreen.ts 新增 getBaseConfig() 或 dacli bigscreen construct --template=base
组件默认选项 (38 个) jnpf-web-datascreen-vue3/src/option/components/*.vue bar/line/pie/text/map/video/swiper/iframe/table 等每种组件的默认 option 对象 (从 bar.vue text.vue 看到结构: {category, barWidth, barRadius, ...}) webapi/datascreen.ts 新增 getComponentDefaults(prop)
组件列表 (nav) jnpf-web-datascreen-vue3/src/page/build.vue:705-709 + mixins/index.js:18-36 已放置的组件数组, 每项: {index, name, display, lock, group, option, component: {prop}, data: {dataType, value, url, sql, ...}, children?} 用户/dacli 构造, 走 loadVisualData.updateObj

8.2.2 Save 数据结构 (权威源: header.vue:200-211)

// 大屏设计器 "保存" 按钮实际发的请求
const formdata = {
  visual: {
    id: this.contain.visual.id,
    backgroundUrl: url || this.contain.visual.backgroundUrl  // 缩略图 (exportImg 截图后上传)
  },
  config: {
    id: this.contain.obj.config.id,
    visualId: this.contain.visual.id,
    detail: JSON.stringify(this.contain.config),    // ← 基础配置对象 (来自 option/config.js)
    component: JSON.stringify(this.contain.nav),     // ← 组件列表数组
  }
}
updateComponent(formdata)  // POST /visual/update (走 webapi/visualdata.updateObj)

8.2.3 校验方法 (镜像 step machine, 参照 form 的 buildFormData 模式)

web 端校验来源 (build.vue):

校验 位置 用途
validProp(name) build.vue:1040-1042 检查 active 组件是否在某分类 (titleList/barList/labelList/tipList/legendList/colorList/positionList/labelFormatterList/dataList/mappingList/echartList) 里 — 决定属性编辑面板显示哪些分组
isStatic/isApi/isSql/isWs/isRecord/isPublic/isMqtt/isNode build.vue:666-689 dataType 0-7, 决定数据配置面板显示哪些字段
isFolder build.vue:690-692 active 组件有 children 字段, 是文件夹 (轮播)
configData mixins/index.js:35 ['header', 'query', 'before', 'style'] — 这 4 个是 config (大屏) 而非 activeObj (组件) 的字段
setGlobParams(val) mixins/index.js:114-126 把 config.style 注入到 <style>, 解析 config.query/header/before/style 字符串为函数 (用 getFunction), 注入到 window.$glob

dacli 镜像:

  • dacli bigscreen construct --prop=bar --validate → 镜像 validProp 给 AI 提示可用属性分类
  • dacli bigscreen construct --dataType=2 --validate → 镜像 isSql/isApi 等给 AI 提示该 dataType 必填字段
  • dacli bigscreen construct --config=base.json --components=nav.json --validate → 镜像 mixins.setGlobParams (解析 query/header/before/style 函数) + nav 数组结构校验

8.2.4 实施路径 (v0.14 推进, 不是 v0.13)

阶段 工期 内容
1. 镜像 base config 0.5 天 webapi/datascreen.ts 新增 getBaseConfig() 镜像 option/config.js (含 themeList/colorOption/tableOption/dicOption, 38 组件 metadata)
2. 镜像组件默认 option 0.5 天 webapi/datascreen.ts 新增 getComponentDefaults(prop), 通过 import.meta.globEager (web 端用此加载 38 .vue 文件) 在 dacli 端模拟 — 注意 web 端用 vue compiler, dacli 端只能读 .vue 里的 <script> default data 段, 这是 v0.14 待解决技术点
3. 镜像 save 数据结构 0.5 天 webapi/datascreen.ts 暴露 constructConfigDetail(baseConfig, navArray) + constructComponentJson(navArray), 镜像 header.vue:200-211 的 formdata 构造逻辑
4. 镜像校验 0.5 天 commands/bigscreen/_validate.ts 加 validateConstruct({ baseConfig, nav }), 镜像 validProp/isStatic/isSql/setGlobParams 等
5. dacli bigscreen construct 命令 0.5 天 接受 --template=base (空大屏) / --from-template=xxx (官方模板) / --from-json=design.json (用户设计 JSON), 走 step machine 校验 → loadVisualData.updateObj
6. 文档 + 测试 0.5 天 1) 文档化 38 组件 metadata + 默认 option 2) 端到端测试: 构造一个含 5 组件 (bar + line + text + map + video) 的大屏, save, 浏览器预览
总计 3 天 之前审计"建空壳"是 0.5 天, 完整构造大屏是 3 天 (差 6x)

8.2.5 v0.14+ 收益对比

路径 工期 端到端可用 构造大屏能力
❌ 旧 v0.14 计划: 镜像 dataV.ts Selector + 手写其他端点 0.5 天 部分 (list/copy ok, save/update drift) 仅空壳 (无组件)
❌ 旧 v0.14 计划: 用后端 controller 反推 + 直调 /api/blade-visual/visual/* 0.5 天 部分 (基础 CRUD ok) 仅空壳
✅ 新 v0.14+ 路线 (基于 8.2 实施): 镜像 option/config.js + option/components/*.vue + header.vue save 逻辑 3 天 全 (CRUD + 构造 + 校验) 可构造 38 组件的完整大屏

用户 2026-07-01 决策点:

  1. 走 8.2 完整 3 天路径 (推荐) — 真正能用, 端到端构造大屏
  2. 退回到 0.5 天 "空壳" 路径 — 留作"以后补", 但 1) 违反"用命令构造大屏"目标 2) TC-C dacli test render --module=bigscreen 仍然只能查基础字段, 查不出组件配置 bug

8.3 bigscreen TC-B/TC-C 重审计 (用户 2026-07-01 强要求)

用户原话: "TC-B 现在也是在猜, 没有完整读源码". 重新完整读 .claude/skills/ssw-e2e-test/references/tc-ab-real-test.md + ssw-e2e-test/SKILL.md (TC-A/B/C 精确定义) + jnpf-web-datascreen-vue3/src/page/{list/index,build}.vue + option/config.js + option/components/*.vue 后, TC-B/TC-C 应当:

8.3.1 TC-B 跨模块原则 (用户 2026-07-01 强要求, 适用于 form/workflow/portal/di/report/bigscreen)

关键原则 (用户原话): "TC-B 最好也能复用 webapi 镜像能力, 在确认渲染后, 使用原始 webapi 在构造+查找+触发+注入, 能加速的地方尽可能加速"

TC-B 不是"全浏览器操作", 应当复用 webapi 加速:

步骤 旧 (全浏览器) 新 (webapi + 浏览器) 加速比
构造 浏览器填表 + 提交 (5-10s) webapi dacli X create --ai ... (50ms) 100x
查找 浏览器点 menu + 翻页 (2-5s) webapi dacli X list + grep (50ms) 50x
触发 浏览器点 release/update 按钮 (3-5s) webapi dacli X release --id=X (50ms) 50x
注入 浏览器 cookie + localStorage (1-2s) page.addInitScript 注入 token (50ms) 30x
验证 浏览器 (必要, 真实) 浏览器 (保留) 1x (核心价值)
总计 11-22s / form 1-2s (准备) + 5s (验证) 3-5x

正路 (webapi 准备 + 浏览器验证):

# 1. webapi 拿 token (替代浏览器登录)
TOKEN=$(dacli app context --json | jq -r .token)
# 浏览器 addInitScript 注入 token, 跳过登录页
playwright -s={app_code} addInitScript "window.localStorage.setItem('jnpf_access-token', JSON.stringify({accessToken:'$TOKEN'}))"

# 2. webapi 构造测试数据 (替代浏览器填表)
FORM_ID=$(dacli form create --ai "TC-B 测试表: 名称" --autoRelease --json | jq -r .id)
# 拿测试 id
REC_ID=$(dacli test run --formId=$FORM_ID --keep-data --json | jq -r '.steps[] | select(.step=="create") | .data.id')

# 3. 浏览器只验证 (不构造) — 跳过 5 步填表, 直接 goto URL 看渲染
playwright -s={app_code} open "http://nginx/jnpf_app_{app_code}/model/{enCode}"
playwright -s={app_code} eval "() => JSON.stringify({
  rows: document.querySelectorAll('tr').length,  // 期望 ≥ 2 (表头 + 数据)
  dataRows: [...document.querySelectorAll('tr')].slice(1).map(r => r.textContent?.slice(0,50)),
  addBtn: !!document.querySelector('button:has-text(\"新增\")')
})"

# 4. 真实点击新增 → 弹窗 → 关闭 (验证前端 vue 渲染, 不构造数据)
playwright -s={app_code} click "button:has-text('新增')"
sleep 1
playwright -s={app_code} eval "() => !!document.querySelector('.ant-modal')"
playwright -s={app_code} click ".ant-modal-close"
sleep 1

# 5. 真实点击删除 + 验行数 -1 (用 webapi 构造的 REC_ID 反查, 不再"点新增 + 填表 + 提交")
#    实际是验证删除按钮, 删除后 webapi list 验少 1 条
BEFORE=$(playwright -s={app_code} eval "() => document.querySelectorAll('tr').length" --raw)
playwright -s={app_code} click "tr:has-text('TC-B-...') button:has-text('删除')"
playwright -s={app_code} click ".ant-modal button.ant-btn-primary"
sleep 2
# webapi 验: 行数 -1
NEW_COUNT=$(dacli form info $FORM_ID --list 2>/dev/null | wc -l)
# 期望: $NEW_COUNT == $BEFORE - 1

TC-B 模板升级路径 (.claude/skills/ssw-e2e-test/references/tc-ab-real-test.md v0.14+):

  • 步骤 1 (浏览器登录) → 改为 addInitScript 注入 token
  • 步骤 2 (拿 currentUserInfo 推路由) → 改为 dacli X list | jq 拿 id + 直接 goto URL
  • 步骤 3 (真实点击 menu) → 保留 (SPA 路由验证)
  • 步骤 4 (检测真实 DOM 渲染) → 保留
  • 步骤 5 (真实点击 + 填表单 + 提交) → 改为 真实点击 + webapi 验行数变化

8.3.2 TC-B 大屏特例 (v0.14+ 数据大屏)

关键差异: 大屏 web 端是独立子项目 jnpf-web-datascreen-vue3, 不是 主 webapp jnpf-web-apps-main 的 model/{enCode} 路由. URL 不一样.

应用 8.3.1 原则到大屏:

# 1. webapi 构造 (替代浏览器拖拽设计器) — 走 webapi/datascreen + 镜像 option/config.js 基础配置
BIGSCREEN_ID=$(dacli bigscreen create --fullName=TC-B-大屏 --enCode=tc-b-dash --category=1 --json | jq -r .id)
# 后续构造组件: v0.14 8.2 推进的 construct 命令 (dacli bigscreen construct --from-template=basic)

# 2. webapi 查找
TITLE=$(dacli bigscreen list --json | jq -r ".data.records[] | select(.id==$BIGSCREEN_ID) | .title")

# 3. webapi 触发 (release)
dacli bigscreen release --id=$BIGSCREEN_ID

# 4. 浏览器验证 (不构造, 只渲染)
playwright -s={app_code} open "http://nginx/jnpf_app_{app_code}/list"  # 数据大屏独立子项目 URL
sleep 2
# addInitScript 注入 token
playwright -s={app_code} addInitScript "..."
playwright -s={app_code} eval "() => JSON.stringify({
  containerCount: document.querySelectorAll('.list').length,
  itemCount: document.querySelectorAll('.content__item').length,
  hasNewItem: [...document.querySelectorAll('.content__name')].some(n => n.textContent?.includes('TC-B-大屏'))
})"
# 期望: hasNewItem=true (webapi 构造的数据能在浏览器看到)

4 铁律 (大屏 + 应用 8.3.1 加速原则):

  1. 按钮存在性: .content__add 存在 (list/index.vue:6-12) — 浏览器
  2. 跳过 modal ≠ PASS: 真实打开 dialog + 关闭 (不构造数据) — 浏览器
  3. CREATE 验行: webapi 构造 → 浏览器验 hasNewItem=true — 混合 (核心创新)
  4. 截图去重 (md5 不全相同): 截 4 张 (list / dialog / filled(不构造数据) / after-webapi-create) → md5 必须不全相同

TC-B 反模式 (重审计后新增, 大屏特殊):

  • ❌ 全浏览器构造 (5 步填表 + 提交) — 慢, 应走 webapi
  • ❌ 用 location.href 判断"创建成功" → 真路: webapi 验 list + 浏览器验 hasNewItem
  • ❌ 不看 category 字典 → 数据大屏 category 是后端 API /category/list 动态拉, web 端强制 dropdown 选择, AI 不能 category='1' 写死 (跟 form 旧版问题同源)
  • ❌ 不测设计器拖拽 → 大屏核心价值是设计器, 但 design drag-drop 是 Playwright 难做的 (定位 canvas 内部 component 困难), 降级为: 验证设计器 URL + canvas DOM 存在 + 左侧组件列表渲染 ≥ 38 项 (mirror option/config.js:268 dataList), 用 webapi dacli bigscreen construct --from-template=basic 构造基础组件 (避免拖拽)

8.3.3 TC-C (源码渲染层, dacli test render) 真实契约 (v0.14+ 跨模块)

v0.11+ 已有: dacli test render --module=dict | form. 缺: workflow / portal / di / report / bigscreen / menu (Phase B 计划中) / role / msg / schedule / monitor / user / log. 用户强要求: 用 webapi 镜像原则, 不要自己拼数据接后端.

跨模块 TC-C 现状审计 (2026-07-01):

模块 dacli test render 支持 webapi 镜像 TC-C 4 关卡完整 备注
dict ✅ v0.11+ ✅ loadDict ✅ list/form/详情/更新 标杆, form/dict 跟 mode 同源
form ✅ v0.11+ v0.11g 升级 ✅ loadVisualDev ✅ formData/columnData/relationForm/必填 标杆, v0.11g+ 4 真实契约
workflow ❌ 缺 ✅ loadWorkflow ❌ 缺 需加, 镜像 web BPMN 设计器 FlowProcess + 节点校验
portal ❌ 缺 ✅ loadPortal ❌ 缺 (Bug 5 同源) 需加, 镜像 web sysForm/Form.vue + category 校验
di (数据接口) ❌ 缺 ✅ loadDataInterface ❌ 缺 需加, 镜像 web 数据接口页 + SQL/API/WebSocket 三类型 schema 校验
report ❌ 缺 ✅ loadReport ❌ 缺 需加, 镜像 web 报表设计器 + 单元格 schema 校验
bigscreen ❌ 缺 (v0.14 推进 8.2) ✅ loadVisualData / loadDatascreen ❌ 缺 (8.3.2 详) 需加, 镜像 option/config.js + option/components/*.vue + build.vue + header.vue save 逻辑
role / msg / schedule / monitor / user / log ❌ 缺 ✅ 已建 (见 webapi/*.ts 列表) ❌ 缺 v0.14+ Phase B 计划, 按 dict/form 模式批量加
menu ❌ 缺 (Phase B 计划中) ✅ loadMenu ❌ 缺 镜像 web Menu.vue + propertyJson 校验

TC-C 跨模块模板 (跟 dict/form 同模式, 但每个模块有自己的 web 渲染契约源):

// 通用 TC-C 4 步模式 (镜像 dict/form)
async function renderModule(c, opts, results, log) {
  // 1. 读 web 端渲染契约 (SFC 解析, 不用后端 API)
  const renderFields = extractFieldsBySFC(WEB_VIEWS[opts.module].list)  // 列表渲染字段
  const formFields = extractFieldsBySFC(WEB_VIEWS[opts.module].form)    // 表单渲染字段
  const webapiModule = WEBAPI_MODULES[opts.module]                       // loadDict | loadVisualDev | loadVisualData | ...

  // 2. 调 webapi 拿实际数据 (走 webapi 镜像, NOT c.get)
  await initWebapi(c)
  const listResp = await webapiModule.getList({ ... })
  const apiFields = listResp.data?.records?.[0] ? Object.keys(listResp.data.records[0]) : []

  // 3. 4 关卡对比
  //    3.1 list 字段 ⊆ api 字段
  //    3.2 form 字段 ⊆ api 字段
  //    3.3 必填/外键/关联完整性
  //    3.4 schema 完整性 (config/component/detail/BPMN 等)
  results.push({ page: `${opts.module}-list`, status: extra.length === 0 ? 'PASS' : 'FAIL', ... })
  // ...

  // 4. 报告
  return { module: opts.module, totalPages, pass, fail, missingFields, results }
}

vs 反模式 (用户 2026-07-01 警告, 跨模块):

  • ❌ 反模式 A: c.get('/X/list') 直调后端 → 违反 webapi 镜像原则, 漂移
  • ❌ 反模式 B: 自己写 loadX = { getList: () => fetch('/api/X/list') } → 看似 webapi 化实际是拼数据接后端
  • ❌ 反模式 C: 只对比 list 字段 (跟 form 旧版同源问题) → 漏掉 form/detail/schema 完整性
  • ❌ 反模式 D: 用 SFC 解析拼凑字段, 不调 webapi 镜像 (跟 A 同源, 但伪装成"读 web 源码")
  • ✅ 正路: @vue/compiler-sfc 读 views/.../*.vue 拿 web 渲染契约 → 调 loadX.* 拿 API 实际数据 → 4 关卡对比

8.3.4 实施路径 (v0.14 跨模块)

阶段 模块 工期 备注
1 bigscreen (v0.14 强要求) 3 天 (含 §8.2 完整构造) 见 §8.2 实施路径
2 portal (Bug 5 修复 + TC-C) 1 天 category 字典校验, 跟 form 同模式
3 workflow (TC-C) 1 天 镜像 web FlowProcess + 节点完整性
4 di (TC-C) 0.5 天 镜像 web 数据接口 + SQL/API/WebSocket 三类型 schema
5 report (TC-C) 1 天 镜像 web 报表设计器 + 单元格 schema
6 role / msg / schedule / monitor / user / log (TC-C Phase B) 1 天/批 按 dict/form 模式批量加
7 menu (TC-C Phase B) 0.5 天 镜像 web Menu.vue + propertyJson
8 TC-B 模板升级 (跨模块加速) 0.5 天 应用 8.3.1 原则到 tc-ab-real-test.md
总计 8.5 天 较原"0.5 天空壳"差 17x, 但能查 schema 漂移 / API 字段不对 / enCode 不匹配等真实 bug

用户 2026-07-01 决策点:

  1. 走 8.3 完整 8.5 天路径 (推荐) — 跨模块真实契约校验, 端到端能用
  2. 只做 bigscreen (3 天) — 局部最优, 但 form/workflow/portal/di/report 仍有同样问题
  3. 只做 webapi 基础切换, 不做 TC-C — 治标不治本, 下次审计会复发