kiotviet-data-manager

name	kiotviet-data-manager
description	Dùng khi cần tổ chức output KiotViet thư mục data, raw export, dữ liệu xử lý, file import, báo cáo, backup, hoặc manifest.

KiotViet Data Manager

Mục tiêu

Skill này giữ output KiotViet dễ quản lý, dễ audit, dễ rollback.

Chi tiết schema nằm trong references/data-contracts.md.

Cấu trúc chuẩn

data/
├── raw/YYYYMMDD_HHMMSS/
├── processed/YYYYMMDD_HHMMSS/
├── import_ready/YYYYMMDD_HHMMSS/
├── import_errors/YYYYMMDD_HHMMSS/
├── reports/YYYYMMDD_HHMMSS/
└── _backup/YYYYMMDD_HHMMSS/

Template import gốc không nằm trong data/.

Template import KiotViet để trong:

templates/

Ý nghĩa thư mục

Thư mục	Dùng cho
raw	JSON hoặc file tải trực tiếp từ KiotViet
processed	dữ liệu đã chuẩn hóa để tra cứu
import_ready	file chuẩn bị upload hoặc import bằng API
import_errors	file lỗi, response lỗi, log import lỗi
reports	báo cáo kiểm tra, đối chiếu, thay đổi
_backup	bản cũ trước khi thay thế

Manifest bắt buộc

Mỗi lần chạy tạo:

data/<nhóm>/YYYYMMDD_HHMMSS/manifest.json

Manifest tối thiểu:

{
  "run_id": "YYYYMMDD_HHMMSS",
  "created_at": "2026-05-16T10:30:00",
  "operation": "export",
  "inputs": [],
  "outputs": [],
  "status": "success"
}

Không ghi token, cookie, mật khẩu, hoặc header auth vào manifest.

Quy tắc backup

Trước khi ghi đè file Excel output, tạo backup:

data/_backup/YYYYMMDD_HHMMSS/

Chỉ backup file bị thay.

Không backup token hoặc file nhạy cảm.

Báo cáo cho người dùng

Báo cáo ngắn:

• operation đã chạy.
• run id.
• file mới.
• lỗi hoặc cảnh báo.

Không liệt kê dữ liệu nhạy cảm.