Files
dacli/src/commands/report/create.ts
T
ssw df213fdfad fix(dacli-docs): 修审计报告 14 项 + 加 CI 校验防再漂 (P0/P1/P2 全清)
审计报告 docs/dacli-doc-audit-report.md 14 项全部采纳:

P0 (3 项事实错误, 直接误导 AI 执行):
- ANTI_PATTERN F_→f_ 前缀 (form update --fields 实际是小写)
- ANTI_PATTERN AP-fc-4 vs AP-fu-1 矛盾 (统一指向 form import --autoTable)
- ANTI_PATTERN form info <enCode> 误导 (改为 <id>, 加 enCode 自动解析 fallback)

P1 (3 项文档漂移):
- CLAUDE.md "含 FK 时必用 --fields" → 实际已废弃, 删除 + form/create.ts Commander 加 DEPRECATED
- doc/get.ts 引用 Java DocCommand.java → 改指 TS _parser.ts
- AP-fd-1 "--cascade 必带" 过度约束 → 改为可选

P2 (2 项衔接断裂):
- Source 路径 web/.../ → web/apps/jnpf-web-apps-main/src/ (73 文件)
- test/run TC-B 前置提示 (需 menu 挂载)

附加 (CI script 抓出的 8 条额外路径 drift, 已就近修正):
- di/create|export|copy: DataInterfaceController.java 路径补 jnpf-java-boot/ + jnpf/base/controller/
- print/delete|update: PrintDevController.java 同上
- org/create: OrganizeController.java 路径 jnpf/controller/ → jnpf/permission/controller/
- form/codegen|audit: FormGenerator/FormGenerator.vue 加 /components/ + /src/ 前缀
- workflow/create: flowEngine + FlowProcess 加 views/onlineDev/ + components/ 前缀
- workflow/syncForm: FlowableProcessDesigner.vue 不存在 → 改指 Form.vue
- msg/notice*: notice.ts 不存在 → 改指 msgMonitor.ts
- bigscreen/delete|update: 双前缀 web/.../src/jnpf-web-datascreen-vue3/ → jnpf/前端/
- app/login: api/auth.ts → api/core/auth.ts
- apis/refresh|status|info: Java ApiService 路径 → TS 化指向
- test/render: sysData/formDesign 加 views/ 前缀
- form/create: formDesign/Form.vue 加 views/onlineDev/ 前缀

Task 1.6 收尾: 删 core/help.ts legacy (~85 行 dead code):
- AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp
- installAiHelpHook alias / _aiMeta 副作用 / AiHelp type alias

新增 docs/doc-drift-findings-2026-07-24.md (2 条无法自动修复的 docs 路径, 待人工)

新增 scripts/check-doc-drift.ts (scripts/check-doc-drift.ts, 218 行):
- 4 类检查: 命令引用 / arg-opt 一致性 / source 路径 / ANTI_PATTERNS 命令引用
- 接入 npm run doc:check
- 验证: 修复前 21 处 drift → 修复后 2 处 (已归档)

测试: typecheck 0 errors, 387/387 tests pass, doc:check 报告 2 known issues
2026-07-24 16:33:31 +08:00

211 lines
11 KiB
TypeScript

/**
* commands/report/create.ts — 新建报表模板 (v0.13+ 镜像 web 端)
*
* v0.14+ (2026-07-01 P0 webapi rollout): 已切到 webapi/report.ts (createReport)
* - 之前直接 c.postJson('/api/Report') — 经验复刻, 与 web 端 schema 漂移风险
* - 现在 webapi 镜像: 复用 web 端 createReport (走 reportHttp, 端口 32000 报表服务)
*
* 镜像源: web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts:17 createReport
* web/apps/jnpf-web-apps-main/src/views/onlineDev/report/Form.vue: handleSubmit: 'const query = { ...values, id }; createReport(query)'
* 后端: jnpf-java-datareport-univer/.../ReportController.java POST /api/Report
* 端口 32000 独立微服务 (nginx 代理 /api/Report/ → jnpf:32000)
*
* v0.14+ 增强:
* - 走完整 webapi/initWebapi(c) + loadReport.createReport 链路 (与 v3.0+ 一致)
* - 后端 ReportController.create() 返 {code:200, msg:'新建成功', data: <id 字符串>}
* - shim unwrap 已经解出 data=<id>, 直接拿 r.data 即可
* - BACKEND-7 已修 (2026-07-21): nginx /api/Report 尾 slash 调整后, create 返 200 (testspace 验证 id=849221845...)
*/
import { Command } from 'commander'
import { JnpfClient } from '../../core/client.ts'
import { installHelpHook } 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' // v0.15+ (P1-1, 2026-07-02): 4 命令接入 _validate
import { setupOutputFilter, addOutputOptions, wrapCommand } from '../_output_filter.ts' // v2.1+ 输出过滤; v2.2+ wrapCommand 收口 5c
import { runCommandAutoFix, fetchExistingLists } from '../_auto_fix.ts' // v2.1+ (2026-07-21): 命令级 auto-fix pipeline (S-X1 enCode strip / S-X2 fullName soften / G-X1 BS-47 重名 suggest), 替代原 inline autoStripEnCode (BS-新38)
interface CreateOpts {
fullName: string
enCode: string
category?: string
description?: string
sortCode?: string
cells?: string
snapshot?: string
/** v0.21+ (Round 12 fix): 从 JSON 文件读 baseline 完整 cells + snapshot, 替代空 placeholder */
fromJsonFile?: string
json?: boolean
/** v2.1+ (2026-07-21): --verbose, addOutputOptions 注入 */
verbose?: boolean
}
/** 后端 ReportController.create() 返 {code, msg, data: <id string>} → shim 解出后是 id */
type CreateResp = string | { id?: string; code?: number; msg?: string; data?: string }
export function buildReportCreateCommand(): Command {
const cmd = new Command('create')
.description('新建报表模板 (镜像 web report.ts:17 createReport, 走 /api/Report 端口 32000)')
.requiredOption('--fullName <n>', '报表名称 (镜像 web Form.vue field:fullName)')
.requiredOption('--enCode <e>', '英文编码 (镜像 web Form.vue field:enCode, BS-56 字符限制)')
.option('--category <c>', '分类 (镜像 web Form.vue field:category)', '报表示例')
.option('--description <d>', '说明 (镜像 web Form.vue field:description)')
.option('--sortCode <s>', '排序码 (镜像 web Form.vue field:sortCode, 0-999999)', '0')
.option('--cells <json>', '模板内容 cells (镜像 web Form.vue field:cells, JSON 字符串)', '{"cells":[]}')
.option('--snapshot <s>', '模板快照 (镜像 web Form.vue field:snapshot)')
// v0.21+ (Round 12 fix BS-新40): 从 JSON 文件读 baseline 完整 cells + snapshot
// Round 12 用 `--cells '{"cells":[]}'` 默认空 stub 创建, baseline 126k-466k chars 全丢 → cells_drift=5
// 现在传 baseline 的 f_content JSON 文件, 透传到 createReport
.option('--from-json-file <f>', '从 JSON 文件读 baseline 完整 schema (含 cells/snapshot, BS-新40 修复)')
addOutputOptions(cmd)
.action(async (opts: CreateOpts) => {
// 输出过滤: 默认静默 (quiet mode), --verbose 走完整日志, --json 走原始 JSON
setupOutputFilter(opts)
const c = await JnpfClient.fromToken()
await wrapCommand({
command: 'report create',
appCode: c.appCode,
startTime: Date.now(),
verbose: opts.verbose,
json: opts.json,
fixes: [],
}, async (ctx) => {
try {
// v2.1+ (2026-07-21): 命令级 auto-fix pipeline (替代原 inline autoStripEnCode, BS-新38)
// S-X1 enCode strip silent — autoStripEnCode
// S-X2 fullName soften silent — autoStripFullName
// G-X1 BS-47 重名 suggest — 含 <appCode> 前缀建议
const fixCtx = await fetchExistingLists(c, c.appCode)
const cmdFix = runCommandAutoFix(opts as unknown as Record<string, unknown>, fixCtx)
if (cmdFix.silent.length > 0) {
Object.assign(opts, cmdFix.opts)
}
// v0.15+ (P1-1, 2026-07-02): step machine 校验 (之前 _validate.ts 71 行零引用)
// 镜像 web onlineDev/report/Form.vue:26-58 schemas (fullName maxlength 100, enCode 正则, category 必填)
const validation = validateReportCreate({
fullName: opts.fullName,
enCode: opts.enCode,
category: opts.category,
sortCode: opts.sortCode,
description: opts.description,
})
if (!validation.ok) {
const errLines: string[] = []
for (const step of validation.steps) {
for (const err of step.errors) {
const msg = ` [${step.stepName}] ${err.message}`
errLines.push(msg)
log.error(msg)
}
}
return ctx.fail(errLines.join('; '), { enCode: opts.enCode, errorCount: errLines.length })
}
// v0.14+ webapi 化: 走 webapi/report.initWebapi + loadReport.createReport
// - 镜像 web 端 createReport (走 reportHttp, 端口 32000 报表服务)
// - 不直接 c.postJson('/api/Report') — 那是经验复刻, web 端 schema 变了会漂移
await initReportWebapi(c)
// 镜像 web 端 web/apps/jnpf-web-apps-main/src/views/onlineDev/report/Form.vue handleSubmit:
// const query = { ...values, id: state.dataForm.id };
// const formMethod = state.dataForm.id ? updateReport : createReport;
// formMethod(query);
// v0.21+ (Round 12 fix BS-新40): --from-json-file 优先, 直接读完整 body 透传 baseline cells/snapshot
let query: Record<string, unknown>
if (opts.fromJsonFile) {
const { readFileSync, existsSync } = await import('node:fs')
if (!existsSync(opts.fromJsonFile)) {
const errMsg = `--from-json-file 文件不存在: ${opts.fromJsonFile}`
log.error(errMsg)
return ctx.fail(errMsg, { enCode: opts.enCode, fromJsonFile: opts.fromJsonFile })
}
try {
const jsonBody = JSON.parse(readFileSync(opts.fromJsonFile, 'utf-8'))
// 必填字段覆盖 (file 提供的是 raw schema)
jsonBody.fullName = opts.fullName
jsonBody.enCode = opts.enCode
jsonBody.category = opts.category || jsonBody.category || '报表示例'
if (opts.sortCode !== undefined) jsonBody.sortCode = Number(opts.sortCode)
if (opts.description) jsonBody.description = opts.description
if (opts.snapshot) jsonBody.snapshot = opts.snapshot
if (opts.cells) jsonBody.cells = opts.cells
jsonBody.enabledMark = jsonBody.enabledMark ?? 1
query = jsonBody
log.ok(`✓ 从 ${opts.fromJsonFile} 加载完整 schema, BS-新40 fix: baseline cells 透传`)
log.info(` 提示: file 必须含 cells (ureport XML JSON) + snapshot, 否则后端不会接收`)
} catch (e) {
const errMsg = `--from-json-file 解析失败: ${(e as Error).message?.slice(0, 200)}`
log.error(errMsg)
return ctx.fail(errMsg, { enCode: opts.enCode })
}
} else {
query = {
fullName: opts.fullName,
enCode: opts.enCode,
category: opts.category || '报表示例',
sortCode: Number(opts.sortCode) || 0,
description: opts.description || '',
cells: opts.cells || '{"cells":[]}',
snapshot: opts.snapshot || '',
enabledMark: 1,
}
}
// 调用 web 端 createReport (走 reportHttp, 端口 32000)
// web 端 defHttp 对 POST 返 {code, msg, data} → shim unwrap 解出 data = <id 字符串>
const r = (await loadReport.createReport(query)) as CreateResp
// BS-新12 v2 (jxcj 2026-07-01): jnpf 报表后端可能返纯字符串 id 或 { id, code, msg }
let id: string | undefined
if (typeof r === 'string') {
id = /^\d+$/.test(r.trim()) ? r.trim() : undefined
} else if (r && typeof r === 'object') {
id = r.data || r.id
if (r.code !== undefined && r.code !== 200) {
const errMsg = `report create 失败 (code=${r.code}): ${r.msg}`
log.error(errMsg)
return ctx.fail(errMsg, { enCode: opts.enCode, code: r.code })
}
}
if (!id) {
const errMsg = `BS-新12 silent fail: report create 后端返 code=200 但 r 不可解析为 id. 实际 raw: ${JSON.stringify(r).slice(0, 200)}`
log.error(errMsg)
return ctx.fail(errMsg, { enCode: opts.enCode, raw: JSON.stringify(r).slice(0, 200) })
}
log.ok(`✓ 报表创建成功 id=${id} enCode=${opts.enCode} (镜像 web 端 report.ts:17 createReport)`)
const summary = { id, enCode: opts.enCode, raw: r }
if (opts.json) printJson(summary)
ctx.success(summary)
} catch (e) {
ctx.fail(`report create 失败: ${(e as Error).message?.slice(0, 200)}`)
}
})
})
installHelpHook(cmd, {
purpose: '新建报表模板 (jnpf 6.x 6.2.0, 走独立报表服务 /api/Report 端口 32000)',
required: { '--fullName | --enCode': '中文名 + 英文编码 (BS-56 字符限制)' },
optional: {
'--category': '分类 (默认 "报表示例")',
'--description': '说明',
'--cells': '模板内容 JSON',
'--snapshot': '模板快照',
},
example: [
'dacli report create --fullName=月销售报表 --enCode=MonthlySales',
'dacli report create --fullName=Jxcj综合排名 --enCode=JxcjFinalRankingReport --category=大赛报表 --cells=\'{"cells":[]}\'',
],
source: {
web: 'web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts:17 createReport + report/Form.vue handleSubmit',
api: 'POST /api/Report (走 webapi/report Proxy, 端口 32000 报表服务)',
ref: 'jnpf-java-datareport-univer/.../ReportController.java + ReportCrForm.java',
},
notes: [
'v0.14+ 改用 webapi 镜像 (loadReport.createReport), 不直接 c.postJson',
'启动 32000 报表服务: java -Dloader.path=boot/report/lib/ -jar boot/report/jnpf-datareport-univer-admin-*.jar (见 CLAUDE.md §常用命令)',
],
})
return cmd
}