## 文档更新 - 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]>
12 KiB
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/listGET — 列表/visual/detail/{id}GET — 详情/visual/savePOST — 创建 (addObj, body:{visual:{title,category,status}, config:{detail,component}})/visual/updatePOST — 修改 (updateComponent, 含 status=1 发布)/visual/removeDELETE — 删除/visual/copyPOST — 复制/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— 完整构造大屏 (含组件), 详见 §6dacli 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 个最关键成果:
- [P0] 统一 webapi 镜像:
webapi/visualdata.ts主推,webapi/bigscreen.ts@deprecated. 端点修正为/api/visual/*端口 30000 jnpf-visualdata 微服务. - [P0] 完整构造命令:
dacli bigscreen construct支持 4 入口 (template/from-template/from-json/prop), 镜像 web 端 save formdata 完整链路. - [P0] 36 组件 metadata 文档化:
cmd-review/bigscreen-components.md(跟 form/workflow 一样, 列 36 组件 prop + 默认 option + dataType 推荐).