chanjs 2.7.8 → 2.7.11

package/doc/09-/345/233/275/351/231/205/345/214/226Lang.md

@@ -0,0 +1,220 @@
+# 国际化 i18n（Lang）
+
+> 基于 `i18next` 的多语言支持，启动时扫描 `lang/` 目录加载全部 JSON 语言包，运行时 O(1) 查词。
+> 对外通过 `import { initLang } from "chanjs"` 或 `this.app.lang`（Chan 应用实例已内置）使用。
+
+---
+
+## 一、设计理念
+
+| 决策 | 说明 |
+|------|------|
+| 成熟库 | 采用 `i18next`，复用其插值、复数、命名空间等成熟能力，不重复造轮子 |
+| 启动加载 | 启动时扫描 `lang/` 目录，把全部语言包读进内存，运行时零 I/O |
+| 全局单例 | `initLang` 返回的就是 i18next 单例，`this.app.lang` 指向同一实例 |
+| 后端不转义 | `interpolation.escapeValue: false`，JSON 输出 / 邮件等后端场景不自动转义 |
+
+---
+
+## 二、语言包目录结构
+
+在项目**根目录**下建 `lang/`，每个语言一个子目录，每个命名空间一个 JSON 文件：
+
+```
+lang/
+├── zh-CN/
+│   ├── common.json      # 默认命名空间
+│   └── user.json        # 也可按模块拆命名空间
+├── en/
+│   ├── common.json
+│   └── user.json
+└── ja/
+    └── common.json
+```
+
+`lang/zh-CN/common.json` 示例：
+
+```json
+{
+  "user": {
+    "welcome": "欢迎，{{name}}",
+    "login": "登录",
+    "logout": "退出"
+  },
+  "order": {
+    "created": "订单创建成功，编号 {{id}}"
+  }
+}
+```
+
+> 语言目录名需匹配 `^[a-zA-Z_-]+$`（如 `zh-CN`、`en`、`ja`）。命名空间 = JSON 文件名（如 `common`）。
+
+---
+
+## 三、初始化 initLang
+
+### 应用实例内置（推荐）
+
+`Chan` 应用启动时会自动调用 `initLang`，并把结果挂到 `this.app.lang`：
+
+```javascript
+// app/app.js
+import Chan from "chanjs";
+
+const chan = new Chan();
+await chan.start();   // 内部已初始化 i18n，默认语言来自 config
+```
+
+启动后业务代码直接用 `this.app.lang`：
+
+```javascript
+const msg = this.app.lang.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+```
+
+### 手动初始化（中间件 / 独立脚本）
+
+```javascript
+import { initLang } from "chanjs";
+
+const i18n = await initLang("zh-CN");   // 返回 i18next 实例
+i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `locale` | `string` | 默认语言，默认 `"zh-CN"` |
+| **返回** | `Promise<i18next>` | i18next 实例 |
+
+---
+
+## 四、翻译 `t(key, opts?)`
+
+### 4.1 基础查词
+
+```javascript
+this.app.lang.t("user.login");   // → "登录"
+```
+
+### 4.2 插值（`{{变量}}`）
+
+```javascript
+this.app.lang.t("user.welcome", { name: "张三" });   // → "欢迎，张三"
+```
+
+### 4.3 复数（i18next 原生支持）
+
+语言包：
+
+```json
+{ "item": {
+  "one": "有 {{count}} 个商品",
+  "other": "有 {{count}} 个商品"
+} }
+```
+
+```javascript
+this.app.lang.t("item", { count: 1 });   // → "有 1 个商品"
+this.app.lang.t("item", { count: 5 });   // → "有 5 个商品"
+```
+
+### 4.4 指定命名空间
+
+语言包拆了多个命名空间时，用 `ns` 指定：
+
+```javascript
+// lang/user.json: { "title": "用户中心" }
+this.app.lang.t("title", { ns: "user" });   // → "用户中心"
+```
+
+> 未指定 `ns` 时默认用 `common` 命名空间。
+
+---
+
+## 五、动态切换语言 changeLanguage
+
+业务运行时（登录后 / 用户偏好 / 请求头）可随时切换：
+
+```javascript
+// 切换语言并等待资源生效
+await this.app.lang.changeLanguage("en");
+
+// 切换后立即按新语言取词
+const msg = this.app.lang.t("user.welcome", { name: "Zhang San" });  // 英文包
+```
+
+### 按请求动态切换（多语言站点）
+
+```javascript
+// app/middleware/i18n.js  —— 每个请求按 Accept-Language 切换
+import { event } from "chanjs";
+
+export function i18nMw(app) {
+  app.use(async (req, res, next) => {
+    const lang = req.headers["accept-language"]?.split(",")[0] || "zh-CN";
+    await app.lang.changeLanguage(lang);
+    next();
+  });
+}
+```
+
+> 注意：`changeLanguage` 是异步的，切换后记得 `await` 再取词。
+
+---
+
+## 六、使用场景
+
+### 场景一：接口返回多语言文案
+
+```javascript
+// Controller 里
+async greet(req, res) {
+  const name = req.query.name || "朋友";
+  return this.success({
+    data: {
+      msg: this.app.lang.t("user.welcome", { name }),
+    },
+  });
+}
+```
+
+### 场景二：邮件 / 短信模板
+
+```javascript
+const subject = this.app.lang.t("email.subject", { ns: "mail" });
+const body = this.app.lang.t("email.reset_body", { name: user.name, link });
+await sendMail(user.email, subject, body);
+```
+
+### 场景三：错误提示本地化
+
+```javascript
+const KeyedError = new AppError(this.app.lang.t("error.order_not_found"));
+throw KeyedError;   // → 按当前语言给出错误提示
+```
+
+---
+
+## 七、注意事项
+
+### 1. 语言包必须存在，否则回退 zh-CN
+
+`fallbackLng` 固定为 `zh-CN`。某语言缺词时自动回退到中文包，不会报错。
+
+### 2. `escapeValue: false`（后端不转义）
+
+这是后端场景特意关闭的。若用于**前端渲染用户输入**，请自行 `XSS` 过滤（见 `filterXSS`），不要直接拼接。
+
+### 3. 单文件解析失败不阻断
+
+某个语言包的 JSON 解析失败会被跳过，不影响其它语言和应用启动。
+
+### 4. 与 `changeLanguage` 配合 requestId
+
+`changeLanguage` 是异步切换，多语言站点建议在请求期间保持语言一致，避免并发切换串语言。
+
+### 5. 新增语言步骤
+
+1. 在 `lang/` 下建语言目录（如 `lang/fr/`）
+2. 放入 `common.json`（及需要的命名空间文件）
+3. 重启应用（启动时扫描加载）
+4. 用 `changeLanguage("fr")` 切换后按 `fr` 渲染

package/index.js

@@ -10,6 +10,7 @@
  *   import { Controller, Repository, Service, cache, Paths, loader, utils, getApp } from "chanjs";
  *   import { validate, validateAll } from "chanjs";  // zod 校验中间件
  *   import { AppError, NotFoundError, ValidationError } from "chanjs";  // 错误类
+ *   import { event, EventBus, Task, initLang } from "chanjs";  // 基础设施
  *
  * 多实例：
  *   每个 Chan 实例持有独立 config/db/paths/dbManager（注册表管理），
@@ -22,6 +23,11 @@ export { default as Controller } from "./core/Controller.js";
 export { default as Repository } from "./core/Repository.js";
 export { Service } from "./core/Service.js";
 
+// ===================== 基础设施（事件总线 / 定时任务 / i18n）=====================
+export { EventBus, event } from "./core/EventBus.js";
+export { default as Task } from "./core/Task.js";
+export { initLang } from "./core/Lang.js";
+
 // ===================== 错误体系 =====================
 export {
   AppError, AuthError, TokenExpiredError, ForbiddenError,
@@ -33,6 +39,29 @@ export {
 // ===================== 统一响应工具（纯函数，可复用于接口 / 定时任务 / RPC）=====================
 export { success, fail, routeNotFound, serializeError, buildErrorHtml, respondError } from "./response/index.js";
 
+// ===================== 业务状态码 =====================
+export {
+  CODE,
+  getCodeMsg,
+  CODE_OK,
+  CODE_AUTH_FAILED,
+  CODE_TOKEN_EXPIRED,
+  CODE_FORBIDDEN,
+  CODE_NOT_FOUND,
+  CODE_CONFLICT,
+  CODE_PARAM_INVALID,
+  CODE_PARAM_MISSING,
+  CODE_BUSINESS_FAIL,
+  CODE_RATE_LIMIT,
+  CODE_DEVICE_ERROR,
+  CODE_BLOCKED,
+  CODE_SYSTEM_ERROR,
+  CODE_SERVICE_BUSY,
+  CODE_DB_CONNECTION_ERROR,
+  CODE_DB_ACCESS_DENIED,
+  CODE_DB_OPERATION_TIMEOUT,
+} from "./response/code.js";
+
 // ===================== 安全工具 =====================
 export { setToken, getToken, verifyToken, revokeToken } from "./security/jwt.js";
 export { aesEncrypt, aesDecrypt } from "./security/sign.js";
@@ -58,4 +87,4 @@ export { Paths } from "./utils/paths.js";
 
 // ===================== 默认导出应用主类 =====================
 import Chan from "./core/App.js";
-export default Chan;
+export default Chan;

package/middleware/log.js

@@ -1,35 +1,52 @@
-import morgan from "morgan";
+import { randomUUID } from "crypto";
+import pinoHttp from "pino-http";
 import { getIp } from "../utils/ip.js";
-
-// 日志格式白名单，防止非法格式注入
-const ALLOWED_FORMATS = new Set(["chancms", "combined", "common", "dev", "short", "tiny"]);
-
-// 自定义token
-morgan.token("ip", req => getIp(req));
-morgan.token("user", req => req.user ? `${req.user.uid}:${req.user.username}` : "-");
-morgan.token("datetime", () => new Date().toISOString());
-
-// 自定义ChanCMS日志输出模板
-morgan.format("chancms", (tokens, req, res) => [
-  tokens.datetime(req, res),
-  tokens.ip(req, res),
-  tokens.user(req, res),
-  tokens.method(req, res),
-  tokens.url(req, res),
-  tokens.status(req, res),
-  tokens.res(req, res, "content-length") || "-",
-  "-",
-  tokens["response-time"](req, res),
-  "ms"
-].join(" "));
+import { root } from "../utils/logger.js";
 
 /**
- * 请求日志中间件(morgan)，内置格式白名单防注入
- * @param {express.Application} app Express实例
- * @param {{level?: string}} [logger={}] 日志配置
+ * 请求日志中间件（pino-http）
+ *
+ * 自动为每个请求生成 requestId，挂载 req.log（带 requestId 的子 logger）。
+ * 业务 Controller 中可通过 req.log.info("xxx") 输出带 requestId 的日志。
+ *
+ * @param {object} app - Express 实例
+ * @param {object} [config={}] - 配置对象
  */
-export const log = (app, logger = {}) => {
-  const level = logger.level;
-  const format = ALLOWED_FORMATS.has(level) ? level : "chancms";
-  app.use(morgan(format));
-};
+export function log(app, config = {}) {
+  app.use(pinoHttp({
+    logger: root,
+    // 自动记录请求日志（静态资源跳过）
+    autoLogging: {
+      ignore: (req) => {
+        const url = req.url || "";
+        return /\.(ico|png|jpg|jpeg|gif|svg|css|js|woff|woff2)$/.test(url);
+      },
+    },
+    // requestId 生成：优先复用上游 X-Request-Id
+    genReqId: (req, res) => {
+      const id = req.headers["x-request-id"] || randomUUID();
+      res.setHeader("X-Request-Id", id);
+      return id;
+    },
+    // 日志级别按状态码区分
+    customLogLevel: (req, res, err) => {
+      if (err || res.statusCode >= 500) return "error";
+      if (res.statusCode >= 400) return "warn";
+      return "info";
+    },
+    customSuccessMessage: (req, res) => {
+      return `${req.method} ${req.originalUrl || req.url} ${res.statusCode}`;
+    },
+    customErrorMessage: (req, res, err) => {
+      return `${req.method} ${req.originalUrl || req.url} ${res.statusCode} ${err.message}`;
+    },
+    serializers: {
+      req: (req) => ({
+        method: req.method,
+        url: req.originalUrl || req.url,
+        ip: getIp(req),
+      }),
+      res: (res) => ({ statusCode: res.statusCode }),
+    },
+  }));
+}

package/middleware/waf.js

@@ -1,16 +1,10 @@
-import crypto from "crypto";
 import { getIp } from "../utils/ip.js";
 import { checkKeywords } from "../security/checker.js";
 import { filterXSS } from "../security/xss-filter.js";
 import { createRateLimitMiddleware } from "../security/rate-limit.js";
-import { store } from "../storage/store.js";
 import { CODE_BLOCKED } from "../response/code.js";
 import logger from "../utils/logger.js";
 
-const BLOCK_KEY_PREFIX = "waf:block:";
-const STRIKE_KEY_PREFIX = "waf:strike:";
-
-// 放行路径白名单
 const WAF_PATH_WHITELIST = [
   "/.well-known/appspecific/",
   "/.well-known/change-password",
@@ -22,24 +16,19 @@ const WAF_PATH_WHITELIST = [
 
 const TRUSTED_IPS = new Set(["127.0.0.1", "::1"]);
 
-const DEFAULT_BLOCK = {
-  BLOCK_DURATION: 30 * 60 * 1000,
-  STRIKE_THRESHOLD: 3,
-  STRIKE_WINDOW: 60 * 60 * 1000,
-};
+// URL/query 关键词检测保留的分类——只保留真正危险、几乎不会在正常 URL 中出现的攻击特征。
+// 去掉 wholeWord / extensions / directories / sensitiveIdentifiers / commandInjection，
+// 这些在正常 URL（?debug=1、/internal/、/.well-known/、wget/scp/dd 等）极易误伤正常请求。
+const URL_SCAN_CATEGORIES = ["sqlInjection", "xss", "pathTraversal", "encoding"];
 
 /**
- * 判断内网/回环可信IP
+ * 判断本机回环可信IP：仅 127.0.0.1 / ::1 无条件放行 WAF 的 query 关键词检测与 XSS 净化。
+ * 不再放行整个内网段（如 10.x、192.168.x、172.16-31.x），
+ * 否则当 Nginx 部署在另一台内网机、Express 未解析 XFF 时，全站 WAF 会静默失效。
  */
 const isTrustedIp = ip => {
   if (!ip) return false;
-  if (TRUSTED_IPS.has(ip)) return true;
-  if (ip.startsWith("10.") || ip.startsWith("192.168.")) return true;
-  if (ip.startsWith("172.")) {
-    const seg = Number(ip.split(".")[1]);
-    return seg >= 16 && seg <= 31;
-  }
-  return false;
+  return TRUSTED_IPS.has(ip);
 };
 
 /**
@@ -47,12 +36,6 @@ const isTrustedIp = ip => {
  */
 const isWhitelistedPath = path => WAF_PATH_WHITELIST.some(p => path === p || path.startsWith(p));
 
-/**
- * IP+UA指纹 sha256(前32位)
- */
-const buildFingerprint = (ip, ua = "") =>
-  crypto.createHash("sha256").update(`${ip}|${ua}`).digest("hex").slice(0, 32);
-
 /**
  * 覆盖Express5只读req.query
  */
@@ -72,22 +55,8 @@ const respondWaf = (res, status, msg, data) =>
   res.status(status).json({ code: CODE_BLOCKED, success: false, msg, data });
 
 /**
- * 关键词命中计数+封禁逻辑
+ * 限流，返回是否已响应
  */
-async function handleStrike(fingerprint, clientIp, keyword, blockCfg) {
-  const strikeKey = `${STRIKE_KEY_PREFIX}${fingerprint}`;
-  const strikes = await store.incrAndExpire(strikeKey, blockCfg.STRIKE_WINDOW);
-
-  if (strikes >= blockCfg.STRIKE_THRESHOLD) {
-    const blockKey = `${BLOCK_KEY_PREFIX}${fingerprint}`;
-    await store.set(blockKey, { ip: clientIp, reason: keyword, expireAt: Date.now() + blockCfg.BLOCK_DURATION }, blockCfg.BLOCK_DURATION);
-    logger.error(`[WAF封禁] IP:${clientIp} 累计命中:${strikes}次 封禁${blockCfg.BLOCK_DURATION / 60000}分钟`);
-    return { blocked: true, strikes };
-  }
-  return { blocked: false, strikes };
-}
-
-/** 执行限流，返回是否已响应 */
 const runRateLimit = (rateLimit, req, res) =>
   new Promise(resolve => rateLimit(req, res, resolve)).then(() => res.headersSent);
 
@@ -96,7 +65,6 @@ const runRateLimit = (rateLimit, req, res) =>
  */
 const createWafMiddleware = wafConfig => {
   const rateLimit = createRateLimitMiddleware(wafConfig.rateLimit);
-  const blockCfg = { ...DEFAULT_BLOCK, ...wafConfig.block };
 
   return async (req, res, next) => {
     try {
@@ -104,8 +72,6 @@ const createWafMiddleware = wafConfig => {
 
       const clientIp = getIp(req);
       const path = req.path || "";
-      const ua = req.headers["user-agent"] || "";
-      const fp = buildFingerprint(clientIp, ua);
       const whitePath = isWhitelistedPath(path);
 
       // 可信IP直接放行，仅做query XSS过滤
@@ -117,32 +83,24 @@ const createWafMiddleware = wafConfig => {
       // 限流
       if (await runRateLimit(rateLimit, req, res)) return;
 
-      // 已封禁直接拦截
-      const blockInfo = await store.get(`${BLOCK_KEY_PREFIX}${fp}`);
-      if (blockInfo) {
-        logger.error(`[WAF拦截封禁] IP:${clientIp} UA:${ua.slice(0, 50)}`);
-        return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
-      }
-
       // 白名单路径跳过关键词检测
       if (whitePath) {
         if (req.query && Object.keys(req.query).length) overrideQuery(req, filterXSS(req.query));
         return next();
       }
 
-      // 路径+query拼接检测恶意关键词
+      // 路径+query拼接检测恶意关键词（仅保留真正危险分类，避免 debug/secret/internal/.env 等正常词误伤）
       let checkText = path;
       if (Object.keys(req.query ?? {}).length) {
         const queryStr = Object.entries(req.query).map(([k, v]) => `${k}=${v}`).join(" ");
         checkText += ` ${queryStr}`;
       }
-      const hit = checkKeywords(checkText);
+      const hit = checkKeywords(checkText, { categories: URL_SCAN_CATEGORIES });
       if (hit) {
         const { keyword, category } = hit;
         logger.error(`[WAF拦截-URL] IP:${clientIp} Path:${path} Key:${keyword} Type:${category}`);
-        const { blocked, strikes } = await handleStrike(fp, clientIp, keyword, blockCfg);
-        if (blocked) return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
-        return respondWaf(res, 403, "检测到非法内容，请求已被拦截", { strikes, threshold: blockCfg.STRIKE_THRESHOLD });
+        // 仅当次拦截，不再累计封禁 IP（避免误报把整 IP 锁 30 分钟）
+        return respondWaf(res, 403, "检测到非法内容，请求已被拦截");
       }
 
       // query XSS净化
@@ -160,19 +118,10 @@ const createWafMiddleware = wafConfig => {
   };
 };
 
-/**
- * 已登录用户的管理接口路径前缀（跳过 body 关键词检测，避免误杀富文本/代码内容）
- * 可通过 waf 配置 bodySkipPrefixes 字段自定义，默认包含常见管理模块前缀
- */
-const DEFAULT_BODY_SKIP_PREFIXES = ["/cms/", "/base/", "/member/", "/book/", "/oss/", "/vip/"];
-
 /**
  * Body层WAF中间件（body解析后）
  */
 const createWafBodyMiddleware = wafConfig => {
-  const blockCfg = { ...DEFAULT_BLOCK, ...wafConfig.block };
-  const bodySkipPrefixes = wafConfig.bodySkipPrefixes ?? DEFAULT_BODY_SKIP_PREFIXES;
-
   return async (req, res, next) => {
     try {
       if (!wafConfig.enabled) return next();
@@ -186,35 +135,18 @@ const createWafBodyMiddleware = wafConfig => {
       // 空body直接放行
       if (!req.body || (typeof req.body === "object" && !Object.keys(req.body).length)) return next();
 
-      // 已登录用户的管理接口：跳过关键词检测（富文本/代码内容会误杀），仅做 XSS 过滤
-      const isAuthedAdmin = req.user?.uid && bodySkipPrefixes.some(p => path.startsWith(p));
-
-      if (!isAuthedAdmin) {
-        // 序列化body文本，截断1w字符防绕过
-        let bodyText = "";
-        try {
-          bodyText = (typeof req.body === "string" ? req.body : JSON.stringify(req.body)).slice(0, 10000);
-        } catch (e) {
-          logger.error(`[WAF警告] body序列化失败 IP:${clientIp} Err:${e.message}`);
-        }
-
-        // body关键词检测拦截（scope='body' 跳过路径/文件特征类规则，降低正文误报）
-        if (bodyText) {
-          const hit = checkKeywords(bodyText, { scope: 'body' });
-          if (hit) {
-            const { keyword, category } = hit;
-            const fp = buildFingerprint(clientIp, req.headers["user-agent"] || "");
-            logger.error(`[WAF拦截-Body] IP:${clientIp} Path:${path} Key:${keyword} Type:${category}`);
-            const { blocked, strikes } = await handleStrike(fp, clientIp, keyword, blockCfg);
-            if (blocked) return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
-            return respondWaf(res, 403, "检测到非法内容，请求已被拦截", { strikes, threshold: blockCfg.STRIKE_THRESHOLD });
-          }
-        }
-      }
+      // 请求体关键词拦截已移除：
+      // 项目 DB 全部走 knex 参数化查询（天然防 SQL 注入），后端也无任何
+      // 把用户输入交给 shell 执行的路径；而关键词扫描对留言/评论/注册等正常正文
+      // 误报极高（drop / select / alert / onclick 等普通词都会被拦），代价远大于收益。
+      // XSS 防护由下方 filterXSS 负责（输出编码），SQL 注入由参数化查询负责。
 
       // body XSS过滤
+      // 例外：base/config 系统配置写入接口跳过 XSS 过滤——sys_config 配置值须原样存储
+      // （含「名称 <邮箱>」发件人格式、HTML 邮件模板等），且该接口仅管理员可访问，
+      // 配置值由后端逻辑消费而非直接反射到页面，无 XSS 风险。
       try {
-        if (typeof req.body === "object") req.body = filterXSS(req.body);
+        if (typeof req.body === "object" && !path.startsWith("/base/config")) req.body = filterXSS(req.body);
       } catch (e) {
         logger.error(`[WAF警告] body过滤失败 IP:${clientIp} Err:${e.message}`);
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.8",
+  "version": "2.7.11",
   "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
   "main": "index.js",
   "module": "index.js",
@@ -18,6 +18,18 @@
   },
   "author": "明空",
   "license": "ISC",
+  "files": [
+    "index.js",
+    "app/",
+    "config/",
+    "core/",
+    "middleware/",
+    "response/",
+    "security/",
+    "storage/",
+    "utils/",
+    "doc/"
+  ],
   "dependencies": {
     "art-template": "^4.13.4",
     "cookie-parser": "^1.4.7",
@@ -26,15 +38,21 @@
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "express-art-template": "^1.0.1",
+    "i18next": "^24.2.0",
     "jsonwebtoken": "^9.0.3",
     "knex": "^3.2.10",
     "marked": "^18.0.3",
-    "morgan": "^1.10.1",
     "mysql2": "^3.22.3",
+    "node-cron": "^3.0.3",
+    "pino": "^9.5.0",
+    "pino-http": "^10.3.0",
     "serve-favicon": "^2.5.1",
     "xss": "^1.0.15",
     "ioredis": "^5.4.6"
   },
+  "devDependencies": {
+    "pino-pretty": "^11.3.0"
+  },
   "peerDependencies": {
     "zod": "^4.4.3"
   },

package/response/code.js

@@ -52,18 +52,6 @@ export const CODE_DB_CONNECTION_ERROR = 6001;
 export const CODE_DB_ACCESS_DENIED = 6002;
 export const CODE_DB_OPERATION_TIMEOUT = 6007;
 
-// 数据库原生错误标识 → 业务码映射
-export const DB_ERROR = Object.freeze({
-  ECONNREFUSED: 6001,
-  ER_ACCESS_DENIED_ERROR: 6002,
-  ER_ROW_IS_REFERENCED_2: 6003,
-  ER_BAD_FIELD_ERROR: 6004,
-  ER_DUP_ENTRY: 6005,
-  ER_NO_SUCH_TABLE: 6006,
-  ETIMEDOUT: 6007,
-  ER_TABLE_EXISTS_ERROR: 1005,
-});
-
 /**
  * 根据业务码获取默认提示文案
  * @param {number} code 业务状态码

package/response/response.js

@@ -31,7 +31,12 @@ export function serializeError(err, exposeDetail = false) {
   if (isAppError(err)) {
     const result = { success: false, code: err.code, msg: err.message };
     const extra = {};
+    // 框架内部字段永远不外泄；stack/cause(可能含SQL) 仅 dev(exposeDetail=true) 时附带
+    const NEVER_EXPOSE = new Set(["code", "message", "name", "meta", "httpStatus"]);
+    const SENSITIVE = new Set(["stack", "cause"]);
     for (const key of Object.getOwnPropertyNames(err)) {
+      if (NEVER_EXPOSE.has(key)) continue;
+      if (SENSITIVE.has(key) && !exposeDetail) continue; // 生产环境不泄露堆栈/根因(SQL)
       const val = err[key];
       if (val === undefined || val === null) continue;
       if (typeof val === "function" || typeof val === "symbol") continue;
@@ -42,11 +47,12 @@ export function serializeError(err, exposeDetail = false) {
     return result;
   }
 
-  // 原生未知系统错误：生产环境强制脱敏，不泄露 SQL / 堆栈
+  // 原生未知系统错误：生产环境强制脱敏，不泄露 SQL / 堆栈 / 根因
   return {
     success: false,
     code: CODE_SYSTEM_ERROR,
-    msg: err?.message || "系统内部错误",
+    // 生产环境不暴露原始 message（可能含 SQL 片段），仅 dev 透出
+    msg: exposeDetail ? (err?.message || "系统内部错误") : "系统内部错误",
     ...(exposeDetail && err?.stack ? { data: { stack: err.stack } } : {}),
   };
 }