| name | kiotviet-orchestrator |
| description | Dùng khi người dùng yêu cầu làm việc với dữ liệu, sản phẩm, bảng giá, hóa đơn, đơn hàng, khách hàng, nhà cung cấp, danh mục, tồn kho, kiểm kho, thu chi, công nợ, báo cáo doanh thu, import, export, bảo trì reverse API, hoặc cập nhật KiotViet. |
KiotViet Orchestrator
Mục tiêu
Điều phối đúng skill KiotViet theo yêu cầu người dùng.
Mặc định dùng reverse API qua kiotviet-client. Không dùng Public API Business.
Skill liên quan
| Nhu cầu | Skill |
|---|
| Kiểm tra phiên, gọi API, CRUD, tồn kho, thu chi, báo cáo | kiotviet-client |
| Tổ chức output | kiotviet-data-manager |
| Tải dữ liệu khách hàng, sản phẩm, bảng giá, hóa đơn, đơn hàng | download-du-lieu-kiotviet |
| Import hoặc cập nhật sản phẩm từ Excel | import-san-pham |
| Cập nhật bảng giá | import-update-bang-gia |
| Làm hóa đơn hoặc file import hóa đơn | lamhoadon |
| Tạo hoá đơn random hàng loạt | nhathoadon |
| Endpoint lỗi do KiotViet đổi giao diện | reverse-engineering-api |
Agent liên quan
| Tình huống | Agent |
|---|
| Vận hành dữ liệu, tạo file, lập báo cáo | kiotviet-data-operator |
| Kiểm tra import, update, payload trước khi ghi | kiotviet-import-qa |
| Endpoint lỗi, cần phân tích HAR hoặc vá client | kiotviet-api-maintainer |
Orchestrator gọi agent theo rủi ro. Việc đọc dữ liệu đơn giản có thể chạy trực tiếp bằng skill.
Trước thao tác ghi, luôn có kiotviet-import-qa kiểm tra báo cáo hoặc payload.
Luồng chọn việc
- Nếu yêu cầu là tải hoặc cập nhật dữ liệu nền, dùng
download-du-lieu-kiotviet.
- Nếu yêu cầu là import hàng hóa, dùng
import-san-pham.
- Nếu yêu cầu là cập nhật giá, dùng
import-update-bang-gia.
- Nếu yêu cầu là tạo hoá đơn random hoặc hàng loạt, dùng
nhathoadon.
- Nếu yêu cầu là tạo hóa đơn cho khách cụ thể, dùng
lamhoadon.
- Nếu API lỗi hoặc thiếu endpoint, dùng
reverse-engineering-api, rồi cập nhật kiotviet-client.
- Nếu thao tác có ghi dữ liệu, giao
kiotviet-import-qa kiểm tra trước khi hỏi xác nhận.
Gate bắt buộc
Trước thao tác ghi:
- Chạy
ensure_session.py.
- Chạy kiểm tra phiên bằng
check_session.py.
- Tạo
manifest.json trong data/reports/YYYYMMDD_HHMMSS/.
- Tạo báo cáo dry run trong
data/reports/YYYYMMDD_HHMMSS/.
- Tạo
qa_report.json trong data/reports/YYYYMMDD_HHMMSS/.
- Chạy gate bằng
kiotviet_write_gate.validate_apply_gate trước khi apply.
- Hỏi xác nhận người dùng bằng đúng
qa_report.confirmation_text.
- Chỉ gọi API ghi sau xác nhận rõ.
- Khi gọi method ghi, truyền
confirmed=True.
- Verify sau ghi và lưu
verify_summary.json.
- Export lại dữ liệu liên quan trước khi kết luận hoàn tất.
- Báo rõ dữ liệu đúng, dữ liệu lệch, và dữ liệu chưa kiểm được.
Không có qa_report.json thì không apply.
Nếu qa_report.blockers không rỗng thì không apply.
Nếu câu xác nhận không khớp qa_report.confirmation_text thì không apply.
Thao tác ghi gồm:
- import sản phẩm.
- update sản phẩm.
- xóa sản phẩm.
- update bảng giá.
- tạo/sửa/xóa khách hàng.
- tạo/sửa/xóa nhà cung cấp.
- tạo/sửa/xóa danh mục.
- tạo/sửa/hủy đơn hàng.
- tạo phiếu thu chi.
- tạo hóa đơn nếu endpoint ghi được bổ sung sau này.
Hợp đồng xác nhận ghi
Trước mọi thao tác ghi lên KiotViet, phải báo rõ:
- sẽ cập nhật gì.
- sẽ tạo mới gì.
- sẽ xóa gì nếu có.
- số lượng dòng hoặc bản ghi bị tác động.
- mã hàng, mã khách, bảng giá, hóa đơn liên quan.
- giá trị trước/sau với trường thay đổi quan trọng.
- phạm vi chi nhánh hoặc toàn hệ thống.
- file báo cáo dry run.
- file
qa_report.json.
- kế hoạch verify sau ghi.
Không gọi API ghi nếu user chỉ nói chung chung.
Không nói thao tác đã xong nếu chưa có bằng chứng đọc lại từ KiotViet.
Câu xác nhận phải nhắc lại đúng tác động.
Ví dụ:
Xác nhận apply: sẽ cập nhật 12 sản phẩm, tạo mới 3 sản phẩm trong bảng giá Giá Bán Buôn, theo report data/reports/<run_id>/report.md.
Hợp đồng qa_report.json
File qa_report.json phải có tối thiểu:
{
"run_id": "YYYYMMDD_HHMMSS",
"operation": "create_pricebook",
"mode": "apply",
"target": {},
"planned_counts": {"affected_records": 0},
"endpoints": {"write": [], "verify": []},
"blockers": [],
"warnings": [],
"apply_allowed": true,
"confirmation_text": "Xác nhận apply: ...",
planned_counts.affected_records phải khớp verify_plan.expected_records.
endpoints.write và endpoints.verify không được rỗng.
Chế độ chạy
| Chế độ | Ý nghĩa |
|---|
| dry run | kiểm tra, tạo file, tạo báo cáo, không ghi KiotViet |
| apply | ghi KiotViet sau xác nhận |
| repair | dùng HAR để sửa endpoint |
Nếu người dùng không nói rõ, mặc định là dry run.
Gate sau ghi
Sau mọi thao tác ghi, orchestrator phải chạy hậu kiểm.
Luồng hậu kiểm:
- Lưu job response hoặc response API vào
data/reports/YYYYMMDD_HHMMSS/.
- Export lại dữ liệu liên quan từ KiotViet.
- Chạy script verify phù hợp.
- Báo kết quả theo 3 nhóm: đúng, lệch, chưa kiểm được.
- Lưu report hậu kiểm vào
data/reports/YYYYMMDD_HHMMSS/.
Với import sản phẩm, dùng:
~/.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 phải có:
- Job ID hoặc response ID.
- trạng thái job hoặc response.
- file result.
- file export sau ghi.
- mã đã tìm thấy.
- trường đúng.
- trường lệch.
- việc cần xử lý tiếp.
Bối cảnh đầu vào
Trước khi chạy, kiểm tra:
.env hoặc biến môi trường KiotViet đã có chưa.- File Excel người dùng nêu có tồn tại chưa.
- Template import KiotViet cần dùng có trong
templates/ chưa.
- Yêu cầu có cần ghi dữ liệu thật không.
Lỗi và fallback
| Lỗi | Cách xử lý |
|---|
| token hết hạn | yêu cầu người dùng lấy token mới |
| thiếu env | báo đúng biến thiếu |
| endpoint đổi | dùng reverse-engineering-api với HAR mới |
| dữ liệu không chắc | hỏi người dùng chọn |
| preview lỗi | dừng, lưu lỗi vào data/import_errors/ |
| thiếu QA report | dừng, tạo lại dry run và QA |
| verify lệch | dừng, lưu verify_summary.json, báo mã lệch |
Test scenario
Luồng thường:
- User: “tải dữ liệu KiotViet”.
- Dùng
download-du-lieu-kiotviet.
- Chạy export customers, products, pricebooks.
- Ghi
data/raw/<run_id>.
- Báo run id và file.
Luồng lỗi:
- User: “import sản phẩm”.
- Kiểm tra file xong.
check_session.py trả 401.- Dừng.
- Báo cần token mới, không import.
