📖 Hướng dẫn Sử dụng: Quản Trị Kho Hàng & Chuỗi Cung Ứng (Inventory Hub)

1. 📌 Định nghĩa & Mục đích Tính năng (Overview)

• Tên tính năng: Phân hệ Quản Trị Kho Hàng & Chuỗi Cung Ứng Toàn Diện (Inventory Hub - 3-Tier Architecture).
• Phân hệ áp dụng: 🌐 Web Dashboard (Dành cho Quản trị viên, Quản lý kho, Agency PM) & 📱 Zalo Mini App (Dành cho Field Worker / PG / PB / Kỹ thuật viên).
• Vấn đề giải quyết (Problem Statement):
  • Trước đây, việc luân chuyển hàng mẫu (sampling), quà tặng (premium), đồng phục và thiết bị POSM tại điểm bán thường bị thất thoát, không khớp số liệu giữa kho tổng và điểm bán thực tế.
  • Thiếu quy trình dự trù, phê duyệt cấp phát trước ca làm và cơ chế đối soát thu hồi tài sản sau khi kết thúc ca làm.
• Lợi ích mang lại (Key Benefits):
  • Kiến trúc 3 Tầng chuẩn hóa: Phân tách rõ ràng giữa Lệnh Kho & Dự trù (Stock Orders) ➡️ Giao dịch Vật lý & Sổ Cái (Stock Transactions & Ledger) ➡️ Tồn Kho Tức Thời (Stock Balances Snapshot).
  • 8 Phân loại Tài sản chuyên biệt: Quản lý chi tiết theo nhóm hàng (product, premium, sampling, posm, uniform, equipment, consumable, other) với cờ thu hồi (is_returnable), định mức an toàn (min_stock_level) và mã vạch (barcode).
  • Khép kín vòng lặp ca làm việc: Worker nhận vật tư đầu ca ➡️ Bán hàng & phát sampling trong ca ➡️ Thu hồi hoàn trả vật tư cuối ca ngay trên Zalo Mini App.
  • Quy đổi đóng gói đa cấp: Hỗ trợ quy đổi Thùng / Lốc / Lẻ trực quan khi tạo phiếu xuất/nhập.
  • Kiểm kê & Cân đối kho tức thời: Chốt kiểm kê sai lệch số lượng và tự động điều chỉnh tồn kho chính xác theo sổ cái kế toán.

2. 👥 Đối tượng Sử dụng & Phân Quyền (Target Audience & IAM)

3. 📖 Thuật ngữ & Khái niệm Nghiệp vụ (Glossary)

• Lệnh kho (Stock Order): Phiếu đề xuất / kế hoạch cấp phát hoặc thu hồi vật tư (trước khi hàng hoá di chuyển vật lý). Khi duyệt lệnh kho, hệ thống tự động khóa số lượng giữ chỗ (booked_unit_qty).
• Giao dịch kho (Stock Transaction): Bút toán dịch chuyển vật tư thực tế gồm 6 loại: Nhập kho (inbound), Xuất kho (outbound), Điều chuyển (transfer), Hủy/Thanh lý (disposal), Kiểm kê cân đối (adjustment), và Thu hồi hoàn trả (return).
• Tồn kho tức thời (Stock Balance): Số liệu tồn kho tại một thời điểm gồm: Tồn thực tế (unit_qty), Đang giữ chỗ cho lệnh kho (booked_unit_qty), và Tồn khả dụng (available_qty = unit_qty - booked_unit_qty).
• Tài sản thu hồi (Returnable Asset): Các vật tư có thuộc tính is_returnable = true (Đồng phục, Bàn ghế POSM, Standee, Máy móc) bắt buộc Worker phải hoàn trả lại kho sau khi kết thúc ca làm việc.
• Sổ Thẻ Kho (Movement Ledger): Báo cáo dòng thời gian lịch sử mọi biến động nhập/xuất kèm số dư tồn kho tích lũy sau mỗi giao dịch.

4. 🔄 Luồng Vận Hành Toàn Diện (End-to-End Workflow)

5. 🛠 Hướng Dẫn Thao Tác Chi Tiết Trên Web Dashboard

🔹 5.1. Bảng Điều Khiển & Cảnh Báo Kho (Tab Overview)

1. Truy cập: Điều hướng menu Kho hàng (Stock) ➡️ Chọn tab Tổng quan (Overview).
2. Theo dõi chỉ số Real-time:
   • Tổng danh mục SKU: Số lượng mã hàng hoá đang quản lý trong workspace.
   • Tồn khả dụng: Tổng số lượng sản phẩm sẵn sàng xuất kho phục vụ ca làm.
   • Lệnh chờ duyệt: Số lượng Lệnh kho cần cấp quản lý phê duyệt.
   • Cảnh báo tồn dưới định mức (Safety Stock) & Cảnh báo hết hàng (Stockout): Danh sách sản phẩm có số tồn thấp hơn mức min_stock_level để kịp thời lên kế hoạch nhập hàng.

🔹 5.2. Quản Lý Lệnh Kho & Cấp Phát (Tab Orders)

1. Tạo Lệnh Kho mới:
   • Bấm nút ”+ Tạo lệnh kho”.
   • Chọn Loại lệnh (Cấp phát nhân viên, Nhập hàng NCC, Điều chuyển, Thu hồi sau ca).
   • Chọn Kho xuất / Kho nhập, Địa điểm làm việc, và Mục đích cấp phát.
   • Thêm danh sách vật tư và số lượng dự trù.
2. Phê duyệt Lệnh Kho:
   • Quản lý kho click vào dòng lệnh có trạng thái Chờ duyệt (pending).
   • Xem xét số lượng yêu cầu và số lượng duyệt (approved_qty).
   • Bấm “Phê duyệt” ➡️ Hệ thống tự động kích hoạt trigger khóa giữ chỗ số lượng vật tư trên kho xuất.
3. Thực hiện Xuất kho theo Lệnh:
   • Bấm “Tạo phiếu xuất” từ Lệnh kho đã duyệt ➡️ Tự động điền danh sách hàng hoá sang phiếu Giao dịch kho.

🔹 5.3. Tạo & Xử Lý Giao Dịch Kho (Tab Transactions)

1. Tạo Giao dịch kho thủ công:
   • Bấm nút ”+ Tạo giao dịch”.
   • Chọn Loại giao dịch (inbound, outbound, transfer, disposal).
   • Chọn Kho xuất và Kho nhập (hỗ trợ tìm kiếm theo tên và địa chỉ kho).
2. Chọn Sản phẩm & Quy đổi Đơn vị Đóng gói:
   • Tìm kiếm sản phẩm theo Tên / SKU / Mã vạch. Ô chọn hiển thị tức thời số tồn kho thực tế và khả dụng.
   • Bấm nút “Quy đổi” để mở modal chia nhỏ Thùng / Lốc / Lẻ:
     • Nhập số lượng Thùng (Pack) và Lốc (Bundle).
     • Hệ thống tự động tính toán tổng số lượng lẻ và tạo chuỗi diễn giải trực quan (ví dụ: 2 thùng + 1 lốc = 54 lon).
3. Tải lên Chứng từ / Biên bản Bàn giao:
   • Kéo thả hoặc chọn ảnh biên bản bàn giao có chữ ký hai bên.
   • Bấm “Tạo giao dịch” hoặc “Xác nhận ngay” để cập nhật số tồn kho.
   • Với giao dịch được tạo từ task, mở Chi tiết ca làm để xem ảnh/chứng từ kho, duyệt hoặc yêu cầu Worker nộp lại bằng chứng. Các giao dịch đã có proof được duyệt không thể sửa các thuộc tính cấu trúc.

🔹 5.4. Quản Lý Danh Mục Hàng Hoá & Vật Tư (Tab Assets)

1. Thêm Hàng hoá mới:
   • Nhập Mã SKU, Mã vạch (Barcode), Tên hàng hoá, Đơn vị tính cơ sở.
   • Chọn Phân loại (Asset Type):
     • product: Hàng hoá bán ra.
     • premium: Quà tặng khuyến mãi kèm theo.
     • sampling: Hàng mẫu dùng thử miễn phí.
     • posm: Vật phẩm quảng cáo tại điểm bán (Standee, Hanger, Booth).
     • uniform: Đồng phục nhân viên PG/PB.
     • equipment: Máy móc, dụng cụ hỗ trợ (Máy tính bảng, Đầu đọc mã vạch).
     • consumable: Vật tư tiêu hao (Băng keo, Túi nilon, Ly giấy).
     • other: Khác.
   • Bật cờ “Thu hồi sau ca (is_returnable)” đối với Uniform, POSM và Equipment.
   • Cài đặt Định mức tồn tối thiểu (Safety Stock Level) và Quy cách đóng gói (Hệ số Thùng/Lốc).

🔹 5.5. Kiểm Kê & Cân Đối Kho (Tab Audits)

1. Khởi tạo Phiếu Kiểm kê:
   • Chọn kho hàng cần kiểm đếm.
   • Hệ thống tự động tải số tồn sổ sách tại thời điểm mở phiếu.
2. Ghi nhận Số lượng Thực tế:
   • Nhập số lượng thực đếm (actual_unit_qty).
   • Đối với các mặt hàng có chênh lệch, chọn nguyên nhân sai lệch: Hư hỏng (damage), Hết hạn (expired), Thất thoát (loss), Sử dụng mẫu (sampling_usage), Lỗi nhập liệu (data_error), Khác (other).
3. Chốt Cân Đối Kho:
   • Bấm “Chốt kiểm kê & Cân đối kho”.
   • Hệ thống thực thi RPC tự động sinh bút toán điều chỉnh (adjustment) và đưa số dư tồn kho về đúng thực tế.

🔹 5.6. Sổ Thẻ Kho & Báo Cáo Xuất - Nhập - Tồn (Tab Reports & Ledger)

1. Xem Sổ Thẻ Kho (Movement Ledger):
   • Lọc theo từng mặt hàng và khoảng thời gian.
   • Theo dõi từng dòng phát sinh: Mã giao dịch, loại bút toán, số lượng nhập/xuất, và số dư luỹ kế sau giao dịch.
2. Xuất Báo cáo Xuất - Nhập - Tồn (Summary Report):
   • Xem bảng tổng hợp Đầu kỳ - Nhập trong kỳ - Xuất trong kỳ - Điều chỉnh - Cuối kỳ.
   • Bấm “Xuất CSV” để tải file báo cáo kế toán.

📱 6. Hướng Dẫn Dành Cho Worker Trên Zalo Mini App

1. Mở Nhiệm Vụ Kho trong Ca Làm:
   • Khi nhận ca làm có Task Giao dịch kho, Worker bấm vào nhiệm vụ để mở form giao dịch.
2. Chọn Nhanh Vật Tư & Quét Mã Vạch:
   • Sử dụng thanh tìm kiếm hoặc bộ lọc phân loại để chọn danh mục vật tư.
   • Các vật tư có cờ “Thu hồi sau ca” được gắn huy hiệu màu vàng cảnh báo.
3. Chụp Ảnh Biên Bản Bàn Giao:
   • Chụp rõ nét biên bản giao nhận có chữ ký đại diện cửa hàng / kho.
   • Có thể chụp nhiều ảnh chứng từ không giới hạn số trang.
4. Nộp Bằng Chứng:
   • Bấm “Nộp bằng chứng” ➡️ Giao dịch được ghi nhận tức thời, không làm gián đoạn tiến độ công việc trong ca.

🚨 7. Xử Lý Lỗi Thường Gặp (Troubleshooting & FAQs)