Kiểm duyệt và bảo vệ dữ liệu

Khi duy trì cơ sở dữ liệu nghiên cứu dài hạn trên máy tính cá nhân, một trong những rủi ro lớn nhất là nguồn cấp dữ liệu bất ngờ thay đổi cấu trúc (thay đổi tên cột, đổi kiểu dữ liệu số thành chuỗi hoặc bỏ bớt cột). Nếu ghi đè trực tiếp dữ liệu sai lệch này vào kho lưu trữ, các bảng lịch sử nhiều năm có thể bị hỏng cấu trúc và khiến các thuật toán phân tích báo lỗi.

vnstock_pipeline giảm rủi ro này thông qua quy trình kiểm soát chất lượng dữ liệu, cơ chế cách ly an toàn (.quarantine) và bộ công cụ kiểm toán toàn vẹn dữ liệu.

Bộ quy chuẩn cấu trúc (Schema Baseline)

Mỗi danh mục dữ liệu (ohlcv, trades, financial...) trong hệ thống đều có một lược đồ chuẩn (Schema Baseline) quy định chặt chẽ:

• Danh sách các cột bắt buộc phải có.
• Kiểu dữ liệu tương ứng của từng cột (số nguyên int64, số thực float64, chuỗi ký tự string hoặc ngày giờ datetime).
• Thứ tự sắp xếp các trường dữ liệu.

Xem cấu trúc chuẩn hiện hành

Bạn có thể tra cứu cấu trúc chuẩn của một danh mục dữ liệu qua lệnh:

vnstock_pipeline schema show ohlcv

Schema Baseline: ohlcv
--------------------------------------------------
Column        Type        Nullable
--------------------------------------------------
time          datetime    False
open          float64     False
high          float64     False
low           float64     False
close         float64     False
volume        int64       False
--------------------------------------------------

Nếu bạn muốn đặt lại cấu trúc chuẩn về mặc định ban đầu:

vnstock_pipeline schema reset ohlcv

Cơ chế vùng cách ly an toàn (.quarantine)

Trong quá trình chạy các tác vụ tải dữ liệu theo lô:

1. Thư viện kiểm tra từng bản ghi mới tải về so với Schema Baseline của danh mục tương ứng.
2. Nếu dữ liệu mới khớp chuẩn hoàn toàn, hệ thống ghi dữ liệu vào kho chính thức.
3. Nếu phát hiện sai lệch bất thường (thiếu cột quan trọng, kiểu dữ liệu bị biến đổi), hệ thống sẽ ngăn chặn ngay lập tức việc ghi vào cơ sở dữ liệu chính. Tệp dữ liệu bất thường đó được chuyển vào thư mục cách ly .quarantine/ kèm dấu thời gian:
   Text

   data/
   ├── ohlcv/
   │   └── ACB.parquet              <-- Cơ sở dữ liệu chính được bảo vệ an toàn
   └── .quarantine/
       └── ohlcv/
           └── ACB_20260301T154500.parquet  <-- Tệp bất thường được giữ lại để kiểm tra

Cơ chế này giúp hạn chế việc dữ liệu sai lệch từ nguồn ghi đè lên dữ liệu đã lưu trên máy bạn.

Quản trị vùng cách ly qua dòng lệnh

1. Xem danh sách các tệp đang bị cách ly

# Xem toàn bộ tệp bị cách ly trong hệ thống
vnstock_pipeline quarantine list

# Hoặc chỉ lọc theo danh mục cụ thể
vnstock_pipeline quarantine list --category ohlcv

Lệnh sẽ hiển thị danh sách các mã, thời gian phát hiện và lý do sai lệch cấu trúc.

2. Chấp thuận cấu trúc mới (Adopt)

Nếu qua kiểm tra bạn thấy website nguồn đã thực hiện nâng cấp cấu trúc cột hợp lệ và bạn muốn áp dụng cấu trúc mới này cho toàn bộ hệ thống từ nay về sau:

vnstock_pipeline quarantine adopt ohlcv ACB 20260301T154500

Hệ thống sẽ cập nhật Schema Baseline theo cấu trúc mới và di chuyển tệp dữ liệu vào kho lưu trữ chính.

3. Huỷ bỏ tệp cách ly (Discard)

Nếu tệp cách ly là do nguồn cấp trả về lỗi tạm thời hoặc dữ liệu rác không có giá trị:

vnstock_pipeline quarantine discard ohlcv ACB 20260301T154500

Tệp trong vùng cách ly sẽ bị xoá an toàn mà không ảnh hưởng tới dữ liệu đang có trên đĩa.

Kiểm toán toàn vẹn cơ sở dữ liệu: storage audit

Sau một thời gian vận hành, bạn nên định kỳ chạy công cụ kiểm toán để rà soát chất lượng dữ liệu trên máy:

vnstock_pipeline storage audit --category ohlcv --stale-days 5

Tham số --stale-days 5 yêu cầu cảnh báo các mã cổ phiếu không có dữ liệu giao dịch mới trong vòng 5 ngày gần nhất.

Lệnh kiểm toán sẽ phát hiện và liệt kê:

• Tệp rỗng hoặc hỏng (Empty / Corrupted files): Các tệp dung lượng 0 byte hoặc tệp lỗi cấu trúc đĩa.
• Đứt gãy thời gian (Data Gaps): Các mã có khoảng trống ngày giao dịch bất thường trong lịch sử.
• Dữ liệu bị ngưng cập nhật (Stale data): Các mã lâu ngày chưa được cập nhật dữ liệu mới.

Dọn dẹp và báo cáo dung lượng đĩa

Dọn dẹp dữ liệu cũ quá hạn (storage cleanup)

Đối với các tập dữ liệu có tần suất cao và dung lượng lớn (như dữ liệu khớp lệnh từng bước giá trades), việc lưu trữ vĩnh viễn nhiều năm có thể làm đầy ổ cứng. Bạn có thể định kỳ dọn dẹp các tệp cũ hơn N ngày:

# Xoá các tệp dữ liệu khớp lệnh cũ hơn 90 ngày
vnstock_pipeline storage cleanup --days 90

Báo cáo dung lượng thư mục lưu trữ (storage report)

Để nắm được tổng quan không gian lưu trữ mà thư mục dữ liệu đang chiếm dụng trên máy tính của bạn:

vnstock_pipeline storage report

Database Storage Report
--------------------------------------------------
Category        Files       Size        Format
--------------------------------------------------
ohlcv           385         42.5 MB     parquet
trades          1,240       186.2 MB    parquet
financial       385         18.1 MB     parquet
company         385         5.4 MB      parquet
--------------------------------------------------
Total:          2,395 files, 252.2 MB on disk
--------------------------------------------------

Bước tiếp theo

Bạn đã nắm trọn vẹn đường chính của tài liệu vnstock_pipeline thế hệ 5. Khi cần xây dựng các hệ thống chuyên sâu, mời bạn khám phá thêm các nội dung trong phần Tính năng nâng cao hoặc xem hướng dẫn Nâng cấp từ bản 2.x.