📄 / / root / .hermes / skills / research / tourism-accommodation-database-update / SKILL.md

Quy trình Cập nhật và Xây dựng Cơ sở Dữ liệu Lưu trú

name: tourism-accommodation-database-update description: Quy trình thu thập, đối chiếu chéo dữ liệu cơ sở lưu trú (4-5 sao) và xuất dữ liệu sang Google Sheets phục vụ quy hoạch du lịch vùng. category: research

Quy trình Cập nhật và Xây dựng Cơ sở Dữ liệu Lưu trú

Kịch bản này hướng dẫn cách thu thập dữ liệu chính thống từ cơ quan quản lý nhà nước, đối chiếu chéo thông tin trên các kênh OTA và CSDL Quốc gia, chạy kiểm định chất lượng qua Grill QA và đồng bộ tự động lên Google Sheets. Quy trình này có thể áp dụng cho phân khúc 5 sao hoặc mở rộng sang phân khúc 4 sao.

Điều kiện kích hoạt

Áp dụng khi người dùng yêu cầu xây dựng hoặc cập nhật cơ sở dữ liệu khách sạn, resort theo phân hạng sao tại các khu vực quy hoạch du lịch trọng điểm.

Quy trình Thực hiện 6 Bước

Bước 1: Thu thập Dữ liệu Chính thống và CSDL Quốc gia (Tầng Pháp lý)

Ưu tiên tra cứu trên trang Cơ sở dữ liệu ngành Du lịch Việt Nam (csdl.vietnamtourism.gov.vn) bằng cách lọc theo tỉnh thành và hạng sao mong muốn để có danh sách danh nghĩa chính thức (ví dụ: Khánh Hòa có 55 cơ sở 5 sao trên CSDL Quốc gia).
Khi phát hiện tệp tài liệu PDF hoặc văn bản phụ lục từ Sở Du lịch địa phương, cần kiểm tra thời điểm ban hành để loại trừ nếu dữ liệu đã lỗi thời (outdated) so với dữ liệu thời gian thực trên CSDL Quốc gia.
Nếu sử dụng tài liệu PDF, chuyển đổi sang văn bản thuần bằng lệnh: bash pdftotext /path/to/danh_sach.pdf /path/to/danh_sach.txt
Cơ chế tìm kiếm và cấu trúc Routing của CSDL Quốc gia:
Cổng thông tin CSDL Du lịch Việt Nam không hỗ trợ truy cập trực tiếp bằng các tham số GET tùy ý như ?item=ID khi không có phiên làm việc (Session) được thiết lập hoặc khi truy cập bằng các thư viện HTTP raw (như urllib, requests) mà không giả lập đầy đủ trình duyệt hoặc mang theo đúng Cookie/CSRF token. Khi truy cập thô không có session, hệ thống server của Cục sẽ tự động rơi về trạng thái trả về kết quả tìm kiếm mặc định đầu tiên trong CSDL (ví dụ: luôn trả về "Khách sạn Mercure Hải Phòng" với địa chỉ 12 Lạch Tray cho mọi ID, khiến lập trình viên dễ lầm tưởng CSDL quốc gia bị lỗi lệch dòng/tráo dòng chéo trên diện rộng).
Cách xử lý đúng: Phải điều hướng thông qua trang danh mục tìm kiếm chính (ví dụ: cslt/?province=56%2C58&rate%5B0%5D=1&page=X) để server thiết lập Cookie session và render dữ liệu AJAX/HTML đầy đủ trước khi thực hiện trích xuất dữ liệu, hoặc sử dụng trình duyệt headless (Browser tool) để mô phỏng chính xác hành vi của người dùng thực tế. Việc cào dữ liệu qua trình duyệt headless cần phải điều hướng tuần tự qua các trang danh mục, đợi AJAX render đầy đủ danh sách kết quả (chứa sẵn Tên, Địa chỉ, Số phòng, SĐT, Website, Email của từng cơ sở) rồi tiến hành bóc tách trực tiếp từ trang danh mục đó thay vì cố gắng request riêng lẻ từng trang chi tiết qua ID.
Trường hợp các cơ sở đặc thù (Amanoi Vĩnh Hy, An Lâm Retreats Ninh Vân Bay, L'Alya Ninh Vân Bay):
Nhiều siêu nghỉ dưỡng vận hành theo tiêu chuẩn quốc tế (như Amanoi Vĩnh Hy, An Lâm Retreats, L'Alya) có triết lý thương hiệu không đăng ký xếp hạng sao nội địa, hoặc chỉ làm thủ tục thông báo điều kiện tối thiểu với Sở Du lịch địa phương chứ không có Quyết định công nhận hạng sao từ Cục Du lịch Quốc gia. Do đó, các cơ sở này hoàn toàn vắng bóng trong danh sách công nhận hạng sao 5 sao trực tuyến của CSDL Quốc gia.
Quy tắc biên tập: Phải chủ động rà soát qua các báo cáo thực tế, trang tin du lịch địa phương hoặc cổng thông tin của Sở để phát hiện các khu nghỉ dưỡng cao cấp nằm ngoài danh sách online của Cục. Khi phát hiện, ghi nhận riêng các cơ sở này trong phần phụ lục đặc biệt của báo cáo để đảm bảo tính đầy đủ về mặt hạ tầng thực tế, và bổ sung vào cơ sở dữ liệu với số phòng thực tế và ghi chú "Dữ liệu khảo sát".
Lưu ý thao tác trên Google Sheets:
Khi cập nhật dữ liệu đồng bộ lên Google Sheets, nếu người dùng đã tạo công thức tự động tính toán (auto update) trong tab tổng quan (ví dụ: tab "Tổng quan Chỉ số Sức tải"), tuyệt đối không được ghi đè, xóa hoặc thay đổi bất kỳ ô dữ liệu nào ở tab tổng quan này.
Chỉ được phép xóa và cập nhật dữ liệu thô trên các tab danh sách chi tiết (ví dụ: các tab phân vùng) để đảm bảo các công thức tự động của người dùng không bị lỗi tham chiếu hoặc bị ghi đè mất.
Đồng bộ hóa dữ liệu hoạt động du lịch từ NotebookLM:
Khi cập nhật số liệu hoạt động du lịch (ví dụ: số lượt khách, khách nội địa, khách quốc tế, doanh thu du lịch, chi tiêu bình quân) cho toàn địa bàn nghiên cứu, phải ưu tiên tra cứu trực tiếp bằng RAG thông qua NotebookLM bằng cách sử dụng các Notebook đã được cung cấp (ví dụ: Notebook cdcc2614-c5cf-4a37-8aa7-34e3f26a3a36 cho du lịch Khánh Hòa và các sự kiện sáp nhập hành chính).
Quy tắc trích xuất dữ liệu: Chỉ được phép ghi nhận dữ liệu nếu NotebookLM cung cấp thông tin rõ ràng và có trích dẫn nguồn (citation). Nếu NotebookLM không có dữ liệu (ví dụ: công suất lấp phòng cả năm), phải ghi nhận rõ là tài liệu chưa có thông tin chứ tuyệt đối không được tự ý bịa đặt (fabricate) hoặc suy diễn từ các nguồn không chính thống khác.
Cú pháp tiếng Việt: Trong mọi phần văn bản giải trình hoặc báo cáo bằng tiếng Việt, tuyệt đối không sử dụng dấu gạch nối trong văn xuôi (ví dụ: viết "không có thông tin" thay vì "không-có-thông-tin", viết "60 phần trăm" thay vì "60%").
Báo cáo phê bình Grill QA: Mọi deliverable về nghiên cứu thị trường/chính sách du lịch phải được Grill QA phê bình qua skill research-critism với format báo cáo: grill_qa_critique_<topic>_v<version>.md. Không được bỏ qua bước này trước khi đưa vào sản phẩm chính.

Bước 2: Thẩm định và Hiệu đính dữ liệu mismatch (Tầng Kỹ thuật)

Cảnh báo lỗi hệ thống CSDL Quốc gia: Trang csdl.vietnamtourism.gov.vn thường gặp lỗi tráo cột dữ liệu (mismatch) nghiêm trọng giữa ID/Tên khách sạn và các trường Địa chỉ, Số phòng thực tế của các bản ghi liền kề do lỗi kết xuất cơ sở dữ liệu trên server của Cục.
Quy trình hiệu đính bắt buộc:
Không được tin cậy hoàn toàn vào việc cào tự động (Scrape) từ CSDL Quốc gia mà thiếu bước đối soát chéo.
Phải viết mã đối chiếu chéo (Cross-check) và hiệu đính thủ công (hoặc map đè dữ liệu) dựa trên thông tin xác thực từ trang chủ của chính khách sạn và các trang OTA uy tín (Chudu24, Booking, Agoda) để đưa các trường địa chỉ và số phòng thực tế về đúng thực thể vật lý.
Đối chiếu chéo số phòng giữa nguồn thiết kế vật lý ban đầu và thực tế vận hành thương mại:
Ví dụ thực tế: Khách sạn Havana Nha Trang thiết kế ban đầu có 1.260 phòng (hiển thị trên các OTA quảng cáo), nhưng website chính thức của khách sạn công bố vận hành 1.060 phòng 5 sao (do 200 phòng condotel không tham gia rental pool). Xét trên góc độ quy hoạch hạ tầng và sức tải vật lý, vẫn ghi nhận con số 1.260 phòng vì tải trọng thực tế đè nặng lên hạ tầng kỹ thuật là không đổi.

Bước 2b: Cập nhật Chỉ số Sức tải (Kinh tế - Địa lý)

Sử dụng Niên giám Thống kê (Statistical Yearbook) của tỉnh phát hành trong năm hiện tại hoặc gần nhất (ví dụ: đang ở năm 2026, bắt buộc phải dùng Niên giám 2025 công bố đầu năm 2026, tuyệt đối không chấp nhận dùng số liệu 2024 trừ khi có giải trình bất khả kháng).
Trích xuất chính xác Diện tích (km2) và Dân số trung bình của các đơn vị hành chính sau khi sáp nhập hoặc điều chỉnh địa giới (Nghị quyết của Quốc hội/Chính phủ).
Tính toán Hệ số phòng 5 sao / 1.000 dân làm chỉ số đo lường sức tải và mức độ tập trung hạ tầng chính:
Công thức: Hệ số = (Tổng số phòng 5 sao) / (Dân số / 1000).
Thống kê này giúp xác định áp lực hạ tầng (Nha Trang thường có hệ số > 20, trong khi các khu vực mới phát triển hoặc biệt lập có hệ số thấp hơn nhiều).

Bước 3: Rà soát Địa giới Hành chính và Phân vùng Địa lý

Xác định rõ ranh giới hành chính tại thời điểm nghiên cứu. Tuyệt đối không gộp chung các tỉnh độc lập (như Khánh Hòa và Ninh Thuận) vào một thực thể hành chính duy nhất trừ khi có nghị quyết phê duyệt chính thức từ Quốc hội. Nếu có nghị quyết sáp nhập (ví dụ: dự báo theo Quyết định 759/QD-TTg), phải ghi rõ bối cảnh "Dự báo/Giả định" và vẫn duy trì số liệu độc lập để đối chiếu.
Phân nhóm cơ sở theo các cụm ngành phát triển kinh tế du lịch thực tế (ví dụ: Nha Trang, Cam Ranh - Cam Lâm, Vân Phong - Ninh Hòa, Ninh Thuận).

Bước 4: Hợp nhất Cơ sở Dữ liệu JSON (Single Source of Truth)

Thiết lập cấu trúc lưu trữ dữ liệu tại thư mục dự án dưới dạng tệp tin db_co_so_luu_tru.json:

{
  "tinh_thanh_1": [
    {
      "item_id": "8000",
      "ten": "Tên Khách Sạn",
      "so_phong": 100,
      "dia_chi": "Địa chỉ cụ thể",
      "khu_vuc": "Nha Trang",
      "url": "https://csdl.vietnamtourism.gov.vn/cslt/?item=8000"
    }
  ],
  "meta_stats": {
    "Nha Trang": {
      "dien_tich": 254.38,
      "dan_so": 420000
    }
  }
}

Bước 5: Thẩm định và Kiểm tra Chất lượng (Grill QA Critique)

Khởi động subagent Grill QA (grill-qa) để thực hiện rà soát độc lập, phê bình chất lượng nghiên cứu bằng skill research-critism. Mọi báo cáo phê bình bắt buộc phải đặt tên theo định dạng grill_qa_critique_<topic>_v<version>.md và lưu vào thư mục reports/. Các lỗi cần phê bình: 1. Chênh lệch số học: Tổng số buồng phòng của tỉnh phải bằng tổng số phòng các phân vùng cộng lại. Số lượng cơ sở trong danh sách phải khớp chính xác với số lượng khai báo ở tiêu đề. 2. Lọc sạch trùng lặp chéo: CSDL Quốc gia thường khai báo 2 bản ghi cho cùng 1 thực thể (ví dụ: Alma và Alma Cam Ranh). Phải loại bỏ trùng lặp cơ học này trước khi chốt danh sách. 3. Sai lệch liên kết: Đảm bảo link CSDL chi tiết trỏ đúng ID thực tế của cơ sở đó trên trang CSDL Quốc gia.

Bước 6: Đồng bộ hóa tự động lên Google Sheets

Sử dụng Google Sheets API để ghi đè dữ liệu: 1. Tạo một Spreadsheet mới trên Drive. 2. Tạo các tab riêng biệt tương ứng với từng cụm phân vùng địa lý để người dùng dễ theo dõi. 3. Ghi tiêu đề cột ở dòng 1: ["STT", "Tên Cơ sở Lưu trú (CSDL Quốc gia)", "Số lượng buồng/phòng", "Địa chỉ thực tế", "Link CSDL Chi tiết"]. 4. Điền toàn bộ dữ liệu từ tệp JSON đã được làm sạch vào các tab tương ứng. 5. Tạo riêng một tab mang tên "Tổng quan Chỉ số Sức tải" để ghi nhận các chỉ số Diện tích, Dân số, Mật độ và Hệ số phòng/1000 dân.

Các cạm bẫy cần tránh (Pitfalls)

Tránh sử dụng thư viện gspread: Trong môi trường Hermes Agent, thư viện gspread thường không được cài đặt sẵn. Thay vì cố gắng cài đặt gspread bằng pip (dễ gây lỗi môi trường hoặc xung đột gói), hãy sử dụng trực tiếp thư viện chính thức google-api-python-client (thông qua googleapiclient.discovery) vốn đã được cài đặt sẵn trong môi trường và tương thích hoàn toàn với file credential ~/.hermes/google_token.json. Xem mẫu tại templates/sync_to_sheets.py.
Lệch dòng cột của CSDL Quốc gia (Ảo giác cào lỗi): Tránh vội vàng kết luận CSDL của Cục bị lỗi lệch dòng/tráo dòng chéo khi thấy nhiều khách sạn khác nhau trả về cùng một địa chỉ hoặc thông tin (ví dụ: Mercure Hải Phòng). Đây là biểu hiện của việc request thô bị server từ chối và trả về kết quả mặc định. Luôn dùng trình duyệt thực tế (Browser) navigate và kiểm chứng trực quan cấu trúc trang web hiển thị trước khi viết code parse.
Số liệu "ảo" của Cổng thông tin hỗ trợ du khách: Số liệu tổng phòng của vùng thường bị lỗi cộng dồn (ví dụ hiển thị tổng Cam Ranh có 339 phòng là sai lệch kỹ thuật của website). Phải dùng số liệu tổng tự tính toán từ danh sách chi tiết đã hiệu đính.
Sử dụng số liệu dân số/diện tích cũ: Tại thời điểm 2026, bắt buộc dùng Niên giám 2025 (phát hành đầu 2026). Giải trình rõ nguồn gốc số liệu.

📚 Hướng dẫn & Tài liệu hỗ trợ

Hướng dẫn đối soát bằng stays (Google Hotels): Cách dùng MCP stays để quét giá OTA, hạng sao và tiện ích thời gian thực, kèm phương án sửa lỗi RPC details.

Mẫu code tự động hóa (Templates)

Skill này cung cấp mẫu code tích hợp đồng bộ dữ liệu trực tiếp từ JSON/Python dict sang Google Sheets tại templates/sync_to_sheets.py. Hãy sử dụng script này để giảm thiểu việc gõ tay các API calls của Google Sheets.