WELIFE Docs Swagger Admin Web

WP-ROUTE-GOOGLE-GEO-01 — Audit tìm địa chỉ bản đồ + wire Google

Domain: D-ROUTE · Surfaces: API (+ CON dùng sẵn) · Date: 2026-08-14 Status: IMP (code) · OWNER_REQUIRED (paste GOOGLE_MAPS_API_KEY)

1. Verdict

Tìm địa chỉ kiểu số nhà / hẻm / tên đường / tên riêng trên bản đồ WELIFE chưa đủ chuẩn Google Maps vì:

Lớp Trước audit Sau wire
DB hub + catalog ILIKE name/address — POI tốt, yếu số nhà/hẻm Giữ
Mapbox Geocoding Có nếu token (local có token) Fallback #2
Nominatim OSM Yếu VN house-level Fallback #3
Google Places + Geocoding Key trong .env.example nhưng không đọc Ưu tiên #1 khi có key

Local check (không in secret): GOOGLE_MAPS_API_KEY=empty · MAPBOX_ACCESS_TOKEN=set.

2. Surface FE dùng search

Màn API Ghi chú
WelifeMapScreen autocomplete → geocode fly-to Search trên bản đồ
RoutingDirectionsScreen autocomplete Chỉ đường
AddressFormScreen autocomplete + geocode + pin Lưu Nhà/Công ty
RideHomeScreen autocomplete Điểm đến xe

FE không gọi Google trực tiếp (đúng boundary) — chỉ Nest GET /routing/autocomplete · GET /routing/geocode.

3. Gap vs Google Maps (hành vi người dùng)

Query ví dụ Kỳ vọng Maps Trước (DB/Mapbox/OSM)
123 Nguyễn Huệ Số nhà + đường OSM/Mapbox thường lệch / thiếu
Hẻm 123 Cách Mạng Tháng 8 Hẻm cụ thể Nominatim thường fail
Landmark 81 POI DB/Mapbox OK
Bitexco Tên riêng DB/Mapbox OK
đường Lê Lợi Q1 Trục đường Mapbox tạm ổn

Rule mới: query có số hoặc từ khóa hẻm|ngõ|đường|phố|… → luôn gọi external (Google→Mapbox→OSM), không chờ DB đầy.

4. Pipeline sau wire

autocomplete(q, lat?, lng?)
  → hub nearby + hub ILIKE + catalog ILIKE
  → if street-like OR items < 4:
       Google Places Autocomplete + Place Details (nếu GOOGLE_MAPS_API_KEY)
       → Mapbox Geocoding
       → Nominatim

geocode(address, lat?, lng?)
  → hub match
  → Google Geocoding API
  → Mapbox
  → Nominatim
  → Q1 fallback (found:false)

5. OWNER — bật Google

  1. Google Cloud Console → project WELIFE
  2. Enable: Places API · Geocoding API (billing bắt buộc)
  3. Tạo API key (restrict IP server / API list)
  4. Paste vào api/.env (+ VPS):
GOOGLE_MAPS_API_KEY=...
  1. Restart API · smoke:
GET /api/v1/routing/autocomplete?q=123%20Nguyen%20Hue&lat=10.7769&lng=106.7009
→ items có địa chỉ Google (id `gplace:…`)

GET /api/v1/routing/geocode?address=Hẻm%20123%20Cách%20Mạng%20Tháng%208,%20HCM
→ provider=google · found=true

EXPO_PUBLIC_GOOGLE_MAPS_API_KEY (mobile) không dùng cho search server-side — tránh lộ key; map tiles/SDK riêng.

6. Files

Path Change
api/src/modules/routing/routing.service.ts Google autocomplete + geocode · street-like force
api/.env.example Comment Places/Geocoding
docs/OWNER-WIRE-CHECKLIST.md Hàng Google Maps geocode
docs/reports/WP-ROUTE-GOOGLE-GEO-01.md Báo cáo này

7. Không làm (P1)