2 KiB
2 KiB
| name | description |
|---|---|
| integration-validation | Manages Excel imports validation, zero-trust internal routing, and n8n webhook setups. Use this when importing sales, routing webhooks, configuring API endpoints, or troubleshooting 502/network issues. |
Integration Validation
Governs the validation of external file imports (e.g., Excel/CSV sales sheets) and the secure routing of n8n integration webhooks.
Core Rationale
Ensuring data integrity at the system entry point prevents downstream calculation failures. Proper zero-trust routing isolates staging/test runs from production environments.
Execution Rules
1. Webhook Isolation and Sandbox Branching
- Branching Rule: For all test runs and staging simulations, route webhook payloads strictly through the
/webhook-testpath instead of/webhook. - Target DB: The
/webhook-testendpoint must write only to the test database sandbox. - Why: Prevents test data from contaminating real collaborator settlements and polluting production audit histories.
2. Zero-Trust Routing and Internal Hostnames
- Container Name Routing: Do not route requests via public IP or expose host ports unnecessarily. Connect via internal Docker hostnames behind the Caddy reverse proxy (e.g.
http://n8n:5678or local reverse-proxied aliases). - Network Check: If a
502 Bad Gatewayerror occurs, verify that Caddy and the target service container share the same Docker network.
3. Idempotency & Double-Upload Prevention
- Idempotency Key: Every file upload or API payload must contain or generate a unique transaction/idempotency key.
- Verification: Query the database for the key before running the processing pipeline. If the key already exists, fail gracefully with a duplicate warning (e.g. "Duplicate import detected").
4. Layout Validation
- Ensure imported files have the correct column layout (Collaborator email/ID, Hotel, Amount, Date).
- Report validation errors formatted clearly so they can be rendered in the UI according to the user's active locale (en/es).