Files
dacli/src/commands/_error_codes.ts
T
ssw 4a942c1d54 feat(errors): v0.11e+ Phase A1 错误码分类闭环 (镜像 MsgCode.java:50-783)
新建 src/commands/_error_codes.ts (335 行):
- ErrorCode union type (top 30 常用: EXIST001/002/101/102/103/104, FA001/002/003/019/021/028/029, VS024/401/402/403/408/409/411/412, SYS014/017, DB201/302, WF025/054, FM005/007, OTHER 兜底)
- ErrorCategory enum (duplicate/not_found/permission/invalid_state/db/workflow/visual_dev/unknown)
- ALL_ERROR_CODES 字典 (code → { code, category, rawMessage, suggestion })
- classify(msg) — regex 提取 EXIST/FA/VS/SYS/DB/WF/FM prefix
- format(code, ctx) — 替换 suggestion 占位符
- aggregate(errors) — 按 code + category 分桶
- formatErrorLine(err, { step, stepName }) — 输出 '[step N name] field: CODE - message'
- enhanceFromBackend(msg, field, ctx) — catch 后端错一键增强

集成 7 _validate.ts (form/menu/dm/workflow/dict/role/di):
- ValidationError 加 code?: string 字段
- 关键错误标 code: EXIST001/002/104, VS030/401/402/408, WF054 等

集成 7 create/update.ts:
- catch 后端 r.msg 时调 enhanceFromBackend() 自动填 code
- 输出格式: '[step N name] field: CODE - message (suggestion)'

SKILL.md 加 v0.11e+ Phase A1 段 (架构/权威源/web 镜像/集成/验证)

端到端 tdd10 验证 (admin/123456, appCode=tdd10):
- EXIST002: dict typeCreate enCode 重复 → [step 1 唯一性] enCode: EXIST002 - 字典编码已存在
- EXIST001: dict typeCreate fullName 重复 → [step 1 唯一性] fullName: EXIST001 - 字典名称已存在

selfcheck 8/8 pass (_error_codes.ts + 7 _validate.ts)

镜像 web Form.vue:419 validatePopoverRef 字段级 + 后端 MsgCode.java:50-783 错误码体系
2026-06-27 03:05:23 +08:00

335 lines
16 KiB
TypeScript

/**
* 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<ErrorCode, ErrorCodeInfo> = {
// 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> 确认 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 <id> 查 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 <formId> 发布后再 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(/<id>/g, ctx.enCode)
if (ctx.id) suggestion = suggestion.replace(/<id>/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<string, ValidationError[]>
total: number
/** 按 category 分桶 (高层视角: duplicate 几个, not_found 几个) */
byCategory: Record<ErrorCategory, number>
}
/**
* 把 ValidationError[] 按 code + category 分桶
* @param errors step machine 错误 + catch 后端错误 (统一格式)
* @returns 分桶结果
*/
export function aggregate(errors: ValidationError[]): AggregateResult {
const byCode: Record<string, ValidationError[]> = {}
const byCategory: Record<ErrorCategory, number> = {
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,
}
}