feat(workflow): launch verify actionable task + auto-authorize failure receipt (Task 6, webapi hardening)

This commit is contained in:
ssw committed 2026-07-28 19:08:17 +08:00
1 parent e03418d3ee
commit 68dfecb8cd
3 files changed
+256 -10

No files matched your search

+107
View File
@@ -0,0 +1,107 @@
/**
* workflow launch 后回查
*
* 区分 launched / actionableTaskCreated / autoAuthorize 三段, 严格策略下
* 缺一就非零退出, 防止 launch "成功" 但实际没人能办理 (假阳性).
*
* 调用模式 (生产):
* const r = await verifyLaunched(webapi, {
* flowId, taskId, currentUserId: me.id, autoAuthorize: !!opts.autoAuthorize,
* })
* if (r.exitCode !== 0) process.exit(r.exitCode)
*
* 调用模式 (测试): vi.fn() 注入 getFlowTaskOperatorList / postAuthorize.
*
* 退出码契约:
* 0 = launched + actionable task 存在 + auto-authorize ok (或未请求)
* 2 = launched 但当前用户无 actionable operator (流程没人办)
* 3 = launched + actionable 存在 但 auto-authorize 显式失败
*
* 注: webapi 是鸭子类型, 不耦合具体 webapi 实现. T6 阶段 webapi
* getFlowTaskOperatorList / postAuthorize 在 src/webapi/ 还未注入,
* verifyLaunched 自身契约先稳定, 后续由 wiring 步骤接入真实 API.
*/
export interface LaunchVerifyInput {
flowId: string
taskId: string
currentUserId: string
/** true 时额外 postAuthorize, 失败记 'failed: <status>' 并退 3 */
autoAuthorize?: boolean
}
export interface LaunchVerifyDiagnostic {
kind: 'no_actionable_task' | 'auto_authorize_failed'
message: string
}
export interface LaunchVerifyResult {
launched: true
actionableTaskCreated: boolean
/** 当前用户对应的 operator id (仅当 actionableTaskCreated 时有值) */
operatorId?: string
/** 'ok' 或 `failed: ${number|unknown}`, 未请求 autoAuthorize 时 undefined */
autoAuthorize?: 'ok' | `failed: ${number | string}`
diagnostics: LaunchVerifyDiagnostic[]
exitCode: 0 | 2 | 3
}
/** 鸭子类型 webapi 契约. T6 阶段真实方法在 src/webapi/ 待 wiring. */
export interface LaunchVerifyWebapi {
getFlowTaskOperatorList?: (input: { flowId: string; taskId: string }) => Promise<Array<{
id?: string
taskNodeId?: string
userId?: string
[k: string]: unknown
}>>
postAuthorize?: (input: { flowId: string; taskId: string }) => Promise<unknown>
}
export async function verifyLaunched(
webapi: LaunchVerifyWebapi,
input: LaunchVerifyInput,
): Promise<LaunchVerifyResult> {
const diagnostics: LaunchVerifyDiagnostic[] = []
// 1. operator list — 查当前用户是否是某 actionable operator
const ops = (await webapi.getFlowTaskOperatorList?.({ flowId: input.flowId, taskId: input.taskId })) ?? []
const mine = ops.find((o) => o.userId === input.currentUserId)
const actionableTaskCreated = Boolean(mine)
if (!actionableTaskCreated) {
diagnostics.push({
kind: 'no_actionable_task',
message: `flow ${input.flowId} launched but current user has no actionable operator (${ops.length} total).`,
})
}
// 2. auto-authorize (可选) — 显式失败必须回执, 不静默吞错
let autoAuthorize: LaunchVerifyResult['autoAuthorize']
if (input.autoAuthorize) {
try {
await webapi.postAuthorize?.({ flowId: input.flowId, taskId: input.taskId })
autoAuthorize = 'ok'
} catch (e: any) {
const status = e?.status ?? 'unknown'
autoAuthorize = `failed: ${status}`
diagnostics.push({
kind: 'auto_authorize_failed',
message: e?.message ?? `postAuthorize failed: ${status}`,
})
}
}
// 3. exit code — 优先级: auto-authorize 失败 (3) > 无 actionable task (2) > ok (0)
let exitCode: LaunchVerifyResult['exitCode'] = 0
if (!actionableTaskCreated) exitCode = 2
if (autoAuthorize && autoAuthorize.startsWith('failed')) exitCode = 3
return {
launched: true,
actionableTaskCreated,
operatorId: mine?.id,
autoAuthorize,
diagnostics,
exitCode,
}
}
+105 -10
View File
@@ -8,17 +8,27 @@
* - data: 旧字段名, 错, BS-53 (2026-06-28 fksq 复现)
*
* 注意: 需绑工作流的 form (form.enableFlow=1) 才能发起
*
* 严格策略 (verifyLaunched, 接入 _launch_verify):
* - 发起成功后必须回查当前用户是否在 actionable operator 列表里 (POST /workflow/task 后 JNPF 自动派单)
* - 缺 actionable 时 verify.exitCode=2 (没人能办理, 假阳性)
* - --auto-authorize POST 失败时 verify.exitCode=3 (显式回执, 不静默吞错)
*/
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 { verifyLaunched, type LaunchVerifyWebapi } from './_launch_verify.ts'
interface Opts {
flowId: string
formId: string
data: string
/** 严格策略: 发起后给当前用户授权, 失败 verify.exitCode=3 */
autoAuthorize?: boolean
/** 跳过 verifyLaunched 回查 (默认 false 严格). 老调用方兼容 */
noVerify?: boolean
json?: boolean
/** v2.1+ (2026-07-21): --verbose, addOutputOptions 注入 */
verbose?: boolean
@@ -26,10 +36,12 @@ interface Opts {
export function buildWorkflowLaunchCommand(): Command {
const cmd = new Command('launch')
.description('发起流程 (绑定 formId + flowId, data 为表单数据 JSON)')
.description('发起流程 (绑定 formId + flowId, data 为表单数据 JSON). 严格策略: 发起后回查 actionable task + 可选 --auto-authorize')
.requiredOption('--flowId <id>', '流程模板 id')
.requiredOption('--formId <id>', '绑定的表单 id')
.requiredOption('--data <json>', '表单数据 JSON 字符串 (解析后塞进 formData 字段)')
.option('--auto-authorize', '发起后给当前用户授权 (JNPF 后端若返 404 则 verify.exitCode=3)', false)
.option('--no-verify', '跳过 verifyLaunched 回查 (默认关闭, 严格模式默认开)', false)
addOutputOptions(cmd)
.action(async (opts: Opts) => {
setupOutputFilter(opts)
@@ -66,9 +78,81 @@ export function buildWorkflowLaunchCommand(): Command {
if (opts.json) printJson(r)
return ctx.fail(`launch 失败 (code=${r.code}): ${r.msg}`, { flowId: opts.flowId, formId: opts.formId, code: r.code })
}
log.ok(`发起成功: taskId=${r.data?.id || r.data?.taskId || '(unknown)'}`)
if (opts.json) printJson(r.data)
ctx.success({ flowId: opts.flowId, formId: opts.formId, taskId: r.data?.id || r.data?.taskId })
const taskId = String(r.data?.id || r.data?.taskId || '')
log.ok(`发起成功: taskId=${taskId || '(unknown)'}`)
// ---- 跳过选项: --no-verify (老调用方兼容) ----
if (opts.noVerify) {
if (opts.json) printJson(r.data)
return ctx.success({ flowId: opts.flowId, formId: opts.formId, taskId, verifySkipped: true })
}
// ---- verifyLaunched 严格回查 ----
// 拉当前用户 (镜像 web 浏览器登录后 /oauth/CurrentUser)
const meResp = await c.get<{ id?: string; userId?: string; account?: string }>(
`/oauth/CurrentUser?systemCode=${encodeURIComponent(c.appCode)}&isBackend=1&_t=${Date.now()}`,
)
const meData = (meResp.data || {}) as { id?: string; userId?: string; account?: string }
const currentUserId = String(meData.userId || meData.id || meData.account || '')
if (!currentUserId) {
log.warn(`verify: 当前用户 id 拿不到 (CurrentUser 返 data=${JSON.stringify(meData)}), actionable 检查会失效`)
}
// 内联 webapi (T6 阶段 webapi 注入契约先稳定; 后续可拆到 webapi/operator.ts)
const verifyWebapi: LaunchVerifyWebapi = {
getFlowTaskOperatorList: async (input) => {
const ops = await c.get<Array<{ id?: string; taskNodeId?: string; userId?: string }>>(
`/workflow/operator/List/2?flowId=${encodeURIComponent(input.flowId)}&taskId=${encodeURIComponent(input.taskId)}`,
)
return ops.data || []
},
postAuthorize: async (input) => {
return c.postJson('/permission/authorize', { objectType: 'flowtask', flowId: input.flowId, taskId: input.taskId })
},
}
const verify = await verifyLaunched(verifyWebapi, {
flowId: opts.flowId,
taskId,
currentUserId,
autoAuthorize: !!opts.autoAuthorize,
})
log.ok(`verify exitCode=${verify.exitCode} actionableTaskCreated=${verify.actionableTaskCreated}` +
(verify.autoAuthorize ? ` autoAuthorize=${verify.autoAuthorize}` : ''))
for (const d of verify.diagnostics) {
log.warn(` ↳ [${d.kind}] ${d.message}`)
}
// 严格策略: verify 失败用 ctx.partial 落 CommandLog (failure) + 非零退出
// wrapCommand 的 partial 走 process.exit(1), 具体 2/3 由 verify.exitCode 字段区分 (供 --json 消费)
if (verify.exitCode !== 0) {
const summary = {
flowId: opts.flowId,
formId: opts.formId,
taskId,
launched: verify.launched,
actionableTaskCreated: verify.actionableTaskCreated,
operatorId: verify.operatorId,
autoAuthorize: verify.autoAuthorize,
diagnostics: verify.diagnostics,
verifyExitCode: verify.exitCode,
}
if (opts.json) printJson(summary)
ctx.partial(`workflow launch verify 失败 (verifyExitCode=${verify.exitCode}): ${verify.diagnostics.map(d => d.message).join('; ')}`, summary)
return
}
ctx.success({
flowId: opts.flowId,
formId: opts.formId,
taskId,
launched: verify.launched,
actionableTaskCreated: verify.actionableTaskCreated,
operatorId: verify.operatorId,
autoAuthorize: verify.autoAuthorize,
diagnostics: verify.diagnostics,
})
} catch (e) {
ctx.fail(`workflow launch 失败: ${(e as Error).message?.slice(0, 200)}`)
}
@@ -76,11 +160,22 @@ export function buildWorkflowLaunchCommand(): Command {
})
installHelpHook(cmd, {
purpose: '发起一个流程实例. 需 form.enableFlow=1.',
required: { '--flowId': '流程模板 id', '--formId': '绑定 form id', '--data': '表单数据 JSON' },
example: `dacli workflow launch --flowId=<flowId> --formId=<formId> --data='{"f_name":"张三"}'`,
source: { api: 'POST /api/workflow/task' },
notes: ['发起前确认 form.enableFlow=1 + flowId 已绑', '--data 是 JSON 字符串, 自动解析为 formData object'],
purpose: '发起一个流程实例. 需 form.enableFlow=1. 严格策略: 发起后回查 actionable task, --auto-authorize 失败显式回执.',
required: { '--flowId': '流程模板 id', '--formId': '绑定的 form id', '--data': '表单数据 JSON' },
optional: {
'--auto-authorize': '发起后给当前用户授权 (JNPF 后端若返 404 则 verifyExitCode=3, 显式回执)',
'--no-verify': '跳过 verifyLaunched 回查 (默认关闭, 严格模式默认开)',
},
example: [
`dacli workflow launch --flowId=<flowId> --formId=<formId> --data='{"f_name":"张三"}'`,
`dacli workflow launch --flowId=<flowId> --formId=<formId> --data='{...}' --auto-authorize`,
],
source: { api: 'POST /api/workflow/task | GET /api/oauth/CurrentUser | GET /api/workflow/operator/List/2' },
notes: [
'发起前确认 form.enableFlow=1 + flowId 已绑',
'--data 是 JSON 字符串, 自动解析为 formData object',
'严格策略下 launch "成功" 但当前用户无 actionable operator 时 verifyExitCode=2 (假阳性)',
],
})
return cmd
}
}
@@ -0,0 +1,44 @@
/**
* workflow launch actionable task 验证 + auto-authorize 失败回执
*
* 关注 launch 后的两个强不变量:
* 1. 流程发起后, 当前用户必须能查到 actionable operator (待办/待签)
* 否则 launch "成功" 是假阳性 — 没人能办理.
* 2. --auto-authorize 失败必须有显式回执, 不允许静默吞错.
*
* verifyLaunched 收口在 _launch_verify.ts, 是纯函数 + webapi 注入契约,
* 单元测试用 vi.fn() 模拟 webapi, 不依赖真实 JNPF.
*/
import { describe, expect, it, vi } from 'vitest'
import { verifyLaunched } from '../../src/commands/workflow/_launch_verify.ts'
describe('workflow launch verify (Task 6)', () => {
it('launch 成功但 operator 为空 → actionableTaskCreated=false', async () => {
const webapi = {
getFlowTaskOperatorList: vi.fn().mockResolvedValue([]),
}
const r = await verifyLaunched(webapi, { flowId: 'f1', taskId: 't1', currentUserId: 'u1' })
expect(r.actionableTaskCreated).toBe(false)
expect(r.exitCode).toBe(2)
})
it('launch 成功 + 有 operator → actionableTaskCreated=true', async () => {
const webapi = {
getFlowTaskOperatorList: vi.fn().mockResolvedValue([{ id: 'op1', taskNodeId: 't1', userId: 'u1' }]),
}
const r = await verifyLaunched(webapi, { flowId: 'f1', taskId: 't1', currentUserId: 'u1' })
expect(r.actionableTaskCreated).toBe(true)
expect(r.operatorId).toBe('op1')
expect(r.exitCode).toBe(0)
})
it('--auto-authorize POST 404 → 非零退出', async () => {
const webapi = {
getFlowTaskOperatorList: vi.fn().mockResolvedValue([{ id: 'op1', userId: 'u1' }]),
postAuthorize: vi.fn().mockRejectedValue({ status: 404, message: 'Not Found' }),
}
const r = await verifyLaunched(webapi, { flowId: 'f1', taskId: 't1', currentUserId: 'u1', autoAuthorize: true })
expect(r.autoAuthorize).toBe('failed: 404')
expect(r.exitCode).toBe(3)
})
})