Hướng dẫn Nâng Cấp Phiên Bản v3.2.8

Tài liệu này cung cấp hướng dẫn chi tiết để giúp bạn nâng cấp code từ các phiên bản cũ lên vnstock_data v3.2.8 trở đi.

Trong phiên bản mới nhất, dữ liệu báo cáo tài chính (Fundamental) được tái cấu trúc toàn diện, áp dụng bộ chuẩn hóa theo chuẩn mực kế toán Việt Nam (VAS) cho tất cả các nguồn dữ liệu. Điều này giúp loại bỏ sự sai lệch tên gọi giữa các nguồn, đồng nhất dữ liệu và đảm bảo ngữ cảnh tài chính chính xác cho các thuật toán phân tích định lượng và AI.

🚨 Những Thay Đổi Quan Trọng

Lưu ý đối với môi trường Google Colab

Nguồn dữ liệu Báo cáo tài chính mặc định đã được chuyển sang VCI để cung cấp mức độ chi tiết tốt nhất. Tuy nhiên, kết nối tới VCI có thể bị chặn trên môi trường Google Colab.

Khuyến nghị: Cài đặt và chạy code trong môi trường cục bộ (local PC) để sử dụng trơn tru nhất.

Tải bảng dữ liệu tham chiếu Agent Guide

1. Thay Đổi Định Dạng Đầu Ra

Định dạng trả về mặc định cho tất cả các hàm tài chính (như Bảng cân đối kế toán, Kết quả kinh doanh, Lưu chuyển tiền tệ) hiện nay là Tidy Data (Long Format) thay vì bảng ngang (Wide Format) như trước.

Mỗi hàng dữ liệu sẽ bao gồm các thuộc tính chuẩn hóa:

id: Mã định danh (primary key) duy nhất cho mỗi tiêu chí (Ví dụ: BS_CASH_AND_PRECIOUS_METALS). Sử dụng id giúp code không bị gãy khi tên tiêu chí hiển thị thay đổi.
name: Tên tiêu chí theo chuẩn mực kế toán.
unit: Đơn vị dữ liệu.
order: Thứ tự trình bày tiêu chí trong báo cáo gốc, giúp bạn khôi phục đúng cấu trúc khi pivot.
level: Thể hiện phân cấp tiêu chí cha/con.

💡 Mẹo: Nếu bạn cần phân tích dữ liệu dạng bảng ngang quen thuộc (nhiều kỳ nằm trên các cột), bạn có thể thêm tham số format="wide" hoặc format="time_series" khi gọi hàm. Khi đó, tên các cột sẽ được sử dụng bằng Semantic ID chuẩn hoá mới thay vì các tên cột snake_case cũ bị phụ thuộc vào nguồn dữ liệu.

2. Thay Đổi Tham Số Hàm

Các hàm tải dữ liệu tài chính như balance_sheet(), income_statement(), cash_flow(), ratio() đã thay đổi danh sách tham số:

Xóa bỏ: Tham số dropna đã bị thay thế thành drop_empty.
Thêm mới: Tham số format để cấu hình định dạng ('long', 'wide', 'time_series').
Thêm mới: Tham số com_type giúp cố định loại hình công ty ('Regular', 'Bank', 'Securities', 'Insurance') để áp dụng Taxonomy phù hợp thay vì tự động đoán ngầm định.

📊 Bảng Tham Chiếu (Mapping)

Bảng Cân Đối Kế Toán (Balance Sheet)

Tên Chỉ Tiêu (Theo VAS)	Cột Mới (Semantic ID)	Tên Cột Cũ (Nguồn MAS)	Tên Cột Cũ (Nguồn KBS)
Tiền và các khoản tương đương tiền	`BS_CASH_AND_PRECIOUS_METALS`	`i_cash_gold_and_silver_precious_stones`	`1_cash_and_cash_equivalents`
Tài sản cố định	`BS_FIXED_ASSETS`	`x_fixed_assets`	`ix_fixed_assets`
Tài sản cố định hữu hình	`BS_TANGIBLE_FIXED_ASSETS`	`1_tangible_fixed_assets`	`1_tangible_fixed_assets`
Nguyên giá	`BS_TANGIBLE_FIXED_ASSETS_COST`	`a_cost`	`cost`
Giá trị hao mòn luỹ kế	`BS_TANGIBLE_FIXED_ASSETS_ACCUMULATED_DEPRECIATION`	`b_accumulated_depreciation`	`accumulated_depreciation`
Tài sản cố định vô hình	`BS_INTANGIBLE_FIXED_ASSETS`	`3_intangible_fixed_assets`	`3_intangible_fixed_assets`

Lưu Chuyển Tiền Tệ (Cash Flow)

Tên Chỉ Tiêu (Theo VAS)	Cột Mới (Semantic ID)	Tên Cột Cũ (Nguồn MAS)	Tên Cột Cũ (Nguồn KBS)
Lợi nhuận trước thuế	`CF_PROFIT_BEFORE_TAX`	`1_profit_before_tax`	`profit_before_tax`
Khấu hao TSCĐ và BĐSĐT	`CF_DEPRECIATION_AND_AMORTISATION`	`depreciation_of_fixed_assets_and_investment_properties`	`depreciation_and_amortization`
Các khoản dự phòng	`CF_PROVISIONS`	`reversal_of_provisions_provisions`	`reversal_of_provisions_provisions`
Chi phí lãi vay	`CF_INTEREST_EXPENSE`	`borrowing_costs`	`interest_expense`
Thu lãi và cổ tức	`CF_INTEREST_AND_DIVIDENDS_RECEIVED`	`interest_income_and_dividends`	`accrued_interest_income`

Báo Cáo Kết Quả Kinh Doanh (Income Statement)

Tên Chỉ Tiêu (Theo VAS)	Cột Mới (Semantic ID)	Tên Cột Cũ (Nguồn MAS)	Tên Cột Cũ (Nguồn KBS)
Tổng lợi nhuận kế toán trước thuế	`IS_PROFIT_BEFORE_TAX`	`xi_profit_before_tax`	`31_taxable_profit`
Lợi nhuận sau thuế	`IS_NET_PROFIT_AFTER_TAX`	`xiii_net_profit_after_tax`	`34_profit_after_tax`
Lợi nhuận sau thuế của cổ đông công ty mẹ	`IS_PROFIT_AFTER_TAX_FOR_SHAREHOLDERS_OF_PARENT_COMPANY`	`xv_net_profit_atttributable_to_the_equity_holders_of_the_bank`	`36_profit_after_tax_for_shareholders_of_the_parent_company`
Thu nhập lãi thuần	`IS_NET_INTEREST_INCOME`	`i_net_interest_income`	`i_net_interest_income`
Lãi thuần từ hoạt động dịch vụ	`IS_NET_FEE_AND_COMMISSION_INCOME`	`ii_net_fee_and_commission_income`	`ii_net_fee_and_commission_income`

Bạn có thể tra cứu nhanh chóng hàm và các tham số mới nhất thông qua bảng tham chiếu vnstock_3.2.8_schema_migration_reference.csv tải về từ tài khoản đã thực hiện Tài trợ dự án. Chúc các bạn Vibe Coding hiệu quả với hệ thống dữ liệu hoàn toàn mới!