feat: multiple updates - alerts, auth, sectors, rotation service, financials ingestion, task specs, and agent framework

2026-06-06 22:01:40 -04:00
parent 7cbc5c120d
commit a16050c80a
47 changed files with 2434 additions and 373 deletions
@@ -0,0 +1,43 @@
+# SPEC: Refactor Alert CRUD to Service Layer
+
+## Goal
+Refactor the `src/backend/routers/alerts.py` file to move business logic and data access into a dedicated `src/backend/services/alert_service.py` file. This aligns the alerting module with the existing service-oriented architecture used in the rest of the project (e.g., `SentimentService`, `RotationService`).
+
+## Exact Requirements
+1. **Create `src/backend/services/alert_service.py`**:
+    - Implement an `AlertService` class containing methods for all current alert operations.
+    - Methods required:
+        - `get_user_alerts(watchlist_id, status, page, page_size, user_id)`
+        - `create_alert(body, user_id)`
+        - `get_alert(alert_id, user_id)`
+        - `update_alert(alert_id, body, user_id)`
+        - `resolve_alert(alert_id, user_id)`
+        - `dismiss_alert(alert_id, user_id)`
+2. **Encapsulate Authorization**:
+    - Move the ownership verification logic (`_require_watchlist_owner`) into the service layer or a shared security service.
+3. **Encapsulate Data Access & Transformation**:
+    - Move all `execute_query`, `execute_one`, and `execute_command` calls into the `AlertService`.
+    - Handle the mapping of database rows to `AlertResponse` and `AlertListResponse` models within the service.
+4. **Update `src/backend/routers/alerts.py`**:
+    - Remove direct database calls and business logic.
+    - Inject/instantiate `AlertService` and delegate all requests to it.
+    - Maintain the existing FastAPI route definitions and dependency injection (e.g., `get_current_user`).
+5. **Maintain Feature Parity**:
+    - The API behavior (endpoints, status codes, response models) must remain identical to the current implementation.
+
+## Acceptance Criteria
+1. **Code Structure**: `src/backend/routers/alerts.py` contains only routing and request/response handling.
+2. **Service Implementation**: `src/backend/services/alert_service.py` is the single source of truth for alert business logic.
+3. **Test Pass Rate**: All tests in `src/backend/tests/test_alerts.py` must pass (including the previously failing tests).
+4. **No Regressions**: All CRUD operations (Create, Read, Update, Delete, Resolve, Dismiss) must function exactly as before.
+
+## Constraints & Non-Goals
+- **Non-Goal**: Do not change the database schema.
+- **Non-Goal**: Do not change the external API contract (URLs, JSON structure, status codes).
+- **Constraint**: Maintain existing error handling patterns (e.g., 404 for missing resources, 403/404 for ownership issues).
+
+## Recommended Implementation Approach
+1. **Phase 1: Service Creation**: Implement the `AlertService` in `src/backend/services/alert_service.py` by copying logic from the router, but parameterizing it for the service methods.
+2. **Phase 2: Router Migration**: Replace the body of each router function with a call to the corresponding `AlertService` method.
+3. **Phase 3: Cleanup**: Remove the old `_require_watchlist_owner` helper from the router.
+4. **Phase 4: Verification**: Run the existing test suite.