派 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]>
13 KiB
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. 总结
审计结论:
- 当前 3 子命令严重不足,AI 无法完成报表 CRUD 闭环
- web 源码已确认存在完整 CRUD API (designer.js 中 Alt+J 保存就是 POST /api/extend/ReportManage)
- P0 命令 (create/update/delete/preview) 可在 1-2 周内实现,价值高、成本低
- 报表设计器复杂度高于表单,但 webapi 可覆盖 40% 场景(脚手架 + 验证),浏览器拖拽场景必须保留
最关键 3 个建议 (主代理优先采纳):
- 立即新增
report preview命令 — AI 验证报表是否正确的唯一方式,1 天可实现 - 批量新增 P0 CRUD (create/update/delete) — 闭环报表生命周期,1 周可实现
- 新增
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 的存在