Xây nền tảng media với NestJS — Part 1: Nền móng, thiết kế CSDL & ACID

media-forge/
├── src/
│   ├── main.ts                 # điểm khởi động
│   ├── app.module.ts           # module gốc, gom các module con
│   ├── config/                 # đọc & kiểm tra biến môi trường
│   ├── common/                 # lớp lỗi, interceptor, decorator dùng chung
│   ├── database/
│   │   ├── data-source.ts      # cấu hình TypeORM
│   │   └── migrations/         # migration sinh ra, commit vào git
│   ├── auth/                   # người dùng, đăng nhập, refresh token
│   ├── media/                  # video, asset
│   ├── job/                    # vòng đời job chuyển mã
│   └── billing/                # sổ cái credit — nơi phần ACID diễn ra
├── docker/
│   └── docker-compose.yml      # chỉ Postgres — redis thêm ở Part 3
├── .env.example
├── tsconfig.json
└── package.json

npx @nestjs/cli new media-forge --package-manager npm --strict
cd media-forge

npm run start:dev
# → Nest application successfully started
# Mở http://localhost:3000 sẽ thấy: Hello World!

# Cấu hình & kiểm tra biến môi trường
npm i @nestjs/config zod
npm i dotenv

# Cơ sở dữ liệu
npm i @nestjs/typeorm typeorm pg

# Kiểm tra dữ liệu đầu vào (DTO)
npm i class-validator class-transformer

rm src/app.controller.ts src/app.controller.spec.ts src/app.service.ts

import { Module } from '@nestjs/common';

@Module({
  imports: [],
  controllers: [],
  providers: [],
})
export class AppModule {}

mkdir -p src/{config,common,database/migrations,auth,media,job,billing}
mkdir -p docker

NODE_ENV=development
PORT=3000

# Khớp với docker/docker-compose.yml ở mục dưới
DATABASE_URL=postgres://forge:forge@localhost:5432/media_forge

cp .env.example .env
echo ".env" >> .gitignore

import { z } from 'zod';

const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url().startsWith('postgres://'),
});

// Kieu SINH RA tu schema — khong viet tay, nen khong the lech nhau.
export type AppConfig = z.infer<typeof configSchema>;

export function validateEnv(raw: Record<string, unknown>): AppConfig {
  const result = configSchema.safeParse(raw);

  if (!result.success) {
    const issues = result.error.issues
      .map((issue) => `  ${issue.path.join('.')}: ${issue.message}`)
      .join('\n');
    throw new Error(`Bien moi truong khong hop le:\n${issues}`);
  }

  return result.data;
}

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { validateEnv } from './configuration';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      // Chay luc khoi dong. Nem loi o day thi app dung han, khong the
      // chay duoc roi moi sap o truy van dau tien.
      validate: validateEnv,
    }),
  ],
})
export class AppConfigModule {}

constructor(private readonly config: ConfigService<AppConfig, true>) {}

// PORT co kieu number — z.coerce da doi chuoi thanh so tu luc khoi dong
const port = this.config.get('PORT', { infer: true });

import { Module } from '@nestjs/common';
import { AppConfigModule } from './config/config.module';

@Module({
  imports: [AppConfigModule],
})
export class AppModule {}

services:
  postgres:
    image: postgres:17-alpine
    container_name: forge-postgres
    environment:
      POSTGRES_USER: forge
      POSTGRES_PASSWORD: forge
      POSTGRES_DB: media_forge
    ports:
      - '5432:5432'
    volumes:
      - forge-pgdata:/var/lib/postgresql/data
    healthcheck:
      # Khong chi doi cong mo — doi Postgres THUC SU san sang nhan truy van
      test: ['CMD-SHELL', 'pg_isready -U forge -d media_forge']
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  forge-pgdata:

docker compose -f docker/docker-compose.yml up -d

# Doi toi khi healthy roi hay chay app
docker compose -f docker/docker-compose.yml ps

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",

    "strict": true,

    // Bốn cờ KHÔNG nằm trong "strict" — đây mới là phần đắt giá
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitOverride": true,

    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,

    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

// 1. Mảng rỗng vẫn trả về giá trị — lỗi kinh điển khi parse input
const ids: string[] = [];
const first: string = ids[0]; // thực tế là undefined lúc chạy

// 2. Gán undefined vào thuộc tính optional: "có key nhưng rỗng" khác "không có key"
interface Opts {
  readonly retries?: number;
}
const o: Opts = { retries: undefined };

// 3. Ghi đè method của lớp cha mà không khai báo — đổi tên ở cha là hỏng lặng lẽ
class BaseWorker {
  handle(): void {}
}
class TranscodeWorker extends BaseWorker {
  handle(): void {} // thiếu từ khoá override
}

// 4. Đọc biến môi trường không tồn tại mà không hề bị cảnh báo
const env: Record<string, string> = {};
const url = env.DATABASE_URL;

probe.ts(3,7):   error TS2322: Type 'string | undefined' is not assignable to type 'string'.
probe.ts(9,7):   error TS2375: Type '{ retries: undefined; }' is not assignable to type 'Opts'
                               with 'exactOptionalPropertyTypes: true'.
probe.ts(16,3):  error TS4114: This member must have an 'override' modifier because it
                               overrides a member in the base class 'BaseWorker'.
probe.ts(21,17): error TS4111: Property 'DATABASE_URL' comes from an index signature,
                               so it must be accessed with ['DATABASE_URL'].

SELECT COALESCE(SUM(delta), 0) AS balance
FROM credit_entries
WHERE user_id = $1;

-- Lịch sử đầy đủ, luôn có sẵn, không cần bảng log riêng:
-- +100  nạp tiền      job_id = NULL
--  -10  chuyển mã     job_id = 'a1b2...'
--  +10  hoàn do lỗi   job_id = 'a1b2...'

queued ──→ processing ──→ completed
              │
              ├──→ failed ──→ queued        (thử lại, tăng attempts)
              └──→ failed                    (hết lượt thử, dừng hẳn)

KHÔNG hợp lệ:  completed → bất kỳ đâu     (đã xong là xong)
               queued    → completed       (bỏ qua xử lý)

import type { DataSourceOptions } from 'typeorm';
import { SnakeNamingStrategy } from './snake-naming.strategy';

// Moi thu KHONG phu thuoc moi truong. Chi thieu duy nhat `url`.
export const sharedOptions = {
  type: 'postgres',
  entities: [__dirname + '/../**/*.entity.{ts,js}'],
  migrations: [__dirname + '/migrations/*.{ts,js}'],
  // Sinh cot snake_case tu thuoc tinh camelCase: passwordHash -> password_hash
  namingStrategy: new SnakeNamingStrategy(),
  // Bat buoc false. Xem canh bao ben duoi.
  synchronize: false,
} satisfies Partial<DataSourceOptions>;

import { DefaultNamingStrategy, NamingStrategyInterface } from 'typeorm';
import { snakeCase } from 'typeorm/util/StringUtils';

export class SnakeNamingStrategy extends DefaultNamingStrategy implements NamingStrategyInterface {
  override tableName(targetName: string, userSpecifiedName: string | undefined): string {
    return userSpecifiedName ?? snakeCase(targetName);
  }

  override columnName(propertyName: string, customName: string | undefined, embeddedPrefixes: string[]): string {
    return snakeCase(embeddedPrefixes.concat(customName ?? propertyName).join('_'));
  }

  override relationName(propertyName: string): string {
    return snakeCase(propertyName);
  }

  override joinColumnName(relationName: string, referencedColumnName: string): string {
    return snakeCase(`${relationName}_${referencedColumnName}`);
  }

  override joinTableName(firstTableName: string, secondTableName: string): string {
    return snakeCase(`${firstTableName}_${secondTableName}`);
  }

  override joinTableColumnName(tableName: string, propertyName: string, columnName?: string): string {
    return snakeCase(`${tableName}_${columnName ?? propertyName}`);
  }
}

import { config } from 'dotenv';
import { DataSource } from 'typeorm';
import { sharedOptions } from './typeorm.options';

config();

const url = process.env['DATABASE_URL'];
if (!url) {
  throw new Error('Thiếu DATABASE_URL — CLI không chạy qua ConfigModule nên phải tự kiểm.');
}

export const AppDataSource = new DataSource({ ...sharedOptions, url });

import {
  Column,
  CreateDateColumn,
  Entity,
  Index,
  JoinColumn,
  ManyToOne,
  PrimaryGeneratedColumn,
} from 'typeorm';
import { User } from '../auth/user.entity';

export type CreditReason = 'topup' | 'transcode' | 'refund';

@Entity('credit_entries')
// Index theo dung truy van se chay nhieu nhat: cong so du cua mot user
@Index(['userId', 'createdAt'])
// Chi muc DUY NHAT tren job_id — dieu kien de thao tac tru tien "binh than"
// o Part 3 (muc 4.2) co gi de ON CONFLICT DO NOTHING khop vao. Loai tru NULL
// vi nap tien/hoan tien khong gan voi job nao ca.
@Index(['jobId'], { unique: true, where: '"job_id" IS NOT NULL' })
export class CreditEntry {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @Column('uuid')
  userId!: string;

  @ManyToOne(() => User, { onDelete: 'CASCADE' })
  @JoinColumn({ name: 'user_id' })
  user!: User;

  // So nguyen, co the am. KHONG dung float cho thu phai cong dung.
  @Column('integer')
  delta!: number;

  @Column({ type: 'varchar', length: 32 })
  reason!: CreditReason;

  // Nap tien thi khong gan voi job nao -> nullable
  @Column({ type: 'uuid', nullable: true })
  jobId!: string | null;

  @CreateDateColumn({ type: 'timestamptz' })
  createdAt!: Date;
}

import {
  Column,
  CreateDateColumn,
  Entity,
  Index,
  JoinColumn,
  ManyToOne,
  PrimaryGeneratedColumn,
  UpdateDateColumn,
} from 'typeorm';
import { Video } from '../media/video.entity';

export const JOB_STATUSES = ['queued', 'processing', 'completed', 'failed'] as const;
export type JobStatus = (typeof JOB_STATUSES)[number];

@Entity('jobs')
// Worker lay job theo trang thai + thu tu vao truoc ra truoc
@Index(['status', 'createdAt'])
export class Job {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @Column('uuid')
  videoId!: string;

  @ManyToOne(() => Video, { onDelete: 'CASCADE' })
  @JoinColumn({ name: 'video_id' })
  video!: Video;

  @Column({ type: 'enum', enum: JOB_STATUSES, default: 'queued' })
  status!: JobStatus;

  @Column({ type: 'integer', default: 0 })
  attempts!: number;

  @Column({ type: 'text', nullable: true })
  error!: string | null;

  // Thieu cot nay thi khong phan biet duoc job dang chay voi job da chet
  @Column({ type: 'timestamptz', nullable: true })
  startedAt!: Date | null;

  @Column({ type: 'timestamptz', nullable: true })
  finishedAt!: Date | null;

  @CreateDateColumn({ type: 'timestamptz' })
  createdAt!: Date;

  @UpdateDateColumn({ type: 'timestamptz' })
  updatedAt!: Date;
}

import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @Column({ type: 'varchar', unique: true })
  email!: string;

  @Column({ type: 'varchar' })
  passwordHash!: string;

  @Column({ type: 'varchar', default: 'free' })
  plan!: string;

  // Dung cho phan quyen o Part 2 (RolesGuard). Dat o day, khong phai them
  // bang mot migration rieng sau nay — so do o tren da cap nhat theo.
  @Column({ type: 'varchar', default: 'user' })
  role!: string;

  @CreateDateColumn({ type: 'timestamptz' })
  createdAt!: Date;
}

import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity('videos')
export class Video {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @Column('uuid')
  userId!: string;

  // Duong dan file tren dia (hoac object storage key) — khong luu noi dung
  // file trong database, chi luu noi tim thay no.
  @Column({ type: 'varchar' })
  originalKey!: string;

  // Ten file goc nguoi dung upload — dung o Part 2 khi hien thi danh sach video.
  @Column({ type: 'varchar', nullable: true })
  originalName!: string | null;

  @Column({ type: 'bigint', nullable: true })
  size!: string | null;

  @Column({ type: 'integer', nullable: true })
  duration!: number | null;

  @CreateDateColumn({ type: 'timestamptz' })
  createdAt!: Date;
}

import { Column, CreateDateColumn, Entity, Index, JoinColumn, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
import { User } from './user.entity';

@Entity('refresh_tokens')
export class RefreshToken {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @ManyToOne(() => User, { onDelete: 'CASCADE' })
  @JoinColumn({ name: 'user_id' })
  user!: User;

  @Column({ name: 'user_id' })
  userId!: string;

  // SHA-256 cua token. Khong bao gio luu ban goc.
  @Index({ unique: true })
  @Column({ name: 'token_hash', length: 64 })
  tokenHash!: string;

  // Ca mot chuoi xoay vong dung chung mot family_id.
  @Index()
  @Column({ name: 'family_id' })
  familyId!: string;

  // null = chua dung. Co gia tri = da dung, dung lai la bao dong.
  @Column({ name: 'used_at', type: 'timestamptz', nullable: true })
  usedAt!: Date | null;

  @Column({ name: 'expires_at', type: 'timestamptz' })
  expiresAt!: Date;

  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
  createdAt!: Date;
}

import { Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppConfigModule } from './config/config.module';
import type { AppConfig } from './config/configuration';
import { sharedOptions } from './database/typeorm.options';

@Module({
  imports: [
    AppConfigModule,
    // forRootAsync: cho ConfigModule san sang roi moi dung ConfigService
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService<AppConfig, true>) => ({
        ...sharedOptions,
        url: config.get('DATABASE_URL', { infer: true }),
        logging: config.get('NODE_ENV', { infer: true }) === 'development',
      }),
    }),
  ],
})
export class AppModule {}

{
  "scripts": {
    "typeorm": "typeorm-ts-node-commonjs -d src/database/data-source.ts",
    "migration:generate": "npm run typeorm -- migration:generate",
    "migration:run": "npm run typeorm -- migration:run",
    "migration:revert": "npm run typeorm -- migration:revert"
  }
}

npm run migration:generate -- src/database/migrations/InitSchema

# → Migration src/database/migrations/1755...-InitSchema.ts has been generated successfully.

export class InitSchema1755000000000 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `CREATE TYPE "public"."jobs_status_enum" AS ENUM('queued','processing','completed','failed')`,
    );
    await queryRunner.query(`CREATE TABLE "credit_entries" (
      "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
      "user_id" uuid NOT NULL,
      "delta" integer NOT NULL,
      "reason" character varying(32) NOT NULL,
      "job_id" uuid,
      "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
      CONSTRAINT "PK_credit_entries" PRIMARY KEY ("id")
    )`);
    // ... cac bang con lai
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    // Duong lui, sinh tu dong theo thu tu nguoc lai
  }
}

npm run migration:run

# → Migration InitSchema1755000000000 has been executed successfully.

docker exec -it forge-postgres psql -U forge -d media_forge -c '\dt'

#              List of relations
#  Schema |      Name       | Type  | Owner
# --------+-----------------+-------+-------
#  public | credit_entries  | table | forge
#  public | jobs            | table | forge
#  public | migrations      | table | forge
#  public | refresh_tokens  | table | forge
#  public | users           | table | forge
#  public | videos          | table | forge

import { BadRequestException, Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { CreditEntry, type CreditReason } from './credit-entry.entity';

@Injectable()
export class BillingService {
  constructor(
    @InjectRepository(CreditEntry)
    private readonly entries: Repository<CreditEntry>,
  ) {}

  async getBalance(userId: string): Promise<number> {
    const row = await this.entries
      .createQueryBuilder('e')
      .select('COALESCE(SUM(e.delta), 0)', 'balance')
      .where('e.user_id = :userId', { userId })
      .getRawOne<{ balance: string }>();

    return Number(row?.balance ?? 0);
  }

  async charge(userId: string, amount: number, reason: CreditReason): Promise<void> {
    // 1. Doc so du
    const balance = await this.getBalance(userId);

    // 2. Kiem tra
    if (balance < amount) {
      throw new BadRequestException('Không đủ credit');
    }

    // 3. Ghi
    await this.entries.insert({ userId, delta: -amount, reason });
  }
}

# Tao user mau truoc — credit_entries co khoa ngoai tro ve users, khong the
# nap tien cho mot id chua ton tai.
docker exec -it forge-postgres psql -U forge -d media_forge -c \
  "INSERT INTO users (id, email, password_hash)
   VALUES ('11111111-1111-1111-1111-111111111111', '[email protected]', 'khong-dung-de-dang-nhap');"

# Nap 50 credit
docker exec -it forge-postgres psql -U forge -d media_forge -c \
  "INSERT INTO credit_entries (user_id, delta, reason)
   VALUES ('11111111-1111-1111-1111-111111111111', 50, 'topup');"

# 10 request DONG THOI, moi cai tru 10
seq 1 10 | xargs -P 10 -I{} curl -s -o /dev/null -w '%{http_code}\n' \
  -X POST http://localhost:3000/billing/charge \
  -H 'Content-Type: application/json' \
  -d '{"userId":"11111111-1111-1111-1111-111111111111","amount":10}'

docker exec -it forge-postgres psql -U forge -d media_forge -c \
  "SELECT SUM(delta) AS balance, COUNT(*) FILTER (WHERE delta < 0) AS so_lan_tru
   FROM credit_entries
   WHERE user_id = '11111111-1111-1111-1111-111111111111';"

import { BadRequestException, Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { DataSource, Repository } from 'typeorm';
import { CreditEntry, type CreditReason } from './credit-entry.entity';

@Injectable()
export class BillingService {
  constructor(
    @InjectRepository(CreditEntry)
    private readonly entries: Repository<CreditEntry>,
    private readonly dataSource: DataSource,
  ) {}

  async getBalance(userId: string): Promise<number> {
    const row = await this.entries
      .createQueryBuilder('e')
      .select('COALESCE(SUM(e.delta), 0)', 'balance')
      .where('e.user_id = :userId', { userId })
      .getRawOne<{ balance: string }>();

    return Number(row?.balance ?? 0);
  }

  async charge(userId: string, amount: number, reason: CreditReason): Promise<void> {
    await this.dataSource.transaction(async (manager) => {
      // Khoa DONG cua user nay. Request thu hai se DUNG o day cho toi khi
      // transaction dau tien commit.
      await manager.query('SELECT id FROM users WHERE id = $1 FOR UPDATE', [userId]);

      const row = await manager
        .createQueryBuilder(CreditEntry, 'e')
        .select('COALESCE(SUM(e.delta), 0)', 'balance')
        .where('e.user_id = :userId', { userId })
        .getRawOne<{ balance: string }>();

      const balance = Number(row?.balance ?? 0);
      if (balance < amount) {
        throw new BadRequestException('Không đủ credit');
      }

      await manager.insert(CreditEntry, { userId, delta: -amount, reason });
    });
  }
}

import { IsIn, IsInt, IsUUID, Min } from 'class-validator';
import type { CreditReason } from './credit-entry.entity';

export class ChargeDto {
  @IsUUID()
  userId!: string;

  @IsInt()
  @Min(1)
  amount!: number;

  @IsIn(['topup', 'transcode', 'refund'])
  reason!: CreditReason;
}

import { Body, Controller, Post } from '@nestjs/common';
import { BillingService } from './billing.service';
import { ChargeDto } from './charge.dto';

@Controller('billing')
export class BillingController {
  constructor(private readonly billing: BillingService) {}

  @Post('charge')
  charge(@Body() dto: ChargeDto) {
    return this.billing.charge(dto.userId, dto.amount, dto.reason);
  }
}

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { CreditEntry } from './credit-entry.entity';
import { BillingController } from './billing.controller';
import { BillingService } from './billing.service';

@Module({
  imports: [TypeOrmModule.forFeature([CreditEntry])],
  controllers: [BillingController],
  providers: [BillingService],
  exports: [BillingService],
})
export class BillingModule {}

import { Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppConfigModule } from './config/config.module';
import type { AppConfig } from './config/configuration';
import { sharedOptions } from './database/typeorm.options';
import { BillingModule } from './billing/billing.module';

@Module({
  imports: [
    AppConfigModule,
    // forRootAsync: cho ConfigModule san sang roi moi dung ConfigService
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService<AppConfig, true>) => ({
        ...sharedOptions,
        url: config.get('DATABASE_URL', { infer: true }),
        logging: config.get('NODE_ENV', { infer: true }) === 'development',
      }),
    }),
    BillingModule,
  ],
})
export class AppModule {}

Khoa bi quan (FOR UPDATE)     - request thu 2 CHO
  + De hieu, de suy luan, khong can retry
  - Giam thong luong khi tranh chap nhieu; co nguy co deadlock neu khoa
    nhieu dong sai thu tu

Muc co lap SERIALIZABLE        - Postgres tu phat hien va HUY
  + Khong can nghi ve khoa
  - Phai viet retry cho loi 40001, va no huy ca transaction da chay gan xong

Khoa lac quan (version column) - kiem tra luc ghi, that bai thi thu lai
  + Thong luong cao khi it tranh chap
  - Hop voi UPDATE mot dong; kho ap cho mo hinh so cai chi INSERT