@gennext/lb-infra 0.3.0 → 0.3.4

package/README.md

@@ -2,24 +2,23 @@
 
 Gennex Technology - LoopBack 4 infrastructure framework.
 
-`@gennext/lb-infra` provides shared base classes, components, helpers, datasources, model mixins, repositories and controller generators for building backend services on top of LoopBack 4.
+`@gennext/lb-infra` cung cấp các lớp cơ sở (base classes), components, helpers, datasources, model mixins, repositories và các controller generator dùng chung để xây dựng các dịch vụ backend chất lượng cao trên nền tảng LoopBack 4.
 
-## Requirements
+---
 
-- Node.js `>= 18`
-- Bun `>= 1.3.2`
-- TypeScript
+## 1. Requirements
 
-Install dependencies from the repository root:
+- **Node.js**: `>= 18`
+- **Bun**: `>= 1.3.2`
+- **TypeScript**
+
+Cài đặt dependencies từ thư mục gốc của repository:
 
 ```bash
 bun install
 ```
 
-## Package Scripts
-
-Run commands from the repository root:
-
+### Các lệnh chạy trong package:
 ```bash
 bun run --filter "@gennext/lb-infra" build
 bun run --filter "@gennext/lb-infra" clean
@@ -28,33 +27,28 @@ bun run --filter "@gennext/lb-infra" lint
 bun run --filter "@gennext/lb-infra" test
 ```
 
-Root shortcut:
-
+Lệnh tắt từ root:
 ```bash
 bun run rebuild:lb-infra
 ```
 
-The build script compiles TypeScript, resolves aliases with `tsc-alias`, then copies runtime assets into `dist`:
-
-- `src/components/authenticate/views`
-- `static`
-- `tsconfig.json` as `dist/tsconfig.base.json`
+---
 
-## CLI
+## 2. CLI
 
-After the package is installed, the `lb-infra` binary can scaffold the default consumer-app folder structure:
+Sau khi cài đặt package, binary `lb-infra` có thể được sử dụng để khởi tạo cấu trúc thư mục mặc định cho dự án consumer-app:
 
 ```bash
 lb-infra init
 ```
 
-Or target another directory:
+Hoặc trỏ tới một thư mục cụ thể:
 
 ```bash
 lb-infra init ./apps/api
 ```
 
-Generated structure:
+Cấu trúc thư mục được sinh ra:
 
 ```text
 src
@@ -72,13 +66,17 @@ src
 public
 ```
 
-The command creates `index.ts` placeholders for TypeScript folders and `.gitkeep` files for asset/proto/migration folders. Existing placeholder files are not overwritten unless `--force` is passed:
+Các file placeholder `index.ts` và `.gitkeep` sẽ được tự động tạo. Sử dụng cờ `--force` để ghi đè các file đã có:
 
 ```bash
 lb-infra init ./apps/api --force
 ```
 
-## Main Imports
+---
+
+## 3. Main Imports & Re-exports
+
+Sử dụng trực tiếp các thành phần chính được cung cấp bởi framework:
 
 ```ts
 import {
@@ -91,7 +89,7 @@ import {
 } from '@gennext/lb-infra';
 ```
 
-LoopBack re-export aliases:
+Sử dụng các alias re-export của LoopBack để đảm bảo đồng bộ phiên bản:
 
 ```ts
 import {inject, injectable, BindingScope} from '@gennext/lb-infra/lb-core';
@@ -100,229 +98,452 @@ import {model, property, repository} from '@gennext/lb-infra/lb-repo';
 import {authenticate, TokenServiceBindings} from '@gennext/lb-infra/lb-auth';
 ```
 
-Optional feature exports:
+Các tính năng tùy chọn:
 
 ```ts
 import {SocketIOComponent} from '@gennext/lb-infra/socket-io';
 import {GrpcServerComponent} from '@gennext/lb-infra/grpc';
 ```
 
-## Project Layout
+---
+
+## 4. Cấu trúc thư mục (Project Layout)
 
 ```text
-src
-├── base          # base application, sequence, models, repositories, controllers
-├── common        # constants, environment keys, shared types
-├── components    # auth, authorize, migration, mail, socket.io, grpc, health check
-├── datasources   # postgres, redis, memory datasources
-├── helpers       # logger, queue, redis, network, crypto, storage, testing
-├── interceptors  # global interceptors
-├── middlewares   # request middleware
-├── migrations    # migration helpers
-├── mixins        # model mixins
-└── utilities     # shared utility functions
+src/
+├── base/         # Các base class cốt lõi (Application, Sequence, Models, Repositories, Controllers, Services)
+├── common/       # Định nghĩa constants, kiểu dữ liệu dùng chung (Types), keys và environments
+├── components/   # Các LoopBack 4 Components cắm ngoài (Auth, Authorize, Mail, Health, v.v.)
+├── datasources/  # Nguồn cấp dữ liệu (Postgres, Redis, In-memory KV)
+├── helpers/      # Các wrapper helper: logger, hàng đợi queue, cryptography, testing, cronjob
+├── interceptors/ # Global Interceptors (ví dụ: Content-Range header)
+├── middlewares/  # Express Middlewares (Request body parser, Request spy)
+├── migrations/   # Script chạy migration cơ sở dữ liệu
+├── mixins/       # TypeScript mixins dùng cho LoopBack Models
+└── utilities/    # Hàm tiện ích (parse data, query helper, format, error handler)
 ```
 
-## Base Application
-
-Use `BaseApplication` when you want full control over configuration:
-
-```ts
-import {BaseApplication} from '@gennext/lb-infra';
-import {ApplicationConfig} from '@gennext/lb-infra/lb-core';
-
-export class MyApplication extends BaseApplication {
-  constructor(options: ApplicationConfig = {}) {
-    super({
-      scope: 'MyApplication',
-      serverOptions: options,
-    });
-  }
-
-  staticConfigure(): void {
-    // Bind components, datasources, repositories, services and controllers.
-  }
+---
 
-  getProjectRoot(): string {
-    return __dirname;
-  }
+## 5. Kiến trúc ứng dụng & Vòng đời (Architecture & Lifecycle)
 
-  validateEnv() {
-    return {result: true};
-  }
+Ứng dụng kế thừa từ `BaseApplication` hoặc `DefaultRestApplication` tuân theo thứ tự khởi động và nạp cấu hình nghiêm ngặt:
 
-  declareModels(): Set<string> {
-    return new Set([]);
-  }
-
-  preConfigure(): void {}
-
-  postConfigure(): void {}
-}
+```text
+  New Application Instance
+             │
+             ▼
+     staticConfigure()
+             │
+             ▼
+       initialize()
+             │
+             ▼
+       validateEnv()
+             │
+             ▼
+      declareModels()
+             │
+             ▼
+      preConfigure()
+             │
+             ▼
+   Loopback Bootstrapping
+             │
+             ▼
+     postConfigure()
+             │
+             ▼
+     Application Ready
 ```
 
-Use `DefaultRestApplication` when you want the standard setup with environment validation, PostgreSQL, in-memory KV datasource, migration component, content-range interceptor and boot options.
+### Chi tiết các lifecycle hooks:
 
-## Models And Mixins
+1. **`staticConfigure()`**: Được gọi đầu tiên trong constructor của `BaseApplication`.
+   - *Khi nào dùng*: Thực hiện bind trực tiếp các giá trị tĩnh, cấu hình component, datasources tĩnh trước khi nạp sequence hay cấu hình động.
+2. **`validateEnv()`**: Được gọi khi initialize.
+   - *Khi nào dùng*: Thực hiện kiểm tra các biến môi trường thông qua `validateEnvironment()` theo schema định sẵn. Nếu trả về `result: false`, ứng dụng sẽ dừng boot ngay lập tức kèm thông tin lỗi chi tiết.
+3. **`declareModels()`**: Được gọi ngay sau kiểm tra môi trường.
+   - *Khi nào dùng*: Đăng ký danh sách các model của consumer app với metadata schema.
+4. **`preConfigure()`**: Chạy trước khi LoopBack thực hiện boot process quét thư mục.
+   - *Khi nào dùng*: Bind cấu hình dynamic, đăng ký interceptors, khai báo global middleware, thiết lập kết nối datasource.
+5. **`postConfigure()`**: Chạy sau khi ứng dụng hoàn tất quá trình boot.
+   - *Khi nào dùng*: Thực hiện các tác vụ khởi tạo muộn, kiểm tra tính sẵn sàng của database hoặc thiết lập lắng nghe hàng đợi (worker).
 
-Common base models:
+---
 
-- `BaseEntity`
-- `BaseKVEntity`
-- `BaseTzEntity`
-- `BaseUserAuditTzEntity`
-- `BaseTextSearchTzEntity`
-- `BaseObjectSearchTzEntity`
-- `BaseSearchableTzEntity`
-- `BaseSoftDeleteTzEntity`
+## 6. Quản lý phụ thuộc (Dependency Graph & DI Binding Keys)
 
-Common mixins:
+Framework chuẩn hóa cách đặt tên binding keys để tránh sử dụng các chuỗi string thô không an toàn thông qua lớp static `BindingKeys`:
 
-- `IdMixin`
-- `TzMixin`
-- `UserAuditMixin`
-- `SoftDeleteModelMixin`
-- `SoftPersistentMixin`
-- `TextSearchMixin`
-- `ObjectSearchMixin`
-- `VectorMixin`
-- `DuplicatableMixin`
-- `DataTypeMixin`
-- `PrincipalMixin`
+- **Datasource bindings**: `datasources.postgres`, `datasources.redis`
+- **Repository bindings**: `repositories.XxxRepository` (được tạo tự động thông qua `BindingKeys.repositoryFor('XxxRepository')`)
+- **Service bindings**: `services.XxxService` (được tạo tự động thông qua `BindingKeys.serviceFor('XxxService')`)
 
-Example:
+### Ví dụ Wire Controller - Service - Repository thông qua `@inject`:
 
 ```ts
-import {BaseUserAuditTzEntity} from '@gennext/lb-infra';
-import {model, property} from '@gennext/lb-infra/lb-repo';
+import {BindingKeys} from '@gennext/lb-infra';
+import {inject, injectable, BindingScope} from '@gennext/lb-infra/lb-core';
 
-@model({
-  settings: {
-    postgresql: {
-      schema: 'public',
-      table: 'user',
-    },
-    strict: true,
-  },
-})
-export class User extends BaseUserAuditTzEntity {
-  @property({type: 'string', required: true})
-  email: string;
+@injectable({scope: BindingScope.SINGLETON})
+export class ProductRepository extends TzCrudRepository<Product> {
+  constructor(
+    @inject('datasources.postgres') dataSource: PostgresDataSource
+  ) {
+    super(Product, dataSource);
+  }
+}
+
+@injectable({scope: BindingScope.TRANSIENT})
+export class ProductService extends BaseCrudService<Product> {
+  constructor(
+    @inject(BindingKeys.repositoryFor('ProductRepository'))
+    protected productRepository: ProductRepository
+  ) {
+    super({ scope: ProductService.name, repository: productRepository });
+  }
 }
 ```
 
-## Repositories
+---
+
+## 7. Hệ thống Models & Mixins
 
-Use the base repositories in `src/base/repositories`:
+Framework cung cấp sẵn các base class tích hợp mixin nhằm tái sử dụng thuộc tính dữ liệu:
 
-- `TzCrudRepository`
-- `SearchableTzCrudRepository`
-- `KVRepository`
+| Base Model Class | Các Mixin tích hợp sẵn | Mục đích / Khi nào nên dùng |
+| :--- | :--- | :--- |
+| `BaseEntity` | Không | Model cơ bản nhất không có ID và audit log |
+| `BaseKVEntity` | Không | Dành cho các cặp dữ liệu dạng Key-Value (chứa trường `payload`) |
+| `BaseTzEntity` | `TzMixin` | Tự động tạo và cập nhật `createdAt`, `modifiedAt` |
+| `BaseUserAuditTzEntity` | `TzMixin`, `UserAuditMixin` | Tự động cập nhật timestamp cùng thông tin user tạo/sửa (`createdBy`, `modifiedBy`) |
+| `BaseTextSearchTzEntity` | `TzMixin`, `TextSearchMixin` | Tự động build trường text search `textSearch` |
+| `BaseObjectSearchTzEntity` | `TzMixin`, `ObjectSearchMixin` | Tự động build trường search JSONB `objectSearch` |
+| `BaseSearchableTzEntity` | `TzMixin`, `TextSearchMixin`, `ObjectSearchMixin` | Model tìm kiếm tổng hợp (cả text và object search) |
+| `BaseSoftDeleteTzEntity` | `TzMixin`, `SoftDeleteModelMixin` | Hỗ trợ xóa mềm (đánh dấu cờ `isDeleted` và `deletedAt`) |
+| `BaseVectorEntity` | `TzMixin`, `VectorMixin` | Hỗ trợ lưu trữ vector embedding (cho tìm kiếm AI / pgvector) |
 
-Example:
+---
+
+## 8. Repository nâng cao
+
+Framework cung cấp lớp `TzCrudRepository` và `SearchableTzCrudRepository` kế thừa từ LoopBack repository gốc nhưng được bổ sung cơ chế xử lý timezone và audit user tự động:
 
 ```ts
 import {PostgresDataSource, TzCrudRepository} from '@gennext/lb-infra';
-import {inject, injectable, BindingScope} from '@gennext/lb-infra/lb-core';
+import {inject} from '@gennext/lb-infra/lb-core';
 
-@injectable({scope: BindingScope.SINGLETON})
-export class UserRepository extends TzCrudRepository<User> {
+export class ProductRepository extends TzCrudRepository<Product> {
   constructor(@inject('datasources.postgres') dataSource: PostgresDataSource) {
-    super(User, dataSource);
+    super(Product, dataSource);
+  }
+
+  // Ví dụ custom query phức tạp (sử dụng Knex query builder của PostgresDataSource)
+  async findActiveProductsWithMinPrice(minPrice: number): Promise<Product[]> {
+    const table = this.modelClass.definition.settings.postgresql.table;
+    const query = this.dataSource
+      .connector!.execute(`SELECT * FROM ${table} WHERE price >= $1 AND is_deleted = false`, [minPrice]);
+    return query;
   }
 }
 ```
 
-## Controller Generators
-
-### CRUD
+---
 
-`defineCrudController` creates standard CRUD routes:
+## 9. Bộ tạo Controller tự động (Controller Generator)
 
-- `GET /`
-- `POST /`
-- `PATCH /`
-- `GET /count`
-- `GET /find-one`
-- `GET /{id}`
-- `PATCH /{id}`
-- `PUT /{id}`
-- `DELETE /{id}`
+Framework cho phép sinh nhanh các route REST chuẩn RESTful chỉ qua cấu hình tùy chọn:
 
-Example:
+### 1. defineCrudController
+Sinh ra các endpoints: `GET /`, `POST /`, `PATCH /`, `GET /count`, `GET /find-one`, `GET /{id}`, `PATCH /{id}`, `PUT /{id}`, `DELETE /{id}`.
 
 ```ts
 import {defineCrudController} from '@gennext/lb-infra';
 import {api} from '@gennext/lb-infra/lb-rest';
 
-const BaseUserController = defineCrudController<User>({
-  entity: User,
-  repository: {name: 'UserRepository'},
+const BaseController = defineCrudController<Product>({
+  entity: Product,
+  repository: {name: 'ProductRepository'},
   controller: {
-    basePath: '/users',
-    readonly: false,
+    basePath: '/products',
+    readonly: false, // Nếu true, chỉ sinh ra các route GET/count/find-one
+    defaultLimit: 100
   },
+  doInjectCurrentUser: true,  // Tự động inject context user vào audit log
+  doDeleteWithReturn: true    // delete trả về object {id}
 });
 
-@api({basePath: '/users'})
-export class UserController extends BaseUserController {}
+@api({basePath: '/products'})
+export class ProductController extends BaseController {
+  // Bạn có thể kế thừa và viết đè hoặc bổ sung custom method tại đây
+}
 ```
 
-When extending generated controllers, keep custom method paths relative to the class base path:
+### 2. defineKVController
+Dành cho mô hình Key-Value lưu vào memory hoặc Redis:
+- Endpoints sinh ra: `GET /{key}`, `POST /{key}`, `DELETE /{key}`.
 
-```ts
-@get('/search')
-search() {}
-```
+### 3. defineRelationCrudController / defineRelationViewController
+Dành cho quan hệ (HasMany, BelongsTo, HasManyThrough). Sinh ra các REST API quản lý mối quan hệ giữa Source và Target model (ví dụ: `POST /users/{id}/posts`, `GET /users/{id}/posts`).
 
-### Key-Value
+---
 
-Use `defineKVController` for `BaseKVEntity` models and key-value repositories:
+## 10. Hướng dẫn thiết kế Custom Controller - Service - Repository
 
-```ts
-@api({basePath: '/sessions'})
-export class SessionController extends defineKVController<Session>({
-  entity: Session,
-  repository: {name: 'SessionRepository'},
-  controller: {
-    basePath: '/sessions',
-    readonly: false,
-  },
-}) {}
-```
+Framework tuân thủ nghiêm ngặt quy tắc phân tách trách nhiệm (Separation of Concerns):
+1. **Model**: Định nghĩa cấu trúc dữ liệu và các mixin.
+2. **Repository**: Thực hiện truy vấn DB qua SQL/Knex.
+3. **Service**: Chứa logic nghiệp vụ, tính toán, gọi API ngoài, điều phối nghiệp vụ.
+4. **Controller**: Xử lý HTTP routing, nhận request, kiểm tra định dạng và gọi Service.
 
-### Relations
+#### Bước 1: Khai báo Model
+```ts
+import {BaseUserAuditTzEntity} from '@gennext/lb-infra';
+import {model, property} from '@gennext/lb-infra/lb-repo';
 
-Use `defineRelationViewController` or `defineRelationCrudController` for relation endpoints:
+@model({
+  settings: {
+    postgresql: {
+      schema: 'public',
+      table: 'order',
+    },
+    strict: true,
+  },
+})
+export class Order extends BaseUserAuditTzEntity {
+  @property({type: 'string', required: true})
+  code: string;
 
-```ts
-@api({basePath: '/users'})
-export class UserPostRelationController extends defineRelationViewController<User, Post>({
-  entities: {source: User, target: Post},
-  relation: {name: 'posts', type: EntityRelations.HAS_MANY},
-  endPoint: 'posts',
-}) {}
+  @property({type: 'number', required: true})
+  amount: number;
+}
 ```
 
-## gRPC Usage Example
+#### Bước 2: Tạo Repository
+```ts
+import {PostgresDataSource, TzCrudRepository} from '@gennext/lb-infra';
+import {inject} from '@gennext/lb-infra/lb-core';
 
-The gRPC module is exported from `@gennext/lb-infra/grpc`.
+export class OrderRepository extends TzCrudRepository<Order> {
+  constructor(
+    @inject('datasources.postgres') dataSource: PostgresDataSource
+  ) {
+    super(Order, dataSource);
+  }
+}
+```
 
-The server flow is:
+#### Bước 3: Tạo Service chứa Business Logic
+```ts
+import {BaseCrudService, BindingKeys} from '@gennext/lb-infra';
+import {inject} from '@gennext/lb-infra/lb-core';
+import {OrderRepository} from '../repositories/order.repository';
+import {Order} from '../models/order.model';
+
+export class OrderService extends BaseCrudService<Order> {
+  constructor(
+    @inject(BindingKeys.repositoryFor('OrderRepository'))
+    private orderRepository: OrderRepository
+  ) {
+    // Gọi constructor của BaseCrudService nhận 1 object { scope, repository }
+    super({ scope: OrderService.name, repository: orderRepository });
+  }
 
-1. Create a `.proto` file.
-2. Create a controller method and decorate it with `@grpcMethod`.
-3. Register the controller with `app.grpcController(...)`.
-4. Configure `GrpcServerKeys.GRPC_OPTIONS`.
-5. Register `GrpcServerComponent`.
+  // Phương thức chứa logic nghiệp vụ đặc thù
+  async createOrderWithValidation(data: Order): Promise<Order> {
+    if (data.amount <= 0) {
+      throw new Error('Order amount must be positive');
+    }
+    // Sử dụng context trống nếu không truyền currentUser
+    return this.orderRepository.create(data, {});
+  }
+}
+```
 
-### Proto File
+#### Bước 4: Tạo Custom Controller
+```ts
+import {BaseController, BindingKeys} from '@gennext/lb-infra';
+import {api, post, requestBody} from '@gennext/lb-infra/lb-rest';
+import {inject} from '@gennext/lb-infra/lb-core';
+import {OrderService} from '../services/order.service';
+import {Order} from '../models/order.model';
+
+@api({basePath: '/orders'})
+export class OrderController extends BaseController {
+  constructor(
+    @inject(BindingKeys.serviceFor('OrderService'))
+    private orderService: OrderService
+  ) {
+    super({scope: OrderController.name});
+  }
 
-Example file: `src/protos/user.proto`
+  @post('/')
+  async create(@requestBody() data: Order): Promise<Order> {
+    try {
+      return await this.orderService.createOrderWithValidation(data);
+    } catch (err) {
+      this.logger.error('Failed to create order: %s', err.message);
+      throw err;
+    }
+  }
+}
+```
 
+---
+
+## 11. Các Components tích hợp sẵn
+
+Framework tích hợp sẵn các LoopBack 4 Components hỗ trợ bootstrap nhanh:
+
+1. **`AuthenticateComponent`**
+   - *Mục đích*: Quản lý phiên đăng nhập và định danh (JWT, Basic, OAuth2).
+   - *Cấu hình*: Bind cấu hình qua `AuthenticateKeys.TOKEN_OPTIONS` và `AuthenticateKeys.REST_OPTIONS`.
+2. **`AuthorizeComponent`**
+   - *Mục đích*: Phân quyền chi tiết người dùng sử dụng Casbin authorization adapter.
+3. **`MigrationComponent`**
+   - *Mục đích*: Quản lý chạy tự động các tệp tin schema migration SQL/TS lúc boot ứng dụng.
+4. **`HealthCheckComponent`**
+   - *Mục đích*: Endpoint `/health` cung cấp thông tin trạng thái hoạt động của hệ thống.
+5. **`MailComponent`**
+   - *Mục đích*: Quản lý gửi mail tích hợp BullMQ để gửi bất đồng bộ qua SMTP / Mailgun.
+6. **`SocketIOComponent`**
+   - *Mục đích*: Quản lý Socket.IO server tích hợp Redis adapter phục vụ phân tán.
+7. **`GrpcServerComponent`**
+   - *Mục đích*: Khởi tạo và khởi chạy gRPC server của hệ thống.
+8. **`CrashReportComponent`**
+   - *Mục đích*: Ghi lại dấu vết lỗi hệ thống sang các bên thứ 3 (Sentry / MT service).
+9. **`StaticAssetComponent`**
+   - *Mục đích*: Hỗ trợ upload, quản lý file và tích hợp với Object Storage (MinIO/S3).
+
+---
+
+## 12. Hệ thống Helpers dùng chung
+
+Các helper cung cấp giao diện API đồng bộ và dễ sử dụng:
+
+* **Logger Helper**:
+  ```ts
+  import {LoggerFactory} from '@gennext/lb-infra';
+  
+  const logger = LoggerFactory.getLogger('CustomScope');
+  logger.info('Message log: %s', 'value');
+  ```
+
+* **Redis Helper**:
+  ```ts
+  import {RedisHelper} from '@gennext/lb-infra';
+  
+  const redis = new RedisHelper({host: '127.0.0.1', port: 6379});
+  await redis.set('key', 'value');
+  ```
+
+* **Queue Helpers**:
+  ```ts
+  // 1. QueueHelper (Hàng đợi trong bộ nhớ)
+  import {QueueHelper} from '@gennext/lb-infra';
+  
+  const inMemoryQueue = new QueueHelper<string>({
+    identifier: 'my-in-memory-queue',
+    onMessage: async ({ queueElement }) => {
+      console.log('Processing:', queueElement.payload);
+    }
+  });
+  await inMemoryQueue.enqueue('task-payload');
+  
+  // 2. BullMQHelper (Hàng đợi Redis-backed)
+  import {BullMQHelper} from '@gennext/lb-infra';
+  import Redis from 'ioredis';
+  
+  const connection = new Redis({ host: '127.0.0.1', port: 6379 });
+  
+  // Client Role: queue (để đẩy job vào hàng đợi)
+  const bullQueue = new BullMQHelper<string>({
+    queueName: 'email-tasks',
+    identifier: 'email-queue-client',
+    role: 'queue',
+    connection,
+  });
+  await bullQueue.queue.add('send-email', 'payload');
+  
+  // Server Role: worker (để xử lý job)
+  const bullWorker = new BullMQHelper<string>({
+    queueName: 'email-tasks',
+    identifier: 'email-worker-server',
+    role: 'worker',
+    connection,
+    onWorkerData: async (job) => {
+      console.log('Processing job data:', job.data);
+    }
+  });
+  ```
+
+* **Crypto Helper**:
+  ```ts
+  import {AES} from '@gennext/lb-infra';
+  
+  const aes = AES.withAlgorithm('aes-256-cbc');
+  const encrypted = aes.encrypt('plain-text', 'secret-key');
+  ```
+
+* **Storage Helper (MinIO)**:
+  ```ts
+  import {MinioHelper} from '@gennext/lb-infra';
+  
+  const storage = new MinioHelper({
+    endPoint: '127.0.0.1',
+    port: 9000,
+    useSSL: false,
+    accessKey: 'minioadmin',
+    secretKey: 'minioadmin',
+  });
+  
+  const files = [{
+    originalname: 'file.txt',
+    mimetype: 'text/plain',
+    buffer: Buffer.from('hello world'),
+    size: 11,
+    encoding: 'utf-8',
+  }];
+  
+  const result = await storage.upload({
+    bucket: 'bucket-name',
+    files,
+  });
+  ```
+
+---
+
+## 13. Cơ chế mở rộng (Extension Point)
+
+Consumer Application có thể mở rộng các chức năng của framework mà không cần sửa mã nguồn gốc bằng các cách sau:
+
+- **Custom Mixins**: Tạo các mixin riêng bằng cách bọc quanh `BaseEntity` hoặc các model hiện có và truyền vào cấu hình của mình.
+- **Custom Components**: Viết các LoopBack component tuân thủ giao diện `Component` của Loopback và cắm vào thông qua `this.component(MyComponent)`.
+- **Custom Datasource**: Đăng ký các Connector mới bằng cách viết các lớp kế thừa `juggler.DataSource`.
+
+---
+
+## 14. Best Practices trong phát triển dự án
+
+1. **Sử dụng Package Aliases**: Luôn dùng `@gennext/lb-infra/lb-core`, `@gennext/lb-infra/lb-rest`, `@gennext/lb-infra/lb-repo` để tránh xung đột phiên bản của các thư viện LoopBack.
+2. **Quản lý Binding Keys đúng cách**: Phân biệt rõ hai loại binding key để tránh lỗi runtime khi gọi `@inject`:
+   - *Với repository/service NỘI BỘ của framework*: Sử dụng các key tĩnh định nghĩa sẵn như `BindingKeys.REPOSITORIES.User`, `BindingKeys.SERVICES.JWTToken`.
+   - *Với repository/service do ứng dụng TỰ TẠO*: Sử dụng các static helper dynamic để sinh key như `BindingKeys.repositoryFor('ProductRepository')` hoặc `BindingKeys.serviceFor('ProductService')`.
+3. **Phân tách tầng logic**: Luôn tuân thủ quy tắc: HTTP validation / Response formatting nằm ở Controller -> Logic xử lý nghiệp vụ ở Service -> Query Database / Transaction ở Repository.
+4. **Không đổi schema đa ngôn ngữ (i18n)**: Lưu trữ các trường đa ngôn ngữ trực tiếp dưới dạng literal text indexable thay vì dynamic path-lookup để tối ưu hiệu năng tìm kiếm Postgres.
+5. **Clamp limit truy vấn**: Luôn sử dụng helper `applyLimit` để đảm bảo hệ thống tự động clamp các limit quá lớn từ client về `App.MAX_QUERY_LIMIT` (giá trị thực tế là `1000`) nhằm tránh lỗi quá tải bộ nhớ.
+
+---
+
+## 15. Hướng dẫn sử dụng gRPC (5 bước)
+
+Module gRPC được xuất từ `@gennext/lb-infra/grpc`. Quy trình triển khai dịch vụ gRPC gồm 5 bước:
+
+### Bước 1: Tạo file định nghĩa Proto
+Tệp: `src/protos/user.proto`
 ```proto
 syntax = "proto3";
-
 package demo;
 
 service UserService {
@@ -336,25 +557,13 @@ message GetUserRequest {
 message GetUserResponse {
   int32 id = 1;
   string email = 2;
-  string fullName = 3;
 }
 ```
 
-### gRPC Controller
-
+### Bước 2: Tạo gRPC Controller
 ```ts
 import {BaseGrpcController, grpcController, grpcMethod} from '@gennext/lb-infra/grpc';
 
-type GetUserRequest = {
-  id: number;
-};
-
-type GetUserResponse = {
-  id: number;
-  email: string;
-  fullName: string;
-};
-
 @grpcController()
 export class UserGrpcController extends BaseGrpcController {
   constructor() {
@@ -366,32 +575,21 @@ export class UserGrpcController extends BaseGrpcController {
     service: 'demo.UserService',
     method: 'GetUser',
   })
-  async getUser(request: GetUserRequest): Promise<GetUserResponse> {
+  async getUser(request: {id: number}): Promise<{id: number; email: string}> {
     return {
       id: request.id,
       email: `user-${request.id}@example.com`,
-      fullName: `User ${request.id}`,
     };
   }
 }
 ```
 
-`service` must match the package and service path loaded from the proto definition. In the example above, `package demo; service UserService` becomes `demo.UserService`.
-
-`method` must match the RPC method name in the proto. If `method` is omitted, the TypeScript method name is used.
-
-### Register Server In Application
-
+### Bước 3: Cấu hình gRPC Options & Register Component
 ```ts
 import {BaseApplication} from '@gennext/lb-infra';
-import {
-  GrpcServerComponent,
-  GrpcServerKeys,
-  IGrpcServerOptions,
-} from '@gennext/lb-infra/grpc';
+import {GrpcServerComponent, GrpcServerKeys, IGrpcServerOptions} from '@gennext/lb-infra/grpc';
 import {ServerCredentials} from '@grpc/grpc-js';
 import {join} from 'node:path';
-
 import {UserGrpcController} from './controllers/user-grpc.controller';
 
 export class MyApplication extends BaseApplication {
@@ -399,92 +597,34 @@ export class MyApplication extends BaseApplication {
     this.bind<IGrpcServerOptions>(GrpcServerKeys.GRPC_OPTIONS).to({
       identifier: 'my-grpc-server',
       protoFolder: join(__dirname, 'protos'),
-      address: process.env.GRPC_ADDRESS ?? '0.0.0.0:50051',
+      address: '0.0.0.0:50051',
       credentials: ServerCredentials.createInsecure(),
     });
 
     this.grpcController(UserGrpcController);
     this.component(GrpcServerComponent);
   }
-
-  getProjectRoot(): string {
-    return __dirname;
-  }
-
-  validateEnv() {
-    return {result: true};
-  }
-
-  declareModels(): Set<string> {
-    return new Set([]);
-  }
-
-  preConfigure(): void {}
-
-  postConfigure(): void {}
 }
 ```
 
-`GrpcServerComponent` starts the gRPC server immediately when the component is registered, except when `RUN_MODE=migrate`. Register gRPC controllers before registering the component so the server can discover them.
-
-### Client Example
-
+### Bước 4: Gọi gRPC Client thông thường
 ```ts
-import * as grpc from '@grpc/grpc-js';
-import * as protoLoader from '@grpc/proto-loader';
 import {initializeGrpcClient} from '@gennext/lb-infra/grpc';
-import get from 'lodash/get';
-import {join} from 'node:path';
+import * as grpc from '@grpc/grpc-js';
 
-type GetUserResponse = {
-  id: number;
-  email: string;
-  fullName: string;
-};
-
-type UserServiceClient = grpc.Client & {
-  GetUser(
-    request: {id: number},
-    callback: (error: grpc.ServiceError | null, response: GetUserResponse) => void,
-  ): void;
-};
-
-const protoPath = join(__dirname, 'protos/user.proto');
-const packageDefinition = protoLoader.loadSync(protoPath);
-const proto = grpc.loadPackageDefinition(packageDefinition);
-
-const UserService = get(proto, 'demo.UserService') as unknown as new (
-  address: string,
-  credentials: grpc.ChannelCredentials,
-  options?: grpc.ClientOptions,
-) => UserServiceClient;
-
-const userClient = initializeGrpcClient<UserServiceClient>({
-  serviceClass: UserService,
+const userClient = initializeGrpcClient<any>({
+  serviceClass: UserService, // UserService loaded from proto
   address: '127.0.0.1:50051',
   credentials: grpc.ChannelCredentials.createInsecure(),
-  autoConnect: true,
-});
-
-userClient.client.GetUser({id: 1}, (error, response) => {
-  if (error) {
-    console.error(error);
-    return;
-  }
-
-  console.log(response);
 });
 ```
 
-### Repository-Style Client
-
-For app code that prefers datasource/repository style, use `GrpcDataSource` and `GrpcRepository`:
-
+### Bước 5: Gọi gRPC dưới dạng Repository-Style
 ```ts
-import * as grpc from '@grpc/grpc-js';
 import {GrpcDataSource, GrpcRepository} from '@gennext/lb-infra/grpc';
+import * as grpc from '@grpc/grpc-js';
 
-const dataSource = new GrpcDataSource<UserServiceClient>({
+const dataSource = new GrpcDataSource<any>({
   dsConfig: {
     host: '127.0.0.1',
     port: 50051,
@@ -493,86 +633,18 @@ const dataSource = new GrpcDataSource<UserServiceClient>({
   },
 });
 
-class UserGrpcRepository extends GrpcRepository<UserServiceClient> {
+class UserGrpcRepository extends GrpcRepository<any> {
   constructor() {
     super({dataSource, scope: UserGrpcRepository.name});
   }
 
-  getUser(id: number): Promise<GetUserResponse> {
+  async getUser(id: number): Promise<any> {
     return new Promise((resolve, reject) => {
-      this.getServiceClient().GetUser({id}, (error, response) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-
+      this.getServiceClient().GetUser({id}, (error: any, response: any) => {
+        if (error) return reject(error);
         resolve(response);
       });
     });
   }
 }
 ```
-
-The current helper examples above use standard unary request/response calls.
-
-## Components
-
-Available components include:
-
-- `AuthenticateComponent`: JWT/basic/oauth2 strategies, auth middleware, token services and auth controller generator.
-- `AuthorizeComponent`: Casbin authorization, role/permission models, adapters, provider and interceptor.
-- `MigrationComponent`: migration model, repository and runtime wiring.
-- `HealthCheckComponent`: application and datasource health checks.
-- `StaticAssetComponent`: MinIO/static asset controllers.
-- `MailComponent`: mail service, template engine, transports and queue executors.
-- `SocketIOComponent`: Socket.IO server/client helpers and Redis adapter support.
-- `GrpcServerComponent`: gRPC server support.
-- `CrashReportComponent`: crash report providers and services.
-
-## Helpers
-
-Important helper groups:
-
-- Logger: `LoggerFactory`, `ApplicationLogger`
-- Redis: `RedisHelper`, `RedisClusterHelper`
-- Queue: `QueueHelper`, `BullMQHelper`, `MQTTClientHelper`
-- Network: HTTP request, TCP, TLS TCP and UDP helpers
-- Crypto: `AES`, `RSA`
-- Storage: `MinioHelper`, `DIContainerHelper`
-- Worker thread helpers
-- Testing helpers
-- `CronHelper`
-
-## Datasources
-
-Built-in datasources:
-
-- `PostgresDataSource`
-- `RedisDataSource`
-- `KvMemDataSource`
-
-Common environment keys are defined in `src/common/environments.ts`, including server, PostgreSQL and datasource settings.
-
-## Development Checklist
-
-Before opening a change:
-
-```bash
-bun run --filter "@gennext/lb-infra" build
-bun run --filter "@gennext/lb-infra" lint
-bun run --filter "@gennext/lb-infra" test
-```
-
-When adding or changing exports:
-
-1. Update `src/index.ts` or the relevant module `index.ts`.
-2. Update `package.json` `exports` when adding a new public subpath.
-3. Build the package.
-4. Verify the consumer app can import the new path.
-
-## Notes For Consumer Apps
-
-- Prefer the package aliases `lb-core`, `lb-rest`, `lb-repo` and `lb-auth` to keep LoopBack dependency versions consistent.
-- Add `@api({basePath: ...})` on the final exported class when using generated controllers.
-- Bind required component options before starting the application, especially authentication token options and auth service bindings.
-- Ensure build output includes copied runtime assets when publishing or packaging.