플러터 맵 SDK 버그 진단 시스템 프롬프트

### 1. Map System Flow (Visual + Layer-Specific) #### A. Flow Diagram ```mermaid graph TD A[User Action: e.g., tap on map / select feature] --> B[UI Layer: GestureDetector / InkWell] B --> C[Controller/State: ViewModel / ChangeNotifier] C --> D[State Update: e.g., selectedFeatureId] D --> E[Layer Manager: find layer by name] E --> F[SDK Interaction: layer.setProperty / layer.setStyle] F --> G[SDK Internal: property cache update] G --> H[SDK Internal: renderer invalidation] H --> I[Rendering: GPU/CPU draw] I --> J[UI Update: setState / rebuild widget] J --> A ``` #### B. Explain Each Stage - **User Action**: The user interacts with the map (e.g., taps a point, toggles a layer). - **UI Layer**: Flutter widget captures the event and forwards it to the controller. No SDK logic here. - **Controller/State**: The ViewModel or ChangeNotifier updates a state variable (e.g., `selectedFeatureId`). This is the source of truth for the UI and logic. - **Layer Manager**: A service that holds references to all created layers. It retrieves the target layer by its unique ID. - **SDK Interaction**: The layer object is passed to the SDK. The SDK applies the property (e.g., `setStyle`, `setVisibility`) to its internal representation. - **SDK Internal**: The SDK updates its property cache and marks the layer as "dirty" for re-rendering. - **Rendering**: The SDK's renderer redraws the affected layer on the next frame. - **UI Update**: Flutter rebuilds the widget tree (e.g., to show a selection highlight) based on the state change. #### C. Critical Timing Points - **Layer Creation**: When `addLayer()` is called, the SDK creates an internal layer object. Properties set before this call are ignored. - **Data Loading**: When `setDataSource()` is called, the SDK fetches data (from network, file, or memory). Properties set before data is loaded may be overwritten by the data source's default style. - **Property Application**: Properties MUST be applied AFTER the layer is created AND after data is loaded, but BEFORE the next render cycle. The SDK typically exposes a `refresh()` or `redraw()` method to force this. --- ### 2. Expected Behavior (Map-Specific) - **Successful Layer Load**: The layer appears on the map with default or configured style. - **Correct Property Application**: After the user action, the layer's style/behavior changes immediately (e.g., highlight selected feature, change fill color). - **Failure Scenarios**: - Invalid input (e.g., null feature ID) → no crash, log warning. - Missing data (e.g., layer not found) → no-op, log error. - SDK failure (e.g., renderer busy) → retry or queue the property change. If any of these are unclear, ask up to 3 questions and STOP. --- ### 3. Current Behavior Based on the provided issue description and code: - The layer is created and data is loaded. - The property is applied, but the visual result does not match the expected behavior. - The issue likely occurs because the property is applied at the wrong time in the SDK lifecycle (e.g., before data is loaded, or after the render cycle has already started). --- ### 4. Mismatch (Critical) - **Expected**: Property change reflects immediately after user action. - **Actual**: Property change is either ignored, delayed, or applied to the wrong layer. - **Failing Step**: The `SDK Interaction` stage (step 4) is likely out of sync with the `Rendering` stage (step 6). The property is set, but the SDK does not re-render because the layer is not marked as dirty, or the property is set on a stale layer reference. --- ### 5. Root Cause (Precise) - **Timing Issue**: The property is applied before the layer's data source is fully loaded. The SDK overwrites the property when data arrives. - **Incorrect Layer Reference**: The layer ID used in the controller does not match the ID used when creating the layer. - **State Not Updating**: The controller updates the state, but the layer manager is not notified (missing listener). - **Async Handling**: The property is applied inside an async callback that fires after the render cycle, so the change is not picked up. Point to the specific function: In the code, look for `setProperty()` or `setStyle()` calls. Check if they are inside a `then()` or `async` block that runs after `setDataSource()`. --- ### 6. Minimal Fix (STRICT) ```dart // BEFORE (buggy) Future<void> applyProperty(String layerId, MapProperty prop) async { final layer = layerManager.getLayer(layerId); await layer.setDataSource(dataSource); // data loads async layer.setProperty(prop); // applied too early } // AFTER (fixed) Future<void> applyProperty(String layerId, MapProperty prop) async { final layer = layerManager.getLayer(layerId); await layer.setDataSource(dataSource); // Wait for data load to complete, then apply property await layer.onDataLoaded(); // SDK-specific callback layer.setProperty(prop); layer.refresh(); // force re-render } ``` --- ### 7. Why Fix Works - The fix ensures the property is applied AFTER the data source is fully loaded, preventing the SDK from overwriting it. - The `refresh()` call forces the SDK to invalidate the layer's render cache, so the property change is drawn on the next frame. - This aligns with the SDK lifecycle: create → load → style → render. --- ### 8. Map-Specific Risks - **Impact on Other Layers**: If the layer ID is wrong, the property could be applied to a different layer. The fix does not change ID resolution, so this risk remains. - **Performance**: Adding `await onDataLoaded()` may introduce a delay if the data source is large. Consider a timeout or fallback. - **Re-render Issues**: Forcing `refresh()` on every property change may cause flicker or performance degradation if called frequently. Batch property changes if possible. --- ### 9. Prevention (Map Architecture) - **Layer Lifecycle Handling**: Create a `LayerController` that wraps SDK calls and enforces a state machine (created → loading → ready → styled). Expose methods like `applyProperty()` that check the current state. - **Property Logic Placement**: - **Config Layer**: Store default styles in a separate config object, not in the SDK layer. - **Renderer**: Let the SDK handle rendering; do not manually call `refresh()` unless necessary. - **Controller**: Keep all property changes in the controller, and use a single `applyChanges()` method that batches updates. - **Async Handling**: Use a `Completer` or `Future` to wait for data load, and always apply properties in a `then()` block after the load completes. --- ### Self-Check - **Did I map the bug to a specific flow step?** Yes, step 4 (SDK Interaction) is the likely failure point. - **Did I identify a timing issue if present?** Yes, property applied before data load completes. - **Is the fix minimal and scoped?** Yes, only adds a wait and a refresh call. - **Did I avoid over-engineering?** Yes, no new classes or abstractions introduced. --- **Note**: If the provided code snippet does not contain `setDataSource` or `onDataLoaded`, please provide the actual SDK method names. Also, if the issue is not timing-related, clarify the exact symptom (e.g., wrong color, no highlight, crash).