Module Backend

Backend gồm 5 module chính, mỗi module quản lý một miền nghiệp vụ riêng biệt.

IAM Module (Identity & Access Management)

Module quản lý xác thực, phân quyền, và quản trị hệ thống.

modules/iam/
├── auth/              # Xác thực
│   ├── strategies/    # JWT strategy, Local strategy
│   ├── guards/        # Auth guard, Roles guard
│   ├── services/      # Login, register, password reset
│   └── decorators/    # @CurrentUser, @Public
├── admin/             # Quản trị
│   ├── users/         # CRUD users, assign roles
│   ├── roles/         # Quản lý roles
│   ├── permissions/   # Quản lý permissions
│   ├── menus/         # Menu hệ thống (dynamic sidebar)
│   ├── settings/      # System settings (SMTP, S3, ...)
│   ├── user-permissions/ # Gán quyền cho user cụ thể
│   └── cache/         # Cache management
├── profile/           # Xem/sửa profile cá nhân
├── account/           # Đổi mật khẩu, cập nhật account
├── upload/            # Upload file lên S3
└── notifications/     # Thông báo realtime (Socket.IO)

Luồng xác thực:

1. User đăng nhập -> nhận JWT access token + refresh token
2. Token lưu trong httpOnly cookies (bảo mật CSRF)
3. Mỗi request gửi kèm cookie -> Guard verify -> cho phép/từ chối
4. Token hết hạn -> tự động refresh bằng refresh token

Commercial Module (Kinh doanh)

Quản lý khách hàng, hợp đồng, và gói dịch vụ.

modules/commercial/
├── customers/          # Khách hàng + brands
├── contracts/          # Hợp đồng (lifecycle: draft -> active -> completed)
└── service-packages/   # Gói dịch vụ mẫu

Domain	Mô tả
Customers	CRUD khách hàng, quản lý brand của từng khách hàng
Contracts	Tạo/duyệt hợp đồng, theo dõi vòng đời hợp đồng
Service Packages	Định nghĩa gói dịch vụ (items, giá, mô tả)

Delivery Module (Vận hành)

Module lớn nhất, quản lý toàn bộ quy trình vận hành dự án.

modules/delivery/
├── projects/               # Dự án
├── operations/             # Sprint, Task, Post (core operations)
│   ├── controllers/
│   ├── services/
│   ├── repositories/
│   └── dto/
├── shooting-sessions/      # Phiên chụp/quay
├── deliverable-services/   # Dịch vụ giao hàng
├── non-billable-requests/  # Yêu cầu không tính phí
└── support-tickets/        # Phiếu hỗ trợ

Domain	Mô tả
Projects	Tạo/quản lý dự án, liên kết với hợp đồng
Operations	Sprint planning, task management, post scheduling
Shooting Sessions	Lịch chụp/quay, phân công crew
Deliverable Services	Theo dõi deliverables theo từng giai đoạn
Non-Billable Requests	Yêu cầu phát sinh ngoài hợp đồng
Support Tickets	Phiếu hỗ trợ từ khách hàng

Finance-Ops Module (Tài chính vận hành)

Quản lý tài chính theo POD và ngân sách quảng cáo.

modules/finance-ops/
├── pods/             # Báo cáo tài chính POD (doanh thu, chi phí)
└── media-budget/     # Ngân sách quảng cáo (category + items)

Organization Module (Tổ chức)

Quản lý cơ cấu nhân sự và tổ chức.

modules/organization/
├── controllers/
│   ├── departments.controller.ts
│   ├── employees.controller.ts
│   ├── positions.controller.ts
│   ├── pods.controller.ts
│   ├── documents.controller.ts
│   └── roles.controller.ts
├── services/
├── repositories/
└── dto/

Domain	Mô tả
Departments	Phòng ban (hỗ trợ cấp bậc cha-con)
Positions	Chức vụ (gắn với phòng ban, hỗ trợ hierarchy)
Employees	Thông tin nhân viên, gắn user với phòng ban
Pods	Nhóm Agile POD (leader + members)
Documents	Tài liệu nhân sự

Cách tạo module mới

Bước 1: Tạo cấu trúc thư mục

# Ví dụ tạo module "reports" trong delivery
mkdir -p apps/backend/src/modules/delivery/reports/{controllers,services,repositories,dto}

Bước 2: Tạo Repository

reports.repository.ts

import { Injectable } from '@nestjs/common';
import { PrismaService } from '@infrastructure/database/prisma.service';

@Injectable()
export class ReportsRepository {
  constructor(private readonly prisma: PrismaService) {}

  async findAll(query: ReportQueryDto) {
    return this.prisma.report.findMany({ where: query.toFilter() });
  }
}

Bước 3: Tạo Service

reports.service.ts

import { Injectable } from '@nestjs/common';
import { ReportsRepository } from '../repositories/reports.repository';

@Injectable()
export class ReportsService {
  constructor(private readonly reportsRepository: ReportsRepository) {}
}

Bước 4: Tạo Controller

reports.controller.ts

import { Controller, Get, UseGuards } from '@nestjs/common';
import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
import { JwtAuthGuard } from '@modules/iam/auth/guards/jwt-auth.guard';

@ApiTags('Reports')
@ApiBearerAuth()
@UseGuards(JwtAuthGuard)
@Controller('reports')
export class ReportsController {
  constructor(private readonly reportsService: ReportsService) {}
}

Bước 5: Đăng ký Module

reports.module.ts

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

@Module({
  controllers: [ReportsController],
  providers: [ReportsService, ReportsRepository],
  exports: [ReportsService],
})
export class ReportsModule {}

Sau đó import ReportsModule vào module cha (vd: DeliveryModule).

Regenerate API

Sau khi thêm endpoint mới, chạy pnpm api:generate để frontend tự động có typed hooks mới.