---
title: "Kiến trúc và cấu trúc mã nguồn"
url: https://phatdev.net/docs/erp-tan-doanh/kien-truc
lang: vi
updated: 2026-10-19
alternate:
  en: https://phatdev.net/en/docs/erp-tan-doanh/kien-truc
markdown: https://phatdev.net/docs/erp-tan-doanh/kien-truc.md
---

# Kiến trúc và cấu trúc mã nguồn

Thuộc bộ tài liệu: [ERP Tân Doanh](https://phatdev.net/docs/erp-tan-doanh.md)

> Ứng dụng, cơ sở dữ liệu, lõi nghiệp vụ và quy ước đặt tên.

## Kiến trúc
Một ứng dụng **Next.js 16** (App Router, Server Components và Server Actions) nói chuyện trực tiếp với **PostgreSQL 16**, đóng gói bằng Docker. Đăng nhập uỷ quyền cho dịch vụ xác thực dùng chung.

**Vì sao PostgreSQL:** lược đồ cần `JSONB`, `timestamptz`, ràng buộc `EXCLUDE USING gist`, trigger chặn sửa sổ, cột sinh, `pg_trgm` và `unaccent`.

## Phân lớp mã nguồn
| Lớp | Vai trò |
|---|---|
| Màn hình (route) | Server Component đọc dữ liệu và kiểm quyền; Server Action cho mọi thao tác ghi |
| Lõi nghiệp vụ | Ghi sổ kho, vòng đời đơn, báo cáo, xác thực và phân quyền, không dính giao diện |
| Giao diện dùng lại | Bảng, form, biểu tượng SVG, theo hệ thống thiết kế Tân Doanh, không dùng emoji |
| Migration | Mỗi tính năng một file đánh số; dựng cơ sở dữ liệu trống thì chạy hết theo thứ tự |

## Quy ước
Thư mục, route và hàm nghiệp vụ đặt tên tiếng Việt không dấu; thuật ngữ kỹ thuật giữ tiếng Anh. Có công thức 8 bước để thêm một tính năng: migration, nghiệp vụ, action, màn hình, menu và quyền, nhãn, kiểm thử, build.

## Tìm kiếm và tốc độ
Danh mục hơn 5.000 sản phẩm tải bản rút gọn xuống trình duyệt để tìm tức khắc không cần hỏi máy chủ; chỉ mục trigram cho tìm gần đúng không dấu; đệm điều hướng giúp bấm tab hiện gần như liền.