Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,64 @@
+# 22 — Integration & API Layer
+
+**Status**: Not Started
+**Depends On**: 19 — Finance & Accounting, 13 — Fleet Management
+
+---
+
+## Goal
+
+Covers [mainPlan.md §16](./mainPlan.md#16-integration--api-layer) in full
+— outbound/inbound integration with third-party systems.
+
+---
+
+## Background / Context
+
+No external system integration exists today. Each function here depends on a specific named
+third-party provider (accounting platform, telematics provider, B2B portal) that hasn't been
+chosen yet — this step cannot be scoped precisely until that choice is made per Open Questions.
+
+---
+
+## Data Model Changes
+
+### Integration Sync Log
+
+`TargetSystem`, `EntityType`, `EntityId`, `Status` (`Success`, `Failed`, `Retrying`), `AttemptedAt`,
+`ErrorDetail` (nullable).
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `syncToAccountingSystem(transactionId, targetSystem)` | Internal/background job — triggered on GL posting ([19_finance_accounting.md](./19_finance_accounting.md)) |
+| `syncTelematicsData(vehicleId, provider)` | Internal/background job — feeds `recordVehicleTelemetry` ([13_fleet_management.md](./13_fleet_management.md)) |
+| `pushOrderToDistributorPortal(orderId)` | Internal/background job — triggered on order status change ([05_delivery_ride.md](./05_delivery_ride.md)) |
+| — | `GET /api/integrations/sync-log?targetSystem=...` — for support/debugging |
+
+---
+
+## Business Rules
+
+- Every outbound sync must be retryable and idempotent — a failed sync logs to `Integration Sync
+  Log` and retries rather than silently dropping.
+- No integration should be able to block the originating business transaction (order creation, GL
+  posting) — sync happens after commit, asynchronously.
+
+---
+
+## Open Questions
+
+- Which accounting platform (QuickBooks/SAP/Xero — reference doc names all three as examples), and
+  which telematics provider — is either actually contracted yet, or is this step purely
+  speculative until a vendor is chosen?
+- Does a "distributor-facing B2B portal" already exist to push orders to, or is this describing a
+  future/external system not yet built?
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.