@fastcar/cli 0.1.2 → 0.1.4

package/skills/fastcar-database/SKILL.md

@@ -5,7 +5,7 @@ description: FastCar 数据库与缓存开发指南。Use when working with Fast
 
 # FastCar Database
 
-FastCar 数据库模块提供基于装饰器的 ORM 支持，涵盖 MySQL、PostgreSQL、MongoDB 和 Redis，并支持通过 `mysql-tool` 逆向生成 Model 和 Mapper。
+FastCar 数据库模块提供基于装饰器的 ORM 支持，涵盖 MySQL、PostgreSQL、MongoDB 和 Redis。
 
 ## 模块速查
 
@@ -26,10 +26,17 @@ export default new APP();
 #### 定义实体模型
 
 ```typescript
-import { Table, Field, DBType, PrimaryKey, NotNull, Size } from "@fastcar/core/annotation";
-
-@Table("users")
-class User {
+import {
+  Table,
+  Field,
+  DBType,
+  PrimaryKey,
+  NotNull,
+  Size,
+} from "@fastcar/core/annotation";
+
+@Table("entities")
+class Entity {
   @Field("id")
   @DBType("int")
   @PrimaryKey
@@ -41,27 +48,16 @@ class User {
   @Size({ maxSize: 50 })
   name!: string;
 
-  @Field("profile")
+  @Field("data")
   @DBType("json")
-  profile!: any;
+  data!: any;
 
   @Field("created_at")
   @DBType("datetime")
   createdAt!: Date;
 
-  constructor(args?: Partial<User>) {
-    if (args) {
-      Object.assign(this, args);
-    }
-  }
-
-  toObject() {
-    return {
-      id: this.id,
-      name: this.name,
-      profile: this.profile,
-      createdAt: this.createdAt,
-    };
+  constructor(args?: Partial<Entity>) {
+    if (args) Object.assign(this, args);
   }
 }
 ```
@@ -71,300 +67,269 @@ class User {
 ```typescript
 import { Entity, Repository } from "@fastcar/core/annotation";
 import { MysqlMapper } from "@fastcar/mysql";
-import User from "./User";
+import Entity from "./Entity";
 
-@Entity(User)
+@Entity(Entity)
 @Repository
-class UserMapper extends MysqlMapper<User> {}
-
-export default UserMapper;
+class EntityMapper extends MysqlMapper<Entity> {}
+export default EntityMapper;
 ```
 
-#### MysqlMapper 完整 API 参考
+#### MysqlMapper 核心 API
 
 ```typescript
 import { Service, Autowired } from "@fastcar/core/annotation";
 import { OrderEnum, OperatorEnum } from "@fastcar/core/db";
-import UserMapper from "./UserMapper";
-import User from "./User";
+import EntityMapper from "./EntityMapper";
+import Entity from "./Entity";
 
 @Service
-class UserService {
+class EntityService {
   @Autowired
-  private userMapper!: UserMapper;
+  private mapper!: EntityMapper;
 
-  // ==================== 查询方法 ====================
+  // ===== 查询方法 =====
 
-  // 1. select(conditions) - 查询列表
-  // 返回: T[] - 实体对象数组
-  async getAllUsers() {
-    return this.userMapper.select({});
+  // 查询列表
+  async list() {
+    return this.mapper.select({});
   }
 
-  // 2. selectOne(conditions) - 查询单个
-  // 返回: T | null
-  async getUserById(id: number) {
-    return this.userMapper.selectOne({
-      where: { id }
-    });
+  // 查询单个
+  async getOne(id: number) {
+    return this.mapper.selectOne({ where: { id } });
   }
 
-  // 3. selectByPrimaryKey(row) - 根据主键查询
-  // 参数: 包含主键字段的对象
-  // 返回: T | null
-  async getUserByPK(id: number) {
-    return this.userMapper.selectByPrimaryKey({ id } as User);
+  // 根据主键查询
+  async getByPK(id: number) {
+    return this.mapper.selectByPrimaryKey({ id } as Entity);
   }
 
-  // 4. count(where) - 统计记录数
-  // 返回: number
-  async countUsers() {
-    return this.userMapper.count({ status: 1 });
+  // 统计记录数
+  async count() {
+    return this.mapper.count({ status: 1 });
   }
 
-  // 5. exist(where) - 判断是否存在
-  // 返回: boolean
-  async checkUserExists(name: string) {
-    return this.userMapper.exist({ name });
+  // 判断是否存在
+  async exists(name: string) {
+    return this.mapper.exist({ name });
   }
 
-  // ==================== 条件查询详解 ====================
+  // ===== 条件查询 =====
 
   // 简单等于条件
   async queryByStatus(status: number) {
-    return this.userMapper.select({
-      where: { status }
-    });
+    return this.mapper.select({ where: { status } });
   }
 
   // 多条件 AND
   async queryByConditions(name: string, status: number) {
-    return this.userMapper.select({
-      where: {
-        name,
-        status,
-        delStatus: false
-      }
+    return this.mapper.select({
+      where: { name, status, delStatus: false },
     });
   }
 
   // 比较运算符
-  async queryByAgeRange(minAge: number, maxAge: number) {
-    return this.userMapper.select({
-      where: {
-        age: { $gte: minAge, $lte: maxAge }
-      }
+  async queryByRange(min: number, max: number) {
+    return this.mapper.select({
+      where: { value: { [OperatorEnum.gte]: min, [OperatorEnum.lte]: max } },
     });
   }
 
-  // 支持的运算符:
-  // $eq - 等于 (默认)
-  // $gt / $gte - 大于 / 大于等于
-  // $lt / $lte - 小于 / 小于等于
-  // $ne - 不等于
-  // $in - IN 查询 (数组)
-  // $nin - NOT IN 查询
-  // $isNull - IS NULL
-  // $isNotNull - IS NOT NULL
-
   // IN 查询
   async queryByIds(ids: number[]) {
-    return this.userMapper.select({
-      where: { id: { $in: ids } }
+    return this.mapper.select({
+      where: { id: { [OperatorEnum.in]: ids } },
     });
   }
 
   // IS NULL 查询
-  async queryDeletedUsers() {
-    return this.userMapper.select({
-      where: { deletedAt: { $isNull: true } }
+  async queryDeleted() {
+    return this.mapper.select({
+      where: { deletedAt: { [OperatorEnum.isNUll]: true } },
     });
   }
 
-  // ==================== 排序和分页 ====================
+  // ===== AND 条件查询 =====
 
-  // 排序 - 必须使用 OrderEnum
-  async getUsersOrdered() {
-    return this.userMapper.select({
-      where: { status: 1 },
-      orders: { createdAt: OrderEnum.desc }  // 正确: 使用 OrderEnum.desc
-      // 错误: orders: { createdAt: "DESC" }
+  // 方式1：默认多字段自动 AND
+  async queryByMultipleConditions(name: string, status: number) {
+    return this.mapper.select({
+      where: { name, status, delStatus: false },
+      // 生成 SQL: WHERE name = ? AND status = ? AND del_status = ?
     });
   }
 
-  // OrderEnum 定义:
-  // OrderEnum.asc = "ASC"
-  // OrderEnum.desc = "DESC"
-
-  // 多字段排序
-  async getUsersMultiOrder() {
-    return this.userMapper.select({
-      orders: {
-        status: OrderEnum.asc,
-        createdAt: OrderEnum.desc
-      }
+  // 方式2：同一字段多条件 AND
+  async queryByAgeRange(min: number, max: number) {
+    return this.mapper.select({
+      where: {
+        age: { [OperatorEnum.gte]: min, [OperatorEnum.lte]: max },
+        // 生成 SQL: WHERE age >= ? AND age <= ?
+      },
     });
   }
 
-  // 分页
-  async getUsersPaged(page: number, pageSize: number) {
-    return this.userMapper.select({
-      orders: { id: OrderEnum.desc },
-      offest: (page - 1) * pageSize,
-      limit: pageSize
+  // ===== OR 条件查询 =====
+
+  // 方式1：对象形式（推荐）- 不同字段 OR
+  async queryByNameOrEmail(keyword: string) {
+    return this.mapper.select({
+      where: {
+        [JoinEnum.or]: {
+          name: keyword,
+          email: keyword,
+        },
+        // 生成 SQL: WHERE name = ? OR email = ?
+      },
     });
   }
 
-  // 只取前N条
-  async getTopUsers(limit: number) {
-    return this.userMapper.select({
-      orders: { score: OrderEnum.desc },
-      limit
+  // 方式2：数组形式 - 复杂条件 OR
+  async queryComplexOr() {
+    return this.mapper.select({
+      where: {
+        [JoinEnum.or]: [
+          { status: 1, type: "A" },
+          { status: 2, type: "B" },
+        ],
+        // 生成 SQL: WHERE (status = 1 AND type = 'A') OR (status = 2 AND type = 'B')
+      },
     });
   }
 
-  // ==================== 插入方法 ====================
+  // ===== AND 与 OR 组合 =====
 
-  // 1. saveOne(row) - 插入单条
-  // 返回: number - 插入的主键ID
-  async createUser(name: string) {
-    const user = new User({ name, createdAt: new Date() });
-    const insertId = await this.userMapper.saveOne(user);
-    return insertId;
+  async queryComplex(department: string, status: number, keyword: string) {
+    return this.mapper.select({
+      where: {
+        department,
+        [JoinEnum.or]: {
+          name: { [OperatorEnum.like]: `%${keyword}%` },
+          email: { [OperatorEnum.like]: `%${keyword}%` },
+        },
+        status,
+        // 生成 SQL: WHERE department = ? AND (name LIKE ? OR email LIKE ?) AND status = ?
+      },
+    });
   }
 
-  // 2. saveList(rows) - 批量插入
-  // 返回: boolean
-  async createUsers(users: User[]) {
-    return this.userMapper.saveList(users);
+  // ===== 排序和分页 =====
+
+  async getOrdered() {
+    return this.mapper.select({
+      where: { status: 1 },
+      orders: { createdAt: OrderEnum.desc },
+    });
   }
 
-  // 3. saveORUpdate(rows) - 插入或更新 (UPSERT)
-  // 主键冲突时更新，否则插入
-  // 返回: number - 主键ID
-  async saveOrUpdateUser(user: User) {
-    return this.userMapper.saveORUpdate(user);
+  async getPaged(page: number, pageSize: number) {
+    return this.mapper.select({
+      orders: { id: OrderEnum.desc },
+      offset: (page - 1) * pageSize,
+      limit: pageSize,
+    });
   }
 
-  // ==================== 更新方法 ====================
+  // ===== 插入方法 =====
 
-  // 1. update({ row, where, limit }) - 条件更新
-  // 返回: boolean
-  async updateUserName(id: number, name: string) {
-    return this.userMapper.update({
-      where: { id },
-      row: { name, updatedAt: new Date() }
-    });
+  // 插入单条
+  async create(name: string) {
+    const entity = new Entity({ name, createdAt: new Date() });
+    return this.mapper.saveOne(entity);
   }
 
-  // 2. updateOne({ row, where }) - 更新单条
-  // 自动限制 limit: 1
-  async updateOneUser(where: any, row: any) {
-    return this.userMapper.updateOne({ where, row });
+  // 批量插入
+  async createBatch(list: Entity[]) {
+    return this.mapper.saveList(list);
   }
 
-  // 3. updateByPrimaryKey(row) - 根据主键更新
-  // 根据实体对象的主键字段更新
-  // 返回: boolean
-  async updateById(user: User) {
-    return this.userMapper.updateByPrimaryKey(user);
+  // 插入或更新
+  async saveOrUpdate(entity: Entity) {
+    return this.mapper.saveORUpdate(entity);
   }
 
-  // 更新示例：软删除
-  async softDeleteUser(id: number) {
-    return this.userMapper.update({
+  // ===== 更新方法 =====
+
+  // 条件更新
+  async updateName(id: number, name: string) {
+    return this.mapper.update({
       where: { id },
-      row: { delStatus: true, deletedAt: new Date() }
+      row: { name, updatedAt: new Date() },
     });
   }
 
-  // ==================== 删除方法 ====================
-
-  // 1. delete({ where, limit }) - 条件删除
-  // 返回: boolean
-  async deleteUser(id: number) {
-    return this.userMapper.delete({
-      where: { id }
-    });
+  // 更新单条
+  async updateOne(where: any, row: any) {
+    return this.mapper.updateOne({ where, row });
   }
 
-  // 2. deleteOne(where) - 删除单条
-  async deleteOneUser(where: any) {
-    return this.userMapper.deleteOne(where);
+  // 根据主键更新
+  async updateById(entity: Entity) {
+    return this.mapper.updateByPrimaryKey(entity);
   }
 
-  // 3. deleteByPrimaryKey(row) - 根据主键删除
-  async deleteById(id: number) {
-    return this.userMapper.deleteByPrimaryKey({ id } as User);
+  // 软删除
+  async softDelete(id: number) {
+    return this.mapper.update({
+      where: { id },
+      row: { delStatus: true, deletedAt: new Date() },
+    });
   }
 
-  // ==================== 高级查询 ====================
+  // ===== 删除方法 =====
 
-  // 自定义 SQL 查询
-  // query(sql, args) - 执行查询 SQL
-  async customQuery() {
-    return this.userMapper.query(
-      "SELECT * FROM users WHERE status = ? AND created_at > ?",
-      [1, "2024-01-01"]
-    );
+  async deleteById(id: number) {
+    return this.mapper.delete({ where: { id } });
   }
 
-  // execute(sql, args) - 执行任意 SQL
-  async customExecute() {
-    return this.userMapper.execute(
-      "UPDATE users SET login_count = login_count + 1 WHERE id = ?",
-      [1]
-    );
+  async deleteOne(where: any) {
+    return this.mapper.deleteOne(where);
   }
 
-  // 左连接查询 - 使用 selectByCustom
-  async leftJoinQuery() {
-    return this.userMapper.selectByCustom({
+  // ===== 高级查询 =====
+
+  // selectByCustom 支持 JOIN、分组、聚合
+  async advancedQuery() {
+    // 指定字段 + 泛型类型
+    const results = await this.mapper.selectByCustom<{
+      id: number;
+      name: string;
+      relatedName: string;
+    }>({
+      tableAlias: "t",
+      fields: ["t.id", "t.name", "r.name as relatedName"],
       join: [
         {
           type: "LEFT",
-          table: "orders o",
-          on: "o.user_id = t.id",
+          table: "related_table r",
+          on: "r.entity_id = t.id",
         },
       ],
-      tableAlias: "t",
-      where: { "t.status": 1 }
-    });
-  }
-
-  // 强制索引
-  async forceIndexQuery() {
-    return this.userMapper.select({
-      forceIndex: ["idx_name"],
-      where: { status: 1 }
+      where: { "t.status": 1 },
+      camelcaseStyle: true,
     });
-  }
 
-  // 指定查询字段
-  async selectFields() {
-    return this.userMapper.select({
-      fields: ["id", "name", "email"],
-      where: { status: 1 }
+    // 聚合查询
+    const stats = await this.mapper.selectByCustom({
+      fields: [
+        "status",
+        "COUNT(*) as totalCount",
+        "MAX(created_at) as lastCreated",
+      ],
+      groups: ["status"],
+      orders: { totalCount: OrderEnum.desc },
     });
-  }
 
-  // 分组查询
-  async groupByStatus() {
-    return this.userMapper.selectByCustom({
-      fields: ["status", "COUNT(*) as count"],
-      groups: ["status"]
-    });
+    return { results, stats };
   }
 
-  // 使用数据库函数
-  async useDbFunction() {
-    return this.userMapper.selectByCustom({
-      fields: [
-        'id',
-        'name',
-        'DATE_FORMAT(created_at, "%Y-%m-%d") as createdDate'
-      ]
-    });
+  // 自定义 SQL
+  async customQuery() {
+    return this.mapper.query(
+      "SELECT * FROM entities WHERE status = ? AND created_at > ?",
+      [1, "2024-01-01"],
+    );
   }
 }
 ```
@@ -372,45 +337,43 @@ class UserService {
 #### 常用查询条件速查表
 
 ```typescript
+import { OperatorEnum, OrderEnum } from "@fastcar/core/db";
+
 // 等于 (默认)
 { where: { status: 1 } }
 
 // 不等于
-{ where: { status: { $ne: 1 } } }
-
-// 大于 / 大于等于
-{ where: { age: { $gt: 18 } } }
-{ where: { age: { $gte: 18 } } }
+{ where: { status: { [OperatorEnum.neq]: 1 } } }
 
-// 小于 / 小于等于
-{ where: { age: { $lt: 60 } } }
-{ where: { age: { $lte: 60 } } }
+// 大于 / 大于等于 / 小于 / 小于等于
+{ where: { age: { [OperatorEnum.gt]: 18 } } }
+{ where: { age: { [OperatorEnum.gte]: 18, [OperatorEnum.lte]: 60 } } }
 
-// 范围查询
-{ where: { age: { $gte: 18, $lte: 60 } } }
+// IN / NOT IN
+{ where: { id: { [OperatorEnum.in]: [1, 2, 3] } } }
+{ where: { id: { [OperatorEnum.notin]: [1, 2, 3] } } }
 
-// IN 查询
-{ where: { id: { $in: [1, 2, 3] } } }
+// IS NULL / IS NOT NULL
+{ where: { deletedAt: { [OperatorEnum.isNUll]: true } } }
+{ where: { deletedAt: { [OperatorEnum.isNotNull]: true } } }
 
-// NOT IN 查询
-{ where: { id: { $nin: [1, 2, 3] } } }
+// AND（默认，多字段自动 AND）
+{ where: { name: "A", status: 1 } }
 
-// IS NULL
-{ where: { deletedAt: { $isNull: true } } }
+// OR（对象形式 - 推荐，不同字段）
+{ where: { [JoinEnum.or]: { name: "A", email: "A" } } }
 
-// IS NOT NULL
-{ where: { deletedAt: { $isNotNull: true } } }
+// OR（数组形式，复杂条件）
+{ where: { [JoinEnum.or]: [{ status: 1 }, { status: 2 }] } }
 
-// 多条件 AND (默认)
-{ where: { status: 1, delStatus: false } }
+// AND + OR 组合
+{ where: { status: 1, [JoinEnum.or]: { type: 1, category: 2 } } }
 
-// 排序 (必须使用 OrderEnum)
-import { OrderEnum } from "@fastcar/core/db";
+// 排序
 { orders: { createdAt: OrderEnum.desc } }
-{ orders: { createdAt: OrderEnum.asc } }
 
 // 分页
-{ offest: 0, limit: 10 }
+{ offset: 0, limit: 10 }
 ```
 
 #### 事务处理
@@ -420,35 +383,33 @@ import { SqlSession } from "@fastcar/core/annotation";
 import { MysqlDataSourceManager } from "@fastcar/mysql";
 
 @Service
-class OrderService {
+class BizService {
   @Autowired
   private dsm!: MysqlDataSourceManager;
 
   @Autowired
-  private orderMapper!: OrderMapper;
+  private mapperA!: MapperA;
 
   @Autowired
-  private inventoryMapper!: InventoryMapper;
+  private mapperB!: MapperB;
 
-  async createOrderWithTransaction(order: Order, inventoryUpdate: any) {
+  async transactionExample(dataA: any, dataB: any) {
     const sessionId = await this.dsm.beginTransaction();
-    
+
     try {
-      // 插入订单
-      await this.orderMapper.saveOne(order, undefined, sessionId);
-      
-      // 更新库存
-      await this.inventoryMapper.update({
-        where: { id: inventoryUpdate.id },
-        row: { quantity: inventoryUpdate.quantity }
-      }, undefined, sessionId);
-      
-      // 提交事务
+      await this.mapperA.saveOne(dataA, undefined, sessionId);
+      await this.mapperB.update(
+        {
+          where: { id: dataB.id },
+          row: { status: dataB.status },
+        },
+        undefined,
+        sessionId,
+      );
+
       await this.dsm.commit(sessionId);
-      
       return true;
     } catch (error) {
-      // 回滚事务
       await this.dsm.rollback(sessionId);
       throw error;
     }
@@ -458,81 +419,45 @@ class OrderService {
 
 ### PostgreSQL (@fastcar/pgsql)
 
-#### 开启 PostgreSQL
-
 ```typescript
-import { Application } from "@fastcar/core/annotation";
 import { EnablePgsql } from "@fastcar/pgsql/annotation";
+import { PgsqlMapper } from "@fastcar/pgsql";
 
 @Application
 @EnablePgsql
 class APP {}
-export default new APP();
-```
-
-#### 定义 Mapper
-
-```typescript
-import { Entity, Repository } from "@fastcar/core/annotation";
-import { PgsqlMapper } from "@fastcar/pgsql";
-import User from "./User";
 
-@Entity(User)
+@Entity(Entity)
 @Repository
-class UserMapper extends PgsqlMapper<User> {}
-
-export default UserMapper;
+class EntityMapper extends PgsqlMapper<Entity> {}
 ```
 
-用法与 `MysqlMapper` 基本一致，支持相同的查询条件和 CRUD 操作。
+用法与 `MysqlMapper` 基本一致。
 
 ### MongoDB (@fastcar/mongo)
 
-#### 开启 MongoDB
-
 ```typescript
-import { Application } from "@fastcar/core/annotation";
 import { EnableMongo } from "@fastcar/mongo/annotation";
+import { MongoMapper } from "@fastcar/mongo";
 
 @Application
 @EnableMongo
 class APP {}
-export default new APP();
-```
-
-#### 定义 Mapper
 
-```typescript
-import { Entity, Repository } from "@fastcar/core/annotation";
-import { MongoMapper } from "@fastcar/mongo";
-import User from "./User";
-
-@Entity(User)
+@Entity(Entity)
 @Repository
-class UserMapper extends MongoMapper<User> {}
-
-export default UserMapper;
+class EntityMapper extends MongoMapper<Entity> {}
 ```
 
 ### Redis (@fastcar/redis)
 
-#### 开启 Redis
-
 ```typescript
-import { Application } from "@fastcar/core/annotation";
 import { EnableRedis } from "@fastcar/redis/annotation";
+import { RedisClient } from "@fastcar/redis/annotation";
 
 @Application
 @EnableRedis
 class APP {}
-export default new APP();
-```
-
-#### 使用 RedisClient
-
-```typescript
-import { Service, Autowired } from "@fastcar/core/annotation";
-import { RedisClient } from "@fastcar/redis/annotation";
 
 @Service
 class CacheService {
@@ -551,10 +476,6 @@ class CacheService {
     await this.redis.del(key);
   }
 
-  async expire(key: string, seconds: number) {
-    await this.redis.expire(key, seconds);
-  }
-
   // Hash 操作
   async hset(key: string, field: string, value: string) {
     await this.redis.hset(key, field, value);
@@ -577,17 +498,19 @@ class CacheService {
 
 ## 数据库逆向生成 (@fastcar/mysql-tool)
 
-### 生成配置文件
-
 ```bash
+# 生成配置文件
 fastcar-cli reverse:init
+
+# 执行逆向生成
+fastcar-cli reverse
 ```
 
-### 配置文件示例
+配置文件示例：
 
 ```json
 {
-  "tables": ["users", "orders"],
+  "tables": ["table1", "table2"],
   "modelDir": "D:/project/src/model",
   "mapperDir": "D:/project/src/mapper",
   "dbConfig": {
@@ -596,25 +519,10 @@ fastcar-cli reverse:init
     "user": "root",
     "password": "password",
     "database": "test_db"
-  },
-  "style": {
-    "tabWidth": 4,
-    "printWidth": 200,
-    "trailingComma": "es5",
-    "useTabs": true,
-    "parser": "typescript",
-    "endOfLine": "crlf"
-  },
-  "ignoreCamelcase": false
+  }
 }
 ```
 
-### 执行逆向生成
-
-```bash
-fastcar-cli reverse
-```
-
 ## application.yml 数据库配置
 
 ```yaml
@@ -627,10 +535,7 @@ mysql:
   database: mydb
   username: root
   password: password
-  # 连接池配置
   connectionLimit: 10
-  # 是否使用预处理语句
-  useServerPrepStmts: true
 
 pgsql:
   host: localhost
@@ -653,13 +558,13 @@ redis:
 
 ## 完整模块列表
 
-| 模块 | 安装命令 | 用途 |
-|------|----------|------|
-| @fastcar/mysql | `npm i @fastcar/mysql` | MySQL ORM |
-| @fastcar/pgsql | `npm i @fastcar/pgsql` | PostgreSQL ORM |
-| @fastcar/mongo | `npm i @fastcar/mongo` | MongoDB |
-| @fastcar/redis | `npm i @fastcar/redis` | Redis 缓存 |
-| @fastcar/mysql-tool | `npm i @fastcar/mysql-tool` | 逆向生成工具 |
+| 模块                | 安装命令                    | 用途           |
+| ------------------- | --------------------------- | -------------- |
+| @fastcar/mysql      | `npm i @fastcar/mysql`      | MySQL ORM      |
+| @fastcar/pgsql      | `npm i @fastcar/pgsql`      | PostgreSQL ORM |
+| @fastcar/mongo      | `npm i @fastcar/mongo`      | MongoDB        |
+| @fastcar/redis      | `npm i @fastcar/redis`      | Redis 缓存     |
+| @fastcar/mysql-tool | `npm i @fastcar/mysql-tool` | 逆向生成工具   |
 
 ## 快速开始
 
@@ -679,6 +584,200 @@ npm run debug
 
 1. **排序必须使用 OrderEnum**：`orders: { createdAt: OrderEnum.desc }`，不能使用字符串 `"DESC"`
 2. **主键查询**：`selectByPrimaryKey` 和 `updateByPrimaryKey` 需要传入包含主键字段的对象
-3. **时间范围查询**：使用 `$gte` 和 `$lte` 运算符
-4. **批量插入**：`saveList` 会自动分批处理（每批1000条）
-5. **软删除**：建议使用 `update` 方法更新 `delStatus` 字段，而不是物理删除
+3. **批量插入**：`saveList` 会自动分批处理（每批1000条）
+4. **软删除**：建议使用 `update` 方法更新 `delStatus` 字段，而不是物理删除
+
+## 数据库查询最佳实践
+
+### ⚠️ 分页查询 - 必须使用数据库层分页
+
+**核心原则**：分页必须在数据库层完成，严禁全表查询后在内存中切片。
+
+```typescript
+// ✅ 正确：使用 SQL LIMIT/OFFSET 分页（数据库层完成分页）
+const list = await this.mapper.select({
+  where: { status: 1 },
+  orders: { id: OrderEnum.desc },
+  offset: (page - 1) * pageSize,
+  limit: pageSize,  // 只取需要的记录
+});
+
+// ✅ 正确：使用游标/滚动分页（适合大数据量）
+const list = await this.mapper.select({
+  where: { 
+    id: { [OperatorEnum.lt]: lastId }  // 基于上一页最后ID
+  },
+  orders: { id: OrderEnum.desc },
+  limit: pageSize,
+});
+
+// ❌ 错误：全表查询后在内存中切片（数据量大时会导致 OOM）
+const allData = await this.mapper.select({ where: { status: 1 } });  // 可能百万级数据
+const pageData = allData.slice((page - 1) * pageSize, page * pageSize);  // 内存中切片
+```
+
+**为什么重要**：
+- 全表查询会将所有数据加载到 Node.js 内存，数据量大时会导致内存溢出（OOM）
+- 网络传输大量无用数据，严重影响性能
+- 数据库层分页只返回需要的记录，内存占用固定
+
+---
+
+### ⚠️ 分组聚合 - 必须使用数据库层 GROUP BY
+
+**核心原则**：分组统计必须在数据库层完成，严禁全表查询后在 JS 中分组。
+
+```typescript
+// ✅ 正确：使用 SQL GROUP BY 分组（数据库层聚合）
+const stats = await this.mapper.selectByCustom({
+  fields: [
+    "status",
+    "COUNT(*) as count",
+    "SUM(amount) as totalAmount",
+    "MAX(created_at) as latestTime",
+  ],
+  groups: ["status"],  // 数据库层分组
+  orders: { count: OrderEnum.desc },
+});
+
+// ✅ 正确：使用 JOIN + GROUP BY 关联聚合
+const userOrderStats = await this.mapper.selectByCustom({
+  fields: [
+    "u.id",
+    "u.name",
+    "COUNT(o.id) as orderCount",
+    "SUM(o.amount) as totalAmount",
+  ],
+  join: [{
+    type: "LEFT",
+    table: "orders o",
+    on: "o.user_id = u.id",
+  }],
+  groups: ["u.id", "u.name"],  // 数据库层分组聚合
+});
+
+// ❌ 错误：全表查询后在 JS 中分组（数据量大时会导致 OOM）
+const allRecords = await this.mapper.select({});  // 加载所有数据
+const grouped = allRecords.reduce((acc, item) => {
+  if (!acc[item.status]) acc[item.status] = { count: 0, total: 0 };
+  acc[item.status].count++;
+  acc[item.status].total += item.amount;
+  return acc;
+}, {});  // 内存中分组，大数据量时性能极差
+```
+
+**为什么重要**：
+- 数据库专为聚合计算优化，性能远高于 JS 遍历
+- 减少网络传输（只返回聚合结果，而非原始数据）
+- 避免 JS 单线程处理大量数据的性能瓶颈
+- 防止内存溢出风险
+
+---
+
+## 编码规范
+
+### 1. 实体对象创建规范
+
+```typescript
+// ✅ 正确：使用 key-value 形式创建对象
+const entity = new Entity({
+  name: "示例",
+  status: 1,
+  createTime: new Date(),
+});
+
+// ❌ 错误：逐行赋值创建对象
+const entity = new Entity();
+entity.name = "示例";
+entity.status = 1;
+```
+
+### 2. 分页查询规范
+
+```typescript
+// ✅ 正确：使用 SQL limit/offset 分页
+const total = await this.mapper.count(where);
+const list = await this.mapper.select({
+  where: where,
+  orders: { createTime: OrderEnum.desc },
+  offset: (page - 1) * pageSize,
+  limit: pageSize,
+});
+
+// ❌ 错误：先全表查询再用 JS slice 分页
+const list = await this.mapper.select({ where });
+const pageData = list.slice((page - 1) * pageSize, page * pageSize);
+```
+
+### 3. 查询条件规范
+
+```typescript
+import { OperatorEnum } from "@fastcar/core/db";
+
+// ✅ 正确：使用 OperatorEnum
+const list = await this.mapper.select({
+  where: {
+    age: { [OperatorEnum.gte]: 18, [OperatorEnum.lte]: 60 },
+    status: { [OperatorEnum.in]: [1, 2, 3] },
+  },
+});
+```
+
+### 4. 接口返回规范
+
+```typescript
+// ✅ 正确：返回空数据
+if (records.length === 0) {
+  return Result.ok({ list: [], total: 0 });
+}
+
+// ❌ 错误：返回模拟数据
+if (records.length === 0) {
+  return Result.ok({ list: [{ name: "模拟数据1" }] });
+}
+```
+
+### 5. 更新操作规范
+
+```typescript
+// ✅ 正确：更新少于3个字段时使用 update/updateOne
+await this.mapper.updateOne({
+  where: { id },
+  row: { lastLoginTime: new Date() },
+});
+
+// ❌ 错误：为了更新1-2个字段而查询整个实体对象
+const entity = await this.mapper.selectByPrimaryKey({ id });
+entity.lastLoginTime = new Date();
+await this.mapper.updateByPrimaryKey(entity);
+```
+
+### 6. 复杂查询优化
+
+```typescript
+// ✅ 正确：使用 selectByCustom + JOIN 一条 SQL 完成
+interface QueryResult {
+    id: number;
+    name: string;
+    relatedName: string;
+}
+
+const results = await this.mapper.selectByCustom<QueryResult>({
+    tableAlias: "t",
+    fields: ["t.id", "t.name", "r.name as relatedName"],
+    join: [{
+        type: "INNER",
+        table: "related_table r",
+        on: "r.entity_id = t.id",
+    }],
+    where: { "t.status": 1 },
+    camelcaseStyle: true,
+});
+
+// ❌ 错误：多次查询 + 内存组装（N+1 问题）
+const list = await this.mapper.select({});
+for (const item of list) {
+    const related = await this.relatedMapper.selectOne({ ... });
+    // 内存组装...
+}
+```