Lớp dữ liệu HIỆU SUẤT theo thời gian — schema + luật ghi

Lớp này khác data/ ở chỗ cơ bản nhất: hình dạng dữ liệu.

🔴 Luật số một: KHÔNG sửa và KHÔNG xoá dòng đã có trong fact_metrics.csv. Một phép đo sai vẫn là sự thật về điều extranet trả về hôm đó. Muốn sửa thì thêm mốc mới, hoặc thêm cột đánh dấu — đừng viết lại lịch sử.

Sáu thành phần

metrics/
├── dim_property.csv           CHIỀU  — 1 dòng mỗi (căn × kênh). Thay đổi chậm.   7 dòng
├── fact_metrics.csv           SỰ KIỆN dạng DÀI — 1 dòng = 1 phép đo.            935 dòng
├── fact_reservations.csv      SỰ KIỆN — 1 dòng = 1 ĐƠN đặt phòng.               164 dòng
├── fact_funnel.csv            SỰ KIỆN dạng RỘNG — 1 dòng = mốc × căn × KỲ.       35 dòng
├── fact_reviews.csv           SỰ KIỆN — 1 dòng = 1 REVIEW.                       14 dòng
├── booking_ranking.csv        SỰ KIỆN — 1 dòng = 1 căn × 1 lượt tìm kiếm CÔNG KHAI (thêm 26/09/2026)
├── crawl_log.csv              NHẬT KÝ — 1 dòng mỗi lần cào.                       4 dòng
└── _raw/…/                    payload gốc nén gzip + _manifest.json

Bảng nào do lượt cào nào lấp — và kiểm đủ bằng gì

🔴 Cào "xong" mà một trong sáu ô kiểm trên chưa đạt thì chưa xong. Chỗ hay hụt nhất là fact_reservations: cửa sổ hỏng thường là cửa sổ đông đơn nhất, bỏ qua là mất cả chục đơn mà không bảng nào báo.

_raw/ là bảo hiểm: bộ trích có bug thì dựng lại số từ payload gốc, không phải đi cào lại (và không cào lại được — extranet không cho xem số của quá khứ).

Tên file trong _raw/ và cách soát độ phủ

<slug>__<trang>__<file mạng>.gz, <trang> là một trong reviews · sales · showrank. Nhìn tên là biết payload của căn nào, trang nào — không phải giải nén ra mới biết.

⚠️ File tên dạng NN-admin.booking.com_hotel_hoteladmin_extranet__… là của lược đồ cũ (trước 23/09/2026). Lược đồ đó cắt tên thư mục ở 46 ký tự nên mất cả hotel_id lẫn tên trang, và chạy bù trong cùng ngày thì ghi đè lên nhau. Đừng dùng lại.

_manifest.json có ba khối đọc được ngay, không cần mở file .gz nào:

Cào bù trong cùng ngày thì manifest được gộp, không ghi đè — mất mục lục là mất luôn khả năng biết payload nào đã có.

🔴 Payload trả về rỗng vẫn phải giữ. salesInsightsTotal với data: [], hoặc với propertyValue: -1, là bằng chứng đã hỏi và extranet trả về không có gì — đó là thứ duy nhất phân biệt 0 thật với cào hụt.

-1 của Booking nghĩa là "không có dữ liệu", không phải "bằng 0"

salesInsightsTotal trả roomNights · totalTransactionValue · averageDailyRate cùng bằng -1 (kể cả benchmarkValue) khi căn không có đêm ở nào trong cửa sổ 12 tháng; kèm theo salesInsightsBreakdown.rooms: []. Bộ trích bỏ qua giá trị âm — ghi -1 vào bảng là bịa số, mà ghi 0 cũng là bịa vì extranet không nói thế.

⇒ Căn trống cả khối 12m không mặc nhiên là cào hụt. Mở _raw/<slug>__sales__*.gz: thấy -1 hoặc data: [] là đã hỏi rồi; không có file mới là chưa hỏi được. Đã xác minh trên alacarte404, 23/09/2026 (đối chứng alacarte305: 174 đêm / 336.132.266 ₫).

Lược đồ fact_metrics.csv

Khoá tự nhiên: (snapshot_date, channel, slug, metric, period_start, period_end). Nạp lại cùng khoá thì thay giá trị, không đẻ dòng trùng — ota-metrics.py append lo việc đó.

🔴 Bẫy chết người: mỗi chỉ số có CỬA SỔ ĐO RIÊNG

⇒ Chia revenue (12 tháng) cho bookings (90 ngày) là ra một con số vô nghĩa. Analyst phải WHERE window = '12m' trước khi so sánh hay cộng. Cột window tồn tại chính vì lý do đó.

Lịch sử TỪ KHI MỞ LISTING — window = 1m và alltime

Cửa sổ 12 tháng ở trên là mặc định của trang, không phải giới hạn của dữ liệu. Trang doanh thu đọc khoảng ngày từ query string, nên nới bằng URL chứ không phải bấm date-picker (ô đó không nhận chữ gõ vào):

statistics/sales_insights.html?hotel_id=<id>&fromDate=2015-01-01&untilDate=<hôm nay>
   &granularity=MONTHLY&reservationType=STAYED&showTotals=true

Đặt fromDate sớm hơn mọi listing là được — Booking không báo lỗi, chỉ cắt về mốc sớm nhất nó phục vụ. Payload salesInsightsGranular trả một điểm mỗi tháng, salesInsightsTotal trả tổng của đúng khoảng đã xin.

⚠️ Mốc sàn là của TÀI KHOẢN, không phải của từng listing. Xin fromDate=2015-01-01 thì cả bảy căn đều trả chuỗi bắt đầu 2023-06 (40 tháng tính tới 09/2026) — giống hệt nhau, nên đó không thể là ngày mở của từng căn. Chưa xác minh được 2023-06 là giới hạn lưu trữ của Booking hay ngày mở tài khoản đối tác. Các tháng trước lần ở đầu tiên của mỗi căn được đệm bằng 0, không phải khuyết.

⇒ Với danh mục hiện tại chuyện này vô hại: lần ở sớm nhất của mọi căn đều sau 2023-06, nên chuỗi đã phủ trọn lịch sử. Nhưng đừng đọc tháng đầu chuỗi thành "ngày mở listing" — muốn biết ngày mở thì tra chỗ khác.

python3 scripts/ota-metrics-crawl.py --history            # cả 7 căn, từ khi mở
python3 scripts/ota-metrics-crawl.py --history --from 2019-01-01 --only alacarte305

🔴 1m là chuỗi thật, 12m/alltime là số đã cộng sẵn — đừng trộn. Cộng 1m lại sẽ ra đúng alltime của cùng khoảng; cộng 1m với 12m là tính hai lần. Chuỗi 1m không đổi về quá khứ, nên nó cũng là thứ cho phép đọc xu hướng ngay từ mốc cào đầu tiên, không phải chờ đủ ba tuần.

fact_reviews.csv — từng review một

fact_metrics.csv chỉ giữ hai con số về review (review_count, review_score). Payload gốc có nhiều hơn thế, nên có bảng riêng: ngày ở, sáu điểm thành phần, nhận xét tốt/xấu, quốc tịch, ngôn ngữ, đã trả lời hay chưa.

python3 scripts/ota-reviews-extract.py          # dựng lại từ payload ĐÃ CÓ trong _raw/, không cần mạng
node scripts/ota-read-booking-reviews.mjs --out <dir>   # tải mới, rows=500 nên không sót trang sau

🔴 Điểm thành phần 0 nghĩa là KHÔNG ĐÁNH GIÁ, không phải điểm không. Thang chạy 2,5–10 theo nửa điểm; khách không tiếp xúc hạng mục nào thì ô đó về 0 (vd nhận phòng tự động → không chấm staff). Bảng giữ nguyên 0 vì đó là thứ payload trả về — mọi phép trung bình phải WHERE <cột> > 0, nếu không một ô trống kéo tụt cả danh mục. Đo 23/09/2026: gộp cả ô 0 thì staff ra 9,11 và đội sổ; loại ra thì 9,81 và đứng thứ hai từ trên.

⚠️ Trang reviews.html chỉ nạp 10 review đầu. Căn nào nhiều hơn là bộ cào theo trang mất phần đuôi (alacarte305: pageCount 2, lấy 10/12). Dùng script .mjs ở trên — nó xin thẳng rows=500 qua review/fetch_reviews.json, và phải có &ses=<token> lấy từ tab extranet đang mở, thiếu là Booking đá sang trang đăng nhập dù Chrome vẫn đăng nhập.

Không lưu tên khách và số đặt phòng: lớp này để phân tích, không để liên hệ.

Reservation — fact_reservations.csv

Doanh thu và đêm phòng ở trên là số đã cộng. Muốn biết có bao nhiêu ĐƠN, đặt vào lúc nào, ở mấy đêm, huỷ hay không thì phải xuống tầng đơn lẻ, và tầng đó nằm ở trang Reservations.

node scripts/ota-read-booking-reservations.mjs          # cào, tự chia cửa sổ theo quý
python3 scripts/ota-reservations-extract.py             # nạp vào fact_reservations.csv

✅ Trang GROUP không có hai trần đó — lấy TRỌN lịch sử (đo 26/09/2026)

admin.booking.com/hotel/hoteladmin/groups/reservations/index.html (menu nhóm → Reservations) trả mọi property một lần, không ép 1 năm, không giới hạn 3 tháng: dải nhận phòng 2010–2030 ra 189 đơn = dải 2023–2027; 2010–2022 ra 0; theo ngày đặt / ngày trả cũng 189 ⇒ đó là toàn bộ (đơn sớm nhất đặt 25/12/2024, nhận phòng sớm nhất 09/01/2025). Kiểm chéo: 165/165 đơn của lượt cào theo property có mặt, trang group thêm 24 đơn (23 đơn nhận phòng 2025 mà trang property cắt mất). Nút Download của trang (tạo file sau ~3 phút "Retrieving file") ra Reservations_<from>_<to>.xls khớp 189/189 mã.

• Cào: node scripts/ota-read-booking-group-reservations.mjs [--from 2023-01-01 --to 2027-12-31] → JSON có tên khách ở _private/reservations/<ngày>/ (đã .gitignore, không commit). GraphQL searchReservations, 🔴 pagination.offset là SỐ TRANG (0,1,2…) chứ không phải số dòng; rowsPerPage 30 (200 → lỗi 500).
• Nạp fact_reservations bằng gộp theo khoá (channel, slug, reservation_id) như ota-reservations-extract.py (đơn đã có thì THAY, giữ lại rooms/is_last_minute cũ khi nguồn group để trống) — ⚠️ 26/09 lần đầu lỡ nối thẳng thành 354 dòng trùng, đã gộp lại 27/09 còn 189 dòng = 189 đơn. Mốc 2026-09-26 là bản trọn đời 189 đơn từ nguồn group (source_file = groups/reservations …); cột rooms và is_last_minute để trống (nguồn không có); đơn không ok ghi price_vnd = 0 như quy ước cũ (giá gốc đơn huỷ còn trong bản _private). Bản CSV không tên khách: _raw/reservations-group/2026-09-26/booking-reservations-all.csv.
• ⇒ Lượt reservation của /ota-metrics-crawl nên dùng script group; script property chỉ còn cần khi muốn cột rooms.

🔴 Hai trần của Booking — đo 23/09/2026, không phải giới hạn của công cụ

⇒ Đơn nhận phòng trước hôm nay − 1 năm là không lấy được. Doanh thu và đêm phòng của giai đoạn đó thì vẫn có (window = 1m, lùi tới 2023-06) — nên số đêm có lịch sử dài hơn số đơn, và hai đường trên cùng một biểu đồ sẽ bắt đầu ở hai thời điểm khác nhau. Nói rõ điều đó trên biểu đồ, đừng để người đọc tưởng trước đó không có đơn nào.

Ba thứ tưởng làm được mà không

• page và perpage trên URL bị bỏ qua — trang luôn gọi page=1&perpage=100.
• token của endpoint là nonce dùng một lần; phát lại đúng URL đó trả success: 0, nên không tự phân trang bằng fetch được.
• Chặn fetch/XHR trong trang cũng không bắt được gì (calls:1 mà n:0) — request đi từ realm khác. Đường chạy được là để chrome-grab.mjs bắt ở tầng mạng.

Phép kiểm đủ

Mỗi cửa sổ tự đối chiếu: cộng price.amount của các đơn nhận được, so với totalPrice mà API trả cho toàn bộ tập lọc. Khớp thì cửa sổ đó chắc chắn không sót trang — mạnh hơn nhiều so với tin vào cờ hasNextPage, vì cờ đó từng trả '' cho cả trang đầy. Cờ complete trong file kết quả là AND của mọi cửa sổ.

fact_funnel.csv — phễu theo KỲ

Cùng dữ liệu phễu với fact_metrics nhưng ở dạng rộng (một dòng đọc thẳng được) và có thêm chiều kỳ: Ranking Dashboard cho chọn 30 · 60 · 90 · 365 ngày, mỗi kỳ một dòng.

node scripts/ota-read-booking-funnel.mjs     # đổi bộ chọn kỳ, bắt response, lưu payload thô
python3 scripts/ota-funnel-extract.py        # nạp vào bảng

🔴 Các kỳ CHỒNG lên nhau. Kỳ 90 ngày đã bao trùm kỳ 30 ngày — trừ kỳ này cho kỳ kia rồi đọc thành "hai tháng trước" là sai, vì không biết phần chênh rơi vào ngày nào.

🔴 bookings đếm đơn ĐƯỢC ĐẶT trong kỳ, GỒM CẢ đơn sau này huỷ. Nên conversion ở đây là chuyển đổi sang lượt đặt, không phải sang đêm ở. Với tỷ lệ huỷ 53% của danh mục, hai thứ đó cách nhau rất xa — muốn con số thật thì nối sang fact_reservations qua (slug, booked_at) và lọc status = 'ok'.

⚠️ 365 ngày là trần. Xa hơn Booking không phục vụ. Muốn chuỗi thời gian thật của phễu thì phải tự tích luỹ qua từng mốc cào hằng tuần — khác hẳn doanh thu, vốn có sẵn chuỗi tháng lùi tới 2023-06.

booking_ranking.csv — thứ hạng trên trang tìm kiếm CÔNG KHAI booking.com (thêm 26/09/2026)

Bản đôi của ../metrics-agoda/agoda_ranking.csv (tên do user đặt theo cặp). Nguồn: scripts/ota-booking-search-rank.mjs — mở browser context sạch (không đăng nhập, không lịch sử), bắt GraphQL FullSearch rồi phát lại theo offset; căn nào không lọt vào danh sách thì hỏi riêng (destType: HOTEL) để biết còn phòng không. Chỉ thêm, không sửa. Đây là thứ hạng cho đúng một tìm kiếm; hạng thành phố chính thức 90 ngày (competitiveSetLeaderboard, vd 305 #1.039/3.241) nằm ở Ranking Dashboard extranet — số khác bản chất, đừng trộn.

🔴 Ba bẫy đã đo: (1) tài khoản đăng nhập bị cá nhân hoá — 25AT11 #1 / 41LHC #5 khi đăng nhập, #122–136 / #104 ở context sạch; (2) &offset= trên URL bị bỏ qua, phải đi qua FullSearch; (3) sau ~1.000 kết quả Booking chỉ trả dòng lặp, nên căn chìm sâu hơn mốc đó không đo được thứ hạng, chỉ biết là beyond_cap.

Dùng

python3 scripts/ota-metrics.py log              # nhật ký các lần cào
python3 scripts/ota-metrics.py table            # bảng rộng của mốc mới nhất
python3 scripts/ota-metrics.py trend revenue    # xu hướng một chỉ số, có % thay đổi giữa các mốc
python3 scripts/ota-metrics.py check            # soát: slug lạ · dòng trùng · thiếu cửa sổ · thiếu giá trị
python3 scripts/ota-metrics.py append rows.json # nạp thêm, idempotent

Analyst mở thẳng bằng pandas hoặc DuckDB, không cần tool của repo:

import pandas as pd
f = pd.read_csv('vault/19-Harthliving-OTA/performance/metrics/fact_metrics.csv')
d = pd.read_csv('vault/19-Harthliving-OTA/performance/metrics/dim_property.csv')
df = f.merge(d, on=['slug','channel'])

# xu hướng doanh thu theo căn
(df[df.metric=='revenue']
   .pivot_table(index='snapshot_date', columns='name', values='value'))

# phễu 90 ngày — LỌC CỬA SỔ TRƯỚC
(df[(df.window=='90d') & df.metric.isin(['search_impressions','page_views','bookings'])]
   .pivot_table(index='name', columns='metric', values='value'))

-- DuckDB đọc thẳng CSV, không cần nạp
SELECT slug, metric, value FROM 'fact_metrics.csv'
WHERE window = '12m' AND snapshot_date = (SELECT max(snapshot_date) FROM 'fact_metrics.csv');

Vì sao CSV chứ không phải database

7 listing × ~12 chỉ số × cào hằng tuần ≈ 4.400 dòng/năm. Ở cỡ này CSV thắng tuyệt đối: đọc được bằng mắt, diff được trong git (thấy ngay số nào đổi giữa hai lần cào), mở bằng pandas / DuckDB / Excel, không cần server, không cần migration. Dựng warehouse cho vài nghìn dòng là tự tạo việc bảo trì mà không đổi lại được gì.

Ngưỡng nên đổi: khi vượt ~1 triệu dòng, hoặc khi cần nhiều người ghi đồng thời. Lúc đó chuyển sang Parquet + DuckDB là bước kế tiếp tự nhiên — lược đồ dạng dài này giữ nguyên, không phải viết lại.

Nhịp cào đề xuất

Hằng tuần, cùng thứ trong tuần — khoảng cách đều thì xu hướng mới đọc được.

Một lượt đầy đủ gồm bốn lần cào theo thứ tự, xem /ota-metrics-crawl: chỉ số nền → lịch sử doanh thu (--history) → reservation → phễu nhiều kỳ. Lượt reservation phải chạy trước lượt phễu, vì bộ trích phễu dò ngược cửa sổ bằng fact_reservations.

Sau mỗi lần cào nhớ ghi một dòng vào crawl_log.csv: thiếu nhật ký thì sau này không biết khoảng trống trong chuỗi là không cào hay cào mà không có số.

Lịch sử