Smart Quote System
The Smart Quote System is a full-stack logistics quoting application for KS Ways (BridgeLogis by KS Ways). It calculates international shipping costs across multiple carriers (UPS, DHL, FedEx), including export packing, surcharges, and margin analysis. React frontend with a Rails API backend and mirrored calculation logic.
Live URL: https://bridgelogis.com / https://smart-quote-main.vercel.app
Key Features
Multi-Carrier Quoting (UPS, DHL, FedEx)
- Zone-based pricing: Config-driven country-to-zone mapping (Z1-Z10 for UPS, Z1-Z8 for DHL, letter zones A-Y for FedEx) with exact rate tables (0.5-20kg in 0.5kg steps) and range rates (>20kg per-kg)
- No fallback zone: a destination absent from a carrier's official zone table is never priced off a guessed zone — the UI shows a "zone unavailable" notice (result panel, comparison card, country dropdown) and the API rejects the quote with
422 ZONE_NOT_FOUND
- Shared rate lookup: Common
lookupCarrierRate() engine for all carriers (exact table -> range table -> fallback), carrier/document-aware table selection via rateTableResolver
- FedEx Document rates: Envelope (rated ≤0.5kg) / Pak (≤2.5kg) tables for Document shipments, International Priority (IP) fallback with warning above the cap
- UPS Surge Fee: Auto-detected for Middle East (KRW 2,004/kg) and Israel (KRW 4,722/kg) destinations, FSC applicable
- EAS/RAS Auto-Detection: Postal code-based Extended/Remote Area Surcharge lookup (86 countries, 39,876 zip ranges, binary search O(log n), lazy-loaded)
- Surcharges: FSC% fuel surcharge, DB-driven surcharges, manual surge fees, carrier-specific add-ons (UPS: 6, DHL: 19, FedEx: 18 — all mirrored on the backend)
- Carrier comparison: 3-way side-by-side cost comparison with Fastest/Cheapest/Eco badges; carriers without a zone for the destination show a "No zone — quote unavailable" column
- Incoterm Policy: Express shipments (UPS/DHL/FedEx) use DAP exclusively
Calculation Pipeline
- Item Costs - Packing dimensions via
applyPackingDimensions() utility (+10/+10/+15cm), volumetric weight (L x W x H / 5000), packing material/labor, Special Packing info panel (WOODEN_BOX/SKID/VACUUM with live cost preview)
- Carrier Costs - Config-driven zone lookup ->
lookupCarrierRate() -> FSC -> UPS Surge Fee (auto) -> EAS/RAS (auto)
- Add-on Services - Auto-detected (AHS, OSP, OWT, DDP, Surge Fee, EAS/RAS) + user-selectable (19 DHL / 6 UPS / 18 FedEx add-ons; FedEx applies highest-only and 18kg minimum chargeable weight rules)
- Margin - Dynamic margin resolution via
MarginRuleResolver (priority-based first-match-wins algorithm with 5min cache), admin CRUD management, hardcoded fallback if API unavailable. Markup 방식: revenue = cost × (1 + margin%), rounded up to nearest KRW 100
- Warnings - Low margin (<10%), high volumetric weight, surge charges, collect terms (EXW/FOB)
- PDF Output - Branded PDF with packing type/cost breakdown, carrier add-on details, surcharge info
Role-Based Access
| Feature | Admin | Member |
|---|
| Customer Dashboard | O | O |
| Quote Calculator | O | O |
| Carrier Comparison | O | O |
| Margin breakdown visible | O | X |
| Financial settings (Exchange Rate, FSC) | O | X |
| Special Packing options | O | X |
| Weather Widget | O | X |
| Exchange Rate / Calculator Widget | O | X |
| Jet Fuel Widget | O | O |
| Language toggle (i18n) | O | X |
| Currency toggle (KRW/USD) | O | X |
| Flight Schedule | O | X |
| Quote History | O | O |
| PDF Export | O | O |
| Admin Management Panel (collapsible) | O | X |
| Slack notification on save | X | O (auto) |
Dashboard & Widgets
- Customer Dashboard: Landing page after login with welcome banner, recent quotes, and live widgets
- Jet Fuel Price Widget: Real-time USGC Jet Fuel spot prices and trend chart via US EIA API
- Exchange Rate Widget: Real-time KRW rates for 6 currencies (USD, EUR, JPY, CNY, GBP, SGD) via open.er-api.com with localStorage caching, stale detection, and live indicator
- Currency Calculator Widget: Quick currency conversion tool
- Weather Widget: 47 global port & airport weather conditions via Open-Meteo API with paginated carousel and delay alerts
- Global Header: Dark mode toggle, account settings modal (i18n toggle: Admin only)
- Collapsible Admin Widgets: All 7 admin panels default collapsed with toggle
Admin Management Panel (Admin only)
| Widget | Purpose |
|---|
| Target Margin Rules | DB-driven margin rule CRUD with priority tiers (P100/P90/P50/P0) |
| FSC Rate Management | Track/update UPS, DHL & FedEx fuel surcharge percentages |
| Surcharge Management | Carrier-specific surcharge CRUD |
| Customer Management | Customer records with quote count badges |
| User Management | Role assignment, company, nationality, network access |
| Rate Table Viewer | Read-only carrier rate table reference |
| Audit Log | Full audit trail of all admin actions |
Slack Notifications
When a Member saves a quote, a Slack notification is automatically sent to the admin channel with reference number, carrier, destination, billable weight, total quote amount, and margin percentage.
Internationalization (i18n)
- 4 languages: English, Korean, Chinese, Japanese
- Context-based language switching with localStorage persistence
- 390+ translation keys covering all UI strings
Quote History & Management
- Save quotes with auto-generated reference numbers (
SQ-YYYY-NNNN), duplicate detection
- Search, filter by country/date/status, paginated list
- Detail modal with status tracking (Draft -> Sent -> Accepted), CSV export, email, deletion
This is the beginning of the README. Read the rest at the original. Read the full README ↗
