> ## Documentation Index
> Fetch the complete documentation index at: https://tomotek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Thiết kế Database

## Cấu trúc bảng cốt lõi cho module Quản lý Tồn kho

***

### 1. Bảng `products` - Sản phẩm

| Trường | Kiểu dữ liệu | Mô tả |
| - | - | - |
| `id` | BIGINT | Primary Key |
| `code` | VARCHAR(20) | Mã sản phẩm TỰ ĐỘNG tạo bởi hệ thống, duy nhất |
| `merchant_id` | BIGINT | |
| `name` | VARCHAR(255) | Tên sản phẩm đầy đủ theo quy tắc đặt tên |
| `category` | ENUM | Thức ăn, Vệ sinh, Phụ kiện, Chăm sóc, Đồ chơi, Y tế |
| `min_stock_alert` | INTEGER | Mức tồn kho tối thiểu cảnh báo |
| `status` | ENUM | `active`, `inactive`, `deleted` |
| `created_at`, `updated_at` | TIMESTAMP | |
| `deleted_at` | TIMESTAMP | NULL nếu chưa xóa |

**Index:** `(merchant_id, name)`, `(merchant_id, category)`, `(merchant_id, code)`

**Quy tắc tạo Mã sản phẩm:**

* Định dạng: `PRD-{YYYYMMDD}-{XXXX}`
* Tự động tăng dần theo thời gian tạo sản phẩm
* Duy nhất trên toàn hệ thống
* Không thể sửa đổi sau khi tạo
* Không cần người dùng nhập hay cấu hình

***

### 2. Bảng `stock_batches` - Lô hàng

| Trường | Kiểu dữ liệu | Mô tả |
| - | - | - |
| `id` | BIGINT | Primary Key |
| `batch_code` | VARCHAR(50) | Mã lô hàng TỰ TẠO bởi hệ thống theo định dạng `YYYYMMDD-XXXX` |
| `product_id` | BIGINT | Foreign Key |
| `supplier_batch_code` | VARCHAR(100) | Mã lô hàng của nhà cung cấp (Tùy chọn, không bắt buộc nhập) |
| `imported_at` | DATE | Ngày nhập kho |
| `expired_at` | DATE | Hạn sử dụng |
| `cost_price` | DECIMAL(12,0) | Giá nhập / đơn vị |
| `original_quantity` | INTEGER | Số lượng nhập ban đầu |
| `remaining_quantity` | INTEGER | Số lượng còn lại |
| `status` | ENUM | `active`, `expired`, `closed` |
| `created_at` | TIMESTAMP | |

**Quy tắc:**

* Không bao giờ được xóa dòng này
* `remaining_quantity` chỉ có thể giảm theo thời gian
* Khi `remaining_quantity` = 0 thì tự động chuyển trạng thái `closed`
* **KHÔNG BAO GIỜ** được phép sửa `cost_price` sau khi lô hàng đã được tạo. Nếu nhập giá nhầm phải tạo giao dịch điều chỉnh riêng biệt, không sửa trực tiếp giá nhập lô cũ
* `batch_code` được hệ thống tự động tạo tại thời điểm nhập kho, không cho phép người dùng chỉnh sửa
* Khi tạo sản phẩm lần đầu tiên, thông tin giá nhập sẽ được dùng để tạo lô hàng đầu tiên tự động

***

### 3. Bảng `stock_movement_logs` - Log biến động kho

> Bảng quan trọng nhất, bất biến, không bao giờ được update hay delete

| Trường | Kiểu dữ liệu | Mô tả |
| - | - | - |
| `id` | BIGINT | Primary Key |
| `product_id` | BIGINT | |
| `stock_batch_id` | BIGINT | |
| `movement_type` | ENUM | `IMPORT`, `SALE`, `ADJUSTMENT`, `RETURN`, `EXPIRED` |
| `quantity` | INTEGER | Số lượng biến động (dương = nhập, âm = xuất) |
| `remaining_after` | INTEGER | Số lượng còn lại sau giao dịch này |
| `reference_type` | VARCHAR(50) | Loại tham chiếu: Order, ImportNote, Adjustment |
| `reference_id` | BIGINT | ID tham chiếu |
| `note` | TEXT | Ghi chú lý do |
| `created_at` | TIMESTAMP | |

**Quy tắc bất biến:**

> KHÔNG UPDATE, KHÔNG DELETE, KHÔNG SOFT DELETE. CHỈ CHO PHÉP INSERT.

**Giải thích trường tham chiếu (Reference):**

Hai trường `reference_type` và `reference_id` sử dụng kỹ thuật đa hình (Polymorphism) để truy vết chính xác chứng từ hoặc nghiệp vụ nào đã làm thay đổi số lượng tồn kho:

* **Khách mua hàng:** `reference_type` = `Order`, `reference_id` = ID của Đơn hàng.
* **Nhập kho:** `reference_type` = `ImportNote`, `reference_id` = ID của Phiếu nhập kho.
* **Điều chỉnh thủ công:** `reference_type` = `Adjustment`, `reference_id` = ID của Phiếu điều chỉnh.
  Việc này giúp hệ thống lưu vết minh bạch và Merchant dễ dàng bấm vào xem lại chi tiết nguyên nhân biến động kho.

***

## Quy tắc tính toán

* Số lượng tồn kho hiện tại của sản phẩm = `SUM(stock_batches.remaining_quantity)`
* Giá vốn tồn kho hiện tại = `SUM(stock_batches.remaining_quantity * stock_batches.cost_price)`
* Tổng giá trị xuất kho = Tổng giá trị các lô hàng đã xuất


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.