Đặc Tả Hợp Nhất Vật Tư Đơn Hàng (OrderItemMaterials)

📖 Nguyên Tắc Nghiệp Vụ & Quy Trình Khởi Tạo

Business Flow

Khi ra đơn hàng bán lẻ (Sales Order), hệ thống MES tự động phân rã nguyên vật liệu định mức từ thiết kế kỹ thuật Variant sang thực thể OrderItemMaterial gắn trực tiếp theo dòng đơn hàng. Quy trình cụ thể như sau:

Truy xuất cấu hình Variant / Set

Hệ thống đọc danh sách vật tư (`VariantMaterial`) đã được định nghĩa cứng trong hồ sơ thiết kế kỹ thuật R&D.

Phân loại vai trò vật tư tự động

Hệ thống duyệt từng dòng vật tư. Vật tư nào có `assemblyQty1 > 0` hoặc `assemblyQty2 > 0` sẽ được phân loại là PRODUCTION (Vật tư sản xuất). Vật tư nào có `packagingQty > 0` sẽ được phân loại là PACKAGING (Vật tư đóng gói).

Tính toán định lượng nhân số lượng đơn

Số lượng khởi tạo = (Định mức gốc + Hao hụt Extra) * Số lượng sản phẩm trên đơn hàng (OrderItem.quantity). Dữ liệu này được lưu trực tiếp vào bảng order_item_materials.

Hợp nhất tùy chỉnh (Override) và Nhập thêm

Bên cạnh định mức tự động, Planner có toàn quyền chỉnh sửa trực tiếp số lượng, ghi chú hoặc click nút "Thêm vật tư" để nhập thêm nguyên vật liệu mới theo yêu cầu riêng biệt của đơn hàng.

📡 REST API Endpoints

API Spec

Endpoints hợp nhất quản lý CRUD vật tư theo dòng đơn hàng:

GET /api/admin/order-items/:itemId/materials

Lấy danh sách vật tư. Hỗ trợ query ?type=PRODUCTION|PACKAGING để lọc.

POST /api/admin/order-items/:itemId/materials

Thêm vật tư đính kèm ngoài định mức. Payload:

{
  "materials": [
    {
      "materialId": 10,
      "type": "PRODUCTION",
      "quantity": 5,
      "note": "Ốc dự phòng"
    }
  ]
}

PUT /api/admin/order-items/:itemId/materials/:id

Sửa đổi số lượng hoặc ghi chú của vật tư đính kèm.

DELETE /api/admin/order-items/:itemId/materials/:id

Xóa một dòng vật tư nhập thêm.

💾 Mô Hình Thực Thể Prisma Model (DDL)

Database Table

Bảng order_item_materials thay thế hoàn toàn bảng order_packaging_materials cũ, gộp cả vật tư đóng gói và sản xuất vào chung một bảng và sử dụng trường phân loại type:

// file: prisma/providers/mysql/prisma-models/order.prisma

model OrderItemMaterial {
  id           Int      @id @unique @default(autoincrement()) @map("id")
  isDeleted    Boolean  @default(false) @map("is_deleted")
  orderItemId  Int      @map("order_item_id")
  materialId   Int      @map("material_id")
  type         String   @db.VarChar(20) @map("type") // "PRODUCTION" hoặc "PACKAGING"
  quantity     Decimal  @db.Decimal(10, 2) @map("quantity")
  note         String?  @db.Text @map("note")
  createdAt    DateTime @default(now()) @map("created_at")
  updatedAt    DateTime @default(now()) @updatedAt @map("updated_at")

  orderItem    OrderItem @relation("orderItemMaterialRelation", fields: [orderItemId], references: [id])
  material     Material  @relation("materialOrderItemRelation", fields: [materialId], references: [id])

  @@map("order_item_materials")
}

⚖️ So Sánh Khác Biệt Giữa 2 Mô Hình Thiết Kế

Architecture Analysis

Đặc tính so sánh	Mô hình cũ (OrderPackagingMaterial)	Mô hình mới (OrderItemMaterial Hợp Nhất)
Tên bảng CSDL	order_packaging_materials	order_item_materials
Khả năng quản lý	Chỉ lưu trữ vật tư bao bì, đóng gói đính kèm đơn.	Lưu cả vật tư sản xuất (PRODUCTION) và vật tư đóng gói (PACKAGING).
Khởi tạo dữ liệu tự động	Không có (chỉ lưu những gì người dùng tạo tay thêm).	Tự động nhân định mức của Variant (assembly/packaging qty) nhân với số lượng đơn hàng bán.
Endpoints REST API	/order-items/:id/packaging-materials	/order-items/:id/materials?type=...
Trực quan hóa UI	Hiện chung một bảng đóng gói đơn giản, thô sơ.	Tách biệt thành 2 bảng/tab riêng biệt (Vật tư sản xuất & Vật tư đóng gói) cùng ẩn hiện các cột số lượng phù hợp.

🖥️ Mô Phỏng Sa Bàn Giao Diện Chi Tiết Đơn Hàng (Materials View)

Interactive Mockup

Trải nghiệm các chức năng tương tác thực tế của hệ thống sau khi hợp nhất vật tư đơn hàng:

Chế độ xem: