Lớp dữ liệu listing — nguồn sự thật duy nhất

Mục lục

data/ — nguồn sự thật duy nhất cho mọi listing
Vì sao có lớp này
Dùng
Bộ khoá
Thêm một căn
Trạng thái hiện tại

`data/` — nguồn sự thật duy nhất cho mọi listing

Mỗi file data/<slug>/<kênh>.json chứa toàn bộ sự thật đã xác minh của một căn trên một kênh, ở dạng máy đọc được.

Khi JSON và Markdown lệch nhau, JSON đúng. File .md trong properties/ là lớp trình bày cho người đọc, sinh ra từ cùng dữ liệu này.

Vì sao có lớp này

Trước 08/09/2026 mọi fact nằm trong văn xuôi Markdown. Ba hệ quả đo được:

Không tra được bằng máy. Câu "Swimming pool → Outdoor · All year · Paid · 06:00–19:00" là chữ trong bảng; muốn biết bể bơi có thu phí không thì phải đọc hiểu.
Cùng một con số viết hai kiểu. Giá buffet xuất hiện 3 lần dạng 285.000₫ và 3 lần dạng 285,000 VND trong cùng một bộ hồ sơ. Grep một dạng là hụt một nửa.
Không so được giữa các căn. Muốn biết 502 thiếu gì so với 305 thì phải mở hai file và đọc tay.

Dùng

python3 scripts/listing-data.py list                    # có những file nào
python3 scripts/listing-data.py check                   # kiểm khoá bắt buộc + trường còn trống
python3 scripts/listing-data.py show alacarte305        # in gọn một listing
python3 scripts/listing-data.py compare booking         # bảng đối chiếu mọi căn cạnh nhau
python3 scripts/listing-data.py gaps alacarte305        # căn khác THIẾU gì so với căn mẫu
python3 scripts/listing-data.py get alacarte305 facilities.swimming_pool.paid

gaps là lệnh đáng dùng nhất khi đã có ≥2 căn: lấy một căn làm chuẩn, liệt kê tiện ích căn kia chưa bật và mọi chỉ số thấp hơn căn chuẩn.

Bộ khoá

Khối	Chứa gì
`read`	ngày đọc, đọc bằng gì, trỏ tới `_raw/` chứa dump thô
`identity`	tên, địa chỉ, toạ độ, trạng thái, URL công khai
`scores`	page score, review tổng + từng hạng mục, điểm công ty, điểm của đối thủ cùng toà
`photos`	tổng, số hiện public, số bị gắn cờ kém, smart ordering
`room`	loại phòng, diện tích, số phòng ngủ/tắm, cấu hình giường từng phòng, sức chứa
`fees_taxes`	VAT, phí dọn, giá bữa sáng cả ba nguồn, giá đỗ xe khai vs thật
`policies`	giờ nhận/trả, thanh toán, trẻ em, nội quy, từng chính sách huỷ kèm số liệu 90 ngày
`facilities`	từng tiện ích: `on` · `paid` · `hours` · `features` · `price_vnd`
`amenities_room`	danh sách tiện nghi trong phòng
`accessibility`	khai báo tiếp cận xe lăn
`messaging`	mẫu tin, lịch gửi, cờ cảnh báo như `contains_door_code`, `asks_for_star_rating`
`sustainability`	đã bắt đầu chưa, chứng nhận
`profile`	hồ sơ chủ nhà, độ dài từng ô chữ
`public_view`	thứ khách thật sự thấy: huy hiệu, chip, số nhóm tiện ích, câu phủ định đang chạy
`issues`	mã `L-nn` liên quan, tra chéo sang `../issues.md`

Quy ước: null = chưa đọc được, khác với false = đã đọc và đúng là không. Mọi số tiền là số nguyên VND, không kèm ký tự — định dạng để lớp hiển thị lo.

Thêm một căn

Cào bằng node scripts/chrome-grab.mjs --out vault/18-ota-listings/properties/<slug>/_raw/<ngày>-<kênh>/ …
Tạo data/<slug>/<kênh>.json theo đúng bộ khoá trên — thiếu khoá nào thì check báo, không cần sửa script.
python3 scripts/listing-data.py check rồi gaps alacarte305 để thấy ngay căn mới hụt gì.

Trạng thái hiện tại

Căn	Kênh	Ngày đọc
`alacarte305`	booking	2026-09-08

Sáu căn còn lại (alacarte404 · alacarte502 · 15nuocman5 · 181tohienthanh · 41lehycat · 25anthuong11) chưa có file dữ liệu — mới chỉ có hồ sơ Markdown.

Lớp dữ liệu listing — nguồn sự thật duy nhất