chanjs 2.7.8 → 2.7.11

package/doc/Controller.md

@@ -1,223 +0,0 @@
-# Controller 控制器基类
-
-## 概述
-
-`Controller` 是所有业务控制器的基类，继承自 `Container` 容器类，提供统一的响应格式封装（成功/失败响应），规范控制器层的返回数据结构。
-
-## 继承关系
-
-```
-Container <── Controller
-```
-
-## 构造函数
-
-```javascript
-constructor()
-```
-
-调用父类 `Container` 构造函数，指定组件类型为 `'controller'`。
-
-## 核心方法
-
-### 1. success - 成功响应
-
-封装标准化的成功响应格式。
-
-**语法**
-
-```javascript
-success({ data, msg = "操作成功" } = {})
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| data | any | 否 | {} | 响应数据 |
-| msg | string | 否 | "操作成功" | 提示信息 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: "操作成功",
-  data: { /* 响应数据 */ }
-}
-```
-
-**示例**
-
-```javascript
-class UserController extends Controller {
-  async getUser(req, res) {
-    const user = { id: 1, name: "张三" };
-    return this.success({ data: user });
-  }
-  
-  async createUser(req, res) {
-    // 业务逻辑...
-    return this.success({ 
-      data: { id: 100 }, 
-      msg: "创建成功" 
-    });
-  }
-}
-```
-
-### 2. fail - 失败响应
-
-封装标准化的失败响应格式。
-
-**语法**
-
-```javascript
-fail(opts = {})
-```
-
-**参数**
-
-支持两种传参方式：
-
-1. **字符串简写**：直接传入错误提示文案
-2. **对象配置**：传入完整配置对象
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| opts | string \| object | 否 | {} | 错误配置 |
-| opts.msg | string | 否 | "操作失败" | 错误提示 |
-| opts.code | number | 否 | 1008 | 错误码 |
-| opts.data | any | 否 | {} | 附加数据 |
-
-**返回值**
-
-```javascript
-{
-  success: false,
-  code: 1008,  // 或其他错误码
-  msg: "操作失败",
-  data: {}
-}
-```
-
-**示例**
-
-```javascript
-class UserController extends Controller {
-  async deleteUser(req, res) {
-    const { id } = req.params;
-    
-    if (!id) {
-      // 字符串简写
-      return this.fail("用户ID不能为空");
-    }
-    
-    if (id === 1) {
-      // 对象配置，自定义错误码
-      return this.fail({ 
-        msg: "该用户不可删除", 
-        code: 1001,
-        data: { userId: id }
-      });
-    }
-    
-    // 业务逻辑...
-    return this.success({ msg: "删除成功" });
-  }
-}
-```
-
-## 完整示例
-
-```javascript
-import { Controller } from 'chanjs';
-
-export default class UserController extends Controller {
-  constructor() {
-    super();
-  }
-
-  // 查询用户列表
-  async list(req, res) {
-    const users = [
-      { id: 1, name: "张三" },
-      { id: 2, name: "李四" }
-    ];
-    return this.success({ data: users });
-  }
-
-  // 查询单个用户
-  async detail(req, res) {
-    const { id } = req.params;
-    const user = { id, name: "张三", age: 25 };
-    return this.success({ data: user });
-  }
-
-  // 创建用户
-  async create(req, res) {
-    const { name, email } = req.body;
-    
-    if (!name || !email) {
-      return this.fail({ 
-        msg: "姓名和邮箱不能为空", 
-        code: 1001 
-      });
-    }
-    
-    // 业务逻辑...
-    const newUser = { id: 100, name, email };
-    return this.success({ 
-      data: newUser, 
-      msg: "创建成功" 
-    });
-  }
-
-  // 更新用户
-  async update(req, res) {
-    const { id } = req.params;
-    const data = req.body;
-    
-    // 业务逻辑...
-    return this.success({ msg: "更新成功" });
-  }
-
-  // 删除用户
-  async delete(req, res) {
-    const { id } = req.params;
-    
-    if (!id) {
-      return this.fail("用户ID不能为空");
-    }
-    
-    // 业务逻辑...
-    return this.success({ msg: "删除成功" });
-  }
-}
-```
-
-## 错误码规范
-
-| 错误码范围 | 说明 |
-|-----------|------|
-| 0 | 成功 |
-| 1xxx | 业务错误 |
-| 5xxx | 系统错误 |
-| 6xxx | 数据库错误 |
-
-常用错误码：
-- `0` - 成功
-- `1008` - 默认业务失败
-- `400` - 参数错误
-- `401` - 未授权
-- `403` - 权限不足
-- `404` - 资源不存在
-- `500` - 系统内部错误
-
-## 注意事项
-
-1. 所有自定义控制器必须继承 `Controller` 基类
-2. `success` 方法默认 code 为 `0`，`fail` 方法默认 code 为 `1008`
-3. 响应结构统一为 `{ success, code, msg, data }`
-4. 错误码建议与前端约定统一规范

package/doc/Help.md

@@ -1,390 +0,0 @@
-# ChanJS 框架 API 参考
-
-## 概述
-
-ChanJS 是基于 Express 5 的轻量级 Node.js MVC 框架，采用纯 JavaScript（ESM）编写。本文档汇总框架所有对外暴露的 API。
-
-## 包入口
-
-```javascript
-import Chan from 'chanjs';  // 默认导出：应用主类
-
-// 命名导出
-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';
-```
-
-## 核心类
-
-### Chan - 应用主类
-
-```javascript
-const app = new Chan();
-await app.start();
-app.run(port => console.log(`监听端口 ${port}`));
-```
-
-| 方法 | 说明 |
-|------|------|
-| `start()` | 完整启动流程（配置→缓存→数据库→中间件→路由→错误处理→钩子） |
-| `run(cb)` | 启动 HTTP 监听，`cb(port)` 回调接收端口号 |
-| `beforeStart(fn)` | 注册启动前置钩子 |
-| `shutdown()` | 执行优雅停机 |
-
-### Controller - 控制器基类
-
-```javascript
-class UserController extends Controller {
-  async getUser(req, res) {
-    return this.success({ data: { id: 1 } });
-  }
-}
-```
-
-| 方法 | 说明 |
-|------|------|
-| `success({ data, msg })` | 成功响应，默认 code=0 |
-| `fail(opts)` | 失败响应，支持字符串简写或对象配置，默认 code=1008 |
-
-### Repository - 数据访问基类
-
-```javascript
-class UserRepo extends Repository {
-  constructor() {
-    super('users');  // 表名
-  }
-}
-```
-
-| 方法 | 说明 |
-|------|------|
-| `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();
-  }
-}
-```
-
-Service 是纯业务逻辑层，不包含 CRUD 方法。通过注入 Repository 实例进行数据操作。
-
-## 错误体系
-
-### 错误类
-
-| 类名 | 默认 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 | 数据库操作超时 |
-
-### 错误类使用
-
-```javascript
-// 字符串简写
-throw new NotFoundError('用户不存在');
-
-// 对象配置
-throw new ValidationError({ 
-  msg: '参数校验失败', 
-  fields: ['name', 'email'] 
-});
-
-// 带底层 cause
-throw new SystemError('系统异常', originalError);
-```
-
-### 错误工具函数
-
-| 函数 | 说明 |
-|------|------|
-| `isAppError(err)` | 判断是否为业务错误实例 |
-| `describeError(err)` | 递归解析完整可读错误信息 |
-| `errorExtraProps(err)` | 提取错误自定义附加属性 |
-| `wrapDbError(err)` | 将数据库原生错误转换为 AppError 子类 |
-| `parseStack(stack)` | 解析 V8 堆栈，提取报错文件和行号 |
-
-## 响应工具
-
-| 函数 | 说明 |
-|------|------|
-| `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
-
-```javascript
-import { setToken, getToken, verifyToken } from 'chanjs';
-
-// 签发令牌
-const token = setToken({ userId: 1 }, secretKey, '7d');
-
-// 校验令牌（详细结果）
-const result = await verifyToken(token, secretKey);
-// { valid: true, reason: 'ok', payload: {...} }
-// { valid: false, reason: 'expired' | 'invalid' | 'revoked' | 'missing' }
-
-// 校验令牌（成功返回载荷，失败返回 null）
-const payload = await getToken(token, secretKey);
-```
-
-### AES 加解密
-
-```javascript
-import { aesEncrypt, aesDecrypt } from 'chanjs';
-
-const encrypted = await aesEncrypt('敏感数据', secretKey);
-const decrypted = await aesDecrypt(encrypted, secretKey);
-```
-
-### 参数校验中间件
-
-```javascript
-import { validate, validateAll } from 'chanjs';
-import { z } from 'zod';
-
-// 单源校验
-router.post('/user', validate('body', z.object({
-  name: z.string().min(1),
-  age: z.number().int().positive()
-})), ctrl.create);
-
-// 多源校验
-router.post('/user', validateAll({
-  body: z.object({ name: z.string() }),
-  query: z.object({ page: z.coerce.number() })
-}), ctrl.create);
-```
-
-### XSS 过滤
-
-```javascript
-import { filterXSS } from 'chanjs';
-
-const safe = filterXSS('<script>alert("xss")</script>');
-// 支持字符串、对象、数组递归过滤
-```
-
-### 关键词检测
-
-```javascript
-import { checkKeywords } from 'chanjs';
-
-const result = checkKeywords('SELECT * FROM users');
-// null 或 { category: 'sqlInjection', keyword: 'SELECT' }
-```
-
-### 限流中间件
-
-```javascript
-import { createRateLimitMiddleware } from 'chanjs';
-
-const rateLimit = createRateLimitMiddleware({
-  windowMs: '1m',    // 时间窗口，支持 '1s'/'1m'/'1h'/'1d' 格式
-  max: 100,          // 窗口内最大请求数
-  ignorePaths: ['/api/public']  // 忽略路径
-});
-```
-
-## 存储层
-
-### cache - 内存缓存
-
-```javascript
-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);       // 刷新过期时间
-```
-
-### store - 统一存储适配层
-
-```javascript
-import { store } from 'chanjs';
-
-// 初始化（框架自动调用）
-await store.init({ REDIS_ENABLED: false, REDIS: {} });
-
-// 统一 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);
-
-// 诊断信息
-store.getInfo();
-// { mode: 'memory' | 'redis', memorySize, redisConnected, circuitOpen }
-
-// 释放资源
-await store.close();
-```
-
-## 工具模块
-
-### helper 聚合对象
-
-```javascript
-import { helper } from 'chanjs';
-
-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;
-```
-
-### loader 命名空间
-
-```javascript
-import { loader } from 'chanjs';
-
-// 加载模块路由
-await loader.loadModuleRouter(chan);
-
-// 加载公共路由
-await loader.loadCommonRouter(chan);
-```
-
-### utils 命名空间
-
-```javascript
-import { utils } from 'chanjs';
-// 包含 helper 中的所有工具函数
-```
-
-## 日志
-
-```javascript
-import { logger, createLogger } from 'chanjs';
-
-logger.info('信息日志');
-logger.warn('警告日志');
-logger.error('错误日志');
-
-// 创建自定义 logger
-const customLogger = createLogger('MyModule');
-customLogger.info('自定义模块日志');
-```
-
-## 全局资源访问
-
-Controller、Service、Repository 继承自 Container，可访问：
-
-| 属性 | 说明 |
-|------|------|
-| `this.app` | 全局应用实例 |
-| `this.config` | 全局配置对象 |
-| `this.db` | 默认数据库连接 |
-| `this.paths` | 路径工具对象 |
-| `this.get(moduleName, fileName)` | 动态加载组件 |
-
-## 错误码规范
-
-| 范围 | 说明 |
-|------|------|
-| 0 | 成功 |
-| 1xxx | 通用业务错误 |
-| 5xxx | 系统错误 |
-| 6xxx | 数据库错误 |
-
-详见 [Common.md](./Common.md) 中的完整错误码列表。
-
-## 目录结构
-
-```
-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) - 公共工具模块

package/doc/QuickStart.md

@@ -1,116 +0,0 @@
-# ChanJS 快速入门
-
-## 安装
-
-```bash
-npm install chanjs
-```
-
-## 最小化启动
-
-### 1. 创建入口文件 `index.js`
-
-```javascript
-import Chan from 'chanjs';
-
-const app = new Chan();
-await app.start();
-app.run(port => {
-  console.log(`服务启动在端口 ${port}`);
-});
-```
-
-### 2. 创建配置文件 `config/index.js`
-
-```javascript
-export default {
-  PORT: 3000,
-  NODE_ENV: 'dev',
-  
-  // 数据库配置（可选）
-  db: [{
-    key: 'default',
-    client: 'mysql2',
-    connection: {
-      host: '127.0.0.1',
-      user: 'root',
-      password: '',
-      database: 'test'
-    }
-  }],
-  
-  // 模块列表
-  modules: ['web', 'api']
-};
-```
-
-### 3. 创建模块目录结构
-
-```
-app/
-├── modules/
-│   ├── web/
-│   │   ├── controller/
-│   │   │   └── IndexController.js
-│   │   └── router.js
-│   └── api/
-│       ├── controller/
-│       │   └── UserController.js
-│       └── router.js
-```
-
-### 4. 创建控制器
-
-```javascript
-// app/modules/api/controller/UserController.js
-import { Controller } from 'chanjs';
-
-export default class UserController extends Controller {
-  async getUser(req, res) {
-    const { id } = req.params;
-    // 业务逻辑
-    return this.success({ data: { id, name: '张三' } });
-  }
-}
-```
-
-### 5. 创建路由
-
-```javascript
-// app/modules/api/router.js
-import { loader } from 'chanjs';
-
-export default async function(app, router, config) {
-  const userCtrl = await loader.loadController('api', 'UserController');
-  
-  router.get('/user/:id', userCtrl.getUser);
-}
-```
-
-## 访问测试
-
-```bash
-curl http://localhost:3000/api/user/1
-```
-
-响应：
-```json
-{
-  "success": true,
-  "code": 0,
-  "msg": "操作成功",
-  "data": {
-    "id": "1",
-    "name": "张三"
-  }
-}
-```
-
-## 下一步
-
-- [Controller 控制器](./Controller.md) - 学习控制器编写规范
-- [Service 服务层](./Service.md) - 业务逻辑层使用
-- [Repository 数据层](./Repository.md) - 数据库操作
-- [Cache 缓存](./Cache.md) - 缓存使用
-- [Common 公共配置](./Common.md) - 全局配置说明
-- [Help API 参考](./Help.md) - 完整 API 文档