Dữ liệu Người dùng Nhập Trước Kỳ Dự báo

Chín nhóm dữ liệu mà kho dữ liệu không có, phải do Trade, KAM, Sales, Kế hoạch, Mua hàng nhập trước ngày chạy dự báo: từng trường, kiểu dữ liệu, luật kiểm tra, trạng thái hiện nay.

1.0 (Draft) ✓ Đã chốt giải pháp & mô hình dự báo

Kho dữ liệu chỉ ghi lại những gì đã xảy ra. Những gì sắp xảy ra — khuyến mãi tháng tới, cửa hàng sắp khai trương, mã hàng sắp ra mắt, Tết rơi vào ngày nào — chỉ có trong đầu người làm nghiệp vụ. Nếu không ai nhập, mô hình coi tháng tới giống nhịp mấy tháng gần đây.

1. Tóm tắt chín nhóm

Trạng thái có ba mức:

Đang dùng — đã có nơi lưu và mô hình chốt đang đọc.
Có nơi lưu — đã có bảng hoặc tệp, nhưng mô hình chốt chưa đọc đủ.
Đề xuất — chưa có nơi nhập. Danh sách trường bên dưới là thiết kế đề xuất, chờ nghiệp vụ duyệt.

#	Nhóm	Ai nhập	Nhịp nhập	Trạng thái	Thiếu thì sao
1	Lịch chương trình khuyến mãi	Trade	Mỗi khi có chương trình mới hoặc đổi, tối thiểu đủ 3 tháng tới	Có nơi lưu — mô hình chỉ đọc CTKM của tháng trước	Đợt khuyến mãi lớn mới bắt đầu bị dự báo thấp
2	Cửa hàng mở mới, đóng cửa	Sales, KAM, Phát triển kênh	Hằng tháng	Đề xuất	Sản lượng cửa hàng mới không có trong dự báo; cửa hàng đã đóng vẫn được dự báo tới 3 tháng
3	Mã hàng mới, ngừng mã, đổi mã	Mua hàng, Marketing, Trade	Khi có quyết định	Đề xuất — riêng đổi mã TMICC máy tự nối	Mã mới không có dự báo; mã đã ngừng vẫn được dự báo
4	Danh mục hàng theo chuỗi	Trade, KAM	Khi chuỗi đổi danh mục	Có tệp Excel, chưa nạp	Mã mới vào chuỗi không có dự báo ở hạt chuỗi
5	Lịch lễ, Tết, sự kiện	Kế hoạch	Một lần mỗi năm, sửa khi có thay đổi	Đề xuất — mã nguồn chỉ có 5 ngày lễ dương lịch	Tháng có Tết dự báo lệch
6	Đơn đặc biệt, đột biến	KAM, Sales	Khi biết trước	Đề xuất	Đơn DC lớn, đơn khai trương không có trong dự báo
7	Điều chỉnh tay và chỉ tiêu	Kế hoạch	Sau mỗi lượt chạy	Đề xuất (Giai đoạn 2)	Không tách được số máy với số người chỉnh
8	Kỳ dữ liệu nhiễm	Nhóm kỹ thuật	Khi phát hiện	Viết cứng trong mã, đang rỗng	Tháng dữ liệu hỏng lọt vào huấn luyện
9	Tham số lượt chạy	Nhóm kỹ thuật, Kế hoạch	Mỗi lượt chạy	Viết cứng trong mã	Chưa tự chạy được kỳ mới

Hạn chót nhập liệu. Dữ liệu nhóm 1–6 phải có trước ngày chạy dự báo đầu tháng. Ngày cụ thể chưa chốt — cần Kế hoạch và Trade thống nhất cùng câu hỏi “lịch khuyến mãi và lịch đặt hàng của chuỗi cung cấp trước được bao nhiêu ngày”. Dữ liệu nhập sau ngày chạy chỉ có tác dụng từ kỳ sau.

Quy ước chung cho mọi nhóm:

Tên trường là tên kỹ thuật, dùng chung giữa tài liệu, giao diện và máy chủ (định danh tiếng Anh). Cột “Nhãn hiển thị” là chữ hiện trên màn hình.
Ngày nhập đủ dd/mm/yyyy, tháng lưu dạng YYYYMM và hiển thị MM/YYYY. Sản lượng tính bằng thùng.
Mã hàng phải tồn tại trong dwh.dim_products và bắt đầu bằng 11 (thành phẩm). Mã cửa hàng, mã chuỗi, mã kho, mã địa bàn chọn từ danh mục, không gõ tự do.
Mọi bản ghi có submitted_by, submitted_at (tự sinh từ tài khoản đăng nhập) và status. Huỷ thì đổi trạng thái, không xoá dòng, để truy được vì sao con số dự báo đổi.

Nhóm 1. Lịch chương trình khuyến mãi

Nơi lưu hiện tại: bảng user_uploads.trade_promotions, xuất ra out/export/trade_promotions_full.parquet. Lần nạp gần nhất ngày 13/09/2026: 6.368 dòng từ hai tệp Excel của Trade (Kem Wall’s 3.906 dòng, sản phẩm trừ Wall’s 2.462 dòng), chỉ kênh MT. Dòng dày tới 07/2026; từ 08/2026 rất thưa (51, 9, 2, 8, 5 dòng hiệu lực theo tháng bắt đầu 08 → 12/2026).

Cách nhập: tải tệp Excel của Trade lên, hệ thống kiểm tra từng dòng, cho xem trước rồi mới ghi. Bản demo forecast_demo đã có luồng này (POST /api/imports, rồi POST /api/imports/{batch_id}/commit). Mẫu tệp ở docs/05-thi-cong-gd1/MAU-NAP-CTKM_DBNC-v0.1.xlsx.

Tên trường	Nhãn hiển thị	Cột trong tệp Excel của Trade	Kiểu	Bắt buộc	Kiểm tra	Mô hình chốt đọc
`promotion_code`	Số chương trình	SỐ CHƯƠNG TRÌNH KHUYẾN MÃI	Chuỗi	Có	Ô gộp trong tệp Wall’s phải điền xuống trước khi kiểm tra	—
`orc_promotion_code`	Mã chương trình ORC	Mã Gift ORC / Số CTKM (ORC)	Chuỗi	Không	Cột nguồn lẫn chữ trạng thái (Done, Cancel…) — tách sang `promotion_status`	—
`promotion_name`	Tên chương trình	TÊN CHƯƠNG TRÌNH KHUYẾN MÃI	Chuỗi	Không	Tệp sản phẩm trừ Wall’s không có cột này	—
`promotion_mechanic_code`	Cơ chế khuyến mãi	Hình thức KM / Type Scheme	Danh mục đóng	Có	Đang có trong bảng: `GIAM_GIA`, `GIAM_TREN_HD`, `GIAM_SAU`, `TANG_HANG`, `TANG_QUA`, `MUA_N_TINH_M`, `CLAIM_BACK`, `HO_TRO`, `KHAC`. Biến thể chính tả phải ánh xạ về mã, không cho gõ tự do	—
`product_code`	Mã sản phẩm	Mã SP mới / Mã SP ORC	Chuỗi	Có	Có trong `dim_products`, bắt đầu bằng `11`	Có
`channel_level_1_name`	Kênh áp dụng	KÊNH BÁN HÀNG / Mã kênh (level01)	Danh mục đóng	Có	Hiện chỉ MT	—
`chain_code`	Chuỗi áp dụng	PHẠM VI THỰC HIỆN / Hệ thống (party name)	Chọn từ danh mục chuỗi	Có khi áp theo chuỗi	Tên chuỗi trùng lặp (Win/WIN, Aeon/AEON, Coop/SAIGON CO.OP) phải ánh xạ về một mã	Có (hạt chuỗi)
`promotion_allocation_level`	Mức phân bổ	Hệ thống sinh	Danh mục đóng	Có	`TOAN_MT`, `CHUOI`, `CUA_HANG`. Tệp chỉ tới cấp chuỗi nên giả định “mọi cửa hàng trong chuỗi đều áp dụng” phải được ghi lại	—
`promotion_buy_qty`, `promotion_get_qty`	Mua bao nhiêu, tặng bao nhiêu	Bóc từ cơ cấu KM	Số nguyên	Với tặng hàng	“3 tặng 1” → 3 và 1	—
`promotion_discount_pct`	Mức giảm (%)	DISCOUNT 1 (%)	Số thực	Với giảm giá	0 ≤ giá trị ≤ 100	Có
`promotion_discount_amount`	Mức giảm (đồng)	DISCOUNT 2 (VND)	Số	Với giảm giá	≥ 0	—
`promotion_gift_code`, `promotion_gift_name`	Mã và tên quà tặng	Gift Code / Gift Desc.	Chuỗi	Với tặng quà	—	—
`promotion_sell_in_start_date`, `promotion_sell_in_end_date`	Thời gian đặt hàng từ / đến	Thời gian đặt hàng	Ngày	Có	Ngày đầu ≤ ngày cuối (bảng hiện có dòng ngược chiều tới −336 ngày)	—
`promotion_sell_out_start_date`, `promotion_sell_out_end_date`	Thời gian áp dụng cho người tiêu dùng từ / đến	Thời gian áp dụng NTD	Ngày	Có	Đủ `dd/mm/yyyy` — tệp từng ghi “14/2 - 30/4” thiếu năm	Có (qua tháng bắt đầu, kết thúc)
`promotion_days`	Số ngày chạy	Hệ thống tính	Số nguyên	—	= ngày kết thúc − ngày bắt đầu của cửa sổ người tiêu dùng	Có
`promotion_start_year_month`, `promotion_end_year_month`	Tháng bắt đầu, kết thúc	Hệ thống tính	`YYYYMM`	—	Tính từ cửa sổ người tiêu dùng	Có
`promotion_budget`	Tổng ngân sách	TỔNG NGÂN SÁCH KHUYẾN MÃI	Số (đồng)	Không	Chỉ tệp Wall’s có	—
`promotion_forecast_qty`	Số FC	Cột FC	Số	Không	Chưa ai xác nhận cột này là cam kết mua của chuỗi hay ước lượng của Trade — lưu nguyên, chưa đưa vào mô hình	—
`promotion_status`	Trạng thái	Hệ thống suy từ ghi chú	Danh mục đóng	Có	`HIEU_LUC`, `HUY`, `DIEU_CHINH`. Chương trình dừng thì đổi trạng thái, không xoá	Có (chỉ đọc `HIEU_LUC`)
`promotion_note`	Ghi chú	Note	Chuỗi	Không	—	—

Hai quy tắc nghiệp vụ phải giữ khi nhập:

Dự báo nhu cầu dùng cửa sổ người tiêu dùng (sell-out), không dùng cửa sổ đặt hàng (sell-in). Nhầm hai cửa sổ là lệch pha 2–4 tuần. Màn hình nên đặt hai cặp ngày cạnh nhau và ghi rõ cặp nào đi vào mô hình.
Một mã hàng, một chuỗi, một thời điểm chỉ chịu một chương trình. Chồng lấn phải cảnh báo ngay lúc nạp.

Còn thiếu để CTKM tác động lên tháng đang dự báo: (a) Trade nạp đủ lịch 3 tháng tới; (b) mô hình đọc CTKM của tháng đích — chỗ nối đã có sẵn là hệ số promo_adj (đang luôn bằng 1, xem danh mục biến); (c) lịch CTKM kênh GT.

Nhóm 2. Cửa hàng mở mới, đóng cửa

Vì sao cần. Từ 01 đến 08/2026, sản lượng từ cửa hàng lần đầu phát sinh đơn chiếm khoảng 2,4% tổng sản lượng (kênh GT 4,8%, MT 1,8%). Hệ thống không thể biết trước cửa hàng nào sắp khai trương: nó chỉ thấy số cửa hàng có đơn tháng trước tăng hay giảm (biến mv_grp_store_growth). Ngược lại, cửa hàng đã đóng vẫn được dự báo cho tới khi im lặng đủ 3 tháng.

Có hai cách nhập. Cách A khi đã biết từng cửa hàng; cách B khi mới có kế hoạch số lượng.

Cách A — từng cửa hàng (`store_change_event`)

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Kiểm tra và ghi chú
`event_type`	Loại thay đổi	Danh mục đóng	Có	`OPEN` khai trương · `CLOSE` đóng cửa · `PAUSE` tạm ngừng · `REOPEN` mở lại · `CHANGE_WAREHOUSE` đổi kho phục vụ
`store_code`	Mã cửa hàng	Chọn từ `dim_stores`	Có, trừ khi cửa hàng chưa có mã	Cửa hàng mới thường chưa có mã DMS — khi đó điền `store_name_planned` và bổ sung mã sau
`store_name_planned`	Tên cửa hàng dự kiến	Chuỗi	Khi chưa có `store_code`	—
`effective_date`	Ngày khai trương / đóng cửa	Ngày	Có	Không được ở quá khứ quá 1 tháng (nhập trễ thì báo)
`chain_code`	Chuỗi	Chọn từ danh mục chuỗi (42 chuỗi thật)	Có với kênh MT	Trống = cửa hàng lẻ
`channel_level_1_code`	Kênh cấp 1	Danh mục đóng	Có	`30000` MT · `20000` GT · `10000` Horeca · `40000` Bán sỉ · `50000` Thương mại điện tử
`channel_code`	Kênh chi tiết	Chọn từ `dim_account_channels`	Không	—
`serving_warehouse_code`	Kho phục vụ dự kiến	Chọn từ `dim_warehouses`	Có	Quyết định phần dự báo cộng vào kho nào — sai kho là sai kế hoạch nhập
`site_domain_code`	Địa bàn	Chọn từ `dim_site_domains`	Có	Dùng cho cấp gộp vùng, khu vực
`reference_store_code`	Cửa hàng tương tự	Chọn từ `dim_stores`	Khuyến nghị với `OPEN`	Cửa hàng mới chưa có lịch sử; hệ thống mượn nhịp bán và cơ cấu mã hàng của cửa hàng này
`freezer_count_planned`	Số tủ đông dự kiến	Số nguyên	Không	Rất quan trọng với ngành kem
`expected_cartons_month`	Sản lượng dự kiến khi ổn định (thùng/tháng)	Số	Không	Nếu có, dùng thay cho mức của cửa hàng tương tự
`ramp_up_months`	Số tháng để đạt mức ổn định	Số nguyên	Không	Mặc định đề xuất 3
`note`	Ghi chú	Chuỗi	Không	—
`confirmed_by`	Người xác nhận	Chọn từ danh sách nhân sự	Có với `OPEN`, `CLOSE`	—
`status`	Trạng thái	Danh mục đóng	Có	`DRAFT` · `CONFIRMED` · `CANCELLED`. Chỉ `CONFIRMED` đi vào mô hình

Cách B — số lượng theo kế hoạch (`store_count_plan`)

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Ghi chú
`period_ym`	Tháng	`YYYYMM`	Có	—
`chain_code`	Chuỗi	Chọn từ danh mục	Có với MT	Trống với GT
`channel_level_1_code`	Kênh cấp 1	Danh mục đóng	Có	—
`serving_warehouse_code`	Kho phục vụ	Chọn từ danh mục	Có	—
`planned_open_count`	Số cửa hàng dự kiến mở	Số nguyên ≥ 0	Có	—
`planned_close_count`	Số cửa hàng dự kiến đóng	Số nguyên ≥ 0	Có	—
`expected_cartons_per_store`	Sản lượng bình quân một cửa hàng mới (thùng/tháng)	Số	Không	Trống thì dùng bình quân cửa hàng mới cùng chuỗi, cùng kho trong 6 tháng gần nhất

Mô hình sẽ dùng thế nào (đề xuất): cửa hàng OPEN được thêm vào khung dự báo hạt cửa hàng với hồ sơ mượn từ reference_store_code; cửa hàng CLOSE bị loại khỏi khung từ effective_date; cách B thay biến tăng trưởng độ phủ của tháng trước bằng tăng trưởng theo kế hoạch.

Nhóm 3. Mã hàng mới, ngừng mã, đổi mã (`product_change_event`)

Hiện trạng: hệ thống tự nối 26 mã mới TMICC của Wall’s về mã cũ theo luật trùng tên (sku_series.successor_map). Nghiệp vụ chưa xác nhận bảng nối này. Mã ra mắt mới (NPD) và mã ngừng bán chưa có nơi nhập.

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Kiểm tra và ghi chú
`event_type`	Loại thay đổi	Danh mục đóng	Có	`LAUNCH` ra mắt · `DISCONTINUE` ngừng bán · `REPLACE` mã mới thay mã cũ
`product_code`	Mã hàng	Chuỗi	Có	Bắt đầu bằng `11`. Với `LAUNCH` cho phép mã chưa có trong `dim_products`, đánh dấu chờ đối chiếu
`product_name`	Tên hàng	Chuỗi	Với `LAUNCH`	—
`effective_date`	Ngày hiệu lực	Ngày	Có	Ngày bắt đầu bán, hoặc ngày ngừng nhận đơn
`predecessor_code`	Mã cũ được thay	Chọn từ `dim_products`	Với `REPLACE`	Ghi đè luật nối tự động. Hệ thống nối lịch sử mã cũ vào mã mới và cộng tồn của cả hai khi lập đơn đặt hàng
`analog_product_code`	Mã tương tự	Chọn từ `dim_products`	Khuyến nghị với `LAUNCH`	Mượn nhịp bán và mùa vụ
`target_channel_codes`	Kênh bán	Chọn nhiều	Với `LAUNCH`	—
`target_chain_codes`	Chuỗi đã listing	Chọn nhiều	Không	Liên kết nhóm 4
`expected_cartons_m1`, `expected_cartons_m2`, `expected_cartons_m3`	Sản lượng kỳ vọng 3 tháng đầu (thùng)	Số	Không	Nếu có, dùng làm dự báo cho mã chưa có lịch sử
`confirmed_by`	Người xác nhận	Chọn từ danh sách nhân sự	Có	—
`status`	Trạng thái	Danh mục đóng	Có	`DRAFT` · `CONFIRMED` · `CANCELLED`

Nhóm 4. Danh mục hàng theo chuỗi (`chain_assortment`)

Hiện trạng: Trade có tệp PHAN_LOAI_SKU_MT_GT_2026_v1.5_TRADE sent to IT.xlsx phân loại mã theo chuỗi. Tệp chưa được nạp vào hệ thống.

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Kiểm tra và ghi chú
`chain_code`	Chuỗi	Chọn từ danh mục chuỗi	Có	—
`product_code`	Mã hàng	Chuỗi	Có	Bắt đầu bằng `11`
`sku_class`	Phân loại	Danh mục đóng	Có	`CORE` · `FUTURE_CORE` · `NPD` · `NON_CORE`
`listed_from`	Ngày bắt đầu bày bán	Ngày	Có	—
`delisted_from`	Ngày rút khỏi chuỗi	Ngày	Không	Trống = còn bán
`source_file`, `source_version`	Tệp và phiên bản nguồn	Chuỗi	Có	Ví dụ `v1.5`

Mô hình sẽ dùng thế nào (đề xuất): mã vừa listing được thêm vào khung dự báo hạt chuỗi; mã đã delisting bị loại khỏi khung từ ngày rút.

Nhóm 5. Lịch lễ, Tết, sự kiện (`holiday_event`)

Hiện trạng: dwh.dim_dates không có cột ngày lễ. Lõi mùa vụ chỉ biết 5 ngày lễ dương lịch viết cứng trong frontier.PUBLIC_HOLIDAYS_MD (01/01, 30/04, 01/05, 01/09, 02/09). Tết Âm lịch và Giỗ Tổ Hùng Vương đổi ngày dương lịch mỗi năm nên không có. Dữ liệu bán hàng mới có đúng một lần Tết (mùng 1 Tết là 17/02/2026), nên mô hình chưa học được dạng sản lượng quanh Tết. Tết 2027 rơi vào 06/02/2027, nằm trong tầm dự báo 12 tháng hiện tại.

Bảng đề nghị tạo mới dwh.dim_holidays, hạt ngày × sự kiện. Khoảng 100–150 dòng lễ quốc gia có thể dựng sẵn; người dùng chỉ cần rà, sửa và thêm lễ địa phương.

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Kiểm tra và ghi chú
`date_key`	Ngày	Ngày	Có	Chọn trên lịch
`event_code`	Mã sự kiện	Chuỗi chữ hoa, gạch dưới	Có	Ví dụ `TET_NGUYEN_DAN`. Sinh tự động từ tên rồi cho sửa
`event_name`	Tên sự kiện	Chuỗi	Có	Ví dụ “Tết Nguyên đán — mùng 1”
`event_type`	Loại sự kiện	Danh mục đóng	Có	`LE_QUOC_GIA` · `LE_TON_GIAO` · `LE_HOI_DIA_PHUONG` · `SU_KIEN_CHINH_TRI`
`scope_level`	Phạm vi	Danh mục đóng	Có	`TOAN_QUOC` · `TINH` · `HUYEN`
`site_domain_code`	Địa bàn	Chọn từ `dim_site_domains` (137 địa bàn)	Khi phạm vi khác toàn quốc	Khoá ô này khi chọn toàn quốc
`is_day_off`	Là ngày nghỉ chính thức	Đúng / Sai	Có	Phân biệt ngày nghỉ với ngày kỷ niệm
`intensity`	Mức ảnh hưởng thương mại	Số 0,00 – 1,00	Có	Do nghiệp vụ ấn định, máy không suy ra được. Lưu lịch sử ai sửa, sửa lúc nào

Mô hình sẽ dùng thế nào (đề xuất): ngày nghỉ nhận trọng số ngày giao dịch thấp như 5 ngày lễ hiện có; working_days của tháng tới trừ thêm ngày nghỉ; riêng Tết dùng hệ số do người ấn định cho tới khi có đủ hai năm dữ liệu.

Nhóm 6. Đơn đặc biệt, sự kiện đột biến (`special_demand_event`)

Dùng cho các đơn mà nhịp lịch sử không đoán được: đơn nhập DC của chuỗi, đơn trải hàng khi chuỗi khai trương, đơn dự án, đợt xả hàng.

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Kiểm tra và ghi chú
`event_type`	Loại	Danh mục đóng	Có	`DC_ORDER` · `OPENING_FILL` · `PROJECT` · `CLEARANCE` · `OTHER`
`chain_code` hoặc `store_code`	Chuỗi hoặc cửa hàng	Chọn từ danh mục	Có một trong hai	—
`product_code`	Mã hàng	Chuỗi	Có	Bắt đầu bằng `11`
`serving_warehouse_code`	Kho giao	Chọn từ danh mục	Có	—
`period_ym`	Tháng giao	`YYYYMM`	Có	—
`qty_cartons`	Sản lượng (thùng)	Số > 0	Có	—
`is_incremental`	Cộng thêm vào dự báo	Đúng / Sai	Có	Đúng = ngoài nhịp thường, cộng thẳng vào số dự báo. Sai = đã nằm trong nhịp thường, chỉ ghi để theo dõi
`note`	Ghi chú	Chuỗi	Có với `OTHER`	—
`confirmed_by`, `status`	Người xác nhận, trạng thái	—	Có	Như các nhóm trên

Nhóm 7. Điều chỉnh tay và chỉ tiêu

Ba con số phải lưu tách nhau ngay từ đầu, để báo cáo độ chính xác dự báo không lẫn với báo cáo hoàn thành chỉ tiêu:

Tên trường	Nhãn hiển thị	Ai ghi	Làm ô nhập	Ghi chú
`forecast_model`	Số máy dự báo (thùng)	Hệ thống	Không	Không bao giờ bị ghi đè
`forecast_adjusted`	Số đã rà soát (thùng)	Kế hoạch, Sale, ASM	Có (Giai đoạn 2)	Kèm `adjustment_reason` bắt buộc
`kpi_target`	Chỉ tiêu được giao (thùng)	Kế hoạch	Có	Nhập tay hoặc tải tệp

Điều chỉnh theo hệ số $$K$$ (công thức $\text{Base} \times (1 + \sum K)$ , xem Bài toán Nghiệp vụ & Hệ thống Cấp gộp):

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Ghi chú
`k_code`	Hệ số	Danh mục đóng 6 giá trị	Có	`SEASON`, `WEATHER`, `EVENT`, `PROGRAM`, `MARKET`, `OTHER`. Không cho thêm hệ số ngoài danh mục
`k_value_pct`	Giá trị (%)	Số thực	Có	Phần trăm thay đổi so với mức nền
`period_ym`	Kỳ áp dụng	`YYYYMM`	Có	—
`scope_level`, `scope_code`	Phạm vi	Kênh / chuỗi / khu vực / kho / mã hàng	Có	Ghi rõ cấp để cộng dồn không trùng
`adjustment_reason`	Lý do	Chuỗi	Có với `MARKET`, `OTHER`	—
`confirmed_by`	Người xác nhận	Chọn từ danh sách nhân sự	Có với `MARKET`	—

Câu hỏi chưa chốt: người rà soát sửa hệ số hay sửa số lượng. Câu trả lời quyết định màn hình này.

Nhóm 8. Kỳ dữ liệu nhiễm (`excluded_period`)

Hiện trạng: danh sách nằm ở hằng EXCLUDED_MONTHS trong model_lab/src/model_lab/data/features.py, đang rỗng. Tháng bị đánh dấu sẽ bị loại khỏi huấn luyện, khỏi mốc dự báo và khỏi phần chấm điểm.

Tên trường	Nhãn hiển thị	Kiểu	Bắt buộc	Ghi chú
`period_ym`	Tháng bị loại	`YYYYMM`	Có	—
`reason`	Lý do	Chuỗi, tối thiểu 20 ký tự	Có	Phải nêu bằng chứng
`marked_by`, `marked_at`	Người và thời điểm đánh dấu	Tự sinh	—	—
`is_active`	Đang áp dụng	Đúng / Sai	Có	Tắt chứ không xoá

Chỉ hai trường hợp được đánh dấu: đổi quy ước ghi nhận dữ liệu, hoặc nhiễm bẩn đo được ngay trong dữ liệu. Sản lượng cao hay thấp bất thường thì không — đó là dao động thật.

Nhóm 9. Tham số lượt chạy (`run_config`)

Hiện trạng: các giá trị dưới đây đang viết cứng trong yearly_3grains.py (FUTURE_12_YMS, PANEL_PATH, HIST_PATH…), nên chưa tự chạy được kỳ 11/2026.

Tên trường	Nhãn hiển thị	Kiểu	Giá trị hiện tại	Ghi chú
`origin_ym`	Tháng gốc (tháng cuối đã đóng sổ)	`YYYYMM`	202609	Không được là tháng đang chạy dở — số của tháng chưa đủ ngày bị hụt mà không có cảnh báo
`horizon_months`	Số tháng dự báo	Số nguyên	12	M+1 dùng mô hình đầy đủ; M+2 trở đi kéo dài theo mùa vụ
`grains`	Cấp hạt xuất	Chọn nhiều	Kho con, Chuỗi, Cửa hàng	—
`model_name`	Mô hình	Danh mục	`chronos2_mv_cross`	—
`data_snapshot`	Bộ tệp dữ liệu	Chọn từ danh sách	Bộ tệp 04/2025 – 09/2026	Phải khớp `origin_ym`
`regime_switch_ym`	Mốc đổi quy ước ghi nhận	`YYYYMM`	202601	Tầng cây chỉ học từ mốc này
`random_seed`	Hạt giống ngẫu nhiên	Số nguyên	20260904	Để chạy lại ra đúng số cũ khi cần đối chiếu

Tài liệu gốc

Nội dung	Nơi lưu
Danh mục dữ liệu đầu vào cho Frontend (bản 07/09/2026, mô tả bàn thử `model_lab`; dùng tên trường cũ tiếng Việt cho nhóm 7, 8)	`docs/05-thi-cong-gd1/DANH-MUC-DU-LIEU-DAU-VAO_DBNC-v0.1.md`
Đặc tả giao diện nạp dữ liệu	`docs/05-thi-cong-gd1/DAC-TA-DAU-VAO-GIAO-DIEN_DBNC-v0.1.md`
Mẫu tệp nạp CTKM	`docs/05-thi-cong-gd1/MAU-NAP-CTKM_DBNC-v0.1.xlsx`
Luồng nạp CTKM của bản demo	`forecast_demo/src/forecast_demo/ingest/ctkm.py`, `forecast_demo/src/forecast_demo/engine/promo.py`
Phần sản lượng ngoài tầm với (cửa hàng mới, mã mới)	`model_lab/out/error-floor.md`, `model_lab/out/csv/error-floor.csv`

Dữ liệu Người dùng Nhập Trước Kỳ Dự báo

1. Tóm tắt chín nhóm

Nhóm 1. Lịch chương trình khuyến mãi

Nhóm 2. Cửa hàng mở mới, đóng cửa

Cách A — từng cửa hàng (store_change_event)

Cách B — số lượng theo kế hoạch (store_count_plan)

Nhóm 3. Mã hàng mới, ngừng mã, đổi mã (product_change_event)

Nhóm 4. Danh mục hàng theo chuỗi (chain_assortment)

Nhóm 5. Lịch lễ, Tết, sự kiện (holiday_event)

Nhóm 6. Đơn đặc biệt, sự kiện đột biến (special_demand_event)