/** * commands/_error_codes.ts — JNPF 错误码分类系统 (Phase A1, v0.11e+, 2026-06-26) * * 镜像 web Form.vue:419 validatePopoverRef.setVisible + 后端 MsgCode.java 错误码体系 * 让 dacli 在 step machine + catch 后端错误时统一分类, AI 不用猜错误码含义 * * 设计原则 (2026-06-26 v0.11e+): * - 权威源: jnpf/后端/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/constant/MsgCode.java * 共 200+ 错误码, 按 prefix 分组: SU/FA/EXIST/IMP/PRI/LOG/OA/PS/DB/WF/VS/GT/SC/AD/ETD/FM/MSERR/SYS/COD * - 仅取 top 30 常用, 其它统一归类为 'OTHER' (避免复刻全部, 防止 AI 引用过时细节) * - 给每个 code 配 category (duplicate/not_found/permission/invalid_state/db/workflow/visual_dev/unknown) + 友好提示 * * 用法: * import { classify, format, aggregate, ValidationError } from '../_error_codes.ts' * const code = classify(r.msg) // 'EXIST001' | null * const e: ValidationError = { field: 'enCode', message: r.msg, code: code ?? undefined } * const agg = aggregate([e]) // { byCode: {...}, total: 1 } * * 为什么: * - step machine 已经有 ValidationError { field, message }, 但缺 code → AI 看到 "名称不能重复" 不知道是 EXIST001 * - catch 后端 r.msg 也不知道哪个 prefix → AI 要去翻 MsgCode.java (200+ 行) * - 统一 classification 让 step machine 错误 + 后端错误输出格式一致 * * 相关 web/backend 行号 (权威源): * - web: Form.vue:419 validatePopoverRef.setVisible(true) — 字段级错误聚合 * - web: FormGenerator.vue:237-300 getData() — errorList 字段级定位 * - web: _dirty_check.ts:45-58 errors: {field, message} — 同模式 * - 后端: jnpf/.../constant/MsgCode.java:50-783 — 200+ 错误码权威定义 */ /* eslint-disable regexp/no-unused-capturing-group */ /* ============================================================ * 1. ErrorCode union type (top 30 常用, 覆盖 90% AI 场景) * ============================================================ */ export type ErrorCode = // EXIST 系列: 重名/重码 (BS-47 全平台唯一性) | 'EXIST001' // 名称不能重复 | 'EXIST002' // 编码不能重复 | 'EXIST003' // 模板名已存在 | 'EXIST004' // 文件夹名称不能重复 | 'EXIST005' // 模板名称超过了限制长度 | 'EXIST006' // 账户不能重复 | 'EXIST101' // 名称重复,请重新输入 | 'EXIST102' // 编码重复,请重新输入 | 'EXIST103' // 不能重复 | 'EXIST104' // 路由地址已存在 (menu urlAddress/pcParents) // FA 系列: 通用失败 (操作失败/无权限/数据不存在) | 'FA001' // 数据不存在 (update/delete on non-existent) | 'FA002' // 更新失败,数据不存在 | 'FA003' // 删除失败,数据不存在 | 'FA019' // 已失效 | 'FA021' // 操作失败!您没有权限操作 (BS-21) | 'FA028' // 新增数据失败 (通用) | 'FA029' // 修改数据失败 (通用) // VS 系列: 在线开发 (form/workflow/di) | 'VS024' // 表单不存在或者未发布 (BS-24) | 'VS401' // 该模板内表单内容为空,无法 (form create empty fields) | 'VS402' // 该模板内列表内容为空,无法 (columnList empty) | 'VS403' // 该功能未配置流程不可用 (workflow not bind) | 'VS408' // 请至少选择一个数据表 (tables.length=0) | 'VS409' // 未找到主表信息 | 'VS411' // 已存在相同功能 | 'VS412' // 该表单已删除 // SYS 系列: 系统 (字典/接口) | 'SYS014' // 字典类型下面有字典值禁止删除 | 'SYS017' // 删除失败,请先删除子菜单 // DB 系列: 数据库 | 'DB201' // 表已经被使用,不允许被删除 | 'DB302' // 数据库连接失败 (dm list 400) // WF 系列: 工作流 | 'WF054' // 流程编码不能重复 | 'WF025' // 启用失败,流程未设计 // FM 系列: form 表单 | 'FM005' // 该表单已被流程引用,无法删除 | 'FM007' // 该模板内表单内容为空,无法发布 (BS-50 同源) // 兜底: 未识别 | 'OTHER' /* ============================================================ * 2. ErrorCategory enum (按修复类别分桶) * ============================================================ */ export type ErrorCategory = | 'duplicate' // EXIST 系列 — 重名重码 | 'not_found' // FA001/FA002/FA003/VS024/FM002 | 'permission' // FA021/FA022/FA051 | 'invalid_state' // FA019/SYS014/SYS017/FM005/FM006 | 'db' // DB 系列 | 'workflow' // WF 系列 | 'visual_dev' // VS/FM 系列 | 'unknown' // OTHER /* ============================================================ * 3. ALL_ERROR_CODES — 完整 enum 列表 (含后端 200+ codes 描述) * * 仅暴露前 30 常用 + OTHER, 完整 200+ 用作 references/error-codes.md 文档 * 用途: AI 学习参考 + 兜底分类 * ============================================================ */ export interface ErrorCodeInfo { code: ErrorCode category: ErrorCategory /** 后端 MsgCode.java 原文 */ rawMessage: string /** AI 友好提示 */ suggestion: string } export const ALL_ERROR_CODES: Record = { // EXIST 系列 (BS-47 全平台唯一性, dacli 必修预校验) EXIST001: { code: 'EXIST001', category: 'duplicate', rawMessage: '名称不能重复', suggestion: '改名加 _v2 / form delete 后重建, 或换名字' }, EXIST002: { code: 'EXIST002', category: 'duplicate', rawMessage: '编码不能重复', suggestion: '改 enCode 加 _v2 后缀, 或查 dacli {form/menu/dict/role} list 看占用' }, EXIST003: { code: 'EXIST003', category: 'duplicate', rawMessage: '模板名已存在', suggestion: '模板名加 _v2 或换名字' }, EXIST004: { code: 'EXIST004', category: 'duplicate', rawMessage: '文件夹名称不能重复', suggestion: '文件夹改名' }, EXIST005: { code: 'EXIST005', category: 'duplicate', rawMessage: '模板名称超过了限制长度', suggestion: '缩短到 50 字符以内' }, EXIST006: { code: 'EXIST006', category: 'duplicate', rawMessage: '账户不能重复', suggestion: '换账户名' }, EXIST101: { code: 'EXIST101', category: 'duplicate', rawMessage: '名称重复,请重新输入', suggestion: '换 fullName' }, EXIST102: { code: 'EXIST102', category: 'duplicate', rawMessage: '编码重复,请重新输入', suggestion: '换 enCode' }, EXIST103: { code: 'EXIST103', category: 'duplicate', rawMessage: '不能重复', suggestion: '查重后再提交' }, EXIST104: { code: 'EXIST104', category: 'duplicate', rawMessage: '路由地址已存在', suggestion: '换 urlAddress/pageAddress (menu)' }, // FA 系列 FA001: { code: 'FA001', category: 'not_found', rawMessage: '数据不存在', suggestion: '跑 dacli {module} info 确认 id 是否被删' }, FA002: { code: 'FA002', category: 'not_found', rawMessage: '更新失败,数据不存在', suggestion: '确认 id 有效后再 update' }, FA003: { code: 'FA003', category: 'not_found', rawMessage: '删除失败,数据不存在', suggestion: '确认 id 有效后再 delete' }, FA019: { code: 'FA019', category: 'invalid_state', rawMessage: '已失效', suggestion: '跑 dacli {module} info 查 enabledMark/state' }, FA021: { code: 'FA021', category: 'permission', rawMessage: '操作失败!您没有权限操作', suggestion: '切换 admin 账号 或 申请角色权限' }, FA028: { code: 'FA028', category: 'invalid_state', rawMessage: '新增数据失败', suggestion: '检查必填字段 + 后端日志 (dacli tool logs --level=error)' }, FA029: { code: 'FA029', category: 'invalid_state', rawMessage: '修改数据失败', suggestion: '检查 step machine 校验 + 后端日志' }, // VS 系列 VS024: { code: 'VS024', category: 'visual_dev', rawMessage: '表单不存在或者未发布', suggestion: '跑 dacli form release 发布后再 menu create' }, VS401: { code: 'VS401', category: 'visual_dev', rawMessage: '该模板内表单内容为空,无法', suggestion: 'formData.fields 不能为空, 至少 1 个 vmodel 控件' }, VS402: { code: 'VS402', category: 'visual_dev', rawMessage: '该模板内列表内容为空,无法', suggestion: 'columnData.columnList 不能为空 (webType≠1 必须勾选)' }, VS403: { code: 'VS403', category: 'visual_dev', rawMessage: '该功能未配置流程不可用', suggestion: '绑工作流 (enableFlow=1 + flowId)' }, VS408: { code: 'VS408', category: 'visual_dev', rawMessage: '请至少选择一个数据表', suggestion: '传 --tables=... 或 --ai-json 含完整 tables' }, VS409: { code: 'VS409', category: 'visual_dev', rawMessage: '未找到主表信息', suggestion: '检查 ai-json[0].isMain=true 且 tableName 非空' }, VS411: { code: 'VS411', category: 'visual_dev', rawMessage: '已存在相同功能', suggestion: '同名 enCode 已占用, 加 _v2 后缀' }, VS412: { code: 'VS412', category: 'visual_dev', rawMessage: '该表单已删除', suggestion: 'form 已删除, 重新创建' }, // SYS 系列 SYS014: { code: 'SYS014', category: 'invalid_state', rawMessage: '字典类型下面有字典值禁止删除', suggestion: '先 dacli dict dataDelete 删除所有字典项, 再 typeDelete' }, SYS017: { code: 'SYS017', category: 'invalid_state', rawMessage: '删除失败,请先删除子菜单', suggestion: '先 dacli menu delete 子菜单, 再 delete 父菜单' }, // DB 系列 DB201: { code: 'DB201', category: 'db', rawMessage: '表已经被使用,不允许被删除', suggestion: 'form/workflow/di 引用, 先解除引用再 drop' }, DB302: { code: 'DB302', category: 'db', rawMessage: '数据库连接失败', suggestion: 'dbLinkId 失效, 跑 dacli app init -- --appCode=X --force-rebuild --restart' }, // WF 系列 WF054: { code: 'WF054', category: 'workflow', rawMessage: '流程编码不能重复', suggestion: '改 workflow enCode 加 _v2 后缀' }, WF025: { code: 'WF025', category: 'workflow', rawMessage: '启用失败,流程未设计', suggestion: 'flowXml 必须含 start + end 节点' }, // FM 系列 FM005: { code: 'FM005', category: 'visual_dev', rawMessage: '该表单已被流程引用,无法删除', suggestion: '先解除 workflow.formId 引用, 再 form delete' }, FM007: { code: 'FM007', category: 'visual_dev', rawMessage: '该模板内表单内容为空,无法发布', suggestion: 'formData.fields 至少 1 个 vmodel 控件 (同 VS401)' }, // 兜底 OTHER: { code: 'OTHER', category: 'unknown', rawMessage: '(未识别)', suggestion: '查 references/error-codes.md 或 dacli tool logs --level=error' }, } /* ============================================================ * 4. classify(msg) — 从后端返回的 msg 提取 prefix * * 镜像 web Form.vue:419 validatePopoverRef.setVisible 字段级反馈思想 * 但代码层做: regex 提取 EXIST/FA/VS/SYS/DB/WF/FM 等 prefix * ============================================================ */ /** 错误码 regex — 提取 EXIST001 / FA021 / VS401 等 prefix */ const CODE_REGEX = /\b(EXIST\d{3}|EXIST\d{2}|FA\d{3}|FA\d{2}|VS\d{3}|VS\d{2}|SYS\d{3}|SYS\d{2}|DB\d{3}|DB\d{2}|WF\d{3}|WF\d{2}|FM\d{3}|FM\d{2})\b/i /** * 从后端 r.msg 提取 ErrorCode * @param msg 后端返回的 msg (例: '编码不能重复' / 'EXIST002 / 编码不能重复' / '数据不存在') * @returns ErrorCode union 或 null (没匹配上 prefix) */ export function classify(msg: string): ErrorCode | null { if (!msg || typeof msg !== 'string') return null const m = msg.match(CODE_REGEX) if (!m) return null const code = m[1].toUpperCase() as ErrorCode // 验证是已知的 30 个之一 if (code in ALL_ERROR_CODES) return code return 'OTHER' } /* ============================================================ * 5. format(code, ctx) — 给 AI 友好提示 * * 返回 { code, category, message, suggestion } * ctx: 上下文 (例: { entity: 'form', id: 'xxx', enCode: 'yyy' }) * ============================================================ */ export interface FormatContext { /** 实体类型 (form/menu/dict/workflow/role/di/dm) */ entity?: string /** id */ id?: string /** enCode (供 suggestion 模板用) */ enCode?: string /** 其它自由参数 */ [key: string]: unknown } export interface FormattedError { code: ErrorCode category: ErrorCategory /** 后端原文 (从 ALL_ERROR_CODES 拿) */ message: string /** AI 友好提示 (ctx 替换占位符 {entity}/{id}/{enCode}) */ suggestion: string } export function format(code: ErrorCode, ctx: FormatContext = {}): FormattedError { const info = ALL_ERROR_CODES[code] || ALL_ERROR_CODES.OTHER // 替换 suggestion 里的 {entity}/{id}/{enCode} 占位符 let suggestion = info.suggestion if (ctx.entity) suggestion = suggestion.replace(/\{module\}/g, ctx.entity) if (ctx.entity) suggestion = suggestion.replace(/\{form\/menu\/dict\/role\}/g, ctx.entity) if (ctx.enCode) suggestion = suggestion.replace(//g, ctx.enCode) if (ctx.id) suggestion = suggestion.replace(//g, ctx.id) return { code: info.code, category: info.category, message: info.rawMessage, suggestion, } } /* ============================================================ * 6. aggregate(errors) — 错误聚合 * * 镜像 web FormGenerator.vue:239-300 errorList 字段级定位 + validatePopoverRef 聚合展示 * 返回: 按 code 分桶 + total, AI 一眼看出哪些 code 重复触发 * ============================================================ */ export interface ValidationErrorWithCode { field?: string message: string code?: ErrorCode | string } /** step machine 错误 + 后端错误统一格式 (dacli 所有 create/update 共用) */ export interface ValidationError { field?: string message: string /** v0.11e+: ErrorCode, 镜像后端 MsgCode.java, AI 能查表 */ code?: string } export interface AggregateResult { byCode: Record total: number /** 按 category 分桶 (高层视角: duplicate 几个, not_found 几个) */ byCategory: Record } /** * 把 ValidationError[] 按 code + category 分桶 * @param errors step machine 错误 + catch 后端错误 (统一格式) * @returns 分桶结果 */ export function aggregate(errors: ValidationError[]): AggregateResult { const byCode: Record = {} const byCategory: Record = { duplicate: 0, not_found: 0, permission: 0, invalid_state: 0, db: 0, workflow: 0, visual_dev: 0, unknown: 0, } for (const e of errors) { const code = e.code || 'OTHER' if (!byCode[code]) byCode[code] = [] byCode[code].push(e) // 查 category const cat = (code in ALL_ERROR_CODES ? ALL_ERROR_CODES[code as ErrorCode].category : 'unknown') as ErrorCategory byCategory[cat]++ } return { byCode, total: errors.length, byCategory } } /* ============================================================ * 7. formatErrorLine(err) — 单行格式化 (供 create/update 输出用) * * 输出格式: [step 0 基础信息] enCode: EXIST002 - 编码不能重复 (改名加 _v2) * 镜像 _dirty_check.ts:103-106 错误输出风格 * ============================================================ */ export interface FormatErrorLineOpts { /** step 编号 (0/1/2/3), 用于前缀 */ step?: number | string /** step 名 */ stepName?: string } export function formatErrorLine( err: ValidationError, opts: FormatErrorLineOpts = {}, ): string { const parts: string[] = [] if (opts.step !== undefined && opts.stepName) { parts.push(`[step ${opts.step} ${opts.stepName}]`) } if (err.field) parts.push(err.field) if (err.code) parts.push(`${err.code} - ${err.message}`) else parts.push(err.message) return parts.join(': ') } /* ============================================================ * 8. enhanceFromBackend(msg, field?, ctx) — catch 后端错时一键增强 * * 用法: * } catch (e: any) { * const enhanced = enhanceFromBackend(e?.msg || String(e), 'enCode', { entity: 'form' }) * log.error(formatErrorLine(enhanced, { step: 0, stepName: '基础信息' })) * } * * 输出: ValidationError { field, message, code } — 自动填 code (从 msg 提取) * ============================================================ */ export function enhanceFromBackend( msg: string, field?: string, ctx: FormatContext = {}, ): ValidationError { const code = classify(msg) const info = code ? format(code, ctx) : { code: 'OTHER', category: 'unknown' as ErrorCategory, message: msg, suggestion: '' } return { field, message: info.message || msg, code: info.code === 'OTHER' ? undefined : info.code, } }