lamhoadon

name	lamhoadon
description	Dùng khi người dùng yêu cầu làm hóa đơn KiotViet, tạo đơn hàng, tạo file import hóa đơn, hoặc đối chiếu khách hàng và sản phẩm để bán hàng.

Làm Hóa Đơn KiotViet

Mục tiêu

Tạo hóa đơn hoặc file import hóa đơn từ yêu cầu người dùng.

Mặc định tra khách hàng, sản phẩm, bảng giá trực tiếp bằng reverse API trong kiotviet-client.

Luật chi tiết nằm trong references/invoice-rules.md. Phải đọc trước khi tạo file cuối cùng.

Đầu vào tối thiểu

Hỏi TẤT CẢ trước khi bắt đầu quy trình:

• Tên khách hàng hoặc số điện thoại.
• Danh sách mặt hàng.
• Số lượng từng mặt hàng.
• Tồn kho âm: Gian hàng cho phép bán khi tồn kho ≤ 0 không? Mặc định hỏi user. Nếu không cho phép, cảnh báo SP hết hàng và hỏi thay thế.
• Thanh toán: Ghi nhận thanh toán không? Tiền mặt hay chuyển khoản? Mặc định để trống (chưa thanh toán). Nếu user chọn, điền tổng tiền vào cột tương ứng ở dòng đầu.

Nếu thiếu phần nào, hỏi đúng phần thiếu.

Nguồn tra cứu API

Dữ liệu	Hàm client
Khách hàng	export_customers hoặc endpoint khách hàng phù hợp
Sản phẩm	export_products
Bảng giá	export_pricebooks

Không dùng cache file làm nguồn chính.

Bảng giá mặc định

Dùng Giá Bán Buôn nếu user không chỉ định bảng giá khác.

Không tự đổi sang bảng giá khác nếu thiếu giá.

Tra khách hàng

Tìm gần đúng theo:

• tên có dấu và không dấu.
• số điện thoại.
• địa chỉ.
• tên gọi quen.

Nếu có nhiều kết quả gần giống, hỏi user chọn.

Nếu không tìm thấy, hỏi thêm thông tin.

Tra mặt hàng

Ưu tiên:

1. Mã hàng.
2. Mã model hoặc số hiệu.
3. Loại hàng.
4. Kích thước hoặc dung tích.
5. Tên gần âm.

Nếu không chắc, hỏi user chọn.

Không tự tạo mã hàng.

Ưu tiên giữ các mã, giá, khách hàng lấy từ dữ liệu KiotViet.

Output

Tạo output trong:

data/processed/YYYYMMDD_HHMMSS/
data/reports/YYYYMMDD_HHMMSS/
data/import_ready/YYYYMMDD_HHMMSS/

Template import hóa đơn, nếu có, phải nằm trong templates/.

Mẫu hóa đơn hiện tại:

templates/MauFileDanhSachHoaDon.xlsx

Tên file gợi ý:

data/import_ready/YYYYMMDD_HHMMSS/don_hang_<ten_khach>_kiotviet.xlsx

Kiểm tra trước khi giao file

Báo:

• khách hàng.
• mã khách hàng nếu có.
• bảng giá.
• số mặt hàng.
• tổng số lượng.
• tổng tiền hàng.
• danh sách hàng thật đã khớp.
• dòng thiếu giá hoặc thiếu hàng.
• các lựa chọn user đã xác nhận.

Ghi lên KiotViet

Hiện tại mặc định chỉ tạo file import.

Chỉ ghi trực tiếp lên KiotViet khi:

1. endpoint tạo hóa đơn đã được reverse và test.
2. có báo cáo dry run.
3. user xác nhận rõ.
4. method ghi được gọi với confirmed=True.

Hợp đồng xác nhận ghi

Trước khi tạo hóa đơn hoặc import file lên KiotViet, báo rõ:

• sẽ cập nhật gì nếu có.
• sẽ tạo mới gì, gồm hóa đơn, khách hàng, hoặc sản phẩm nếu có.
• khách hàng.
• danh sách hàng.
• số lượng.
• đơn giá.
• tổng tiền.
• bảng giá.
• trạng thái thanh toán.
• giá trị trước/sau nếu có cập nhật dữ liệu cũ.

Không ghi nếu user chưa xác nhận đúng các tác động này.

Không làm

• Không tự sinh mã hóa đơn nếu user không yêu cầu.
• Không tự tạo mã khách hàng.
• Không tự tạo mã hàng.
• Không tự đoán giá nếu thiếu Giá Bán Buôn.
• Không import hoặc ghi hóa đơn khi user chưa yêu cầu rõ.