From 4cc0df3ced07ffc10111031aa10b11ab34040043 Mon Sep 17 00:00:00 2001 From: ssw Date: Fri, 24 Jul 2026 15:57:01 +0800 Subject: [PATCH] auto(14b5ea1b9bd9): session end @ 2026-07-24T15:56:59 (+6f) --- src/commands/_anti_patterns.ts | 25 +++---- src/commands/doc/get.ts | 2 +- src/commands/form/create.ts | 2 +- src/commands/form/info.ts | 62 ++++++++++++++--- src/commands/test/run.ts | 4 +- src/core/help.ts | 123 +++------------------------------ 6 files changed, 80 insertions(+), 138 deletions(-) diff --git a/src/commands/_anti_patterns.ts b/src/commands/_anti_patterns.ts index 2595da7..4159eb6 100644 --- a/src/commands/_anti_patterns.ts +++ b/src/commands/_anti_patterns.ts @@ -68,10 +68,10 @@ export const ANTI_PATTERNS: Record = { id: 'AP-fc-4', severity: 'P0', wrong: '1 句话建多表 (含 FK 字段)', - right: '拆步: 先建被关联表 (不含 FK), 再 form update --fields 补 FK', - rationale: '主表先建时 FK 字段无 modelId, step machine 校验失败', + right: '拆步: 先建被关联表 (不含 FK) → 主表 --ai 不带 FK → 主表 form update --fields 加 FK (formData only, 物理表 FK 列需 form import --autoTable 重建)', + rationale: '主表先建时 FK 字段无 modelId, step machine 校验失败; form update --fields 仅改 formData 不会 ALTER 物理表, FK varchar 列必须 form import --autoTable 重建 (与 AP-fu-1 一致)', source: 'archive/drift-rounds-2026-07/2026-07-15-round17-plan.md', - crossRefs: ['decisions/0007-dacli-form-ai-not-in-dependency'], + crossRefs: ['decisions/0007-dacli-form-ai-not-in-dependency', 'decisions/0003-form-update-fields-no-alter-table'], }, { id: 'AP-fc-5', @@ -102,7 +102,7 @@ export const ANTI_PATTERNS: Record = { id: 'AP-fc-8', severity: 'P0', wrong: '建表后未跑 dacli form info 验证', - right: '必跑 `dacli form info ` 验证 4 项 (字段数/jnpfKey/relationForm/required)', + right: '必跑 `dacli form info ` 验证 4 项 (字段数/jnpfKey/relationForm/required); v2.3+ 支持 enCode 自动解析', rationale: 'BS-新117 4 限制入生产会报 "Field cannot be empty"', source: 'archive/drift-rounds-2026-07/2026-07-15-round17-plan.md', crossRefs: ['decisions/0002-form-create-ai-4-limitations'], @@ -119,10 +119,11 @@ export const ANTI_PATTERNS: Record = { }, { id: 'AP-fu-2', severity: 'P1', - wrong: '--fields 字段名不带 F_ 前缀', - right: '所有字段名必带 F_ 前缀', - rationale: '列名缺 F_ 前缀, 列表显示异常', + wrong: '--fields 字段名不带 f_ 前缀', + right: '所有字段名必带 f_ 前缀 (小写, JNPF 标准 snake_case)', + rationale: '列名缺 f_ 前缀, 列表显示异常; F_ (大写) 是老 jnpf 2.x 命名, 现代标准是 f_ (默认 column-naming=snake)', source: 'archive/drift-rounds-2026-07/2026-07-15-round12-summary.md §column_drift', + crossRefs: ['decisions/0009-field-prefix-f-underscore'], }, { id: 'AP-fu-3', severity: 'P2', @@ -136,17 +137,17 @@ export const ANTI_PATTERNS: Record = { { id: 'AP-fi-1', severity: 'P1', wrong: '建表后未跑 form info 验证', - right: '必跑 `dacli form info ` 检查字段数/jnpfKey/relationForm/required 4 项', - rationale: 'BS-新117 4 限制只能通过 form info 验证, 提前发现问题', + right: '必跑 `dacli form info ` 检查字段数/jnpfKey/relationForm/required 4 项 (v2.3+ 支持 enCode 自动解析)', + rationale: 'BS-新117 4 限制只能通过 form info 验证, 提前发现问题; id 直查更稳, enCode 走 form list 解析有 pageSize 截断风险', source: 'archive/drift-rounds-2026-07/2026-07-15-round17-plan.md', }, ], 'form delete': [ { id: 'AP-fd-1', severity: 'P1', - wrong: 'form delete 不带 --cascade', - right: '删 form 前必带 --cascade 删关联菜单/物理表', - rationale: '否则留下孤立菜单和物理表', + wrong: '认为 form delete 必带 --cascade (过度约束)', + right: '--cascade 默认关 (false), 仅在需要级联清关联菜单时带; 不带也能删, 但残留菜单会触发 BS-43 名称重复', + rationale: '--cascade 是可选优化, 非强制; 真要避免 BS-43, 带 --cascade 或先 menu delete; 不带直接 form delete --yes 也合法', source: 'lessons/jxcj1', }, ], diff --git a/src/commands/doc/get.ts b/src/commands/doc/get.ts index 37b9405..6f3d9bd 100644 --- a/src/commands/doc/get.ts +++ b/src/commands/doc/get.ts @@ -125,7 +125,7 @@ export function buildDocGetCommand(): Command { 'dacli doc get --file=docs/tds2/design.html --strip-mermaid', ], source: { - ref: 'docs/dacli/ssw-dacli/.../DocCommand.java + DocService.java', + ref: 'src/commands/doc/_parser.ts (getSection/getRawLines/listSections 切片引擎) + 本文件 (Commander wiring)', }, notes: [ 'section id 来自
或 sidebar nav href=#xxx', diff --git a/src/commands/form/create.ts b/src/commands/form/create.ts index 311b2f1..494dc32 100644 --- a/src/commands/form/create.ts +++ b/src/commands/form/create.ts @@ -285,7 +285,7 @@ export function buildFormCreateCommand(): Command { .option('--webType ', '1=仅表单 2=表单+列表(默认) 3=树+表单 4=数据视图', '2') .option('--category ', '分类 id (form list 看真实值; 镜像 web Form.vue:60-66 必填; 推荐每个 appCode 派独立 category, 通用复用 8f65bbe3bce341c8b3625d93544a044a=crmOrder 业务表单)') .option('--dbLinkId ', 'db link id (type≠4 时必传, 默认从 token.dbLinkId)') - .option('--fields ', 'formData.fields JSON 数组 (--ai 自动填)') + .option('--fields ', 'formData.fields JSON 数组 (DEPRECATED v0.12+ — 运行时 reject, 改用 --ai "<描述>" 或 --table )') .option('--tables ', 'tables JSON 数组 (type=1/2 必传)') .option('--enableFlow <0|1>', '是否绑工作流', '0') .option('--flowId ', '工作流 id (enableFlow=1 时必传)') diff --git a/src/commands/form/info.ts b/src/commands/form/info.ts index d5c3d28..c597d8f 100644 --- a/src/commands/form/info.ts +++ b/src/commands/form/info.ts @@ -19,6 +19,36 @@ import type { FormDetail } from '../../core/types.ts' import { initWebapi, loadVisualDev } from '../../webapi/visualDev.ts' import { setupOutputFilter, addOutputOptions, wrapCommand } from '../_output_filter.ts' // v2.1+ (2026-07-21): 输出过滤 + CommandLog 落盘 (info 类查询历史可追溯); v2.2+ wrapCommand 收口 5c 样板 +/** + * 解析 id-or-enCode 输入 → 真实 form id. + * - 纯数字/UUID 直接当 id 返回 + * - 非数字当 enCode, 走 form list 查 id (审计 P0-1 修复: 旧版只收 id, AI 拿 enCode 卡死) + */ +async function resolveFormId(input: string): Promise<{ id: string; resolvedFrom: 'literal' | 'enCode'; matchedEnCode?: string }> { + // 纯数字 或 UUID 形态 → 直接当 id + if (/^[\d-]+$/.test(input) && input.length >= 10) { + return { id: input, resolvedFrom: 'literal' } + } + // 否则按 enCode 查 + const c = await JnpfClient.fromToken() + await initWebapi(c) + const resp = (await loadVisualDev.getVisualDevList({ + keyword: input, + currentPage: 1, + pageSize: 200, + })) as { list?: Array<{ id?: string; enCode?: string; fullName?: string }> } + const list = resp.list || [] + // 精确匹配 enCode (优先); 否则 fullName 包含; 最后模糊 enCode + const exact = list.find((f) => f.enCode === input) + const byName = list.find((f) => f.fullName === input) + const fuzzy = list.find((f) => (f.enCode || '').toLowerCase().includes(input.toLowerCase())) + const hit = exact || byName || fuzzy + if (!hit || !hit.id) { + throw new Error(`enCode 未匹配到 form: "${input}" (list 返回 ${list.length} 条, 请用 dacli form list 查正确 enCode)`) + } + return { id: hit.id, resolvedFrom: 'enCode', matchedEnCode: hit.enCode } +} + /** * 尝试 JSON.parse 字符串, 失败返回原值. 用于 formData/columnData/tables 解 escaped JSON. */ @@ -75,14 +105,14 @@ export function projectFormBindings(input: Record | null | undefine export function buildFormInfoCommand(): Command { const cmd = new Command('info') - .description('拉表单完整 schema (含 formData/columnData/tables)') - .argument('', '表单 id') + .description('拉表单完整 schema (含 formData/columnData/tables). 支持 id 或 enCode (enCode 自动走 form list 解析)') + .argument('', '表单 id 或 enCode (enCode 自动走 form list 解析为 id)') .option('--summary', '只打概要 (id/enCode/state/type/webType/dbLinkId/字段数)', false) // --json 含特殊语义 (BS-新1 解码 formData escaped JSON), 跟 addOutputOptions 的通用 --json 不能混 .option('--json', 'BS-新1: 解码 formData/columnData/tables escaped JSON, 直接 jq (无需 Python 二次解码)', false) .option('--bindings', '打印 formData 字段的拍平绑定 (field/jnpfKey/dataType/dictionaryType/required)', false) .option('--verbose', '完整输出 (含 step machine、API 调用等过程日志)', false) - .action(async (id: string, opts: { summary?: boolean; json?: boolean; verbose?: boolean; bindings?: boolean }) => { + .action(async (rawId: string, opts: { summary?: boolean; json?: boolean; verbose?: boolean; bindings?: boolean }) => { // 输出过滤: 默认静默 setupOutputFilter(opts) const c = await JnpfClient.fromToken() @@ -96,6 +126,11 @@ export function buildFormInfoCommand(): Command { fixes: [], }, async (ctx) => { try { + // 审计 P0-1: 支持 enCode 输入, 自动走 form list 解析为 id + const { id, resolvedFrom, matchedEnCode } = await resolveFormId(rawId) + if (resolvedFrom === 'enCode' && opts.verbose) { + log.dim(`[enCode→id] ${rawId} → ${id}`) + } // v0.11+ Phase 1: 用 web 端 getInfo (替代 c.get('/visualdev/Base/{id}')) await initWebapi(c) const data = (await loadVisualDev.getInfo(id)) as FormDetail @@ -104,6 +139,8 @@ export function buildFormInfoCommand(): Command { enCode: data.enCode, fullName: data.fullName, state: data.state, + resolvedFrom, + matchedEnCode: matchedEnCode ?? undefined, mode: opts.summary ? 'summary' : opts.bindings ? 'bindings' : (opts.json ? 'json-decoded' : 'json-raw'), @@ -150,25 +187,28 @@ export function buildFormInfoCommand(): Command { } catch (e) { const errMsg = (e as Error).message?.slice(0, 200) log.error(`form info 失败: ${errMsg}`) - if (opts.json) printJson({ error: errMsg, id }) - ctx.fail(`form info 失败: ${errMsg}`, { id }) + if (opts.json) printJson({ error: errMsg, input: rawId }) + ctx.fail(`form info 失败: ${errMsg}`, { input: rawId }) } }) }) installHelpHookWithPatterns(cmd, 'form info', { - purpose: '拉表单完整 schema. clone 前先 info 看结构', - required: { '': '表单 id' }, + purpose: '拉表单完整 schema. clone 前先 info 看结构 (支持 id 或 enCode; enCode 自动走 form list 解析)', + required: { '': '表单 id (数字/UUID) 或 enCode (自动查 form list 解析)' }, optional: { '--summary': '只打概要', '--json': 'BS-新1: 解码 formData/columnData/tables escaped JSON (默认输出仍是字符串, 需 Python 二次解码)', + '--bindings': '拍平 formData 字段绑定 (field/jnpfKey/dataType/dictionaryType/required/modelId)', + '--verbose': '显示 enCode→id 解析过程 (resolveFormId 命中日志)', }, example: [ - 'dacli form info 123456 --summary', - 'dacli form info 123456 --json | jq .formData.fields', // BS-新1: 直接 jq - 'dacli form info 123456 > /tmp/x.json', // 老路径 (formData 是 escaped 字符串) + 'dacli form info 839877227762942789 --summary', + 'dacli form info jxcjteam --summary # enCode 自动解析', + 'dacli form info 839877227762942789 --json | jq .formData.fields', // BS-新1: 直接 jq + 'dacli form info 839877227762942789 --bindings | jq .bindings[].jnpfKey', // 看全部 jnpfKey ], - source: { api: 'GET /api/visualdev/Base/:id' }, + source: { api: 'GET /api/visualdev/Base/:id (enCode 路径额外走 GET /visualdev/Base list 解析)' }, }) return cmd diff --git a/src/commands/test/run.ts b/src/commands/test/run.ts index d66b8bb..0b7db8e 100644 --- a/src/commands/test/run.ts +++ b/src/commands/test/run.ts @@ -481,9 +481,10 @@ export function buildTestRunCommand(): Command { step: '7. DELETE (清理测试数据)', status: 'SKIP', duration: 0, - detail: `--keep-data 默认 ON, 保留 id=${testDataId} 供浏览器层 TC-B 验证`, + detail: `--keep-data 默认 ON, 保留 id=${testDataId} 供浏览器层 TC-B 验证 (⚠️ TC-B 前置: 需先 dacli menu create --formId= 挂菜单, 否则 test browser 找不到 realUrl → 第 1 步 FAIL)`, }) if (!opts.json) log.ok(`Step 7: SKIP (--keep-data 默认 ON, 保留数据 id=${testDataId})`) + if (!opts.json) log.warn(` ⚠️ TC-B 前置: 需先 dacli menu create --formId= 挂菜单 (或 form create --autoCreateMenu 一体化)`) } } catch (e) { steps.push({ @@ -575,6 +576,7 @@ export function buildTestRunCommand(): Command { ], source: { api: 'GET/POST/PUT/DELETE /visualdev/OnlineDev/{formId}' }, notes: [ + '**TC-B 前置**: keep-data 后跑 test browser 需 form 已挂菜单 (menu create --formId 或 form create --autoCreateMenu); 无菜单 → test browser 找不到 realUrl → 第 1 步 FAIL', '**v0.11+ NEW** (2026-06-28 阶段 7.2): 升级到真实业务数据 CRUD 模式', '**默认模式**: real-data (字段语义化默认值 + 关联表真实 ID lookup) + keep-data (留数据供 TC-B)', '**7 步流程**: 拉 schema → POST create → GET info → PUT update → 跨表 join → 业务规则 → DELETE', diff --git a/src/core/help.ts b/src/core/help.ts index 235d6fe..9433d2f 100644 --- a/src/core/help.ts +++ b/src/core/help.ts @@ -2,14 +2,15 @@ * dacli --help system: 知识落地到 CLI 自己 (Phase 1 改造). * * 架构 (v0.22+): - * - DacliHelp interface (Task 1.1): 含 4 新字段 pitfalls/bestPractices/decisionTree/relatedRefs - * - renderDacliHelp() (Task 1.2): 把 DacliHelp 序列化为 addHelpText 文本 - * - installHelpHook() (Task 1.3): 双路径注入 — .description(purpose) + .addHelpText('after', ...) + * - DacliHelp interface: 含 7 字段 purpose/required/optional/example/source/pitfalls/bestPractices/decisionTree/relatedRefs/notes + * - renderDacliHelp(): 把 DacliHelp 序列化为 addHelpText 文本 + * - installHelpHook(): 双路径注入 — .description(purpose) + .addHelpText('after', ...) + * - installHelpHookWithPatterns(): 增强版, 自动从 ANTI_PATTERNS 注入反模式 * - * Legacy compat (Task 1.6 将清理): - * - installAiHelpHook = installHelpHook (alias for source-compat during migration) - * - _aiMeta 副作用保留到 Task 1.6 删 --ai-help flag 时 - * - AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp 是遗留代码 + * v2.3 (2026-07-24): 完成 Task 1.6 legacy 清理. + * - 删除 AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp / installAiHelpHook alias / _aiMeta 副作用 + * - 删除 AiHelp type alias (改名 DacliHelp 是正名, alias 已停用) + * - --ai-help / --example / --source 三个 flag 拦截已停用, 全部走标准 --help addHelpText 输出 */ import type { Command } from 'commander' import { enrichHelp } from '../commands/_anti_patterns' @@ -39,17 +40,14 @@ export interface DacliHelp { /** 跨文件链接 */ relatedRefs?: string[] - /** legacy: 杂项 */ + /** 杂项 */ notes?: string[] } -/** Backward-compat alias during migration */ -export type AiHelp = DacliHelp - /** * 渲染 DacliHelp 为 Commander addHelpText('after', ...) 可接受的字符串. * 包含 4 新段: Pitfalls / Best Practices / Decision Tree / Related Refs. - * 也渲染 example / source / notes (legacy) 段. + * 也渲染 example / source / notes 段. * * Note: `help.purpose` is NOT rendered here — it is intended for Commander's * `.description(help.purpose)` call, which commands should make separately. @@ -122,11 +120,8 @@ export function renderDacliHelp(help: DacliHelp): string { return sections.join('\n') } -const AI_FLAGS = new Set(['--ai-help', '--example', '--source']) - /** * 把 DacliHelp 注入 Commander 命令的 --help 输出. - * 替换旧的 installAiHelpHook, 单 flag --help 包含所有信息. * * - `purpose` 走 Commander 的 `.description()`, 出现在 Usage 之后 Options 之前 * (Commander `helpInformation()` 内置可见) @@ -142,15 +137,8 @@ export function installHelpHook(command: Command, help: DacliHelp): void { if (rendered.trim().length > 0) { command.addHelpText('after', `\n${rendered}`) } - - // Legacy compat: preserve _aiMeta side effect for --ai-help/--example/--source - // flag interception. Task 1.6 will delete this and the interceptor. - ;(command as unknown as { _aiMeta?: DacliHelp })._aiMeta = help } -/** Backward-compat alias during migration */ -export const installAiHelpHook = installHelpHook - /** * 增强版 installHelpHook: 自动从 ANTI_PATTERNS 注入反模式. * 在所有 migrate 完成的命令中使用, 以启用 Pitfalls / Best Practices / Decision Tree / Related Refs. @@ -167,93 +155,4 @@ export function installHelpHookWithPatterns( ): void { const enriched = enrichHelp(fullCmd, help) installHelpHook(command, enriched) -} - -function getMeta(cmd: Command): DacliHelp | undefined { - return (cmd as unknown as { _aiMeta?: DacliHelp })._aiMeta -} - -/** - * 顶层在 parse 前调用. 命中 ai flag 则打印 + exit, 返回 true. - */ -export function maybeInterceptAiHelp(program: Command): boolean { - const argv = process.argv.slice(2) - const flagIdx = argv.findIndex((a) => AI_FLAGS.has(a)) - if (flagIdx < 0) return false - const flag = argv[flagIdx] - // 把 flag 之前的非选项 token 当成命令路径 - const path = argv.slice(0, flagIdx).filter((a) => !a.startsWith('-')) - // 走命令树 - let cur: Command = program - for (const p of path) { - const sub = cur.commands.find( - (c) => c.name() === p || (c.aliases() as string[]).includes(p), - ) - if (!sub) break - cur = sub - } - const meta = getMeta(cur) - if (!meta) { - console.error(`(no ai-help for: ${path.join(' ') || ''})`) - process.exit(2) - } - if (flag === '--example') { - const ex = Array.isArray(meta.example) ? meta.example.join('\n') : meta.example || '(no example)' - console.log(ex) - } else if (flag === '--source') { - const lines: string[] = [] - if (meta.source?.web) lines.push(`web: ${meta.source.web}`) - if (meta.source?.api) lines.push(`api: ${meta.source.api}`) - console.log(lines.join('\n') || '(no source)') - } else { - console.log(renderAiHelp(cur, meta)) - } - process.exit(0) -} - -function renderAiHelp(cmd: Command, meta: DacliHelp): string { - const lines: string[] = [] - // 拼出完整路径 - const path: string[] = [cmd.name()] - let p: Command | null = cmd.parent as Command | null - while (p) { - path.unshift(p.name()) - p = p.parent as Command | null - } - // 去 root 名 - const fullCmd = path.slice(1).join(' ') || path[0] - - lines.push(`# dacli ${fullCmd}`) - lines.push('') - lines.push('## 用途') - lines.push(meta.purpose) - if (meta.required && Object.keys(meta.required).length) { - lines.push('') - lines.push('## 必传参数') - for (const [k, v] of Object.entries(meta.required)) lines.push(`- \`${k}\`: ${v}`) - } - if (meta.optional && Object.keys(meta.optional).length) { - lines.push('') - lines.push('## 可选参数') - for (const [k, v] of Object.entries(meta.optional)) lines.push(`- \`${k}\`: ${v}`) - } - if (meta.source?.web || meta.source?.api) { - lines.push('') - lines.push('## 来源') - if (meta.source.web) lines.push(`- web 源码: ${meta.source.web}`) - if (meta.source.api) lines.push(`- API: ${meta.source.api}`) - } - if (meta.example) { - lines.push('') - lines.push('## 例子') - lines.push('```bash') - lines.push(Array.isArray(meta.example) ? meta.example.join('\n') : meta.example) - lines.push('```') - } - if (meta.notes && meta.notes.length) { - lines.push('') - lines.push('## 注意') - for (const n of meta.notes) lines.push(`- ${n}`) - } - return lines.join('\n') -} +} \ No newline at end of file