chanjs 2.7.2 → 2.7.4

package/common/api.js

@@ -1,21 +1,31 @@
 /**
- * API响应常量定义
- * 提供统一的响应状态码和消息
+ * API 响应常量定义（旧版对象形式，保留向后兼容）
+ *
+ * ============================================================
+ * 重要说明
+ * ============================================================
+ * 业务侧推荐使用 helper/response.js 的函数式响应（success/fail/error），
+ * 通过 Controller 的 this.success() / this.fail() 调用。
+ *
+ * 本文件的 success/fail/error 为旧版对象常量，仅用于兼容历史代码。
+ * code 值已对齐新体系（0/1008/5001），不再使用 200/201/500。
+ *
+ * @deprecated 推荐使用 helper/response.js 的函数式响应
  */
 
 export const success = {
-  code: 200,
-  msg: "success",
+  code: 0,
+  msg: "操作成功",
 };
 
 export const fail = {
-  code: 201,
-  msg: "error",
+  code: 1008,
+  msg: "操作失败",
 };
 
 export const error = {
-  code: 500,
-  msg: "error",
+  code: 5001,
+  msg: "系统错误",
 };
 
 export default {

package/common/code.js

@@ -1,42 +1,52 @@
 /**
- * 响应状态码常量定义
- * 提供标准的状态码和对应消息
+ * 响应状态码常量定义（旧版对象形式，保留向后兼容）
+ *
+ * ============================================================
+ * 重要说明
+ * ============================================================
+ * 业务侧推荐使用 config/code.js 的三层 code 体系（0/1xxx/5xxx/6xxx），
+ * 该文件提供完整的 CODE 字典、CODE_RANGE 段位常量、语义化别名、DB_ERROR 映射。
+ *
+ * 本文件的 CODE 对象为旧版形式，仅用于兼容历史代码。
+ * code 值已对齐新体系，不再使用 200/201/500。
+ *
+ * @deprecated 推荐使用 config/code.js 的新体系
  */
 
 export const CODE = {
   /**
-   * 操作成功
+   * 操作成功（code: 0，不再用 200）
    */
   SUCCESS: {
-    code: 200,
+    code: 0,
     message: "操作成功",
   },
   /**
-   * 操作失败
+   * 操作失败（code: 1008 业务处理失败）
    */
   FAIL: {
-    code: 201,
+    code: 1008,
     message: "操作失败",
   },
   /**
-   * 服务器错误
+   * 系统错误（code: 5001 系统内部错误）
    */
   ERROR: {
-    code: 500,
-    message: "服务器错误",
+    code: 5001,
+    message: "系统错误",
   },
   /**
-   * 未授权
+   * 未授权（code: 1001 认证失败）
    */
   UNAUTHORIZED: {
-    code: 401,
-    message: "未授权",
+    code: 1001,
+    message: "认证失败",
   },
   /**
-   * 禁止访问
+   * 禁止访问（code: 1003 权限不足）
    */
   FORBIDDEN: {
-    code: 403,
-    message: "禁止访问",
+    code: 1003,
+    message: "权限不足",
   },
 };

package/common/email.js

@@ -1,10 +1,81 @@
 import nodemailer from "nodemailer";
+import Chan from "../App.js";
 
 /**
  * 邮件发送工具
  * 提供邮件发送和HTML模板生成功能
+ * 通过 import Chan 获取应用配置（不依赖 global.Chan）
  */
 
+/**
+ * 邮箱地址正则（基础校验，防注入和拼写错误）
+ */
+const EMAIL_REGEX = /^[^\s@<>'"`]+@[^\s@<>'"`]+\.[^\s@<>'"`]+$/;
+
+/**
+ * 模块级 transporter 缓存（避免每次发邮件都创建连接池）
+ * 配置不变时复用同一个 transporter，提升性能
+ */
+let _transporter = null;
+let _transporterKey = '';
+
+/**
+ * HTML 特殊字符转义，防止邮件模板注入
+ * @param {string} str - 待转义的字符串
+ * @returns {string} 转义后的字符串
+ */
+function escapeHtml(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * 校验收件人邮箱格式（基础规则，拒绝含特殊字符的非法地址）
+ * @param {string} email - 邮箱地址
+ * @returns {boolean} 是否合法
+ */
+function isValidEmail(email) {
+  return typeof email === 'string' && EMAIL_REGEX.test(email) && email.length <= 254;
+}
+
+/**
+ * 获取或创建 transporter（带缓存）
+ * @param {Object} EMAIL - 邮件配置
+ * @returns {Object} nodemailer transporter
+ */
+function getTransporter(EMAIL) {
+  // 用 host+port+user 作为缓存 key，配置变化时自动重建
+  const key = `${EMAIL.HOST}:${EMAIL.PORT}:${EMAIL.USER}`;
+  if (_transporter && _transporterKey === key) {
+    return _transporter;
+  }
+
+  _transporter = nodemailer.createTransport({
+    host: EMAIL.HOST,
+    port: parseInt(EMAIL.PORT),
+    secure: EMAIL.SECURE === "true",
+    auth: {
+      user: EMAIL.USER,
+      pass: EMAIL.PASS,
+    },
+    // 连接池配置：避免每次发邮件都握手，降低 SMTP 服务器压力
+    pool: true,
+    maxConnections: 5,
+    maxMessages: 100,
+    // 超时控制，避免 SMTP 卡死拖垮业务
+    connectionTimeout: 10 * 1000,
+    greetingTimeout: 10 * 1000,
+    socketTimeout: 30 * 1000,
+  });
+  _transporterKey = key;
+  return _transporter;
+}
+
 /**
  * 发送邮件
  * @param {string} to - 收件人邮箱
@@ -13,19 +84,19 @@ import nodemailer from "nodemailer";
  * @param {string|null} html - 邮件HTML内容，默认为null
  * @returns {Promise<Object>} 发送结果
  * @throws {Error} 邮件服务未配置或发送失败时抛出异常
+ * @description
+ * - 收件人邮箱格式校验，拒绝非法地址
+ * - transporter 模块级缓存，避免每次创建连接池
  */
 export const sendMail = async (to, subject, text, html = null) => {
+  // 收件人邮箱格式校验
+  if (!isValidEmail(to)) {
+    throw new Error(`[email] 收件人邮箱格式非法: ${to}`);
+  }
+
   const { EMAIL, APP_NAME } = Chan.config;
   
-  const transporter = nodemailer.createTransport({
-    host: EMAIL.HOST,
-    port: parseInt(EMAIL.PORT),
-    secure: EMAIL.SECURE === "true",
-    auth: {
-      user: EMAIL.USER,
-      pass: EMAIL.PASS,
-    },
-  });
+  const transporter = getTransporter(EMAIL);
   
   let res = await transporter.verify();
   if (!res) {
@@ -54,26 +125,31 @@ export const sendMail = async (to, subject, text, html = null) => {
  * @param {string} code - 验证码
  * @param {number} minutes - 有效期（分钟），默认10分钟
  * @returns {string} HTML字符串
+ * @description
+ * 安全改进：所有动态内容（code、APP_NAME）都经 escapeHtml 转义，防止 HTML 注入
  */
 export const genRegEmailHtml = (code, minutes = 10) => {
   const { APP_NAME } = Chan.config;
+  // 转义防止 HTML 注入
+  const safeCode = escapeHtml(code);
+  const safeAppName = escapeHtml(APP_NAME);
   return `
   <div style="font-family: Arial, sans-serif; max-width: 750px; margin: auto; border: 1px solid #ddd; border-radius: 10px; overflow: hidden;">
     <div style="background-color: #007bff; color: white; padding: 10px; text-align: center;">
-      <h2>${APP_NAME} 欢迎注册！</h2>
+      <h2>${safeAppName} 欢迎注册！</h2>
     </div>
     <div style="padding: 20px; line-height: 1.6;">
       <p>您好，感谢您注册我们的服务！</p>
       <p>您的注册验证码是：</p>
       <div style="font-size: 24px; font-weight: bold; color: #007bff; text-align: center; margin: 20px 0;">
-        ${code}
+        ${safeCode}
       </div>
-      <p>请在 <strong>${minutes} 分钟内</strong> 输入该验证码，完成账户验证。</p>
+      <p>请在 <strong>${escapeHtml(minutes)} 分钟内</strong> 输入该验证码，完成账户验证。</p>
       <p>如非本人操作，请忽略此邮件。</p>
       <p>祝您使用愉快！</p>
     </div>
     <div style="background-color: #f8f9fa; padding: 10px; text-align: center; font-size: 12px; color: #666;">
-      &copy; ${new Date().getFullYear()} ${APP_NAME}. 保留所有权利。
+      &copy; ${new Date().getFullYear()} ${safeAppName}. 保留所有权利。
     </div>
   </div>
   `;
@@ -84,26 +160,31 @@ export const genRegEmailHtml = (code, minutes = 10) => {
  * @param {string} code - 验证码
  * @param {number} minutes - 有效期（分钟），默认10分钟
  * @returns {string} HTML字符串
+ * @description
+ * 安全改进：所有动态内容（code、APP_NAME）都经 escapeHtml 转义，防止 HTML 注入
  */
 export const genResetPasswordEmail = (code, minutes = 10) => {
   const { APP_NAME } = Chan.config;
+  // 转义防止 HTML 注入
+  const safeCode = escapeHtml(code);
+  const safeAppName = escapeHtml(APP_NAME);
   return `
   <div style="font-family: Arial, sans-serif; max-width: 600px; margin: auto; border: 1px solid #ddd; border-radius: 10px; overflow: hidden;">
     <div style="background-color: #28a745; color: white; padding: 20px; text-align: center;">
-      <h2>重置密码_${APP_NAME}</h2>
+      <h2>重置密码_${safeAppName}</h2>
     </div>
     <div style="padding: 20px; line-height: 1.6;">
       <p>您好，我们收到了您重置密码的请求。</p>
        <p>您的重置密码验证码是：</p>
       <div style="font-size: 24px; font-weight: bold; color: #007bff; text-align: center; margin: 20px 0;">
-        ${code}
+        ${safeCode}
       </div>
-      <p>请在 <strong>${minutes} 分钟内</strong> 输入该验证码，完成账户验证。</p>
+      <p>请在 <strong>${escapeHtml(minutes)} 分钟内</strong> 输入该验证码，完成账户验证。</p>
       <p>如非本人操作，请忽略此邮件。</p>
       <p>祝您使用愉快！</p>
     </div>
     <div style="background-color: #f8f9fa; padding: 10px; text-align: center; font-size: 12px; color: #666;">
-      &copy; ${new Date().getFullYear()} ${APP_NAME}. 保留所有权利。
+      &copy; ${new Date().getFullYear()} ${safeAppName}. 保留所有权利。
     </div>
   </div>
   `;

package/common/index.js

@@ -1,5 +1,5 @@
 export { success, fail, error } from "./api.js";
-export { getChildrenId } from "./category.js";
+export { getChildrenId } from "./utils.js";
 export { CODE } from "./code.js";
 export { sendMail, genRegEmailHtml, genResetPasswordEmail } from "./email.js";
 export { pages, getHtmlFilesSync } from "./pages.js";

package/config/code.js

@@ -1,102 +1,127 @@
 /**
- * 业务状态码和数据库错误码映射
- * 定义系统中使用的各种状态码和错误码
+ * 业务状态码定义（统一三层 code 体系）
+ *
+ * ============================================================
+ * 设计原则
+ * ============================================================
+ * 1. 业务 code 与 HTTP Status 彻底解耦
+ *    - HTTP Status 由网关/Express 控制（200/400/401/403/404/500）
+ *    - 业务 code 由业务层控制（0 / 1xxx / 5xxx / 6xxx）
+ *    - 前端 axios 先看 HTTP Status，再看业务 code
+ *
+ * 2. 0 表示成功（不再用 200，避免与 HTTP 200 混淆）
+ *
+ * 3. 错误按业务域分段
+ *    - 1xxx 通用业务错误（认证/权限/参数/资源）
+ *    - 2xxx CMS 业务专用错误（保留扩展段）
+ *    - 5xxx 系统错误
+ *    - 6xxx 数据库错误
+ *
+ * 4. 每个 code 都有默认 msg，业务可覆盖
+ *
+ * ============================================================
+ * Code 段位定义
+ * ============================================================
+ * 0       → 成功
+ * 1001    → 认证失败（token 无效/未登录）
+ * 1002    → token 已过期
+ * 1003    → 权限不足
+ * 1004    → 资源不存在
+ * 1005    → 资源已存在
+ * 1006    → 参数无效
+ * 1007    → 参数缺失
+ * 1008    → 业务处理失败（通用兜底）
+ * 1009    → 请求过于频繁（限流）
+ * 1010    → 登录设备异常
+ * 2xxx    → CMS 业务专用错误（保留扩展段）
+ * 5001    → 系统内部错误
+ * 5002    → 服务繁忙，请稍后再试
+ * 6001    → 数据库连接失败
+ * 6002    → 数据库访问被拒绝
+ * 6003    → 存在关联数据，操作失败
+ * 6004    → 数据库字段错误
+ * 6005    → 数据重复，违反唯一性约束
+ * 6006    → 目标表不存在
+ * 6007    → 数据库操作超时
+ * 6008    → 数据库语法错误
+ * 6009    → 数据库连接已关闭
  */
 
+/**
+ * 业务状态码 → 默认消息
+ * @type {Object<number, string>}
+ */
 export const CODE = {
-  /**
-   * 操作成功
-   */
-  200: "操作成功",
-  /**
-   * 操作失败
-   */
-  201: "操作失败",
-  /**
-   * 业务处理失败
-   */
-  1001: "业务处理失败",
-  /**
-   * 参数无效
-   */
-  2001: "参数无效",
-  /**
-   * 参数缺失
-   */
-  2002: "参数缺失",
-  /**
-   * 认证失败
-   */
-  3001: "认证失败",
-  /**
-   * 令牌已过期
-   */
-  3002: "令牌已过期",
-  /**
-   * 权限不足
-   */
-  3003: "权限不足",
-  /**
-   * 资源不存在
-   */
-  4001: "资源不存在",
-  /**
-   * 资源已锁定
-   */
-  4002: "资源已锁定",
-  /**
-   * 资源已存在
-   */
-  4003: "资源已存在",
-  /**
-   * 系统内部错误
-   */
+  // 成功
+  0: "操作成功",
+
+  // 1xxx 通用业务错误
+  1001: "认证失败",
+  1002: "令牌已过期",
+  1003: "权限不足",
+  1004: "资源不存在",
+  1005: "资源已存在",
+  1006: "参数无效",
+  1007: "参数缺失",
+  1008: "业务处理失败",
+  1009: "请求过于频繁",
+  1010: "登录设备异常",
+
+  // 2xxx CMS 业务专用错误（保留扩展段，业务方可自定义）
+  // 例如：2001 文章不存在 / 2002 栏目不存在 等
+
+  // 5xxx 系统错误
   5001: "系统内部错误",
-  /**
-   * 服务繁忙，请稍后再试
-   */
   5002: "服务繁忙，请稍后再试",
-  /**
-   * 数据库连接失败
-   */
+
+  // 6xxx 数据库错误
   6001: "数据库连接失败",
-  /**
-   * 数据库访问被拒绝
-   */
   6002: "数据库访问被拒绝",
-  /**
-   * 存在关联数据，操作失败
-   */
   6003: "存在关联数据，操作失败",
-  /**
-   * 数据库字段错误
-   */
   6004: "数据库字段错误",
-  /**
-   * 数据重复，违反唯一性约束
-   */
   6005: "数据重复，违反唯一性约束",
-  /**
-   * 目标表不存在
-   */
   6006: "目标表不存在",
-  /**
-   * 数据库操作超时
-   */
   6007: "数据库操作超时",
-  /**
-   * 数据库语法错误，请检查查询语句
-   */
   6008: "数据库语法错误，请检查查询语句",
-  /**
-   * 数据库连接已关闭，请重试
-   */
   6009: "数据库连接已关闭，请重试",
 };
 
 /**
- * 数据库错误码映射
- * 将数据库原生错误码映射为业务状态码
+ * 业务 code 段位常量
+ * 便于业务方判断 code 归属段位
+ * @example
+ * if (code >= CODE_RANGE.SYSTEM[0] && code <= CODE_RANGE.SYSTEM[1]) { ... }
+ */
+export const CODE_RANGE = {
+  SUCCESS: [0, 0],            // 成功
+  BUSINESS: [1000, 1999],    // 通用业务错误
+  CMS: [2000, 2999],          // CMS 业务错误（保留扩展段）
+  SYSTEM: [5000, 5999],      // 系统错误
+  DATABASE: [6000, 6999],    // 数据库错误
+};
+
+/**
+ * 常用 code 语义化别名
+ * 业务方可直接用 CODE_OK / CODE_AUTH_FAILED 等语义化常量，避免硬编码数字
+ */
+export const CODE_OK = 0;                  // 成功
+export const CODE_AUTH_FAILED = 1001;       // 认证失败
+export const CODE_TOKEN_EXPIRED = 1002;     // token 过期
+export const CODE_FORBIDDEN = 1003;         // 权限不足
+export const CODE_NOT_FOUND = 1004;         // 资源不存在
+export const CODE_CONFLICT = 1005;          // 资源已存在
+export const CODE_PARAM_INVALID = 1006;     // 参数无效
+export const CODE_PARAM_MISSING = 1007;     // 参数缺失
+export const CODE_BUSINESS_FAIL = 1008;     // 业务处理失败（通用）
+export const CODE_RATE_LIMIT = 1009;        // 限流
+export const CODE_DEVICE_ERROR = 1010;       // 登录设备异常
+export const CODE_SYSTEM_ERROR = 5001;      // 系统内部错误
+export const CODE_SERVICE_BUSY = 5002;       // 服务繁忙
+
+/**
+ * 数据库原生错误码 → 业务 code 映射
+ * 将 MySQL/Knex 等数据库原生错误码转换为业务 code
+ * @type {Object<string, number>}
  */
 export const DB_ERROR = {
   ECONNREFUSED: 6001,
@@ -106,5 +131,36 @@ export const DB_ERROR = {
   ER_DUP_ENTRY: 6005,
   ER_NO_SUCH_TABLE: 6006,
   ETIMEOUT: 6007,
-  ER_TABLE_EXISTS_ERROR: 4003,
+  ER_TABLE_EXISTS_ERROR: 1005,  // 表已存在 → 资源已存在
 };
+
+/**
+ * 判断 code 是否为成功
+ * @param {number} code - 业务 code
+ * @returns {boolean}
+ */
+export function isSuccessCode(code) {
+  return code === CODE_OK;
+}
+
+/**
+ * 判断 code 所属段位
+ * @param {number} code - 业务 code
+ * @returns {string} 段位名：SUCCESS / BUSINESS / CMS / SYSTEM / DATABASE / UNKNOWN
+ */
+export function getCodeRange(code) {
+  for (const [name, [min, max]] of Object.entries(CODE_RANGE)) {
+    if (code >= min && code <= max) return name;
+  }
+  return 'UNKNOWN';
+}
+
+/**
+ * 获取 code 的默认消息
+ * @param {number} code - 业务 code
+ * @param {string} [fallback='操作失败'] - 兜底消息
+ * @returns {string}
+ */
+export function getCodeMsg(code, fallback = '操作失败') {
+  return CODE[code] || fallback;
+}

package/global/index.js

@@ -3,6 +3,6 @@
  * 导入所有全局配置和功能
  */
 
-import "./global.js";
+
 import "./import.js";
 import "./env.js";

package/helper/index.js

@@ -1,11 +1,25 @@
-// 加载器相关
-export { loaderSort, loadConfig, clearConfigCache, loadController } from "./loader.js";
+/**
+ * 聚合导出层 - 从各子模块统一 re-export
+ *
+ * 框架内部已按职责拆分到 storage/security/realtime/schedule/loader/response/utils
+ * 本文件提供扁平化聚合访问，业务侧可用：
+ *   import { helper } from "chanjs";
+ *   const { getIp, formatDateFields, filterXSS } = helper;
+ *
+ * 也可直接从子模块导入（更精确）：
+ *   import { utils, security, storage } from "chanjs";
+ */
+
+// 加载器
+export { loaderSort, loadConfig, clearConfigCache, loadController } from "../loader/index.js";
 
 // 时间处理
-export { formatTime, formatDateFields } from "./time.js";
+export { formatTime, formatDateFields } from "../utils/time.js";
 
-// 缓存相关
-export { cache } from "./cache.js";
+// 存储相关
+export { cache, DEFAULT_INCR_TTL } from "../storage/index.js";
+export { store } from "../storage/index.js";
+export { default as RedisBackend } from "../storage/redis.js";
 
 // 文件操作
 export {
@@ -15,47 +29,32 @@ export {
   readFileContent,
   saveFileContent,
   isPathSafe,
-  getFolders
-} from "./file.js";
+  getFolders,
+} from "../utils/file.js";
 
-// HTML处理
-export { htmlDecode, htmlEncode,escapeScript } from "./html.js";
+// HTML 处理
+export { htmlDecode, htmlEncode, escapeScript } from "../utils/html.js";
 
-// IP相关
-export { getIp } from "./ip.js";
+// IP 获取
+export { getIp } from "../utils/ip.js";
 
-// JWT令牌
-export {
-  verifyToken,
-  generateToken,
-  setToken,
-  getToken
-} from "./jwt.js";
+// JWT 令牌
+export { verifyToken, generateToken, setToken, getToken } from "../security/jwt.js";
 
 // 签名/加密
-export {
-  signData,
-  verifySign,
-  aesEncrypt,
-  aesDecrypt
-} from "./sign.js";
+export { signData, verifySign, aesEncrypt, aesDecrypt } from "../security/sign.js";
 
 // 网络请求
-export { request } from "./request.js";
+export { request } from "../utils/request.js";
 
 // 数据解析
-export {
-  dataParse,
-  arrToObj,
-  parseJsonFields,
-  buildTree
-} from "./data-parse.js";
+export { dataParse, arrToObj, parseJsonFields, buildTree } from "../utils/data-parse.js";
 
 // 树形结构
-export { tree, treeById } from "./tree.js";
+export { tree, treeById } from "../utils/tree.js";
 
 // 字段过滤
-export { filterFields } from "./filter.js";
+export { filterFields } from "../utils/filter.js";
 
 // 响应格式化
 export {
@@ -64,14 +63,17 @@ export {
   error,
   parseDatabaseError,
   notFoundResponse,
-  errorResponse
-} from "./response.js";
+  errorResponse,
+} from "../response/index.js";
 
-// 内容检查
-export { checkKeywords, isIgnored } from "./checker.js";
+// 安全检查
+export { checkKeywords, isIgnored } from "../security/checker.js";
+export { filterXSS } from "../security/xss-filter.js";
+export { createRateLimitMiddleware } from "../security/rate-limit.js";
 
-// XSS过滤
-export { filterXSS } from "./xss-filter.js";
+// 定时任务
+export { schedule } from "../schedule/index.js";
 
-// 限流中间件
-export { createRateLimitMiddleware } from "./rate-limit.js";
+// 实时通信
+export { sse, SSEManager } from "../realtime/index.js";
+export { websocket, WebSocketManager } from "../realtime/index.js";