import-update-bang-gia

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

1. Xác định file giá nguồn.
2. Xác định bảng giá đích.
3. Đọc references/price-update-rules.md.
4. Gọi KiotVietClient.export_pricebooks.
5. Gọi KiotVietClient.export_products.
6. Kiểm tra mã hàng và giá mới.
7. Tạo báo cáo chênh lệch.
8. Cảnh báo giá bất thường.
9. Tạo file hoặc payload cập nhật.
10. Hỏi xác nhận.
11. 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:

1. Tạo bảng giá bằng create_pricebook(..., confirmed=True) nếu bảng giá chưa có.
2. Thêm đúng mã hàng vào bảng giá bằng add_products_to_pricebook(..., confirmed=True).
3. Ghi giá từng dòng bằng calc_price_for_all_items(..., confirmed=True).
4. Dùng get_pricebook_items để verify giá sau ghi.
5. 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á.