chanjs 2.7.4 → 2.7.6

package/doc/Service.md

@@ -1,566 +1,240 @@
-# Service 数据库服务基类文档
-## 一、模块概述
-`Service` 类是基于 `Container` 扩展的数据库服务基类，封装了常用的数据库操作方法，包括增删改查、分页查询、事务处理、软删除、关联查询等核心能力。该类自动处理日期字段格式化、数据库连接校验，并提供统一的返回格式，简化业务层数据库操作逻辑。
-
-## 二、依赖说明
-- 继承自 `Container` 基类（`./Container.js`）
-- 引入日期字段格式化工具 `formatDateFields`（`../helper/time.js`）
-- 依赖全局对象 `Chan`：
-  - `Chan.db`/`Chan.dbManager`：数据库连接实例/连接管理器
-  - `Chan.config`：系统配置（包含分页、限制条数等配置项）
-
-## 三、类构造与初始化
-### 3.1 构造函数
-#### 函数签名
-```javascript
-constructor(tableName = null, dbName = null)
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| tableName | string | 否 | null | 数据库表名，子类实例化时指定 |
-| dbName | string | 否 | null | 数据库连接名称，不传则使用默认数据库连接 |
-
-#### 初始化逻辑
-1. 调用父类 `Container` 构造函数，指定组件类型为 `service`；
-2. 根据 `dbName` 获取对应数据库连接（优先），否则使用默认连接 `Chan.db`；
-3. 初始化日期字段列表 `_dateFields`，用于自动格式化日期字符串；
-4. 若子类定义 `on` 方法，自动执行以注册事件监听器。
-
-### 3.2 内置属性
-| 属性名 | 类型 | 说明 |
-|--------|------|------|
-| _dateFields | Array<string> | 需自动格式化的日期字段列表（包含下划线/驼峰命名的常见日期字段） |
-| pageSize（getter） | number | 每页默认记录数，优先读取 `Chan.config.PAGE_SIZE`，默认20 |
-| limit（getter） | number | 查询最大限制条数，优先读取 `Chan.config.LIMIT_MAX`，默认300 |
-
-## 四、私有方法
-### 4.1 _checkDB
-#### 功能描述
-校验数据库连接是否可用，不可用时抛出异常。
-#### 函数签名
-```javascript
-_checkDB()
-```
-#### 异常抛出
-- 类型：`Error`
-- 消息：`Database connection not available`
-
-### 4.2 _formatDateFields
-#### 功能描述
-自动将日期字符串转换为数据库可识别的 `Date` 类型，仅处理 `_dateFields` 中的字段。
-#### 函数签名
-```javascript
-_formatDateFields(data) => Object
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| data | Object | 是 | 待格式化的数据对象 |
+# Service 服务基类
 
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| Object | 格式化后的数据对象（原对象深拷贝，避免修改源数据） |
+## 概述
 
-#### 处理逻辑
-1. 非对象类型直接返回；
-2. 遍历 `_dateFields` 中的字段，若字段值为有效日期字符串，转换为 `Date` 对象；
-3. 转换失败时打印错误日志，不中断流程。
+`Service` 是纯业务逻辑层基类，继承自 `Container` 容器类。**不包含任何数据库 CRUD 方法**，仅作为业务逻辑的载体。
 
-### 4.3 _buildBaseQuery
-#### 功能描述
-构建基础查询器（Knex 查询构建器），整合查询条件、排序、字段筛选。
-#### 函数签名
-```javascript
-_buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) => Object
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 查询条件（Knex `where` 格式） |
-| sort | Object | 否 | {} | 排序条件（键：字段名，值：asc/desc） |
-| fields | Array<string> | 否 | [] | 查询字段列表（为空则查询所有字段） |
-
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| Object | Knex 查询构建器实例 |
-
-#### 处理逻辑
-1. 先调用 `_checkDB` 校验连接；
-2. 初始化查询器，指定操作表名；
-3. 依次添加 `where` 条件、字段筛选、排序规则（排序方向自动兼容大小写，默认升序）。
-
-## 五、核心操作方法
-### 5.1 all - 查询所有记录
-#### 功能描述
-查询符合条件的所有记录，自动格式化日期字段。
-#### 函数签名
-```javascript
-async all({ query = {}, sort = {}, fields = [] } = {}) => Promise<Array>
-```
-#### 参数说明
-同 `_buildBaseQuery` 方法参数。
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| Promise<Array> | 查询结果数组，日期字段已格式化 |
+业务子类可注入多个 `Repository` 实例，进行跨表事务编排。
+
+## 继承关系
 
-### 5.2 find - 分页查询（偏移量模式）
-#### 功能描述
-基于偏移量和限制条数的分页查询，返回结构化结果。
-#### 函数签名
-```javascript
-async find({ query = {}, sort = {}, fields = [], limit, offset } = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 查询条件 |
-| sort | Object | 否 | {} | 排序条件 |
-| fields | Array<string> | 否 | [] | 查询字段 |
-| limit | number | 否 | - | 限制返回条数 |
-| offset | number | 否 | - | 偏移量（从0开始） |
-
-#### 返回值
-| 类型 | 结构 | 说明 |
-|------|------|------|
-| Promise<Object> | `{ success: true, code: 200, msg: '查询成功', data: Array }` | data 为查询结果数组，日期字段已格式化 |
-
-### 5.3 findOne - 查询单条记录
-#### 功能描述
-根据条件查询单条记录，无结果时返回明确的失败状态。
-#### 函数签名
-```javascript
-async findOne({ query = {}, fields = [] } = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 查询条件（建议唯一条件） |
-| fields | Array<string> | 否 | [] | 查询字段 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 有结果 | `{ success: true, code: 200, msg: '查询成功', data: Object }` |
-| 无结果 | `{ success: false, code: 404, msg: '记录不存在', data: null }` |
-
-### 5.4 findById - 根据ID查询单条记录
-#### 功能描述
-简化根据主键ID查询单条记录的逻辑，参数更简洁。
-#### 函数签名
-```javascript
-async findById(id, { fields = [] } = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| id | number/string | 是 | - | 记录主键ID |
-| fields | Array<string> | 否 | [] | 查询字段 |
-
-#### 返回值
-同 `findOne` 方法。
-
-### 5.5 insert - 插入单条记录
-#### 功能描述
-插入单条记录，自动格式化日期字段，返回插入结果。
-#### 函数签名
-```javascript
-async insert(data = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| data | Object | 否 | {} | 插入的数据对象 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数为空 | `{ success: false, code: 400, msg: '参数缺失', data: {} }` |
-| 插入成功 | `{ success: true, code: 200, msg: '插入成功', data: { insertId: number, affectedRows: number } }` |
-
-### 5.6 insertMany - 批量插入记录
-#### 功能描述
-批量插入多条记录，自动格式化每条记录的日期字段。
-#### 函数签名
-```javascript
-async insertMany(records = []) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| records | Array<Object> | 否 | [] | 待插入的记录数组 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数为空 | `{ success: false, code: 400, msg: '参数缺失', data: {} }` |
-| 插入成功 | `{ success: true, code: 200, msg: '批量插入成功', data: { insertIds: Array<number>, affectedRows: number } }` |
-
-### 5.7 delete - 根据条件删除记录
-#### 功能描述
-根据自定义条件删除记录，返回受影响行数。
-#### 函数签名
-```javascript
-async delete(query = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 删除条件（Knex `where` 格式） |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 条件为空 | `{ success: false, code: 400, msg: '参数缺失', data: {} }` |
-| 删除成功 | `{ success: true, code: 200, msg: '删除成功', data: { affectedRows: number } }` |
-
-### 5.8 deleteById - 根据ID删除记录
-#### 功能描述
-简化根据主键ID删除记录的逻辑。
-#### 函数签名
-```javascript
-async deleteById(id) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| id | number/string | 是 | 记录主键ID |
-
-#### 返回值
-同 `delete` 方法。
-
-### 5.9 updateByQuery - 根据条件更新记录
-#### 功能描述
-根据自定义条件更新记录，自动格式化日期字段，返回受影响行数。
-#### 函数签名
-```javascript
-async updateByQuery({ query, data } = {}) => Promise<Object>
 ```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| query | Object | 是 | 更新条件（Knex `where` 格式） |
-| data | Object | 是 | 更新的数据对象 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数无效（条件/数据为空） | `{ success: false, code: 400, msg: '参数无效', data: {} }` |
-| 更新成功 | `{ success: true, code: 200, msg: '更新成功', data: { affectedRows: number } }` |
-
-### 5.10 updateById - 根据ID更新记录
-#### 功能描述
-根据主键ID更新记录，返回更新后的完整记录。
-#### 函数签名
-```javascript
-async updateById(id, data = {}) => Promise<Object>
+Container <── Service
 ```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| id | number/string | 是 | - | 记录主键ID |
-| data | Object | 否 | {} | 更新的数据对象 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数无效（ID/数据为空） | `{ success: false, code: 400, msg: '参数无效', data: {} }` |
-| 更新成功 | `{ success: true, code: 200, msg: '更新成功', data: Object }` |
-
-### 5.11 updateMany - 批量更新记录（事务）
-#### 功能描述
-基于事务的批量更新，确保所有更新操作原子性（要么全部成功，要么全部回滚）。
-#### 函数签名
-```javascript
-async updateMany(updates = []) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| updates | Array<Object> | 否 | [] | 批量更新配置，每项结构：`{ query: Object, data: Object }` |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数无效（非数组/空数组） | `{ success: false, code: 400, msg: '参数缺失', data: {} }` |
-| 单条条件为空 | `{ success: false, code: 400, msg: '参数无效：批量更新不允许空条件', data: {} }` |
-| 更新成功 | `{ success: true, code: 200, msg: '批量更新成功', data: { affectedRows: number } }` |
-
-#### 事务逻辑
-1. 开启数据库事务；
-2. 遍历更新配置，逐条执行更新；
-3. 任意一条更新条件为空时，回滚事务并返回失败；
-4. 全部执行完成后提交事务，返回总受影响行数。
-
-### 5.12 query - 分页查询（页码模式）
-#### 功能描述
-基于页码的分页查询，自动计算偏移量，返回包含分页信息的结构化结果。
-#### 函数签名
+
+## 构造函数
+
 ```javascript
-async query({ current = 1, pageSize = 10, query = {}, sort = {}, field = [] }) => Promise<Object>
+constructor()
 ```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| current | number | 否 | 1 | 当前页码 |
-| pageSize | number | 否 | 10 | 每页条数（自动限制在1~limit之间） |
-| query | Object | 否 | {} | 查询条件 |
-| sort | Object | 否 | {} | 排序条件 |
-| field | Array<string> | 否 | [] | 查询字段 |
-
-#### 返回值
+
+调用父类 `Container` 构造函数，指定组件类型为 `'service'`。
+
+## 设计原则
+
+1. **无表绑定**：Service 不直接操作数据库表
+2. **无 CRUD 方法**：所有数据操作委托给 Repository
+3. **业务编排**：负责组合多个 Repository 完成复杂业务逻辑
+4. **事务管理**：可跨 Repository 进行事务编排
+
+## 使用示例
+
+### 基础示例
+
 ```javascript
-{
-  success: true,
-  code: 200,
-  msg: '查询成功',
-  data: {
-    list: Array, // 查询结果列表
-    total: number, // 总记录数
-    current: number, // 当前页码
-    pageSize: number, // 实际每页条数
-    totalPages: number // 总页数
+import { Service } from 'chanjs';
+import UserRepo from '../repository/UserRepo.js';
+import OrderRepo from '../repository/OrderRepo.js';
+
+export default class UserService extends Service {
+  constructor() {
+    super();
+    this.userRepo = new UserRepo();
+    this.orderRepo = new OrderRepo();
+  }
+
+  // 查询用户及其订单
+  async getUserWithOrders(userId) {
+    const user = await this.userRepo.findById(userId);
+    if (!user.success) {
+      return user;
+    }
+    
+    const orders = await this.orderRepo.all({
+      query: { userId }
+    });
+    
+    return this.success({
+      data: {
+        user: user.data,
+        orders: orders.data
+      }
+    });
   }
 }
 ```
 
-### 5.13 count - 统计记录数
-#### 功能描述
-根据条件统计记录总数。
-#### 函数签名
-```javascript
-async count(query = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 统计条件 |
+### 跨表事务示例
 
-#### 返回值
 ```javascript
-{
-  success: true,
-  code: 200,
-  msg: '统计成功',
-  data: { count: number } // 统计结果
-}
-```
+import { Service } from 'chanjs';
+import UserRepo from '../repository/UserRepo.js';
+import WalletRepo from '../repository/WalletRepo.js';
 
-### 5.14 exists - 检查记录是否存在
-#### 功能描述
-根据条件检查是否存在匹配记录。
-#### 函数签名
-```javascript
-async exists(query = {}) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 检查条件 |
+export default class PaymentService extends Service {
+  constructor() {
+    super();
+    this.userRepo = new UserRepo();
+    this.walletRepo = new WalletRepo();
+  }
 
-#### 返回值
-```javascript
-{
-  success: true,
-  code: 200,
-  msg: '检查成功',
-  data: { exists: boolean } // 是否存在匹配记录
+  // 用户充值（跨表事务）
+  async recharge(userId, amount) {
+    const trx = await this.db.transaction();
+    
+    try {
+      // 更新用户余额
+      await this.userRepo.updateById(userId, {
+        balance: this.db.raw(`balance + ${amount}`)
+      }, trx);
+      
+      // 记录充值流水
+      await this.walletRepo.insert({
+        userId,
+        amount,
+        type: 'recharge',
+        createdAt: new Date()
+      }, trx);
+      
+      await trx.commit();
+      return this.success({ msg: '充值成功' });
+    } catch (err) {
+      await trx.rollback();
+      return this.fail({ 
+        msg: '充值失败', 
+        code: 500 
+      });
+    }
+  }
 }
 ```
 
-### 5.15 join - 关联查询
-#### 功能描述
-实现两表内连接查询，支持条件、排序、字段筛选。
-#### 函数签名
-```javascript
-async join({ joinTable, localField, foreignField, fields = ["*"], query = {}, sort = {} }) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| joinTable | string | 是 | - | 关联表名 |
-| localField | string | 是 | - | 主表关联字段 |
-| foreignField | string | 是 | - | 关联表关联字段 |
-| fields | Array<string> | 否 | ["*"] | 查询字段（可指定表别名，如 `table1.field1`） |
-| query | Object | 否 | {} | 查询条件 |
-| sort | Object | 否 | {} | 排序条件 |
-
-#### 返回值
+### 复杂业务逻辑示例
+
 ```javascript
-{
-  success: true,
-  code: 200,
-  msg: '查询成功',
-  data: Array // 关联查询结果列表
+import { Service } from 'chanjs';
+import UserRepo from '../repository/UserRepo.js';
+import OrderRepo from '../repository/OrderRepo.js';
+import ProductRepo from '../repository/ProductRepo.js';
+
+export default class OrderService extends Service {
+  constructor() {
+    super();
+    this.userRepo = new UserRepo();
+    this.orderRepo = new OrderRepo();
+    this.productRepo = new ProductRepo();
+  }
+
+  // 创建订单
+  async createOrder(userId, products) {
+    // 1. 校验用户
+    const user = await this.userRepo.findById(userId);
+    if (!user.success) {
+      return this.fail({ msg: '用户不存在' });
+    }
+    
+    // 2. 校验商品库存
+    for (const item of products) {
+      const product = await this.productRepo.findById(item.productId);
+      if (!product.success || product.data.stock < item.quantity) {
+        return this.fail({ 
+          msg: `商品 ${product.data.name} 库存不足` 
+        });
+      }
+    }
+    
+    // 3. 计算订单金额
+    const totalAmount = await this.calculateTotal(products);
+    
+    // 4. 创建订单
+    const order = await this.orderRepo.insert({
+      userId,
+      totalAmount,
+      status: 'pending',
+      createdAt: new Date()
+    });
+    
+    // 5. 扣减库存
+    await this.deductStock(products);
+    
+    return this.success({
+      data: { orderId: order.data.insertId },
+      msg: '订单创建成功'
+    });
+  }
+
+  // 计算订单总额
+  async calculateTotal(products) {
+    let total = 0;
+    for (const item of products) {
+      const product = await this.productRepo.findById(item.productId);
+      total += product.data.price * item.quantity;
+    }
+    return total;
+  }
+
+  // 扣减库存
+  async deductStock(products) {
+    for (const item of products) {
+      await this.productRepo.updateById(item.productId, {
+        stock: this.db.raw(`stock - ${item.quantity}`)
+      });
+    }
+  }
 }
 ```
 
-### 5.16 deleteMany - 批量删除（ID数组）
-#### 功能描述
-根据ID数组批量删除记录。
-#### 函数签名
-```javascript
-async deleteMany(ids = []) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| ids | Array<number/string> | 否 | [] | 待删除记录的ID数组 |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| ID数组为空 | `{ success: false, code: 400, msg: '参数缺失', data: {} }` |
-| 删除成功 | `{ success: true, code: 200, msg: '删除成功', data: { affectedRows: number } }` |
-
-### 5.17 softDelete - 软删除
-#### 功能描述
-设置 `deleted_at` 字段为当前时间，实现逻辑删除（非物理删除）。
-#### 函数签名
-```javascript
-async softDelete(id) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| id | number/string | 是 | 记录主键ID |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数为空 | `{ msg: '参数缺失' }` |
-| 删除成功 | `{ affectedRows: number }` |
-
-### 5.18 restore - 恢复软删除记录
-#### 功能描述
-将 `deleted_at` 字段置为 `null`，恢复软删除的记录。
-#### 函数签名
-```javascript
-async restore(id) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| id | number/string | 是 | 记录主键ID |
-
-#### 返回值
-| 场景 | 返回结构 |
-|------|----------|
-| 参数为空 | `{ msg: '参数缺失' }` |
-| 恢复成功 | `{ affectedRows: number }` |
-
-### 5.19 findTrashed - 查询软删除记录
-#### 功能描述
-查询已被软删除的记录（`deleted_at` 不为空）。
-#### 函数签名
-```javascript
-async findTrashed({ query = {}, fields = [], limit = 20, offset = 0 } = {}) => Promise<Array>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| query | Object | 否 | {} | 额外查询条件 |
-| fields | Array<string> | 否 | [] | 查询字段 |
-| limit | number | 否 | 20 | 限制条数 |
-| offset | number | 否 | 0 | 偏移量 |
-
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| Promise<Array> | 软删除记录列表，按 `deleted_at` 降序排列 |
+## 访问全局资源
 
-### 5.20 forceDelete - 强制删除软删除记录
-#### 功能描述
-物理删除指定天数前被软删除的记录，用于清理历史数据。
-#### 函数签名
-```javascript
-async forceDelete(days = 30) => Promise<Object>
-```
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| days | number | 否 | 30 | 天数（删除N天前的软删除记录） |
+Service 继承自 Container，可访问以下全局资源：
 
-#### 返回值
-| 类型 | 说明 |
+| 属性 | 说明 |
 |------|------|
-| Promise<Object> | `{ affectedRows: number }` - 受影响的行数 |
+| `this.app` | 全局应用实例 |
+| `this.config` | 全局配置对象 |
+| `this.db` | 默认数据库连接 |
+| `this.paths` | 路径工具对象 |
 
-### 5.21 stats - 统计总数与今日新增
-#### 功能描述
-统计表中总记录数和今日新增记录数（按 `created_at` 字段）。
-#### 函数签名
-```javascript
-async stats() => Promise<Object>
-```
-#### 返回值
-| 类型 | 结构 |
-|------|------|
-| Promise<Object> | `{ total: number, today: number }` - total为总记录数，today为今日新增数 |
+### 示例
 
-## 六、使用示例
-### 6.1 基础使用（子类继承）
 ```javascript
-// UserService.js
-import Service from './Service.js';
-
-class UserService extends Service {
-  constructor() {
-    // 指定表名和数据库连接名
-    super('user', 'default');
+export default class ConfigService extends Service {
+  async getAppName() {
+    // 访问全局配置
+    const appName = this.config.APP_NAME;
+    return this.success({ data: appName });
   }
 
-  // 自定义业务方法
-  async findByUsername(username) {
-    return this.findOne({ query: { username } });
+  async getDbVersion() {
+    // 访问数据库连接
+    const [result] = await this.db.raw('SELECT VERSION() as version');
+    return this.success({ data: result[0].version });
   }
 }
-
-export default new UserService();
 ```
 
-### 6.2 调用示例
+## 动态加载组件
+
+Service 可使用 `get` 方法动态加载其他 Service 或 Repository：
+
 ```javascript
-import userService from './UserService.js';
-
-// 1. 查询用户列表（分页）
-const userPage = await userService.query({
-  current: 1,
-  pageSize: 10,
-  query: { status: 1 },
-  sort: { create_at: 'desc' },
-  field: ['id', 'username', 'email']
-});
-
-// 2. 新增用户
-const insertRes = await userService.insert({
-  username: 'test',
-  email: 'test@example.com',
-  created_at: '2024-01-01 12:00:00'
-});
-
-// 3. 软删除用户
-await userService.softDelete(1);
-
-// 4. 恢复软删除用户
-await userService.restore(1);
-
-// 5. 关联查询（用户-订单）
-const userOrder = await userService.join({
-  joinTable: 'order',
-  localField: 'id',
-  foreignField: 'user_id',
-  fields: ['user.username', 'order.order_no'],
-  query: { user.status: 1 }
-});
+export default class OrderService extends Service {
+  async processOrder(orderId) {
+    // 动态加载 UserService
+    const userService = await this.get('user', 'UserService');
+    
+    // 调用 UserService 方法
+    const user = await userService.getUserById(1);
+    
+    // 业务逻辑...
+  }
+}
 ```
 
-## 七、注意事项
-1. 所有方法均依赖 `Chan` 全局对象，需确保初始化时已配置数据库连接和相关配置项；
-2. 日期字段格式化仅处理 `_dateFields` 中的字段，若需扩展可在子类中重写该属性；
-3. 事务操作（`updateMany`）需数据库支持事务，否则会抛出异常；
-4. 分页查询 `query` 方法会自动限制 `pageSize` 不超过 `limit`，避免大数据量查询；
-5. 软删除相关方法依赖 `deleted_at` 字段，需确保表结构中包含该字段。
+## 注意事项
+
+1. Service 不包含 CRUD 方法，数据操作请使用 Repository
+2. 建议在 Service 中注入所需的 Repository 实例
+3. 跨表事务需在 Service 层统一管理
+4. Service 文件应放在 `app/modules/{moduleName}/service/` 目录下
+5. 导出时使用 `export default` 导出实例或类