docs: update doc for reverse geoencoding

Author: Enter-tainer

apps/docs/contents/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Overview
 createdAt: 2025-07-20T22:35:03+08:00
-lastModified: 2025-11-14T21:52:55+08:00
+lastModified: 2025-11-15T01:31:13+08:00
 ---
 
 # Overview
@@ -45,6 +45,7 @@ Live Photo Galleries:
 - 🌈 **Blurhash Placeholders** - Elegant image loading experience
 - 📱 **Live Photo Support** - Detection and display of iPhone Live Photos
 - ☀️ **HDR Image Support** - Display HDR images
+- 🌍 **Reverse Geocoding** - Automatic location extraction from GPS coordinates with support for Mapbox and Nominatim providers
 
 ### Advanced Features
 
@@ -126,6 +127,10 @@ This will automatically pull resources from the remote repository, avoiding rebu
 - `enableLivePhotoDetection`: Enable Live Photo detection
 - `digestSuffixLength`: Digest suffix length for deterministic IDs
 - `supportedFormats`: Optional allowlist of file extensions to process
+- `enableGeocoding`: Enable reverse geocoding from GPS coordinates (default: `false`)
+- `geocodingProvider`: Geocoding service provider (`'mapbox'` | `'nominatim'` | `'auto'`, default: `'auto'`)
+- `mapboxToken`: Mapbox access token (required when using Mapbox provider)
+- `nominatimBaseUrl`: Custom Nominatim base URL (optional, defaults to OpenStreetMap's public instance)
 
 #### System Observability (`system.observability`)
 
@@ -138,6 +143,44 @@ This will automatically pull resources from the remote repository, avoiding rebu
 - `performance.worker.timeout`: Worker timeout (milliseconds)
 - `performance.worker.useClusterMode`: Enable cluster mode
 
+#### Geocoding Configuration Example
+
+To enable reverse geocoding, configure the geocoding provider in your `builder.config.ts`:
+
+**Using Nominatim (Free, but rate-limited):**
+
+```typescript
+{
+  system: {
+    processing: {
+      enableGeocoding: true,
+      // Optional: use custom Nominatim instance
+      // nominatimBaseUrl: 'https://your-nominatim-instance.com'
+    }
+  }
+}
+
+```
+
+**Using Mapbox:**
+
+```typescript
+{
+  system: {
+    processing: {
+      enableGeocoding: true,
+      mapboxToken: process.env.MAPBOX_TOKEN
+    }
+  }
+}
+```
+
+**Notes:**
+- Mapbox maybe provide higher accuracy and better rate limits but requires an API token
+- Nominatim is free but has strict rate limits (1 request/second)
+- Both providers support intelligent caching to minimize API calls
+- Location data includes country, city, and location name extracted from GPS coordinates
+
 ## 📋 CLI Commands
 
 ### Build Commands

packages/builder/README.md

@@ -20,7 +20,8 @@ src/core/
 │   └── exif.ts     # EXIF 数据提取
 ├── photo/          # 照片处理
 │   ├── info-extractor.ts # 照片信息提取
-│   └── processor.ts # 照片处理主逻辑
+│   ├── processor.ts # 照片处理主逻辑
+│   └── geocoding.ts # 反向地理编码
 ├── manifest/       # Manifest 管理
 │   └── manager.ts  # Manifest 读写和管理
 ├── worker/         # 并发处理
@@ -62,6 +63,7 @@ src/core/
 
 - **info-extractor.ts**: 从文件名和 EXIF 提取照片信息
 - **processor.ts**: 照片处理主流程，整合所有处理步骤
+- **geocoding.ts**: 反向地理编码，支持 Mapbox 和 Nominatim 提供者
 
 ### 6. Manifest 管理 (`manifest/`)
 
@@ -136,6 +138,13 @@ const exif = await extractExifData(buffer)
 - 可配置的并发数
 - 环境变量配置
 
+### 6. 地理编码支持
+
+- 从 GPS 坐标提取位置信息
+- 支持 Mapbox 和 Nominatim 两种提供者
+- 智能缓存和速率限制
+- 自动重试和并发安全
+
 ## 扩展指南
 
 ### 添加新的图像处理功能

packages/builder/src/photo/README.md

@@ -12,6 +12,7 @@
 - **`live-photo-handler.ts`** - Live Photo 检测和处理
 - **`logger-adapter.ts`** - Logger 适配器，实现适配器模式
 - **`info-extractor.ts`** - 照片信息提取
+- **`geocoding.ts`** - 反向地理编码，从 GPS 坐标提取位置信息
 
 ### 设计模式
 
@@ -43,17 +44,19 @@ class CompatibleLoggerAdapter implements PhotoLogger {
 3. 处理缩略图和 blurhash
 4. 处理 EXIF 数据
 5. 处理影调分析
-6. 提取照片信息
-7. 处理 Live Photo
-8. 构建照片清单项
+6. 处理地理编码（从 GPS 坐标反向解析位置信息）
+7. 提取照片信息
+8. 处理 Live Photo
+9. 构建照片清单项
 
 ### 主要改进
 
 1. **模块化分离**: 将不同的处理逻辑分离到专门的模块中
 2. **Logger 适配器**: 使用异步执行上下文管理 logger，避免全局状态污染
 3. **缓存管理**: 统一管理各种数据的缓存和复用逻辑
 4. **Live Photo 处理**: 专门的模块处理 Live Photo 检测和匹配
-5. **类型安全**: 完善的 TypeScript 类型定义
+5. **反向地理编码**: 支持从 GPS 坐标提取位置信息，支持多个地理编码提供商
+6. **类型安全**: 完善的 TypeScript 类型定义
 
 ### 使用方法
 
@@ -80,7 +83,8 @@ const result = await processPhoto(
 #### 单独使用各个模块
 
 ```typescript
-import { processLivePhoto, processThumbnailAndBlurhash, processExifData } from './index.js'
+import { processLivePhoto, processThumbnailAndBlurhash, processExifData, processLocationData } from './index.js'
+import { createGeocodingProvider } from './geocoding.js'
 
 // Live Photo 处理
 const livePhotoResult = processLivePhoto(photoKey, livePhotoMap, builder.getStorageManager())
@@ -90,6 +94,9 @@ const thumbnailResult = await processThumbnailAndBlurhash(imageBuffer, photoId,
 
 // EXIF 处理
 const exifData = await processExifData(imageBuffer, rawImageBuffer, photoKey, existingItem, options)
+
+// 地理编码处理
+const locationInfo = await processLocationData(exifData, photoKey, existingItem, options)
 ```
 
 ### 扩展性