# Tehnička Dokumentacija E-Commerce Platforme za Proizvođača Suncobrana (Suman d.o.o.) Ova dokumentacija pruža sveobuhvatan tehnički pregled implementirane platforme za proizvođača suncobrana, bazirane na **Medusa.js v2**, **Next.js (App Router)** i **Turborepo** monorepo arhitekturi. Platforma podržava poslovanje na dva odvojena tržišta (**Bosna i Hercegovina** i **Hrvatska**), CRM evidentiranje B2B / HoReCa kupaca, sigurnosnu izolaciju administratorskih korisnika po državama i veleprodajne cjenovnike, u potpunosti poštujući pravilo **korištenja zvaničnog Medusa ekosistema bez izmišljanja custom UI rješenja**. --- ## 1. Arhitektonski Pregled i Tehnološki Stek ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Turborepo Monorepo │ │ │ │ ┌─────────────────────────┐ ┌───────────────────────┐ │ │ │ apps/suman-bosna (BA) │ │apps/suman-hrvatska(HR)│ │ │ │ Next.js Starter │ │ Next.js Starter │ │ │ │ Port: 8000 │ │ Port: 8002 │ │ │ │ Key: pk_ba_... (BAM) │ │ Key: pk_hr_... (EUR) │ │ │ └────────────┬────────────┘ └───────────┬───────────┘ │ │ │ (x-publishable-api-key: BA) │ (x-pub: HR) │ │ ▼ ▼ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ apps/backend (Medusa.js v2) │ │ │ │ │ │ │ │ ┌──────────────────────┐ ┌───────────────────────────────────┐ │ │ │ │ │ Kanal BiH (BAM) │ │ Kanal Hrvatska (EUR) │ │ │ │ │ │ Skladište Gračanica │ │ Skladište Zagreb │ │ │ │ │ └──────────────────────┘ └───────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ HTTP Middleware Interceptor (Izolacija Admina po Kanavu) │ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────┐ ┌───────────────────────────────────┐ │ │ │ │ │ CRM B2B Admin Widget│ │ B2B Event Subscriber │ │ │ │ │ │ (Isključivo @medusa/ui)│ │ (Webhook na HubSpot / Brevo) │ │ │ │ │ └──────────────────────┘ └───────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ B2B Price List Override (HoReCa B2B Partneri Cjenovnik) │ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────┬────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ Infrastruktura (Docker) │ │ │ │ - PostgreSQL 16 (Baza: medusa-suman-doo) │ │ │ │ - Redis 7 (umbrella-redis :6379 za Event Bus i Sesije) │ │ │ └───────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### Korištene Tehnologije: - **Medusa Core**: `@medusajs/medusa` v2.22.3 (Node.js >= 22) - **Admin Dashboard**: Ugrađeni Medusa Admin (Vite + React) proširen sa `@medusajs/admin-sdk` i `@medusajs/ui` v4.2.9 - **Frontend Storefronts**: Zvanični `@medusajs/nextjs-starter-template` (Next.js 16 App Router) - **Baza Podataka**: PostgreSQL 16 - **Keš i Event Bus**: Redis 7 - **Monorepo Manager**: Turborepo --- ## 2. Infrastruktura i Konfiguracija Okruženja ### 2.1. Docker Compose (`docker-compose.yml`) U korijenu repozitorijuma nalazi se trajna definicija servisa baze i keša: - **PostgreSQL 16**: Port `5432`, baza `medusa-suman-doo`. - **Redis 7**: Kontejner `umbrella-redis`, port `6379`. ### 2.2. Backend Okruženje (`apps/backend/.env`) ```env PORT=9000 DATABASE_URL=postgres://suman_user:TvojaSigurnaLozinka123!@localhost:5432/medusa-suman-doo REDIS_URL=redis://localhost:6379 JWT_SECRET=supersecret COOKIE_SECRET=supersecret STORE_CORS=http://localhost:8000,http://localhost:8002,https://docs.medusajs.com ADMIN_CORS=http://localhost:5173,http://localhost:9000,https://docs.medusajs.com AUTH_CORS=http://localhost:5173,http://localhost:9000,http://localhost:8000,http://localhost:8002,https://docs.medusajs.com CRM_WEBHOOK_URL=https://api.hubspot.com/v1/webhook/umbrella-orders CRM_API_KEY=crm_secret_token_b2b ``` ### 2.3. Storefront BiH (`apps/suman-bosna/.env.local`) ```env NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_b722e44870bc8cc7828d0713980537e95b2e74ff229a529a4b3fa8155035f1f0 NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000 NEXT_PUBLIC_DEFAULT_REGION=ba NEXT_PUBLIC_BASE_URL=http://localhost:8000 NODE_ENV=development ``` ### 2.4. Storefront Hrvatska (`apps/suman-hrvatska/.env.local`) ```env NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_031702290a2f70f73ecc0cf0663bf7382ee625cb2098d10d34c4b5c6623c044c NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000 NEXT_PUBLIC_DEFAULT_REGION=hr NEXT_PUBLIC_BASE_URL=http://localhost:8002 NODE_ENV=development ``` --- ## 3. Multi-Channel Arhitektura (Dva Webshopa iz Jedne Baze) Multi-tenant rješenje koristi Medusa v2 **Sales Channels** i **Remote Links**, čime se postiže potpuna izolacija kataloga i zaliha bez dupliciranja koda ili baze. ### 3.1. Konfiguracija Kanala i Skladišta | Parametar | Kanal 1 (Bosna i Hercegovina) | Kanal 2 (Hrvatska) | | :--- | :--- | :--- | | **Storefront Aplikacija** | `apps/suman-bosna` (Port 8000) | `apps/suman-hrvatska` (Port 8002) | | **Sales Channel Naziv** | `Suman d.o.o. - Bosna i Hercegovina` | `Suman d.o.o. - Hrvatska` | | **Sales Channel ID** | `sc_01M6SJ3AG7CTC55DZDDVRSR44J` | `sc_01M6SKCNSJA9R34666NEEH1FHN` | | **Povezano Skladište** | `Centralno Skladište Suman Gračanica (BiH)` | `Distributivni Centar Suman Zagreb (HR)` | | **Stock Location ID** | `sloc_01M6SJ3AGHK91SD1M120G7BVA5` | `sloc_01M6SKCNSTVM7JGM3DAPWZDRC5` | | **Publishable API Key** | `pk_b722e44870bc8cc7828d0713980537e95b2e74ff229a529a4b3fa8155035f1f0` | `pk_031702290a2f70f73ecc0cf0663bf7382ee625cb2098d10d34c4b5c6623c044c` | | **Valuta / Regija** | BAM / KM (`ba`) | EUR (`hr`) | > [!NOTE] > **Rješenje za "Out of Stock" problem:** Skladišta su eksplicitno povezana sa pripadajućim prodajnim kanalima kroz zvanični Medusa core workflow `linkSalesChannelsToStockLocationWorkflow`. Svi artikli imaju raspoložive zalihe u odgovarajućem regionalnom skladištu. --- ## 4. Sigurnost i Admin Izolacija po Državama Standardni Medusa Admin podrazumijeva globalni pristup svim podacima. Izolacija je implementirana **na nivou API sloja** bez izmjene ili račvanja izvornog koda dashboarda. ### 4.1. Mehanizam Rada (`apps/backend/src/api/middlewares.ts`) 1. Svaki regionalni admin u `user.metadata` ima zapisan `sales_channel_id`. 2. Middleware presreće sve administratorske zahtjeve prema narudžbama (`/admin/orders*`). 3. **Zahtjev za listu (`GET /admin/orders`):** Injektuje se filter `req.query.sales_channel_id = [user.metadata.sales_channel_id]`. Admin vidi samo narudžbe iz svoje države. 4. **Zahtjev za detalje (`GET /admin/orders/:id`):** Provjerava se kanal narudžbe. Ukoliko ne pripada kanalu korisnika, backend automatski vraća HTTP `403 NOT_ALLOWED`. 5. **Super Admini:** Korisnici sa `sales_channel_id: null` (npr. `admin@suncobrani.com`) zadržavaju puni pristup svim podacima. ### 4.2. Administratorski Nalozi za Testiranje | Nalog | Email | Šifra | Nivo Pristupa | | :--- | :--- | :--- | :--- | | **Super Admin** | `admin@suncobrani.com` | `supersecret123` | Globalni pristup (sve države, svi kanali, sve narudžbe) | | **Admin BiH** | `admin.ba@suncobrani.com` | `SigurnaSifra123` | Vidi isključivo narudžbe za Bosnu i Hercegovinu | | **Admin HR** | `admin.hr@suncobrani.com` | `SigurnaSifra123` | Vidi isključivo narudžbe za Republiku Hrvatsku | --- ## 5. B2B / CRM Modul & Admin Widget Za poslovanje sa ugostiteljima (HoReCa sektor) implementiran je CRM mehanizam koji ne mijenja osnovne tabele baze, već koristi Medusino polje `metadata` na entitetu `Customer`. ### 5.1. Admin UI Widget (`apps/backend/src/admin/widgets/customer-crm-widget.tsx`) Injektovan je na stranicu detalja kupca (`customer.details`). > [!IMPORTANT] > **Pravilo o zabrani izmišljanja UI-ja:** Widget je izgrađen **isključivo pomoću komponenti paketa `@medusajs/ui`** prateći zvanične semantičke stilove Medusa dizajna: > - `` > - `` i `` > - `` i `