From 1650c3fe571c1913b70134a05b03c8e571333861 Mon Sep 17 00:00:00 2001 From: ssw Date: Thu, 2 Jul 2026 13:52:05 +0800 Subject: [PATCH] =?UTF-8?q?v0.16-1=20=E5=AE=9E=E6=96=BD:=20report=20releas?= =?UTF-8?q?e=20=E2=86=92=20save/publish=20=E6=8B=86=E5=88=86=20(deprecatio?= =?UTF-8?q?n=20=E5=91=A8=E6=9C=9F,=202026-07-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v0.14 audit FINDING-R3 (2026-07-02): report release 命名误导 - 旧 release 命令同时做 '保存设计' (type=0) 和 '发布+部署' (type=1) - 用户误以为是 form release (state 切换), 实际是 saveVersion (设计+部署) - 跟 form release 行为完全不一致 (form release 切 state 0→1) v0.16+ 拆分: - 新增 report/save.ts (v0.16+ 推荐) - 隐式 type=0 (保存设计, 不部署) - cells 必传 (type=1 必填, save 同样要) - 新增 report/publish.ts (v0.16+ 推荐) - 隐式 type=1 (真正发布+部署, BS-新116 实战) - report/release.ts 标记 deprecated - description 加 ⚠️ [DEPRECATED v0.16+] - 入口 log.warn 引导用 save/publish - 保留到 v0.18 (1 季度 deprecation 周期), 之后移除 - report/index.ts 注册 2 个新子命令 测试场景: - 旧: 'dacli report release --type=1' 仍可用 + deprecation warn - 新: 'dacli report publish' 隐式 type=1 (推荐) - 新: 'dacli report save' 隐式 type=0 (推荐) 审计: dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md §2.1 R3 --- src/commands/report/index.ts | 21 ++++- src/commands/report/publish.ts | 144 +++++++++++++++++++++++++++++++++ src/commands/report/release.ts | 9 ++- src/commands/report/save.ts | 139 +++++++++++++++++++++++++++++++ 4 files changed, 309 insertions(+), 4 deletions(-) create mode 100644 src/commands/report/publish.ts create mode 100644 src/commands/report/save.ts diff --git a/src/commands/report/index.ts b/src/commands/report/index.ts index 130ef11..03ebfd7 100644 --- a/src/commands/report/index.ts +++ b/src/commands/report/index.ts @@ -7,6 +7,10 @@ * - info: GET /api/Report/{id} (loadReport.getReportInfo) * - create: POST /api/Report (loadReport.createReport) * - update: PUT /api/Report/{id} (loadReport.updateReport, v0.14+ 新增) + * - save: POST /api/Report/Save type=0 (v0.16+ 新增, 替代 release --type=0) + * - publish: POST /api/Report/Save type=1 (v0.16+ 新增, 替代 release --type=1) + * - release: POST /api/Report/Save type=0/1 (v0.14+ BS-新116, v0.16+ deprecated) + * - delete: DELETE /api/Report/{id} (v0.14+ BS-新116 配套, jyzs 2026-07-02 补) * - templates: GET /api/Report/Selector (loadReport.getReportSelector) * * 历史迁移: @@ -14,12 +18,19 @@ * - templates 旧版走 /extend/ReportTemplate/{Month|...} (老 ureport2 样本数据) — web 端已无对应镜像 * - v0.14+ 统一走 webapi 镜像, 端点对齐 jnpf 6.x univer 报表微服务 (jnpf-datareport-univer) * + * v0.16+ 拆分 release → save + publish (FINDING-R3 audit 2026-07-02): + * - release 命令同时做 "保存设计" (type=0) 和 "发布+部署" (type=1), 命名误导 + * - 拆 save (type=0 隐式) + publish (type=1 隐式), 跟 web 端 /api/Report/Save 一致 + * - release 保留到 v0.18 (1 季度 deprecation 周期), 之后移除 + * * 子命令: * list 列表 (元数据) * info 详情 * create 新建 * update 修改 (v0.14+ 新增) - * release 发布/保存设计 (v0.14+ BS-新116, jyzs 2026-07-02 补) + * save 保存设计 (v0.16+ 新增, 替代 release --type=0) + * publish 发布+部署 (v0.16+ 新增, 替代 release --type=1) + * release [DEPRECATED v0.18] 发布/保存设计, 用 save/publish 替代 * delete 删除 (v0.14+ BS-新116 配套, jyzs 2026-07-02 补) * templates 选择器 (web 等价语义: 菜单/下拉/树形展示, 替代旧版样本数据端点) */ @@ -29,7 +40,9 @@ import { buildReportInfoCommand } from './info.ts' import { buildReportTemplatesCommand } from './templates.ts' import { buildReportCreateCommand } from './create.ts' import { buildReportUpdateCommand } from './update.ts' -import { buildReportReleaseCommand } from './release.ts' +import { buildReportSaveCommand } from './save.ts' // v0.16+ +import { buildReportPublishCommand } from './publish.ts' // v0.16+ +import { buildReportReleaseCommand } from './release.ts' // v0.16+ deprecated import { buildReportDeleteCommand } from './delete.ts' export function buildReportCommand(): Command { @@ -39,6 +52,10 @@ export function buildReportCommand(): Command { cmd.addCommand(buildReportTemplatesCommand()) cmd.addCommand(buildReportCreateCommand()) cmd.addCommand(buildReportUpdateCommand()) + // v0.16+ 新增 save + publish, 跟 release 拆开 + cmd.addCommand(buildReportSaveCommand()) + cmd.addCommand(buildReportPublishCommand()) + // v0.16+ release deprecated (保留到 v0.18, 之后移除) cmd.addCommand(buildReportReleaseCommand()) cmd.addCommand(buildReportDeleteCommand()) return cmd diff --git a/src/commands/report/publish.ts b/src/commands/report/publish.ts new file mode 100644 index 0000000..376f769 --- /dev/null +++ b/src/commands/report/publish.ts @@ -0,0 +1,144 @@ +/** + * commands/report/publish.ts — 发布+部署报表 (v0.16+ 新增, release → save/publish 改名) + * + * v0.16+ (2026-07-02 v0.16-1): 跟 release 拆分 + * - 旧: `dacli report release --type=1` 等价发布+部署 + * - 新: `dacli report publish` 直接发布+部署 (type 隐式 1) + * - 旧命令保留到 v0.18, 之后移除 (deprecation 周期 1 季度) + * + * v0.14 audit FINDING-R3 (2026-07-02): report release 命名误导 + * - 拆 save (type=0) + publish (type=1), 跟 web 端 /api/Report/Save 一致 + * + * 镜像源: web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts:49 saveVersion + * web 端: reportHttp.post({ url: `${Api.Prefix}/Save`, data: {...form, type: 1 } }) + * + * 端点: POST /api/Report/Save (走 32000, type=1) + * 后端: ReportController.java @PostMapping("/Save") (同 update, type 区分) + * + * v0.14+ BS-新116 (jyzs 实战): report.release --type=1 是核心工作流 + * - jyzs 实战 '卡模板态' bug 修复: type=1 把报表从模板态发布到运行态 + * - 后端 SU011 '发布成功' 响应 + */ +import { Command } from 'commander' +import { JnpfClient } from '../../core/client.ts' +import { installAiHelpHook } from '../../core/help.ts' +import { log, printJson } from '../../core/log.ts' +import { initWebapi as initReportWebapi, loadReport } from '../../webapi/report.ts' +import { validateReportCreate } from './_validate.ts' +import { enhanceFromBackend, formatErrorLine } from '../_error_codes.ts' + +interface PublishOpts { + id: string + cells?: string + dataSets?: string + columnList?: string + queryList?: string + versionId?: string + json?: boolean +} + +export function buildReportPublishCommand(): Command { + const cmd = new Command('publish') + .description( + '发布+部署报表 (v0.16+ 新增, type=1 隐式; 跟 report release --type=1 等价, 推荐用 publish 替代)', + ) + .requiredOption('--id ', '报表 id') + .option('--cells ', '设计 cells JSON 字符串 (type=1 必传, 后端校验)') + .option('--dataSets ', '数据集列表 JSON 数组字符串') + .option('--columnList ', '列定义 JSON 数组字符串') + .option('--queryList ', '查询参数 JSON 数组字符串') + .option('--versionId ', '版本 id (留空则创建新版本)') + .option('--json', '原始 JSON 输出', false) + .action(async (opts: PublishOpts) => { + const c = await JnpfClient.fromToken() + await initReportWebapi(c) + + // 拉原报表 (跟 update 一致) + const current = (await loadReport.getReportInfo(opts.id)) as Record + if (!current || !current.id) { + log.error(`report publish 失败: 拉原报表 id=${opts.id} 失败`) + process.exit(1) + } + + // step machine 校验 + const vBasic = validateReportCreate({ + fullName: current.fullName as string, + enCode: current.enCode as string, + category: current.category as string, + }) + if (!vBasic.ok) { + for (const err of vBasic.errors) log.error(` [${vBasic.stepName}] ${err.message}`) + process.exit(1) + } + + // v0.16+ (P2-2): --cells 必传 (type=1 必填) + JSON 预校验 + if (!opts.cells) { + log.error('--cells 必传 (publish 隐式 type=1, 后端要求 cells 非空)') + process.exit(1) + } + try { + JSON.parse(opts.cells) + } catch (e) { + log.error(`--cells 不是合法 JSON 字符串: ${(e as Error).message?.slice(0, 100)}`) + process.exit(1) + } + + // 构造 body (跟 release --type=1 一致, type 写死 1) + const body: Record = { + ...current, + id: opts.id, + type: 1, // v0.16+ publish 隐式 type=1 (真正发布+部署) + versionId: opts.versionId || current.versionId || null, + } + if (opts.cells !== undefined) body.cells = opts.cells + if (opts.dataSets !== undefined) body.dataSetList = opts.dataSets + if (opts.columnList !== undefined) body.columnList = opts.columnList + if (opts.queryList !== undefined) body.queryList = opts.queryList + + // 调 webapi saveVersion (走 web 端镜像, 端点 /api/Report/Save type=1) + const r = (await loadReport.saveVersion(body)) as unknown + let code: number | undefined + let msg: string | undefined + if (r && typeof r === 'object') { + const obj = r as { code?: number; msg?: string } + code = obj.code + msg = obj.msg + } + if (code !== undefined && code !== 200) { + log.error(`report publish 失败 (code=${code}): ${msg}`) + const enhanced = enhanceFromBackend(msg || '', 'report', { entity: 'report' }) + log.error(` ${formatErrorLine(enhanced, { step: 1, stepName: '后端API' })}`) + process.exit(1) + } + log.ok(`✓ 报表已发布+部署 id=${opts.id} (v0.16+ 新 publish 命令, type=1)`) + if (opts.json) printJson({ id: opts.id, code, msg, raw: r }) + }) + installAiHelpHook(cmd, { + purpose: '发布+部署报表 (v0.16+ 新增, 替代 release --type=1)', + required: { '--id': '报表 id' }, + optional: { + '--cells': '设计 cells JSON 字符串 (必传, type=1 后端校验)', + '--dataSets': '数据集列表 JSON 数组', + '--columnList': '列定义 JSON 数组', + '--queryList': '查询参数 JSON 数组', + '--versionId': '版本 id (留空创建新版本)', + }, + example: [ + 'dacli report publish --id=842032225770801349 --cells=\'{"cells":[]}\'', + 'dacli report publish --id=842032225770801349 --cells=\'{"cells":[]}\' --dataSets=\'[{"id":"ds1"}]\'', + ], + source: { + web: 'web/.../api/onlineDev/report.ts:49 saveVersion', + api: 'POST /api/Report/Save (走 webapi Proxy, 端口 32000, type=1 隐式)', + ref: 'jnpf-java-datareport-univer/.../ReportController.java @PostMapping("/Save")', + }, + notes: [ + '**v0.16+ 新增**: 跟 release 拆开, publish 隐式 type=1 (真正发布+部署)', + '**deprecation 周期**: release --type=1 仍可用到 v0.18, 之后移除 (1 季度 deprecation)', + '**跟 form release 区别**: form release 切 state 0→1, report publish 是保存+部署 (type=1)', + '**跟 save 区别**: save 只保存 (type=0), publish 是保存+部署 (type=1)', + '**BS-新116 (jyzs 实战)**: 报表从模板态发布到运行态的核心工作流', + ], + }) + return cmd +} diff --git a/src/commands/report/release.ts b/src/commands/report/release.ts index d2a1cd5..b3b388b 100644 --- a/src/commands/report/release.ts +++ b/src/commands/report/release.ts @@ -52,10 +52,10 @@ interface ReportForm { export function buildReportReleaseCommand(): Command { const cmd = new Command('release') .description( - '发布/保存报表设计 (BS-新116 jyzs 2026-07-02, 镜像 web report.ts:49 saveVersion, 走 POST /api/Report/Save)', + '⚠️ [DEPRECATED v0.16+] 发布/保存报表设计 (推荐用 save/publish). 镜像 web report.ts:49 saveVersion, 走 POST /api/Report/Save. v0.18 将移除.', ) .requiredOption('--id ', '报表 id') - .option('--type <0|1>', '类型: 0=保存设计 1=发布+部署 (默认 1)', '1') + .option('--type <0|1>', '类型: 0=保存设计 (推荐 save) 1=发布+部署 (推荐 publish), 默认 1', '1') .option('--cells ', '设计 cells JSON 字符串 (type=1 必传)') .option('--dataSets ', '数据集列表 JSON 数组字符串') .option('--columnList ', '列定义 JSON 数组字符串') @@ -63,6 +63,11 @@ export function buildReportReleaseCommand(): Command { .option('--versionId ', '版本 id (留空则创建新版本)') .option('--json', '原始 JSON 输出', false) .action(async (opts: ReleaseOpts) => { + // v0.16+ (v0.16-1) DEPRECATION 警告: 引导用户用新命令 + log.warn('⚠️ report release 命令 v0.16+ 已 deprecated, 推荐用 save/publish 替代') + log.warn(' - dacli report save (type=0 隐式, 保存设计)') + log.warn(' - dacli report publish (type=1 隐式, 发布+部署)') + log.warn(' - release 仍可用到 v0.18 (1 季度 deprecation 周期)') const c = await JnpfClient.fromToken() await initReportWebapi(c) diff --git a/src/commands/report/save.ts b/src/commands/report/save.ts new file mode 100644 index 0000000..bfc9bf9 --- /dev/null +++ b/src/commands/report/save.ts @@ -0,0 +1,139 @@ +/** + * commands/report/save.ts — 保存报表设计 (v0.16+ 新增, release → save/publish 改名) + * + * v0.16+ (2026-07-02 v0.16-1): 跟 release 拆分 + * - 旧: `dacli report release --type=0` 等价保存设计 + * - 新: `dacli report save` 直接保存 (type 隐式 0) + * - 旧命令保留到 v0.18, 之后移除 (deprecation 周期 1 季度) + * + * v0.14 audit FINDING-R3 (2026-07-02): report release 命名误导 + * - 旧 release 命令同时做 "保存设计" (type=0) 和 "发布+部署" (type=1) + * - 用户误以为是 form release (state 切换), 实际是 saveVersion (设计+部署) + * - 修复: 拆 save + publish, 跟 web 端 /api/Report/Save 一致 + * + * 镜像源: web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts:49 saveVersion + * web 端: reportHttp.post({ url: `${Api.Prefix}/Save`, data: {...form, type: 0 } }) + * + * 端点: POST /api/Report/Save (走 32000 报表微服务 jnpf-datareport-univer) + * 后端: ReportController.java @PostMapping("/Save") (同 update, type 区分) + */ +import { Command } from 'commander' +import { JnpfClient } from '../../core/client.ts' +import { installAiHelpHook } from '../../core/help.ts' +import { log, printJson } from '../../core/log.ts' +import { initWebapi as initReportWebapi, loadReport } from '../../webapi/report.ts' +import { validateReportCreate } from './_validate.ts' +import { enhanceFromBackend, formatErrorLine } from '../_error_codes.ts' + +interface SaveOpts { + id: string + cells?: string + dataSets?: string + columnList?: string + queryList?: string + versionId?: string + json?: boolean +} + +export function buildReportSaveCommand(): Command { + const cmd = new Command('save') + .description( + '保存报表设计 (v0.16+ 新增, type=0 隐式; 跟 report release --type=0 等价, 推荐用 save 替代)', + ) + .requiredOption('--id ', '报表 id') + .option('--cells ', '设计 cells JSON 字符串 (必传, saveVersion 入参)') + .option('--dataSets ', '数据集列表 JSON 数组字符串') + .option('--columnList ', '列定义 JSON 数组字符串') + .option('--queryList ', '查询参数 JSON 数组字符串') + .option('--versionId ', '版本 id (留空则创建新版本)') + .option('--json', '原始 JSON 输出', false) + .action(async (opts: SaveOpts) => { + const c = await JnpfClient.fromToken() + await initReportWebapi(c) + + // 拉原报表 (跟 update 一致, 后端 ReportUpForm 必填全字段) + const current = (await loadReport.getReportInfo(opts.id)) as Record + if (!current || !current.id) { + log.error(`report save 失败: 拉原报表 id=${opts.id} 失败`) + process.exit(1) + } + + // step machine 校验 + const vBasic = validateReportCreate({ + fullName: current.fullName as string, + enCode: current.enCode as string, + category: current.category as string, + }) + if (!vBasic.ok) { + for (const err of vBasic.errors) log.error(` [${vBasic.stepName}] ${err.message}`) + process.exit(1) + } + + // v0.16+ (P2-2): --cells JSON 预校验 + if (opts.cells) { + try { + JSON.parse(opts.cells) + } catch (e) { + log.error(`--cells 不是合法 JSON 字符串: ${(e as Error).message?.slice(0, 100)}`) + process.exit(1) + } + } + + // 构造 body (跟 release --type=0 一致, 但 type 写死 0) + const body: Record = { + ...current, + id: opts.id, + type: 0, // v0.16+ save 隐式 type=0 + versionId: opts.versionId || current.versionId || null, + } + if (opts.cells !== undefined) body.cells = opts.cells + if (opts.dataSets !== undefined) body.dataSetList = opts.dataSets + if (opts.columnList !== undefined) body.columnList = opts.columnList + if (opts.queryList !== undefined) body.queryList = opts.queryList + + // 调 webapi saveVersion (走 web 端镜像, 端点 /api/Report/Save type=0) + const r = (await loadReport.saveVersion(body)) as unknown + let code: number | undefined + let msg: string | undefined + if (r && typeof r === 'object') { + const obj = r as { code?: number; msg?: string } + code = obj.code + msg = obj.msg + } + if (code !== undefined && code !== 200) { + log.error(`report save 失败 (code=${code}): ${msg}`) + const enhanced = enhanceFromBackend(msg || '', 'report', { entity: 'report' }) + log.error(` ${formatErrorLine(enhanced, { step: 1, stepName: '后端API' })}`) + process.exit(1) + } + log.ok(`✓ 报表设计已保存 id=${opts.id} (v0.16+ 新 save 命令, type=0)`) + if (opts.json) printJson({ id: opts.id, code, msg, raw: r }) + }) + installAiHelpHook(cmd, { + purpose: '保存报表设计 (v0.16+ 新增, 替代 release --type=0)', + required: { '--id': '报表 id' }, + optional: { + '--cells': '设计 cells JSON 字符串', + '--dataSets': '数据集列表 JSON 数组', + '--columnList': '列定义 JSON 数组', + '--queryList': '查询参数 JSON 数组', + '--versionId': '版本 id (留空创建新版本)', + }, + example: [ + 'dacli report save --id=842032225770801349 --cells=\'{"cells":[]}\'', + 'dacli report save --id=842032225770801349 --cells=\'{"cells":[]}\' --dataSets=\'[{"id":"ds1"}]\'', + ], + source: { + web: 'web/.../api/onlineDev/report.ts:49 saveVersion', + api: 'POST /api/Report/Save (走 webapi Proxy, 端口 32000, type=0 隐式)', + ref: 'jnpf-java-datareport-univer/.../ReportController.java @PostMapping("/Save")', + }, + notes: [ + '**v0.16+ 新增**: 跟 release 拆开, save 隐式 type=0', + '**deprecation 周期**: release --type=0 仍可用到 v0.18, 之后移除 (1 季度 deprecation)', + '**跟 form release 区别**: form release 切 state 0→1, report save 是保存设计 (无 state 切换)', + '**跟 publish 区别**: save 只保存 (type=0), publish 是保存+部署 (type=1)', + ], + }) + return cmd +}