nicot 1.2.2 → 1.2.4

package/README.md

@@ -1,41 +1,90 @@
 # NICOT
 
-**NICOT** 是一个基于 NestJS + TypeORM 的后端开发框架。通过实体定义即生成：
-- 数据库模型（TypeORM）
-- 字段校验（class-validator）
-- 请求 DTO（Create / Update / Query）
-- RESTful 接口与文档（Swagger）
-- 统一返回结构、查询控制、权限注入等
+**NICOT** is an entity-driven REST framework for **NestJS + TypeORM**.
 
-适用于希望快速搭建标准化接口、减少重复代码的后端项目。
+You define an entity once, and NICOT generates:
+
+- ORM columns (TypeORM)
+- Validation rules (class-validator)
+- Request DTOs (Create / Update / Query)
+- RESTful endpoints + Swagger docs
+- Unified response shape, pagination, relations loading
+
+with **explicit, field-level control** over:
+
+- what can be written
+- what can be queried
+- what can be returned
 
 ---
 
-## 📦 安装
+## Name & Philosophy
+
+**NICOT** stands for:
+
+- **N** — NestJS  
+- **I** — **nesties** (the shared utility toolkit NICOT builds on)  
+- **C** — class-validator  
+- **O** — OpenAPI / Swagger  
+- **T** — TypeORM  
+
+The name also hints at **“nicotto”** / **“nicotine”**: something small that can be habit-forming. The idea is:
+
+> **One entity definition becomes the contract for everything**  
+> (DB, validation, DTO, OpenAPI, CRUD, pagination, relations).
 
-在你的 Nest.js 项目中：
+NICOT’s design is:
+
+- **Entity-driven**: metadata lives close to your domain model, not in a separate schema file.
+- **Whitelist-first**: what can be queried or returned is **only** what you explicitly decorate.
+- **AOP-like hooks**: lifecycle methods and query decorators let you inject logic without scattering boilerplate.
+
+---
+
+## Installation
 
 ```bash
 npm install nicot @nestjs/config typeorm @nestjs/typeorm class-validator class-transformer reflect-metadata @nestjs/swagger
 ```
 
+NICOT targets:
+
+- NestJS ^9 / ^10 / ^11  
+- TypeORM ^0.3.x
+
 ---
 
-## 🧱 定义实体 Entity
+## Quick Start
+
+### 1. Define your entity
 
 ```ts
+import { Entity } from 'typeorm';
+import {
+  IdBase,
+  StringColumn,
+  IntColumn,
+  BoolColumn,
+  DateColumn,
+  NotInResult,
+  NotWritable,
+  QueryEqual,
+  QueryMatchBoolean,
+} from 'nicot';
+
 @Entity()
-class User extends IdBase() {
+export class User extends IdBase() {
+  @StringColumn(255, { required: true, description: 'User name' })
   @QueryEqual()
-  @StringColumn(255, {
-    required: true,
-    description: '用户名',
-  })
   name: string;
 
   @IntColumn('int', { unsigned: true })
   age: number;
 
+  @BoolColumn({ default: true })
+  @QueryMatchBoolean()
+  isActive: boolean;
+
   @StringColumn(255)
   @NotInResult()
   password: string;
@@ -43,1205 +92,844 @@ class User extends IdBase() {
   @DateColumn()
   @NotWritable()
   createdAt: Date;
-}
-```
-
----
 
-## 🧾 主键基础类：IdBase / StringIdBase
-
-在定义实体时，NICOT 提供了两种基础类 `IdBase` 与 `StringIdBase`，可作为实体的继承基类，为你自动处理：
-
-- 主键字段定义（自增或字符串主键）
-- 主键字段的权限控制与文档注解
-- 默认排序逻辑（id 降序 / 升序）
-- 支持 queryBuilder 查询条件注入
-
----
-
-### 1. `IdBase()` - 数字主键（自增）
-
-适合常见的自增整型主键使用场景。
+  isValidInCreate() {
+    return this.age < 18 ? 'Minors are not allowed to register' : undefined;
+  }
 
-```ts
-@Entity()
-class User extends IdBase() {
-  // 继承字段：id: number (bigint unsigned, primary key, auto-increment)
+  isValidInUpdate() {
+    return undefined;
+  }
 }
 ```
 
-- 自动添加字段：`id: number`
-- 默认排序为 `ORDER BY id DESC`
-- 使用 `Generated('increment')` 作为主键生成策略
-- 搭配 `@IntColumn` + `@NotWritable()`，在创建 / 修改时不可写
+### 2. Create a RestfulFactory
 
----
-
-### 2. `StringIdBase()` - 字符串主键（手动或 UUID）
-
-适合你希望使用业务主键或 UUID 作为主键的场景。传入 `uuid: true` 参数后自动生成 UUID 主键。
+Best practice: **one factory file per entity**.
 
 ```ts
-@Entity()
-class ApiKey extends StringIdBase({ uuid: true, description: 'API 密钥 ID' }) {
-  // 继承字段：id: string (uuid, primary key)
-}
+// user.factory.ts
+export const UserFactory = new RestfulFactory(User, {
+  relations: [],             // explicitly loaded relations (for DTO + queries)
+  skipNonQueryableFields: true, // query DTO = only fields with @QueryXXX
+});
 ```
 
-- 自动添加字段：`id: string`
-- 默认排序为 `ORDER BY id ASC`
-- 支持配置长度（`length`）和描述（`description`）
-- `uuid: true` 时自动添加 `@Generated('uuid')`
-
----
-
-### 3. 示例对比
+### 3. Service with CrudService
 
 ```ts
-@Entity()
-class Article extends IdBase({ description: '文章 ID' }) {
-  // id: number 自动生成
-}
-
-@Entity()
-class Token extends StringIdBase({
-  uuid: true,
-  description: '访问令牌',
-}) {
-  // id: string，自动生成 UUID
+// user.service.ts
+@Injectable()
+export class UserService extends UserFactory.crudService() {
+  constructor(@InjectRepository(User) repo: Repository<User>) {
+    super(repo);
+  }
 }
 ```
 
----
-
-### 小结
-
-| 基类            | 主键类型   | 排序默认 | ID 生成策略         | 使用场景               |
-|-----------------|------------|----------|----------------------|------------------------|
-| `IdBase()`      | number     | DESC     | 自增 `Generated('increment')` | 常规实体 ID             |
-| `StringIdBase()`| string     | ASC      | 可选 UUID / 手动输入 | UUID 主键、业务主键等   |
-
-建议你为每个实体都继承其中一个基类，以统一主键结构和查询逻辑。
-
----
-
-## 🧠 字段装饰器总览
-
-NICOT 提供了一系列 `***Column()` 装饰器，统一处理字段的：
-
-- 数据类型定义（TypeORM）
-- 输入校验（class-validator）
-- 文档描述（@nestjs/swagger）
-
-### 字段类型装饰器（`***Column()`）
-
-| 装饰器名                   | 数据类型            | 自动添加的验证与文档                            |
-|------------------------|-----------------|---------------------------------------|
-| `@StringColumn(len)`   | varchar         | `@IsString()` + `@Length()`           |
-| `@TextColumn()`        | text            | `@IsString()`                         |
-| `@UuidColumn()`        | uuid            | `@IsUUID()`                           |
-| `@IntColumn(type)`     | int/bigint/...  | `@IsInt()` + Swagger number 类型        |
-| `@FloatColumn(type)`   | float/decimal   | `@IsNumber()`                         |
-| `@BoolColumn()`        | boolean         | `@IsBoolean()`                        |
-| `@DateColumn()`        | Date            | `@IsDate()`                           |
-| `@JsonColumn(T)`       | 任意对象/数组 (jsonb) | `@IsObject()` / `@ValidateNested()` 等 |
-| `@SimpleJsonColumn(T)` | 任意对象/数组 (json)  | `@IsObject()` / `@ValidateNested()` 等 |
-| `@StringJsonColumn(T)` | 任意对象/数组 (text)  | `@IsObject()` / `@ValidateNested()` 等 |
-
-所有字段装饰器都支持第二个参数 `options`：
+### 4. Controller using factory-generated decorators
 
 ```ts
-@StringColumn(255, {
-  required: true,
-  description: '用户名',
-  default: 'Anonymous',
-})
-name: string;
-```
-
----
-
-## 🔒 字段访问限制装饰器（行为控制）
-
-NICOT 提供以下装饰器用于控制字段在不同接口中的表现：
-
-| 装饰器名                                   | 行为控制说明                                        |
-|----------------------------------------|-----------------------------------------------|
-| `@NotWritable()`                       | 不允许在创建（POST）或修改（PATCH）时传入                     |
-| `@NotChangeable()`                     | 不允许在修改（PATCH）时更新（只可创建）                        |
-| `@NotQueryable()`                      | 不允许在 GET 查询参数中使用该字段                           |
-| `@NotInResult()`                       | 不会出现在任何返回结果中（如密码字段）                           |
-| `@NotColumn()`                         | 不是数据库字段，仅作为查询结果间接字段（在 afterGet 钩子方法赋值）        |
-| `@QueryColumn()`                       | 不是数据库字段，仅作为虚拟查询字段（和 @QueryEqual() 等查询装饰器同时使用） |
-| `@RelationComputed(() => EntityClass)` | 标识该字段依赖关系字段推导而来（通常在 afterGet）                 |
+// user.controller.ts
+import { Controller } from '@nestjs/common';
+import { PutUser } from '../auth/put-user.decorator'; // your own decorator
 
-RestfulFactory 处理 Entity 类的时候，会以这些装饰器为依据，裁剪生成的 DTO 和查询参数。
+// Fix DTO types up front
+export class CreateUserDto extends UserFactory.createDto {}
+export class UpdateUserDto extends UserFactory.updateDto {}
+export class FindAllUserDto extends UserFactory.findAllDto {}
 
-这些限制装饰器非常适合处理：
+@Controller('users')
+export class UserController {
+  constructor(private readonly service: UserService) {}
 
-- 安全字段（如密码、Token）
-- 系统字段（如创建时间、创建者 ID）
-- 只读字段（如 auto-increment 主键）
+  @UserFactory.create()
+  async create(
+    @UserFactory.createParam() dto: CreateUserDto,
+    @PutUser() currentUser: User,
+  ) {
+    // business logic - attach owner
+    dto.ownerId = currentUser.id;
+    return this.service.create(dto);
+  }
 
----
+  @UserFactory.findAll()
+  async findAll(
+    @UserFactory.findAllParam() dto: FindAllUserDto,
+    @PutUser() currentUser: User,
+  ) {
+    return this.service.findAll(dto, qb => {
+      qb.andWhere('user.ownerId = :uid', { uid: currentUser.id });
+    });
+  }
 
-### 示例：完整字段定义
+  @UserFactory.findOne()
+  async findOne(@UserFactory.idParam() id: number) {
+    return this.service.findOne(id);
+  }
 
-```ts
-@StringColumn(255, {
-  required: true,
-  description: '用户昵称',
-})
-@NotWritable()
-nickname: string;
+  @UserFactory.update()
+  async update(
+    @UserFactory.idParam() id: number,
+    @UserFactory.updateParam() dto: UpdateUserDto,
+  ) {
+    return this.service.update(id, dto);
+  }
 
-@BoolColumn()
-@QueryMatchBoolean()
-isActive: boolean;
+  @UserFactory.delete()
+  async delete(@UserFactory.idParam() id: number) {
+    return this.service.delete(id);
+  }
+}
 ```
 
----
-
-## 🔍 查询装饰器总览（Query 系列）
-
-NICOT 提供了一套查询装饰器，用于在 Entity 字段上声明支持的 GET 查询条件。它们会自动应用到 `findAll()` 中的 queryBuilder。
-
-### ✅ 内建查询装饰器
-
-| 装饰器名                                                 | 查询效果                                            |
-|------------------------------------------------------|-------------------------------------------------|
-| `@QueryEqual()`                                      | 精确匹配：`WHERE field = :value`                     |
-| `@QueryLike()`                                       | 前缀模糊匹配：`WHERE field LIKE :value%`               |
-| `@QuerySearch()`                                     | 宽泛模糊搜索：`WHERE field LIKE %:value%`              |
-| `@QueryMatchBoolean()`                               | `true/false/1/0` 转换为布尔类型查询                      |
-| `@QueryEqualZeroNullable()`                          | `0 → IS NULL`，否则 `= :value`（适合 nullable）        |
-| `@QueryIn()`                                         | 包含查询：`WHERE field IN (:...value)`，value 可以数组或者逗号分隔 |
-| `@QueryNotIn()`                                      | 不包含查询：`WHERE field NOT IN (:...value)`          |
-| `@QueryGreater(field)`                               | 大于查询：`WHERE field > :value`                     |
-| `@QueryLess(field)`                                  | 小于查询：`WHERE field < :value`                     |
-| `@QueryGreaterOrEqual(field)`                        | 大于等于查询：`WHERE field >= :value`                  |
-| `@QueryLessOrEqual(field)`                           | 小于等于查询：`WHERE field <= :value`                  |
-| `@QueryJsonbHas()`                                   | JSONB 包含键查询：`WHERE field ? :value`              |
-| `@QueryOperator('=')`                                | 自定义操作符查询：`WHERE field <operator> :value`        |
-| `@QueryWrap((entExpr, valExpr) => `${entExpr} = ${valExpr}`) | 自定义查询片段                                         |
-| `@QueryFullText(options)`                            | 全文搜索查询，只支持 PostgreSQL，会自动建索引                    |
-
----
-
-### 全文搜索
+Start the Nest app, and you get:
 
-利用 `@QueryFullText(options)` 装饰器，可以在 PostgreSQL 中实现全文搜索。
+- `POST /users`
+- `GET /users/:id`
+- `GET /users`
+- `PATCH /users/:id`
+- `DELETE /users/:id`
+- Optional `POST /users/import`
 
-程序启动的时候，会自动创建索引。不需要加 `@Index()`。
-
-```ts
-@StringColumn(255)
-@QueryFullText({ 
-  configuration: 'english', // 使用 postgres 搜索配置
-  tsQueryFunction: 'websearch_to_tsquery'// 使用的 tsquery 函数。默认为 websearch_to_tsquery
-  orderBySimilarity: true, // 使用相似度排序
-})
-englishContent: string;
-
-@StringColumn(255)
-@QueryFullText({
-  parser: 'zhparser', // 使用中文分词器。NICOT 自动管理配置。需要手动给 postgres 添加中文分词器
-})
-simpleContent: string;
-```
+Documented in Swagger, with DTOs derived directly from your entity definition.
 
 ---
 
-## 🛠 自定义查询装饰器：`QueryCondition()`
+## Base ID classes: IdBase / StringIdBase
 
-如果你需要构建更复杂或专用的查询逻辑，可以使用 `QueryCondition()` 创建自己的装饰器：
+In NICOT you usually don’t hand-roll primary key fields. Instead you **inherit** one of the base classes.
 
-### 示例：大于查询
+### `IdBase()` — numeric auto-increment primary key
 
 ```ts
-export const QueryGreater = () =>
-  QueryCondition((dto, qb, alias, key) => {
-    if (dto[key] != null) {
-      qb.andWhere(`${alias}.${key} > :${key}`, { [key]: dto[key] });
-    }
-  });
-```
-
-### 示例：动态排序字段（带字段名映射）
-
-```ts
-export const QueryOrderBy = () =>
-  QueryCondition((dto, qb, alias, key) => {
-    const orderValue = dto[key];
-    if (orderValue) {
-      const originalKey = key.replace(/OrderBy$/, '');
-      qb.addOrderBy(`${alias}.${originalKey}`, orderValue);
-    }
-  });
+@Entity()
+export class Article extends IdBase({ description: 'Article ID' }) {
+  // id: number (bigint unsigned, primary, auto-increment)
+}
 ```
 
-> 使用方式与普通装饰器一致，应用在实体字段上即可。
+Behavior:
 
----
+- Adds `id: number` column (`bigint unsigned`, `primary: true`, `Generated('increment')`)
+- Marks it as:
+  - `@NotWritable()` — cannot be written via create/update DTO
+  - `@IntColumn('bigint', { unsigned: true, ... })`
+  - `@QueryEqual()` — usable as `?id=...` in GET queries
+- By default, adds `ORDER BY id DESC` in `applyQuery` (you can override or disable with `noOrderById: true`)
 
-### 使用效果示例
+### `StringIdBase()` — string / UUID primary key
 
 ```ts
-@IntColumn('int', { unsigned: true })
-@QueryGreater()
-views: number;
-
-@StringColumn(255)
-@QueryLike()
-title: string;
-
-@BoolColumn()
-@QueryMatchBoolean()
-isPublished: boolean;
-
-@NotWritable()
-@NotInResult()
-@QueryOrderBy()
-@IsIn(['ASC', 'DESC'])
-@ApiProperty({ enum: ['ASC', 'DESC'], description: 'Order by views' })
-viewsOrderBy?: 'ASC' | 'DESC';
+@Entity()
+export class ApiKey extends StringIdBase({
+  uuid: true,
+  description: 'API key ID',
+}) {
+  // id: string (uuid, primary)
+}
 ```
 
----
+Behavior:
 
-## GetMutator
+- Adds `id: string` column
+- When `uuid: true`:
+  - `@UuidColumn({ primary: true, generated: true, ... })`
+  - `@NotWritable()`
+- When `uuid: false` or omitted:
+  - `@StringColumn(length || 255, { required: true, ... })`
+  - `@IsNotEmpty()` + `@NotChangeable()` (writable only at create time)
+- Default ordering: `ORDER BY id ASC` (can be disabled via `noOrderById`)
 
-GET 方法的参数只能是 URL 参数，因此数据类型只能是 string，具有局限性。
+Summary:
 
-NICOT 提供了 `GetMutator` 装饰器，允许你在实体字段上定义一个转换函数，将 URL 参数转换为正确的数据类型，并把 OpenAPI 文档中 GET 接口的数据类型改为目标类型。
+| Base class        | Type    | Default order | Generation strategy         |
+|-------------------|---------|---------------|-----------------------------|
+| `IdBase()`        | number  | `id DESC`     | auto increment (`bigint`)   |
+| `StringIdBase()`  | string  | `id ASC`      | UUID or manual string       |
 
-### 示例
+---
 
-```ts
-@JsonColumn(SomeObject)
-@GetMutator((val: string) => JSON.parse(val)) // GET 参数不会体现为 SomeObject，而是 string
-@QueryOperator('@>') // JSONB 包含查询
-meta: SomeObject;
-```
+## Column decorators overview
 
-### 内建 GetMutator
+NICOT’s `***Column()` decorators combine:
 
-- `@GetMutatorBool()`
-- `@GetMutatorInt()`
-- `@GetMutatorFloat()`
-- `@GetMutatorStringSeparated(',')`
-- `@GetMutatorIntSeparated()`
-- `@GetMutatorFloatSeparated()`
-- `@GetMutatorJson()`
+- **TypeORM column definition**
+- **class-validator rules**
+- **Swagger `@ApiProperty()` metadata**
 
-> `@BoolColumn()` 已经内建了 `@GetMutatorBool()`
+Common ones:
 
----
+| Decorator            | DB type             | Validation defaults         |
+|----------------------|--------------------|-----------------------------|
+| `@StringColumn(len)` | `varchar(len)`     | `@IsString()`, `@Length()`  |
+| `@TextColumn()`      | `text`             | `@IsString()`               |
+| `@UuidColumn()`      | `uuid`             | `@IsUUID()`                 |
+| `@IntColumn(type)`   | integer types      | `@IsInt()`                  |
+| `@FloatColumn(type)` | float/decimal      | `@IsNumber()`               |
+| `@BoolColumn()`      | `boolean`          | `@IsBoolean()`              |
+| `@DateColumn()`      | `timestamp`/date   | `@IsDate()`                 |
+| `@JsonColumn(T)`     | `jsonb`            | `@IsObject()` / nested val. |
+| `@SimpleJsonColumn`  | `json`             | same as above               |
+| `@StringJsonColumn`  | `text` (stringified JSON) | same as above       |
+| `@EnumColumn(Enum)`  | enum or text       | enum validation             |
 
-## 🧩 实体关系示例
+All of them accept an `options` parameter:
 
 ```ts
-@Entity()
-class Article extends IdBase() {
-  @QueryEqual()
-  @IntColumn('bigint', { unsigned: true })
-  userId: number;
-
-  @ManyToOne(() => User, user => user.articles, { onDelete: 'CASCADE' })
-  user: User;
-}
-
-@Entity()
-class User extends IdBase() {
-  @OneToMany(() => Article, article => article.user)
-  articles: Article[];
-
-  async afterGet() {
-    this.articleCount = this.articles.length;
-  }
-}
+@StringColumn(255, {
+  required: true,
+  description: 'Display name',
+  default: 'Anonymous',
+})
+displayName: string;
 ```
 
 ---
 
-## 🔁 生命周期钩子
+## Access control decorators
 
-支持在实体中定义以下方法：
+These decorators control **where** a field appears:
 
-```ts
-class User {
-  async beforeCreate() {}
-  async afterCreate() {}
-  async beforeUpdate() {}
-  async afterUpdate() {}
-  async beforeGet() {}
-  async afterGet() {}
-
-  isValidInCreate(): string | undefined {
-    return this.name ? undefined : '必须填写名称';
-  }
-}
-```
-
----
+- in create/update DTOs
+- in query DTOs (GET)
+- in response DTOs (`ResultDto`)
 
-## 🛠 使用 CrudService（服务层标准写法）
+### Write / read restrictions
 
-NICOT 提供了 `CrudService(Entity, options)`，是所有资源的标准服务实现方式。
+| Decorator         | Effect on DTOs                                            |
+|-------------------|-----------------------------------------------------------|
+| `@NotWritable()`  | Removed from both Create & Update DTO                    |
+| `@NotCreatable()` | Removed from Create DTO only                             |
+| `@NotChangeable()`| Removed from Update DTO only                             |
+| `@NotQueryable()` | Removed from GET DTO (query params), can’t be used in filters |
+| `@NotInResult()`  | Removed from all response DTOs (including nested relations) |
 
-你只需继承它，并传入对应的实体和配置，即可拥有完整的：
-- 查询（支持分页、排序、过滤、关系）
-- 创建、更新、删除（带钩子、校验、字段控制）
-- 统一返回结构
+### Non-column & virtual fields
 
----
+| Decorator            | Meaning                                                                 |
+|----------------------|-------------------------------------------------------------------------|
+| `@NotColumn()`       | Not mapped to DB; usually set in `afterGet()` as a computed field      |
+| `@QueryColumn()`     | Only exists in query DTO (no DB column), used with `@QueryXXX()`       |
+| `@RelationComputed(() => Class)` | Virtual field that depends on relations; participates in relation pruning |
 
-### 定义 Service
+Example:
 
 ```ts
-import { CrudService } from 'nicot';
+@Entity()
+export class User extends IdBase() {
+  @StringColumn(255, { required: true })
+  name: string;
 
-@Injectable()
-export class ArticleService extends CrudService(Article, {
-  relations: ['user'], // 自动关联 user 实体（LEFT JOIN）
-}) {
-  constructor(@InjectRepository(Article) repo) {
-    super(repo);
-  }
+  @StringColumn(255)
+  @NotInResult()
+  password: string;
 
-  // 可根据需要添加业务方法（非覆盖）
-  async downloadArticle(id: number): Promise<Buffer> {
-    const res = await this.findOne(id);
-    return res.data.getContentAsBuffer();
-  }
+  @DateColumn()
+  @NotWritable()
+  createdAt: Date;
+
+  @NotColumn()
+  @RelationComputed(() => Profile)
+  profileSummary: ProfileSummary;
 }
 ```
 
----
+### Decorator priority (simplified)
 
-### 关于 relations
+When NICOT generates DTOs, it applies a **whitelist/cut-down** pipeline. Roughly:
 
-`relations: string[]` 是 `CrudService` 的核心配置项之一。它用于在查询中自动加载关联实体（即 TypeORM 的 `leftJoinAndSelect`）。
+- **Create DTO omits**:
+  - `@NotColumn`
+  - `@NotWritable`
+  - `@NotCreatable`
+  - factory options: `fieldsToOmit`, `writeFieldsToOmit`, `createFieldsToOmit`
+  - relation fields (TypeORM relations are not part of simple create DTO)
+- **Update DTO omits**:
+  - `@NotColumn`
+  - `@NotWritable`
+  - `@NotChangeable`
+  - factory options: `fieldsToOmit`, `writeFieldsToOmit`, `updateFieldsToOmit`
+- **Query DTO (GET) omits**:
+  - `@NotColumn`
+  - `@NotQueryable`
+  - fields that **require a GetMutator** but do not actually have one
+- **Response DTO (`ResultDto`) omits**:
+  - `@NotInResult`
+  - factory `outputFieldsToOmit`
+  - relation fields that are not in the current `relations` whitelist
 
-- `'user'` 表示加载 `article.user`
-- `'user.articles'` 表示递归加载嵌套关系
-- 默认使用 `LEFT JOIN`，如需 `INNER JOIN` 可通过 `Inner('user')` 指定
+In short:
 
-这能确保你在 Controller 中无需手动构建复杂的 join 查询。
+> If you mark something as “not writable / queryable / in result”, that wins, regardless of column type or other decorators.
 
 ---
 
-### 方法列表
-
-| 方法名           | 说明                                   |
-|------------------|----------------------------------------|
-| `findAll(dto, qb?)` | 查询列表（支持查询装饰器 / 分页）     |
-| `findOne(id, qb?)`  | 查单条数据，自动关联 / 过滤 / 封装     |
-| `create(dto)`       | 创建数据，带验证、钩子处理             |
-| `update(id, dto, extraConditions?)` | 更新数据并支持条件限制 |
-| `delete(id, extraConditions?)`      | 删除数据（软删）         |
+## Query decorators & QueryCondition
 
----
+Query decorators define **how a field is translated into SQL** in GET queries.
 
-### 示例：条件限制用户只能操作自己数据
+Internally they all use a `QueryCondition` callback:
 
 ```ts
-async findOne(id: number, user: User) {
-  return this.service.findOne(id, qb => qb.andWhere('userId = :uid', { uid: user.id }));
-}
-
-async update(id: number, dto: UpdateDto, user: User) {
-  return this.service.update(id, dto, { userId: user.id }); // 附加 where 条件
-}
+export const QueryCondition = (cond: QueryCond) =>
+  Metadata.set(
+    'queryCondition',
+    cond,
+    'queryConditionFields',
+  ) as PropertyDecorator;
 ```
 
----
-
-### 建议实践
-
-- 所有实体的服务类都应继承 `CrudService(Entity, options)`
-- `relations` 是推荐使用的配置方式，替代手动 join
-- 如果你有定制查询逻辑，建议用 `super.findAll(...)` + `.data` 进行后处理
-- 避免直接使用 `repo`，使用封装后的方法保持一致性与钩子逻辑生效
-
----
-
-## 🧩 Controller 自动生成（RestfulFactory）
-
-NICOT 提供了 `RestfulFactory(Entity)` 工厂函数，自动为实体生成标准 RESTful Controller 接口装饰器及参数提取器。
-
-你不再需要手动定义每个路由，只需：
+### Lifecycle in `findAll()` / `findAllCursorPaginated()`
 
-1. 创建 DTO（工厂生成）
-2. 使用工厂提供的装饰器
+When you call `CrudBase.findAll(ent)`:
 
----
-
-### 一键生成的接口说明
+1. NICOT creates a new entity instance.
+2. Copies the DTO into it.
+3. Calls `beforeGet()` (if present) — good place to adjust defaults.
+4. Calls `entity.applyQuery(qb, alias)` — from your base class (e.g. `IdBase` adds `orderBy(id desc)`).
+5. Applies relations joins (`relations` config).
+6. Iterates over all fields with `QueryCondition` metadata and runs the conditions to mutate the `SelectQueryBuilder`.
 
-| 方法                     | 路径                    | 功能说明                  |
-|--------------------------|-------------------------|---------------------------|
-| `@factory.create()`      | `POST /`        | 创建，使用 `createDto`    |
-| `@factory.findOne()`     | `GET /:id`     | 获取单条数据              |
-| `@factory.findAll()`     | `GET /`         | 查询列表，支持过滤 / 分页 |
-| `@factory.update()`      | `PATCH /:id`   | 修改单条数据              |
-| `@factory.delete()`      | `DELETE /:id`  | 删除单条数据（软删）      |
-
----
+So `@QueryXXX()` is a **declarative hook** into the query building stage.
 
-### 参数提取装饰器一览
+### Built-in Query decorators
 
-| 装饰器                     | 用途说明                                |
-|----------------------------|-----------------------------------------|
-| `@factory.createParam()`   | 注入 `createDto`，自动校验 body         |
-| `@factory.updateParam()`   | 注入 `updateDto`，自动校验 body         |
-| `@factory.findAllParam()`  | 注入 `queryDto`，自动校验 query         |
-| `@factory.idParam()`       | 注入路径参数中的 id                     |
-
-这些参数装饰器全部内建了 `ValidationPipe`，支持自动转换与校验。
-
----
+Based on `QueryWrap` / `QueryCondition`:
 
-### 查询能力：基于实体字段的装饰器
+- Simple operators:
+  - `@QueryEqual()`
+  - `@QueryGreater()`, `@QueryGreaterEqual()`
+  - `@QueryLess()`, `@QueryLessEqual()`
+  - `@QueryNotEqual()`
+  - `@QueryOperator('<', 'fieldName?')` for fully custom operators
+- LIKE / search:
+  - `@QueryLike()` (prefix match `field LIKE value%`)
+  - `@QuerySearch()` (contains match `field LIKE %value%`)
+- Boolean handling:
+  - `@QueryMatchBoolean()` — parses `"true" / "false" / "1" / "0"`
+- Arrays / IN:
+  - `@QueryIn()` — `IN (...)`, supports comma-separated strings or arrays
+  - `@QueryNotIn()` — `NOT IN (...)`
+- Null handling:
+  - `@QueryEqualZeroNullable()` — `0` (or `"0"`) becomes `IS NULL`, others `= :value`
+- JSON:
+  - `@QueryJsonbHas()` — Postgres `?` operator on jsonb field
 
-`@factory.findAll()` 所生成的接口具有完整的查询能力，其行为由实体字段上的 `@QueryXXX()` 装饰器控制：
+All of these are high-level wrappers over the central abstraction:
 
 ```ts
-@StringColumn(255)
-@QueryEqual()
-name: string;
-
-@BoolColumn()
-@QueryMatchBoolean()
-isActive: boolean;
+export const QueryWrap = (wrapper: QueryWrapper, field?: string) =>
+  QueryCondition((obj, qb, entityName, key) => {
+    // ...convert obj[key] and call qb.andWhere(...)
+  });
 ```
 
-则生成的 `GET /resource?name=Tom&isActive=true` 接口会自动构建对应的 SQL 条件。
+### Composing conditions: QueryAnd / QueryOr
 
----
-
-### RestfulFactory 配置项
+You can combine multiple `QueryCondition` implementations:
 
 ```ts
-export interface RestfulFactoryOptions<T> {
-  fieldsToOmit?: (keyof T)[]; // 不出现在任何输入 DTO 中的字段
-  writeFieldsToOmit?: (keyof T)[]; // 不出现在创建与更新 DTO 中的字段
-  createFieldsToOmit?: (keyof T)[]; // 不出现在创建 DTO 中的字段
-  updateFieldsToOmit?: (keyof T)[]; // 不出现在更新 DTO 中的字段
-  findAllFieldsToOmit?: (keyof T)[]; // 不出现在查询 DTO 中的字段
-  outputFieldsToOmit?: (keyof T)[]; // 不出现在任何输出 DTO 中的字段
-  prefix?: string; // 接口的路由前缀
-  keepEntityVersioningDates?: boolean; // 在返回结果中保留实体的 createTime / updateTime 字段
-  entityClassName?: string; // 实体类名称，如果存在同一 Entity 的多个 RestfulFactory 实例时需要指定，避免 OpenAPI 类型冲突
-  relations?: (string | RelationDef)[]; // 关联加载的关系字段，传给 CrudService 的 relations 参数，以及用于生成关系 DTO
-  skipNonQueryableFields?: boolean; // 在查询 DTO 中跳过所有没有 @QueryXXX() 装饰器的字段
-}
+export const QueryAnd = (...decs: PropertyDecorator[]) => { /* ... */ };
+export const QueryOr = (...decs: PropertyDecorator[]) => { /* ... */ };
 ```
 
----
-
-### 示例 Controller
+- `QueryAnd(A, B)` — run both conditions on the same field (AND).
+- `QueryOr(A, B)` — build an `(A) OR (B)` bracket group.
 
-```ts
-const factory = new RestfulFactory(User, { relations: ['articles'] });
-class CreateUserDto extends factory.createDto {}
-class UpdateUserDto extends factory.updateDto {}
-class FindAllUserDto extends factory.findAllDto {}
+These are useful for e.g. multi-column search or fallback logic.
 
-@Controller('user')
-export class UserController {
-  constructor(private readonly service: UserService) {}
+### Full-text search: `QueryFullText`
 
-  @factory.create()
-  async create(@factory.createParam() dto: CreateUserDto) {
-    return this.service.create(dto);
-  }
+PostgreSQL-only helper:
 
-  @factory.findAll()
-  async findAll(@factory.findAllParam() dto: FindAllUserDto) {
-    return this.service.findAll(dto);
-  }
-
-  @factory.findOne()
-  async findOne(@factory.idParam() id: number) {
-    return this.service.findOne(id);
-  }
-
-  @factory.update()
-  async update(@factory.idParam() id: number, @factory.updateParam() dto: UpdateUserDto) {
-    return this.service.update(id, dto);
-  }
-
-  @factory.delete()
-  async delete(@factory.idParam() id: number) {
-    return this.service.delete(id);
-  }
-}
+```ts
+@StringColumn(255)
+@QueryFullText({
+  configuration: 'english',
+  tsQueryFunction: 'websearch_to_tsquery',
+  orderBySimilarity: true,
+})
+content: string;
 ```
 
----
+NICOT will:
 
-### 补充说明
+- On module init, create needed text search configuration & indexes.
+- For queries, generate `to_tsvector(...) @@ websearch_to_tsquery(...)`.
+- Optionally compute a `rank` subject and order by it when `orderBySimilarity: true`.
 
-- 所有路由默认返回统一结构（`GenericReturnMessageDto` / `BlankReturnMessageDto`）
-- 所有参数自动校验，无需手动加 `ValidationPipe`
-- `findAll()` 自动支持分页、排序、模糊查询、布尔匹配等
-- 如果你使用了实体关系（relations），则 `findOne()` / `findAll()` 也自动关联查询
-- 所有的接口都是返回状态码 200。
-- OpenAPI 文档会自动生成，包含所有 DTO 类型与查询参数。
-- Service 需要使用 `CrudService(Entity, options)` 进行标准化实现。
+> **Note:** full-text features are intended for **PostgreSQL**. On other databases they are not supported.
 
 ---
 
-### 导出 DTO 类
+## GetMutator & MutatorPipe
 
-`RestfulFactory` 会自动生成以下 DTO 类：供你导出并在其他的 OpenAPI 装饰器中使用。
+GET query params are **always strings** on the wire, but entities may want richer types (arrays, numbers, JSON objects).
 
-```ts
-const factory = new RestfulFactory(User, {
-  relations: ['articles'],
-});
+NICOT uses:
 
-class CreateUserDto extends factory.createDto {} // 创建用 DTO，在 POST /user 中使用
-class UpdateUserDto extends factory.updateDto {} // 更新用 DTO，在 PATCH /user/:id 中使用
-class FindAllUserDto extends factory.findAllDto {} // 查询用 DTO，在 GET /user 中使用
-class UserResultDto extends factory.entityResultDto {} // 查询结果 DTO，在 GET /user/:id 和 GET /user 中返回
-class UserCreateResultDto extends factory.entityCreateResultDto {} // 创建结果 DTO，在 POST /user 中返回。相比 entityResultDto 省略了间接字段和关系字段
-class UserReturnMessageDto extends factory.entityReturnMessageDto {} // 相当于 ReturnMessageDto(UserResultDto)，在 GET /user 中返回
-class UserCreateReturnMessageDto extends factory.entityCreateReturnMessageDto {} // 相当于 ReturnMessageDto(UserCreateResultDto)，在 POST /user 中返回
-class UserArrayResultDto extends factory.entityArrayResultDto {} // 相当于 PaginatedReturnMessageDto(UserResultDto)，在 GET /user 中返回
-```
+- `@GetMutator(...)` metadata on the entity field
+- `MutatorPipe` to apply the conversion at runtime
+- `PatchColumnsInGet` to adjust Swagger docs for GET DTOs
 
----
+### Concept
 
-### 关系定义
+1. Swagger/OpenAPI for GET shows the field as **string** (or string-based, possibly with example/enum from the mutator).
+2. At runtime, `MutatorPipe` reads the string value and calls your mutator function.
+3. The controller receives a **typed DTO** (e.g. array of numbers, parsed JSON) even though the URL carried strings.
 
-类似于 `CrudService`，`RestfulFactory` 也需要在配置中定义关系字段。语法和 `CrudService` 的 `relations` 参数完全一致。
+### Example
 
 ```ts
-class User extends IdBase() {
-  @OneToMany(() => Article, article => article.user)
-  articles: Article[];
+@JsonColumn(SomeFilterObject)
+@GetMutatorJson()         // parse JSON string from ?filter=...
+@QueryOperator('@>')      // use jsonb containment operator
+filter: SomeFilterObject;
+```
 
-  @OneToMany(() => Comment, comment => comment.user)
-  comments: Comment[];
+Built-in helpers include:
 
-  @OneToMany(() => Like, like => like.users)
-  likes: Like[];
-}
+- `@GetMutatorBool()`
+- `@GetMutatorInt()`
+- `@GetMutatorFloat()`
+- `@GetMutatorStringSeparated(',')`
+- `@GetMutatorIntSeparated()`
+- `@GetMutatorFloatSeparated()`
+- `@GetMutatorJson()`
 
-class Article extends IdBase() {
-  @ManyToOne(() => User, user => user.articles)
-  user: User;
+Internally, `PatchColumnsInGet` tweaks Swagger metadata so that:
 
-  @OneToMany(() => Comment, comment => comment.article)
-  comments: Comment[];
+- Fields with GetMutator are shown as `type: string` (with `example` / `enum` if provided by the mutator metadata).
+- Other queryable fields have their default value cleared (so GET docs don’t misleadingly show defaults).
 
-  @OneToMany(() => Like, like => like.article)
-  likes: Like[];
-}
+And `RestfulFactory.findAllParam()` wires everything together:
 
-class Like extends IdBase() {
-  @ManyToOne(() => User, user => user.likes)
-  user: User;
+- Applies `MutatorPipe` if GetMutators exist.
+- Applies `OmitPipe(fieldsInGetToOmit)` to strip non-queryable fields.
+- Optionally applies `PickPipe(queryableFields)` when `skipNonQueryableFields: true`.
 
-  @ManyToOne(() => Article, article => article.likes)
-  article: Article;
-}
+---
 
-class Comment extends IdBase() {
-  @ManyToOne(() => Article, article => article.comments)
-  article: Article;
+## `skipNonQueryableFields`: only expose explicitly declared query fields
 
-  @ManyToOne(() => User, user => user.articles)
-  user: User;
-}
+By default, `findAllDto` is:
 
-const factory = new RestfulFactory(User, {
-  relations: ['comments', 'articles', 'articles.comments'], // 生成的 DTO 类中，只含有标明的关系字段，而 articles.user 不会被包含
-});
+- Entity fields minus:
+  - `@NotColumn`
+  - TypeORM relations
+  - `@NotQueryable`
+  - fields that require GetMutator but don’t have one
+- Plus `PageSettingsDto`’s pagination fields (`pageCount`, `recordsPerPage`).
 
-class UserResultDto extends factory.entityResultDto {
-  // 生成的 DTO 类中包含 comments, articles, articles.comments 字段
-  // 但是不包含 likes, articles.user, articles.likes 等未声明关系字段
-}
-```
-
-如果你的配套 `CrudService` 不准备加载任何关系，那么可以传入空数组：
+If you want GET queries to accept **only** fields that have `@QueryEqual()` / `@QueryLike()` / `@QueryIn()` etc, use:
 
 ```ts
-const factory = new RestfulFactory(User, {
-  relations: [], // DTO 不包含任何关系字段
+const UserFactory = new RestfulFactory(User, {
+  relations: [],
+  skipNonQueryableFields: true,
 });
 ```
 
-如果不写 `relations`，则默认会尽可能加载所有非 `@NotInResult()` 的关系字段。但现在推荐显式声明需要加载的关系，以避免不必要的 OpenAPI 文档杂乱。
-
-> 这是曾经版本的 nicot (<1.1.9) 的做法。
-
----
-
-### 依赖关系的间接字段
+Effects:
 
-如果你有实体类，某一间接字段（`@NotColumn()`），依赖某个关系字段，那么需要显示声明这个字段。
+- `findAllDto` keeps only fields that:
+  - have a `QueryCondition` (i.e. some `@QueryXXX()` decorator),
+  - and are not in the omit list (`NotQueryable`, `NotColumn`, missing mutator).
+- Swagger query params = exactly those queryable fields.
+- At runtime, `findAllParam()` runs `PickPipe(queryableFields)`, so stray query params are dropped.
 
-```ts
-export class Participant extends IdBase() {
-  @OneToMany(() => Match, match => match.player1)
-  matches1: Match[];
-
-  @OneToMany(() => Match, match => match.player2)
-  matches2: Match[];
-}
-
-export class Match extends IdBase() {
-  @ManyToOne(() => Participant, participant => participant.matches1)
-  player1: Participant;
-  @ManyToOne(() => Participant, participant => participant.matches2)
-  player2: Participant;
-
-  @NotColumn()
-  @RelationComputed(() => Participant) // 声明这个字段依赖于 player1 和 player2 生成，当作关系参与裁剪，避免被拖入 Participant 属性黑洞
-  players: Participant[];
-
-  async afterGet() {
-    this.players = [this.player1, this.player2].filter(s => s);
-  }
-}
-
-const factory = new RestfulFactory(Match, {
-  relations: ['player1', 'player2', 'players'],
-});
-
-class MatchResultDto extends factory.entityResultDto {
-  // 包含 player1, player2, players 字段，但是不包含 player1.matches1, player1.matches2 等间接关系字段
-}
-```
+Mental model:
 
----
+> “If you want a field to be filterable in GET `/users`, you **must** explicitly add a `@QueryXXX()` decorator. Otherwise it’s invisible.”
 
-## 📄 分页查询（自动支持）
+Recommended:
 
-NICOT 的 `findAll()` 方法默认支持分页，**无需你手动声明分页字段**，框架内部已内置分页 DTO 与逻辑。
+- For **admin / multi-tenant APIs** → turn `skipNonQueryableFields: true` ON.
+- For **internal tools / quick debugging** → you can leave it OFF for convenience.
 
 ---
 
-### ✅ 默认分页行为
-
-所有 `findAll()` 查询接口会自动识别以下 query 参数：
+## Pagination
 
-| 参数             | 类型     | 默认值 | 说明                            |
-|------------------|----------|--------|---------------------------------|
-| `pageCount`      | number   | `1`    | 第几页，从 1 开始               |
-| `recordsPerPage` | number   | `25`   | 每页多少条数据                  |
+### Offset pagination (default)
 
-这些字段由框架内置的 `PageSettingsDto` 管理，自动注入到 `findAllParam()` 的 DTO 中，无需你自己定义。
+Every `findAll()` uses **offset pagination** via `PageSettingsDto`:
 
-分页逻辑最终会转化为：
-
-```ts
-qb.take(recordsPerPage).skip((pageCount - 1) * recordsPerPage);
-```
-
----
+- Query fields:
+  - `pageCount` (1-based)
+  - `recordsPerPage` (default 25)
+- Internally:
+  - Applies `.take(recordsPerPage).skip((pageCount - 1) * recordsPerPage)`
 
-### 🔧 如何更改分页行为
+If your entity extends `PageSettingsDto`, it can control defaults by overriding methods like `getRecordsPerPage()`.
 
-分页逻辑由实体继承类中的方法控制（如 `getRecordsPerPage()`），如果你希望关闭分页或调高上限，可以 override 这些方法：
+You can also effectively “disable” pagination for specific entities by returning a large value:
 
 ```ts
 @Entity()
-class LogEntry extends IdBase() {
-  // ...其他字段
+export class LogEntry extends IdBase() {
+  // ...
 
-  override getRecordsPerPage() {
-    return this.recordsPerPage || 99999; // 禁用分页（或返回极大值）
+  getRecordsPerPage() {
+    return this.recordsPerPage || 99999;
   }
 }
 ```
 
-这样处理后，该实体的 `findAll()` 查询将默认返回所有数据。
-
----
-
-### 示例：分页 + 条件查询
-
-```
-GET /user?name=Tom&pageCount=2&recordsPerPage=10
-// 查询第 2 页，每页 10 条，筛选 name = Tom 的用户
-```
-
-你可以在 Controller 中完全不关心这些字段，它们已由 NICOT 自动注入、处理并应用在 QueryBuilder 上。
+### Cursor pagination
 
----
-
-## 🔁 游标分页（Cursor Pagination）
+NICOT also supports **cursor-based pagination** via:
 
-NICOT 支持游标式分页查询（Cursor-based Pagination），相比传统的页码分页，在数据量大、频繁变更或无限滚动的场景中更加稳定可靠。
-
----
+- `CrudBase.findAllCursorPaginated()`
+- `RestfulFactory.findAllCursorPaginatedDto`
+- `entityCursorPaginationReturnMessageDto`
 
-### ✅ 使用方式
-
-定义查询 DTO 时继承工厂生成的游标分页基类：
+Usage sketch:
 
 ```ts
-class FindAllUserCursorDto extends factory.findAllCursorPaginatedDto {}
-```
-
-在 Controller 中，使用以下工厂方法：
+class FindAllUserCursorDto extends UserFactory.findAllCursorPaginatedDto {}
 
-```ts
-@factory.findAllCursorPaginated()
-async findAll(@factory.findAllParam() dto: FindAllUserCursorDto) {
-return this.service.findAllCursorPaginated(dto);
+@UserFactory.findAllCursorPaginated()
+async findAll(
+  @UserFactory.findAllParam() dto: FindAllUserCursorDto,
+) {
+  return this.service.findAllCursorPaginated(dto);
 }
 ```
 
-> ⚠️ 注意：`findAll()` 与 `findAllCursorPaginated()` **不能同时使用**，因为它们会绑定到同一个 GET `/` 路由。请选择其中一种分页模式。
+Notes:
+
+- Offset vs cursor pagination share the same query decorators and entity metadata.
+- You choose one mode per controller route (`paginateType: 'offset' | 'cursor' | 'none'` in `baseController()`).
+- Cursor payload and multi-column sorting behavior are documented in more detail in the API reference.
 
 ---
 
-### 📥 请求字段说明
+## CrudBase & CrudService
 
-| 字段名             | 类型    | 描述                                           |
-|--------------------|---------|------------------------------------------------|
-| `recordsPerPage`   | number  | 每页数据数量，默认 25                          |
-| `paginationCursor` | string  | 上一次请求返回的游标（`nextCursor` 或 `previousCursor`）|
+`CrudBase<T>` holds the core CRUD and query logic:
 
-- 首次请求无需传 `paginationCursor`
-- 后续请求使用返回的游标即可获取上一页或下一页数据
+- `create(ent, beforeCreate?)`
+- `findOne(id, extraQuery?)`
+- `findAll(dto?, extraQuery?)`
+- `findAllCursorPaginated(dto?, extraQuery?)`
+- `update(id, dto, cond?)`
+- `delete(id, cond?)`
+- `importEntities(entities, extraChecking?)`
+- `exists(id)`
+- `onModuleInit()` (full-text index loader for Postgres)
 
----
+It honors:
 
-### 📤 返回结构说明
+- Relations configuration (`relations` → joins + DTO shape)
+- `NotInResult` / `outputFieldsToOmit` in responses (`cleanEntityNotInResultFields()`)
+- Lifecycle hooks on the entity:
+  - `beforeCreate` / `afterCreate`
+  - `beforeGet` / `afterGet`
+  - `beforeUpdate` / `afterUpdate`
+  - `isValidInCreate` / `isValidInUpdate` (return a string = validation error)
 
-返回值格式与传统分页一致，但字段不同：
+You usually don’t subclass `CrudBase` directly; instead you use:
 
-```json
-{
-    "statusCode": 200,
-    "success": true,
-    "message": "success",
-    "timestamp": "2025-04-25T12:00:00.000Z",
-    "data": [{}],
-    "nextCursor": "eyJpZCI6MTAwfQ",
-    "previousCursor": "eyJpZCI6NDB9"
+```ts
+export function CrudService<T extends ValidCrudEntity<T>>(
+  entityClass: ClassType<T>,
+  crudOptions: CrudOptions<T> = {},
+) {
+  return class CrudServiceImpl extends CrudBase<T> {
+    constructor(repo: Repository<T>) {
+      super(entityClass, repo, crudOptions);
+    }
+  };
 }
 ```
 
-- 游标格式为 Base64URL 编码（安全可用于 URL 参数）
-- `nextCursor` / `previousCursor` 是可选字段，仅在有下一页或上一页时返回
+And let `RestfulFactory` call this for you via `factory.crudService()`.
 
----
-
-### 🔐 兼容性说明
-
-- 所有字段控制装饰器（如 `@NotInResult()`, `@QueryEqual()`, `@NotQueryable()` 等）在游标分页中同样生效
-- 查询参数仍来自实体声明，Swagger 自动生成文档
-- 无需变更现有实体结构，只需更换 `findAllDto` 和分页调用方法
+> You can still use TypeORM’s repository methods directly in **custom business methods**, but when you do, entity lifecycle hooks (`beforeGet()`, `afterGet()`, etc.) are not automatically applied. For NICOT-managed resources, prefer going through `CrudBase` when you want its behavior.
 
 ---
 
-### ✅ 适用场景
+## RestfulFactory: DTO & Controller generator
 
-- 无限滚动分页加载（如微博、时间线）
-- 数据频繁变动（传统分页页数易错）
-- 前后端希望避免“总页数”等全表统计带来的性能消耗
-
----
+`RestfulFactory<T>` is the heart of “entity → DTOs → controller decorators” mapping.
 
-### 🧪 示例请求
+### Options
 
-```http
-GET /user?recordsPerPage=20&paginationCursor=eyJpZCI6MTAwfQ
+```ts
+interface RestfulFactoryOptions<T> {
+  fieldsToOmit?: (keyof T)[];
+  writeFieldsToOmit?: (keyof T)[];
+  createFieldsToOmit?: (keyof T)[];
+  updateFieldsToOmit?: (keyof T)[];
+  findAllFieldsToOmit?: (keyof T)[];
+  outputFieldsToOmit?: (keyof T)[];
+  prefix?: string;
+  keepEntityVersioningDates?: boolean;
+  entityClassName?: string;
+  relations?: (string | RelationDef)[];
+  skipNonQueryableFields?: boolean;
+}
 ```
 
----
-
-### 🛑 注意事项
-
-- 不支持跳页（如 pageCount = 5 这种跳转）
-- 不再返回 `pageCount`、`totalPages` 等字段
-- 若你的 Controller 中已有 `@factory.findAll()`，请不要再使用游标分页版本
+Key ideas:
 
----
+- **relations**: both for:
+  - which relations are eager-loaded and exposed in DTO,
+  - and which joins are added to queries.
+- **outputFieldsToOmit**: extra fields to drop from response DTOs (in addition to `@NotInResult`).
+- **prefix**: extra path prefix for controller decorators (e.g. `v1/users`).
+- **skipNonQueryableFields**: described above.
 
-## 一键生成 Controller
+### Auto-generated DTOs
 
-在一般情况下，可以使用 `factory.baseController()` 生成 RESTful 控制器，自动处理所有 CRUD 接口。
+For a factory:
 
 ```ts
-const factory = new RestfulFactory(User, {
-  relations: ['articles'],
-});
-
-@Controller('user')
-class UserController extends factory.baseController() {
-  constructor(userService: UserService) {
-    super(userService)
-  }
-}
+export const UserFactory = new RestfulFactory(User, { relations: [] });
 ```
 
-这样就可以自动生成所有 CRUD 接口，无需手动编写。
+NICOT gives you:
+
+- `UserFactory.createDto`
+- `UserFactory.updateDto`
+- `UserFactory.findAllDto`
+- `UserFactory.findAllCursorPaginatedDto`
+- `UserFactory.entityResultDto`
+- `UserFactory.entityCreateResultDto`
+- `UserFactory.entityReturnMessageDto`
+- `UserFactory.entityCreateReturnMessageDto`
+- `UserFactory.entityArrayReturnMessageDto`
+- `UserFactory.entityCursorPaginationReturnMessageDto`
 
-### 选项
+Recommended usage:
 
 ```ts
-class UserController extends factory.baseController({
-  pagination: 'offset' // findAll 的分页模式。可以是 'offset', 'cursor', 'none'。默认为 'offset'
-  globalMethodDecorators: [ApiError(404, 'Error')] // 每个方法都添加的装饰器
-  routes: {
-    findOne: {
-      methodDecorators: [] // 本方法的装饰器
-    },
-    import: {
-      enabled: false // 禁用该路由
-    },
-    // ...
-  }
-}) {}
+export class CreateUserDto extends UserFactory.createDto {}
+export class UpdateUserDto extends UserFactory.updateDto {}
+export class FindAllUserDto extends UserFactory.findAllDto {}
+export class UserResultDto extends UserFactory.entityResultDto {}
 ```
 
-> 如果需要覆盖某个方法的实现，请在 `routes` 中设置 `enabled: false`，然后手动实现该方法。
+This keeps types stable and easy to re-use in custom endpoints or guards.
 
-> 如果该 Controller 内任意路由写了 `enabled: true`，那么该 Controller 内只有 `enabled: true` 的路由会被生成。
+### Controller decorators & params
 
----
-
-## 一键生成 CrudService
+Each factory exposes decorators that match CRUD methods:
 
-利用 `factory.crudService()` 生成标准的 CRUD 服务类，自动处理所有 CRUD 接口。效果与 `CrudService(Entity, options)` 类似。
+- `create()` + `createParam()`
+- `findOne()` + `idParam()`
+- `findAll()` / `findAllCursorPaginated()` + `findAllParam()`
+- `update()` + `updateParam()`
+- `delete()`
+- `import()` (`POST /import`)
 
-`relations` 的配置与 `RestfulFactory` 的 `relations` 参数一致，保证 DTO 与查询参数的一致性。
+These decorators stack:
 
-```ts
-const factory = new RestfulFactory(User, {
-  relations: ['articles'],
-});
-
-class UserService extends factory.crudService() {
-  constructor(@InjectRepository(User) repo) {
-    super(repo);
-  }
-}
-```
+- HTTP method + path (optionally prefixed)
+- Swagger operation and response schemas (using the generated DTOs)
+- Validation & transform pipes (through DataPipe / OptionalDataPipe / OmitPipe / MutatorPipe)
 
-推荐在 Entity 文件中定义 `RestfulFactory`，然后在 Service 中使用 `factory.crudService()` 生成服务类，而在 Controller 中使用 `factory.baseController()` 生成控制器。
+Example (revised):
 
 ```ts
-// user.entity.ts
-@Entity()
-export class User extends IdBase() {
-  //
-}
-
-export const UserRestfulFactory = new RestfulFactory(User, {
-  relations: ['articles'], // 自动代入 UserService 和 UserController 的 relations
+// post.factory.ts
+export const PostFactory = new RestfulFactory(Post, {
+  relations: [], // no relations for this resource
 });
 
-// user.service.ts
+// post.service.ts
 @Injectable()
-export class UserService extends UserRestfulFactory.crudService() {
-  constructor(@InjectRepository(User) repo) {
+export class PostService extends PostFactory.crudService() {
+  constructor(@InjectRepository(Post) repo: Repository<Post>) {
     super(repo);
   }
 }
 
-// user.controller.ts
-@Controller('user')
-export class UserController extends UserRestfulFactory.baseController() {
-  constructor(userService: UserService) {
-    super(userService);
-  }
-}
-```
-
-这么做可以真正实现『一处定义，处处使用』，避免了 DTO 与查询参数的重复定义。
-
----
-
-## 📦 统一返回结构与接口注解
+// post.controller.ts
+import { PutUser } from '../common/put-user.decorator';
 
-NICOT 默认提供统一的接口返回格式与 Swagger 自动注解能力，便于前后端标准化对接。
+export class FindAllPostDto extends PostFactory.findAllDto {}
+export class CreatePostDto extends PostFactory.createDto {}
 
----
-
-### ✅ 返回结构 DTO 类型（用于 Swagger 类型标注）
+@Controller('posts')
+export class PostController {
+  constructor(private readonly service: PostService) {}
 
-#### `ReturnMessageDto(EntityClass)`
-
-用于生成带数据的标准返回结构类型（**不是直接返回值**，用于 `@nestjs/swagger`）。
+  @PostFactory.findAll()
+  async findAll(
+    @PostFactory.findAllParam() dto: FindAllPostDto,
+    @PutUser() user: User,
+  ) {
+    return this.service.findAll(dto, qb => {
+      qb.andWhere('post.userId = :uid', { uid: user.id });
+    });
+  }
 
-```json
-{
-  "statusCode": 200,
-  "success": true,
-  "message": "success",
-  "timestamp": "2025-04-25T12:00:00.000Z",
-  "data": {}
+  @PostFactory.create()
+  async create(
+    @PostFactory.createParam() dto: CreatePostDto,
+    @PutUser() user: User,
+  ) {
+    dto.userId = user.id;
+    return this.service.create(dto);
+  }
 }
 ```
 
-#### `BlankReturnMessageDto`
+### `baseController()` shortcut
 
-无数据返回结构的类型（用于 DELETE、UPDATE 等空响应）。
+If you don’t have extra logic, you can generate a full controller class:
 
-```json
-{
-  "statusCode": 200,
-  "success": true,
-  "message": "success"
+```ts
+@Controller('users')
+export class UserController extends UserFactory.baseController({
+  paginateType: 'offset', // 'offset' | 'cursor' | 'none'
+  globalMethodDecorators: [],
+  routes: {
+    import: { enabled: false }, // disable /import
+  },
+}) {
+  constructor(service: UserService) {
+    super(service);
+  }
 }
 ```
 
-#### `PaginatedReturnMessageDto(EntityClass)`
-
-带有分页信息的返回结构类型。
+- If **any** route in `routes` has `enabled: true`, then **only** explicitly enabled routes are generated.
+- Otherwise, all routes are generated except ones marked `enabled: false`.
 
-> EntityClass 会自动变成数组类型。
-
-```json
-{
-  "statusCode": 200,
-  "success": true,
-  "message": "success",
-  "timestamp": "2025-04-25T12:00:00.000Z",
-  "data": [{}],
-  "total": 100,
-  "totalPages": 4,
-  "pageCount": 1,
-  "recordsPerPage": 25
-}
-```
+This is useful for quickly bootstrapping admin APIs, then selectively disabling / overriding certain endpoints.
 
 ---
 
-### 📊 实际返回结构
+## Relations & RelationComputed
 
-- **返回数据：**
+Relations are controlled by:
 
-```ts
-import { GenericReturnMessageDto } from 'nicot';
+- TypeORM decorators on the entity: `@ManyToOne`, `@OneToMany`, etc.
+- NICOT’s `relations` whitelist in:
+  - `RestfulFactory` options
+  - `CrudOptions` for `CrudService` / `CrudBase`
 
-return new GenericReturnMessageDto(200, '操作成功', data);
-```
-
-- **返回空结构：**
+Example:
 
 ```ts
-import { BlankReturnMessageDto } from 'nicot';
+@Entity()
+export class User extends IdBase() {
+  @OneToMany(() => Article, article => article.user)
+  articles: Article[];
+}
 
-return new BlankReturnMessageDto(204, '删除成功');
+@Entity()
+export class Article extends IdBase() {
+  @ManyToOne(() => User, user => user.articles)
+  user: User;
+}
 ```
 
-- **抛出异常结构：**
+If you configure:
 
 ```ts
-throw new BlankReturnMessageDto(404, '未找到资源').toException();
+export const UserFactory = new RestfulFactory(User, {
+  relations: ['articles'],
+});
 ```
 
----
+Then:
 
-### 📚 Swagger 注解装饰器
+- `UserResultDto` includes `articles` but not `articles.user` (no recursive explosion).
+- Query joins `user.articles` when using `findOne` / `findAll`.
 
-NICOT 提供以下装饰器帮助你自动声明接口返回结构，无需手动写复杂的 `@ApiResponse(...)`：
+### Virtual relation: `RelationComputed`
 
-#### `@ApiTypeResponse(EntityClass)`
+Sometimes you want a **computed field** that conceptually depends on relations, but is not itself a DB column.
 
-等价于：
+Example:
 
 ```ts
-@ApiOkResponse({
-  type: ReturnMessageDto(EntityClass),
-  description: '成功响应结构',
-})
-```
-
-#### `@ApiError(code, message)`
-
-等价于：
-
-```ts
-@ApiResponse({
-  status: code,
-  description: message,
-  type: BlankReturnMessageDto,
-})
-```
+@Entity()
+export class Match extends IdBase() {
+  @ManyToOne(() => Participant, p => p.matches1)
+  player1: Participant;
 
----
+  @ManyToOne(() => Participant, p => p.matches2)
+  player2: Participant;
 
-### 示例用法
+  @NotColumn()
+  @RelationComputed(() => Participant)
+  players: Participant[];
 
-```ts
-@Get()
-@ApiTypeResponse(User)
-@ApiError(404, '未找到用户')
-async findOne(@Query() dto: SearchDto) {
-  const user = await this.service.findOne(dto);
-  if (!user) {
-    throw new BlankReturnMessageDto(404, '未找到用户').toException();
+  async afterGet() {
+    this.players = [this.player1, this.player2].filter(Boolean);
   }
-  return new GenericReturnMessageDto(200, '成功', user);
 }
-```
-
----
 
-## 📥 参数解析 + 验证（DataQuery / DataBody）
+export const MatchFactory = new RestfulFactory(Match, {
+  relations: ['player1', 'player2', 'players'],
+});
+```
 
-NICOT 提供便捷装饰器 `@DataQuery()` 与 `@DataBody()`，用于自动完成：
+NICOT will:
 
-- 参数绑定（从 query 或 body）
-- 数据校验（class-validator）
-- 类型转换（`transform: true`）
-- 避免重复书写 ValidationPipe
+- Treat `players` as a “computed relation” for pruning rules.
+- Include `players` in the result DTO, but **not** recursively include all fields from `Participant.matches1`/`matches2` etc.
+- This keeps DTOs from blowing up due to cyclic relations.
 
 ---
 
-### ✅ 装饰器对照说明
+## Unified response shape
 
-| 装饰器         | 等价于标准写法                                                              |
-|----------------|-------------------------------------------------------------------------------|
-| `@DataQuery()` | `@Query(new ValidationPipe({ transform: true }))`           |
-| `@DataBody()`  | `@Body(new ValidationPipe({ transform: true }))`            |
-
-这些装饰器默认启用了：
-- 自动类型转换（如 query string 转 number）
-- 自动剔除未声明字段（`whitelist: true`）
-- 自动抛出校验异常（422）
-
----
-
-### 示例用法
+NICOT uses a uniform wrapper for all responses:
 
 ```ts
-@Get()
-async findAll(@DataQuery() dto: SearchUserDto) {
-  return this.service.findAll(dto);
-}
-
-@Post()
-async create(@DataBody() dto: CreateUserDto) {
-  return this.service.create(dto);
+{
+  statusCode: number;
+  success: boolean;
+  message: string;
+  timestamp?: string;
+  data?: any;
 }
 ```
 
-你无需手动加 `ValidationPipe`，也无需手动处理转换错误或格式校验，NICOT 帮你做好了这一切。
+Types are built via generics:
 
----
-
-## 📊 和同类框架的对比
+- `ReturnMessageDto(Entity)` — single payload
+- `PaginatedReturnMessageDto(Entity)` — with `total`, `totalPages`, etc.
+- `CursorPaginationReturnMessageDto(Entity)` — with `nextCursor`, `previousCursor`
+- `BlankReturnMessageDto` — for responses with no data
 
-在实际开发中，很多框架也提供了 CRUD 接口构建能力，但存在不同程度的痛点。NICOT 从底层设计上解决了这些问题，适合长期维护的中大型后端项目。
-
----
+And correspondingly in `RestfulFactory`:
 
-### ✅ FastAPI / SQLModel（Python）
+- `entityReturnMessageDto`
+- `entityCreateReturnMessageDto`
+- `entityArrayReturnMessageDto`
+- `entityCursorPaginationReturnMessageDto`
 
-- ✅ 代码简洁，自动生成 OpenAPI 文档
-- ❌ 无字段权限控制（不能区分不可写/不可查）
-- ❌ 查询能力不够细致，字段粒度控制弱
-- ❌ DTO 拆分需手动处理，复杂模型重复多
-
-🔹 **NICOT 优势：**
-- 字段级别控制查询/写入/输出行为
-- 自动生成 DTO + 查询 + OpenAPI + 验证
-- 生命周期钩子和逻辑注入更灵活
+You can still build custom endpoints and return these wrappers manually if needed.
 
 ---
 
-### ✅ @nestjsx/crud（NestJS）
-
-- ✅ 快速生成接口
-- ❌ 安全性差：字段查询/排序过于开放
-- ❌ 控制力弱：很难注入逻辑或自定义查询
-- ❌ Swagger 文档支持不完整
+## Best practices
 
-🔹 **NICOT 优势：**
-- 每个字段查询能力需显式声明（不开放默认）
-- 完全类型安全 + 文档自动生成
-- 逻辑钩子、权限注入、返回结构标准化
+- **One factory per entity**, in its own `*.factory.ts` file.  
+  - Keeps entity, factory, service, controller decoupled but aligned.
+- Let **entities own the contract**:
+  - Column types
+  - Validation
+  - Access control (`@NotWritable`, `@NotInResult`, `@NotQueryable`)
+  - Query capabilities (`@QueryXXX`)
+- For list APIs, strongly consider:
+  - `skipNonQueryableFields: true`
+  - `@QueryXXX` only on fields you really want public filtering on.
+- Prefer `CrudService` / `CrudBase` for NICOT-managed resources, so:
+  - lifecycle hooks are honored,
+  - relations + “not in result” logic stay consistent.
+- Use raw TypeORM repository methods only for clearly separated custom flows, and treat them as “outside NICOT”.
 
 ---
 
-### ✅ nestjs-query
-
-- ✅ 支持 GraphQL / REST，类型安全强
-- ❌ 学习曲线陡峭，文档不友好
-- ❌ 查询逻辑复杂，难以上手
-- ❌ 重度依赖 GraphQL 思维模式
-
-🔹 **NICOT 优势：**
-- 更贴合 REST 直觉思维
-- 默认封装，低学习成本
-- 保留足够扩展点，轻松注入业务逻辑
-
----
-
-### ✅ GraphQL
-
-- ✅ 查询自由，前端控制力强
-- ❌ 后端控制弱，权限处理复杂
-- ❌ 易产生过度查询，性能不稳定
-- ❌ 每个字段都必须写解析器，开发成本高
-
-🔹 **NICOT 优势：**
-- 后端主导接口结构，前端只调 REST
-- 查询能力与字段权限完全可控
-- 无需额外解析器，开发更快速
-
----
-
-### ✅ MyBatis-Plus / Hibernate（Java）
-
-- ✅ 成熟，生态强，Java 企业常用
-- ❌ 配置繁杂，样板代码多
-- ❌ 缺乏统一的返回结构与接口注解
-- ❌ 参数校验 / DTO 拆分手动重复
-
-🔹 **NICOT 优势：**
-- 一套装饰器统一字段校验 + ORM + 文档
-- 自动 DTO 拆分，减少重复代码
-- 全自动接口 + 验证 + 注解集成
-
----
-
-### 🏆 框架能力矩阵对比
-
-| 框架                        | 自动接口       | 安全性         | 文档支持       | 类型安全       | 查询控制         | 关系联查支持     | 开发效率       |
-|-----------------------------|----------------|----------------|----------------|----------------|------------------|------------------|----------------|
-| **NICOT**                   | ✅ 全自动       | ✅ 字段级控制   | ✅ 实体即文档   | ✅ 完整类型推导 | ✅ 装饰器精细控制 | ✅ 自动 relations | ✅ 极高         |
-| FastAPI + SQLModel          | ✅ 模型映射生成 | ❌ 缺乏限制     | ✅ 自动生成     | ❌ 运行时类型   | ❌ 查询不受控     | 🟡 手写关系加载   | ✅ 高           |
-| @nestjsx/crud               | ✅ 快速注册     | ❌ 默认全暴露   | ❌ Swagger 不完整 | ✅ Nest 类型系统 | ❌ 全字段可查     | 🟡 需手动配置     | ✅ 快速上手     |
-| nestjs-query                | ✅ 自动暴露接口 | 🟡 DTO 控权限  | 🟡 手动标注文档 | ✅ 强类型推导   | 🟡 灵活但复杂     | ✅ 关系抽象良好   | ❌ 配置繁琐     |
-| GraphQL（code-first）       | ❌ Resolver 必写| ❌ 查询不受控   | ✅ 类型强大     | ✅ 静态推导     | ❌ 查询过度灵活   | ✅ 查询关系强     | ❌ 繁琐/易错     |
-| Hibernate（Java）           | ❌ 需配 Service | 🟡 靠注解控制   | ❌ 文档需插件   | 🟡 Java 泛型弱  | 🟡 XML/HQL 控制   | ✅ JPA 级联支持   | ❌ 模板代码多   |
-| MyBatis-Plus（Java）        | ✅ 注解生成     | ✅ 手写控制     | ❌ 文档缺失     | ❌ 运行期校验   | ❌ 手写 SQL       | ❌ 需 JOIN SQL    | ❌ 重复手写多   |
-| NestJS + TypeORM + 手动 DTO | ❌ 全手写       | ✅ 自由控制     | ✅ 自己写        | ✅ 类型安全     | 🟡 逻辑自己处理   | 🟡 手写 relations | ❌ 重复代码多   |
-
----
-
-NICOT 作为一个 “Entity 驱动” 的框架，在开发体验、安全性、自动化程度之间找到了平衡，真正做到：
-
-> 一份实体定义 → 自动生成完整、安全、文档完备的接口系统
-
-
----
-
-## ✅ 总结
-
-**NICOT = Entity 驱动 + 自动生成的一体化后端框架**，涵盖：
-
-- 实体建模 → 校验规则 → DTO → OpenAPI
-- 自动生成 Controller / Service
-- 灵活字段控制、查询扩展、用户注入、生命周期钩子
-- 内建返回结构、Swagger 注解、守卫装饰器等功能
-
-是构建 NestJS 标准化、低重复、文档完善的后端服务的理想选择。
-
-## LICENSE
+## License
 
 MIT