| name | import-update-bang-gia |
| description | Dùng khi người dùng yêu cầu import, cập nhật, đồng bộ, điều chỉnh, so sánh, hoặc kiểm tra bảng giá KiotViet từ file. |
Import Update Bảng Giá
Mục tiêu
Cập nhật giá an toàn bằng dữ liệu API hiện tại và báo cáo chênh lệch trước khi ghi.
Nguồn dữ liệu
- Giá hiện tại:
KiotVietClient.export_pricebooks.
- Sản phẩm hiện tại:
KiotVietClient.export_products.
- File giá mới: Excel hoặc CSV từ user.
- Template import KiotViet: thư mục
templates/.
- Output:
data/reports, data/import_ready, data/import_errors.
Mẫu bảng giá hiện tại:
templates/MauFileBangGia.xlsx
Luồng mặc định
- Xác định file giá nguồn.
- Xác định bảng giá đích.
- Đọc
references/price-update-rules.md.
- Gọi
KiotVietClient.export_pricebooks.
- Gọi
KiotVietClient.export_products.
- Kiểm tra mã hàng và giá mới.
- Tạo báo cáo chênh lệch.
- Cảnh báo giá bất thường.
- Tạo file hoặc payload cập nhật.
- Hỏi xác nhận.
- Chỉ ghi API sau xác nhận.
Cảnh báo giá bất thường
Báo rõ khi:
- Giá mới bằng 0.
- Giá mới âm.
- Giá giảm trên 30 phần trăm.
- Giá tăng trên 50 phần trăm.
- Giá bán thấp hơn giá vốn nếu có giá vốn.
- Nhiều sản phẩm đổi về cùng một giá.
Ngưỡng có thể đổi nếu user chỉ định.
Cách ghi
Ưu tiên import bằng file nếu templates/ có template KiotViet phù hợp.
Không lưu template import trong .agents/skills hoặc data/.
Nếu tạo hoặc cập nhật bảng giá trực tiếp:
- Tạo bảng giá bằng
create_pricebook(..., confirmed=True) nếu bảng giá chưa có.
- Thêm đúng mã hàng vào bảng giá bằng
add_products_to_pricebook(..., confirmed=True).
- Ghi giá từng dòng bằng
calc_price_for_all_items(..., confirmed=True).
- Dùng
get_pricebook_items để verify giá sau ghi.
- Lưu response từng dòng.
Chỉ dùng build_update_product_payload và update_product khi mục tiêu là sửa trực tiếp hàng hóa.
Hợp đồng xác nhận ghi
Trước khi gọi API và truyền confirmed=True, báo rõ:
- sẽ cập nhật gì.
- sẽ tạo mới gì nếu có import thêm.
- bảng giá đích.
- số sản phẩm đổi giá.
- mã hàng bị tác động.
- giá trước/sau từng dòng hoặc trong file report.
- cảnh báo giá bất thường.
- phạm vi chi nhánh hoặc toàn hệ thống.
Không update nếu user chưa xác nhận đúng các tác động này.
Báo cáo trước khi ghi
Báo:
- bảng giá đích.
- số dòng input.
- số mã khớp.
- số mã không tìm thấy.
- số cảnh báo.
- tổng tác động tiền nếu tính được.
- file report.
- file
qa_report.json.
- câu hỏi xác nhận.
Trước khi apply, tạo qa_report.json cùng thư mục report.
Sau đó kiểm bằng kiotviet_write_gate.validate_apply_gate.
Nếu thiếu QA report, có blocker, hoặc xác nhận không khớp thì dừng.
Không làm
- Không tự đoán bảng giá đích.
- Không update khi chưa có báo cáo.
- Không update khi chưa xác nhận.
- Không tự đổi mã hàng.
- Không bỏ qua sản phẩm không tìm thấy.
- Không tự chọn dòng nào đúng khi file có trùng mã và khác giá.
