chanjs 2.7.8 → 2.7.10

package/doc/Repository.md

@@ -1,560 +0,0 @@
-# Repository 数据访问层
-
-## 概述
-
-`Repository` 是数据访问层基类，继承自 `Container`，封装了常用的数据库 CRUD 操作。基于 Knex.js 构建，提供统一的查询接口和错误处理。
-
-## 继承关系
-
-```
-Container <── Repository
-```
-
-## 构造函数
-
-```javascript
-constructor(tableName, dbName = 'default')
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| tableName | string | 是 | - | 数据库表名 |
-| dbName | string | 否 | 'default' | 数据库连接名称 |
-
-**示例**
-
-```javascript
-import { Repository } from 'chanjs';
-
-class UserRepo extends Repository {
-  constructor() {
-    super('users', 'default');
-  }
-}
-
-export default new UserRepo();
-```
-
-## 核心方法
-
-### 1. all - 查询全部
-
-```javascript
-all({ query, sort, fields, limit })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| query | object | 否 | {} | 查询条件 |
-| sort | object | 否 | {} | 排序规则 |
-| fields | string[] | 否 | [] | 返回字段，空数组返回全部 |
-| limit | number | 否 | 1000 | 返回数量上限 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: [...]
-}
-```
-
-**示例**
-
-```javascript
-// 查询所有用户
-const users = await userRepo.all();
-
-// 条件查询 + 排序
-const activeUsers = await userRepo.all({
-  query: { status: 1 },
-  sort: { createdAt: 'desc' },
-  fields: ['id', 'name', 'email'],
-  limit: 100
-});
-```
-
-### 2. find - 分页查询
-
-```javascript
-find({ query, sort, fields, limit, offset })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| query | object | 否 | {} | 查询条件 |
-| sort | object | 否 | {} | 排序规则 |
-| fields | string[] | 否 | [] | 返回字段 |
-| limit | number | 否 | 10 | 每页数量 |
-| offset | number | 否 | 0 | 偏移量 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: {
-    list: [...],
-    total: 100,
-    limit: 10,
-    offset: 0
-  }
-}
-```
-
-**示例**
-
-```javascript
-const result = await userRepo.find({
-  query: { status: 1 },
-  sort: { id: 'desc' },
-  limit: 20,
-  offset: 40  // 第 3 页
-});
-```
-
-### 3. findOne - 查询单条
-
-```javascript
-findOne({ query, fields })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| query | object | 是 | - | 查询条件 |
-| fields | string[] | 否 | [] | 返回字段 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { ... }  // 或 null
-}
-```
-
-**示例**
-
-```javascript
-const user = await userRepo.findOne({
-  query: { email: 'test@example.com' }
-});
-```
-
-### 4. findById - 根据 ID 查询
-
-```javascript
-findById(id, { fields })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| id | number/string | 是 | - | 记录 ID |
-| fields | string[] | 否 | [] | 返回字段 |
-
-**示例**
-
-```javascript
-const user = await userRepo.findById(1);
-```
-
-### 5. insert - 插入记录
-
-```javascript
-insert(data)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| data | object | 是 | 插入的数据 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { insertId: 1 }
-}
-```
-
-**示例**
-
-```javascript
-const result = await userRepo.insert({
-  name: '张三',
-  email: 'zhangsan@example.com',
-  status: 1
-});
-```
-
-### 6. insertMany - 批量插入
-
-```javascript
-insertMany(records)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| records | object[] | 是 | 记录数组 |
-
-**示例**
-
-```javascript
-await userRepo.insertMany([
-  { name: '张三', email: 'zhangsan@example.com' },
-  { name: '李四', email: 'lisi@example.com' }
-]);
-```
-
-### 7. updateById - 根据 ID 更新
-
-```javascript
-updateById(id, data)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | number/string | 是 | 记录 ID |
-| data | object | 是 | 更新的数据 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { affectedRows: 1 }
-}
-```
-
-**示例**
-
-```javascript
-await userRepo.updateById(1, {
-  name: '张三丰',
-  updatedAt: new Date()
-});
-```
-
-### 8. updateByQuery - 条件更新
-
-```javascript
-updateByQuery({ query, data })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| query | object | 是 | 更新条件 |
-| data | object | 是 | 更新的数据 |
-
-**示例**
-
-```javascript
-await userRepo.updateByQuery({
-  query: { status: 0 },
-  data: { status: 1 }
-});
-```
-
-### 9. del - 条件删除
-
-```javascript
-del(query)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| query | object | 是 | 删除条件 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { affectedRows: 1 }
-}
-```
-
-**示例**
-
-```javascript
-await userRepo.del({ status: -1 });
-```
-
-### 10. deleteById - 根据 ID 删除
-
-```javascript
-deleteById(id)
-```
-
-**示例**
-
-```javascript
-await userRepo.deleteById(1);
-```
-
-### 11. deleteMany - 批量删除
-
-```javascript
-deleteMany(ids)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| ids | array | 是 | ID 数组 |
-
-**示例**
-
-```javascript
-await userRepo.deleteMany([1, 2, 3]);
-```
-
-### 12. count - 统计数量
-
-```javascript
-count(query)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| query | object | 否 | {} | 查询条件 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { count: 100 }
-}
-```
-
-**示例**
-
-```javascript
-const result = await userRepo.count({ status: 1 });
-console.log(result.data.count);  // 100
-```
-
-### 13. exists - 判断是否存在
-
-```javascript
-exists(query)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| query | object | 是 | 查询条件 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: { exists: true }
-}
-```
-
-**示例**
-
-```javascript
-const result = await userRepo.exists({ email: 'test@example.com' });
-if (result.data.exists) {
-  console.log('用户已存在');
-}
-```
-
-### 14. join - 联表查询
-
-```javascript
-join({ joinTable, localField, foreignField, fields, query, sort })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| joinTable | string | 是 | - | 关联表名 |
-| localField | string | 是 | - | 本表关联字段 |
-| foreignField | string | 是 | - | 关联表字段 |
-| fields | string[] | 否 | [] | 返回字段 |
-| query | object | 否 | {} | 查询条件 |
-| sort | object | 否 | {} | 排序规则 |
-
-**示例**
-
-```javascript
-const result = await userRepo.join({
-  joinTable: 'orders',
-  localField: 'id',
-  foreignField: 'userId',
-  fields: ['users.name', 'orders.total'],
-  query: { 'orders.status': 1 }
-});
-```
-
-### 15. stats - 统计总数和今日新增
-
-```javascript
-stats(dateField = 'createdAt')
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| dateField | string | 否 | 'createdAt' | 日期字段名 |
-
-**返回值**
-
-```javascript
-{
-  success: true,
-  code: 0,
-  msg: '操作成功',
-  data: {
-    total: 1000,
-    today: 50
-  }
-}
-```
-
-**示例**
-
-```javascript
-const result = await userRepo.stats('createdAt');
-console.log(`总数：${result.data.total}，今日新增：${result.data.today}`);
-```
-
-## 查询条件语法
-
-Repository 支持灵活的查询条件语法：
-
-### 等值查询
-
-```javascript
-{ field: value }
-```
-
-### 范围查询
-
-```javascript
-{ field: { $gt: 10, $lt: 20 } }  // 大于 10 且小于 20
-{ field: { $gte: 10, $lte: 20 } } // 大于等于 10 且小于等于 20
-```
-
-### 模糊查询
-
-```javascript
-{ field: { $like: '%keyword%' } }
-```
-
-### IN 查询
-
-```javascript
-{ field: { $in: [1, 2, 3] } }
-```
-
-### NOT 查询
-
-```javascript
-{ field: { $ne: value } }
-```
-
-### NULL 查询
-
-```javascript
-{ field: { $null: true } }   // IS NULL
-{ field: { $notNull: true } } // IS NOT NULL
-```
-
-## 完整示例
-
-```javascript
-import { Repository } from 'chanjs';
-
-class UserRepo extends Repository {
-  constructor() {
-    super('users', 'default');
-  }
-
-  // 自定义业务方法
-  async findActiveUsers() {
-    return this.all({
-      query: { status: 1 },
-      sort: { createdAt: 'desc' }
-    });
-  }
-
-  async findByEmail(email) {
-    return this.findOne({
-      query: { email }
-    });
-  }
-
-  async deactivateUser(id) {
-    return this.updateById(id, {
-      status: 0,
-      deactivatedAt: new Date()
-    });
-  }
-}
-
-export default new UserRepo();
-```
-
-## 注意事项
-
-1. Repository 封装了 Knex.js，所有查询都会经过参数校验和 SQL 注入防护
-2. 返回结果统一使用 `{ success, code, msg, data }` 格式
-3. 错误会自动转换为框架标准错误类
-4. 支持多数据库连接，通过构造函数的 `dbName` 参数指定
-5. 日期字段会自动进行格式化处理
-
-## 相关文档
-
-- [QuickStart](./QuickStart.md) - 快速入门
-- [Controller](./Controller.md) - 控制器基类
-- [Service](./Service.md) - 服务基类
-- [Cache](./Cache.md) - 缓存工具
-- [Common](./Common.md) - 公共工具模块