chanjs 2.7.3 → 2.7.5

package/doc/Help.md

@@ -1,789 +1,390 @@
-# chanjs/helper/index.js 工具函数使用文档
-本文档详细说明 `chanjs/helper/index.js` 导出的所有工具函数的调用方式、参数说明及使用示例，帮助开发者快速集成和使用这些工具。
+# ChanJS 框架 API 参考
 
-## 一、加载器相关（loader.js）
-### 1. loaderSort
-**功能**：对加载的模块/配置进行排序处理  
-**调用方式**：
-```javascript
-import { loaderSort } from 'chanjs/helper/index.js';
+## 概述
 
-// 示例：对加载的控制器列表排序
-const loadList = [{ name: 'user', order: 2 }, { name: 'auth', order: 1 }];
-const sortedList = loaderSort(loadList); // 按order升序排列
-console.log(sortedList); // [{ name: 'auth', order: 1 }, { name: 'user', order: 2 }]
-```
-**参数说明**：
-- `list` (Array)：需要排序的加载项数组，数组项需包含排序字段（如`order`，具体字段由内部逻辑定义）
-- 返回值：排序后的数组
+ChanJS 是基于 Express 5 的轻量级 Node.js MVC 框架，采用纯 JavaScript（ESM）编写。本文档汇总框架所有对外暴露的 API。
+
+## 包入口
 
-### 2. loadConfig
-**功能**：加载项目配置文件（如JSON/JS配置）  
-**调用方式**：
 ```javascript
-import { loadConfig } from 'chanjs/helper/index.js';
+import Chan from 'chanjs';  // 默认导出：应用主类
 
-// 示例：加载指定路径的配置
-const config = loadConfig('config/app.js');
-console.log(config); // 配置文件导出的内容
+// 命名导出
+import {
+  Controller, Repository, Service,
+  AppError, NotFoundError, ValidationError, BusinessError,
+  // ... 更多错误类
+  describeError, errorExtraProps, parseStack, isAppError, wrapDbError,
+  success, fail, routeNotFound, serializeError, buildErrorHtml, respondError,
+  setToken, getToken, verifyToken,
+  aesEncrypt, aesDecrypt,
+  logger, createLogger,
+  validate, validateAll,
+  setApp, getApp,
+  loader, utils,
+  cache, store, Paths,
+  helper
+} from 'chanjs';
 ```
-**参数说明**：
-- `path` (String)：配置文件路径（相对/绝对）
-- 返回值：配置文件的导出内容
 
-### 3. clearConfigCache
-**功能**：清除配置加载的缓存（避免配置修改后读取旧值）  
-**调用方式**：
-```javascript
-import { clearConfigCache } from 'chanjs/helper/index.js';
+## 核心类
 
-// 示例：修改配置后清除缓存
-clearConfigCache(); // 无参数，直接调用
-```
-**参数说明**：无参数  
-**返回值**：无
+### Chan - 应用主类
 
-### 4. loadController
-**功能**：加载指定目录下的控制器文件  
-**调用方式**：
 ```javascript
-import { loadController } from 'chanjs/helper/index.js';
-
-// 示例：加载controllers目录下的所有控制器
-const controllers = loadController('app/controllers');
-console.log(controllers); // 控制器实例/映射对象
+const app = new Chan();
+await app.start();
+app.run(port => console.log(`监听端口 ${port}`));
 ```
-**参数说明**：
-- `dir` (String)：控制器目录路径
-- 返回值：加载后的控制器集合（对象/数组，具体格式由内部逻辑定义）
-
-## 二、时间处理（time.js）
-### 1. formatTime
-**功能**：格式化时间戳/日期对象为指定格式的字符串  
-**调用方式**：
-```javascript
-import { formatTime } from 'chanjs/helper/index.js';
 
-// 示例1：格式化当前时间
-const now = new Date();
-const timeStr1 = formatTime(now, 'YYYY-MM-DD HH:mm:ss'); // 2024-05-20 14:30:00
+| 方法 | 说明 |
+|------|------|
+| `start()` | 完整启动流程（配置→缓存→数据库→中间件→路由→错误处理→钩子） |
+| `run(cb)` | 启动 HTTP 监听，`cb(port)` 回调接收端口号 |
+| `beforeStart(fn)` | 注册启动前置钩子 |
+| `shutdown()` | 执行优雅停机 |
+
+### Controller - 控制器基类
 
-// 示例2：格式化时间戳
-const timestamp = 1716205800000;
-const timeStr2 = formatTime(timestamp, 'YYYY/MM/DD'); // 2024/05/20
-```
-**参数说明**：
-- `time` (Date/Number/String)：待格式化的时间（日期对象/时间戳/时间字符串）
-- `format` (String)：格式模板，支持 `YYYY`(年)、`MM`(月)、`DD`(日)、`HH`(时)、`mm`(分)、`ss`(秒)
-- 返回值：格式化后的时间字符串
-
-### 2. formatDateFields
-**功能**：批量格式化对象中的日期字段（如将时间戳字段转为格式化字符串）  
-**调用方式**：
 ```javascript
-import { formatDateFields } from 'chanjs/helper/index.js';
-
-// 示例：格式化对象中的createTime和updateTime字段
-const data = {
-  id: 1,
-  createTime: 1716205800000,
-  updateTime: 1716206800000
-};
-const formattedData = formatDateFields(data, ['createTime', 'updateTime'], 'YYYY-MM-DD');
-// { id: 1, createTime: '2024-05-20', updateTime: '2024-05-20' }
+class UserController extends Controller {
+  async getUser(req, res) {
+    return this.success({ data: { id: 1 } });
+  }
+}
 ```
-**参数说明**：
-- `obj` (Object)：需要处理的对象
-- `fields` (Array)：需要格式化的日期字段名数组
-- `format` (String)：时间格式模板（同formatTime）
-- 返回值：格式化后的新对象
-
-## 三、缓存相关（cache.js）
-### 1. Cache（默认导出类）
-**功能**：缓存操作类（支持设置、获取、删除缓存等）  
-**调用方式**：
+
+| 方法 | 说明 |
+|------|------|
+| `success({ data, msg })` | 成功响应，默认 code=0 |
+| `fail(opts)` | 失败响应，支持字符串简写或对象配置，默认 code=1008 |
+
+### Repository - 数据访问基类
+
 ```javascript
-import { Cache } from 'chanjs/helper/index.js';
+class UserRepo extends Repository {
+  constructor() {
+    super('users');  // 表名
+  }
+}
+```
 
-// 示例：实例化并使用缓存
-const cache = new Cache();
+| 方法 | 说明 |
+|------|------|
+| `all({ query, sort, fields, limit })` | 查询全部，默认上限 1000 条 |
+| `find({ query, sort, fields, limit, offset })` | 分页偏移查询 |
+| `findOne({ query, fields })` | 查询单条 |
+| `findById(id, { fields })` | 根据 ID 查询 |
+| `insert(data)` | 单条插入 |
+| `insertMany(records)` | 批量插入 |
+| `del(query)` | 条件删除 |
+| `deleteById(id)` | 根据 ID 删除 |
+| `deleteMany(ids)` | 批量删除 |
+| `updateByQuery({ query, data })` | 条件更新 |
+| `updateById(id, data)` | 根据 ID 更新 |
+| `updateMany(updates)` | 事务批量更新 |
+| `query({ current, pageSize, query, sort, field })` | 标准分页查询 |
+| `count(query)` | 统计行数 |
+| `exists(query)` | 判断是否存在 |
+| `join({ joinTable, localField, foreignField, fields, query, sort })` | 联表查询 |
+| `stats()` | 统计总数 + 今日新增 |
+
+### Service - 服务基类
+
+```javascript
+class UserService extends Service {
+  constructor() {
+    super();
+    this.userRepo = new UserRepo();
+  }
+}
+```
 
-// 设置缓存（key, value, 过期时间（秒））
-cache.set('user_1', { name: '张三' }, 3600);
+Service 是纯业务逻辑层，不包含 CRUD 方法。通过注入 Repository 实例进行数据操作。
 
-// 获取缓存
-const user = cache.get('user_1');
-console.log(user); // { name: '张三' }
+## 错误体系
 
-// 删除缓存
-cache.del('user_1');
+### 错误类
 
-// 清空所有缓存
-cache.clear();
-```
-**核心方法**：
-- `set(key, value, expire)`：设置缓存，`expire` 为过期时间（秒），可选
-- `get(key)`：获取缓存，返回缓存值（无则返回null）
-- `del(key)`：删除指定key的缓存
-- `clear()`：清空所有缓存
-
-## 四、文件操作（file.js）
-### 1. dirname
-**功能**：获取文件/路径的目录名（兼容不同系统路径）  
-**调用方式**：
-```javascript
-import { dirname } from 'chanjs/helper/index.js';
+| 类名 | 默认 code | HTTP 状态 | 默认提示 |
+|------|-----------|-----------|----------|
+| `AppError` | - | - | 基础类 |
+| `AuthError` | 1001 | 401 | 认证失败 |
+| `TokenExpiredError` | 1002 | 401 | 令牌已过期 |
+| `ForbiddenError` | 1003 | 403 | 权限不足 |
+| `NotFoundError` | 1004 | 404 | 资源不存在 |
+| `ConflictError` | 1005 | 409 | 资源已存在 |
+| `ValidationError` | 1006 | 422 | 参数无效 |
+| `ParamMissingError` | 1007 | 400 | 参数缺失 |
+| `BusinessError` | 1008 | 400 | 业务处理失败 |
+| `RateLimitError` | 1009 | 429 | 请求过于频繁 |
+| `BlockedError` | 1011 | 403 | 访问已被限制 |
+| `SystemError` | 5001 | 500 | 系统内部错误 |
+| `ServiceBusyError` | 5002 | 503 | 服务繁忙 |
+| `DbConnectionError` | 6001 | 503 | 数据库连接失败 |
+| `DbAccessDeniedError` | 6002 | 503 | 数据库访问被拒绝 |
+| `DbTimeoutError` | 6007 | 503 | 数据库操作超时 |
 
-// 示例：获取文件的目录路径
-const filePath = '/app/controllers/user.js';
-const dir = dirname(filePath);
-console.log(dir); // /app/controllers
-```
-**参数说明**：
-- `path` (String)：文件/路径字符串
-- 返回值：目录名字符串
+### 错误类使用
 
-### 2. delImg
-**功能**：删除指定路径的图片文件  
-**调用方式**：
 ```javascript
-import { delImg } from 'chanjs/helper/index.js';
+// 字符串简写
+throw new NotFoundError('用户不存在');
+
+// 对象配置
+throw new ValidationError({ 
+  msg: '参数校验失败', 
+  fields: ['name', 'email'] 
+});
 
-// 示例：删除上传的图片
-const imgPath = '/uploads/2024/05/avatar.png';
-const isDel = delImg(imgPath);
-console.log(isDel); // true（删除成功）/false（删除失败）
+// 带底层 cause
+throw new SystemError('系统异常', originalError);
 ```
-**参数说明**：
-- `imgPath` (String)：图片文件路径
-- 返回值：Boolean，是否删除成功
 
-### 3. getFileTree
-**功能**：生成指定目录的文件树结构（递归遍历）  
-**调用方式**：
-```javascript
-import { getFileTree } from 'chanjs/helper/index.js';
+### 错误工具函数
 
-// 示例：生成src目录的文件树
-const tree = getFileTree('/app/src');
-console.log(tree); 
-// 输出示例：{ name: 'src', type: 'dir', children: [{ name: 'utils', type: 'dir', children: [...] }, ...] }
-```
-**参数说明**：
-- `dir` (String)：目标目录路径
-- 返回值：Object，文件树结构（包含name、type、children等字段）
+| 函数 | 说明 |
+|------|------|
+| `isAppError(err)` | 判断是否为业务错误实例 |
+| `describeError(err)` | 递归解析完整可读错误信息 |
+| `errorExtraProps(err)` | 提取错误自定义附加属性 |
+| `wrapDbError(err)` | 将数据库原生错误转换为 AppError 子类 |
+| `parseStack(stack)` | 解析 V8 堆栈，提取报错文件和行号 |
 
-### 4. readFileContent
-**功能**：读取文件内容（支持文本/JSON格式）  
-**调用方式**：
-```javascript
-import { readFileContent } from 'chanjs/helper/index.js';
+## 响应工具
 
-// 示例1：读取文本文件
-const text = readFileContent('/app/config.txt', 'utf8');
-console.log(text); // 文件文本内容
+| 函数 | 说明 |
+|------|------|
+| `success({ data, msg })` | 成功响应，code=0 |
+| `fail({ msg, code, data })` | 失败响应，默认 code=1008 |
+| `routeNotFound(req)` | 404 路由不存在响应 |
+| `serializeError(err, exposeDetail)` | 统一错误序列化 |
+| `buildErrorHtml(status, msg, code, req)` | 构建错误 HTML 页面 |
+| `respondError(res, req, opts, apiPrefixes)` | 统一错误响应出口（HTML/JSON 自动分流） |
+
+## 安全工具
+
+### JWT
 
-// 示例2：读取JSON文件
-const json = readFileContent('/app/config.json', 'json');
-console.log(json); // 解析后的JSON对象
-```
-**参数说明**：
-- `filePath` (String)：文件路径
-- `type` (String)：读取类型，可选 `utf8`（文本）/`json`（JSON），默认`utf8`
-- 返回值：String/Object，文件内容（JSON类型返回解析后的对象）
-
-### 5. saveFileContent
-**功能**：写入内容到文件（支持覆盖/追加）  
-**调用方式**：
 ```javascript
-import { saveFileContent } from 'chanjs/helper/index.js';
+import { setToken, getToken, verifyToken } from 'chanjs';
 
-// 示例1：覆盖写入文本
-saveFileContent('/app/log.txt', '操作日志：用户登录', 'overwrite');
+// 签发令牌
+const token = setToken({ userId: 1 }, secretKey, '7d');
 
-// 示例2：追加写入文本
-saveFileContent('/app/log.txt', '\n操作日志：用户退出', 'append');
+// 校验令牌（详细结果）
+const result = await verifyToken(token, secretKey);
+// { valid: true, reason: 'ok', payload: {...} }
+// { valid: false, reason: 'expired' | 'invalid' | 'revoked' | 'missing' }
 
-// 示例3：写入JSON对象
-saveFileContent('/app/data.json', { list: [1,2,3] }, 'json');
+// 校验令牌（成功返回载荷，失败返回 null）
+const payload = await getToken(token, secretKey);
 ```
-**参数说明**：
-- `filePath` (String)：文件路径
-- `content` (String/Object)：写入内容（JSON类型自动序列化）
-- `mode` (String)：写入模式，可选 `overwrite`（覆盖）/`append`（追加）/`json`（JSON写入），默认`overwrite`
-- 返回值：Boolean，是否写入成功
-
-### 6. isPathSafe
-**功能**：校验路径是否安全（防止路径遍历攻击）  
-**调用方式**：
-```javascript
-import { isPathSafe } from 'chanjs/helper/index.js';
 
-// 示例1：安全路径
-const safe = isPathSafe('/app/uploads/avatar.png', '/app/uploads');
-console.log(safe); // true
+### AES 加解密
 
-// 示例2：危险路径（路径遍历）
-const unsafe = isPathSafe('/app/uploads/../config.js', '/app/uploads');
-console.log(unsafe); // false
-```
-**参数说明**：
-- `path` (String)：待校验的路径
-- `root` (String)：允许的根目录
-- 返回值：Boolean，路径是否安全
-
-### 7. getFolders
-**功能**：获取指定目录下的所有子目录  
-**调用方式**：
 ```javascript
-import { getFolders } from 'chanjs/helper/index.js';
+import { aesEncrypt, aesDecrypt } from 'chanjs';
 
-// 示例：获取src目录下的所有子目录
-const folders = getFolders('/app/src');
-console.log(folders); // ['utils', 'controllers', 'models']
+const encrypted = await aesEncrypt('敏感数据', secretKey);
+const decrypted = await aesDecrypt(encrypted, secretKey);
 ```
-**参数说明**：
-- `dir` (String)：目标目录路径
-- 返回值：Array，子目录名称数组
-
-## 五、HTML处理（html.js）
-### 1. htmlDecode
-**功能**：HTML实体解码（将`&`/`<`等转为原字符）  
-**调用方式**：
-```javascript
-import { htmlDecode } from 'chanjs/helper/index.js';
 
-// 示例：解码HTML实体
-const htmlStr = '<div>张三&李四</div>';
-const rawStr = htmlDecode(htmlStr);
-console.log(rawStr); // <div>张三&李四</div>
-```
-**参数说明**：
-- `str` (String)：包含HTML实体的字符串
-- 返回值：String，解码后的原始字符串
-
-## 六、IP相关（ip.js）
-### 1. getIp
-**功能**：从请求对象中获取客户端真实IP（兼容反向代理）  
-**调用方式**：
-```javascript
-import { getIp } from 'chanjs/helper/index.js';
-// 示例（Express/Koa框架）
-app.get('/', (req, res) => {
-  const ip = getIp(req); // Koa需传req.req
-  console.log(ip); // 客户端IP，如 192.168.1.100
-  res.send(`你的IP：${ip}`);
-});
-```
-**参数说明**：
-- `req` (Object)：HTTP请求对象（Express/Koa的req）
-- 返回值：String，客户端真实IP
-
-## 七、JWT令牌（jwt.js）
-### 1. verifyToken
-**功能**：验证JWT令牌的有效性  
-**调用方式**：
-```javascript
-import { verifyToken } from 'chanjs/helper/index.js';
-
-// 示例：验证令牌
-const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
-try {
-  const payload = verifyToken(token); // 内部已配置密钥
-  console.log(payload); // 令牌解析后的载荷，如 { userId: 1, exp: 1716300000 }
-} catch (err) {
-  console.error('令牌无效：', err.message);
-}
-```
-**参数说明**：
-- `token` (String)：JWT令牌字符串
-- 返回值：Object，令牌载荷（验证失败抛出异常）
+### 参数校验中间件
 
-### 2. generateToken
-**功能**：生成JWT令牌  
-**调用方式**：
 ```javascript
-import { generateToken } from 'chanjs/helper/index.js';
+import { validate, validateAll } from 'chanjs';
+import { z } from 'zod';
 
-// 示例：生成令牌（有效期1小时）
-const payload = { userId: 1, username: '张三' };
-const token = generateToken(payload, 3600); // 过期时间3600秒
-console.log(token); // 生成的JWT字符串
-```
-**参数说明**：
-- `payload` (Object)：令牌载荷（需包含非敏感信息）
-- `expire` (Number)：过期时间（秒），默认3600
-- 返回值：String，JWT令牌
-
-### 3. setToken
-**功能**：设置令牌到响应头/客户端存储（如Cookie）  
-**调用方式**：
-```javascript
-import { setToken } from 'chanjs/helper/index.js';
-// 示例（Express框架）
-app.post('/login', (req, res) => {
-  const token = generateToken({ userId: 1 });
-  setToken(res, token); // 将令牌设置到Cookie/响应头
-  res.send({ code: 200, msg: '登录成功' });
-});
-```
-**参数说明**：
-- `res` (Object)：HTTP响应对象（Express/Koa的res）
-- `token` (String)：JWT令牌
-- 返回值：无
-
-### 4. getToken
-**功能**：从请求中获取JWT令牌（从Header/Cookie）  
-**调用方式**：
-```javascript
-import { getToken } from 'chanjs/helper/index.js';
-// 示例（Express框架）
-app.get('/profile', (req, res) => {
-  const token = getToken(req); // 从Authorization头/Cookie获取
-  if (!token) {
-    return res.send({ code: 401, msg: '未登录' });
-  }
-  // 验证令牌...
-});
-```
-**参数说明**：
-- `req` (Object)：HTTP请求对象（Express/Koa的req）
-- 返回值：String/null，获取到的令牌（无则返回null）
-
-## 八、签名/加密（sign.js）
-### 1. signData
-**功能**：对数据进行签名（防止篡改）  
-**调用方式**：
-```javascript
-import { signData } from 'chanjs/helper/index.js';
+// 单源校验
+router.post('/user', validate('body', z.object({
+  name: z.string().min(1),
+  age: z.number().int().positive()
+})), ctrl.create);
 
-// 示例：对数据签名
-const data = { userId: 1, amount: 100 };
-const sign = signData(data, 'your-secret-key'); // 传入数据和密钥
-console.log(sign); // 生成的签名字符串
+// 多源校验
+router.post('/user', validateAll({
+  body: z.object({ name: z.string() }),
+  query: z.object({ page: z.coerce.number() })
+}), ctrl.create);
 ```
-**参数说明**：
-- `data` (Object)：待签名的数据
-- `secret` (String)：签名密钥（内部可配置默认密钥）
-- 返回值：String，签名字符串
-
-### 2. verifySign
-**功能**：验证数据签名的有效性  
-**调用方式**：
-```javascript
-import { verifySign } from 'chanjs/helper/index.js';
 
-// 示例：验证签名
-const data = { userId: 1, amount: 100 };
-const sign = 'xxx...'; // 前端传入的签名
-const isValid = verifySign(data, sign, 'your-secret-key');
-console.log(isValid); // true（签名有效）/false（无效）
-```
-**参数说明**：
-- `data` (Object)：原始数据
-- `sign` (String)：待验证的签名
-- `secret` (String)：签名密钥（需与签名时一致）
-- 返回值：Boolean，签名是否有效
-
-### 3. aesEncrypt
-**功能**：AES加密数据  
-**调用方式**：
+### XSS 过滤
+
 ```javascript
-import { aesEncrypt } from 'chanjs/helper/index.js';
+import { filterXSS } from 'chanjs';
 
-// 示例：加密字符串
-const rawData = '敏感信息：123456';
-const encrypted = aesEncrypt(rawData, 'aes-secret-key', 'aes-iv'); // 密钥+向量
-console.log(encrypted); // 加密后的Base64字符串
+const safe = filterXSS('<script>alert("xss")</script>');
+// 支持字符串、对象、数组递归过滤
 ```
-**参数说明**：
-- `data` (String)：待加密数据
-- `key` (String)：AES密钥（内部可配置默认）
-- `iv` (String)：AES向量（内部可配置默认）
-- 返回值：String，加密后的Base64字符串
-
-### 4. aesDecrypt
-**功能**：AES解密数据  
-**调用方式**：
+
+### 关键词检测
+
 ```javascript
-import { aesDecrypt } from 'chanjs/helper/index.js';
+import { checkKeywords } from 'chanjs';
 
-// 示例：解密
-const encrypted = 'xxx...'; // 加密后的字符串
-const decrypted = aesDecrypt(encrypted, 'aes-secret-key', 'aes-iv');
-console.log(decrypted); // 原始敏感信息：123456
+const result = checkKeywords('SELECT * FROM users');
+// null 或 { category: 'sqlInjection', keyword: 'SELECT' }
 ```
-**参数说明**：
-- `data` (String)：加密后的Base64字符串
-- `key` (String)：AES密钥（需与加密时一致）
-- `iv` (String)：AES向量（需与加密时一致）
-- 返回值：String，解密后的原始数据
-
-## 九、网络请求（request.js）
-### 1. request
-**功能**：封装的HTTP请求方法（支持GET/POST等）  
-**调用方式**：
+
+### 限流中间件
+
 ```javascript
-import { request } from 'chanjs/helper/index.js';
-
-// 示例1：GET请求
-request({
-  url: 'https://api.example.com/user',
-  method: 'GET',
-  params: { id: 1 } // URL参数
-}).then(res => {
-  console.log(res); // 响应数据
-}).catch(err => {
-  console.error(err);
-});
+import { createRateLimitMiddleware } from 'chanjs';
 
-// 示例2：POST请求（JSON数据）
-request({
-  url: 'https://api.example.com/user',
-  method: 'POST',
-  data: { name: '张三', age: 20 }, // 请求体
-  headers: { 'Content-Type': 'application/json' }
-}).then(res => {
-  console.log(res);
+const rateLimit = createRateLimitMiddleware({
+  windowMs: '1m',    // 时间窗口，支持 '1s'/'1m'/'1h'/'1d' 格式
+  max: 100,          // 窗口内最大请求数
+  ignorePaths: ['/api/public']  // 忽略路径
 });
 ```
-**参数说明**：
-- `options` (Object)：请求配置
-  - `url` (String)：请求地址（必传）
-  - `method` (String)：请求方法，默认GET
-  - `params` (Object)：URL查询参数
-  - `data` (Object/String)：请求体数据
-  - `headers` (Object)：请求头
-  - `timeout` (Number)：超时时间（毫秒），默认5000
-- 返回值：Promise，解析后为响应数据
-
-## 十、数据解析（data-parse.js）
-### 1. dataParse
-**功能**：通用数据解析（如表单数据/JSON字符串转对象）  
-**调用方式**：
-```javascript
-import { dataParse } from 'chanjs/helper/index.js';
 
-// 示例1：解析JSON字符串
-const jsonStr = '{"name":"张三","age":20}';
-const obj1 = dataParse(jsonStr, 'json');
-console.log(obj1); // { name: '张三', age: 20 }
+## 存储层
 
-// 示例2：解析表单字符串
-const formStr = 'name=张三&age=20';
-const obj2 = dataParse(formStr, 'form');
-console.log(obj2); // { name: '张三', age: '20' }
-```
-**参数说明**：
-- `data` (String)：待解析的数据
-- `type` (String)：解析类型，可选 `json`/`form`，默认`json`
-- 返回值：Object，解析后的对象
-
-### 2. arrToObj
-**功能**：将数组转为对象（指定key为属性名）  
-**调用方式**：
-```javascript
-import { arrToObj } from 'chanjs/helper/index.js';
+### cache - 内存缓存
 
-// 示例：将用户数组转为以id为key的对象
-const userArr = [{ id: 1, name: '张三' }, { id: 2, name: '李四' }];
-const userObj = arrToObj(userArr, 'id');
-console.log(userObj); 
-// { 1: { id: 1, name: '张三' }, 2: { id: 2, name: '李四' } }
-```
-**参数说明**：
-- `arr` (Array)：源数组
-- `key` (String)：作为对象属性名的字段
-- 返回值：Object，转换后的对象
-
-### 3. parseJsonFields
-**功能**：解析对象中的JSON字符串字段为对象  
-**调用方式**：
 ```javascript
-import { parseJsonFields } from 'chanjs/helper/index.js';
-
-// 示例：解析userInfo字段（JSON字符串）
-const data = {
-  id: 1,
-  userInfo: '{"name":"张三","age":20}'
-};
-const parsedData = parseJsonFields(data, ['userInfo']);
-console.log(parsedData.userInfo); // { name: '张三', age: 20 }
-```
-**参数说明**：
-- `obj` (Object)：源对象
-- `fields` (Array)：需要解析的字段名数组
-- 返回值：Object，解析后的新对象
-
-### 4. buildTree
-**功能**：将扁平数组转为树形结构（如分类/菜单）  
-**调用方式**：
-```javascript
-import { buildTree } from 'chanjs/helper/index.js';
-
-// 示例：构建菜单树
-const menuArr = [
-  { id: 1, name: '系统管理', parentId: 0 },
-  { id: 2, name: '用户管理', parentId: 1 },
-  { id: 3, name: '角色管理', parentId: 1 }
-];
-const menuTree = buildTree(menuArr, 'id', 'parentId', 'children');
-console.log(menuTree);
-// 输出：[{ id: 1, name: '系统管理', parentId: 0, children: [{ id: 2, ... }, { id: 3, ... }] }]
-```
-**参数说明**：
-- `arr` (Array)：扁平数组
-- `idKey` (String)：ID字段名，默认'id'
-- `parentKey` (String)：父ID字段名，默认'parentId'
-- `childrenKey` (String)：子节点字段名，默认'children'
-- 返回值：Array，树形结构数组
-
-## 十一、树形结构（tree.js）
-### 1. tree
-**功能**：通用树形结构生成（简化版buildTree）  
-**调用方式**：
-```javascript
-import { tree } from 'chanjs/helper/index.js';
-
-// 示例：生成分类树
-const cateArr = [
-  { id: 1, name: '电子产品', parentId: 0 },
-  { id: 2, name: '手机', parentId: 1 }
-];
-const cateTree = tree(cateArr);
-console.log(cateTree); // 树形结构数组
+import { cache } from 'chanjs';
+
+cache.set('key', value, 60000);  // 设置，TTL 毫秒
+cache.get('key');                 // 读取
+cache.has('key');                 // 检查存在
+cache.del('key');                 // 删除
+cache.clear();                    // 清空
+cache.size();                     // 获取数量
+cache.incr('key', 60000);         // 自增（限流专用）
+cache.incrAndExpire('key', 60000); // 自增并设置过期时间
+cache.expire('key', 30000);       // 刷新过期时间
 ```
-**参数说明**：
-- `arr` (Array)：扁平数组（默认id/parentId字段）
-- 返回值：Array，树形结构数组
 
-### 2. treeById
-**功能**：根据ID查找树形结构中的节点  
-**调用方式**：
-```javascript
-import { treeById } from 'chanjs/helper/index.js';
+### store - 统一存储适配层
 
-// 示例：查找ID为2的节点
-const cateTree = [/* 树形结构数组 */];
-const node = treeById(cateTree, 2);
-console.log(node); // { id: 2, name: '手机', parentId: 1 }
-```
-**参数说明**：
-- `tree` (Array)：树形结构数组
-- `id` (Number/String)：节点ID
-- 返回值：Object/null，找到的节点（无则返回null）
-
-## 十二、字段过滤（filter.js）
-### 1. filterFields
-**功能**：过滤对象中的字段（保留/排除指定字段）  
-**调用方式**：
 ```javascript
-import { filterFields } from 'chanjs/helper/index.js';
+import { store } from 'chanjs';
 
-// 示例1：保留指定字段
-const user = { id: 1, name: '张三', password: '123456', age: 20 };
-const userSafe = filterFields(user, ['id', 'name', 'age'], 'keep');
-console.log(userSafe); // { id: 1, name: '张三', age: 20 }
+// 初始化（框架自动调用）
+await store.init({ REDIS_ENABLED: false, REDIS: {} });
 
-// 示例2：排除指定字段
-const userNoPwd = filterFields(user, ['password'], 'exclude');
-console.log(userNoPwd); // { id: 1, name: '张三', age: 20 }
-```
-**参数说明**：
-- `obj` (Object)：源对象
-- `fields` (Array)：字段名数组
-- `mode` (String)：过滤模式，`keep`（保留）/`exclude`（排除），默认'keep'
-- 返回值：Object，过滤后的新对象
-
-## 十三、响应格式化（response.js）
-### 1. success
-**功能**：生成成功响应格式  
-**调用方式**：
-```javascript
-import { success } from 'chanjs/helper/index.js';
+// 统一 API（自动切换内存/Redis）
+await store.get('key');
+await store.set('key', value, 60000);
+await store.del('key');
+await store.incr('key');
+await store.incrAndExpire('key', 60000);
+await store.exists('key');
+await store.expire('key', 30000);
 
-// 示例：返回成功响应
-const resData = success({ data: { list: [1,2,3] }, msg: '操作成功' });
-console.log(resData); 
-// 输出：{ code: 200, msg: '操作成功', data: { list: [1,2,3] } }
+// 诊断信息
+store.getInfo();
+// { mode: 'memory' | 'redis', memorySize, redisConnected, circuitOpen }
+
+// 释放资源
+await store.close();
 ```
-**参数说明**：
-- `options` (Object)：
-  - `data` (Any)：响应数据，默认{}
-  - `msg` (String)：提示信息，默认'操作成功'
-  - `code` (Number)：状态码，默认200
-- 返回值：Object，成功响应对象
-
-### 2. fail
-**功能**：生成失败响应格式  
-**调用方式**：
+
+## 工具模块
+
+### helper 聚合对象
+
 ```javascript
-import { fail } from 'chanjs/helper/index.js';
+import { helper } from 'chanjs';
 
-// 示例：返回失败响应
-const resData = fail({ msg: '参数错误', code: 400 });
-console.log(resData); 
-// 输出：{ code: 400, msg: '参数错误', data: {} }
+const {
+  formatDateFields,
+  delImg, readFileContent, saveFileContent, getFolders, getHtmlFilesSync,
+  htmlEncode, htmlDecode, escapeScript, filterImgFromStr,
+  getIp,
+  request,
+  arrToObj, getChildrenId,
+  tree, treeById,
+  filterFields,
+  pages,
+  cache, store,
+  setToken, getToken,
+  aesEncrypt, aesDecrypt,
+  success, fail,
+  createRateLimitMiddleware,
+  filterXSS, checkKeywords
+} = helper;
 ```
-**参数说明**：
-- `options` (Object)：
-  - `msg` (String)：错误提示，默认'操作失败'
-  - `data` (Any)：附加数据，默认{}
-  - `code` (Number)：错误码，默认201
-- 返回值：Object，失败响应对象
-
-### 3. error
-**功能**：生成服务器错误响应格式  
-**调用方式**：
+
+### loader 命名空间
+
 ```javascript
-import { error } from 'chanjs/helper/index.js';
+import { loader } from 'chanjs';
 
-// 示例：返回服务器错误响应
-const resData = error({ msg: '数据库查询失败' });
-console.log(resData); 
-// 输出：{ code: 500, msg: '数据库查询失败', data: {} }
+// 加载模块路由
+await loader.loadModuleRouter(chan);
+
+// 加载公共路由
+await loader.loadCommonRouter(chan);
 ```
-**参数说明**：
-- `options` (Object)：
-  - `msg` (String)：错误提示，默认'服务器内部错误'
-  - `data` (Any)：附加数据，默认{}
-- 返回值：Object，错误响应对象（默认code=500）
-
-### 4. parseDatabaseError
-**功能**：解析数据库错误信息（格式化报错）  
-**调用方式**：
+
+### utils 命名空间
+
 ```javascript
-import { parseDatabaseError } from 'chanjs/helper/index.js';
-
-// 示例：解析数据库异常
-try {
-  // 数据库操作...
-} catch (err) {
-  const errInfo = parseDatabaseError(err);
-  console.log(errInfo); // { msg: '主键冲突', code: 'ER_DUP_ENTRY' }
-}
+import { utils } from 'chanjs';
+// 包含 helper 中的所有工具函数
 ```
-**参数说明**：
-- `err` (Error)：数据库抛出的异常对象
-- 返回值：Object，解析后的错误信息（msg/code）
 
-### 5. notFoundResponse
-**功能**：生成404响应格式  
-**调用方式**：
-```javascript
-import { notFoundResponse } from 'chanjs/helper/index.js';
+## 日志
 
-// 示例：返回404响应
-const resData = notFoundResponse({ msg: '资源不存在' });
-console.log(resData); 
-// 输出：{ code: 404, msg: '资源不存在', data: {} }
-```
-**参数说明**：
-- `options` (Object)：
-  - `msg` (String)：提示信息，默认'请求资源不存在'
-- 返回值：Object，404响应对象
-
-### 6. errorResponse
-**功能**：通用错误响应生成（自定义码和信息）  
-**调用方式**：
 ```javascript
-import { errorResponse } from 'chanjs/helper/index.js';
+import { logger, createLogger } from 'chanjs';
 
-// 示例：生成自定义错误响应
-const resData = errorResponse(403, '无访问权限', { userId: 1 });
-console.log(resData); 
-// 输出：{ code: 403, msg: '无访问权限', data: { userId: 1 } }
-```
-**参数说明**：
-- `code` (Number)：错误码
-- `msg` (String)：错误提示
-- `data` (Any)：附加数据，默认{}
-- 返回值：Object，自定义错误响应对象
-
-## 十四、内容检查（checker.js）
-### 1. checkKeywords
-**功能**：检查文本中是否包含敏感关键词  
-**调用方式**：
-```javascript
-import { checkKeywords } from 'chanjs/helper/index.js';
+logger.info('信息日志');
+logger.warn('警告日志');
+logger.error('错误日志');
 
-// 示例：检查内容是否含敏感词
-const content = '这是一条包含敏感词的内容';
-const { isIllegal, keywords } = checkKeywords(content);
-console.log(isIllegal); // true（包含敏感词）/false
-console.log(keywords); // ['敏感词']（检测到的敏感词）
+// 创建自定义 logger
+const customLogger = createLogger('MyModule');
+customLogger.info('自定义模块日志');
 ```
-**参数说明**：
-- `text` (String)：待检查的文本
-- 返回值：Object，{ isIllegal: Boolean, keywords: Array }
 
-### 2. isIgnored
-**功能**：检查内容是否属于忽略项（如白名单/过滤规则）  
-**调用方式**：
-```javascript
-import { isIgnored } from 'chanjs/helper/index.js';
+## 全局资源访问
 
-// 示例：检查用户ID是否在忽略列表
-const userId = 1;
-const isIgnore = isIgnored(userId, 'user_ignore_list'); // 指定忽略规则名称
-console.log(isIgnore); // true（忽略）/false（不忽略）
-```
-**参数说明**：
-- `value` (Any)：待检查的值
-- `rule` (String)：忽略规则名称（内部配置的规则标识）
-- 返回值：Boolean，是否忽略
-
-## 十五、XSS过滤（xss-filter.js）
-### 1. filterXSS
-**功能**：过滤文本中的XSS攻击脚本  
-**调用方式**：
-```javascript
-import { filterXSS } from 'chanjs/helper/index.js';
+Controller、Service、Repository 继承自 Container，可访问：
 
-// 示例：过滤XSS脚本
-const unsafeText = '<script>alert("xss")</script> <div>正常内容</div>';
-const safeText = filterXSS(unsafeText);
-console.log(safeText); // &lt;script&gt;alert("xss")&lt;/script&gt; <div>正常内容</div>
-```
-**参数说明**：
-- `text` (String)：待过滤的文本
-- 返回值：String，过滤后的安全文本
-
-## 十六、限流中间件（rate-limit.js）
-### 1. createRateLimitMiddleware
-**功能**：创建接口限流中间件（防止高频请求）  
-**调用方式**：
-```javascript
-import { createRateLimitMiddleware } from 'chanjs/helper/index.js';
-import express from 'express';
-const app = express();
+| 属性 | 说明 |
+|------|------|
+| `this.app` | 全局应用实例 |
+| `this.config` | 全局配置对象 |
+| `this.db` | 默认数据库连接 |
+| `this.paths` | 路径工具对象 |
+| `this.get(moduleName, fileName)` | 动态加载组件 |
 
-// 示例：创建限流中间件（每分钟最多100次请求）
-const rateLimit = createRateLimitMiddleware({
-  windowMs: 60 * 1000, // 时间窗口（毫秒）
-  max: 100, // 窗口内最大请求数
-  message: { code: 429, msg: '请求过于频繁，请稍后再试' }
-});
+## 错误码规范
 
-// 应用到所有接口
-app.use(rateLimit);
+| 范围 | 说明 |
+|------|------|
+| 0 | 成功 |
+| 1xxx | 通用业务错误 |
+| 5xxx | 系统错误 |
+| 6xxx | 数据库错误 |
+
+详见 [Common.md](./Common.md) 中的完整错误码列表。
+
+## 目录结构
 
-// 或应用到单个接口
-app.get('/api/user', rateLimit, (req, res) => {
-  res.send('用户信息');
-});
 ```
-**参数说明**：
-- `options` (Object)：限流配置
-  - `windowMs` (Number)：时间窗口（毫秒），默认60000
-  - `max` (Number)：窗口内最大请求数，默认100
-  - `message` (Object)：限流提示响应，默认{ code: 429, msg: '请求频繁' }
-  - `keyGenerator` (Function)：生成限流标识的函数（默认取IP）
-- 返回值：Function，中间件函数（适配Express/Koa）
-
-## 注意事项
-1. 所有工具函数的默认配置（如密钥、超时时间等）可在对应子文件（如jwt.js、sign.js）中调整；
-2. 涉及加密/签名的函数，建议使用项目自定义密钥，避免使用默认值；
-3. 中间件类函数（如createRateLimitMiddleware）需适配对应Web框架（Express/Koa）；
-4. 文件操作函数需注意路径权限，避免因权限问题导致读写失败；
-5. 所有异步函数（如request）返回Promise，需使用async/await或.then()处理。
+app/
+├── modules/
+│   ├── {moduleName}/
+│   │   ├── controller/    # 控制器
+│   │   ├── service/       # 服务层
+│   │   ├── repository/    # 数据访问层
+│   │   └── router.js      # 模块路由
+├── config/
+│   └── index.js           # 全局配置
+└── common/
+    └── router.js          # 公共路由
+```
+
+## 相关文档
+
+- [QuickStart](./QuickStart.md) - 快速入门
+- [Controller](./Controller.md) - 控制器基类
+- [Service](./Service.md) - 服务基类
+- [Repository](./Repository.md) - 数据访问层
+- [Cache](./Cache.md) - 缓存工具
+- [Common](./Common.md) - 公共工具模块