component decomposition is done

2026-04-23 03:26:38 +00:00 · 2025-11-24 14:09:23 +02:00
parent acec83018b
commit f50006d100
34 changed files with 8637 additions and 0 deletions
@@ -0,0 +1,358 @@
+# Flight Manager
+
+## Interface Definition
+
+**Interface Name**: `IFlightManager`
+
+### Interface Methods
+
+```python
+class IFlightManager(ABC):
+    @abstractmethod
+    def create_flight(self, flight_data: FlightData) -> str:
+        pass
+    
+    @abstractmethod
+    def get_flight_state(self, flight_id: str) -> Optional[FlightState]:
+        pass
+    
+    @abstractmethod
+    def link_to_route(self, flight_id: str, route_id: str) -> bool:
+        pass
+    
+    @abstractmethod
+    def update_flight_status(self, flight_id: str, status: FlightStatus) -> bool:
+        pass
+    
+    @abstractmethod
+    def initialize_system(self) -> bool:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- Manage flight lifecycle (creation, state tracking, completion)
+- Link flights to Route API routes
+- Initialize system components (models, configurations, satellite database)
+- Coordinate satellite data prefetching
+- Track flight processing status and statistics
+- Manage flight metadata persistence
+
+### Scope
+- Central coordinator for flight processing sessions
+- System initialization and resource management
+- Flight state machine management
+- Integration point between REST API and processing components
+
+## API Methods
+
+### `create_flight(flight_data: FlightData) -> str`
+
+**Description**: Creates a new flight processing session, initializes state, and triggers satellite prefetching.
+
+**Called By**:
+- G01 GPS-Denied REST API
+
+**Input**:
+```python
+FlightData:
+    route_id: str
+    start_gps: GPSPoint
+    camera_params: CameraParameters
+    rough_waypoints: List[GPSPoint]
+    altitude: float
+```
+
+**Output**:
+```python
+flight_id: str  # UUID
+```
+
+**Processing Flow**:
+1. Generate flight_id (UUID)
+2. Get flight configuration from G16 Configuration Manager
+3. Get route info from G03 Route API Client
+4. Initialize flight state
+5. Trigger G04 Satellite Data Manager → prefetch_route_corridor()
+6. Save flight state to G17 Database Layer
+7. Return flight_id
+
+**Error Conditions**:
+- `RouteNotFoundError`: route_id doesn't exist
+- `ConfigurationError`: Invalid camera parameters
+- `DatabaseError`: Failed to persist state
+
+**Test Cases**:
+1. **Valid flight creation**: Returns flight_id, state persisted
+2. **Invalid route_id**: Raises RouteNotFoundError
+3. **Prefetch triggered**: Satellite manager receives prefetch request
+4. **Concurrent creation**: 10 flights created simultaneously → all succeed
+
+---
+
+### `get_flight_state(flight_id: str) -> Optional[FlightState]`
+
+**Description**: Retrieves current flight state including processing statistics.
+
+**Called By**:
+- G01 GPS-Denied REST API (for status endpoint)
+- G05 Image Input Pipeline (to check flight exists)
+- G11 Failure Recovery Coordinator (for state updates)
+
+**Input**:
+```python
+flight_id: str
+```
+
+**Output**:
+```python
+FlightState:
+    flight_id: str
+    route_id: str
+    status: str  # "prefetching", "ready", "processing", "blocked", "completed", "failed"
+    frames_processed: int
+    frames_total: int
+    current_frame: Optional[int]
+    current_heading: Optional[float]
+    blocked: bool
+    search_grid_size: Optional[int]
+    created_at: datetime
+    updated_at: datetime
+    cache_reference: str  # Satellite data cache identifier
+```
+
+**Error Conditions**:
+- Returns `None`: Flight not found (not an error condition)
+
+**Test Cases**:
+1. **Get existing flight**: Returns complete FlightState
+2. **Get non-existent flight**: Returns None
+3. **Get during processing**: Returns accurate frame count
+
+---
+
+### `link_to_route(flight_id: str, route_id: str) -> bool`
+
+**Description**: Links a flight to its Route API route for waypoint updates.
+
+**Called By**:
+- Internal (during create_flight)
+
+**Input**:
+```python
+flight_id: str
+route_id: str
+```
+
+**Output**:
+```python
+bool: True if linked, False if flight doesn't exist
+```
+
+**Processing Flow**:
+1. Verify flight exists
+2. Verify route exists via G03 Route API Client
+3. Store linkage in flight state
+4. Update database
+
+**Error Conditions**:
+- `RouteNotFoundError`: route_id invalid
+
+**Test Cases**:
+1. **Valid linkage**: Returns True
+2. **Invalid flight_id**: Returns False
+3. **Invalid route_id**: Raises RouteNotFoundError
+
+---
+
+### `update_flight_status(flight_id: str, status: FlightStatus) -> bool`
+
+**Description**: Updates flight processing status (processing, blocked, completed, etc.).
+
+**Called By**:
+- G05 Image Input Pipeline (status transitions)
+- G11 Failure Recovery Coordinator (blocked/resumed)
+- G13 Result Manager (completed)
+
+**Input**:
+```python
+flight_id: str
+status: FlightStatus:
+    status_type: str  # "processing", "blocked", "completed", "failed"
+    frames_processed: Optional[int]
+    current_frame: Optional[int]
+    current_heading: Optional[float]
+    blocked: Optional[bool]
+    search_grid_size: Optional[int]
+    message: Optional[str]
+```
+
+**Output**:
+```python
+bool: True if updated, False if flight not found
+```
+
+**Processing Flow**:
+1. Load current flight state
+2. Update relevant fields
+3. Update updated_at timestamp
+4. Persist to G17 Database Layer
+5. Return success
+
+**Error Conditions**:
+- Returns False if flight not found
+
+**Test Cases**:
+1. **Update to processing**: status="processing" → updates successfully
+2. **Update to blocked**: blocked=True, search_grid_size=9 → updates
+3. **Resume from blocked**: blocked=False → processing continues
+4. **Concurrent updates**: Multiple simultaneous updates → all persist correctly
+
+---
+
+### `initialize_system() -> bool`
+
+**Description**: Initializes system components on startup (models, configurations, satellite database).
+
+**Called By**:
+- System startup (main application)
+
+**Input**:
+- None
+
+**Output**:
+```python
+bool: True if initialization successful
+```
+
+**Processing Flow**:
+1. Load system configuration from G16 Configuration Manager
+2. Initialize ML models via G15 Model Manager:
+   - Load SuperPoint model
+   - Load LightGlue model
+   - Load DINOv2 model
+   - Load LiteSAM model
+3. Initialize G08 Global Place Recognition → build satellite descriptor database
+4. Initialize G04 Satellite Data Manager cache
+5. Verify all components ready
+
+**Error Conditions**:
+- `InitializationError`: Component initialization failed
+- `ModelLoadError`: ML model loading failed
+
+**Test Cases**:
+1. **Clean startup**: All models load successfully
+2. **Missing model file**: Raises ModelLoadError
+3. **Configuration error**: Raises InitializationError
+4. **Partial initialization failure**: Cleanup and raise error
+
+## Integration Tests
+
+### Test 1: Flight Lifecycle
+1. initialize_system()
+2. create_flight() with valid data
+3. get_flight_state() → verify "prefetching"
+4. Wait for prefetch completion
+5. update_flight_status("processing")
+6. get_flight_state() → verify "processing"
+7. update_flight_status("completed")
+
+### Test 2: Multiple Concurrent Flights
+1. create_flight() × 10 concurrently
+2. update_flight_status() for all flights in parallel
+3. get_flight_state() for all flights
+4. Verify no state cross-contamination
+
+### Test 3: System Initialization
+1. initialize_system()
+2. Verify all 4 models loaded
+3. Verify satellite database ready
+4. Create flight immediately after init → succeeds
+
+## Non-Functional Requirements
+
+### Performance
+- **create_flight**: < 300ms (excluding prefetch which is async)
+- **get_flight_state**: < 50ms
+- **update_flight_status**: < 30ms
+- **initialize_system**: < 30 seconds (one-time startup cost)
+
+### Scalability
+- Support 1000+ concurrent flight sessions
+- Handle 100 status updates per second
+- Maintain state for up to 10,000 flights (historical data)
+
+### Reliability
+- Graceful handling of component initialization failures
+- Flight state persistence survives process restarts
+- Transaction safety for concurrent updates
+- Automatic cleanup of completed flights after 7 days
+
+## Dependencies
+
+### Internal Components
+- **G03 Route API Client**: For route validation and metadata
+- **G04 Satellite Data Manager**: For prefetch operations
+- **G08 Global Place Recognition**: For descriptor database initialization
+- **G15 Model Manager**: For ML model loading
+- **G16 Configuration Manager**: For system configuration
+- **G17 GPS-Denied Database Layer**: For state persistence
+
+### External Dependencies
+- None (coordinates with internal components)
+
+## Data Models
+
+### FlightData
+```python
+class FlightData(BaseModel):
+    route_id: str
+    start_gps: GPSPoint
+    camera_params: CameraParameters
+    rough_waypoints: List[GPSPoint]
+    altitude: float
+```
+
+### FlightState
+```python
+class FlightState(BaseModel):
+    flight_id: str
+    route_id: str
+    status: str
+    frames_processed: int = 0
+    frames_total: int = 0
+    current_frame: Optional[int] = None
+    current_heading: Optional[float] = None
+    blocked: bool = False
+    search_grid_size: Optional[int] = None
+    created_at: datetime
+    updated_at: datetime
+    cache_reference: str
+    camera_params: CameraParameters
+    altitude: float
+    start_gps: GPSPoint
+```
+
+### FlightStatus (Update DTO)
+```python
+class FlightStatus(BaseModel):
+    status_type: str
+    frames_processed: Optional[int] = None
+    current_frame: Optional[int] = None
+    current_heading: Optional[float] = None
+    blocked: Optional[bool] = None
+    search_grid_size: Optional[int] = None
+    message: Optional[str] = None
+```
+
+### SystemState
+```python
+class SystemState(BaseModel):
+    initialized: bool
+    models_loaded: Dict[str, bool]  # {"SuperPoint": True, "LightGlue": True, ...}
+    satellite_db_ready: bool
+    active_flights_count: int
+    initialization_timestamp: datetime
+```
+