30 lines
2 KiB
Markdown
30 lines
2 KiB
Markdown
---
|
|
name: integration-validation
|
|
description: "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-test` path instead of `/webhook`.
|
|
- **Target DB**: The `/webhook-test` endpoint 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:5678` or local reverse-proxied aliases).
|
|
- **Network Check**: If a `502 Bad Gateway` error 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).
|