Brief Tehnic și Operațional – Aplicația Intraconstruct

1) Context și Obiective

• Scop: Platformă web pentru sectorul construcțiilor din România, cu frontend modern (Next.js) și CMS WordPress pentru gestionarea conținutului.
• Obiective:
  • Prezentare servicii, produse, companii, profesioniști și proiecte.
  • Integrare SEO/ISR și sitemap dinamic.
  • Arhitectură separată între frontend și CMS pentru fiabilitate și scalabilitate.
  • Fundamente pentru multi-tenancy și CRM provider-side.

3.2) Diagramă arhitectură & flux

Reprezentare a fluxurilor principale între sisteme (Mermaid-like, informativ):

• Creare date: conținut public în WordPress; date operaționale în ERPNext prin Next API.
• SOR: ERPNext păstrează datele master/tranzacționale; UI nu persistă local decât configurări minore.
• Dev: MSW răspunde pentru aceleași rute /api/… – înlocuit de ERPNext în producție.

3.1) Workflow sisteme (CMS, ERPNext, SOR)

• De ce WordPress (CMS)
  • Editorial & SEO: interfață familiară, ecosistem matur (SEO, media, permalinks), workflow de publicare.
  • Public content: pagini, articole și pagini de prezentare pentru companii/servicii/produse destinate SEO.
  • API standard: /wp-json/wp/v2/… pentru expunere conținut public către frontend.
• De ce ERPNext
  • System of Record (SOR) pentru date de business: CRM, Items (produse/servicii), Quotation/Invoice, Project/Task, stocuri, contabilitate.
  • Extensibilitate prin DocTypes, workflow, permisiuni granulare și API REST autenticat.
  • Integrare multi-tenant prin TenantIntegration (Prisma): erpnextBaseUrl, apiKey, apiSecret.
• ERPNext ca SOR
  • Date master și tranzacționale (Customers, Items, Quotations/Invoices, Projects/Tasks) trăiesc în ERPNext.
  • Frontend (Next.js) este adaptor: rutele /api/… citesc/scriu în ERPNext și normalizează răspunsurile pentru UI.
  • MSW se folosește doar în dezvoltare, pentru a simula aceste rute până la conectarea reală.
• Unde se încarcă datele mai întâi
  • Conținut public (SEO): se creează/editează în WordPress (companii/servicii/produse de prezentare). Frontend citește prin REST + ISR.
  • Date de business (Customers, Items, Quotation/Invoice, Projects/Tasks): se creează/editează în ERPNext prin UI-ul frontend (care apelează Next API → ERPNext REST).
  • Documente: pentru procese interne se încarcă în ERPNext (File/attachments sau S3); media publică (imagini promo) rămâne în WordPress uploads.
  • Sync & evenimente: WordPress → webhook la /api/revalidate; ERPNext → opțional webhooks către Next pentru actualizări sau joburi de fundal.
• Consistență și caching
  • Next.js poate cache-ui doar date publice; datele sensibile per-tenant se citesc live din ERPNext.
  • În caz de eroare ERPNext, UI afișează mesaje clare și nu persistă stări locale ca sursă de adevăr.

2) Domenii, URL-uri și Acces

• Frontend: https://intraconstruct.ro
• WordPress CMS: https://cms.intraconstruct.ro
• REST API: /wp-json/
• Admin WordPress: /wp-admin/

3) Arhitectură și Componente

• Frontend (Next.js 15.4.6, React 19.1.0, Tailwind 4)
  • SSR, ISR, caching controlat.
  • Rute SEO/robots/sitemap: src/app/sitemap.ts, src/app/robots.ts.
  • SEO head cu fallback OG/Twitter: components/SEOHead.tsx.
• CMS (WordPress pe PHP-FPM 8.3) – servit direct prin NGINX.
• NGINX
  • Frontend: nginx-config/intraconstruct-domain.conf (proxy către localhost:3002, cache strict pentru /_next/static, no-store pe HTML)
  • CMS: nginx-config/cms-subdomain.conf (CSP strict pe public, relaxat limitat în admin)

4) Integrare WordPress ↔ Frontend

• Config WP API: config/wordpress.js (env: NEXT_PUBLIC_WORDPRESS_SITE_URL, NEXT_PUBLIC_WORDPRESS_MEDIA_URL).
• CPT susținute: companies, products, services, professionals (+ proiecte/portofoliu în sitemap).
• Taxonomii: construction_category, locations, professional_type.
• Sitemap dinamic: src/app/sitemap.ts interoghează wp-json/wp/v2/{type} și adaugă tag-uri pentru revalidare.

5) SEO, ISR și Revalidare

• Robots: src/app/robots.ts (disallow: /api/, /dashboard, /auth, /_next).
• SEO Head: components/SEOHead.tsx cu canonical absolut/relativ, fallback OG/Twitter /og-default.jpg.
• ISR Revalidate API: src/app/api/revalidate/route.ts (POST { secret, path?, tag? }, env: REVALIDATE_SECRET).

6) Stack Tehnic și Versiuni

• Next.js 15.4.6, React 19.1.0, TypeScript 5.9.2, Tailwind 4, Radix UI, Headless UI, react-grid-layout, Zod, jose, nodemailer.
• WordPress + PHP-FPM 8.3.
• NGINX ca reverse proxy și server CMS; Cloudflare DNS.
• PM2 pentru procese Node.js.

7) Securitate și Conformitate

• Headere de securitate (X-Frame-Options, X-XSS-Protection, X-Content-Type-Options, Referrer-Policy) pe CMS.
• CSP strict pe public, relaxat doar în admin pentru compatibilitate media modal.
• Izolare frontend/CMS pe subdomenii separate, CORS gestionat în frontend/proxy.
• No-store pe shell HTML pentru a evita inconsistențe după deploy.

8) Date, Modele și Multi-Tenancy (Prisma)

• Schema: prisma/schema.prisma.
• Modele: User, Tenant, TenantIntegration, ModuleAssignment, ProvisioningJob, ProviderAccount, ProviderContact, TenantProviderLink, Membership, Invite, TenantEmailSettings, GlobalEmailSettings.
• Scop: RBAC, invitații, integrare ERPNext per-tenant, module feature-gated.

9) Deploy și Operare

• Frontend rulează pe port 3002 (proxiat via NGINX).
• Loguri: NGINX (/var/log/nginx), PM2 (~/.pm2/logs).
• Backup & monitorizare: scripturi în home (ex: backup-system.sh, monitor-system.sh).

10) UI/UX și Funcționalități-cheie

• Dashboard Overview modern (breadcrumb, KPIs, charts, activity).
• Dashboard personalizabil (drag & drop, resize, layout persistent).
• Admin Tenants: linkuri utile, widgete de overview (Tenants, Jobs, ERP Connected, Invites, Users).
• SEO solid: canonical corect, OG/Twitter fallback, robots/sitemap, caching adecvat.

11) MSW (Mock Service Worker) – Capabilități și Integrare ERPNext

• Inițializare: src/mocks/MswInit.tsx pornește MSW doar în browser când NEXT_PUBLIC_DATA_PROVIDER=mock sau în dev.
• Handlers: src/mocks/handlers.ts – Auth, Modules/Provision, CRM, Marketing, Offers, Projects/Tasks/Documents/RFQs, Finance, Team/Invites.
• De ce MSW: dezvoltare frontend în paralel cu backend, contract-first, demo/e2e, izolare.
• ERPNext:
  • Mapări: Products/Services → Item; Clients → Customer; Offers → Quotation; Invoices → Sales Invoice; Projects/Tasks → Project/Task; RFQs → Request for Quotation; Documents → File/Upload.
  • Autorizare: header Authorization: token <api_key>:<api_secret> din TenantIntegration.
  • Strategie: păstrați aceleași rute /api/... în Next.js; în producție, rutele apelează ERPNext; în dev, MSW răspunde.

12) Roadmap

• Invitații utilizatori (rol implicit ADMIN) cu email template + link acceptare.
• Auto-sync ProviderAccount la crearea tenantului + UI Super Admin pentru vizualizare/sincronizare.
• Webhook WordPress către /api/revalidate (by path sau tag).
• Setări SEO/branding (og-default.jpg, NEXT_PUBLIC_SITE_URL, PREVIEW_SECRET).
• Asigurare noindex pentru CMS (X-Robots-Tag sau robots.txt).