kiotviet-orchestrator

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

1. 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.
2. Nếu yêu cầu là import hàng hóa, dùng import-san-pham.
3. Nếu yêu cầu là cập nhật giá, dùng import-update-bang-gia.
4. Nếu yêu cầu là tạo hoá đơn random hoặc hàng loạt, dùng nhathoadon.
5. Nếu yêu cầu là tạo hóa đơn cho khách cụ thể, dùng lamhoadon.
6. Nếu API lỗi hoặc thiếu endpoint, dùng reverse-engineering-api, rồi cập nhật kiotviet-client.
7. 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:

1. Chạy ensure_session.py.
2. Chạy kiểm tra phiên bằng check_session.py.
3. Tạo manifest.json trong data/reports/YYYYMMDD_HHMMSS/.
4. Tạo báo cáo dry run trong data/reports/YYYYMMDD_HHMMSS/.
5. Tạo qa_report.json trong data/reports/YYYYMMDD_HHMMSS/.
6. Chạy gate bằng kiotviet_write_gate.validate_apply_gate trước khi apply.
7. Hỏi xác nhận người dùng bằng đúng qa_report.confirmation_text.
8. Chỉ gọi API ghi sau xác nhận rõ.
9. Khi gọi method ghi, truyền confirmed=True.
10. Verify sau ghi và lưu verify_summary.json.
11. Export lại dữ liệu liên quan trước khi kết luận hoàn tất.
12. 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: ...",
  "verify_plan": {"expected_records": 0}
}

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:

1. Lưu job response hoặc response API vào data/reports/YYYYMMDD_HHMMSS/.
2. Export lại dữ liệu liên quan từ KiotViet.
3. Chạy script verify phù hợp.
4. Báo kết quả theo 3 nhóm: đúng, lệch, chưa kiểm được.
5. 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:

1. User: “tải dữ liệu KiotViet”.
2. Dùng download-du-lieu-kiotviet.
3. Chạy export customers, products, pricebooks.
4. Ghi data/raw/<run_id>.
5. Báo run id và file.

Luồng lỗi:

1. User: “import sản phẩm”.
2. Kiểm tra file xong.
3. check_session.py trả 401.
4. Dừng.
5. Báo cần token mới, không import.