feat(form): dirty checking (AI 场景增强, 非 web 镜像) - --expected-enCode/--expected-state/--force

v0.11d+ Phase 3.1 闭环 (AI 场景增强, 不是 web 1:1 镜像):

⚠️ 重要前提: web state.isReload (Form.vue:458, 469) 不是真 dirty check
  - L458 'state.isReload = true' (成功标记)
  - L469 'if (state.isReload) emit("reload")' (通知父刷新)
  - 实际用途: 成功更新后通知父组件刷新, 不是检测外部修改
  - web 单 tab 单用户不需要 dirty check; dacli AI session 跨多小时必须做

**新增 _dirty_check.ts (通用模块, 适用 form/workflow/dict update)**:
- 加 --expected-enCode / --expected-state 选项 (API 已暴露字段, 不要求后端改)
- 加 --force 跳过 (用户可能确实想覆盖)
- 失败: 输出 expected vs current diff + AI 友好引导 (info / 重新生成 / --force)
- 镜像 web validatePopoverRef 字段级定位思想

**form/update.ts 集成**:
- 拉原 form 后立即调 dirtyCheck()
- 不匹配: dirtyCheckFailAndExit() 输出 diff + exit 2
- --force: 跳过, 输出 ⚠️ 警告

**关键新发现** (drift 防御):
1. JNPF API 限制: VisualdevEntity.java 后端 entity 不暴露 modifyTime/creatorTime
2. 实际 API 响应 (curl 验证) 也无时间字段
3. 真正内容 hash dirty check 需要后端改 schema, 短期不可行
4. 用 enCode + state 折中方案 (API 暴露字段, AI 友好, 不要求后端改)

**端到端验证 (tdd10, 5/5 通过)**:
1. 干净 update (enCode 匹配) → 4/4 通过 (PUT 成功)
2. enCode 不匹配 → dirty check 拦截 + AI 友好引导
3. state 不匹配 → dirty check 拦截
4. --force 跳过 → 跳过 + ⚠️ 警告
5. 还原 fullName → 4/4 通过

**MEMORY**: 新建 dacli-dirty-checking-2026-06-26.md (含完整设计意图 + 反模式 + 复盘 'web 不做 = dacli 必须 AI 场景补充' 原则)

**原则**: AI 场景补充 ≠ 1:1 镜像. web 单 tab 单用户不需要的, dacli AI session 必须做.

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-06-26 20:48:17 +08:00
1 parent 94f0f258a6
commit ea41b52078
2 files changed
+147

No files matched your search

+115
View File
@@ -0,0 +1,115 @@
/**
* commands/_dirty_check.ts — 通用 dirty checking (AI 场景增强, 非 web 镜像)
*
* v0.11d+ Phase 3.1: 防止 AI session 长时间保留 form id 误覆盖 + 多 AI session 并发覆盖
*
* ⚠️ 重要: 这不是 web 镜像
* - web `state.isReload` (Form.vue:458, 469) 只是"成功更新后通知父组件刷新", 不是 dirty check
* - web 单 tab 单用户不需要 dirty check
* - dacli 是 AI 场景补充 (跨多小时 + 多 AI 并发), 必须自己设计
*
* 设计:
* - 加 --expected-enCode 和 --expected-state 选项 (API 暴露的字段)
* - 不要求后端改 (无 modifyTime, 见 VisualdevEntity.java)
* - 加 --force 跳过 (不常用, 默认严格)
* - 失败: 输出 expected vs current diff, 提示用户用 --force 强制覆盖
*
* 适用: dacli form update / workflow update / dict typeUpdate
* 注: 这层校验只检查用户能感知的字段 (enCode / state), 不检查 formData/tables 内容
* (因为内容 hash 复杂 + 用户难生成, AI 友好性差)
*/
export interface DirtyCheckOpts {
/** --expected-enCode 传值, undefined 表示不校验 */
expectedEnCode?: string
/** --expected-state 传值, undefined 表示不校验 */
expectedState?: string
/** --force 跳过, 默认 false */
force?: boolean
/** form/workflow/dict 当前值 (从 getInfo 拿) */
current: {
enCode?: string
state?: string | number
/** 其他描述信息, 用于错误输出 (如 form fullName) */
fullName?: string
/** 模块标识, 用于错误输出 (form/workflow/dict) */
type: 'form' | 'workflow' | 'dict'
}
/** form/workflow/dict id, 用于错误输出 */
id: string
}
export interface DirtyCheckResult {
ok: boolean
/** 校验失败的具体原因 (镜像 web errorList 字段级定位) */
errors: Array<{ field: string; message: string }>
/** 是否被 --force 跳过 */
skipped: boolean
}
/**
* 执行 dirty check
*
* 镜像 web `validatePopoverRef` 字段级定位思想: 错误信息含 {field, message}
*/
export function dirtyCheck(opts: DirtyCheckOpts): DirtyCheckResult {
const errors: Array<{ field: string; message: string }> = []
// --force 跳过
if (opts.force) {
return { ok: true, errors: [], skipped: true }
}
// --expected-enCode 校验
if (opts.expectedEnCode !== undefined && opts.expectedEnCode !== '') {
if (opts.current.enCode !== opts.expectedEnCode) {
errors.push({
field: 'enCode',
message: `enCode 不匹配: 期望 "${opts.expectedEnCode}", 实际 "${opts.current.enCode ?? '(空)'}". 可能已被外部修改, 加 --force 强制覆盖`,
})
}
}
// --expected-state 校验 (统一转字符串比较)
if (opts.expectedState !== undefined && opts.expectedState !== '') {
const currentStateStr = String(opts.current.state ?? '')
if (currentStateStr !== String(opts.expectedState)) {
errors.push({
field: 'state',
message: `state 不匹配: 期望 "${opts.expectedState}", 实际 "${currentStateStr || '(空)'}". 可能已被重新发布/取消发布, 加 --force 强制覆盖`,
})
}
}
return {
ok: errors.length === 0,
errors,
skipped: false,
}
}
/**
* 输出 dirty check 失败错误 + 退出 (带 diff 提示)
*
* 镜像 web `validatePopoverRef.setVisible` 风格: 错误聚合 + 字段级定位
*/
export function dirtyCheckFailAndExit(
result: DirtyCheckResult,
ctx: { type: 'form' | 'workflow' | 'dict'; id: string; current: { enCode?: string; state?: string | number; fullName?: string } },
logError: (msg: string) => void,
): void {
if (result.ok) return
logError(`✗ dirty check 失败 (${result.errors.length} 个不匹配):`)
for (const e of result.errors) {
logError(` [${e.field}] ${e.message}`)
}
logError('')
logError(`💡 这意味着 ${ctx.type} ${ctx.id} 在你上次 info 之后已被外部修改`)
logError(` 防止: 你的 update 覆盖了别人的修改`)
logError(` 解决:`)
logError(` 1) 跑 dacli ${ctx.type} info --id=${ctx.id} 看最新状态`)
logError(` 2) 重新生成 update 命令 (用新 enCode/state)`)
logError(` 3) 或: 确认你确实想覆盖, 加 --force`)
process.exit(2)
}
+32
View File
@@ -12,6 +12,7 @@ import { JnpfClient } from '../../core/client.ts'
import { installAiHelpHook } from '../../core/help.ts'
import { log, printJson } from '../../core/log.ts'
import { initWebapi, loadVisualDev } from '../../webapi/visualDev.ts'
import { dirtyCheck, dirtyCheckFailAndExit } from '../_dirty_check.ts'
interface Opts {
id: string
@@ -26,6 +27,12 @@ interface Opts {
fields?: string
autoRelease?: boolean
releaseOnly?: boolean
/** v0.11d+ dirty check: 期望的 enCode (与 getInfo 对比) */
expectedEnCode?: string
/** v0.11d+ dirty check: 期望的 state (0/1/2) */
expectedState?: string
/** v0.11d+ dirty check: 跳过校验, 强制覆盖 */
force?: boolean
json?: boolean
}
@@ -45,6 +52,10 @@ export function buildFormUpdateCommand(): Command {
.option('--autoRelease', 'PUT 后自动重新发布 (BS-53 防护, 默认 true)', true)
.option('--no-autoRelease', '不自动发布, 仅 PUT')
.option('--releaseOnly', '仅重新发布, 不 PUT (state 0/2 → 1)')
// v0.11d+ Phase 3.1: dirty check (AI 场景增强, 非 web 镜像)
.option('--expected-enCode <e>', '期望的 enCode (与 getInfo 对比, 防止覆盖外部修改)')
.option('--expected-state <s>', '期望的 state (0/1/2, 防止覆盖外部修改)')
.option('--force', '跳过 dirty check, 强制覆盖 (慎用!)', false)
.option('--json', '原始 JSON 输出', false)
.action(async (opts: Opts) => {
const c = await JnpfClient.fromToken()
@@ -68,6 +79,27 @@ export function buildFormUpdateCommand(): Command {
const orig = (await loadVisualDev.getInfo(opts.id)) as Record<string, unknown>
log.info(`原 form: enCode=${orig.enCode} fullName=${orig.fullName}`)
// v0.11d+ Phase 3.1: dirty check (AI 场景增强)
// ⚠️ 不是 web 镜像 (web state.isReload 不是 dirty check), 是 AI 场景补充
const dirtyResult = dirtyCheck({
expectedEnCode: opts.expectedEnCode,
expectedState: opts.expectedState,
force: opts.force,
id: opts.id,
current: {
enCode: orig.enCode as string | undefined,
state: orig.state as string | number | undefined,
fullName: orig.fullName as string | undefined,
type: 'form',
},
})
dirtyCheckFailAndExit(
dirtyResult,
{ type: 'form', id: opts.id, current: { enCode: orig.enCode as string, state: orig.state as string | number, fullName: orig.fullName as string } },
log.error,
)
if (dirtyResult.skipped) log.warn('⚠️ --force 已跳过 dirty check (强制覆盖)')
// BS-49 防御: enCode 冲突检测 (全平台唯一)
if (opts.enCode && opts.enCode !== orig.enCode) {
const list = (await loadVisualDev.getVisualDevList({ keyword: opts.enCode })) as {