# Feature: Tile Cache Management

## Description
Manages persistent disk-based caching of satellite tiles with flight-specific organization. Provides storage, retrieval, and cleanup of cached tiles to minimize redundant API calls and enable offline access to prefetched data.

## Component APIs Implemented
- `cache_tile(flight_id: str, tile_coords: TileCoords, tile_data: np.ndarray) -> bool`
- `get_cached_tile(flight_id: str, tile_coords: TileCoords) -> Optional[np.ndarray]`
- `clear_flight_cache(flight_id: str) -> bool`

## External Tools and Services
- **diskcache**: Persistent cache library for disk storage management
- **opencv-python**: Image serialization (PNG encoding/decoding)
- **numpy**: Image array handling

## Internal Methods
- `_generate_cache_path(flight_id: str, tile_coords: TileCoords) -> Path`: Generates cache file path following pattern `/satellite_cache/{flight_id}/{zoom}/{tile_x}_{tile_y}.png`
- `_ensure_cache_directory(flight_id: str, zoom: int) -> bool`: Creates cache directory structure if not exists
- `_serialize_tile(tile_data: np.ndarray) -> bytes`: Encodes tile array to PNG bytes
- `_deserialize_tile(data: bytes) -> Optional[np.ndarray]`: Decodes PNG bytes to tile array
- `_update_cache_index(flight_id: str, tile_coords: TileCoords, action: str) -> None`: Updates cache index for tracking
- `_check_global_cache(tile_coords: TileCoords) -> Optional[np.ndarray]`: Fallback lookup in shared cache

## Unit Tests
1. **cache_tile_success**: Cache new tile → file created at correct path
2. **cache_tile_overwrite**: Cache existing tile → file updated
3. **cache_tile_disk_error**: Simulate disk full → returns False
4. **get_cached_tile_hit**: Tile exists → returns np.ndarray
5. **get_cached_tile_miss**: Tile not exists → returns None
6. **get_cached_tile_corrupted**: Invalid file → returns None, logs warning
7. **get_cached_tile_global_fallback**: Not in flight cache, found in global → returns tile
8. **clear_flight_cache_success**: Flight with tiles → all files removed
9. **clear_flight_cache_nonexistent**: No such flight → returns True (no-op)
10. **cache_path_generation**: Various tile coords → correct paths generated

## Integration Tests
1. **cache_round_trip**: cache_tile() then get_cached_tile() → returns identical data
2. **multi_flight_isolation**: Cache tiles for flight A and B → each retrieves only own tiles
3. **clear_does_not_affect_others**: Clear flight A → flight B cache intact
4. **large_cache_handling**: Cache 1000 tiles → all retrievable

