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()
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
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
Hệ thống sử dụng PostgreSQL >= 14 làm CSDL chính.
File storage sử dụng MinIO/S3 cho hình ảnh và tài liệu.
API tuân thủ RESTful, response format JSON.
Authentication sử dụng JWT Bearer Token.
Tất cả timestamp lưu dạng TIMESTAMPTZ (UTC), hiển thị theo timezone user (Asia/Ho_Chi_Minh).
Tìm kiếm full-text sử dụng PostgreSQL tsvector.
SSCC generation cần có GS1 Company Prefix đã cấu hình cho DN tại F01.
Tích hợp F16 (QR Code) phải hoàn tất trước khi triển khai đóng gói.
Chức năng F07 tuân theo kiến trúc Hybrid (Shared Shell + Plugins) định nghĩa tại SRS_TXNG-F05-F08.
17.2. Giả định
Bảng enterprises, users, products, facilities đã tồn tại từ module F01, F02, F03.
Lô thu hoạch (F05) và lô xuất chuồng (F06) đã có API cung cấp danh sách lô khả dụng.
Module F16 (Cấp mã QR Code) có API nhận yêu cầu tạo QR tự động.
Doanh nghiệp đã đăng ký GS1 VN và có Company Prefix trước khi sử dụng chức năng cấp SSCC.
Giao diện hỗ trợ responsive cho desktop (>=1280px) và tablet (>=768px).
Mô hình EPCIS được áp dụng ở mức logic, chưa yêu cầu tích hợp trực tiếp với EPCIS server tại v1.0.
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):
Từ phải sang trái (17 chữ số), nhân luân phiên x3, x1, x3, x1...
Cộng tổng tất cả tích
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.