Files
dacli/docs/cmd-review/bigscreen.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

12 KiB
Raw Blame History

dacli bigscreen 命令审计报告 (2026-06-25 v2 + 2026-07-01 v0.14)

v2 修正: 用户指出大屏 web 端源码不在主 webapp, 而在独立项目 jnpf/前端/jnpf-web-datascreen-vue3. 此版基于正确路径重新审计. v0.14 章节: 端点修正 + webapi 镜像 + construct 命令 (3 天完整构造大屏, 非空壳) + 36 组件 metadata.

1. 命令清单

子命令 格式 用途
dacli bigscreen list [--keyword] [--category] [--json] 列出所有大屏(按 category 过滤)
dacli bigscreen info <id> [--json] 查看大屏详情(含 design JSON)
dacli bigscreen create --fullName --enCode --category --json 创建大屏基础记录
dacli bigscreen release <id> [--json] 发布大屏(state=1)
dacli bigscreen update <id> --json 修改大屏
dacli bigscreen delete <id> --yes 删除大屏
dacli bigscreen construct --template=base | --from-json=<file> | --prop=<name>... v0.14+ 完整构造大屏 (带组件)

2. web 端对应 (正确路径)

正确路径: /home/ubuntu/ccWorkDir/jnpf/前端/jnpf-web-datascreen-vue3/

2.1 API 模块 (在 src/api/)

  • visual.js — 大屏 CRUD (list/copy/detail/save/update/remove/getCategory/uploadImg/updateComponent)
  • category.js — 分类管理
  • components.js — 组件管理
  • glob.js — 全局变量
  • record.js — 访问记录

2.2 页面架构 (在 src/page/)

  • list/ — 大屏列表+分类+CRUD 对话框
  • build.vue — 大屏设计器(复杂 drag-drop 交互)
  • view.vue — 预览

2.3 关键端点 (web 端真实)

  • /visual/list GET — 列表
  • /visual/detail/{id} GET — 详情
  • /visual/save POST — 创建 (addObj, body: {visual:{title,category,status}, config:{detail,component}})
  • /visual/update POST — 修改 (updateComponent, 含 status=1 发布)
  • /visual/remove DELETE — 删除
  • /visual/copy POST — 复制
  • /category/* — 分类管理

2.4 nginx 代理 (实际端点)

  • /api/visual/* → 端口 30000 (jnpf-visualdata 微服务, 不是 32000 jnpf-datareport-univer)
  • 端点修正 (v0.14+): web 端 public/config.js 设 window.$website.url = '/api/blade-visual', 通过 nginx 代理转发到 30000 端口 jnpf-visualdata 微服务. 之前文档写的 /api/visual/* 端口 32000 是错的, 32000 是报表微服务, 大屏有自己的 30000 微服务.
  • ❌ 不要 "镜像 web/.../api/onlineDev/dataV.ts" — 该文件只镜像了 getDataVSelector() (1/8 函数), 其他端点手写直调后端 = 自己拼接数据接后端 API, 绕开前端成熟能力.

3. 改/删/留 建议 (v0.13+ 已闭环)

[KEEP] 保留

  • list — 已切到 webapi/visualdata.ts (走 /api/visual/list)
  • info — 已切到 webapi/visualdata.ts (走 /api/visual/detail)
  • create — 已切到 webapi/datascreen.ts (走 /api/visual/save)
  • release — 已切到 webapi/visualdata.ts (走 /api/visual/update status=1)
  • update/delete — v0.11+ 已加 (webapi/visualdata.ts)
  • construct — v0.14+ 新加 (镜像 option/config.js + option/components/*.vue + header.vue:200-211 save formdata)

[DEPRECATE]

  • webapi/bigscreen.ts — @deprecated since v0.14, 只镜像 Selector 1/8 函数, 其他手写. 全部 bigscreen 命令统一用 webapi/visualdata.ts.

[NEW-CMD] v0.14+ 必补

  • dacli bigscreen construct — 完整构造大屏 (含组件), 详见 §6
  • dacli bigscreen copy — 复制大屏 (走 /visual/copy)
  • dacli bigscreen category — 子命令组: list/add/update/delete (走 /category/list)
  • dacli bigscreen export/import — 跨 app 迁移

[NEW-CMD] P2

  • dacli bigscreen preview-token — 生成分享 token

4. AI 痛点评估

分类管理缺失

  • dacli 用硬编码 category=1
  • web 用 categoryValue 字符串键 (从 category.js 拉)
  • AI 不知道有效分类, 需补 bigscreen category list

设计器 drag-drop 部分 webapi 化 (v0.14+ 已突破)

  • 大屏设计器是复杂可视化交互 (build.vue)
  • 之前无法通过 API 完全复制设计器, AI 只能建空壳大屏
  • v0.14+ dacli bigscreen construct 命令已支持: --template=base / --from-json / --prop=... 四种入口, 端到端构造 36 组件大屏
  • 详见 §6 + cmd-review/bigscreen-components.md (36 组件 metadata)

数据源绑定闭环不全

  • 大屏依赖 DI 拉数据
  • dacli 创建的大屏无数据绑定 (web 端 setup/database.vue 管绑定)
  • 应增加 --dataInterfaceId 参数 + bigscreen binding 子命令
  • v0.14+ 部分解决: dacli bigscreen construct --dataType=1 --url=http://... 直接绑 API URL (dataType 0-7 镜像 build.vue:666-689)

API 路径不一致

  • 这是 最严重盲点 (v0.13+ 已闭环): dacli/web 走不同 API 路径, 数据结构不同
  • 修复: 切 webapi/visualdata.ts 走 web 端真实端点

5. v0.13+ webapi 化路径 (闭环)

webapi/visualdata.ts (主推, v0.11+):

  • 镜像源: jnpf/前端/jnpf-web-datascreen-vue3/src/api/visual.js (9 函数: getList/copyObj/getCategory/getObj/uploadImg/addObj/updateComponent/updateObj/delObj)
  • 端点: /api/visual/list /api/visual/detail /api/visual/save /api/visual/update /api/visual/remove /api/visual/copy
  • 导入: import { initWebapi, loadVisualData } from '../../webapi/visualdata.ts'
  • 用法: await initWebapi(c) + await loadVisualData.<func>(args)

webapi/datascreen.ts (备, v0.13+): 同样源, 独立 shim 路径 (处理 visual.js 相对路径 import, import request from '../axios')

webapi/bigscreen.ts (@deprecated since v0.14): 只镜像 Selector, 其他手写直调 /api/blade-visual/visual/* — 已废弃, 不要新代码用这个.

6. v0.14+ 完整构造大屏 (construct 命令)

6.1 镜像源 (3 层数据)

层 源文件 镜像到
基础配置 (config) jnpf-web-datascreen-vue3/src/option/config.js webapi/datascreen.ts:getBaseConfig()
组件默认 option (36 个) jnpf-web-datascreen-vue3/src/option/components/*.vue webapi/datascreen.ts:getComponentDefaults(prop) + listComponentProps()
Save 数据结构 jnpf-web-datascreen-vue3/src/page/group/header.vue:200-211 webapi/datascreen.ts:constructConfigDetail(baseConfig, nav)
组件列表 (nav) jnpf-web-datascreen-vue3/src/page/build.vue:705-709 用户/dacli 构造, 走 loadVisualData.updateObj
校验 step machine build.vue:666-692 (dataType) + build.vue:1040-1042 (validProp) + mixins/index.js:35 (configData) commands/bigscreen/_validate.ts:validateConstruct()

6.2 Save 数据结构 (镜像 web 端)

// 镜像自 web 端 group/header.vue:200-211
const formdata = {
  visual: {
    id: visual.id,
    backgroundUrl: url || visual.backgroundUrl,  // 缩略图
  },
  config: {
    id: config.id,
    visualId: visual.id,
    detail: JSON.stringify(config),    // ← 基础配置对象 (来自 option/config.js)
    component: JSON.stringify(nav),    // ← 组件列表数组
  }
}
updateComponent(formdata)  // POST /visual/update (走 webapi/visualdata.updateObj)

6.3 命令选项 (22 options)

dacli bigscreen construct [options]

# 必填
  --fullName <name>            大屏名称 (visual.title)
  --enCode <code>              大屏编码 (ENCODE_REGEXP 校验)
  --category <cat>             分类: 1=数据大屏 2=仪表盘

# 数据源入口 (4 选 1)
  --template <t>               内置模板: base=空大屏 (默认 9 组件 demo) [默认 base]
  --from-template <name>       官方模板 (Phase 5+ 扩展, 暂等同 --template=base)
  --from-json <file>           用户设计 JSON (含 baseConfig + nav 两段)
  --prop <name>                组件 prop (多次: --prop=bar --prop=text)

# 组件位置 (--prop 多次时, 全局默认; 单组件时直接用)
  --x <n>                      组件 x 坐标 (默认 0)
  --y <n>                      组件 y 坐标 (默认 0, 多组件时 i*320 纵向堆叠)
  --w <n>                      组件宽度 (默认 400)
  --h <n>                      组件高度 (默认 300)

# 数据源字段 (镜像 build.vue:666-689 dataType 0-7)
  --dataType <n>               数据源类型 0-7 (0=static 1=api 2=sql 3=ws 4=record 5=public 6=mqtt 7=node)
  --url <u>                    数据源 URL (dataType=1/3/5/6)
  --sql <s>                    数据源 SQL (dataType=2)
  --value <v>                  数据源 value (dataType=0/4)

# 大屏尺寸
  --width <n>                  大屏宽度 (默认 1920)
  --height <n>                 大屏高度 (默认 1080)
  --backgroundUrl <u>          缩略图 URL (web put-file/screenShot 上传后回填)

# 状态
  --status <s>                 状态 0/1 (默认 1=已发布, --no-release 时无效)
  --no-release                 跳过发布 (默认 ON 发布)
  --validate-only              只校验不创建
  --json                       原始 JSON 输出

6.4 dataType 0-7 校验 (镜像 build.vue:666-689)

dataType 名称 必填字段 镜像位置
0 static value build.vue:667-668 isStatic
1 api url build.vue:670-671 isApi
2 sql sql build.vue:672-673 isSql
3 ws (websocket) url build.vue:674-675 isWs
4 record (recordId) value build.vue:676-677 isRecord
5 public url build.vue:678-679 isPublic
6 mqtt url build.vue:680-681 isMqtt
7 node (无) build.vue:682-683 isNode

6.5 36 组件 metadata

详见 cmd-review/bigscreen-components.md (每个组件: prop 名 + 用途 + 默认 option keys + dataType 推荐).

6.6 完整流程 (7 步)

[step 1] getBaseConfig()                     ← 镜像 option/config.js
[step 2] constructComponentJson(navInput)     ← 镜像 build.vue:705-709
[step 3] validateConstruct()                  ← 镜像 build.vue:666-692 + 1040-1042 validProp
[step 4] constructConfigDetail()              ← 镜像 header.vue:200-211 save formdata
[step 5] loadVisualData.addObj({visual,config})  ← 拿新大屏 id
[step 6] loadVisualData.updateObj(formdata)   ← save 完整 formdata (含组件)
[step 7] loadVisualData.updateObj({status:1}) ← 发布 (默认 ON)

6.7 使用示例

# 1. 内置模板 (默认 9 组件 demo, 一键)
dacli bigscreen construct --template=base --fullName=销售大屏 --enCode=salesDash --category=1

# 2. 单组件添加 (5 组件 demo, bar+text+map+video+table, 静态数据)
dacli bigscreen construct --template=base \
  --fullName=TC-5comp --enCode=tc-5comp --category=1 \
  --prop=bar --prop=text --prop=map --prop=video --prop=table \
  --dataType=0 --value='[]'

# 3. API 数据源 (bar 组件 + REST API)
dacli bigscreen construct --template=base --fullName=API大屏 --enCode=apiDash --category=1 \
  --prop=bar --dataType=1 --url=http://example.com/api

# 4. 从用户 JSON 设计 (完整 baseConfig + nav)
dacli bigscreen construct --from-json=design.json \
  --fullName=我的大屏 --enCode=myDash --category=1

# 5. 校验 only (不发 API)
dacli bigscreen construct --from-json=design.json \
  --fullName=预览 --enCode=preview --category=1 --validate-only

6.8 端到端验证 (v0.14 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 --id=<id> (5+1 关卡) ✅ PASS
TC-C dacli test render --module=bigscreen (list mode) ✅ PASS
dataType=1 缺 url 校验 ✅ 5 项校验失败阻断

核心结论 (v0.14): bigscreen 命令已闭环 webapi 化 (visualdata.ts + datascreen.ts 双镜像), webapi/bigscreen.ts 已 @deprecated. dacli bigscreen construct 命令支持完整构造大屏 (36 组件 + 4 入口 + 7 步流程 + 22 options), 端到端可用.

3 个最关键成果:

  1. [P0] 统一 webapi 镜像: webapi/visualdata.ts 主推, webapi/bigscreen.ts @deprecated. 端点修正为 /api/visual/* 端口 30000 jnpf-visualdata 微服务.
  2. [P0] 完整构造命令: dacli bigscreen construct 支持 4 入口 (template/from-template/from-json/prop), 镜像 web 端 save formdata 完整链路.
  3. [P0] 36 组件 metadata 文档化: cmd-review/bigscreen-components.md (跟 form/workflow 一样, 列 36 组件 prop + 默认 option + dataType 推荐).