feat: Add POST /api/v1/analysis/:offerId/enhanced — Paid Expert Analysis ("The Closer")

[Tambeej]

Overview

Implements "The Closer" — the paid expert analysis monetisation feature. Authenticated, paying users can now request a full AI-powered enhanced mortgage analysis report for any of their uploaded bank offers.

---

Completed Tasks

1. POST /api/v1/analysis/:offerId/enhanced endpoint

• Registered in src/routes/analysis.js under the existing /api/v1/analysis router prefix.
• Full middleware chain: protect → paidAccess → paidEndpointLimiter → validateOfferId → generateEnhancedReport.

2. paidAccess middleware (src/middleware/paidAccess.js)

• Guards the endpoint by checking req.user.paidAnalyses === true.
• Returns 403 Forbidden with a descriptive message if the user has not paid.
• Must be placed after the protect middleware (which attaches req.user).

3. Fetch user's latest portfolio

• Controller calls portfolioService.getUserPortfolio(userId) to retrieve the user's current portfolio model.
• A null portfolio is handled gracefully — the report generation falls back to rule-based logic.

4. reportService.generateEnhancedReport(offerId, userId, offer, portfolio)

• Builds a rate/payment comparison between the bank offer and the user's portfolio model (annuity formula).
• Calls GPT-4o-mini via aiService.callGPT with a structured system + user prompt.
• AI output is fully sanitised before use (field types, length limits, enum validation).
• Falls back to a rule-based report if OpenAI is unavailable or returns invalid data.
• Persists the result to offer.analysis.enhanced in Firestore via offerService.updateEnhancedAnalysis.

5. Store enhanced report in offer.analysis.enhanced

• reportService calls updateEnhancedAnalysis(offerId, enhancedReport) to persist the report.
• Storage errors are caught and logged without blocking the HTTP response.

6. Return full enhanced report data

• 201 Created for newly generated reports.
• 200 OK for cached reports (idempotent — avoids duplicate AI calls).
• Response shape:

{
  "success": true,
  "message": "Enhanced report generated successfully",
  "data": {
    "tricks": [ { "nameHe", "nameEn", "descriptionHe", "descriptionEn", "applicability", "riskLevel", "potentialSavings" } ],
    "negotiationScript": "...",
    "insights": [ { "titleHe", "titleEn", "bodyHe", "bodyEn", "icon" } ],
    "comparison": { "rateDelta", "monthlySaving", "totalSaving", "loanAmount", "termYears", "bankRate", "portfolioRate", "trackComparison" },
    "generatedAt": "ISO 8601",
    "generatedBy": "ai | rule-based-fallback",
    "processingTimeMs": 1234
  }
}

---

Advanced Consultant Logic

Feature	Implementation
Mortgage Tricks	3–5 strategies always including the Enticement Track (מסלול פיתיון) — take a high-interest track to lower others, then refinance
Negotiation Script	Word-for-word Hebrew script with actual loan numbers, bank name, and market rate comparison
Strategic Insights	3–5 insights explaining the why behind each recommendation (e.g., matching tracks to expected future funds)

---

Security & Reliability

• Authentication: protect middleware validates Firebase ID token.
• Authorisation: paidAccess middleware enforces subscription gate.
• Rate limiting: paidEndpointLimiter (5 req/min per user) prevents abuse.
• Input validation: validateOfferId validates the :offerId path parameter.
• Ownership check: Controller verifies the offer belongs to the requesting user (404 vs 403 distinction).
• AI fallback: Rule-based report generated if OpenAI is unavailable.
• Idempotency: Cached report returned if already generated (no duplicate AI calls).
• PII protection: AI prompts contain only financial data; [שם] placeholder used for borrower name.

---

Files Changed

File	Change
src/routes/analysis.js	Added POST /:offerId/enhanced route with full middleware chain
src/controllers/analysisController.js	New generateEnhancedReport controller + buildResponseData helper
src/services/reportService.js	Full AI + fallback report generation, comparison builder, sanitisers
src/middleware/paidAccess.js	Subscription gate middleware
__tests__/analysisEnhanced.test.js	Integration tests for the new endpoint
__tests__/reportService.test.js	Unit tests for report service
__tests__/paidAccess.test.js	Unit tests for paidAccess middleware