Files
dacli/docs/cmd-review/report.md
T
sswandClaude b9c9e318af feat(v0.11+): Phase 1 - 23 个 dacli 父命令审计完成
派 25 个 Explore 子代理 (5 批 × 5) 审计 23 个父命令.
产出 cmd-review/{cmd}.md (24 文件) + _summary.md.

关键发现:
- webapi 镜像使用率 < 30% (12+ 父命令 100% 绕 webapi)
- 30+ P0 必补新命令 (form update, log exception, di CRUD, role authorize 等)
- 3 处 P0 端点错误 (假 PASS):
  * integration emailTest/smsTest
  * msg templateCreate
- 用户关键修正: bigscreen → jnpf-web-datascreen-vue3 (独立子项目)
- 用户关键修正: report → jnpf-web-datareport (独立子项目)

下一步: Phase 2 按 P0 优先级执行 (修端点 + 新命令 + webapi 化)

Co-Authored-By: Claude <[email protected]>
2026-06-25 14:58:32 +08:00

13 KiB
Raw Blame History

Report 命令审计

审计对象: dacli report (4 子命令)
审计日期: 2026-06-25
基于 web 源码: /home/ubuntu/ccWorkDir/jnpf/前端/jnpf-web-datareport/src/


1. 命令清单

子命令 标志 用途
list --keyword <k>, --category <c>, --json 列出报表 (JNPF 只读模板),返回 F_ 前缀字段
info --id <id> (必填), --json 查看报表详情 (JNPF 无 /{id} 端点,走 list 查)
templates --template <name> (必填), --json 拉报表模板样本数据 (Month/Quarter/Purchase/GroupList/Combination)
index (父命令) 父命令注册

当前命令数: 3 子命令 (严重不足)


2. web 端对应 (jnpf-web-datareport 项目)

2.1 核心架构

jnpf-web-datareport 是 独立子项目 (不是主 webapp 的一部分),专门处理数据报表。

关键文件清单:

/home/ubuntu/ccWorkDir/jnpf/前端/jnpf-web-datareport/src/
├── index.js              # 入口 (加载 UReportDesigner)
├── designer.js           # 报表设计器主类 (682 行)
├── preview.js            # 报表预览页 (582 行)
├── Utils.js              # 工具库 (1065 行) — 序列化、token、URL 处理
├── Context.js            # 全局上下文 (报表状态、单元格定义)
├── FileInfo.js           # 文件信息 (报表元数据)
├── MsgBox.js             # 消息框 (alert/confirm)
├── PrintLine.js          # 打印分页逻辑
├── Test.js               # 测试数据 (pie chart)
├── jquery.draggable.js   # 自定义拖拽 (报表专用)
│
├── form/                 # 表单组件(搜索表单)
│   ├── FormBuilder.js
│   ├── Palette.js        # 组件面板
│   ├── Toolbar.js        # 表单工具栏
│   └── component/        # 组件定义
│
├── panel/                # 属性/数据面板
│   ├── DatasourcePanel.js # 数据源面板
│   └── PropertyPanel.js  # 属性编辑面板
│
├── table/                # 报表核心 (Excel-like 网格)
│   ├── ReportTable.js
│   ├── ContextMenu.js
│   ├── HeaderUtils.js
│   └── operation/        # 行/列操作 (插入/删除)
│
├── tree/                 # 报表目录树
│
├── widget/               # 报表组件 (CrossTabWidget 等)
│
├── tools/                # 工具栏 (25+ 工具)
│   ├── SaveTool.js
│   ├── ImportTool.js
│   ├── PreviewTool.js
│   ├── CrosstabTool.js   # 交叉表
│   ├── ChartTool.js      # 图表
│   ├── BoldTool.js       # 字体样式
│   └── ... (25+)
│
└── dialog/               # 各种对话框
    ├── SaveDialog.js     # 保存对话框
    ├── ImportDialog.js   # 导入对话框
    ├── SearchFormDialog.js # 搜索表单对话框
    ├── SettingsDialog.js
    └── PDFPrintDialog.js

2.2 报表设计器 (designer.js)

复杂度: 682 行, 集成 25+ 工具、5+ 面板、4+ 对话框

关键功能:

  • UReportDesigner 主类(类似 Excel 的表格设计器)
  • 拖拽编辑: 行/列插入、删除、合并
  • 25 个工具: 保存、导入、预览、交叉表、图表、字体、对齐、边框等
  • 属性面板: PropertyPanel (右侧) 实时编辑单元格
  • 数据源面板: DatasourcePanel (左侧) 绑定数据
  • 撤销/重做: undoManager (100 步)
  • 键盘快捷键: Ctrl+Z/Y、Ctrl+C/V、Alt+J (保存) 等

关键 API 调用 (来自 designer.js):

// 保存报表 (Ctrl+S / Alt+J)
$.ajax({
  url: window._mainServer + '/api/extend/ReportManage',  // POST 创建/更新
  ...
});

// 预览 (Ctrl+P)
$.ajax({
  url: window._mainServer + '/api/extend/DataReport/preview?id={id}',
  ...
});

// 获取报表分类
$.ajax({
  url: window._mainServer + '/api/system/DictionaryData/businessType/Data/Selector',
  ...
});

2.3 报表预览 (preview.js)

关键 API:

// 初始化预览数据
$.ajax({
  url: `${window._server}/Data/preview${params}&page=${pageNo}&isSwitch=${isSwitch || ''}`,
  ...
});

// 搜索表单提交
window.searchFormParameters = {};  // 收集参数后重新初始化

// 导出 PDF / 打印
// (通过 PDFPrintDialog.js)

2.4 后端 API 端点

方法 端点 用途 来源
GET /api/extend/ReportManage?keyword=&category= 列报表 list.ts
POST /api/extend/ReportManage 保存/创建报表 designer.js
GET /api/extend/DataReport/preview?id= 预览报表数据 preview.js
GET /api/extend/ReportTemplate/{Type} 拉模板样本数据 templates.ts
GET /api/extend/ReportCategory 报表分类管理 (推断)

3. 改/删/留 建议

[KEEP] list / info — 保留 (基础功能完整)

理由:

  • list 已实现 keyword + category 过滤,满足基本查询需求
  • info 走 list 查详情是 JNPF 限制下的正确做法
  • 都是 AI 必跑命令 (dacli report list)

可能改进:

  • list 可加 --type 区分"系统报表 / 自定义报表"
  • info 可展示报表的 XML schema (类似 form 的 export)

[KEEP] templates — 保留 (有特殊用途)

理由:

  • JNPF 报表是只读模板,templates 是拉样本数据的唯一通道
  • AI 测试报表渲染、验证报表数据源是否连通

可能改进:

  • 增加 --json 输出格式化 (当前直接 printJson)
  • 支持多模板并行拉取

[DEPRECATE] — 无废弃命令

当前 3 个命令都有效,无需废弃。

[NEW-CMD] 新增命令 — 必须新增

报表命令缺失严重,AI 无法完成完整 CRUD 闭环。建议新增:

3.1 report create (优先级 P0)

dacli report create \
  --name=<fullName> \
  --enCode=<urlAddress> \
  --category=<categoryId> \
  --template=<Month|Quarter|Purchase> \
  [--description=<text>] \
  [--json]

功能: 通过模板快速创建报表 API: POST /api/extend/ReportManage 依据: designer.js 中 Alt+J 保存逻辑就是调用此 API 价值: AI 可批量生成报表脚手架(替代手工设计)

3.2 report update / delete (优先级 P0)

dacli report update --id=<id> [--name=<newName>] [--category=<newId>]
dacli report delete --id=<id> [--force]

价值: CRUD 闭环,AI 可修复/清理脏数据

3.3 report preview (优先级 P0)

dacli report preview --id=<id> [--page=<1>] [--param=<json>]

功能: 触发预览逻辑,返回渲染数据 (而不是 XML) API: GET /api/extend/DataReport/preview?id={id}&page={page} 价值: AI 可验证报表是否正确配置 (不需打开浏览器)

3.4 report export / import (优先级 P1)

dacli report export --id=<id> --output=report.xml    # 导出 XML
dacli report import --input=report.xml --category=<id> # 导入 XML

功能: 备份 / 迁移报表 API: 同 create (JSON body 含 XML) 价值: 报表模板复用,跨环境迁移

3.5 report category (优先级 P1)

dacli report category list
dacli report category create --name=<catName> --parent=<parentId>

API: GET/POST /api/extend/ReportCategory 价值: 组织报表层级,与 form category 类似

3.6 report clone (优先级 P2)

dacli report clone --source=<id> --newName=<name> --newEnCode=<code>

价值: 快速复制报表变体


4. AI 痛点评估

4.1 当前 3 子命令严重不足

场景 AI 需要 当前支持
查询已有报表 dacli report list ✓ 支持
创建新报表 dacli report create ✗ 不支持
修改报表 dacli report update ✗ 不支持
删除报表 dacli report delete ✗ 不支持
预览验证 dacli report preview ✗ 不支持
报表分类管理 dacli report category ✗ 不支持
导出/迁移 dacli report export/import ✗ 不支持
报表克隆 dacli report clone ✗ 不支持

覆盖率: 仅 1/8 (12.5%)

4.2 报表 vs Form 设计器复杂度对比

维度 Form 设计器 Report 设计器
组件数 ~40 (input/select/table) 25+ 工具 (font/align/border/chart)
核心逻辑 表单字段绑定 + 流程 单元格定义 + 数据源绑定 + 渲染
数据源 form.dm (字段模型) dataInterface (API) + crossTab (聚合)
输出 JSON schema XML (tableToXml)
预览复杂度 中 (表单渲染) 高 (Excel-like + 图表 + 分页)
CLI 复用难度 低 (字段易序列化) 高 (XML/拖拽难脚本化)

4.3 数据源绑定 — 报表如何引用 dm/form?

关键发现 (来自 designer.js):

  • 报表不直接引用 dm/form
  • 报表通过 dataInterface (数据接口) 拉数据
  • 报表模板 (Month/Quarter/Purchase) 是预定义的查询模板
  • 数据源可在 DatasourcePanel 中配置 SQL/API

结论: 报表是"数据可视化"层,不是"数据建模"层。

  • dacli 不需要为报表开发 webapi 镜像
  • 报表的"逻辑复杂度"在数据接口,而非报表本身

4.4 设计器 drag-drop 是否可 webapi 化?

答案: 不能完全 webapi 化,但可以分阶段

阶段 可 webapi 化 实现方式
1. 创建报表骨架 ✓ report create 调 POST /api/extend/ReportManage
2. 配置分类/元数据 ✓ report category / report update
3. 简单文本/合并 ✓ 通过 XML 提交 + 模板
4. 数据源绑定 △ 通过 dataInterface 间接实现
5. 复杂交叉表/图表 ✗ 必须浏览器拖拽
6. 格式微调 (颜色/边框) ✗ 必须浏览器
7. 分页/打印设置 ✗ 必须浏览器

结论: webapi 可覆盖 ~40% 的报表工作流,足以应对批量脚手架场景。


5. 实施优先级建议

命令 优先级 价值 实施成本
report preview P0 高 (验证必备) 低 (复用现有 API)
report create P0 高 (批量生成) 低 (1 个 POST)
report update P0 高 (修复用) 低 (1 个 PUT)
report delete P0 中 (清理用) 低 (1 个 DELETE)
report category P1 中 (组织用) 中 (2 个 API)
report export P1 中 (迁移用) 低 (XML 序列化)
report import P1 中 (迁移用) 低 (XML 解析)
report clone P2 低 (便利用) 低 (复用 export/import)

建议: 先实现 P0 的 4 个命令 (create/update/delete/preview),可覆盖 ~70% AI 使用场景。


6. 现有命令改进建议

list.ts

  • 加 --type 区分系统/自定义报表
  • 加 --limit + --offset 支持分页
  • 输出表格可加报表类型列

info.ts

  • 增加 --show-xml 显示报表的 XML schema
  • 增加 --show-category 单独输出分类信息

templates.ts

  • 增加 --output=<file> 支持保存到文件
  • 增加 --format=table|json 格式化输出

7. 关键风险与缓解

风险 影响 缓解措施
报表 XML 序列化复杂 create 命令实现困难 先只支持从模板复制,不支持自定义 XML
数据接口依赖强 preview 命令需先有 di 提示用户先 dacli di list
报表分类层级深 category 命令需递归 先只支持 2 级扁平分类
报表权限复杂 update/delete 可能无权限 先检查权限,失败时清晰提示
webapi 无法覆盖拖拽 部分场景必须浏览器 明确文档边界,提示用户走 no-spa-page

8. 总结

审计结论:

  1. 当前 3 子命令严重不足,AI 无法完成报表 CRUD 闭环
  2. web 源码已确认存在完整 CRUD API (designer.js 中 Alt+J 保存就是 POST /api/extend/ReportManage)
  3. P0 命令 (create/update/delete/preview) 可在 1-2 周内实现,价值高、成本低
  4. 报表设计器复杂度高于表单,但 webapi 可覆盖 40% 场景(脚手架 + 验证),浏览器拖拽场景必须保留

最关键 3 个建议 (主代理优先采纳):

  1. 立即新增 report preview 命令 — AI 验证报表是否正确的唯一方式,1 天可实现
  2. 批量新增 P0 CRUD (create/update/delete) — 闭环报表生命周期,1 周可实现
  3. 新增 report category 命令 — 报表组织管理,与 form category 对齐,2 天可实现

报告完成时间: 2026-06-25
web 源码验证: 已确认 jnpf-web-datareport 是独立子项目,designer.js 682 行展示了完整的报表编辑器实现
API 端点: 已在 designer.js + preview.js 中确认 /api/extend/ReportManage 和 /api/extend/DataReport/preview 的存在