pre-geocode-companies

name	pre-geocode-companies
description	Pre-fill location_lat/location_lng vào company_profiles từ address text qua Nominatim batch script. Use sau khi bulk-import addresses để map render instant không cần runtime geocode. Resume-safe + idempotent.

Skill: pre-geocode-companies

Operational helper cho batch geocoder. Reference: [[docs/Architecture/Geocoding.md]] · [[docs/Architecture/Map Performance.md]] · [[docs/Workflows/Bulk Import Companies.md]].

Đọc trước

• [[docs/Architecture/Geocoding.md]] — providers + caching strategy
• [[docs/Architecture/Map Performance.md]] — tại sao cần pre-geocode (avoid runtime API calls)
• scripts/geocode-imported.mjs — script chính

Khi nào dùng

• Sau khi user chạy [[bulk-import-companies]] — addresses có text nhưng location_lat/lng null
• User báo "map không hiện markers mới" sau khi import
• User muốn refresh geocode cho 1 subset (vd companies vừa update address)
• Stark báo ETA dài (script ~26h cho 84k rows) → cần monitor

Pre-checks

1. Có rows cần geocode?

select
  count(*) filter (where location_lat is not null and location_lng is not null) as with_coords,
  count(*) filter (where (location_lat is null or location_lng is null)
                    and (address is not null or location is not null)) as needs_geocode,
  count(*) as total
from company_profiles;

Nếu needs_geocode = 0 → không cần chạy.

2. .env.local có service role?

Cùng yêu cầu như import.

3. Internet OK + Nominatim phản hồi?

curl -s 'https://nominatim.openstreetmap.org/search?format=json&q=Hanoi&limit=1' | head -c 200

Phải return JSON có lat/lng. Nếu fail → kiểm tra firewall/VPN.

Cách chạy

Test 50 rows

npm run geocode:imported -- --limit 50

Kỳ vọng output:

🌍 Geocode imported companies
   start=0 limit=50 dry=false
📋 Loaded cache: 0 entries
  [50] ok=44 fail=4 cached=2 dbSkip=0 (0.91/s, ETA 0.0h)

📊 Done in 55s: processed=50 ok=44 fail=4 cached=2 dbSkip=0

ETA ~55 giây.

Run full

npm run geocode:imported

ETA ~26h cho 84k rows. Để chạy nền qua đêm/cuối tuần. Ctrl+C anytime → re-run pick up rows kế tiếp.

Resume từ offset cụ thể

npm run geocode:imported -- --start 5000

Bắt đầu từ row index 5000 thay vì 0. Hữu ích nếu biết rows đầu đã geocoded mà cache local missing (vd chạy trên máy khác).

Dry run

npm run geocode:imported -- --dry-run

Đếm rows pending mà không gọi API hoặc update DB.

Monitor tiến độ

Trong khi script chạy, mở SQL Editor query định kỳ:

select
  count(*) filter (where location_lat is not null) as done,
  count(*) filter (where location_lat is null and (address is not null or location is not null)) as pending
from company_profiles;

done tăng dần ~0.9-1 row/sec. pending giảm tương ứng.

Hoặc đọc cache local:

# PowerShell — tail progress
Get-Content .\.cache\geocode-progress.json | Measure-Object -Property Length

Cache size tăng dần.

Trả thêm tốc độ

Public Nominatim hard limit 1 req/s. Để giảm THROTTLE_MS dưới 1000ms cần:

Option	Setup	Tốc độ
Self-hosted Nominatim	Docker + OSM dump VN ~5GB	100+ req/s
Mapbox Geocoding	API key, 100k/tháng free	10 req/s
HERE Geocoding	API key, 250k/tháng free	10 req/s
Google Places	API key, paid	50 req/s

Khi đổi provider → edit geocodeOnce() function trong scripts/geocode-imported.mjs. API contract đơn giản: (address) => Promise<{lat, lng} | null>.

Common errors & fix

429 — rate-limited

Script dừng khi gặp 429. Đợi 30 phút (Nominatim window) rồi re-run. Re-run sẽ pick up từ rows NULL kế tiếp (chưa update lat/lng vào DB).

Hoặc giảm tốc bằng cách edit THROTTLE_MS lên 2000ms.

Cache file corrupt

rm .cache/geocode-progress.json
npm run geocode:imported

Cache rebuild từ đầu — chỉ mất tốc độ dedup duplicate addresses, không ảnh hưởng correctness.

Fail rate cao (> 40%)

Address text vague hoặc encoding lỗi:

• "TP. Hồ Chí Minh" → quá rộng, Nominatim trả null
• "144 Cô Giang" → mojibake, Nominatim không hiểu

Inspect rows fail:

select id, address, location from company_profiles
where (location_lat is null or location_lng is null)
  and (address is not null or location is not null)
order by random()
limit 20;

Nếu nhiều mojibake → fix encoding source data trước. Nếu nhiều "TP. xxx" thuần → chấp nhận map thiếu markers, hoặc geocode thủ công ra city center.

Output checklist

Sau khi xong:

• DB count(*) where location_lat is not null tăng từ ban đầu lên ~70-90% rows có address
• Map page (refresh) hiển thị nhiều markers hơn — markercluster cluster mượt
• DevTools Network tab — không còn API calls đến nominatim.openstreetmap.org khi user load Network page (đã pre-fill DB)
• Cache .cache/geocode-progress.json tồn tại + size proportional với unique addresses processed

Liên quan

• [[bulk-import-companies]] — chạy trước skill này (tạo addresses text)
• [[docs/Architecture/Geocoding.md]] — provider details
• [[docs/Architecture/Map Performance.md]] — tại sao MAX_COMPANIES + clustering quan trọng