05-Specifications / 05.05.Additional-Analytics.spec

05.05.Additional Analytics.spec

05.05. Additional Analytics.spec

This document defines the requirements and implementation details for adding selective data tracing and enhancing the "no-save" privacy policy through ephemeral PDF lifecycle management.

---

1. Feature: Selective Data Tracing ("Trace On")

1.1 Objective

To allow developers to enable high-fidelity logging and raw API response capture for specific sessions using a secure TRACE_SECRET, without affecting the privacy or performance of standard users.

1.2 Data Capture Specification

When tracing is active, the system MUST: - Log all incoming and outgoing Tesla Fleet API payloads. - Include full DEBUG level structured logs in the output. - Store raw JSON traces in GCS under gs://{REPORTS_BUCKET}/traces/{session_id}/.

1.3 Implementation Details

• Header: X-Trace-Secret (matched against settings.TRACE_SECRET).
• URL Param: ?trace_secret=... (propagated by the frontend).
• Context: app.core.logging_config._trace_on (ContextVar).
• Storage: app.core.gcs.upload_trace_to_gcs(data: dict, session_id: str).

---

2. Feature: Ephemeral PDF Lifecycle Management

2.1 Objective

To strictly enforce the promise that user data is deleted immediately after the service is rendered.

2.2 Active Deletion Requirements

• Cleanup Endpoint: DELETE /tesla/reports/cleanup (or DELETE /tesla/reports/{report_id}).
• Frontend Trigger: The WUI MUST call the cleanup endpoint immediately after the user initiates the PDF download.
• Verification: The backend MUST verify the session_id ownership of the report before deletion.

2.3 Passive Deletion (TTL) Requirements

• Redis Task TTL: Reduce TASK_STATUS_TTL_SECONDS to 3600 (1 hour).
• GCS Lifecycle Rule: Implement a 1-day auto-delete policy for the reports bucket in Terraform (Step 016).

---

3. Implementation Checklist (Backend)

1. [x] Models: Add trace_on: bool = False to OrderSession dataclass.
2. [x] Config: Add TRACE_SECRET to Settings in config.py.
3. [x] GCS Utility: Implement delete_report_from_gcs and upload_trace_to_gcs.
4. [x] Tesla Service: Add hooks in fleet_api_get_with_token to call upload_trace_to_gcs if trace_on is enabled.
5. [x] Router: Add DELETE /tesla/reports/cleanup to tesla.py.
6. [x] Middleware: Update request_context_middleware to detect the trace secret and set context.

---

4. Implementation Checklist (Frontend)

1. [x] Store: Capture trace_secret from URL and store in sessionStorage.
2. [x] API Service: Automatically attach X-Trace-Secret to all headers.
3. [x] Component: Trigger api.cleanupReport(sessionId) in ReportDashboard.vue after download.

---

5. Security Note

• The TRACE_SECRET MUST NOT be logged or exposed in client-side logs.
• Traces MUST NOT be stored in publicly accessible buckets.