Files
dacli/src/commands/workflow/update.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

239 lines
12 KiB
TypeScript

/**
* commands/workflow/update.ts — 流程模板修改
*
* v0.11+ Phase 2: webapi 化 (loadWorkflow.getInfo + update)
* 替代 v0.10 直接 c.get/c.putJson
*/
import { Command } from 'commander'
import { JnpfClient } from '../../core/client.ts'
import { installHelpHook } from '../../core/help.ts'
import { log, printJson } from '../../core/log.ts'
import { setupOutputFilter, addOutputOptions, wrapCommand } from '../_output_filter.ts' // v2.1+ 输出过滤; v2.2+ wrapCommand 收口 5c
import { initWebapi, loadWorkflow } from '../../webapi/workflow.ts'
import { enhanceFromBackend, formatErrorLine } from '../_error_codes.ts'
import { dirtyCheck, dirtyCheckFailAndExit, DirtyCheckError, logDirtyCheckSkip, buildDirtyCheckSkipFix } from '../_dirty_check.ts'
interface Opts {
id: string
fullName?: string
enCode?: string
category?: string
enabledMark?: string
description?: string
/** v0.12+ 绑定 start node 的 formId (流程-form 绑定, 后端 TemplateNodeEntity.formId) */
startFormId?: string
expectedEnCode?: string
expectedState?: string
force?: boolean
json?: boolean
/** v2.1+ (2026-07-21): --verbose, addOutputOptions 注入 */
verbose?: boolean
}
export function buildWorkflowUpdateCommand(): Command {
const cmd = new Command('update')
.description('流程模板修改 (PUT 语义, v0.11+ webapi)')
.requiredOption('--id <id>', '流程模板 id')
.option('--fullName <n>', '中文名')
.option('--enCode <e>', '英文编码')
.option('--category <c>', '分类 id')
.option('--enabledMark <0|1>', '启用/禁用')
.option('--description <d>', '描述')
/** v0.12+ Bug 3 修复: 绑定 start node formId (流程-form 绑定, TemplateNodeEntity.formId) */
.option('--startFormId <id>', '绑定 start node 的表单 id (配合 --enabledMark=1 使用)')
.option('--expected-enCode <e>', 'v0.11e+ Phase A2: 校验 enCode 未变 (防 AI session 误覆盖)')
.option('--expected-state <s>', 'v0.11e+ Phase A2: 校验 enabledMark 未变')
.option('--force', 'v0.11e+ Phase A2: 跳过 dirty check', false)
addOutputOptions(cmd)
.action(async (opts: Opts) => {
setupOutputFilter(opts)
const c = await JnpfClient.fromToken()
await wrapCommand({
command: 'workflow update',
appCode: c.appCode,
startTime: Date.now(),
verbose: opts.verbose,
json: opts.json,
fixes: [],
}, async (ctx) => {
try {
await initWebapi(c)
// === step 0 拉原流程模板 ===
const orig = (await loadWorkflow.getInfo(opts.id)) as Record<string, unknown>
if (!orig) {
log.error(`workflow update 失败: 拉原模板 id=${opts.id} 失败`)
return ctx.fail(`拉原模板 id=${opts.id} 失败`, { id: opts.id })
}
// === step 1 dirty check (Phase A2) ===
const dirtyResult = dirtyCheck({
expectedEnCode: opts.expectedEnCode,
expectedState: opts.expectedState,
force: opts.force,
current: {
enCode: orig.enCode as string | undefined,
state: orig.enabledMark as string | number | undefined,
fullName: orig.fullName as string | undefined,
type: 'workflow',
},
id: opts.id,
})
try {
dirtyCheckFailAndExit(
dirtyResult,
{ type: 'workflow', id: opts.id, current: { enCode: orig.enCode as string | undefined, fullName: orig.fullName as string | undefined } },
log.error,
)
} catch (e) {
if (e instanceof DirtyCheckError) {
return ctx.fail(e.message, { id: opts.id, type: 'workflow', errorCount: e.errorCount })
}
throw e
}
if (dirtyResult.skipped) {
logDirtyCheckSkip('workflow', opts.id, opts.expectedEnCode, opts.expectedState)
ctx.addFix(buildDirtyCheckSkipFix('workflow', opts.id))
}
// === step 2 --enabledMark=1 走 saveFlow (type=1) 发布流 ===
if (opts.enabledMark !== undefined && parseInt(opts.enabledMark, 10) === 1) {
const emVal = parseInt(opts.enabledMark, 10)
if (emVal !== 1) {
log.error('--enabledMark=0 后端无对应 API, 需 SQL 直接更新 F_ENABLED_MARK=0 (不在 dacli 范围)')
log.info('提示: 用 web 端"下架"按钮操作 (UpDownShelf 端点, 但只改 status 不改 enabledMark)')
return ctx.fail(`--enabledMark=0 后端无对应 API`, { id: opts.id })
}
let flowId = (orig.flowId as string | undefined) || ''
let flowXml = (orig as { flowXml?: string }).flowXml || ''
let flowNodes = (orig as { flowNodes?: Record<string, unknown> }).flowNodes || {}
if (!flowId || !flowXml) {
log.info(`getInfo 缺 flowId/flowXml, 从 Version 列表兜底拉`)
try {
const versions = (await loadWorkflow.getVersionList(opts.id)) as Array<{
id: string
state: number
}>
if (Array.isArray(versions) && versions.length > 0) {
flowId = versions[0].id
const fullInfo = (await loadWorkflow.getFlowInfo(flowId)) as {
flowXml?: string
flowNodes?: Record<string, unknown>
flowConfig?: string
}
if (fullInfo.flowXml) flowXml = fullInfo.flowXml
if (fullInfo.flowNodes) flowNodes = fullInfo.flowNodes
log.info(`兜底拉取 flowId=${flowId}, flowXml 长度=${flowXml.length}`)
}
} catch (e) {
log.warn(`Version/Info 拉取失败: ${(e as Error).message?.slice(0, 100)}`)
}
}
if (opts.startFormId) {
log.info(`绑定 start node formId = ${opts.startFormId}`)
const nodes = flowNodes as Record<string, Record<string, unknown>>
let boundCount = 0
for (const [code, node] of Object.entries(nodes)) {
const t = String(node.type || node.nodeType || '').toLowerCase()
if (t === 'start' || t === '0' || t.includes('startevent')) {
node.formId = opts.startFormId
boundCount++
log.info(` ✓ start node ${code}.formId = ${opts.startFormId}`)
}
}
if (boundCount === 0) {
log.warn(`未找到 start 节点 (flowNodes keys: ${Object.keys(nodes).join(', ')})`)
log.info('尝试根据节点名称 (nodeName 含"发起"或"start") 兜底')
for (const [code, node] of Object.entries(nodes)) {
const name = String(node.nodeName || '').toLowerCase()
if (name.includes('发起') || name.includes('start')) {
node.formId = opts.startFormId
boundCount++
log.info(` ✓ 兜底 start node ${code}.formId = ${opts.startFormId} (匹配 nodeName="${node.nodeName}")`)
break
}
}
}
}
if (!flowId) {
log.error('发布失败: workflow 未保存 flowId (需先创建/导入, 调 saveFlow 必须有 flowId)')
log.info('提示: 用 web 端流程设计器先保存一次, 生成 flowId')
return ctx.fail(`发布失败: workflow 未保存 flowId`, { id: opts.id })
}
if (!flowXml) {
log.error('发布失败: flowXml 为空 (无法发布, BPMN 图为空)')
log.info('提示: 用 web 端流程设计器设计流程图后保存')
return ctx.fail(`发布失败: flowXml 为空`, { id: opts.id })
}
log.info(`发布流 (saveFlow, type=1) — id=${opts.id} flowId=${flowId}`)
const sr = (await loadWorkflow.saveFlow({
id: opts.id,
flowId,
flowXml,
flowNodes,
flowConfig: (orig as { flowConfig?: string }).flowConfig || '{}',
type: 1,
})) as { code?: number; msg?: string }
if (sr.code !== 200 && sr.code !== undefined) {
log.error(`saveFlow 失败 code=${sr.code}: ${sr.msg}`)
return ctx.fail(`saveFlow 失败 (code=${sr.code}): ${sr.msg}`, { id: opts.id, code: sr.code })
}
log.ok(`✓ 已启用 (saveFlow type=1) — enabledMark=1, status=UP (id=${opts.id})`)
const summary = { id: opts.id, action: 'enabled-via-saveFlow' }
if (opts.json) printJson(summary)
return ctx.success(summary)
}
const body: Record<string, unknown> = { ...orig, id: opts.id }
if (opts.fullName) body.fullName = opts.fullName
if (opts.enCode) body.enCode = opts.enCode
if (opts.category) body.category = opts.category
if (opts.enabledMark !== undefined && parseInt(opts.enabledMark, 10) !== 1) {
log.warn('--enabledMark=0 后端无 API 支持, 跳过 enabledMark 字段 (仅改 fullName/enCode/category)')
}
if (opts.description) body.description = opts.description
log.info(`loadWorkflow.update (id=${opts.id})`)
const r = (await loadWorkflow.update(body)) as { code?: number; msg?: string; data?: unknown }
if (r.code !== 200 && r.code !== undefined) {
const enhanced = enhanceFromBackend(r.msg || '', 'workflow', { entity: 'workflow' })
log.error(` ${formatErrorLine(enhanced, { step: 1, stepName: '后端API' })}`)
if (opts.json) printJson(r)
return ctx.fail(`workflow update 失败 (code=${r.code}): ${r.msg}`, { id: opts.id, code: r.code })
}
log.ok(`✓ 流程模板更新成功 (id=${opts.id})`)
const summary = { id: opts.id, action: 'updated' }
if (opts.json) printJson(r.data ?? summary)
ctx.success(summary)
} catch (e) {
ctx.fail(`workflow update 失败: ${(e as Error).message?.slice(0, 200)}`)
}
})
})
installHelpHook(cmd, {
purpose: '流程模板修改 (PUT 语义). v0.12+ Bug 2 修: --enabledMark=1 走 saveFlow; Bug 3 修: --startFormId 绑 start node 表单',
required: { '--id': '流程模板 id' },
optional: {
'--fullName': '中文名',
'--enCode': '英文编码',
'--category': '分类 id',
'--enabledMark': '启用/禁用 0|1 (1 走 saveFlow 发布流, 后端才会 setEnabledMark(1) + setStatus(UP))',
'--description': '描述',
'--startFormId': '绑定 start node 的表单 id (Bug 3 修, 配合 --enabledMark=1)',
'--expected-enCode': '防 AI 误覆盖 (A2)',
'--expected-state': '防 AI 误覆盖 (A2)',
'--force': '跳过 dirty check (A2)',
},
example: [
'dacli workflow update --id=123 --enabledMark=1 --startFormId=840790907757264901',
'dacli workflow update --id=123 --fullName=新名',
],
source: { api: 'PUT /api/workflow/template/{id} + POST /template/Save (publish)', ref: 'web/apps/jnpf-web-apps-main/src/api/workFlow/template.ts update() + saveFlow()' },
notes: [
'v0.11+ 改用 webapi 镜像 (loadWorkflow.update)',
'v0.11e+ Phase A2: dirty check --expected-enCode/--expected-state/--force (防 AI session 长时间保留误覆盖, 同 form/update.ts)',
'v0.12+ Bug 2 修: --enabledMark=1 走 saveFlow (后端 TemplateJsonServiceImpl.save type=1 才会 setEnabledMark(1))',
'v0.12+ Bug 3 修: --startFormId 把表单绑到 start node (后端 TemplateNodeEntity.formId, 流程-form 绑定走 workflow 端不是 form 端)',
],
})
return cmd
}