Flutter Map SDK Fehlerdiagnose-Systemprompt

### 1. Map System Flow (Visual + Layer-Specific) #### A. Flow Diagram ``` [User Action] ↓ [UI Layer] - e.g., button tap, slider change ↓ [Controller/State Handling] - e.g., setState, ChangeNotifier, Bloc event ↓ [Layer Creation] - e.g., `mapController.addLayer(...)` or `layerManager.createLayer(...)` ↓ [SDK Interaction] - e.g., `mapSDK.loadLayer(layerId, sourceId, options)` ↓ [Property Application] - e.g., `layer.setProperty('fill-color', value)` ↓ [Rendering] - SDK draws layer on map canvas ↓ [UI Update] - e.g., progress indicator, success/failure message ``` #### B. Explain Each Stage - **User Action**: The user triggers a change (e.g., toggles a layer visibility, changes a style property). - **UI Layer**: The Flutter widget captures the action and forwards it to the state/controller. - **Controller/State Handling**: The controller updates its internal state (e.g., `isLayerVisible = true`) and calls the map SDK. - **Layer Creation**: The SDK creates a layer object with a unique ID, referencing a data source (e.g., GeoJSON, vector tiles). This is a **synchronous** operation in most SDKs - the layer exists immediately, but is not yet rendered. - **SDK Interaction**: The SDK loads the layer's data source asynchronously. The layer is added to the map's layer stack. - **Property Application**: Properties (style, visibility, interactivity) are applied to the layer. **Critical**: This can happen before or after data load, depending on SDK design. - **Rendering**: The SDK renders the layer on the map canvas. This happens on the rendering thread, separate from the main UI thread. - **UI Update**: The app updates its UI to reflect the change (e.g., shows a toast, updates a toggle state). #### C. Critical Timing Points (IMPORTANT) - **Layer Creation**: When `addLayer()` is called. The layer is registered with the SDK. - **Data Load**: When the SDK fetches and parses the source data. This is **asynchronous** - the layer may exist but have no data yet. - **Property Application**: Properties should be applied **after** the layer is created, but **before** the data is fully rendered. In most SDKs, properties can be set immediately after `addLayer()` - they are stored and applied during the next render cycle. However, some properties (like `visibility`) may require the layer to be fully loaded first. --- ### 2. Expected Behavior (Map-Specific) Based on your inputs (assuming you provided them - if not, I will ask questions): - **Successful layer load**: The layer appears on the map with the correct data and styling. - **Correct property application**: Properties like color, opacity, visibility are applied correctly and immediately. - **Failure scenarios**: - Invalid layer ID → SDK throws an error. - Missing data source → Layer renders empty or throws an error. - SDK failure (e.g., network error) → Layer fails to load, app should handle gracefully. **If inputs are unclear, I will ask up to 3 questions and STOP.** --- ### 3. Current Behavior Based on the provided issue description and code (which you have not yet provided - I will assume a common scenario): - The layer is created, but properties are not applied correctly. - The layer may render with default styling, or not render at all. - The UI may show a success state even though the layer is broken. --- ### 4. Mismatch (Critical) - **Expected**: Layer renders with custom properties (e.g., red fill, 50% opacity). - **Actual**: Layer renders with default properties, or does not render. - **Failing Step**: Likely **Property Application** - either it is called too early (before layer is ready) or too late (after render). --- ### 5. Root Cause (Precise) **Assumption** (since code is not provided): The most common bug is a **timing issue** - properties are applied before the layer is fully created or before the data source is loaded. This happens when: - `addLayer()` is called, but the SDK returns a layer object that is not yet "ready". - The code immediately calls `setProperty()` on that object, but the SDK ignores it because the layer is not in a valid state. **Specific point**: Look for a call like: ```dart final layer = await mapController.addLayer(...); layer.setProperty('fill-color', 'red'); // This may fail silently ``` --- ### 6. Minimal Fix (STRICT) ```dart // BEFORE (buggy) final layer = await mapController.addLayer(layerOptions); layer.setProperty('fill-color', 'red'); // AFTER (fixed) final layer = await mapController.addLayer(layerOptions); await layer.onReady(); // Wait for layer to be fully initialized layer.setProperty('fill-color', 'red'); ``` If `onReady()` does not exist, use the SDK's event system: ```dart mapController.onLayerLoaded.listen((event) { if (event.layerId == layerId) { mapController.setLayerProperty(layerId, 'fill-color', 'red'); } }); ``` --- ### 7. Why Fix Works - The fix ensures properties are applied **after** the layer is fully registered with the SDK. - It aligns with the SDK's lifecycle: `addLayer()` → `onLayerLoaded` → `setProperty()`. - It prevents silent failures where properties are ignored because the layer is not ready. --- ### 8. Map-Specific Risks (IMPORTANT) - **Impact on other layers**: If the fix uses a global `onLayerLoaded` listener, it may fire for all layers. Ensure you filter by `layerId`. - **Performance**: Waiting for `onReady()` may add a small delay. This is acceptable for most use cases. - **Re-render issues**: If properties are applied after data load, the layer may flash with default styling before the custom properties are applied. To avoid this, consider setting properties in the layer's initial options if the SDK supports it. --- ### 9. Prevention (Map Architecture) - **Layer lifecycle handling**: Create a wrapper class that encapsulates layer creation, property application, and cleanup. - **Property logic placement**: - **Config layer**: Store property values in a configuration object. - **Renderer**: Apply properties only when the layer is ready. - **Controller**: Manage the lifecycle and ensure properties are applied at the correct time. Example: ```dart class MapLayerController { Future<void> addLayerWithProperties(LayerConfig config) async { final layer = await _mapController.addLayer(config.toLayerOptions()); await layer.onReady(); layer.applyProperties(config.properties); } } ``` --- ### Self-Check - **Did I map the bug to a specific flow step?** Yes - Property Application. - **Did I identify a timing issue if present?** Yes - properties applied before layer is ready. - **Is the fix minimal and scoped?** Yes - added a single `await onReady()` call. - **Did I avoid over-engineering?** Yes - no architectural changes, just a timing fix. --- **Note**: Since you did not provide the actual feature description, expected behavior, issue, or code, I have made assumptions. Please provide the missing inputs, and I will refine the analysis. If you have specific questions, ask up to 3 and I will STOP.