# راهنمای تحویل توسعه‌دهندگان پورتال‌ها (ACC Engine)

| فیلد | مقدار |
|------|--------|
| **هدف** | یک سند واحد برای برنامه‌نویسان هر پورتال: Entry، مسیر critical first-load، نقشه JS/CSS، جداول DB، گلوگاه‌های شناخته‌شده، و چک‌لیست پروفایل |
| **آخرین به‌روزرسانی** | 2026-07-17 (Growth / سفیران) |
| **PHP CLI** | `C:\xampp\php\php.exe` |
| **پیشوند جداول** | معمولاً `wp_` (از `Standalone_DB::$prefix` / `$wpdb->prefix`) |
| **API پایه** | `/acc-engine/api.php/acc/v1` |
| **منبع حقیقت** | قالب‌های `templates/*-page.php` و entryهای ریشه — نه حافظهٔ قدیمی |

> فونت‌ها، تصاویر hero/story پورتال‌ها، Leaflet و کاشی نقشه همگی **لوکال / آفلاین** هستند. جزئیات: [منابع آفلاین](#۱۱-منابع-آفلاین--بدون-اینترنت) و [فهرست مسیر تصاویر](#۱۲-فهرست-مسیر-تصاویر).

---

## فهرست مطالب

1. [جدول مقایسهٔ ریسک first-load](#۰-جدول-مقایسهٔ-ریسک-first-load)
2. [ERP / Holding SPA (`index.php`)](#۱-erp--holding-spa)
3. [Melk — اقتصاد ملک](#۲-melk--اقتصاد-ملک)
4. [Wholesale — عمده‌فروشی B2B](#۳-wholesale--عمده‌فروشی-b2b)
5. [Election — سامانه هوادران](#۴-election--سامانه-هوادران)
6. [Service / HVAC](#۵-service--hvac)
7. [Education — EduBrain](#۶-education--edubrain)
8. [Shop — عرقیات (Arag)](#۷-shop--عرقیات-arag)
9. [Growth / سفیران](#۸-growth--سفیران)
10. [سایر entryهای ریشه](#۹-سایر-entryهای-ریشه)
11. [جداول مشترک / هسته ERP](#۱۰-جداول-مشترک--هسته-erp)
12. [نکات کلی پروفایل](#۱۱-نکات-کلی-پروفایل)
13. [منابع آفلاین / بدون اینترنت](#۱۲-منابع-آفلاین--بدون-اینترنت)
14. [فهرست مسیر تصاویر](#۱۳-فهرست-مسیر-تصاویر)

---

## ۰. جدول مقایسهٔ ریسک first-load

اندازه‌ها تقریبی روی دیسک (2026-07-17). فونت‌ها و تصاویر hero **لوکال**؛ نقشه با کاشی‌های `assets/vendor/leaflet/tiles_*`.

| پورتال | CSS blocking (تقریبی) | JS entry | Font | Hero / LCP | API قبل از paint؟ | Chat روی first paint | ریسک اصلی |
|--------|----------------------|----------|------|------------|-------------------|----------------------|-----------|
| **ERP** | `fonts-local` + leaflet + FA `all.min` (~100KB) + tabulator + landing + erp/home-applied | `acc-app.js` **~1.6MB** IIFE `defer` | **local** DM Sans + Vazirmatn | CSS gradient (بدون عکس سنگین) | نه برای لندینگ ناشناس | **بله — blocking** از `wp_footer` | Bundle بزرگ + CSSهای ERP/GIS/FA بی‌ربط به لندینگ + chat |
| **Melk** | `fonts-local` + `melk-applied.css?v=5` (~21KB) | `MelkAppView.js?v=24` ~32KB module | **local** Cormorant + Outfit + Vazirmatn | **local** `portals/melk/hero-skyline.jpg` + preload | نه (ناشناس) | **idle deferred** | حجم hero JPG |
| **Election** | `fonts-local` + `election-portal.css?v=12` + `election-applied.css?v=4` | `ElectionAppView.js?v=12` ~103KB + eager Map + Candidate + ABC panel | **local** Figtree + Instrument Serif + Vazirmatn | **local JPG ~213KB** | **بله** `public/election/meta` | ندارد | Blank تا meta؛ hero JPG؛ JS سنگین eager |
| **Service** | `fonts-local` + landing + app + `service-portal?v=3` + `service-applied?v=7` | `ServiceAppView.js?v=22` + eager Workspace + Talent + Acl | **local** Sora + Vazirmatn | **local** `portals/service/hero-hvac.jpg` | نه (ناشناس) | **blocking** (`chat-widget-boot`) | hero بزرگ + chat sync |
| **Wholesale** | `fonts-local` + landing + `wholesale-portal.css?v=5` | `WholesaleAppView.js?v=4` ~36KB | **local** Vazirmatn | متنی / بدون عکس LCP سنگین | **بله** meta + preview catalog | **blocking** + AI JS | دو API قبل از paint + chat |
| **Education** | `fonts-local` + landing + app + portal + applied `?v=3` (~80KB+) | AppView + **۴ import eager** (~143KB+) | **local** Fraunces + Manrope + Vazirmatn | **local** `portals/education/hero-books.jpg` | نه (ناشناس) | **blocking** | hero بزرگ + JS graph |
| **Shop** | `fonts-local` + premium (~77KB) + upgrade (~50KB) + applied `?v=3` | `AragShopView.js?v=22` ~106KB | **local** Fraunces + Sora + Vazirmatn (+ Amiri در premium) | **local** `shop/hero-poster.jpg` (+ ویدیو اختیاری لوکال) | **بله** settings + families (+ payment) | **blocking** + AI | CSS سنگین + API زنجیره‌ای |
| **Growth** | `fonts-local` + `growth-applied.css?v=1` (~15KB) | `GrowthAppView.js?v=1` ~41KB module | **local** Fraunces + Manrope + Vazirmatn | گرادیان/باند CSS (بدون JPG) | **بله** `growth/meta` قبل از landing HTML | ندارد | Blank تا meta؛ MVP تک‌فایل |

---

## ۱. ERP / Holding SPA

### ۱.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `http://localhost/acc-engine/` یا `/acc-engine/index.php` |
| Entry PHP | `C:\xampp\htdocs\acc-engine\index.php` |
| قالب | `templates/spa.php` |
| Boot JS (سورس) | `assets/js/app.js` → `HomeView.js` (داخل Vite bundle) |
| Bundle | `assets/dist/acc-app.js?v=hl20260716c` |

`index.php` قبل از قالب، `includes/install.php` و ده‌ها Controller را `require` می‌کند → **TTFB PHP** می‌تواند قابل توجه باشد حتی قبل از HTML.

### ۱.۲ Critical path — بازدیدکنندهٔ ناشناس

ترتیب تقریبی (همهٔ CSSها **blocking** مگر خلافش ذکر شود):

1. **CSS blocking**
   - `/acc-engine/assets/css/base/fonts-local.css` — self-hosted `@font-face` (بدون CDN)
   - `/acc-engine/assets/vendor/leaflet/leaflet.css` (~14KB)
   - `/acc-engine/assets/css/all.min.css` (~100KB Font Awesome)
   - `/acc-engine/tabulator-master/dist/css/tabulator.min.css` (~28KB)
   - `/acc-engine/assets/css/app.css` (~1KB)
   - `/acc-engine/assets/css/base/landing.css?v=hl20260717fonts` (~29KB)
   - `/acc-engine/assets/css/base/erp-applied.css?v=hl20260717fonts` (~7KB)
   - `/acc-engine/assets/css/base/home-applied.css?v=hl20260717fonts` (~15KB)
2. **Fonts:** local via `fonts-local.css` + `assets/fonts/*` (DM Sans + Vazirmatn)
3. **JS:** `leaflet.js` (~144KB، بدون defer) سپس `acc-app.js?v=hl20260717fonts` (~**1578KB**) با `defer` — IIFE، نه `type=module`
4. **Hero / LCP:** `.hl-hero__media` فقط **گرادیان CSS** — بدون تصویر remote
5. **API قبل از paint:** برای لندینگ ناشناس معمولاً خیر؛ ورود از `HomeView` به `/public/auth/*`
6. **Chat / PWA (footer via `Chat_Controller` → `wp_footer`):** **blocking**
   - `assets/css/base/chat-widget.css` (~26KB)
   - `assets/js/chat-widget/erp-wizards.js`
   - `assets/js/chat-widget/widget.js` (~69KB)
   - ثبت مجدد Service Worker با وجود unregister در `<head>` قالب

### ۱.۳ نقشهٔ سورس JS/CSS

| نقش | فایل |
|-----|------|
| Shell | `templates/spa.php` |
| App router | `assets/js/app.js` (bundled) |
| لندینگ | `assets/js/views/HomeView.js` |
| ERP UI applied | `assets/css/base/erp-applied.css`, `home-applied.css`, `landing.css` |
| Workspace سنگین | Tabulator + Leaflet (روی لندینگ هم لود می‌شوند) |

### ۱.۴ Backend

Controllers لودشده از `index.php` (نمونه): Auth, Dashboard, SmartFlow, Accounting, Sales, Purchase, Payroll, GIS, Inventory, ACL, HR, Workflow, Shipping, Assets, Chat, SR, CPM*, Runtime*, …

### ۱.۵ جداول (هسته — پیشوند `wp_`)

گروه‌های اصلی از `includes/install.php` (لیست کامل طولانی است):

- **Runtime / ACL:** `erp_*`, `accj_*`, `acl_*`
- **GIS:** `gis_districts`, `gis_neighborhoods`, `gis_parcels`, `gis_parcel_*`, `gis_locations`, `gis_block_stats`, …
- **Inventory:** `inv_categories`, `inv_products`, `inv_warehouses`, `inv_stock`, `inv_vouchers`, …
- **CPM:** `cp_projects`, `cp_tasks`, …
- **HR / WF / Ship / Assets:** `hr_*`, `wf_*`, `ship_*`, `asset*`
- **Chat:** `chat_rooms`, `chat_messages`, `chat_participants`, `chat_visitors`, `chat_conversations`
- **Users:** جداول کاربران وردپرس‌مانند (`users`, `usermeta`, `options`) بسته به نصب

### ۱.۶ گلوگاه‌های شناخته‌شده

- Bundle Vite **~1.6MB** برای لندینگ Holding
- CSSهای Leaflet / Font Awesome / Tabulator روی first paint لندینگ
- Chat widget + PWA SW در footer با اسکریپت sync
- TTFB به‌خاطر bootstrap سنگین `index.php`

### ۱.۷ پروفایل

1. DevTools → Network → Disable cache → Hard reload
2. فیلتر CSS / JS / Font — زمان **Waiting (TTFB)** سند HTML را جدا از download `acc-app.js` بنویسید
3. Coverage: چه مقدار CSS FA/Tabulator روی لندینگ unused است
4. Performance: LCP روی `.hl-hero__brand` / متن؛ آیا chat در main thread با bundle رقابت می‌کند

---

## ۲. Melk — اقتصاد ملک

### ۲.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/melk.php` |
| Entry | `melk.php` → `templates/melk-page.php` |
| Partial | `templates/partials/melk-widget-boot.php` (**deferred chat**) |
| JS entry | `assets/js/views/MelkAppView.js?v=24` |
| CSS applied | `assets/css/base/melk-applied.css?v=5` |

### ۲.۲ Critical path — ناشناس

1. **Fonts (local):** `fonts-local.css` — Cormorant Garamond + Outfit + Vazirmatn
2. **Preload LCP:** `/acc-engine/assets/img/portals/melk/hero-skyline.jpg` (`fetchpriority=high`)
3. **CSS blocking:** `fonts-local` + `melk-applied.css?v=5` (~21KB)
4. **JS module:** inline `import MelkAppView …?v=24` (~32KB) — لندینگ از همین فایل paint می‌شود
5. **API قبل از paint:** خیر برای ناشناس؛ با توکن: `acl/me` سپس dynamic import workspace
6. **Chat:** بعد از `requestIdleCallback` (timeout 2500ms) — CSS/JS chat **نه** در critical path
7. **بعد از login:** dynamic `import('./melk/MelkWorkspace.js')` + CSS on-demand:
   - `eqtesad-melk.css?v=18` (~56KB)
   - `gis.css`

Hero دوم (story): `/acc-engine/assets/img/portals/melk/story-home.jpg` در CSS.

### ۲.۳ نقشهٔ JS/CSS

| لایه | فایل‌ها |
|------|---------|
| Landing | `MelkAppView.js` (~32KB) |
| Workspace (پس از login) | `melk/MelkWorkspace.js` (~48KB) + پنل‌ها (جمع ~270KB طبق کامنت سورس) |
| پنل‌های سنگین | `melk-construction-panel.js` (~38KB), `melk-building-specialists-panel.js` (~27KB), `melk-listings-panel.js` (~24KB), `melk-investor-panel.js`, `melk-gis-panel.js`, … |
| CSS | `melk-applied.css`; workspace: `eqtesad-melk.css`, `gis.css` |

### ۲.۴ Backend

- `includes/controllers/Eqtesad_Melk_Controller.php`
- `includes/controllers/Melk_Extensions_Controller.php`
- Helpers: `melk-listing-forms.php`, `melk-investor.php`, `melk-advisory*.php`, `melk-activity-cost.php`, `melk-county-forms.php`, …

### ۲.۵ جداول (پیشوند `wp_`)

**هسته Melk** (`run-melk-install.php`):

- `melk_org_assignments`, `melk_cases`, `melk_case_participants`, `melk_case_notes`

**Extensions** (`run-melk-extensions-install.php`):

- `melk_construction_projects`, `melk_construction_participants`
- `melk_listings`, `melk_county_requests`
- `melk_building_specialists`, `melk_specialist_tenders`, `melk_specialist_bids`
- `melk_listing_form_templates`, `melk_specialist_form_templates`, `melk_county_form_templates`

**Investor / Advisory / ABC:**

- `melk_investor_profiles`, `melk_investment_criteria`, `melk_listing_matches`, `melk_investor_expert_requests`
- `melk_advisory_sessions`, `melk_advisory_messages`
- `melk_acc_activities`, `melk_acc_project_crew`, `melk_acc_activity_costs`

**GIS مشترک (core):** `gis_*` برای نقشه/پارسل

### ۲.۶ وضعیت گلوگاه‌ها (پس از بهینه‌سازی‌های قبلی)

| موضوع | وضعیت فعلی (از قالب/کد) |
|--------|-------------------------|
| CSS اضافی روی لندینگ | حذف شده — فقط `fonts-local` + `melk-applied?v=5` |
| فونت | **local** — `fonts-local.css` + `assets/fonts/*` (بدون Google CDN) |
| MelkWorkspace eager | **دیگر نه** — dynamic import بعد از login |
| Heroes | **local** — `assets/img/portals/melk/*` + preload |
| Chat blocking | **رفع** — idle deferred |
| Cache bust | CSS `v=5`, JS `v=24`, fonts `v=2` |

### ۲.۷ پروفایل

1. Anonymous hard reload → فقط `fonts-local.css`, `melk-applied.css`, `hero-skyline.jpg`, `MelkAppView.js`
2. مطمئن شوید chat تا idle ظاهر نمی‌شود
3. بعد از demo-login: زمان download `MelkWorkspace.js` + پنل‌ها + `eqtesad-melk.css` را جدا ثبت کنید
4. LCP: تصویر لوکال `portals/melk/hero-skyline.jpg` — نباید درخواست Unsplash/CDN باشد

---

## ۳. Wholesale — عمده‌فروشی B2B

### ۳.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/wholesale.php` |
| Entry | `wholesale.php` → `templates/wholesale-page.php` |
| Partial | `partials/wholesale-widget-boot.php` → `chat-widget-boot.php` |
| JS | `WholesaleAppView.js?v=4` |
| CSS | `fonts-local.css` + `landing.css` + `wholesale-portal.css?v=5` (~15KB) |

### ۳.۲ Critical path — ناشناس

1. Fonts local: Vazirmatn via `fonts-local.css`
2. CSS blocking: `fonts-local`, `landing.css`, `wholesale-portal.css?v=5`
3. JS module: `WholesaleAppView.js?v=4` (~36KB)
4. **API قبل از `_paint` (منتظر می‌ماند):**
   - `GET public/wholesale/meta`
   - `GET public/wholesale/catalog?per_page=8&in_stock=1` (preview)
5. Hero: بیشتر متن/badge — بدون JPG محلی بزرگ
6. Chat **blocking:** `chat-widget.css` + `wholesale-wizards.js` + **`wholesale-ai.js`** + `widget.js`

### ۳.۳ Backend / جداول

- Controller: `Wholesale_Controller.php`
- Install: `run-wholesale-install.php`, seed: `run-wholesale-seed.php` / `includes/data/wholesale-seed.php`
- جداول: `wholesale_applications`, `wholesale_accounts`, `wholesale_products`, `wholesale_prices`, `wholesale_orders`
- نقش‌ها: `wholesale_buyer`, `wholesale_admin` (ACL)

> **عدم قطعیت:** اگر نسخهٔ بعدی order-items/shipment جدا اضافه کرده باشد، در install فعلی دیده نشد — با `SHOW TABLES LIKE 'wp_wholesale%'` تأیید کنید.

### ۳.۴ گلوگاه‌ها

- دو fetch عمومی قبل از هر pixel UI
- Chat + AI script sync در انتهای body
- `landing.css` عمومی (~29KB) روی پورتال B2B

### ۳.۵ پروفایل

1. فیلتر XHR/Fetch: `public/wholesale/meta` و `catalog` — Waterfall قبل از DOM paint
2. مقایسهٔ با/بدون chat (block در DevTools) برای تأثیر روی TTI

---

## ۴. Election — سامانه هوادران

### ۴.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/election.php` |
| Entry | `election.php` → `templates/election-page.php` |
| حسابداری | `election-accounting.php` → `templates/election-accounting-page.php` |
| JS | `ElectionAppView.js?v=12` |
| CSS | `fonts-local.css` + `election-portal.css?v=12` + `election-applied.css?v=4` |

### ۴.۲ Critical path — ناشناس

1. Fonts local: Figtree + Instrument Serif + Vazirmatn
2. CSS blocking: `fonts-local` + portal (~32KB) + applied (~20KB)
3. **JS module graph (eager static imports):**
   - `ElectionAppView.js` (~103KB)
   - `ElectionMapView.js?v=11` (~4KB)
   - `ElectionCandidateWidget.js?v=12` (~19KB)
   - `election/election-accounting-panel.js?v=1` (~11KB)
4. **`render()` منتظر `GET public/election/meta` می‌ماند** → ریشه خالی تا پاسخ meta (یا catch خالی)
5. **Hero LCP:** local  
   `/acc-engine/assets/img/election/hero-majles.jpg` (~**213KB**)  
   Story: `story-majles.jpg` (~**291KB**)
6. پس از paint: Candidate widget روی `document.body` mount می‌شود
7. Chat widget روی این صفحه نیست

### ۴.۳ Backend / جداول

- Controller: `Election_Controller.php`
- Helpers: `election-havadaran.php`, `election-ballot-core.php`, `election-logistics.php`, `election-personal-hq.php`, `election-activity-cost.php`

**جداول (نصب‌های v1…v9 + ABC):**

| گروه | جداول |
|------|--------|
| پایه | `election_stations`, `election_segments`, `election_branches`, `election_supporters`, `election_content`, `election_packages`, `election_sms_log`, `election_reports` |
| v2 | `election_hqs`, `election_missions` |
| v3 | `election_districts`, `election_user_stations`, `election_station_pois`, `election_phase_config`, `election_station_tasks`, `election_briefings`, `election_shipments`, `election_org_units`, `election_org_assignments` |
| v4–v6 | `election_dept_work`, `election_warehouse_items`, `election_warehouse_moves`, `election_banner_spots`, `election_onboarding` |
| v7 مالی | `election_budget` / transactions / fin_audit (نام دقیق از helper: `budget_table()`, `transactions_table()`, `fin_audit_table()`) |
| v8–v9 | `election_candidate_suggestions` (نام از helper), `election_sector_engagements` |
| ABC | `election_acc_campaigns`, `election_acc_activities`, `election_acc_campaign_crew`, `election_acc_activity_costs` |

> نام دقیق جداول مالی v7 را از متدهای `Election_Havadaran::*\_table()` بخوانید — ممکن است با پیشوند helper کمی متفاوت از حدس خام باشد.

### ۴.۴ گلوگاه‌های شناخته‌شده

- Blank تا اتمام `public/election/meta` (stats/GIS counts در backend)
- فونت‌ها لوکال (`fonts-local.css`)
- Hero/story JPGهای محلی نسبتاً بزرگ (~200–300KB)
- نقشه: `ElectionMapView.js` → کاشی آفلاین `tiles_esri` (الگوی نقشه هوشمند)
- Admin dashboard بعد از login: `election/me` + `election/dashboard` (سابقاً ~1.5s در محیط‌های اندازه‌گیری‌شده — دوباره اندازه بگیرید)
- Eager import پنل حسابداری حتی روی لندینگ عمومی

### ۴.۵ پروفایل

1. Performance: زمان «اولین محتوا» vs پایان `meta`
2. Img: حجم واقعی `hero-majles.jpg` فشرده‌سازی WebP؟
3. بعد از login admin: Waterfall `dashboard` و کوئری‌های سنگین GIS/segments

---

## ۵. Service / HVAC

### ۵.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/service.php` |
| Entry | `service.php` → `templates/service-page.php` |
| Partial | `partials/service-widget-boot.php` → chat sync |
| گزارش عمومی | `service-report.php` (SSR/PDF، نه SPA) |
| پرداخت | `service-pay.php` |
| JS | `ServiceAppView.js?v=22` |
| CSS | `fonts-local.css`, `landing.css`, `app.css`, `service-portal.css?v=3`, `service-applied.css?v=7` |

### ۵.۲ Critical path — ناشناس

1. Fonts local: Sora + Vazirmatn via `fonts-local.css` (بدون remote `@import`)
2. CSS blocking: fonts-local + landing + app + portal + applied
3. JS module eager:
   - `ServiceAppView.js` (~42KB)
   - `service/ServiceWorkspace.js` (~17KB)
   - `service/ServiceTalentFlow.js` (~26KB)
   - `../core/AclService.js` (~5KB)
4. Hero: local `assets/img/portals/service/hero-hvac.jpg` (+ story در CSS)
5. API قبل از paint ناشناس: خیر (فقط اگر session/token موجود باشد)
6. Chat **blocking** کامل (`chat-widget.css` + `service-wizards.js` + `widget.js`)
7. Demo seed مرتبط: `run-service-hvac-demo-seed.php`, سناریوها: `docs/service/hvac-demo-scenarios.json` (lazy از AppView در مسیر demo)

### ۵.۳ Backend / جداول

Controllers: `SR_Controller`, `SR_Reward_Controller`, `SR_Supplier_Controller`, `SR_Talent_Controller`, `SR_Marketer_Controller`, `SR_Accounting_Controller`

**عملیات میدانی** (`run-service-migrate.php`):  
`svc_devices`, `svc_requests`, `svc_reports`, `svc_pm_contracts`, `svc_payments`, `svc_technician_teams`

**Reward / Marketer / Supplier / Talent / Algorithm / Acc:**

- `svc_reward_accounts`, `svc_reward_ledger`, `svc_reward_badges`
- `svc_marketer_accounts`, `svc_marketer_leads`, `svc_marketer_commissions`, `svc_marketer_payouts`
- `svc_supplier_profiles`, `svc_supplier_catalog`
- `svc_talent_*` (applications, identities, certificates, questions, …)
- `svc_parts_orders`, `svc_equipment_inquiries`
- `svc_acc_config`, `svc_acc_splits`, `svc_acc_journal`
- ABC: `svc_acc_activities`, `svc_acc_order_crew`, `svc_acc_activity_costs`

### ۵.۴ گلوگاه‌ها

- Hero لوکال نسبتاً بزرگ (`hero-hvac.jpg`)
- Eager load Workspace/Talent روی لندینگ مشتری
- Chat sync در critical path
- HVAC demo seed فقط برای دادهٔ تست — روی first-load ناشناس اثر ندارد مگر مسیر demo فراخوانی شود

### ۵.۵ پروفایل

1. Waterfall: `fonts-local.css` → woff2 لوکال؛ سپس applied CSS
2. Img: `portals/service/hero-hvac.jpg` — بدون Unsplash
3. Block `widget.js` و اندازه‌گیری تفاوت FCP

---

## ۶. Education — EduBrain

### ۶.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/education.php` |
| Entry | `education.php` → `templates/education-page.php` |
| حسابداری | `education-accounting.php` → `education-accounting-page.php` |
| Partial | `partials/education-widget-boot.php` |
| JS | `EducationAppView.js?v=7` |
| CSS | `fonts-local.css`, `landing.css`, `app.css`, `education-portal.css?v=7`, `education-applied.css?v=3` |

### ۶.۲ Critical path — ناشناس

1. Fonts local: Fraunces + Manrope + Vazirmatn via `fonts-local.css`
2. CSS blocking: fonts-local + landing + app + portal + applied
3. JS eager static imports (~مجموع قابل توجه):
   - `EducationAppView.js` (~62KB)
   - `education/EducationMapView.js`
   - `education/EduPanels.js` (~20KB)
   - `education/EduRequestFlow.js` (~15KB)
   - `education/EduLifeCompanion.js` (~32KB)
   - `education/edu-accounting-panel.js` (~10KB)
4. Hero: local `assets/img/portals/education/hero-books.jpg` (+ story library)
5. API قبل از paint ناشناس: **خیر**؛ با توکن: `/education/meta`, `/education/me`, `/education/dashboard`
6. Chat **blocking**
7. نقشه: `EducationMapView` + `Edu_GIS::map_payload()` → کاشی آفلاین `tiles_esri` (نه OSM.org)

### ۶.۳ Backend / جداول

- Controller: `Education_Controller.php`
- Helpers: `education-platform.php`, `education-activity-cost.php`, `education-cost-accounting.php`, `education-companion-extras.php`, …

**جداول پایه** (`run-education-install.php`):  
`edu_learners`, `edu_learner_academic_log`, `edu_learner_skill_log`, `edu_educators`, `edu_organizations`, `edu_org_resources`, `edu_org_schedule`, `edu_sessions`, `edu_assessments`, `edu_service_requests`, `edu_learning_plans`, `edu_acc_config`, `edu_acc_splits`, `edu_acc_journal`

**ABC:** `edu_abc_activities`, `edu_abc_session_crew`, `edu_abc_activity_costs`

> Companion extras بیشتر روی `user_meta` / منطق PHP است تا جدول جدید — کامل بودن schema را با `SHOW TABLES LIKE 'wp_edu%'` چک کنید.

### ۶.۴ گلوگاه‌ها

- Hero لوکال بزرگ (`hero-books.jpg` ~646KB)
- گراف JS بزرگ روی لندینگ (Companion/Panels/ABC حتی قبل از login)
- Chat sync
- `landing.css` + `app.css` عمومی
- کاشی نقشه فعلی پوشش **شیراز** است؛ مارکرهای خارج از بسته → `blank.png`

### ۶.۵ پروفایل

1. Coverage روی JS modules لندینگ — چه درصدی قبل از login اجرا می‌شود
2. LCP: `portals/education/hero-books.jpg` (لوکال؛ بدون Unsplash)
3. پس از login حسابدار: هزینهٔ `/education/dashboard` و پنل ABC
4. نقشه: درخواست کاشی فقط به `/acc-engine/assets/vendor/leaflet/tiles_esri/…`

---

## ۷. Shop — عرقیات (Arag)

### ۷.۱ Entry و قالب اصلی

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/shop.php` |
| Entry | `shop.php` → `templates/shop-page.php` |
| Partial | `partials/shop-widget-boot.php` (+ AI JS) |
| JS | `AragShopView.js?v=22` |
| CSS | `fonts-local.css`, `shop-premium.css?v=14` (~77KB), `shop-upgrade.css?v=10` (~50KB), `shop-applied.css?v=3` (~12KB) |

### ۷.۲ Critical path — ناشناس (خانهٔ فروشگاه)

1. Fonts local: Fraunces + Sora + Vazirmatn (+ Amiri از premium) via `fonts-local.css` — بدون Google CDN / بدون `@import` دوبل
2. CSS blocking مجموع ~140KB+ (به‌علاوه fonts-local)
3. JS module: `AragShopView.js` (~106KB)
4. **قبل از UI کامل، `render()` منتظر می‌ماند:**
   - `_loadPaymentMethods()`
   - `_loadSettings()` → `GET /public/arag/shop/settings`
   - `_familiesHtml()` → `GET /public/arag/families`
   - سپس `_syncCartFromServer()` (پس از paint نسبی؛ cart)
5. Hero: local `assets/img/shop/hero-poster.jpg` (+ story `portals/shop/story-herbs.jpg`)؛ در صورت تنظیمات: **ویدیو hero** لوکال (`hero_video_url` + poster)
6. Chat blocking + `shop-ai.js`

### ۷.۳ صفحات خواهر Shop

| URL | قالب | View |
|-----|------|------|
| `shop-admin.php` | `shop-admin-page.php` | `AragShopAdminView.js` |
| `shop-erp.php` | `shop-erp-page.php` | `AragShopErpView.js` |
| `shop-accounting.php` | `shop-accounting-page.php` | `AragShopAccountingView.js` |
| `shop-mizaj.php` | `shop-mizaj-page.php` | `AragShopMizajView.js` + chat |
| `shop-api-docs.php` | `shop-api-docs-page.php` | docs UI |
| `account.php` | `account-page.php` | `MyAccountView.js` |
| `platform.php` | `platform-page.php` | static + `platform-landing.js` (API stats/plans) |

### ۷.۴ Backend / جداول

Controllers: `Arag_Shop_Controller.php`, `Arag_Erp_Controller.php`  
Helpers: `arag-shop.php`, `arag-erp.php`, `arag-expense.php`, `arag-mizaj.php`, …

| گروه | جداول |
|------|--------|
| کاتالوگ | `arag_families`, `arag_variants`, `arag_packages` |
| سفارش / OTP | `arag_orders`, `shop_otp` |
| Premium | `arag_shop_settings`, `arag_reviews` |
| Cart / Coupon | `arag_cart`, `arag_coupons` |
| ERP shop | `arag_erp_config`, `arag_erp_journal`, `arag_erp_expenses` |
| رشد | `arag_mizaj_sessions`, `arag_referrals`, `arag_referral_uses`, `arag_subscriptions`, `arag_ai_chat_log` |
| انبار (اشتراکی) | `inv_*` |

### ۷.۵ گلوگاه‌ها

- CSS premium+upgrade سنگین
- Waterfall API settings → families قبل از کاتالوگ
- Chat + AI روی first load
- ویدیو hero در صورت فعال بودن تنظیمات

### ۷.۶ پروفایل

1. فیلتر CSS: `fonts-local` + سه stylesheet فروشگاه
2. Fetch: ترتیب `shop/settings`, `families`, `cart`
3. اگر ویدیو فعال است: Media → حجم mp4

---

## ۸. Growth / سفیران

پورتال **رشدگاه ACC** — خدمات مالک + شبکه سفیران (ارجاع / کمیسیون). وضعیت فعلی: **MVP**.

### ۸.۱ Entry و قالب

| مورد | مسیر |
|------|------|
| URL | `/acc-engine/growth.php` |
| Entry | `growth.php` → `templates/growth-page.php` |
| JS | `assets/js/views/GrowthAppView.js?v=1` (~41KB) |
| CSS | `fonts-local.css?v=2` + `assets/css/base/growth-applied.css?v=1` (~15KB) |
| Controller | `includes/controllers/Growth_Controller.php` |
| Helper | `includes/helpers/growth-platform.php` |
| Install / seed | `run-growth-portal-install.php` |

بدون chat widget و بدون partial widget-boot.

### ۸.۲ Critical path — ناشناس

همهٔ منابع **لوکال / آفلاین** (بدون CDN فونت یا تصویر remote):

1. **Fonts (local):** `fonts-local.css` — Fraunces + Manrope + Vazirmatn
2. **CSS blocking:** `fonts-local` + `growth-applied.css?v=1` (~15KB)
3. **JS module:** inline `import GrowthAppView …?v=1` (~41KB) — لندینگ و داشبوردها از همین فایل
4. **API قبل از paint:** `_paint()` منتظر `GET growth/meta` می‌ماند (خدمات، اخلاق، جلسات کارگاه) → ریشه خالی تا پاسخ meta (یا catch با `services: []`)
5. **Hero / LCP:** باند گرادیان teal در CSS (`.ga-hero__media`) — **بدون JPG/WebP**
6. **Chat:** ندارد
7. **پس از login:** همان فایل؛ نقش از `growth/me` → تب مشتری / سفیر / ادمین

### ۸.۳ نقشهٔ JS/CSS

| لایه | فایل‌ها |
|------|---------|
| Shell | `templates/growth-page.php` |
| App (landing + forms + dashboards) | `GrowthAppView.js` |
| Applied UI | `growth-applied.css` |
| Config inject | `window.ACC_GROWTH_CFG` (`baseUrl`, `api`) |

### ۸.۴ Backend / API

- Controller: `Growth_Controller.php` — namespace `acc/v1`
- Helper: `Growth_Platform` (کاتالوگ خدمات، سفارش، سفیر، لید، کمیسیون، جلسات)
- Routes نمونه: `growth/meta`, `growth/orders`, `growth/ambassador/signup`, `growth/referral/validate`, `growth/sessions`, `growth/demo-users`, `growth/me`, `growth/dashboard/{customer,ambassador,admin}`, `growth/leads`, `growth/orders/{id}/confirm`

### ۸.۵ جداول (پیشوند `wp_`)

از `run-growth-portal-install.php` / `Growth_Platform::tbl()`:

| جدول | نقش |
|------|-----|
| `growth_services` | کاتالوگ خدمات و بسته‌ها (JSON) |
| `growth_orders` | سفارش خدمت + ارجاع |
| `growth_ambassadors` | سفیر / معرف + کد ارجاع |
| `growth_leads` | لید معرفی‌شده |
| `growth_commissions` | کمیسیون (تک‌سطح، dedupe) |
| `growth_sessions` | جلسات کارگاه حسابداری ۳ساعته |

نقش‌های ACL: `growth_admin`, `growth_ambassador`, `growth_referral`, `growth_customer`  
مجوزها: `growth.view`, `growth.order`, `growth.ambassador`, `growth.admin`

Option: `acc_growth_version` = `1.0`

### ۸.۶ Auth / کاربران دمو

رمز مشترک: **`Growth1234`**

| کاربر | نقش |
|-------|-----|
| `ostadowner` | مدیر (نقش `growth_admin` در صورت وجود کاربر) |
| `growth_admin` | مدیر رشدگاه |
| `growth_ambassador` | سفیر همسایه — کد دمو `SFDEMO1` |
| `growth_referral` | معرف دستگاه — کد دمو `DVDEMO1` |
| `growth_customer` | مشتری |

سفارش نمونه: `GODEMO01` (website / starter).

ورود آزمایشی از UI لندینگ؛ توکن در `sessionStorage` کلید `acc_token`. ارجاع URL: `growth.php?ref=CODE` → `sessionStorage` کلید `growth_ref`.

### ۸.۷ ویژگی‌های MVP (یادداشت)

- چهار خط خدمت: ساخت سایت، مشارکت فروش، آموزش حسابداری ۳ساعته، برندینگ محصول
- دو مسیر سفیر: همسایه / معرف دستگاه (تک‌سطح، بدون درخت)
- ثبت سفارش + اعتبارسنجی کد ارجاع + داشبورد مشتری/سفیر/ادمین
- کمیسیون فقط روی فروش تأییدشده؛ منشور اخلاق در meta
- فاکتور/پرداخت: stub (`invoice_status`) — کامل نیست
- بدون نقشه، بدون chat، بدون تصویر hero لوکال

### ۸.۸ گلوگاه‌ها

- Blank تا اتمام `growth/meta` (شبیه Election)
- تک‌فایل JS برای همهٔ صفحه‌ها (فعلاً سبک؛ با رشد MVP ممکن است نیاز به split باشد)
- فونت‌های display از `fonts-local` مشترک با Education/Shop

### ۸.۹ پروفایل

1. Anonymous hard reload → فقط `fonts-local.css`, `growth-applied.css`, `GrowthAppView.js` (+ woff2 لوکال)
2. فیلتر Fetch: `growth/meta` قبل از DOM لندینگ
3. Img: نباید درخواست Unsplash/CDN باشد — hero فقط CSS
4. Demo login → `growth/me` + dashboard مربوطه

---

## ۹. سایر entryهای ریشه

| Entry | نقش | قالب / نکته |
|-------|-----|-------------|
| `portal-accounting.php` | حسابداری چندپورتال (`?module=`) | `portal-accounting-page.php` + `PortalAccountingView.js` |
| `api.php` | REST gateway | نه UI |
| `token.php` | توکن/احراز | — |
| `acc-engine.php` | bootstrap پلاگین‌مانند | — |
| `help_accss.php`, `help_cpm.php` | صفحات راهنما | — |
| `db-test.php`, `reset-db-version.php` | ابزار | نه پورتال محصول |
| `run-*.php` | نصب/seed/تست CLI | با `C:\xampp\php\php.exe run-….php` |

---

## ۱۰. جداول مشترک / هسته ERP

همهٔ پورتال‌ها معمولاً به این‌ها تکیه می‌کنند:

- `users` / `usermeta` / `options` (پیشوند `wp_`)
- `acl_*`, `accj_*` (نقش و منو)
- `chat_*` (ویجت پشتیبانی)
- `gis_*` (Melk / Election map)
- `inv_*` (Shop / Wholesale stock در صورت اتصال)
- دفترکل عمومی حسابداری (اسناد با برچسب ماژول مثل `arag_shop`, `service_portal`, `election`, `education`) — جزئیات schema در `includes/helpers/acc-portal-accounting.php` و نصب‌های `run-*-abc-install.php` / accounting-install

برای لیست زنده:

```bash
C:\xampp\php\php.exe -r "/* یا از mysql CLI */"
```

```sql
SHOW TABLES LIKE 'wp_melk%';
SHOW TABLES LIKE 'wp_election%';
SHOW TABLES LIKE 'wp_svc_%';
SHOW TABLES LIKE 'wp_edu_%';
SHOW TABLES LIKE 'wp_wholesale%';
SHOW TABLES LIKE 'wp_arag%';
SHOW TABLES LIKE 'wp_growth%';
SHOW TABLES LIKE 'wp_chat%';
```

---

## ۱۱. نکات کلی پروفایل

برای **هر** پورتال یک بار این چک‌لیست را با Disable cache اجرا کنید:

1. **Network → Doc:** TTFB HTML (به‌خصوص `index.php` که Controllers را لود می‌کند)
2. **CSS:** کدام‌ها render-blocking هستند؛ `@import` فونت remote نباید باشد
3. **Font:** فقط `fonts-local.css` + `/acc-engine/assets/fonts/*` (woff2 لوکال)
4. **JS:** module graph (Initiator) — eager vs dynamic
5. **Img:** LCP candidate؛ فقط مسیرهای `/acc-engine/assets/img/…`؛ حجم واقعی
6. **Fetch/XHR:** آیا قبل از First Paint منتظر API می‌مانند؟
7. **Chat:** sync در HTML یا idle؟ اندازهٔ `widget.js` (~69KB)
8. **مقایسه:** همان صفحه با Block request URL روی chat؛ Network نباید `unsplash` / `fonts.googleapis` / `tile.openstreetmap` داشته باشد

### فایل‌های «اول تماشا» به ازای پورتال

| پورتال | اول این‌ها را در Network ببینید |
|--------|--------------------------------|
| ERP | `index.php` TTFB, `fonts-local.css`, `acc-app.js`, `all.min.css`, `chat-widget.css`/`widget.js` |
| Melk | `fonts-local.css`, `melk-applied.css`, `portals/melk/hero-skyline.jpg`, `MelkAppView.js` |
| Election | `public/election/meta`, `hero-majles.jpg`, `ElectionAppView.js` |
| Service | `fonts-local.css`, `service-applied.css`, `portals/service/hero-hvac.jpg`, `widget.js` |
| Wholesale | `public/wholesale/meta`, `catalog`, `widget.js` |
| Education | `fonts-local.css`, `education-applied.css`, `portals/education/hero-books.jpg`, module cascade |
| Shop | `fonts-local.css`, `shop-premium.css`, `shop-upgrade.css`, `shop/hero-poster.jpg`, `shop/settings`, `families` |
| Growth | `fonts-local.css`, `growth-applied.css`, `GrowthAppView.js`, `growth/meta` |

---

## ۱۲. منابع آفلاین / بدون اینترنت

هدف: first-load و runtime پورتال‌ها **بدون درخواست CDN/Unsplash/OSM.org/Google Fonts**.

### ۱۲.۱ الگوی «نقشه هوشمند» (مرجع کپی)

منبع حقیقت ERP:

| نقش | مسیر |
|-----|------|
| UI / منطق | `assets/js/modules/gis/sections/MapSection.js` |
| Leaflet CSS/JS | `assets/vendor/leaflet/leaflet.css`, `leaflet.js` |
| مارکرهای Leaflet | `assets/vendor/leaflet/images/*` |
| کاشی Esri (پیش‌فرض) | `assets/vendor/leaflet/tiles_esri/{z}/{x}/{y}.png` |
| کاشی Voyager/OSM | `assets/vendor/leaflet/tiles_osm/{z}/{x}/{y}.png` |
| کاشی Carto | `assets/vendor/leaflet/tiles/{z}/{x}/{y}.png` |
| کاشی خطا | `assets/vendor/leaflet/tiles/blank.png` |
| CSS پنل | `assets/css/base/gis.css` |
| Tab ERP | `assets/js/tabs/tabsConfig.js` → «🗺️ نقشه هوشمند»؛ `GisView.js` |

قالب URL کاشی (آفلاین):

```text
{pluginUrl}/assets/vendor/leaflet/tiles_esri/{z}/{x}/{y}.png
```

با `pluginUrl = /acc-engine` (از `ACC_CONFIG.pluginUrl` یا fallback). گزینه‌ها: `minZoom: 10`, `maxZoom: 19`, `maxNativeZoom: 16`, `errorTileUrl: …/blank.png`.

پوشش فعلی بستهٔ کاشی: **شیراز / فارس** (حدود z10–16). برای شهر دیگر باید بستهٔ PNG هم‌نام زیر `tiles_esri` (یا `tiles_osm` / `tiles`) اضافه شود.

کپی همین الگو در پورتال‌ها:

| پورتال | فایل |
|--------|------|
| Election | `assets/js/views/ElectionMapView.js` |
| Education | `assets/js/views/education/EducationMapView.js` + `includes/helpers/education-gis.php` (`tile_url`) |
| ERP دیگر | `UniversalMapSection.js`, `HrMapSection.js`, `LocationPicker.js` (از قبل آفلاین) |

**دانلود اختیاری کاشی (ادمین، فقط وقتی آنلاین):** `includes/controllers/TileProxy_Controller.php` — endpointهای `/tiles/download` و `/tiles/status` از OSM.org برای **پر کردن کش** استفاده می‌کنند؛ runtime نقشهٔ کاربر نباید به OSM.org برود.

### ۱۲.۲ تصاویر و فونت

- فونت: `assets/css/base/fonts-local.css` + `assets/fonts/*`
- Heroes/stories: `assets/img/portals/<portal>/` و `assets/img/election/`, `assets/img/shop/`
- Growth: بدون تصویر hero — گرادیان CSS در `growth-applied.css`
- QR گزارش سرویس: `assets/vendor/qrcode/qrcode.min.js` (نه api.qrserver.com)

### ۱۲.۳ استثناهای عمدی (سرور / کاربر، نه first-load UI)

| مورد | توضیح |
|------|--------|
| SMS (Kavenegar / Melipayamak / Ghasedak) | `includes/helpers/acc-sms.php` — API خارجی هنگام ارسال |
| AI (OpenAI-compatible) | تنظیمات `acc_shop_ai_base_url` — فقط وقتی AI فعال است |
| درگاه پرداخت | URL درگاه هنگام checkout |
| لینک‌های واتساپ/تلگرام/اینستاگرام در chat | کلیک کاربر؛ نه بارگذاری منبع |
| `TileProxy` bulk download | ابزار ادمین برای پر کردن کش کاشی |
| اسکریپت‌های `run-*-seed.php` | ممکن است هنگام seed از Unsplash دانلود کنند؛ runtime پورتال نه |

---

## ۱۳. فهرست مسیر تصاویر

مسیرهای وب نسبت به ریشهٔ سایت (`/acc-engine/…`). همهٔ موارد زیر **لوکال** هستند؛ remote باقی‌مانده در first-load پورتال‌ها: **ندارد** (TODO: —).

### ۱۳.۱ Melk

| کاربرد | مسیر |
|--------|------|
| Hero LCP + preload | `/acc-engine/assets/img/portals/melk/hero-skyline.jpg` |
| Story band | `/acc-engine/assets/img/portals/melk/story-home.jpg` |

منبع CSS: `assets/css/base/melk-applied.css` · preload: `templates/melk-page.php`

### ۱۳.۲ Election

| کاربرد | مسیر |
|--------|------|
| Hero LCP | `/acc-engine/assets/img/election/hero-majles.jpg` |
| Story | `/acc-engine/assets/img/election/story-majles.jpg` |
| عکس کاندیدا (API/DB) | `/acc-engine/assets/img/election/azizi.jpg` |
| روی دیسک (آماده / فعلاً در CSS لندینگ استفاده نشده) | `hero-iran.jpg`, `story-iran.jpg`, `story-shiraz.jpg` |

منبع CSS: `assets/css/base/election-applied.css`

### ۱۳.۳ Service / HVAC

| کاربرد | مسیر |
|--------|------|
| Hero LCP | `/acc-engine/assets/img/portals/service/hero-hvac.jpg` |
| Story / IQ visual | `/acc-engine/assets/img/portals/service/story-tech.jpg` |
| Case media | `/acc-engine/assets/img/portals/service/story-building.jpg` |

منبع CSS: `assets/css/base/service-applied.css`

### ۱۳.۴ Education

| کاربرد | مسیر |
|--------|------|
| Hero LCP | `/acc-engine/assets/img/portals/education/hero-books.jpg` |
| Story | `/acc-engine/assets/img/portals/education/story-library.jpg` |

منبع CSS: `assets/css/base/education-applied.css`

### ۱۳.۵ Shop (Arag)

| کاربرد | مسیر |
|--------|------|
| Hero CSS (applied) + poster پیش‌فرض | `/acc-engine/assets/img/shop/hero-poster.jpg` |
| Story band | `/acc-engine/assets/img/portals/shop/story-herbs.jpg` |
| بطری‌های کاتالوگ | `/acc-engine/assets/img/shop/bottles/{golab,bidmeshk,kasni,naana,nastaran,bahar,avishan,zafaran}.jpg` |

تنظیمات DB ممکن است همان مسیرهای لوکال را در `hero_poster_url` / image variants نگه دارد (`includes/helpers/arag-shop.php`).

### ۱۳.۶ ERP / Home / Wholesale / Growth

| پورتال | تصاویر first-load |
|--------|-------------------|
| ERP Home | بدون عکس LCP — گرادیان CSS در `home-applied.css` / `landing.css` |
| Wholesale | بدون عکس LCP سنگین روی لندینگ |
| Growth | بدون عکس LCP — گرادیان teal در `growth-applied.css` (`.ga-hero__media`) |

### ۱۳.۷ کاشی نقشه (تصاویر رستر)

```text
/acc-engine/assets/vendor/leaflet/tiles_esri/{z}/{x}/{y}.png
/acc-engine/assets/vendor/leaflet/tiles_osm/{z}/{x}/{y}.png
/acc-engine/assets/vendor/leaflet/tiles/{z}/{x}/{y}.png
/acc-engine/assets/vendor/leaflet/tiles/blank.png
/acc-engine/assets/vendor/leaflet/images/marker-icon.png
…
```

---

## پیوست — نگاشت سریع URL → فایل

```
/acc-engine/                 → index.php → templates/spa.php
/acc-engine/melk.php         → templates/melk-page.php
/acc-engine/wholesale.php    → templates/wholesale-page.php
/acc-engine/election.php     → templates/election-page.php
/acc-engine/service.php      → templates/service-page.php
/acc-engine/education.php    → templates/education-page.php
/acc-engine/shop.php         → templates/shop-page.php
/acc-engine/growth.php       → templates/growth-page.php
/acc-engine/platform.php     → templates/platform-page.php
/acc-engine/account.php      → templates/account-page.php
/acc-engine/portal-accounting.php → templates/portal-accounting-page.php
```

---

*پایان سند — برای به‌روزرسانی: قالب `templates/*-page.php` و query `?v=` را دوباره بخوانید و تاریخ بالای سند را عوض کنید.*
