chanjs 2.6.3 → 2.6.5

package/doc/Common.md

@@ -0,0 +1,182 @@
+# chanjs/common/index.js 模块文档
+## 概述
+`chanjs/common/index.js` 是 `chanjs` 框架的通用工具模块出口文件，聚合了 API 响应处理、分类操作、状态码、邮件、页面处理、短信、通用工具等多个子模块的核心方法/常量，提供统一的导出入口，简化模块引用流程。
+
+## 导出内容总览
+该文件通过 ES6 导出语法，批量导出以下子模块的核心成员：
+
+| 导出来源文件 | 导出成员 | 功能分类 |
+|--------------|----------|----------|
+| `./api.js` | `success`, `fail`, `error` | API 响应格式化 |
+| `./category.js` | `getChildrenId` | 分类数据处理 |
+| `./code.js` | `CODE` | 业务状态码常量 |
+| `./email.js` | `sendMail`, `genRegEmailHtml`, `genResetPasswordEmail` | 邮件发送与模板生成 |
+| `./pages.js` | `pages`, `getHtmlFilesSync` | 页面/HTML 文件处理 |
+| `./sms.js` | `createSmsClient` | 短信客户端创建 |
+| `./utils.js` | `filterBody`, `pc`, `filterImgFromStr` | 通用工具函数 |
+
+## 详细导出成员说明
+### 1. 来自 `./api.js`：API 响应格式化
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `success` | 函数 | 生成「成功」类型的 API 响应数据（如包含 `code: 200`、`data`、`msg` 等字段） |
+| `fail` | 函数 | 生成「业务失败」类型的 API 响应数据（如包含 `code: 非200`、`msg` 等字段，适用于参数错误、业务逻辑失败等场景） |
+| `error` | 函数 | 生成「系统错误」类型的 API 响应数据（如包含 `code: 500`、`msg` 等字段，适用于服务器内部异常场景） |
+
+**使用示例**：
+```javascript
+import { success, fail } from 'chanjs/common';
+
+// 接口返回成功响应
+export const getUser = (req, res) => {
+  res.json(success({ name: '张三' }, '获取用户信息成功'));
+};
+
+// 接口返回业务失败响应
+export const login = (req, res) => {
+  res.json(fail('用户名或密码错误', 401));
+};
+```
+
+### 2. 来自 `./category.js`：分类数据处理
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `getChildrenId` | 函数 | 根据分类 ID，递归获取该分类下所有子分类的 ID 集合（适用于树形结构分类场景，如商品分类、栏目分类） |
+
+**使用示例**：
+```javascript
+import { getChildrenId } from 'chanjs/common';
+
+// 假设分类数据为树形结构
+const categoryList = [
+  { id: 1, name: '数码', children: [{ id: 11, name: '手机' }, { id: 12, name: '电脑' }] },
+  { id: 2, name: '服饰' }
+];
+// 获取分类1下所有子分类ID
+const childrenIds = getChildrenId(categoryList, 1);
+console.log(childrenIds); // [11, 12]
+```
+
+### 3. 来自 `./code.js`：业务状态码常量
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `CODE` | 对象 | 聚合了项目中所有业务状态码的常量对象（如 `CODE.SUCCESS = 200`、`CODE.PARAM_ERROR = 400`、`CODE.LOGIN_EXPIRE = 401` 等），统一管理状态码，避免硬编码 |
+
+**使用示例**：
+```javascript
+import { CODE, fail } from 'chanjs/common';
+
+export const submitForm = (req, res) => {
+  if (!req.body.name) {
+    // 使用统一状态码返回失败响应
+    return res.json(fail('姓名不能为空', CODE.PARAM_ERROR));
+  }
+  // 业务逻辑处理...
+};
+```
+
+### 4. 来自 `./email.js`：邮件发送与模板生成
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `sendMail` | 函数 | 封装邮件发送逻辑，接收收件人、邮件标题、邮件内容等参数，调用底层邮件服务发送邮件 |
+| `genRegEmailHtml` | 函数 | 生成「用户注册验证」的邮件 HTML 模板（包含验证链接/验证码等动态内容） |
+| `genResetPasswordEmail` | 函数 | 生成「密码重置」的邮件 HTML 模板（包含重置链接/验证码等动态内容） |
+
+**使用示例**：
+```javascript
+import { sendMail, genRegEmailHtml } from 'chanjs/common';
+
+// 发送注册验证邮件
+const sendRegEmail = async (toEmail, verifyCode) => {
+  const html = genRegEmailHtml(verifyCode);
+  await sendMail({
+    to: toEmail,
+    subject: '【XX平台】注册验证',
+    html
+  });
+};
+```
+
+### 5. 来自 `./pages.js`：页面/HTML 文件处理
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `pages` | 对象/函数 | 页面相关配置/工具（如页面路由映射、页面模板配置等，具体需结合子模块实现） |
+| `getHtmlFilesSync` | 函数 | 同步读取指定目录下所有 HTML 文件的路径/内容，返回文件列表（适用于静态页面生成、模板扫描等场景） |
+
+**使用示例**：
+```javascript
+import { getHtmlFilesSync } from 'chanjs/common';
+
+// 获取指定目录下所有HTML文件
+const htmlFiles = getHtmlFilesSync('./src/pages');
+console.log(htmlFiles); // ['./src/pages/index.html', './src/pages/about.html']
+```
+
+### 6. 来自 `./sms.js`：短信客户端创建
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `createSmsClient` | 函数 | 创建并返回短信服务客户端实例（封装了短信服务商 SDK，如阿里云短信、腾讯云短信等），支持配置密钥、签名等参数 |
+
+**使用示例**：
+```javascript
+import { createSmsClient } from 'chanjs/common';
+
+// 创建短信客户端
+const smsClient = createSmsClient({
+  accessKeyId: 'your-access-key',
+  accessKeySecret: 'your-access-secret',
+  signName: 'XX平台'
+});
+
+// 发送短信验证码
+smsClient.sendSms({
+  phoneNumbers: '13800138000',
+  templateCode: 'SMS_123456789',
+  templateParam: { code: '668899' }
+});
+```
+
+### 7. 来自 `./utils.js`：通用工具函数
+| 成员名 | 类型 | 说明 |
+|--------|------|------|
+| `filterBody` | 函数 | 过滤请求体（req.body）中的敏感字段/空值字段，返回清洗后的对象（适用于接口入参校验，避免无效/敏感数据传入业务层） |
+| `pc` | 函数/对象 | 设备判断工具，通常用于检测请求是否来自 PC 端（如返回 `true/false`，或包含 `isPc`、`isMobile` 等方法） |
+| `filterImgFromStr` | 函数 | 从字符串（如 HTML 文本、富文本内容）中提取所有图片 URL，返回图片链接数组 |
+
+**使用示例**：
+```javascript
+import { filterBody, pc, filterImgFromStr } from 'chanjs/common';
+
+// 过滤请求体空值
+const cleanBody = filterBody(req.body, ['name', 'age']); // 仅保留name、age字段，且过滤空值
+
+// 判断是否为PC端请求
+if (pc(req.headers['user-agent'])) {
+  console.log('PC端访问');
+}
+
+// 提取富文本中的图片
+const content = '<p>测试<img src="https://example.com/1.jpg">内容<img src="https://example.com/2.jpg"></p>';
+const imgUrls = filterImgFromStr(content);
+console.log(imgUrls); // ['https://example.com/1.jpg', 'https://example.com/2.jpg']
+```
+
+## 引用方式
+### 方式1：按需导入（推荐）
+```javascript
+import { success, CODE, filterBody } from 'chanjs/common';
+```
+
+### 方式2：批量导入
+```javascript
+import * as common from 'chanjs/common';
+
+// 使用时通过 common.xxx 访问
+common.success(data, '操作成功');
+common.filterBody(req.body);
+```
+
+## 注意事项
+1. 该文件仅为「导出入口」，无实际业务逻辑，所有功能的具体实现均在对应的子模块（`api.js`/`category.js` 等）中；
+2. 若需修改/扩展功能，需修改对应的子模块文件，而非直接修改 `index.js`；
+3. 导入时确保子模块文件路径正确，避免因路径变更导致导入失败。

package/doc/Controller.md

@@ -0,0 +1,152 @@
+# Controller 控制器基类
+## 概述
+`Controller` 是所有业务控制器的基类，继承自 `Container` 容器类，核心作用是提供统一的响应格式封装（成功/失败响应），规范控制器层的返回数据结构，减少重复代码，提升开发效率。
+
+## 依赖说明
+| 依赖模块 | 路径 | 说明 |
+|----------|------|------|
+| `success`/`fail` | `../helper/response.js` | 响应格式封装工具函数，提供标准化的成功/失败响应结构 |
+| `Container` | `./Container.js` | 基础容器类，为控制器提供组件类型标识等能力 |
+
+## 类继承关系
+```
+Container <|-- Controller
+```
+
+## 构造函数
+### 语法
+```javascript
+constructor()
+```
+### 说明
+调用父类 `Container` 的构造函数，并指定组件类型为 `'controller'`，用于容器类对控制器组件的统一管理。
+
+### 示例
+```javascript
+import Controller from './chanjs/base/Controller.js';
+
+class UserController extends Controller {
+  constructor() {
+    super(); // 继承 Controller 构造逻辑
+  }
+}
+```
+
+## 核心方法
+### 1. 成功响应 - `success(options)`
+封装标准化的成功响应格式，返回统一结构的成功数据。
+
+#### 参数说明
+| 参数名 | 类型 | 必传 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `options` | `Object` | 否 | `{}` | 响应配置项 |
+| `options.data` | `any` | 否 | - | 响应体数据，可传任意类型（对象、数组、基本类型等） |
+| `options.msg` | `string` | 否 | `"操作成功"` | 响应提示消息 |
+
+#### 返回值
+`Object`：标准化的成功响应对象（结构由 `../helper/response.js` 的 `success` 函数定义）。
+
+#### 示例
+```javascript
+class UserController extends Controller {
+  async getUserInfo() {
+    const data = { id: 1, name: "张三" };
+    // 返回成功响应，使用默认提示语
+    return this.success({ data });
+    
+    // 自定义提示语
+    // return this.success({ data, msg: "获取用户信息成功" });
+  }
+}
+```
+
+### 2. 失败响应 - `fail(options)`
+封装标准化的失败响应格式，返回统一结构的失败数据。
+
+#### 参数说明
+| 参数名 | 类型 | 必传 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `options` | `Object` | 否 | `{}` | 响应配置项 |
+| `options.msg` | `string` | 否 | `"操作失败"` | 失败提示消息 |
+| `options.data` | `any` | 否 | `{}` | 失败时附带的补充数据 |
+| `options.code` | `number` | 否 | `201` | 自定义错误码，用于前端区分不同失败场景 |
+
+#### 返回值
+`Object`：标准化的失败响应对象（结构由 `../helper/response.js` 的 `fail` 函数定义）。
+
+#### 示例
+```javascript
+class UserController extends Controller {
+  async updateUserInfo() {
+    try {
+      // 业务逻辑：更新用户信息失败
+      throw new Error("用户ID不存在");
+    } catch (err) {
+      // 返回失败响应，自定义提示语和错误码
+      return this.fail({ 
+        msg: err.message, 
+        code: 400,
+        data: { userId: 1 } // 附带失败关联的用户ID
+      });
+      
+      // 使用默认配置
+      // return this.fail();
+    }
+  }
+}
+```
+
+## 完整使用示例
+```javascript
+import Controller from './chanjs/base/Controller.js';
+
+/**
+ * 用户业务控制器
+ * 继承 Controller 基类，使用统一响应格式
+ */
+class UserController extends Controller {
+  constructor() {
+    super(); // 必须调用父类构造函数
+  }
+
+  /**
+   * 获取用户列表
+   * @returns {Object} 成功响应
+   */
+  async getList() {
+    const list = [
+      { id: 1, name: "张三" },
+      { id: 2, name: "李四" }
+    ];
+    return this.success({ 
+      data: list, 
+      msg: "获取用户列表成功" 
+    });
+  }
+
+  /**
+   * 删除用户
+   * @param {number} id - 用户ID
+   * @returns {Object} 成功/失败响应
+   */
+  async delete(id) {
+    if (!id) {
+      return this.fail({ 
+        msg: "用户ID不能为空", 
+        code: 401 
+      });
+    }
+    
+    // 模拟删除成功
+    return this.success({ msg: `删除ID为${id}的用户成功` });
+  }
+}
+
+export default UserController;
+```
+
+## 注意事项
+1. 所有自定义控制器必须继承 `Controller` 基类，以保证响应格式的统一性；
+2. `success`/`fail` 方法的参数为可选配置对象，未传参时会使用默认值；
+3. 响应的最终数据结构由 `../helper/response.js` 中的 `success`/`fail` 函数决定，若需调整全局响应格式，建议修改该工具文件；
+4. 错误码 `code` 可根据业务场景自定义扩展（如 400 代表参数错误、404 代表资源不存在等），建议与前端约定统一的错误码规范。

package/doc/Email.md

@@ -0,0 +1,114 @@
+# 邮件发送工具模块文档
+## 1. 模块概述
+该模块基于 `nodemailer` 实现邮件发送功能，并提供注册验证码、重置密码验证码两类邮件的HTML模板生成能力，适用于系统中的邮件通知场景（如用户注册、密码重置）。
+
+## 2. 依赖
+- 第三方库：`nodemailer`（需提前安装）
+- 全局配置：`Chan.config` 需包含 `EMAIL`（邮件服务配置）和 `APP_NAME`（应用名称）字段
+
+## 3. 配置说明
+`Chan.config.EMAIL` 需包含以下配置项：
+
+| 配置项 | 类型 | 说明 |
+|--------|------|------|
+| HOST | string | 邮件服务器主机地址（如 smtp.qq.com） |
+| PORT | string/number | 邮件服务器端口（如 465、587） |
+| SECURE | string | 是否启用SSL加密（"true" 或 "false"） |
+| USER | string | 发件人邮箱账号 |
+| PASS | string | 发件人邮箱授权码/密码 |
+| FROM | string | 发件人显示格式（如 "应用名称 <xxx@xxx.com>"） |
+
+## 4. API 详情
+### 4.1 sendMail - 发送邮件
+#### 功能描述
+创建邮件传输器，验证邮件服务配置后发送邮件，支持纯文本和HTML格式内容。
+
+#### 函数签名
+```javascript
+async function sendMail(to, subject, text, html = null) => Promise<Object>
+```
+
+#### 参数说明
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| to | string | 是 | - | 收件人邮箱地址 |
+| subject | string | 是 | - | 邮件主题 |
+| text | string | 是 | - | 邮件纯文本内容 |
+| html | string \| null | 否 | null | 邮件HTML内容，未传则使用text内容替代 |
+
+#### 返回值
+`Promise<Object>`：nodemailer 发送邮件后的响应对象（包含 messageId 等信息）。
+
+#### 异常抛出
+- 邮件服务配置验证失败：抛出 `Error("邮件服务未配置")`
+- 邮件发送失败：打印错误日志并抛出原错误对象
+
+#### 使用示例
+```javascript
+import { sendMail, genRegEmailHtml } from './chanjs/common/email.js';
+
+// 发送注册验证码邮件
+async function sendRegCodeEmail(email, code) {
+  const subject = `${Chan.config.APP_NAME} 注册验证码`;
+  const text = `您的注册验证码是：${code}，有效期10分钟。`;
+  const html = genRegEmailHtml(code);
+  
+  try {
+    const result = await sendMail(email, subject, text, html);
+    console.log("邮件发送成功：", result.messageId);
+  } catch (error) {
+    console.error("发送失败：", error);
+  }
+}
+```
+
+### 4.2 genRegEmailHtml - 生成注册验证码邮件HTML模板
+#### 功能描述
+生成美观的注册验证码邮件HTML字符串，包含应用名称、验证码、有效期等信息。
+
+#### 函数签名
+```javascript
+function genRegEmailHtml(code, minutes = 10) => string
+```
+
+#### 参数说明
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| code | string | 是 | - | 注册验证码 |
+| minutes | number | 否 | 10 | 验证码有效期（分钟） |
+
+#### 返回值
+`string`：完整的邮件HTML字符串。
+
+### 4.3 genResetPasswordEmail - 生成重置密码邮件HTML模板
+#### 功能描述
+生成重置密码验证码的邮件HTML字符串，样式与注册邮件区分，突出重置密码场景。
+
+#### 函数签名
+```javascript
+function genResetPasswordEmail(code, minutes = 10) => string
+```
+
+#### 参数说明
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| code | string | 是 | - | 重置密码验证码 |
+| minutes | number | 否 | 10 | 验证码有效期（分钟） |
+
+#### 返回值
+`string`：完整的邮件HTML字符串。
+
+## 5. 模板样式说明
+- 注册邮件模板：头部背景色为蓝色（#007bff），最大宽度750px，整体风格简洁清晰。
+- 重置密码邮件模板：头部背景色为绿色（#28a745），最大宽度600px，布局与注册邮件一致，文案适配重置密码场景。
+- 两类模板均包含：应用名称、验证码醒目展示、有效期提示、版权信息，适配主流邮箱的HTML渲染规则。
+
+## 6. 异常处理建议
+1. 调用 `sendMail` 时务必使用 `try/catch` 捕获异常，避免程序崩溃；
+2. 邮件服务配置错误（如HOST/PORT错误）会触发“邮件服务未配置”异常，需检查 `Chan.config.EMAIL` 配置；
+3. 发送失败（如收件人邮箱格式错误、服务器拒绝）需记录详细错误日志，便于排查问题。
+
+## 7. 扩展建议
+1. 可新增更多邮件模板（如通知类、营销类），参考现有模板结构封装；
+2. 可添加邮件发送重试机制，提升稳定性；
+3. 可将模板样式抽离为配置项，支持自定义主题色、模板宽度等。

package/doc/Event.md

@@ -0,0 +1,232 @@
+# chanjs Event 类使用文档
+## 概述
+`chanjs` 中的 `Event` 类基于 Node.js 内置 `EventEmitter` 封装，提供轻量级的事件订阅/发布能力，支持事件注册、触发、注销等核心操作，接口简洁且保持与原生 `EventEmitter` 兼容，适用于业务中解耦组件间的通信场景。
+
+## 前置准备
+### 1. 引入方式
+```javascript
+import { Event } from "chanjs";
+
+// 方式1：创建实例使用
+const event = new Event();
+
+// 方式2：直接使用内置单例（推荐全局通信）
+import { event } from "chanjs";
+```
+
+### 2. 通用约定
+- 事件名（`eventName`）建议使用**语义化字符串**（如 `user:login`、`order:created`），避免命名冲突
+- 监听器函数（`listener`）接收的参数为触发事件时传入的 `data`，支持任意类型数据
+- 所有方法均返回当前 `Event` 实例，支持**链式调用**
+
+## 核心方法使用指南
+### 1. 注册事件监听器 - on
+#### 作用
+为指定事件注册一个持久化的监听器（事件触发时会执行该函数），支持为同一事件注册多个监听器。
+#### 传参格式
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| eventName | String | 是 | 事件名称（如 `user:login`） |
+| listener | Function | 是 | 事件触发时执行的回调函数，参数为触发事件传入的 `data` |
+#### 使用示例
+```javascript
+// 注册单个事件监听器
+event.on("user:login", (data) => {
+  console.log("用户登录事件触发：", data);
+  // 业务逻辑：记录登录日志、更新最后登录时间等
+});
+
+// 为同一事件注册多个监听器
+event.on("order:created", (orderData) => {
+  console.log("订单创建-日志记录：", orderData.id);
+});
+event.on("order:created", (orderData) => {
+  console.log("订单创建-消息推送：", orderData.userId);
+});
+
+// 链式调用注册多个事件
+event
+  .on("article:add", (article) => console.log("新增文章：", article.title))
+  .on("article:delete", (id) => console.log("删除文章ID：", id));
+```
+
+### 2. 触发事件 - emit
+#### 作用
+触发指定名称的事件，执行该事件下所有已注册的监听器，并传递数据给监听器函数。
+#### 传参格式
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| eventName | String | 是 | 要触发的事件名称 |
+| data | Any | 否 | 传递给监听器的事件数据（任意类型：对象、数组、基本类型等） |
+#### 使用示例
+```javascript
+// 触发用户登录事件，传递用户数据
+event.emit("user:login", {
+  userId: 1001,
+  username: "test_user",
+  loginTime: new Date(),
+  ip: "127.0.0.1"
+});
+
+// 触发订单创建事件，传递订单数据
+const orderData = {
+  id: "ORD20260323001",
+  userId: 1001,
+  amount: 99.9,
+  createTime: new Date()
+};
+event.emit("order:created", orderData);
+
+// 触发无数据的事件
+event.emit("system:refresh");
+```
+
+### 3. 注销事件监听器 - off
+#### 作用
+注销指定事件下的某个具体监听器，仅移除该监听器，不影响同一事件的其他监听器。
+#### 传参格式
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| eventName | String | 是 | 事件名称 |
+| listener | Function | 是 | 要注销的监听器函数（需与注册时的函数引用一致） |
+#### 使用示例
+```javascript
+// 定义可复用的监听器函数
+const loginListener = (data) => {
+  console.log("用户登录监听器：", data);
+};
+
+// 注册监听器
+event.on("user:login", loginListener);
+
+// 触发事件（监听器会执行）
+event.emit("user:login", { userId: 1001 });
+
+// 注销指定监听器
+event.off("user:login", loginListener);
+
+// 再次触发事件（该监听器不再执行）
+event.emit("user:login", { userId: 1001 });
+
+// 链式注销多个监听器
+const articleAddListener = (data) => console.log("新增文章：", data);
+const articleDelListener = (id) => console.log("删除文章：", id);
+
+event
+  .on("article:add", articleAddListener)
+  .on("article:delete", articleDelListener)
+  .off("article:add", articleAddListener)
+  .off("article:delete", articleDelListener);
+```
+
+### 4. 注销所有事件监听器 - removeAllListeners
+#### 作用
+注销指定事件下的**所有**监听器，或注销所有事件的所有监听器（不传参数时）。
+#### 传参格式
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| eventName | String | 否 | 事件名称（不传则注销所有事件的监听器） |
+#### 使用示例
+```javascript
+// 注册多个监听器
+event
+  .on("order:created", (data) => console.log("监听器1：", data))
+  .on("order:created", (data) => console.log("监听器2：", data))
+  .on("user:login", (data) => console.log("登录监听器：", data));
+
+// 注销order:created事件的所有监听器
+event.removeAllListeners("order:created");
+// 触发该事件（无监听器执行）
+event.emit("order:created", { id: "ORD001" });
+
+// 注销所有事件的所有监听器（全局清空）
+event.removeAllListeners();
+// 触发任何事件都无监听器执行
+event.emit("user:login", { userId: 1001 });
+```
+
+## 高级使用场景
+### 场景1：一次性事件监听（扩展）
+原生 `EventEmitter` 支持 `once` 方法（注册仅执行一次的监听器），`Event` 类继承该能力，可直接使用：
+```javascript
+// 注册仅执行一次的监听器
+event.once("config:update", (config) => {
+  console.log("配置更新（仅执行一次）：", config);
+});
+
+// 第一次触发（监听器执行）
+event.emit("config:update", { theme: "dark" });
+// 第二次触发（监听器已自动注销，不执行）
+event.emit("config:update", { theme: "light" });
+```
+
+### 场景2：业务模块解耦示例
+```javascript
+// 模块A：用户模块
+import { event } from "chanjs";
+
+class UserModule {
+  async login(username, password) {
+    // 登录逻辑
+    const user = { id: 1001, username };
+    // 触发登录事件，无需关心其他模块逻辑
+    event.emit("user:login", user);
+    return user;
+  }
+}
+
+// 模块B：日志模块
+import { event } from "chanjs";
+
+class LogModule {
+  constructor() {
+    // 监听登录事件，记录日志
+    event.on("user:login", (user) => {
+      console.log(`[LOG] 用户${user.username}(${user.id})于${new Date()}登录`);
+    });
+  }
+}
+
+// 模块C：消息模块
+import { event } from "chanjs";
+
+class MessageModule {
+  constructor() {
+    // 监听登录事件，推送消息
+    event.on("user:login", (user) => {
+      console.log(`[MSG] 向用户${user.id}推送登录成功消息`);
+    });
+  }
+}
+
+// 业务入口
+const userModule = new UserModule();
+const logModule = new LogModule();
+const messageModule = new MessageModule();
+
+// 执行登录，自动触发日志和消息模块的逻辑
+await userModule.login("test_user", "123456");
+```
+
+### 场景3：错误事件处理
+```javascript
+// 注册全局错误事件监听器
+event.on("error", (err) => {
+  console.error("全局事件错误：", err);
+  // 业务逻辑：错误上报、告警等
+});
+
+// 触发错误事件（建议使用Error对象传递错误信息）
+event.emit("error", new Error("订单创建失败：库存不足"));
+```
+
+## 注意事项
+1. 注销监听器时，`off` 方法传入的 `listener` 必须与 `on` 注册时的函数**引用一致**，匿名函数无法被注销；
+2. 事件名建议使用 `模块:动作` 的命名规范（如 `user:login`、`order:created`），避免全局命名冲突；
+3. 若监听器函数执行过程中抛出异常，不会阻断其他监听器执行，但需自行捕获异常避免程序崩溃；
+4. 单例 `event` 适用于全局通信，若需隔离事件作用域，可创建多个 `Event` 实例（`new Event()`）。
+
+## 总结
+1. `Event` 类核心提供 `on`（注册）、`emit`（触发）、`off`（注销）、`removeAllListeners`（清空）四个方法，覆盖事件通信全流程；
+2. 基于 Node.js `EventEmitter` 实现，兼容原生方法（如 `once`），接口简洁易上手；
+3. 适用于业务模块解耦场景，通过事件发布/订阅模式减少模块间直接依赖，提升代码可维护性。