tech_lead / coder 2roles

specs/007-migration-dashboard-grid/contracts/api.md

@@ -2,48 +2,57 @@
 
 ## Endpoints
 
-### GET /api/migration/dashboards
+### 1. List Dashboards
+**Method**: `GET`
+**Path**: `/api/environments/{env_id}/dashboards`
+**Purpose**: Fetch all dashboards from the specified environment for the grid.
 
-Fetch a list of dashboards from the specified source environment.
+**Request Parameters**:
+- `env_id` (path): The ID of the environment to fetch from.
 
-**Request:**
-- **Headers**:
-  - `x-source-env-id`: `string` (UUID of the source environment configuration)
+**Response**:
+- **200 OK**:
+  ```json
+  [
+    {
+      "id": 123,
+      "title": "Sales Dashboard",
+      "last_modified": "2023-10-27T10:00:00Z",
+      "status": "published"
+    },
+    {
+      "id": 124,
+      "title": "Draft Metrics",
+      "last_modified": "2023-10-26T15:30:00Z",
+      "status": "draft"
+    }
+  ]
+  ```
+- **404 Not Found**: Environment not found.
+- **500 Internal Server Error**: Superset API error.
 
-**Response:**
-- **Status**: `200 OK`
-- **Body**: `List[Dashboard]`
+## Components (Frontend)
 
-```json
-[
-  {
-    "id": 101,
-    "title": "Sales Overview",
-    "changed_on": "2023-10-27T14:30:00Z",
-    "published": true,
-    "url": "/superset/dashboard/sales-overview/"
-  },
-  {
-    "id": 102,
-    "title": "Marketing Draft",
-    "changed_on": "2023-10-26T09:15:00Z",
-    "published": false,
-    "url": "/superset/dashboard/marketing-draft/"
-  }
-]
-```
+### DashboardGrid
+**Props**:
+- `dashboards`: `DashboardMetadata[]` - List of dashboards to display.
+- `selectedIds`: `number[]` - IDs of currently selected dashboards.
 
-**Errors:**
-- `400 Bad Request`: Missing environment ID header.
-- `404 Not Found`: Environment configuration not found.
-- `502 Bad Gateway`: Error communicating with Superset.
+**Events**:
+- `selectionChanged`: Emitted when selection changes. Payload: `number[]` (new list of selected IDs).
 
-## Python Definitions
+**State**:
+- `filterText`: string - Current filter text.
+- `currentPage`: number - Current page index (0-based).
+- `pageSize`: number - Items per page (default 20).
+- `sortColumn`: string - 'title' | 'last_modified' | 'status'.
+- `sortDirection`: 'asc' | 'desc'.
 
-```python
-# [DEF:backend.src.api.routes.migration.get_dashboards:Function]
-# @PURPOSE: Fetch dashboards from the specified source environment.
-# @PRE:     Header 'x-source-env-id' must be a valid environment UUID.
-# @POST:    Returns a list of Dashboard models with id, title, changed_on, and published status.
-# @PARAM:   source_env_id (str) - UUID of the source environment.
-# @RETURN:  List[DashboardModel]
+## Superset Client Extension
+
+### `get_dashboards_summary`
+**Signature**: `def get_dashboards_summary(self) -> List[Dict]`
+**Purpose**: Fetches dashboard metadata optimized for the grid.
+**Implementation Detail**:
+- Calls `GET /api/v1/dashboard/` with query params `q=(columns:!(id,dashboard_title,changed_on_utc,published))`.
+- Maps response fields to `DashboardMetadata` schema.