| name | import-san-pham |
| description | Dùng khi người dùng yêu cầu import, upload, thêm mới, cập nhật, hoặc kiểm tra sản phẩm KiotViet từ Excel, CSV, template, hoặc danh sách hàng hóa. |
Import Sản Phẩm
Mục tiêu
Kiểm tra file sản phẩm, tạo file import sạch, rồi import bằng reverse API nếu user xác nhận.
Template
Template import KiotViet lấy từ templates/.
Mẫu sản phẩm hiện tại:
templates/MauFileSanPham.xlsx
Không lưu template import trong .agents/skills hoặc data/.
File đã điền dữ liệu mới ghi vào data/import_ready/YYYYMMDD_HHMMSS/.
Luồng an toàn
- Xác định file nguồn.
- Đọc
references/product-import-rules.md.
- Lấy template phù hợp trong
templates/.
- Kiểm tra cột, dòng, mã hàng, tên hàng, nhóm hàng, giá, tồn kho.
- Tạo file sạch trong
data/import_ready/YYYYMMDD_HHMMSS/.
- Tạo báo cáo trong
data/reports/YYYYMMDD_HHMMSS/.
- Chạy
check_session.py.
- Hỏi xác nhận.
- Gọi
KiotVietClient.import_products.
- Chờ job bằng
wait_for_import_job.
- Lưu response job vào
data/reports/YYYYMMDD_HHMMSS/.
- Export lại sản phẩm từ KiotViet.
- Chạy
scripts/product_import_audit.py verify.
- Báo trường đúng, trường lệch, và mã chưa tìm thấy.
- Lưu lỗi vào
data/import_errors/YYYYMMDD_HHMMSS/ nếu có.
Cột cần kiểm tra
| Nhóm | Cột thường gặp |
|---|
| Định danh | Mã hàng, Mã sản phẩm, SKU, Mã vạch |
| Tên | Tên hàng, Tên sản phẩm |
| Phân loại | Nhóm hàng, Loại hàng |
| Đơn vị | Đơn vị tính |
| Giá | Giá bán, Giá vốn |
| Tồn kho | Tồn kho, Số lượng |
Nếu thiếu mã định danh hoặc tên hàng, dừng và hỏi.
Lỗi phải báo
- Dòng trống giữa dữ liệu.
- Trùng mã hàng.
- Mã hàng có khoảng trắng đầu hoặc cuối.
- Tên sản phẩm trống.
- Giá hoặc tồn kho không phải số.
- Giá âm hoặc tồn kho âm.
- Công thức Excel chưa tính ra giá trị.
- Ô merge làm lệch dữ liệu.
- Nhiều sheet nhưng chưa rõ sheet dùng.
Gọi API
Chỉ gọi API sau xác nhận:
from api_client import KiotVietClient
client = KiotVietClient()
job = client.import_products(
"data/import_ready/YYYYMMDD_HHMMSS/import_san_pham.xlsx",
is_replace_existing_by_code=True,
confirmed=True,
)
result = client.wait_for_import_job(job)
Hậu kiểm sau import
Sau khi job import trả về thành công, chưa nên kết luận xong. Trạng thái job không đảm bảo dữ liệu đã đúng.
Nên đọc lại dữ liệu thật từ KiotViet, rồi chạy:
~/.venv/claude/bin/python .agents/skills/import-san-pham/scripts/product_import_audit.py verify \
--file data/import_ready/YYYYMMDD_HHMMSS/import_san_pham.xlsx \
--products-json data/raw/YYYYMMDD_HHMMSS/products.json \
--report-dir data/reports/YYYYMMDD_HHMMSS
Báo cáo cuối nên tách rõ:
- job import thành công hay lỗi.
- mã hàng đã tìm thấy sau export.
- trường khớp với file import.
- trường lệch với file import.
- trường chưa kiểm được.
Nếu Giá vốn hoặc Tồn kho lệch sau import, báo là rủi ro cao.
Không tự sửa hai trường này nếu chưa xác định đúng cờ API hoặc nghiệp vụ kho.
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ì.
- số dòng sẽ import.
- mã hàng sẽ cập nhật.
- mã hàng sẽ tạo mới.
- trường thay đổi chính, ví dụ giá, tồn kho, nhóm hàng.
- giá trị trước/sau nếu là cập nhật.
- file import ready và report kiểm tra.
Không import nếu user chưa xác nhận đúng các tác động này.
Báo cáo trước import
Báo:
- file nguồn.
- sheet.
- tổng dòng.
- dòng hợp lệ.
- lỗi hoặc cảnh báo.
- file import ready.
- file export sau import.
- file hậu kiểm.
- câu hỏi xác nhận.
Không làm
- Không import khi chưa kiểm tra file.
- Không import khi chưa xác nhận.
- Không tự tạo mã sản phẩm hàng loạt.
- Không xóa dòng lỗi khỏi file gốc.
- Không ghi đè file gốc.
- Không bỏ qua lỗi job import.
- Không coi job thành công là dữ liệu đã đúng.
- Không bỏ qua hậu kiểm sau import.
- Không sửa giá, tồn kho, nhóm hàng nếu không có căn cứ.
