INTERNAL DEV ONLY SRS TXNG-F07: Nhật ký Sơ chế & Chế biến (WBS 2.28.2 & 2.29.1)

TÀI LIỆU ĐẶC TẢ YÊU CẦU PHẦN MỀM (SRS) ​

HỆ THỐNG: NỀN TẢNG TRUY XUẤT NGUỒN GỐC GOTRACE ​


TXNG-F07 -- Nhật ký Sơ chế – Chế biến – Đóng gói ​

Thông tin Chi tiết
Phiên bản 1.1
Ngày tạo 18/03/2026
Tác giả GoTrace Team
Người review
Người phê duyệt

Lịch sử thay đổi ​

Ngày Người cập nhật Mô tả thay đổi
18/03/2026 GoTrace Team Khởi tạo tài liệu v1.0
13/04/2026 GoTrace Team v1.1 – Bổ sung dấu tiếng Việt toàn bộ, hoàn thiện CTE/KDE, thêm analysis endpoint, bổ sung tham chiếu Kiến trúc SRS F05-F08

1. Tổng quan tài liệu ​

1.1. Mục đích tài liệu ​

Tài liệu này mô tả chi tiết quy trình nghiệp vụ và yêu cầu chức năng của chức năng Nhật ký Sơ chế – Chế biến – Đóng gói (TXNG-F07) trong Module Truy Xuất Nguồn Gốc (TXNG) của hệ thống GoTrace.

Chức năng cho phép Doanh nghiệp/Cơ sở sản xuất ghi nhận toàn bộ quy trình từ nhập nguyên liệu, sơ chế, chế biến, kiểm tra chất lượng, đóng gói đến bảo quản. Hệ thống áp dụng mô hình TransformationEvent (EPCIS) để truy xuất mapping N:N giữa lô nguyên liệu đầu vào và lô thành phẩm đầu ra. Khi đóng gói, hệ thống tự động trigger tạo QR Code (F16) và cấp SSCC cho đơn vị logistic theo TCVN 6754:2007.

Tài liệu là cơ sở cho đội ngũ phát triển (Developer), kiểm thử (QA), và các bên liên quan trong việc hiểu rõ yêu cầu kỹ thuật – nghiệp vụ.

Tham chiếu kiến trúc: Tài liệu này tuân theo kiến trúc Hybrid (Shared Shell + Plugins) được định nghĩa tại SRS_TXNG-F05-F08_Kien_Truc_Nhat_Ky_San_Xuat.md. Các thành phần dùng chung (Shell), Plugin riêng (F07), và quy ước kỹ thuật cần đối chiếu với tài liệu kiến trúc tổng thể.

1.2. Thông tin chức năng ​

Thuộc tính Giá trị
Mã chức năng TXNG-F07
Tên chức năng Nhật ký Sơ chế – Chế biến – Đóng gói
Menu TXNG > Nhật ký Sản xuất > Sơ chế – Chế biến – Đóng gói
Ưu tiên Bắt buộc
Giai đoạn v1.0
Pháp lý TCVN 12850:2019 (CTE/KDE), TCVN 6754:2007 (SSCC), TCVN 13274:2020 (Mã truy vết), TCVN 13275:2020 (Vật mang dữ liệu)
Liên thông <- TXNG-F05 (Nhật ký Trồng trọt – nguồn nguyên liệu từ cây)
<- TXNG-F06 (Nhật ký Chăn nuôi – nguồn nguyên liệu từ vật nuôi)
-> TXNG-F08 (Nhật ký Phân phối – Vận chuyển)
-> TXNG-F16 (Cấp mã QR Code khi đóng gói)
-> TXNG-F09 (Quản lý Lô mã)
Kiến trúc -> SRS_TXNG-F05-F08 (Kiến trúc Hệ thống Nhật ký Sản xuất)

1.3. Tác nhân tham gia (Actors) ​

Actor Vai trò Quyền hạn
ENTERPRISE_ADMIN Quản trị viên Doanh nghiệp Full CRUD lệnh sản xuất, sự kiện CTE, cấp SSCC, xóa
ENTERPRISE_USER Nhân viên sản xuất / QC Tạo/sửa lệnh SX và sự kiện CTE do mình tạo, không xóa
SO_ADMIN Quản trị viên Sở Chỉ xem (read-only), không thấy nút tạo/sửa/xóa
SYSTEM Hệ thống tự động Tự động tính HSD, cấp SSCC, trigger QR Code (F16), ghi audit log

1.4. Tham chiếu UI/UX ​

Tài liệu Link
Mockup (đính kèm link/attach file)
Design (đính kèm link/attach file)

2. Luồng nghiệp vụ (Business Flow) ​

2.1. Luồng nghiệp vụ tổng quan ​

+------------------------------------------------------------------------+
|           LUỒNG SƠ CHẾ – CHẾ BIẾN – ĐÓNG GÓI (F07)                   |
+------------------------------------------------------------------------+
|                                                                        |
|  [F05/F06]         CTE-PROC-01           CTE-PROC-02                  |
|  Lô thu hoạch  --> Nhập nguyên liệu  --> Sơ chế                      |
|  Lô xuất chuồng    (Intake)              (Rửa, phân loại, cắt)       |
|       |                |                       |                       |
|       |                v                       v                       |
|       |         +-------------+         +-------------+                |
|       |         | Kiểm tra    |         | Ghi nhận    |                |
|       |         | nguồn gốc   |         | hao hụt,    |                |
|       |         | lô NL (N:N) |         | phụ phẩm    |                |
|       |         +-------------+         +-------------+                |
|       |                                        |                       |
|       |                                        v                       |
|       |                                  CTE-PROC-03                   |
|       |                                  Chế biến                      |
|       |                                  (Nấu, trộn, lên men)          |
|       |                                        |                       |
|       |                                        v                       |
|       |                                  CTE-PROC-04                   |
|       |                                  Kiểm tra chất lượng (QC)      |
|       |                                  (Trước đóng gói)              |
|       |                                   |           |                |
|       |                              [ĐẠT]             [KHÔNG ĐẠT]     |
|       |                                |                    |          |
|       |                                v                    v          |
|       |                          CTE-PROC-05          Xử lý lại /     |
|       |                          Đóng gói             Loại bỏ          |
|       |                          (Trigger QR F16)                      |
|       |                          (Cấp SSCC)                            |
|       |                                |                               |
|       |                                v                               |
|       |                          CTE-PROC-06                           |
|       |                          Bảo quản                              |
|       |                          (Cold chain / Ambient)                |
|       |                                |                               |
|       |                                v                               |
|       |                          [F08: Phân phối]                      |
|       |                          [F09: Quản lý Lô]                     |
+------------------------------------------------------------------------+
|  TransformationEvent (EPCIS):                                          |
|  Input lots (A + B) --> Output lot (C)   [Traceable N:N]               |
+------------------------------------------------------------------------+

2.2. Diễn giải luồng ​

Bước Mô tả hành động Hệ thống thực hiện
B1 DN Admin/User tạo Lệnh sản xuất (Processing Order) Hệ thống tạo lệnh với mã tự động PO-{YYYYMMDD}-{SEQ}, trạng thái DRAFT
B2 Ghi nhận CTE-PROC-01: Nhập nguyên liệu Chọn lô thu hoạch (F05) hoặc lô xuất chuồng (F06). Mapping N:N nguyên liệu -> lệnh SX. Validate nguồn gốc
B3 Ghi nhận CTE-PROC-02: Sơ chế Ghi nhận hoạt động rửa, phân loại, cắt. Cập nhật khối lượng sau sơ chế, hao hụt
B4 Ghi nhận CTE-PROC-03: Chế biến Ghi nhận quy trình nấu, trộn, lên men. Nhiệt độ, thời gian, phụ gia
B5 Ghi nhận CTE-PROC-04: Kiểm tra chất lượng Ghi kết quả QC: ĐẠT / KHÔNG_ĐẠT. Nếu KHÔNG_ĐẠT -> xử lý lại hoặc loại bỏ
B6 Ghi nhận CTE-PROC-05: Đóng gói Tạo lô thành phẩm (output lot). Tự động tính HSD = ngày SX + shelf life. Trigger F16 tạo QR Code. Cấp SSCC cho đơn vị logistic
B7 Ghi nhận CTE-PROC-06: Bảo quản Ghi điều kiện bảo quản (nhiệt độ, độ ẩm). Liên kết kho (F19)
B8 Hoàn thành lệnh sản xuất Chuyển trạng thái COMPLETED. Lô thành phẩm sẵn sàng cho F08 phân phối

3. Phân loại Sự kiện CTE và Trạng thái ​

3.1. Các loại sự kiện CTE (Critical Tracking Events) ​

Mã CTE Tên sự kiện Mô tả KDE bắt buộc (TCVN 12850)
CTE-PROC-01 Nhập nguyên liệu Tiếp nhận nguyên liệu từ lô thu hoạch (F05) hoặc lô xuất chuồng (F06) Who (performed_by_name), What (source_lot_ids multi-select, source_type CROP_HARVEST/LIVESTOCK_OUTPUT, received_quantity, material_condition TỐT/TRUNG_BÌNH/KÉM, material_temperature), Where (cơ sở facility_id), When (event_time), Why (order_id – lệnh SX)
CTE-PROC-02 Sơ chế Rửa, phân loại, cắt, bóc vỏ Who, What (activity_type multi-select RỬA/PHÂN_LOẠI/CẮT/BÓC_VỎ/LÀM_SẠCH, weight_before, weight_after, loss_percentage auto, by_product_description, by_product_weight), Where, When. Quy tắc: weight_after <= weight_before
CTE-PROC-03 Chế biến Nấu, trộn, lên men, xông khói Who, What (method NẤU/TRỘN/LÊN_MEN/XÔNG_KHÓI/SẤY/ÉP/CHIẾT_XUẤT, temperature, duration_minutes, additives, mixing_ratio, output_weight), Where, When
CTE-PROC-04 Kiểm tra chất lượng Kiểm tra trước đóng gói Who (inspector_name – QC), What (qc_result PASSED/FAILED/CONDITIONAL, qc_criteria, measurements JSONB, failure_reason conditional khi FAILED, corrective_action conditional khi FAILED, qc_documents upload), When. QC PASSED/CONDITIONAL bắt buộc trước đóng gói
CTE-PROC-05 Đóng gói Đóng gói thành phẩm, gắn nhãn Who, What (output_lot_code auto, product_id, packaged_quantity, packaging_spec, unit_count, production_date, expiry_date auto, gtin_code, create_logistics_unit toggle, logistics_unit_count, logistics_unit_type PALLET/THÙNG_CARTON/CONTAINER), Where, When. Trigger SSCC + QR Code F16
CTE-PROC-06 Bảo quản Lưu kho bảo quản Who, What (warehouse_id, storage_location, storage_type LẠNH/MÁT/THƯỜNG/ĐÔNG_LẠNH, storage_temperature, storage_humidity, storage_date), Where (kho), When

3.2. Trạng thái Lệnh sản xuất (Processing Order) ​

Trạng thái Mã Mô tả Màu hiển thị
Nháp DRAFT Mới tạo, chưa bắt đầu sản xuất Xám
Đang sản xuất IN_PROGRESS Đã bắt đầu ghi nhận CTE Xanh dương
Chờ QC PENDING_QC Đã hoàn thành chế biến, chờ kiểm tra chất lượng Vàng
Hoàn thành COMPLETED Đã đóng gói xong, lô thành phẩm sẵn sàng Xanh lá
Hủy CANCELLED Lệnh SX bị hủy Đỏ

3.3. Trạng thái Lô thành phẩm (Output Lot) ​

Trạng thái Mã Mô tả
Đang sản xuất PRODUCING Đang trong quy trình chế biến
Đã đóng gói PACKAGED Đã đóng gói, có QR và SSCC
Đang phân phối DISTRIBUTING Đã chuyển sang F08
Đã thu hồi RECALLED Lô bị thu hồi
Hết hạn EXPIRED Quá hạn sử dụng

3.4. Kết quả kiểm tra chất lượng ​

Kết quả Mã Mô tả
Đạt PASSED Đạt tất cả chỉ tiêu
Không đạt FAILED Không đạt chỉ tiêu, cần xử lý
Đạt có điều kiện CONDITIONAL Đạt nhưng có ghi chú/hạn chế

4. Danh sách màn hình ​

Mã màn hình Tên màn hình Chức năng chính Vai trò sử dụng Ghi chú
SCR-F07-01 Danh sách Lệnh sản xuất Xem, tìm kiếm, lọc danh sách lệnh SX Tất cả Màn hình chính
SCR-F07-02 Tạo mới / Chỉnh sửa Lệnh sản xuất Form tạo/sửa lệnh SX ENTERPRISE_ADMIN, ENTERPRISE_USER
SCR-F07-03 Chi tiết Lệnh sản xuất Xem toàn bộ thông tin + timeline CTE Tất cả Read-only
SCR-F07-04 Ghi nhận Sự kiện CTE Form ghi nhận từng sự kiện CTE ENTERPRISE_ADMIN, ENTERPRISE_USER Form động theo loại CTE
SCR-F07-05 Đóng gói và Cấp SSCC Form đóng gói, tạo lô TP, cấp SSCC ENTERPRISE_ADMIN, ENTERPRISE_USER Trigger F16
SCR-F07-06 Kiểm tra Chất lượng Form ghi kết quả kiểm tra QC ENTERPRISE_ADMIN, ENTERPRISE_USER
SCR-F07-07 Danh sách Đơn vị Logistic Xem danh sách SSCC, in nhãn Tất cả GS1-128 barcode

5. Mô tả chi tiết trường dữ liệu từng màn hình ​

5.1. SCR-F07-01: Danh sách Lệnh sản xuất ​

Thanh công cụ (Toolbar):

Phần tử Loại Mô tả
Tìm kiếm Text Input Tìm theo mã lệnh SX, tên sản phẩm, mã lô
Lọc trạng thái Dropdown DRAFT / IN_PROGRESS / PENDING_QC / COMPLETED / CANCELLED / Tất cả
Lọc loại sự kiện Dropdown CTE-PROC-01 đến CTE-PROC-06 / Tất cả
Lọc ngày Date Range Từ ngày – Đến ngày
Nút "Tạo lệnh SX" Button (Primary) Mở SCR-F07-02 (chỉ ENTERPRISE_ADMIN, ENTERPRISE_USER)
Nút "Xuất Excel" Button (Secondary) Xuất danh sách ra file Excel

Bảng dữ liệu (Data Table):

Cột Kiểu Sortable Mô tả
STT Number Không Số thứ tự
Mã lệnh SX Text (Link) Có Mã tự động PO-{YYYYMMDD}-
Sản phẩm đầu ra Text Có Tên sản phẩm thành phẩm
Số lô NL đầu vào Number Có Số lượng lô nguyên liệu
Số lô TP đầu ra Number Có Số lượng lô thành phẩm
Ngày bắt đầu Date Có dd/MM/yyyy
Ngày hoàn thành Date Có dd/MM/yyyy
Trạng thái Badge Có Color-coded
Sự kiện cuối Text Không CTE cuối cùng đã ghi nhận
Thao tác Actions Không Xem / Sửa / Xóa

Phân trang: 10 / 20 / 50 / 100 bản ghi/trang.

5.2. SCR-F07-02: Tạo mới / Chỉnh sửa Lệnh sản xuất ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Mã lệnh SX order_code Text (auto) Có Auto: PO-{YYYYMMDD}- Hệ thống tự động sinh
Tên lệnh SX order_name Text (5-200) Có Mô tả ngắn gọn về lệnh SX
Sản phẩm đầu ra product_id Dropdown Có FK -> products.id (F03) Sản phẩm dự kiến sản xuất
Cơ sở sản xuất facility_id Dropdown Có FK -> facilities (F02) Nhà máy / Cơ sở chế biến
Ngày bắt đầu dự kiến planned_start_date Date Có >= ngày hiện tại
Ngày kết thúc dự kiến planned_end_date Date Có > planned_start_date
Sản lượng dự kiến planned_quantity Decimal(15,3) Có > 0 Số lượng dự kiến sản xuất
Đơn vị tính unit Dropdown Có kg/lít/thùng/gói/chai/lon/hộp
Hạn sử dụng mặc định (ngày) default_shelf_life_days Number Có > 0 Số ngày từ ngày SX đến HSD
Ghi chú notes Textarea (0-1000) Không

5.3. SCR-F07-04: Ghi nhận Sự kiện CTE ​

5.3.1. Trường chung cho tất cả CTE ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Lệnh sản xuất order_id Auto Có FK -> processing_orders.id Tự động gán theo lệnh SX hiện tại
Loại sự kiện event_type Dropdown Có CTE-PROC-01 đến CTE-PROC-06 Xác định loại CTE
Thời gian sự kiện event_time DateTime Có <= NOW() Thời điểm thực hiện
Người thực hiện performed_by_name Text (2-100) Có Tên người thực hiện
Địa điểm location_description Text (0-500) Không Mô tả vị trí thực hiện
Hình ảnh images File Upload Không JPEG/PNG, <=5MB, tối đa 5 ảnh Ảnh minh chứng
Ghi chú notes Textarea (0-1000) Không

5.3.2. Trường đặc thù CTE-PROC-01: Nhập nguyên liệu ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Lô nguyên liệu source_lot_ids Multi-select Có FK -> lots (F05/F06). Tối thiểu 1 lô Chọn 1 hoặc nhiều lô thu hoạch / lô xuất chuồng
Nguồn gốc source_type Dropdown Có CROP_HARVEST / LIVESTOCK_OUTPUT Từ F05 hay F06
Khối lượng tiếp nhận received_quantity Decimal(15,3) Có > 0 Tổng khối lượng NL nhận
Đơn vị received_unit Dropdown Có kg/lít/tấn/con
Tình trạng NL material_condition Dropdown Có TỐT / TRUNG_BÌNH / KÉM Đánh giá chất lượng NL đầu vào
Nhiệt độ NL (°C) material_temperature Decimal(5,2) Không Nhiệt độ NL khi tiếp nhận

5.3.3. Trường đặc thù CTE-PROC-02: Sơ chế ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Hoạt động sơ chế activity_type Multi-select Có RỬA / PHÂN_LOẠI / CẮT / BÓC_VỎ / LÀM_SẠCH / KHÁC Các bước sơ chế thực hiện
Khối lượng trước sơ chế weight_before Decimal(15,3) Có > 0 kg
Khối lượng sau sơ chế weight_after Decimal(15,3) Có > 0, <= weight_before kg
Tỷ lệ hao hụt (%) loss_percentage Decimal(5,2) Auto = (before - after) / before * 100 Hệ thống tự động tính
Phụ phẩm by_product_description Text (0-500) Không Mô tả phụ phẩm (vỏ, cuống, hạt...)
Khối lượng phụ phẩm by_product_weight Decimal(15,3) Không >= 0 kg

5.3.4. Trường đặc thù CTE-PROC-03: Chế biến ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Phương pháp chế biến method Dropdown Có NẤU / TRỘN / LÊN_MEN / XÔNG_KHÓI / SẤY / ÉP / CHIẾT_XUẤT / KHÁC
Nhiệt độ (°C) temperature Decimal(5,2) Không Nhiệt độ chế biến
Thời gian (phút) duration_minutes Number Không > 0 Thời gian chế biến
Phụ gia / Gia vị additives Textarea (0-500) Không Danh sách phụ gia sử dụng
Tỷ lệ phối trộn mixing_ratio Text (0-200) Không VD: "70% thịt lợn + 30% gia vị"
Khối lượng sau chế biến output_weight Decimal(15,3) Có > 0 kg

5.3.5. Trường đặc thù CTE-PROC-04: Kiểm tra chất lượng (QC) ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Người kiểm tra inspector_name Text (2-100) Có Tên nhân viên QC
Kết quả qc_result Dropdown Có PASSED / FAILED / CONDITIONAL
Chỉ tiêu kiểm tra qc_criteria Textarea (0-1000) Có Các chỉ tiêu đã kiểm tra
Giá trị đo lường measurements JSONB Không VD:
Lý do không đạt failure_reason Textarea (0-500) Có* *Bắt buộc khi qc_result = FAILED
Hành động xử lý corrective_action Textarea (0-500) Có* *Bắt buộc khi qc_result = FAILED VD: "Chế biến lại", "Loại bỏ"
Tài liệu QC qc_documents File Upload Không PDF/JPEG/PNG, <=10MB, tối đa 3 file Phiếu kiểm nghiệm

5.3.6. Trường đặc thù CTE-PROC-05: Đóng gói ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Mã lô thành phẩm output_lot_code Text (auto) Có Auto: LOT-{TYPE}-{YYYYMMDD}- Hệ thống tự động sinh
Sản phẩm product_id Auto Có FK -> products.id Từ lệnh SX
Khối lượng đóng gói packaged_quantity Decimal(15,3) Có > 0 Tổng KL đóng gói
Đơn vị packaged_unit Dropdown Có kg/lít/thùng/gói/chai/lon/hộp
Quy cách đóng gói packaging_spec Text (1-200) Có VD: "Hộp 500g", "Chai 1 lít"
Số lượng đơn vị unit_count Number Có > 0 Số hộp/chai/gói
Ngày sản xuất production_date Date Có = ngày hiện tại
Hạn sử dụng expiry_date Date Auto = production_date + default_shelf_life_days Hệ thống tự động tính
Mã GTIN gtin_code Text (13-14) Không Checksum GS1 Mã sản phẩm GS1
Tạo đơn vị logistic create_logistics_unit Toggle Không Tạo pallet/thùng lớn và cấp SSCC
Số lượng đơn vị logistic logistics_unit_count Number Có* *Bắt buộc khi create_logistics_unit = true, > 0 Số pallet/thùng
Loại đơn vị logistic logistics_unit_type Dropdown Có* PALLET / THÙNG_CARTON / CONTAINER

5.3.7. Trường đặc thù CTE-PROC-06: Bảo quản ​

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Kho bảo quản warehouse_id Dropdown Có FK -> warehouses.id (F19) Chọn kho
Vị trí lưu trữ storage_location Text (0-100) Không Khu/Dãy/Ô
Loại bảo quản storage_type Dropdown Có LẠNH / MÁT / THƯỜNG / ĐÔNG_LẠNH
Nhiệt độ (°C) storage_temperature Decimal(5,2) Có* *Bắt buộc khi storage_type != THƯỜNG
Độ ẩm (%) storage_humidity Decimal(5,2) Không 0-100
Ngày nhập kho storage_date DateTime Có

5.4. SCR-F07-05: Đóng gói và Cấp SSCC ​

Kết hợp trường CTE-PROC-05 với phần cấp SSCC:

Tên trường Field name Kiểu dữ liệu Bắt buộc Validation Mô tả
Extension Digit sscc_extension Dropdown Có 0-9 Chữ số mở rộng SSCC
GS1 Company Prefix gs1_company_prefix Text (auto) Có Từ cấu hình DN (F01) Mã DN do GS1 VN cấp
Serial Reference sscc_serial_ref Text (auto) Có 6-9 chữ số, unique Hệ thống tự động tăng
Check Digit sscc_check_digit Number (auto) Có Thuật toán Mod-10 Tự động tính
SSCC hoàn chỉnh sscc_code Text (18, auto) Có 18 chữ số = Extension + Prefix + Serial + Check
Barcode GS1-128 gs1_128_barcode Auto Có AI(00) + SSCC Tự động sinh cho in nhãn

5.5. SCR-F07-06: Kiểm tra Chất lượng ​

Trùng với phần CTE-PROC-04 (mục 5.3.5). Thêm phần:

Phần tử Mô tả
Summary Card Tổng số mẫu kiểm tra, tỷ lệ ĐẠT/KHÔNG_ĐẠT
Lịch sử QC Bảng lịch sử các lần kiểm tra trước của lệnh SX

5.6. SCR-F07-07: Danh sách Đơn vị Logistic ​

Cột Kiểu Sortable Mô tả
STT Number Không
Mã SSCC Text (Link) Có 18 chữ số
Loại Tag Có PALLET / THÙNG_CARTON / CONTAINER
Sản phẩm Text Có Tên sản phẩm chứa trong
Mã lô TP Text Có Link đến lô thành phẩm
Số lượng SP Number Có Số đơn vị SP trong DV logistic
Ngày tạo DateTime Có
Barcode Icon Không In GS1-128: AI(00) SSCC + AI(02) GTIN + AI(37) Qty
Trạng thái Badge Có ACTIVE / SHIPPED / RECEIVED
Thao tác Actions Không Xem / In nhãn

6. Danh sách Use Case ​

ID Tên Usecase Mô tả Màn hình liên quan
UC-F07-01 Xem danh sách lệnh sản xuất Xem, tìm kiếm, lọc danh sách lệnh SX SCR-F07-01
UC-F07-02 Tạo lệnh sản xuất Tạo lệnh SX mới với thông tin sản phẩm, cơ sở, sản lượng SCR-F07-01, SCR-F07-02
UC-F07-03 Chỉnh sửa lệnh sản xuất Cập nhật thông tin lệnh SX (chỉ khi DRAFT) SCR-F07-02
UC-F07-04 Ghi nhận CTE-PROC-01: Nhập nguyên liệu Liên kết lô NL từ F05/F06, mapping N:N SCR-F07-03, SCR-F07-04
UC-F07-05 Ghi nhận CTE-PROC-02: Sơ chế Ghi nhận hoạt động sơ chế, hao hụt SCR-F07-03, SCR-F07-04
UC-F07-06 Ghi nhận CTE-PROC-03: Chế biến Ghi nhận quy trình chế biến SCR-F07-03, SCR-F07-04
UC-F07-07 Ghi nhận CTE-PROC-04: Kiểm tra chất lượng Ghi kết quả QC trước đóng gói SCR-F07-03, SCR-F07-06
UC-F07-08 Ghi nhận CTE-PROC-05: Đóng gói Tạo lô TP, trigger QR, cấp SSCC SCR-F07-03, SCR-F07-05
UC-F07-09 Ghi nhận CTE-PROC-06: Bảo quản Ghi điều kiện bảo quản, liên kết kho SCR-F07-03, SCR-F07-04
UC-F07-10 Xem chi tiết lệnh sản xuất Xem toàn bộ thông tin + timeline CTE SCR-F07-03
UC-F07-11 Hủy lệnh sản xuất Hủy lệnh SX (chỉ khi DRAFT hoặc IN_PROGRESS) SCR-F07-01
UC-F07-12 Xem danh sách đơn vị logistic Xem SSCC, in nhãn GS1-128 SCR-F07-07
UC-F07-13 Xuất Excel danh sách lệnh SX Export danh sách ra file Excel SCR-F07-01

7. Mô tả chi tiết Use Case ​

7.1. UC-F07-01: Xem danh sách lệnh sản xuất ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Truy cập menu TXNG > Nhật ký Sản xuất > Sơ chế – Chế biến – Đóng gói Hệ thống kiểm tra quyền. Nếu có quyền -> hiển thị SCR-F07-01 với danh sách lệnh SX thuộc DN của user, phân trang mặc định 20 bản ghi Nếu không có quyền -> E-F07-001
2 User Nhập từ khóa vào ô tìm kiếm Tìm kiếm theo mã lệnh SX, tên sản phẩm (full-text, debounce 300ms, min 2 ký tự)
3 User Chọn bộ lọc (trạng thái, ngày) Hệ thống lọc danh sách theo điều kiện Kết hợp nhiều bộ lọc
4 User Click header cột để sắp xếp Sắp xếp ASC/DESC Toggle mỗi lần click
5 User Chọn số bản ghi/trang hoặc chuyển trang Load dữ liệu tương ứng Server-side pagination

7.2. UC-F07-02: Tạo lệnh sản xuất ​

UC-F07-02.1: Tạo thành công ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Tại SCR-F07-01, nhấn "Tạo lệnh SX" Mở SCR-F07-02 (form trống) Chỉ hiển thị nếu có quyền
2 User Chọn sản phẩm đầu ra từ dropdown Load thông tin sản phẩm từ F03, tự động fill default_shelf_life_days nếu đã cấu hình
3 User Chọn cơ sở sản xuất Dropdown cơ sở thuộc DN (F02)
4 User Nhập đầy đủ các trường bắt buộc Validate real-time từng trường
5 User Nhấn "Lưu" Hệ thống thực hiện:
1. Validate toàn bộ form (server-side)
2. Sinh mã lệnh SX tự động: PO-{YYYYMMDD}-
3. Lưu bản ghi vào CSDL với status = DRAFT
4. Ghi log
5. Trả về response 201 Created
6 Hệ thống Điều hướng về SCR-F07-03 (Chi tiết) Hiển thị lệnh SX vừa tạo, sẵn sàng ghi nhận CTE

UC-F07-02.2: Tạo thất bại – Validation error ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1-4 (Giống UC-F07-02.1 bước 1-4)
5 User Nhấn "Lưu" với dữ liệu không hợp lệ Hệ thống trả về danh sách lỗi validate, highlight trường lỗi
6 User Sửa dữ liệu Validate lại real-time

7.3. UC-F07-04: Ghi nhận CTE-PROC-01: Nhập nguyên liệu ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Tại SCR-F07-03, nhấn "Thêm sự kiện" -> chọn CTE-PROC-01 Mở SCR-F07-04 với form Nhập nguyên liệu Lệnh SX phải ở trạng thái DRAFT hoặc IN_PROGRESS
2 User Chọn nguồn gốc: CROP_HARVEST hoặc LIVESTOCK_OUTPUT Hệ thống load danh sách lô tương ứng từ F05 hoặc F06 Chỉ hiển thị lô chưa hết
3 User Chọn 1 hoặc nhiều lô nguyên liệu (N:N) Với mỗi lô, hiển thị: mã lô, sản phẩm, khối lượng còn lại, ngày thu hoạch/xuất chuồng Multi-select
4 User Nhập khối lượng tiếp nhận, đánh giá tình trạng NL Validate: tổng KL tiếp nhận <= tổng KL khả dụng của các lô đã chọn
5 User (Tùy chọn) Upload hình ảnh minh chứng Validate file format, size
6 User Nhấn "Lưu sự kiện" Hệ thống thực hiện:
1. Validate server-side
2. Tạo bản ghi processing_events (event_type = CTE-PROC-01)
3. Tạo bản ghi processing_inputs (mapping N:N lô NL -> lệnh SX)
4. Cập nhật trạng thái lệnh SX -> IN_PROGRESS (nếu đang DRAFT)
5. Ghi log
6. Thông báo thành công

7.4. UC-F07-07: Ghi nhận CTE-PROC-04: Kiểm tra chất lượng ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Tại SCR-F07-03, nhấn "Thêm sự kiện" -> chọn CTE-PROC-04 Mở SCR-F07-06. Lệnh SX phải ở trạng thái IN_PROGRESS
2 User Nhập thông tin kiểm tra: người kiểm, chỉ tiêu, giá trị đo
3 User Chọn kết quả: PASSED / FAILED / CONDITIONAL Nếu FAILED -> bắt buộc nhập lý do và hành động xử lý
4 User Nhấn "Lưu kết quả QC" Hệ thống thực hiện:
1. Validate server-side
2. Tạo bản ghi processing_events (event_type = CTE-PROC-04)
3. Nếu PASSED/CONDITIONAL -> chuyển lệnh SX sang PENDING_QC (cho phép đóng gói)
4. Nếu FAILED -> giữ IN_PROGRESS, gửi notification cho ENTERPRISE_ADMIN
5. Ghi log

7.5. UC-F07-08: Ghi nhận CTE-PROC-05: Đóng gói ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Tại SCR-F07-03, nhấn "Đóng gói" Mở SCR-F07-05. Lệnh SX phải có ít nhất 1 sự kiện QC với kết quả PASSED hoặc CONDITIONAL
2 User Nhập thông tin đóng gói: KL, quy cách, số lượng đơn vị Tự động fill ngày SX = hôm nay, HSD = ngày SX + shelf_life
3 User (Tùy chọn) Bật toggle "Tạo đơn vị logistic" Hiển thị thêm trường: số lượng DV, loại DV
4 User Nhấn "Hoàn thành đóng gói" Hệ thống thực hiện:
1. Validate server-side
2. Tạo bản ghi processing_events (event_type = CTE-PROC-05)
3. Tạo bản ghi processing_outputs (lô thành phẩm, status = PACKAGED)
4. Tự động tính expiry_date = production_date + default_shelf_life_days
5. Trigger TXNG-F16: Tạo QR Code cho lô thành phẩm
6. Nếu create_logistics_unit = true: Cấp SSCC theo TCVN 6754:2007 (Extension + GS1 Prefix + Serial + Check Digit Mod-10)
7. Tạo bản ghi logistics_units với SSCC
8. Chuyển lệnh SX -> COMPLETED
9. Ghi log TransformationEvent: input lots -> output lot
10. Gửi notification N-F07-01

7.6. UC-F07-11: Hủy lệnh sản xuất ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 ENTERPRISE_ADMIN Tại SCR-F07-01, nhấn "Hủy" trên dòng lệnh SX Kiểm tra: lệnh SX phải ở trạng thái DRAFT hoặc IN_PROGRESS Không cho hủy COMPLETED
2 Hệ thống Hiển thị dialog xác nhận "Bạn có chắc muốn hủy lệnh sản xuất [mã]? Hành động này không thể hoàn tác."
3a User Nhấn "Đồng ý" Chuyển trạng thái -> CANCELLED. Ghi log. Thông báo thành công
3b User Nhấn "Hủy bỏ" Đóng dialog, không thay đổi

7.7. UC-F07-12: Xem danh sách đơn vị logistic ​

Bước Tác nhân Hành động / Mô tả Phản hồi / Xử lý hệ thống Ghi chú
1 User Truy cập SCR-F07-07 hoặc từ SCR-F07-03 tab "Đơn vị logistic" Hiển thị danh sách SSCC thuộc DN, phân trang
2 User Nhấn "In nhãn" trên 1 SSCC Hệ thống sinh nhãn GS1-128 barcode: AI(00) SSCC + AI(02) GTIN + AI(37) Quantity. Mở dialog in

8. Thiết kế Database Schema ​

8.1. Sơ đồ quan hệ (ER Diagram) ​

+---------------------+       +------------------------+
|    enterprises      |       |    products (F03)      |
|    (TXNG-F01)       |       +------------------------+
+---------------------+       | id (PK)                |
| id (PK)             |       | product_name           |
+--------+------------+       | gtin_code              |
         | 1:N                 +-----------+------------+
         |                                | 1:N
         v                                v
+----------------------------+  +----------------------------+
|   processing_orders        |  |   processing_outputs       |
|   (Lệnh sản xuất)         |  |   (Lô thành phẩm đầu ra)  |
+----------------------------+  +----------------------------+
| id (PK)                    |  | id (PK)                    |
| enterprise_id (FK)         |  | order_id (FK)              |
| order_code (UNIQUE)        |  | enterprise_id (FK)         |
| order_name                 |  | output_lot_code (UNIQUE)   |
| product_id (FK)            |  | product_id (FK)            |
| facility_id (FK)           |  | packaged_quantity          |
| status                     |  | production_date            |
| planned_start_date         |  | expiry_date                |
| planned_end_date           |  | gtin_code                  |
| planned_quantity           |  | qr_code_id (FK)            |
| default_shelf_life_days    |  | status                     |
+--------+-------------------+  +--------+-------------------+
         | 1:N                           | 1:N
         v                               v
+----------------------------+ +----------------------------+
|   processing_events        | |   logistics_units          |
|   (Sự kiện CTE)           | |   (Đơn vị logistic / SSCC) |
+----------------------------+ +----------------------------+
| id (PK)                    | | id (PK)                    |
| order_id (FK)              | | enterprise_id (FK)         |
| enterprise_id (FK)         | | output_id (FK)             |
| event_type                 | | sscc_code (UNIQUE)         |
| event_time                 | | unit_type                  |
| performed_by_name          | | item_count                 |
| event_data (JSONB)         | | gs1_128_data               |
| notes                      | | status                     |
+--------+-------------------+ +----------------------------+
         | 1:N                +----------------------------+
         v                    |  processing_inputs         |
+----------------------------+|  (NL đầu vào, N:N)        |
| processing_event_images    |+----------------------------+
+----------------------------+| id (PK)                    |
| id (PK)                    || order_id (FK)              |
| event_id (FK)              || event_id (FK)              |
| file_path                  || enterprise_id (FK)         |
| file_name                  || source_lot_id (FK)         |
| file_size                  || source_type                |
| sort_order                 || received_quantity          |
+----------------------------+| material_condition         |
                              | material_temperature       |
                              +----------------------------+

8.2. Mô tả bảng dữ liệu ​

8.2.1. Bảng processing_orders (Lệnh sản xuất) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
enterprise_id UUID NOT NULL FK -> enterprises.id FOREIGN KEY
order_code VARCHAR(30) NOT NULL Mã lệnh SX UNIQUE
order_name VARCHAR(200) NOT NULL Tên lệnh SX
product_id UUID NOT NULL FK -> products.id FOREIGN KEY
facility_id UUID NOT NULL FK -> facilities.id FOREIGN KEY
status VARCHAR(20) NOT NULL 'DRAFT' Trạng thái CHECK IN ('DRAFT','IN_PROGRESS','PENDING_QC','COMPLETED','CANCELLED')
planned_start_date DATE NOT NULL Ngày bắt đầu dự kiến
planned_end_date DATE NOT NULL Ngày kết thúc dự kiến CHECK > planned_start_date
actual_start_date DATE NULL Ngày bắt đầu thực tế
actual_end_date DATE NULL Ngày hoàn thành thực tế
planned_quantity DECIMAL(15,3) NOT NULL Sản lượng dự kiến CHECK > 0
actual_quantity DECIMAL(15,3) NULL Sản lượng thực tế CHECK >= 0
unit VARCHAR(20) NOT NULL Đơn vị tính CHECK IN ('kg','lit','thung','goi','chai','lon','hop')
default_shelf_life_days INTEGER NOT NULL Số ngày HSD CHECK > 0
notes TEXT NULL Ghi chú
created_by UUID NOT NULL FK -> users.id FOREIGN KEY
updated_by UUID NULL FK -> users.id FOREIGN KEY
created_at TIMESTAMPTZ NOT NULL NOW()
updated_at TIMESTAMPTZ NOT NULL NOW()
deleted_at TIMESTAMPTZ NULL Soft delete

8.2.2. Bảng processing_events (Sự kiện CTE) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
order_id UUID NOT NULL FK -> processing_orders.id FOREIGN KEY
enterprise_id UUID NOT NULL FK -> enterprises.id FOREIGN KEY
event_type VARCHAR(20) NOT NULL Loại CTE CHECK IN ('CTE-PROC-01','CTE-PROC-02','CTE-PROC-03','CTE-PROC-04','CTE-PROC-05','CTE-PROC-06')
event_time TIMESTAMPTZ NOT NULL Thời điểm sự kiện
performed_by_name VARCHAR(100) NOT NULL Người thực hiện
location_description VARCHAR(500) NULL Địa điểm
event_data JSONB NOT NULL '{}' Dữ liệu chi tiết theo loại CTE
notes TEXT NULL Ghi chú
created_by UUID NOT NULL FK -> users.id FOREIGN KEY
created_at TIMESTAMPTZ NOT NULL NOW()
updated_at TIMESTAMPTZ NOT NULL NOW()

8.2.3. Bảng processing_inputs (Nguyên liệu đầu vào, mapping N:N) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
order_id UUID NOT NULL FK -> processing_orders.id FOREIGN KEY
event_id UUID NOT NULL FK -> processing_events.id FOREIGN KEY
enterprise_id UUID NOT NULL FK -> enterprises.id FOREIGN KEY
source_lot_id UUID NOT NULL FK -> lots (F05/F06) FOREIGN KEY
source_type VARCHAR(20) NOT NULL Nguồn gốc CHECK IN ('CROP_HARVEST','LIVESTOCK_OUTPUT')
received_quantity DECIMAL(15,3) NOT NULL Khối lượng tiếp nhận CHECK > 0
received_unit VARCHAR(20) NOT NULL Đơn vị CHECK IN ('kg','lit','tan','con')
material_condition VARCHAR(15) NOT NULL Tình trạng NL CHECK IN ('TOT','TRUNG_BINH','KEM')
material_temperature DECIMAL(5,2) NULL Nhiệt độ NL (°C)
created_by UUID NOT NULL FK -> users.id FOREIGN KEY
created_at TIMESTAMPTZ NOT NULL NOW()

8.2.4. Bảng processing_outputs (Lô thành phẩm đầu ra) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
order_id UUID NOT NULL FK -> processing_orders.id FOREIGN KEY
enterprise_id UUID NOT NULL FK -> enterprises.id FOREIGN KEY
event_id UUID NOT NULL FK -> processing_events.id (CTE-PROC-05) FOREIGN KEY
output_lot_code VARCHAR(50) NOT NULL Mã lô thành phẩm
product_id UUID NOT NULL FK -> products.id FOREIGN KEY
packaged_quantity DECIMAL(15,3) NOT NULL Khối lượng đóng gói CHECK > 0
packaged_unit VARCHAR(20) NOT NULL Đơn vị
packaging_spec VARCHAR(200) NOT NULL Quy cách đóng gói
unit_count INTEGER NOT NULL Số đơn vị (hộp/chai/gói) CHECK > 0
production_date DATE NOT NULL Ngày sản xuất
expiry_date DATE NOT NULL Hạn sử dụng (auto-calc: production_date + shelf_life_days) CHECK > production_date
gtin_code VARCHAR(14) NULL Mã GTIN
qr_code_id UUID NULL FK -> qr_codes.id (F16) FOREIGN KEY
status VARCHAR(20) NOT NULL 'PACKAGED' Trạng thái lô TP CHECK IN ('PRODUCING','PACKAGED','DISTRIBUTING','RECALLED','EXPIRED')
created_by UUID NOT NULL FK -> users.id FOREIGN KEY
created_at TIMESTAMPTZ NOT NULL NOW()
updated_at TIMESTAMPTZ NOT NULL NOW()
deleted_at TIMESTAMPTZ NULL Soft delete

8.2.5. Bảng processing_event_images (Hình ảnh sự kiện) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
event_id UUID NOT NULL FK -> processing_events.id FOREIGN KEY, ON DELETE CASCADE
file_path VARCHAR(500) NOT NULL Đường dẫn file trên storage
file_name VARCHAR(200) NOT NULL Tên file gốc
file_size INTEGER NOT NULL Kích thước (bytes) CHECK <= 5242880 (5MB)
mime_type VARCHAR(50) NOT NULL MIME type CHECK IN ('image/jpeg','image/png')
sort_order INTEGER NOT NULL 0 Thứ tự hiển thị
created_at TIMESTAMPTZ NOT NULL NOW()

8.2.6. Bảng logistics_units (Đơn vị logistic / SSCC) ​

Cột Kiểu dữ liệu Nullable Default Mô tả Constraint
id UUID NOT NULL gen_random_uuid() Khóa chính PRIMARY KEY
enterprise_id UUID NOT NULL FK -> enterprises.id FOREIGN KEY
output_id UUID NOT NULL FK -> processing_outputs.id FOREIGN KEY
sscc_code VARCHAR(18) NOT NULL Mã SSCC 18 chữ số
sscc_extension CHAR(1) NOT NULL Extension Digit (0-9)
gs1_company_prefix VARCHAR(10) NOT NULL GS1 Company Prefix
sscc_serial_ref VARCHAR(9) NOT NULL Serial Reference
sscc_check_digit CHAR(1) NOT NULL Check Digit (Mod-10)
unit_type VARCHAR(20) NOT NULL Loại DV logistic CHECK IN ('PALLET','THUNG_CARTON','CONTAINER')
item_count INTEGER NOT NULL Số SP trong DV CHECK > 0
gtin_code VARCHAR(14) NULL GTIN sản phẩm chứa trong
gs1_128_data TEXT NULL Dữ liệu barcode GS1-128
status VARCHAR(15) NOT NULL 'ACTIVE' Trạng thái CHECK IN ('ACTIVE','SHIPPED','RECEIVED')
created_by UUID NOT NULL FK -> users.id FOREIGN KEY
created_at TIMESTAMPTZ NOT NULL NOW()
updated_at TIMESTAMPTZ NOT NULL NOW()

8.3. Indexes ​

sql
-- processing_orders
CREATE UNIQUE INDEX idx_processing_orders_code ON processing_orders(order_code);
CREATE INDEX idx_processing_orders_enterprise ON processing_orders(enterprise_id);
CREATE INDEX idx_processing_orders_status ON processing_orders(status);
CREATE INDEX idx_processing_orders_product ON processing_orders(product_id);
CREATE INDEX idx_processing_orders_dates ON processing_orders(planned_start_date, planned_end_date);
CREATE INDEX idx_processing_orders_search ON processing_orders USING gin(to_tsvector('simple', order_name));
CREATE INDEX idx_processing_orders_not_deleted ON processing_orders(enterprise_id) WHERE deleted_at IS NULL;

-- processing_events
CREATE INDEX idx_processing_events_order ON processing_events(order_id);
CREATE INDEX idx_processing_events_enterprise ON processing_events(enterprise_id);
CREATE INDEX idx_processing_events_type ON processing_events(event_type);
CREATE INDEX idx_processing_events_time ON processing_events(event_time);

-- processing_inputs
CREATE INDEX idx_processing_inputs_order ON processing_inputs(order_id);
CREATE INDEX idx_processing_inputs_source_lot ON processing_inputs(source_lot_id);
CREATE UNIQUE INDEX idx_processing_inputs_unique ON processing_inputs(order_id, source_lot_id, event_id);

-- processing_outputs
CREATE UNIQUE INDEX idx_processing_outputs_lot_code ON processing_outputs(output_lot_code) WHERE deleted_at IS NULL;
CREATE INDEX idx_processing_outputs_order ON processing_outputs(order_id);
CREATE INDEX idx_processing_outputs_enterprise ON processing_outputs(enterprise_id);
CREATE INDEX idx_processing_outputs_status ON processing_outputs(status);
CREATE INDEX idx_processing_outputs_expiry ON processing_outputs(expiry_date);

-- processing_event_images
CREATE INDEX idx_processing_event_images_event ON processing_event_images(event_id);

-- logistics_units
CREATE UNIQUE INDEX idx_logistics_units_sscc ON logistics_units(sscc_code);
CREATE INDEX idx_logistics_units_enterprise ON logistics_units(enterprise_id);
CREATE INDEX idx_logistics_units_output ON logistics_units(output_id);
CREATE INDEX idx_logistics_units_status ON logistics_units(status);

8.4. Migration SQL ​

sql
-- Migration: 001_create_processing_tables.sql

-- Lệnh sản xuất
CREATE TABLE processing_orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    order_code VARCHAR(30) NOT NULL,
    order_name VARCHAR(200) NOT NULL,
    product_id UUID NOT NULL REFERENCES products(id),
    facility_id UUID NOT NULL REFERENCES facilities(id),
    status VARCHAR(20) NOT NULL DEFAULT 'DRAFT'
        CHECK (status IN ('DRAFT','IN_PROGRESS','PENDING_QC','COMPLETED','CANCELLED')),
    planned_start_date DATE NOT NULL,
    planned_end_date DATE NOT NULL,
    actual_start_date DATE,
    actual_end_date DATE,
    planned_quantity DECIMAL(15,3) NOT NULL CHECK (planned_quantity > 0),
    actual_quantity DECIMAL(15,3) CHECK (actual_quantity >= 0),
    unit VARCHAR(20) NOT NULL CHECK (unit IN ('kg','lit','thung','goi','chai','lon','hop')),
    default_shelf_life_days INTEGER NOT NULL CHECK (default_shelf_life_days > 0),
    notes TEXT,
    created_by UUID NOT NULL REFERENCES users(id),
    updated_by UUID REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ,
    CONSTRAINT chk_planned_dates CHECK (planned_end_date > planned_start_date)
);

CREATE UNIQUE INDEX idx_processing_orders_code ON processing_orders(order_code);
CREATE INDEX idx_processing_orders_enterprise ON processing_orders(enterprise_id);
CREATE INDEX idx_processing_orders_status ON processing_orders(status);

-- Sự kiện CTE
CREATE TABLE processing_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID NOT NULL REFERENCES processing_orders(id),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    event_type VARCHAR(20) NOT NULL
        CHECK (event_type IN ('CTE-PROC-01','CTE-PROC-02','CTE-PROC-03','CTE-PROC-04','CTE-PROC-05','CTE-PROC-06')),
    event_time TIMESTAMPTZ NOT NULL,
    performed_by_name VARCHAR(100) NOT NULL,
    location_description VARCHAR(500),
    event_data JSONB NOT NULL DEFAULT '{}',
    notes TEXT,
    created_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_processing_events_order ON processing_events(order_id);
CREATE INDEX idx_processing_events_type ON processing_events(event_type);

-- Nguyên liệu đầu vào (N:N)
CREATE TABLE processing_inputs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID NOT NULL REFERENCES processing_orders(id),
    event_id UUID NOT NULL REFERENCES processing_events(id),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    source_lot_id UUID NOT NULL,
    source_type VARCHAR(20) NOT NULL CHECK (source_type IN ('CROP_HARVEST','LIVESTOCK_OUTPUT')),
    received_quantity DECIMAL(15,3) NOT NULL CHECK (received_quantity > 0),
    received_unit VARCHAR(20) NOT NULL CHECK (received_unit IN ('kg','lit','tan','con')),
    material_condition VARCHAR(15) NOT NULL CHECK (material_condition IN ('TOT','TRUNG_BINH','KEM')),
    material_temperature DECIMAL(5,2),
    created_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_processing_inputs_order ON processing_inputs(order_id);
CREATE INDEX idx_processing_inputs_source ON processing_inputs(source_lot_id);

-- Lô thành phẩm đầu ra
CREATE TABLE processing_outputs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID NOT NULL REFERENCES processing_orders(id),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    event_id UUID NOT NULL REFERENCES processing_events(id),
    output_lot_code VARCHAR(50) NOT NULL,
    product_id UUID NOT NULL REFERENCES products(id),
    packaged_quantity DECIMAL(15,3) NOT NULL CHECK (packaged_quantity > 0),
    packaged_unit VARCHAR(20) NOT NULL,
    packaging_spec VARCHAR(200) NOT NULL,
    unit_count INTEGER NOT NULL CHECK (unit_count > 0),
    production_date DATE NOT NULL,
    expiry_date DATE NOT NULL,
    gtin_code VARCHAR(14),
    qr_code_id UUID,
    status VARCHAR(20) NOT NULL DEFAULT 'PACKAGED'
        CHECK (status IN ('PRODUCING','PACKAGED','DISTRIBUTING','RECALLED','EXPIRED')),
    created_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ,
    CONSTRAINT chk_expiry CHECK (expiry_date > production_date)
);

CREATE UNIQUE INDEX idx_processing_outputs_lot ON processing_outputs(output_lot_code) WHERE deleted_at IS NULL;
CREATE INDEX idx_processing_outputs_order ON processing_outputs(order_id);

-- Hình ảnh sự kiện
CREATE TABLE processing_event_images (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    event_id UUID NOT NULL REFERENCES processing_events(id) ON DELETE CASCADE,
    file_path VARCHAR(500) NOT NULL,
    file_name VARCHAR(200) NOT NULL,
    file_size INTEGER NOT NULL CHECK (file_size <= 5242880),
    mime_type VARCHAR(50) NOT NULL CHECK (mime_type IN ('image/jpeg','image/png')),
    sort_order INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Đơn vị logistic (SSCC)
CREATE TABLE logistics_units (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    output_id UUID NOT NULL REFERENCES processing_outputs(id),
    sscc_code VARCHAR(18) NOT NULL,
    sscc_extension CHAR(1) NOT NULL,
    gs1_company_prefix VARCHAR(10) NOT NULL,
    sscc_serial_ref VARCHAR(9) NOT NULL,
    sscc_check_digit CHAR(1) NOT NULL,
    unit_type VARCHAR(20) NOT NULL CHECK (unit_type IN ('PALLET','THUNG_CARTON','CONTAINER')),
    item_count INTEGER NOT NULL CHECK (item_count > 0),
    gtin_code VARCHAR(14),
    gs1_128_data TEXT,
    status VARCHAR(15) NOT NULL DEFAULT 'ACTIVE'
        CHECK (status IN ('ACTIVE','SHIPPED','RECEIVED')),
    created_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE UNIQUE INDEX idx_logistics_units_sscc ON logistics_units(sscc_code);
CREATE INDEX idx_logistics_units_enterprise ON logistics_units(enterprise_id);

-- Trigger auto-update updated_at
CREATE TRIGGER trg_processing_orders_updated_at
    BEFORE UPDATE ON processing_orders
    FOR EACH ROW EXECUTE FUNCTION update_updated_at();

CREATE TRIGGER trg_processing_events_updated_at
    BEFORE UPDATE ON processing_events
    FOR EACH ROW EXECUTE FUNCTION update_updated_at();

CREATE TRIGGER trg_processing_outputs_updated_at
    BEFORE UPDATE ON processing_outputs
    FOR EACH ROW EXECUTE FUNCTION update_updated_at();

CREATE TRIGGER trg_logistics_units_updated_at
    BEFORE UPDATE ON logistics_units
    FOR EACH ROW EXECUTE FUNCTION update_updated_at();

9. Thiết kế API ​

9.1. Danh sách endpoint ​

Method Endpoint Mô tả Auth Roles
GET /api/v1/processing-orders Danh sách lệnh SX (phân trang, lọc, tìm kiếm) Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER, SO_ADMIN
GET /api/v1/processing-orders/:id Chi tiết lệnh SX + timeline CTE Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER, SO_ADMIN
POST /api/v1/processing-orders Tạo lệnh SX mới Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER
PUT /api/v1/processing-orders/:id Cập nhật lệnh SX (chỉ DRAFT) Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER (owner)
DELETE /api/v1/processing-orders/:id Xóa mềm lệnh SX (chỉ DRAFT) Bearer Token ENTERPRISE_ADMIN
PUT /api/v1/processing-orders/:id/cancel Hủy lệnh SX Bearer Token ENTERPRISE_ADMIN
POST /api/v1/processing-orders/:id/events Ghi nhận sự kiện CTE Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER
GET /api/v1/processing-orders/:id/events Danh sách sự kiện CTE của lệnh SX Bearer Token Tất cả
POST /api/v1/processing-orders/:id/package Đóng gói + tạo lô TP + trigger QR + cấp SSCC Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER
GET /api/v1/processing-orders/:id/inputs Danh sách NL đầu vào Bearer Token Tất cả
GET /api/v1/processing-orders/:id/outputs Danh sách lô TP đầu ra Bearer Token Tất cả
GET /api/v1/processing-orders/analysis Thống kê tổng hợp (SummaryWrapper) Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER, SO_ADMIN
GET /api/v1/logistics-units Danh sách đơn vị logistic (SSCC) Bearer Token Tất cả
GET /api/v1/logistics-units/:id Chi tiết SSCC Bearer Token Tất cả
GET /api/v1/logistics-units/:id/label Sinh nhãn GS1-128 barcode Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER
GET /api/v1/processing-orders/export Xuất Excel Bearer Token ENTERPRISE_ADMIN, ENTERPRISE_USER

9.2. Chi tiết API ​

9.2.1. GET /api/v1/processing-orders – Danh sách lệnh SX ​

Query Parameters:

Param Kiểu Bắt buộc Mô tả
page Integer Không Trang hiện tại (default: 1)
page_size Integer Không Số bản ghi/trang (default: 20, max: 100)
search String Không Tìm theo mã lệnh, tên sản phẩm
status String Không Lọc theo trạng thái
date_from Date Không Từ ngày
date_to Date Không Đến ngày
sort_by String Không Cột sắp xếp (default: created_at)
sort_order String Không ASC / DESC (default: DESC)

Response 200:

json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "order_code": "PO-20260318-0001",
        "order_name": "Sản xuất tương ớt đợt 1",
        "product_name": "Tương ớt GoTrace 500ml",
        "status": "IN_PROGRESS",
        "input_lot_count": 3,
        "output_lot_count": 0,
        "planned_start_date": "2026-03-18",
        "last_event": "CTE-PROC-02",
        "created_at": "2026-03-18T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 45,
      "total_pages": 3
    }
  }
}

9.2.2. POST /api/v1/processing-orders – Tạo lệnh SX ​

Request Body:

json
{
  "order_name": "Sản xuất tương ớt đợt 1",
  "product_id": "uuid-product",
  "facility_id": "uuid-facility",
  "planned_start_date": "2026-03-20",
  "planned_end_date": "2026-03-25",
  "planned_quantity": 5000,
  "unit": "chai",
  "default_shelf_life_days": 365,
  "notes": ""
}

Response 201:

json
{
  "success": true,
  "data": {
    "id": "uuid",
    "order_code": "PO-20260318-0001",
    "status": "DRAFT",
    "message": "Tạo lệnh sản xuất thành công."
  }
}

9.2.3. POST /api/v1/processing-orders/:id/events – Ghi nhận sự kiện CTE ​

Request Body (CTE-PROC-01):

json
{
  "event_type": "CTE-PROC-01",
  "event_time": "2026-03-20T08:00:00+07:00",
  "performed_by_name": "Nguyễn Văn A",
  "location_description": "Khu tiếp nhận NL - Nhà máy 1",
  "event_data": {
    "source_lots": [
      {"lot_id": "uuid-lot-1", "source_type": "CROP_HARVEST", "quantity": 1000, "unit": "kg"},
      {"lot_id": "uuid-lot-2", "source_type": "CROP_HARVEST", "quantity": 500, "unit": "kg"}
    ],
    "material_condition": "TOT",
    "material_temperature": 25.5
  },
  "notes": "NL đạt chất lượng"
}

Response 201:

json
{
  "success": true,
  "data": {
    "event_id": "uuid",
    "event_type": "CTE-PROC-01",
    "order_status": "IN_PROGRESS",
    "message": "Ghi nhận sự kiện Nhập nguyên liệu thành công."
  }
}

9.2.4. POST /api/v1/processing-orders/:id/package – Đóng gói ​

Request Body:

json
{
  "event_time": "2026-03-24T14:00:00+07:00",
  "performed_by_name": "Trần Văn B",
  "packaged_quantity": 4500,
  "packaged_unit": "chai",
  "packaging_spec": "Chai 500ml",
  "unit_count": 9000,
  "production_date": "2026-03-24",
  "gtin_code": "8935001234567",
  "create_logistics_unit": true,
  "logistics_units": [
    {"unit_type": "PALLET", "item_count": 4500},
    {"unit_type": "PALLET", "item_count": 4500}
  ]
}

Response 201:

json
{
  "success": true,
  "data": {
    "output_lot": {
      "id": "uuid",
      "output_lot_code": "LOT-PROC-20260324-0001",
      "expiry_date": "2027-03-24",
      "qr_code_id": "uuid-qr",
      "status": "PACKAGED"
    },
    "logistics_units": [
      {"id": "uuid", "sscc_code": "389350012345670001", "unit_type": "PALLET"},
      {"id": "uuid", "sscc_code": "389350012345670002", "unit_type": "PALLET"}
    ],
    "order_status": "COMPLETED",
    "message": "Đóng gói thành công. QR Code đã được tạo. SSCC đã được cấp."
  }
}

Response 400:

json
{
  "success": false,
  "error": {
    "code": "E-F07-005",
    "message": "Chưa có kết quả kiểm tra chất lượng ĐẠT. Vui lòng thực hiện QC trước khi đóng gói.",
    "details": []
  }
}

9.2.5. GET /api/v1/processing-orders/analysis – Thống kê tổng hợp ​

Query Parameters:

Param Kiểu Bắt buộc Mô tả
keyword String Không Từ khóa tìm kiếm
status String Không Lọc theo trạng thái
company_id String Không ID doanh nghiệp (Admin dùng)

Response 200:

json
{
  "success": true,
  "data": {
    "total": 120,
    "count_draft": 15,
    "count_in_progress": 30,
    "count_pending_qc": 10,
    "count_completed": 60,
    "count_cancelled": 5,
    "total_output_lots": 85,
    "total_logistics_units": 200
  }
}

10. Test Cases cho QA ​

10.1. TC-07-01: Lệnh sản xuất (CRUD) ​

TC ID Tên test case Precondition Bước thực hiện Expected Result Priority
TC-01-01 Tạo lệnh SX thành công ENTERPRISE_ADMIN đăng nhập 1. Nhấn "Tạo lệnh SX" 2. Nhập đầy đủ thông tin 3. Nhấn "Lưu" Lệnh SX tạo thành công, mã tự động PO-{YYYYMMDD}-{SEQ}, status = DRAFT Critical
TC-01-02 Validate trường bắt buộc 1. Để trống tên lệnh SX 2. Nhấn "Lưu" Hiển thị lỗi: "Tên lệnh SX là bắt buộc" High
TC-01-03 Ngày kết thúc < ngày bắt đầu 1. planned_end_date < planned_start_date 2. Nhấn "Lưu" Lỗi validate: "Ngày kết thúc phải sau ngày bắt đầu" High
TC-01-04 Sửa lệnh SX (DRAFT) Lệnh SX ở DRAFT 1. Nhấn "Sửa" 2. Đổi sản lượng 3. Lưu Cập nhật thành công High
TC-01-05 Sửa lệnh SX (IN_PROGRESS) Lệnh SX ở IN_PROGRESS 1. Nhấn "Sửa" Không cho phép sửa (hiển thị thông báo) High
TC-01-06 Xóa lệnh SX (DRAFT) ENTERPRISE_ADMIN, lệnh DRAFT 1. Nhấn "Xóa" 2. Xác nhận Xóa mềm thành công, deleted_at != null High
TC-01-07 Xóa lệnh SX (COMPLETED) 1. Nhấn "Xóa" Không cho phép xóa lệnh đã hoàn thành High
TC-01-08 Hủy lệnh SX ENTERPRISE_ADMIN, lệnh IN_PROGRESS 1. Nhấn "Hủy" 2. Xác nhận Status -> CANCELLED, ghi log High

10.2. TC-07-02: Ghi nhận CTE ​

TC ID Tên test case Precondition Bước thực hiện Expected Result Priority
TC-02-01 CTE-PROC-01 thành công Lệnh SX ở DRAFT 1. Thêm sự kiện Nhập NL 2. Chọn 2 lô thu hoạch từ F05 3. Nhập KL 4. Lưu Sự kiện ghi nhận, processing_inputs tạo 2 bản ghi, lệnh SX -> IN_PROGRESS Critical
TC-02-02 CTE-PROC-01 lô NL không hợp lệ 1. Chọn lô đã hết Lỗi: "Lô nguyên liệu không khả dụng" High
TC-02-03 CTE-PROC-01 KL vượt quá khả dụng Lô NL còn 500kg 1. Nhập received_quantity = 600 Lỗi: "Khối lượng tiếp nhận vượt quá khối lượng khả dụng" High
TC-02-04 CTE-PROC-02 tính hao hụt 1. Nhập weight_before = 1000, weight_after = 850 loss_percentage tự động = 15% High
TC-02-05 CTE-PROC-02 weight_after > weight_before 1. weight_after = 1100, weight_before = 1000 Lỗi validate High
TC-02-06 CTE-PROC-03 ghi nhận chế biến Lệnh SX đã có CTE-PROC-02 1. Thêm sự kiện Chế biến 2. Nhập thông tin Ghi nhận thành công Medium
TC-02-07 CTE-PROC-04 QC – ĐẠT 1. Kết quả = PASSED Sự kiện ghi nhận, lệnh SX -> PENDING_QC Critical
TC-02-08 CTE-PROC-04 QC – KHÔNG ĐẠT 1. Kết quả = FAILED 2. Để trống lý do Lỗi: "Lý do không đạt là bắt buộc" High
TC-02-09 CTE-PROC-04 QC – KHÔNG ĐẠT với lý do 1. FAILED + lý do + hành động xử lý Ghi nhận, gửi notification cho ADMIN High

10.3. TC-07-03: Đóng gói và SSCC ​

TC ID Tên test case Precondition Bước thực hiện Expected Result Priority
TC-03-01 Đóng gói thành công Lệnh SX có QC PASSED 1. Nhập thông tin đóng gói 2. Nhấn "Hoàn thành" Lô TP tạo, QR triggered (F16), lệnh SX -> COMPLETED Critical
TC-03-02 Đóng gói khi chưa có QC Lệnh SX chưa có QC 1. Nhấn "Đóng gói" Lỗi E-F07-005: "Chưa có kết quả QC ĐẠT" Critical
TC-03-03 Tự động tính HSD shelf_life = 365 ngày 1. Đóng gói với production_date = 2026-03-24 expiry_date = 2027-03-24 High
TC-03-04 Cấp SSCC thành công Toggle create_logistics_unit = true 1. Tạo 2 pallet 2 SSCC 18 chữ số, unique, check digit đúng (Mod-10) Critical
TC-03-05 SSCC unique toàn hệ thống 1. Tạo nhiều SSCC Không có 2 SSCC trùng nhau Critical
TC-03-06 Barcode GS1-128 SSCC đã tạo 1. Nhấn "In nhãn" Barcode chứa: AI(00) SSCC + AI(02) GTIN + AI(37) Qty High
TC-03-07 Đóng gói KL > KL chế biến output_weight = 1000 1. packaged_quantity = 1200 Cảnh báo W-F07-002 Medium

10.4. TC-07-04: Tích hợp (Integration) ​

TC ID Tên test case Precondition Bước thực hiện Expected Result Priority
TC-04-01 Liên kết lô thu hoạch F05 Lô thu hoạch đã tạo tại F05 1. CTE-PROC-01, chọn lô F05 mapping lưu đúng, truy ngược được Critical
TC-04-02 Liên kết lô xuất chuồng F06 Lô xuất chuồng đã tạo tại F06 1. CTE-PROC-01, chọn lô F06 mapping lưu đúng Critical
TC-04-03 Trigger QR Code F16 Đóng gói thành công Kiểm tra F16 QR Code được tạo cho lô TP Critical
TC-04-04 Lô TP hiển thị trong F08 Lô TP đã PACKAGED 1. Vào F08, tạo phiếu phân phối Lô TP xuất hiện trong dropdown High
TC-04-05 TransformationEvent EPCIS Nhập 2 lô NL -> 1 lô TP Kiểm tra DB processing_inputs có 2 bản ghi, processing_outputs có 1, mapping đúng Critical
TC-04-06 Multi-tenant isolation 2 DN khác nhau DN A không thấy lệnh SX của DN B Tất cả API có WHERE enterprise_id Critical
TC-04-07 Tham chiếu kiến trúc F05-F08 Plugin F07 đăng ký đúng Kiểm tra manifest đăng ký Plugin F07 tuân theo kiến trúc Shared Shell + Plugins High

10.5. TC-07-05: Hiệu năng (Performance) ​

TC ID Tên test case Điều kiện Expected Result Priority
TC-05-01 Load danh sách 5.000 lệnh SX DN có 5.000 lệnh Trang load <= 2 giây Medium
TC-05-02 Tìm kiếm full-text 5.000 bản ghi Kết quả trả về <= 500ms Medium
TC-05-03 Export Excel 10.000 bản ghi File xuất <= 15 giây Medium
TC-05-04 Cấp SSCC đồng thời 50 request đồng thời Không có SSCC trùng lặp High

10.6. TC-07-06: Bảo mật (Security) ​

TC ID Tên test case Bước thực hiện Expected Result Priority
TC-06-01 API không có token GET /api/v1/processing-orders không gửi Bearer Token 401 Unauthorized Critical
TC-06-02 Truy cập lệnh SX DN khác Gọi API với order_id của DN khác 403 Forbidden Critical
TC-06-03 SO_ADMIN tạo lệnh SX POST /api/v1/processing-orders bằng SO_ADMIN 403 Forbidden High
TC-06-04 SQL Injection Nhập '; DROP TABLE processing_orders;-- vào search Không lỗi, parameterized query Critical
TC-06-05 ENTERPRISE_USER xóa lệnh DELETE API bằng ENTERPRISE_USER 403 Forbidden High

11. Acceptance Criteria (Tiêu chí chấp nhận) ​

ID Tiêu chí chấp nhận Mô tả kiểm thử
AC-F07-01 Nguyên liệu đầu vào PHẢI liên kết với lô thu hoạch (F05) hoặc lô xuất chuồng (F06) CTE-PROC-01 không cho lưu nếu không chọn lô nguồn gốc
AC-F07-02 Mapping N:N giữa lô NL và lô TP phải truy ngược được Từ lô TP -> xem được tất cả lô NL đầu vào. Từ lô NL -> xem được tất cả lô TP đã tạo
AC-F07-03 Hệ thống tự động tính HSD = ngày SX + shelf_life_days Đóng gói -> expiry_date tự động điền, không cho sửa thủ công
AC-F07-04 Đóng gói trigger tạo QR Code (F16) Sau đóng gói, kiểm tra F16 có bản ghi QR mới cho lô TP
AC-F07-05 SSCC cấp theo TCVN 6754:2007: 18 chữ số, check digit Mod-10 Kiểm tra SSCC: đúng 18 chữ số, check digit đúng thuật toán Mod-10
AC-F07-06 SSCC unique toàn hệ thống Tạo nhiều SSCC -> không trùng
AC-F07-07 GS1-128 barcode chứa: AI(00) SSCC + AI(02) GTIN + AI(37) Quantity In nhãn -> barcode đúng format
AC-F07-08 Không cho đóng gói khi chưa có QC ĐẠT Đóng gói khi chưa có sự kiện QC PASSED -> lỗi
AC-F07-09 QC KHÔNG ĐẠT bắt buộc nhập lý do và hành động xử lý qc_result = FAILED, để trống failure_reason -> lỗi validate
AC-F07-10 Trạng thái lệnh SX chuyển đúng theo state machine DRAFT -> IN_PROGRESS -> PENDING_QC -> COMPLETED. Không nhảy trạng thái
AC-F07-11 Mỗi thay đổi dữ liệu phải ghi audit log Tạo/sửa/xóa/ghi CTE -> lịch sử thay đổi ghi nhận đúng
AC-F07-12 SO_ADMIN chỉ xem, không tạo/sửa/xóa SO_ADMIN không thấy nút thao tác ghi
AC-F07-13 Multi-tenant isolation: DN chỉ thấy dữ liệu của mình API luôn có WHERE enterprise_id
AC-F07-14 Lô thành phẩm sẵn sàng cho F08 phân phối khi status = PACKAGED Lô PACKAGED hiển thị trong F08 dropdown

12. Chuyển đổi trạng thái (State Transitions) ​

12.1. Lệnh sản xuất (Processing Order) ​

Từ trạng thái Hành động (Event) Chuyển sang Mô tả
(mới) Tạo lệnh SX DRAFT Lệnh SX mới tạo
DRAFT Ghi nhận CTE-PROC-01 (Nhập NL) IN_PROGRESS Bắt đầu sản xuất
IN_PROGRESS Ghi nhận CTE-PROC-04 (QC ĐẠT) PENDING_QC Chờ đóng gói
PENDING_QC Ghi nhận CTE-PROC-05 (Đóng gói) COMPLETED Hoàn thành
DRAFT Admin hủy CANCELLED Hủy khi chưa bắt đầu
IN_PROGRESS Admin hủy CANCELLED Hủy khi đang sản xuất
COMPLETED (không cho chuyển) – Không thể hủy/xóa lệnh đã hoàn thành

12.2. Lô thành phẩm (Output Lot) ​

Từ trạng thái Hành động (Event) Chuyển sang Mô tả
(mới) Đang trong quy trình PRODUCING Chưa đóng gói
PRODUCING Đóng gói thành công PACKAGED Đã đóng gói, có QR
PACKAGED Xuất kho phân phối (F08) DISTRIBUTING Đang vận chuyển
PACKAGED / DISTRIBUTING Thu hồi (recall) RECALLED Lô bị thu hồi
PACKAGED / DISTRIBUTING Quá HSD EXPIRED Hết hạn sử dụng

12.3. Đơn vị logistic (Logistics Unit) ​

Từ trạng thái Hành động (Event) Chuyển sang
(mới) Tạo khi đóng gói ACTIVE
ACTIVE Xuất kho (F08) SHIPPED
SHIPPED Nhập kho đích (F08) RECEIVED

13. Notification List (Danh sách thông báo) ​

ID Sự kiện Người nhận Kênh Nội dung thông báo
N-F07-01 Đóng gói hoàn thành, lô TP tạo thành công ENTERPRISE_ADMIN In-app "Lệnh SX [mã] đã đóng gói thành công. Lô TP [mã lô] đã tạo với [X] đơn vị. QR Code đã được cấp."
N-F07-02 Kết quả QC KHÔNG ĐẠT ENTERPRISE_ADMIN In-app, Email "Lệnh SX [mã] KHÔNG ĐẠT kiểm tra chất lượng. Lý do: [lý do]. Cần xử lý trước khi đóng gói."
N-F07-03 Lô thành phẩm sắp hết hạn (30 ngày) ENTERPRISE_ADMIN In-app, Email "Lô thành phẩm [mã lô] sẽ hết hạn sử dụng vào [ngày]. Vui lòng xử lý."
N-F07-04 Lô thành phẩm đã hết hạn ENTERPRISE_ADMIN In-app, Email, Push "Lô thành phẩm [mã lô] ĐÃ HẾT HẠN SỬ DỤNG từ [ngày]. Không được phân phối."
N-F07-05 Lệnh SX bị hủy ENTERPRISE_USER (người tạo) In-app "Lệnh sản xuất [mã] đã bị hủy bởi [tên admin]."
N-F07-06 SSCC đã cấp cho đơn vị logistic ENTERPRISE_ADMIN, ENTERPRISE_USER In-app "Đã cấp [X] mã SSCC cho lệnh SX [mã]. Sẵn sàng xuất kho."

14. Error / Warning Message Handling ​

ID Mã lỗi Mô tả Điều kiện kích hoạt Hành động xử lý
ERR01 E-F07-001 Không có quyền truy cập chức năng này User không có role phù hợp Ẩn nút thao tác hoặc redirect
ERR02 E-F07-002 Lệnh sản xuất không tồn tại hoặc đã bị xóa order_id không tìm thấy hoặc deleted_at != null Redirect về danh sách, thông báo lỗi
ERR03 E-F07-003 Không thể thực hiện thao tác ở trạng thái hiện tại Sửa lệnh COMPLETED, đóng gói khi chưa QC Thông báo trạng thái hiện tại và thao tác cho phép
ERR04 E-F07-004 Dữ liệu nhập không hợp lệ Validation server-side thất bại Highlight trường lỗi, hiển thị chi tiết
ERR05 E-F07-005 Chưa có kết quả kiểm tra chất lượng ĐẠT Đóng gói khi chưa có QC PASSED/CONDITIONAL Thông báo cần QC trước
ERR06 E-F07-006 Lô nguyên liệu không khả dụng Lô đã hết hoặc không tồn tại Thông báo lô không hợp lệ
ERR07 E-F07-007 Khối lượng tiếp nhận vượt quá khối lượng khả dụng received_quantity > available quantity của lô NL Hiển thị KL khả dụng còn lại
ERR08 E-F07-008 Upload file vượt kích thước cho phép File > 5MB (ảnh) hoặc > 10MB (tài liệu QC) Thông báo giới hạn
ERR09 E-F07-009 Upload file sai định dạng File không phải JPEG/PNG (ảnh) hoặc PDF (tài liệu) Thông báo định dạng cho phép
ERR10 E-F07-010 Lỗi cấp SSCC GS1 Company Prefix chưa cấu hình cho DN Yêu cầu ADMIN cấu hình GS1 tại F01
ERR11 E-F07-011 Không thể hủy lệnh sản xuất đã hoàn thành Hủy lệnh ở trạng thái COMPLETED Thông báo không cho phép
ERR12 E-F07-012 Khối lượng sau sơ chế lớn hơn khối lượng trước sơ chế weight_after > weight_before (CTE-PROC-02) Lỗi validate: "Khối lượng sau sơ chế không được lớn hơn khối lượng trước sơ chế"
WARN01 W-F07-001 Lô nguyên liệu có chất lượng KÉM material_condition = KÉM Hiển thị cảnh báo, cho phép tiếp tục
WARN02 W-F07-002 Khối lượng đóng gói lớn hơn khối lượng chế biến packaged_quantity > output_weight từ CTE-PROC-03 Cảnh báo xác nhận, cho phép lưu
WARN03 W-F07-003 Lô thành phẩm sắp hết hạn sử dụng expiry_date trong 30 ngày tới Badge cảnh báo vàng trên bản ghi

15. Ma trận truy xuất (Traceability Matrix) ​

UC ID Màn hình (SCR) Tiêu chí chấp nhận (AC) Notification Error/Warning Test Cases
UC-F07-01 (Xem danh sách) SCR-F07-01 AC-F07-12, AC-F07-13 - E-F07-001 TC-01-01 -> TC-01-08
UC-F07-02 (Tạo lệnh SX) SCR-F07-01, SCR-F07-02 AC-F07-11 - E-F07-004 TC-01-01 -> TC-01-03
UC-F07-03 (Sửa lệnh SX) SCR-F07-02 AC-F07-10, AC-F07-11 - E-F07-003, E-F07-004 TC-01-04, TC-01-05
UC-F07-04 (CTE-PROC-01) SCR-F07-03, SCR-F07-04 AC-F07-01, AC-F07-02, AC-F07-13 - E-F07-006, E-F07-007, W-F07-001 TC-02-01 -> TC-02-03
UC-F07-05 (CTE-PROC-02) SCR-F07-03, SCR-F07-04 AC-F07-11 - E-F07-004, E-F07-012 TC-02-04, TC-02-05
UC-F07-06 (CTE-PROC-03) SCR-F07-03, SCR-F07-04 AC-F07-11 - E-F07-004 TC-02-06
UC-F07-07 (CTE-PROC-04) SCR-F07-03, SCR-F07-06 AC-F07-08, AC-F07-09, AC-F07-11 N-F07-02 E-F07-004 TC-02-07 -> TC-02-09
UC-F07-08 (CTE-PROC-05) SCR-F07-03, SCR-F07-05 AC-F07-03, AC-F07-04, AC-F07-05, AC-F07-06, AC-F07-07, AC-F07-10 N-F07-01, N-F07-06 E-F07-005, E-F07-010, W-F07-002 TC-03-01 -> TC-03-07
UC-F07-09 (CTE-PROC-06) SCR-F07-03, SCR-F07-04 AC-F07-11 - E-F07-004 -
UC-F07-10 (Xem chi tiết) SCR-F07-03 AC-F07-02, AC-F07-12 - E-F07-002 -
UC-F07-11 (Hủy lệnh) SCR-F07-01 AC-F07-10, AC-F07-11 N-F07-05 E-F07-011 TC-01-08
UC-F07-12 (DV logistic) SCR-F07-07 AC-F07-05, AC-F07-06, AC-F07-07 - - TC-03-04 -> TC-03-06
- (Tích hợp) - AC-F07-01, AC-F07-14 N-F07-03, N-F07-04 - TC-04-01 -> TC-04-07
- (Hiệu năng) - - - - TC-05-01 -> TC-05-04
- (Bảo mật) - AC-F07-13 - - TC-06-01 -> TC-06-05

16. Quy tắc nghiệp vụ (Business Rules) ​

Mã Quy tắc Giải thích
BR-F07-01 Nguyên liệu đầu vào PHẢI liên kết với lô thu hoạch (F05) hoặc lô xuất chuồng (F06) Đảm bảo truy xuất nguồn gốc theo nguyên tắc 1-up/1-down của TCVN 12850:2019
BR-F07-02 Mapping N:N: 1 lô thành phẩm có thể chứa nhiều lô nguyên liệu và ngược lại Mô hình TransformationEvent (EPCIS): Input lots A + B -> Output lot C
BR-F07-03 HSD tự động tính = ngày SX + default_shelf_life_days, không cho sửa thủ công Đảm bảo tính nhất quán, tránh sai sót nhập liệu
BR-F07-04 Đóng gói PHẢI có kết quả QC ĐẠT (PASSED hoặc CONDITIONAL) trước đó Đảm bảo chất lượng sản phẩm trước khi ra thị trường
BR-F07-05 SSCC cấp theo TCVN 6754:2007: 18 chữ số = Extension (1) + GS1 Prefix (var) + Serial Ref (var) + Check Digit (1, Mod-10) Tuân thủ tiêu chuẩn quốc gia và quốc tế GS1 về mã đơn vị logistic
BR-F07-06 SSCC unique toàn hệ thống (không chỉ trong DN) Mã SSCC là unique toàn cầu theo GS1
BR-F07-07 1 SSCC = 1 đơn vị logistic (pallet/thùng/container) Mỗi đơn vị logistic có duy nhất 1 mã SSCC
BR-F07-08 Đóng gói trigger tự động tạo QR Code qua F16 Liên thông với module cấp mã QR, đảm bảo truy xuất từ người tiêu dùng
BR-F07-09 Nhãn vận chuyển GS1-128 PHẢI chứa: AI(00) SSCC + AI(02) GTIN + AI(37) Quantity Tuân thủ TCVN 13275:2020 về vật mang dữ liệu
BR-F07-10 QC KHÔNG ĐẠT bắt buộc nhập lý do và hành động xử lý Đảm bảo trách nhiệm giải trình, truy xuất sự cố chất lượng
BR-F07-11 Lệnh SX COMPLETED không thể hủy hoặc xóa Bảo toàn dữ liệu truy xuất, audit trail
BR-F07-12 Mỗi thay đổi phải ghi audit log với Tuân thủ TCVN 12850 và FDA 21 CFR Part 11
BR-F07-13 Multi-tenant: mỗi truy vấn PHẢI có WHERE enterprise_id = :current_enterprise_id Cách ly dữ liệu giữa các doanh nghiệp
BR-F07-14 Soft delete cho lệnh SX và lô thành phẩm (deleted_at) Giữ dữ liệu lịch sử, không mất truy xuất
BR-F07-15 Khối lượng sau sơ chế <= khối lượng trước sơ chế Đảm bảo tính hợp lý (sơ chế chỉ giảm, không tăng khối lượng)
BR-F07-16 Trạng thái lệnh SX chuyển đúng theo state machine: DRAFT -> IN_PROGRESS -> PENDING_QC -> COMPLETED Không cho nhảy trạng thái, đảm bảo quy trình
BR-F07-17 Dữ liệu CTE phải ghi nhận đầy đủ KDE theo mô hình 5W (TCVN 12850) Who, What, Where, When, Why tại mỗi CTE
BR-F07-18 GS1 Company Prefix phải được cấu hình cho DN trước khi cấp SSCC DN cần đăng ký GS1 VN để có prefix

17. Ràng buộc & Giả định (Constraints / Assumptions) ​

17.1. Ràng buộc ​

17.2. Giả định ​


18. Phụ lục (Appendix) ​

18.1. EPCIS Event Mapping cho F07 ​

EPCIS Event Type CTE tương ứng Mô tả Ví dụ
TransformationEvent CTE-PROC-01 -> CTE-PROC-05 Đầu vào (lô NL) -> Đầu ra (lô TP) Lô ớt 500kg + Lô tỏi 200kg -> Lô tương ớt 600 chai
ObjectEvent (OBSERVE) CTE-PROC-02, CTE-PROC-03 Quan sát / ghi nhận thao tác trên đối tượng Rửa phân loại 1000kg ớt
ObjectEvent (ADD) CTE-PROC-06 Nhập kho bảo quản Lô TP nhập kho lạnh
AggregationEvent (ADD) CTE-PROC-05 (khi tạo SSCC) Gộp nhiều đơn vị SP vào 1 đơn vị logistic 4500 chai vào 1 pallet SSCC

18.2. Cấu trúc SSCC (TCVN 6754:2007) ​

SSCC – 18 chữ số:
+-----------+---------------------+-----------------+-------------+
| Extension | GS1 Company Prefix  | Serial Ref      | Check Digit |
| Digit     | (do GS1 VN cấp)    | (6-9 chữ số)   |   (1 số)    |
| (0-9)     |                     | DN tự quản lý   |   Mod-10    |
+-----------+---------------------+-----------------+-------------+
  1 chữ số    7-10 chữ số           6-9 chữ số        1 chữ số
              (tổng = 17 chữ số trước check digit)

Ví dụ: GS1 Prefix = 8935001234
  SSCC = 3 8935001234 567890 1
         ^ ^          ^      ^
         |  Prefix     Serial Check
         Extension

Thuật toán Check Digit (Mod-10):

  1. Từ phải sang trái (17 chữ số), nhân luân phiên x3, x1, x3, x1...
  2. Cộng tổng tất cả tích
  3. Check Digit = (10 - (tổng % 10)) % 10

18.3. Cấu trúc GS1-128 Barcode cho nhãn vận chuyển ​

AI(00) + SSCC + AI(02) + GTIN-14 + AI(37) + Quantity
  00     389350012345670001   02   08935001234567   37   4500

18.4. Danh mục phương pháp chế biến ​

Mã Tên Mô tả
NẤU Nấu Nấu chín, hầm, hấp
TRỘN Trộn Trộn nguyên liệu, phối trộn
LÊN_MEN Lên men Lên men tự nhiên hoặc nhân tạo
XÔNG_KHÓI Xông khói Xông khói nóng/lạnh
SẤY Sấy Sấy khô, sấy thăng hoa
ÉP Ép Ép nước, ép dầu
CHIẾT_XUẤT Chiết xuất Chiết xuất tinh chất
KHÁC Khác Phương pháp khác

18.5. Danh mục hoạt động sơ chế ​

Mã Tên
RỬA Rửa sạch
PHÂN_LOẠI Phân loại
CẮT Cắt, thái
BÓC_VỎ Bóc vỏ, lột vỏ
LÀM_SẠCH Làm sạch, loại bỏ tạp chất
KHÁC Khác

18.6. Glossary (Thuật ngữ) ​

Thuật ngữ Giải thích
CTE Critical Tracking Event – Sự kiện theo dõi trọng yếu
KDE Key Data Element – Phần tử dữ liệu chính
SSCC Serial Shipping Container Code – Mã container vận chuyển nối tiếp (18 chữ số)
GTIN Global Trade Item Number – Mã sản phẩm toàn cầu
GLN Global Location Number – Mã địa điểm toàn cầu
EPCIS Electronic Product Code Information Services – Dịch vụ thông tin mã sản phẩm điện tử
TransformationEvent Sự kiện chuyển đổi: đầu vào -> đầu ra khác (EPCIS)
AggregationEvent Sự kiện gộp: gộp nhiều đơn vị con vào đơn vị cha (EPCIS)
ObjectEvent Sự kiện đối tượng: quan sát/thao tác trên 1+ đối tượng (EPCIS)
QC Quality Control – Kiểm tra chất lượng
HSD Hạn Sử Dụng
AI Application Identifier – Mã ứng dụng (GS1)
GS1-128 Mã vạch 1D dùng trong chuỗi cung ứng (GS1)
Mod-10 Thuật toán tính check digit cho mã GS1
N:N Quan hệ nhiều-nhiều (Many-to-Many)
Soft delete Xóa mềm – đánh dấu deleted_at thay vì xóa khỏi DB

18.7. Tham chiếu kiến trúc ​

Tài liệu Mô tả Liên quan
SRS_TXNG-F05-F08_Kien_Truc_Nhat_Ky_San_Xuat.md Kiến trúc Hybrid (Shared Shell + Plugins) cho toàn bộ hệ thống Nhật ký Sản xuất F07 là 1 plugin trong kiến trúc F05-F08. Sử dụng các shared components: Shell Layout, CTE Timeline, Audit Log, Image Upload, State Machine
SRS_TXNG-F05_Nhat_Ky_Trong_Trot.md Nhật ký Trồng trọt – nguồn nguyên liệu từ cây trồng F07 nhận lô thu hoạch (CROP_HARVEST) từ F05 qua CTE-PROC-01
SRS_TXNG-F06_Nhat_Ky_Chan_Nuoi.md Nhật ký Chăn nuôi – nguồn nguyên liệu từ vật nuôi F07 nhận lô xuất chuồng (LIVESTOCK_OUTPUT) từ F06 qua CTE-PROC-01
SRS_TXNG-F08_Nhat_Ky_Phan_Phoi_Van_Chuyen.md Nhật ký Phân phối – Vận chuyển F07 cung cấp lô thành phẩm (PACKAGED) và SSCC cho F08 phân phối
SRS_TXNG-F16_Cap_Ma_QRcode.md Cấp mã QR Code F07 trigger F16 tạo QR Code khi đóng gói (CTE-PROC-05)

Tài liệu này được tạo và cần được review bởi BA, Tech Lead, và QA Lead trước khi triển khai.