import-san-pham

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

1. Xác định file nguồn.
2. Đọc references/product-import-rules.md.
3. Lấy template phù hợp trong templates/.
4. Kiểm tra cột, dòng, mã hàng, tên hàng, nhóm hàng, giá, tồn kho.
5. Tạo file sạch trong data/import_ready/YYYYMMDD_HHMMSS/.
6. Tạo báo cáo trong data/reports/YYYYMMDD_HHMMSS/.
7. Chạy check_session.py.
8. Hỏi xác nhận.
9. Gọi KiotVietClient.import_products.
10. Chờ job bằng wait_for_import_job.
11. Lưu response job vào data/reports/YYYYMMDD_HHMMSS/.
12. Export lại sản phẩm từ KiotViet.
13. Chạy scripts/product_import_audit.py verify.
14. Báo trường đúng, trường lệch, và mã chưa tìm thấy.
15. 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ứ.