Hướng dẫn Cơ sở Dữ liệu

Tất cả các dịch vụ BANA dùng chung một cơ sở dữ liệu PostgreSQL duy nhất (nx_seller) với 14 schema có tên chứa 151 thực thể. Các định nghĩa schema nằm trong @nx/core - các package dịch vụ riêng lẻ không định nghĩa bảng riêng.

Tổng quan Schema

Schema	Thực thể	Dịch vụ sở hữu	Mục đích
`helpdesk`	30	helpdesk	Ticket, agent, tag, bình luận, SLA, knowledge base
`public`	26	identity, commerce	Người dùng, vai trò, quyền, merchant, organizer, sản phẩm, danh mục, biến thể, thiết bị, kênh bán hàng, cấu hình
`inventory`	17	inventory	Vị trí kho, mục tồn kho, đơn mua, biến động kho
`sale`	21	sale	Đơn hàng, mục đơn hàng, check, ticket bếp
`invoice`	9	invoice	Hóa đơn, mục hóa đơn, thông tin thuế, tích hợp hóa đơn điện tử
`pricing`	9	pricing	Giá vé, quy tắc giá, chi phí, thuế, kết quả đánh giá giá
`identity`	8	identity	Thông tin xác thực người dùng, định danh, hồ sơ, token xác thực email
`ledger`	8	ledger	Tác vụ tạo ledger, tài liệu được tạo
`finance`	6	finance	Ví, bản ghi giao dịch, danh mục tài chính, tích hợp thanh toán
`tax`	6	taxation	Định nghĩa thuế, nhóm thuế, quy tắc thuế
`licensing`	5	licensing	Chính sách, tính năng chính sách, license, kích hoạt, sự kiện license
`allocation`	4	commerce	Sắp chỗ sự kiện, sơ đồ địa điểm
`outreach`	2	outreach	Yêu cầu, người đăng ký newsletter
`payment`	0	payment	Namespace dự trữ (PaymentIntegration nằm trong schema `finance`)

Tất cả định nghĩa schema nằm trong packages/core/src/models/schemas/{schema}/.

Column Enricher

@nx/core cung cấp các helper định nghĩa cột nhằm chuẩn hóa cấu trúc bảng.

`generateCommonColumnDefs()`

Mặc định cho hầu hết các bảng. Thêm 5 cột:

Cột	Kiểu	Nullable	Mặc định	Ghi chú
`id`	`text`	Không	`crypto.randomUUID()`	Khóa chính; `$defaultFn` mặc định (một schema có thể chọn dùng Snowflake id qua `IdGenerator`)
`created_at`	`timestamp(tz)`	Không	`now()`	Tự động đặt khi insert
`modified_at`	`timestamp(tz)`	Không	`now()`	Tự động cập nhật mỗi lần thay đổi
`deleted_at`	`timestamp(tz)`	Có	-	Đánh dấu soft delete
`metadata`	`jsonb`	Có	-	Metadata linh hoạt

typescript

import { generateCommonColumnDefs } from '../../common';

export const MySchema = publicSchema.table('MyTable', {
  ...generateCommonColumnDefs(),
  name: text('name').notNull(),
});

`generateIdColumnDefs()`

Khi bạn chỉ cần ID mà không cần timestamp:

Tùy chọn	Kiểu cột	Mặc định
`{ id: { dataType: 'string' } }`	`text` PK, `crypto.randomUUID()`	Phổ biến nhất
`{ id: { dataType: 'number' } }`	`integer` PK, `GENERATED ALWAYS AS IDENTITY`	Tự động tăng
`{ id: { dataType: 'big-number' } }`	`bigint` PK, `GENERATED ALWAYS AS IDENTITY`	Chuỗi lớn

`generateTzColumnDefs()`

Cột timestamp với khả năng cấu hình soft-delete:

typescript

// Có soft delete (mặc định)
generateTzColumnDefs({ deleted: { enable: true } })
// → createdAt, modifiedAt, deletedAt

// Không có soft delete
generateTzColumnDefs({ deleted: { enable: false } })
// → chỉ createdAt, modifiedAt

`generateDataTypeColumnDefs()`

Các cột giá trị đa hình cho bảng lưu trữ nhiều kiểu dữ liệu (dùng bởi PolicyFeature):

Cột	Kiểu	Mục đích
`data_type`	`text`	Phân biệt kiểu (ví dụ `'BOOLEAN'`, `'NUMBER'`, `'TEXT'`, `'JSON'`)
`n_value`	`double precision`	Giá trị số
`t_value`	`text`	Giá trị văn bản
`bo_value`	`boolean`	Giá trị boolean
`j_value`	`jsonb`	Giá trị object JSON
`b_value`	`bytea`	Dữ liệu nhị phân

Định nghĩa một Bảng

Theo pattern này trong packages/core/src/models/schemas/{schema}/{entity}/schema.ts:

typescript

import { text, jsonb, index, foreignKey, unique } from 'drizzle-orm/pg-core';
import { generateCommonColumnDefs, isoTimestamp } from '../../common';
import { mySchema } from '../common';

const TABLE_NAME = 'MyEntity';

export const MyEntitySchema = mySchema.table(
  TABLE_NAME,
  {
    ...generateCommonColumnDefs(),
    name: text('name').notNull(),
    status: text('status').notNull().default('activated'),
    parentId: text('parent_id'),
    data: jsonb('data').$type<{ key: string }>(),
  },
  def => [
    index('IDX_MyEntity_status').on(def.status),
    foreignKey({
      columns: [def.parentId],
      foreignColumns: [ParentSchema.id],
      name: 'FK_MyEntity_parentId_Parent_id',
    }).onDelete('cascade'),
    unique('UQ_MyEntity_name').on(def.name),
  ],
);

Export kiểu

Mỗi schema nên export các kiểu đi kèm sau:

typescript

export type TMyEntity = TTableObject<typeof MyEntitySchema>;        // kiểu select
export type TMyEntityPersist = TTableInsert<typeof MyEntitySchema>; // kiểu insert
export const MyEntitySelectSchema = createSelectSchema(MyEntitySchema);
export const MyEntityInsertSchema = createInsertSchema(MyEntitySchema);
export const MyEntityUpdateSchema = MyEntityInsertSchema.partial();

Repository Soft-Deletable

SoftDeletableRepository từ @nx/core bao bọc Drizzle và tự động:

Lọc ra các hàng có deleted_at IS NOT NULL khi gọi find, findOne, findById
Hiện thực deleteById thành UPDATE SET deleted_at = now() (không phải DELETE cứng)

typescript

import { SoftDeletableRepository } from '@nx/core';

@repository({ dataSource: PostgresCoreDataSource, model: MyEntity })
export class MyRepository extends SoftDeletableRepository<
  typeof MyEntitySchema,
  TMyEntity,
  TMyEntityPersist
> {}

Đối với các entity cần xóa cứng (ví dụ LicenseEvent), hãy dùng lớp Repository cơ sở thay thế, và định nghĩa schema với generateTzColumnDefs({ deleted: { enable: false } }).

Transaction

typescript

const tx = await this.repository.beginTransaction();

try {
  // Tất cả các thao tác chia sẻ cùng transaction
  await this.repository.create({ data, options: { transaction: tx } });
  await this.otherRepository.updateById({ id, data, options: { transaction: tx } });
  await tx.commit();
} catch (err) {
  await tx.rollback();
  throw err;
}

Khóa mức hàng để đảm bảo an toàn đồng thời:

typescript

const row = await this.repository.findOne({
  filter: { where: { id } },
  options: {
    transaction: tx,
    lock: { strength: LockStrengths.UPDATE },  // SELECT ... FOR UPDATE
  },
});

Quy trình Migration

Migration được quản lý bởi Drizzle Kit với một wrapper CLI tùy chỉnh trong @nx/core.

Tạo migration

bash

# Một schema
make db-generate schema=public env=development

# Tất cả schema
make db-generate-all env=development

Lệnh này chạy drizzle-kit generate với cấu hình theo schema cụ thể từ packages/core/src/migrations/migrators/{schema}.ts. Các file SQL được tạo nằm trong packages/core/src/migrations/drizzle/{schema}/.

Áp dụng migration

bash

# Một schema
make db-migrate schema=public env=development

# Tất cả schema
make db-migrate-all env=development

# Theo package (cũng chạy seed của package)

# Dạng rút gọn tương đương, mỗi package một target riêng
make db-migrate-identity-dev

db-migrate chạy drizzle-kit migrate để áp dụng các file SQL chưa được áp dụng theo thứ tự. db-migrate-<pkg>-dev cũng chạy các migration seed riêng của package (quyền, cấu hình mặc định).

Migration seed theo từng package

Mỗi package có thể định nghĩa migration seed trong src/migrations/processes/:

typescript

// packages/licensing/src/migrations/processes/licensing-0001-seed-permissions.ts
const migrationProcess: TMigrationProcess = {
  options: { alwaysRun: true },  // áp dụng lại mỗi lần khởi động
  name: __filename.slice(__dirname.length + 1),
  migrateFn: async ({ context: application }) => {
    const permRepo = application.get<PermissionRepository>({ key: 'repositories.PermissionRepository' });
    for (const permission of LicensingPermissions) {
      const existing = await permRepo.findOne({ filter: { where: { code: permission.code } } });
      if (!existing) await permRepo.create({ data: permission });
      else await permRepo.updateById({ id: existing.id, data: permission });
    }
  },
};

Các migration này chạy khi dịch vụ khởi động (qua bootstrapMigration()) hoặc khi bạn gọi bun run migrate:dev.

Cấu trúc cấu hình migration

Mỗi schema có file cấu hình Drizzle riêng:

packages/core/src/migrations/
├── migrators/
│   ├── cli.ts                 # Điểm vào CLI (generate | migrate [--all])
│   ├── public.ts              # Cấu hình drizzle-kit cho schema public
│   ├── identity.ts            # một config mỗi schema (14 cái)
│   ├── pricing.ts
│   ├── allocation.ts
│   ├── sale.ts
│   ├── inventory.ts
│   ├── finance.ts
│   ├── tax.ts
│   ├── payment.ts
│   ├── ledger.ts
│   ├── invoice.ts
│   ├── licensing.ts
│   ├── helpdesk.ts
│   └── outreach.ts
└── drizzle/
    ├── public/                # Các file SQL migration được tạo
    ├── pricing/
    ├── ...

Thêm bảng mới (từng bước)

Tạo file schema trong packages/core/src/models/schemas/{schema}/{entity}/schema.ts
Tạo file model trong packages/core/src/models/schemas/{schema}/{entity}/model.ts
Export từ index của schema trong packages/core/src/models/schemas/{schema}/index.ts
Tạo migration: make db-generate schema={schema} env={env}
Xem lại SQL trong packages/core/src/migrations/drizzle/{schema}/
Áp dụng: make db-migrate schema={schema} env={env}
Tạo repository trong package sở hữu: packages/{package}/src/repositories/
Đăng ký repository trong Application.configureRepositories()

Quy ước Đặt tên

Phần tử	Quy ước	Ví dụ
Tên bảng	PascalCase	`PolicyFeature`
Tên cột	snake_case	`policy_id`, `created_at`
Index	`IDX_{Table}_{column}`	`IDX_License_status`
Foreign key	`FK_{Table}_{column}_{RefTable}_{refColumn}`	`FK_License_policyId_Policy_id`
Unique constraint	`UQ_{Table}_{columns}`	`UQ_Activation_licenseId_fingerprint`
Biến schema	`{name}Schema`	`licensingSchema`

Target Database trong Makefile

Target	Cách dùng
`make db-generate schema=<name> env=<env>`	Tạo SQL cho một schema
`make db-generate-all env=development`	Tạo SQL cho tất cả 14 schema
`make db-migrate schema=<name> env=<env>`	Áp dụng migration cho một schema
`make db-migrate-all env=development`	Áp dụng tất cả migration
`make db-migrate-<pkg>-dev`	Tương tự, dạng target riêng cho từng package (ví dụ: `db-migrate-ledger-dev`)

Tên schema: public, helpdesk, inventory, sale, invoice, pricing, identity, ledger, finance, tax, licensing, allocation, outreach, payment

Trang Liên quan

Trang	Mô tả
Kiến trúc	Ánh xạ schema sang dịch vụ
IGNIS Patterns	Pattern model, repository soft-delete
Hệ thống Build	Tất cả target Makefile `db-*`
Core - Database	ERD chi tiết và tài liệu theo từng schema

Nhà cung cấp

Các loại Hóa đơn

Hướng dẫn Cơ sở Dữ liệu ​

Tổng quan Schema ​

Column Enricher ​

generateCommonColumnDefs() ​

generateIdColumnDefs() ​

generateTzColumnDefs() ​

generateDataTypeColumnDefs() ​

Định nghĩa một Bảng ​

Export kiểu ​

Repository Soft-Deletable ​

Transaction ​

Quy trình Migration ​

Tạo migration ​

Áp dụng migration ​

Migration seed theo từng package ​

Cấu trúc cấu hình migration ​

Thêm bảng mới (từng bước) ​

Quy ước Đặt tên ​

Target Database trong Makefile ​

Trang Liên quan ​

Hướng dẫn Cơ sở Dữ liệu

Tổng quan Schema

Column Enricher

`generateCommonColumnDefs()`

`generateIdColumnDefs()`

`generateTzColumnDefs()`

`generateDataTypeColumnDefs()`

Định nghĩa một Bảng

Export kiểu

Repository Soft-Deletable

Transaction

Quy trình Migration

Tạo migration

Áp dụng migration

Migration seed theo từng package

Cấu trúc cấu hình migration

Thêm bảng mới (từng bước)

Quy ước Đặt tên

Target Database trong Makefile

Trang Liên quan