# Hướng dẫn cập nhật tồn kho và phân bổ đơn đã thanh toán

## 1. Cách hiểu các số liệu

- **Đã đặt (đã trả, đang mở):** tổng nhu cầu của đơn đã xác nhận thanh toán, chưa hủy, chưa hết hạn và chưa hoàn tất.
- **Đã giao:** số lượng đã ghi nhận xuất/giao thực tế.
- **Đã giữ sẵn:** số cuốn cụ thể kho đã dành cho đơn đã thanh toán. Chỉ giữ chỗ, chưa trừ tồn vật lý.
- **Chưa phân bổ:** phần chưa giao nhưng chưa có cuốn cụ thể được giữ.
- **Tồn khả dụng:** tồn vật lý trừ tổng lượng đang giữ.
- **Điều chuyển đề xuất:** phần có thể lấy từ cơ sở khác của đúng SKU.
- **Cần bổ sung:** phần thiếu còn lại sau khi đã ưu tiên điều chuyển đúng SKU.

Đơn chưa thanh toán không được giữ hàng và không tham gia kế hoạch điều chuyển/bổ sung.

## 2. Cập nhật lên hosting

1. Sao lưu file website và database hiện tại.
2. Giải nén gói cập nhật rồi tải các file lên đúng thư mục tương ứng, giữ nguyên cấu trúc đường dẫn.
3. Trong phpMyAdmin, chọn đúng database đang chạy website.
4. Chạy file `migrations/20260827_inventory_paid_fifo_reconciliation.sql`.
5. Nếu ba migration tồn kho ngày 2026-08-27 chưa từng được chạy, chạy thêm theo thứ tự:
   - `20260827_inventory_physical_stock_and_planning.sql`
   - `20260827_paid_only_inventory_allocation.sql`
   - `20260827_inventory_transfer_workflow.sql`
6. Đăng nhập quản trị, mở **Tồn kho** và chọn phạm vi **Tất cả phân hiệu** hoặc một cơ sở.
7. Kiểm tra khối **Hiểu nhanh tình trạng phân bổ**. Nếu có nút **Phân bổ lại theo FIFO**, mở hộp xác nhận và thực hiện một lần.

Migration mới chỉ tạo bảng lịch sử chạy FIFO; tự nó không thay đổi dữ liệu đơn hàng hoặc tồn kho. Thao tác FIFO chỉ tăng “đã giữ” và giảm “chưa phân bổ”; tồn vật lý không thay đổi.

## 3. Kết quả kiểm thử trên bản sao database hosting ngày 27/08/2026

- Đơn đã thanh toán đang mở: **827 đơn / 4.184 cuốn**.
- Trước phân bổ lại: **487 cuốn đã giữ / 3.697 cuốn chưa phân bổ**.
- Có thể phân bổ ngay theo FIFO: **2.471 cuốn cho 766 đơn**.
- Sau phân bổ lại: **2.958 cuốn đã giữ / 1.226 cuốn chưa phân bổ**.
- Tồn vật lý trước và sau thao tác: **13.133 cuốn**, không thay đổi.
- Đề xuất điều chuyển nội bộ: **549 cuốn**.
- Cần bổ sung sau điều chuyển: **677 cuốn**.
- Có **1 đơn đã hoàn tất nhưng còn 5 cuốn chưa ghi nhận giao**; hệ thống hiển thị cảnh báo riêng và không tự phân bổ lại đơn này.

Các số trên hosting có thể khác nếu đơn hàng hoặc tồn kho thay đổi sau thời điểm sao chép database.

## 4. Xuất Excel

- **Xuất Excel tồn & phân bổ:** tạo sheet `Hướng dẫn`, sheet `Tổng hợp` và một sheet cho từng cơ sở.
- **Xuất số cần bổ sung:** chỉ xuất số lượng cuối cùng còn cần mua/in/nhập sau khi đã tính điều chuyển đúng SKU.

Trong file Excel, các cột màu giúp nhận biết nhanh: đã giữ, chưa phân bổ, điều chuyển đề xuất và cần bổ sung.

## 5. Nguồn dữ liệu tồn kho thống nhất

- **Tồn kho** là nơi duy nhất dùng để cập nhật tồn vật lý và tồn an toàn sau khi sách đã được tạo.
- **Danh mục sách** chỉ đọc và hiển thị `Vật lý / Đã giữ / Khả dụng` theo đúng cơ sở đang chọn trên thanh quản trị. Nếu đang chọn “Tất cả cơ sở”, các số được cộng từ từng dòng `Cơ sở + SKU` mà tài khoản được phép xem.
- **Chỉnh sửa sách** chỉ hiển thị tồn kho theo từng cơ sở và dẫn đến đúng dòng trong mục Tồn kho; không còn ghi đè tồn vật lý khi người dùng chỉ sửa tên, giá hoặc thông tin sách.
- Khi tạo sách mới, có thể nhập tồn ban đầu. Các lần nhập, xuất, điều chuyển hoặc điều chỉnh tiếp theo phải thực hiện ở mục **Tồn kho** để luôn có lịch sử nghiệp vụ.
- Nút **Đặt tồn vật lý** trong Tồn kho đồng thời cho phép cập nhật **Tồn an toàn**. Tồn an toàn chỉ tham gia công thức tính thiếu, không làm tăng hoặc giảm tồn vật lý.

Thay đổi đồng bộ giao diện này không cần chạy migration mới và không sửa dữ liệu tồn kho hiện có.