Skip to content
PLANOVI Docs

Engineering Standards & Testing

This guide defines the engineering conventions, safety protocols, and testing practices expected across the Planovi Microservices codebase.

1. Coding & Security Standards

1. Mandatory Anti-Cache Headers

All public user-facing and API endpoints must emit cache-invalidation headers to prevent stale financial, technical, or slot availability figures:

header("Cache-Control: no-store, no-cache, must-revalidate, max-age=0");
header("Cache-Control: post-check=0, pre-check=0", false);
header("Pragma: no-cache");

2. Strict Input Sanitization

Never construct file paths directly from user input without filtering. Always strip non-alphanumeric characters:

// Good: Whitelisted characters only
$id = preg_replace('/[^a-zA-Z0-9_-]/', '', $_GET['id'] ?? 'default');
$filePath = __DIR__ . "/../data/{$id}.json";

3. Explicit JSON Response Contracts

All API endpoints must return valid JSON with explicit HTTP status codes (200, 201, 400, 401, 404, 500):

header('Content-Type: application/json; charset=utf-8');
if ($validationFailed) {
    http_response_code(400);
    echo json_encode([
        'status' => 'error',
        'error' => 'Descriptive error message'
    ]);
    exit;
}

2. Mock Testing with test_generator.php

The repository includes a dedicated test harness in dealflow/test_generator.php to simulate various client quotation profiles:

To generate mock deals and verify offer rendering:

Terminal window
# Execute test generator via PHP CLI
php dealflow/test_generator.php

This populates dealflow/data/ with test files (e.g., test_pricing_*.json, test_it_*.json, test_normal_*.json) covering:

  • Standard residential solar installation (e.g. 9.8 kWp).
  • Commercial installation with high-voltage battery storage.
  • Edge cases with zero down payment or government subsidies (Mój Prąd).