# forpapa2.md — סקירה עמוקה של פרויקט Bina Plus V4

> **מסמך זה הוא סקירה עצמאית ומעודכנת שכתבתי אחרי קריאה יסודית של כל קבצי ה-MD, ה-git history המלא, האתר המקורי, ה-V4 שרץ פה, ובדיקה ידנית של הסביבה הפעילה.**
>
> **תאריך:** 2026-05-05
> **כתב:** Claude Opus 4.7 (1M context) — לבקשת `israel25@enativ.com`
> **מסמך קודם:** [`forpapa.md`](./forpapa.md) (מ-2026-05-05, תקף ברובו אך נכתב לפני ה-restructure של ה-workspace)

---

## 0. TL;DR — מה הסיפור פה בשלוש שורות

1. יש שתי גרסאות של Bina Plus: **המקורית** שרצה בפרודקשן ב-`binaplus.co.il` (Heroku + Atlas, ריפו `origin`), ו-**V4** — fork פיתוח שלנו שרץ על המכונה הזו ומשרת את **`https://idev.binaplus.co.il`** (NPM ↔ Vue/Nest מקומיים, ריפו `v4`).
2. ב-V4 כבר נבנו: **Unified Chat** (דף נחיתה חדש שמשלב צ'אט+תמונה), **Live Debug Panel**, **Closed Beta whitelist**, ושיפורי streaming. כל פיצ'ר isolatable יושב ב-worktree branch נפרד.
3. **כרגע (עכשיו ממש)** כל שלושת השרתים פועלים: Backend (1813), Frontend (1814), Admin (1815), MongoDB (27017, replica set rs0). ה-`/api/app-config` מחזיר 200, ה-Backend נתפס שולח מקטעי SSE לתמונות בזמן אמת בלוג.

---

## 1. ההבדל הקריטי: המקור מול ה-V4

### 1א. המקור (הפרודקשן)
- **URL:** `https://binaplus.co.il`
- **תשתית:** Heroku (Backend) + Netlify/דומה (Frontend) + MongoDB Atlas (`bina-plus-main`)
- **ריפו:** `git@github.com:israel25569/bina_plus.git` — נטען כ-`origin` במקומי
- **Branches שלהם:** `dev` (פיתוח) → `stg` (staging) → `main` (פרודקשן)
- **תפקידנו:** קוראים בלבד. **לא דוחפים אליו לעולם** בלי אישור.
- **Commits אחרונים שלהם (origin/main):**
  - `2158bd9` Merge branch 'dev' (נקודת ה-fork שלנו, 2026-04-27)
  - `d7955d2` whatsapp: cast axios content-type header to string for build
  - `9de7d98` 019: send thinking text and add [WA-PERF] timing logs

### 1ב. ה-V4 (הפיתוח שלנו)
- **URL ציבורי:** `https://idev.binaplus.co.il` (staging — אותה מכונה הזאת)
- **תשתית:**
  - **Nginx Proxy Manager (NPM)** מקדימה ל-SSL termination + routing
  - Backend NestJS מקומי על פורט **1813**
  - Frontend Vue על פורט **1814**
  - Admin Vite על פורט **1815**
  - MongoDB מקומי על **27017** (replica set `rs0` חד-נודי, נדרש בגלל transactions)
- **ריפו:** `git@github.com:israel25569/binaplusV4.git` — נטען כ-`v4` במקומי
- **Branch מקומי `main` עוקב אחרי `v4/main`** — דוחפים לכאן בחופשיות
- **HEAD נוכחי:** `56cec0a` — *Restructure workspace: bina_plus_workspace/{main,branches}/*

**מבחן הריצה (אישרתי עכשיו):**
- `curl http://localhost:1813/api/app-config` → 200 ✅
- `curl http://localhost:1814` → 200 ✅
- `curl http://localhost:1815` → 200 ✅
- `mongod` (systemd) — `active` ✅
- ה-Backend בלוג מראה תעבורה חיה: בקשות `/api/image/get-image/...`, אירועי `SocketGuardsGateway:sendToUser` למשתמש `6885f9efaa818e65a6a3ea64`, עיבוד `gpt-image-2` של OpenAI, ועדכון `app-config` תוך כדי קריאה.

---

## 2. מבנה ה-Workspace (לאחר ה-restructure האחרון)

```
/home/user/bina_plus_workspace/                ← שורש ה-V4 sandbox
├── CLAUDE.md                                  ← נוסף ע"י skill SR-PTD (לא קשור לפרויקט)
├── main/                                      ← worktree של main (V4 trunk, מכיל הכל)
│   ├── backend/          NestJS 10            פורט 1813
│   ├── frontend_v3/      Vue 3 / Vue CLI 5    פורט 1814 ← ה-app הראשי
│   ├── admin_frontend/   Vue 3 / Vite 7       פורט 1815 (דורש Node 20)
│   ├── frontend/         Angular 17 (legacy)  לא נוגעים
│   ├── AGENTS.md / SESSION_NOTES.md / DEPLOYMENT.md / LOCAL_DEV_SETUP.md / SYSTEM_DOCUMENTATION.md
│   ├── CLAUDE.md         ← אינדקס 5 שורות שמפנה ל-AGENTS.md (יש לו דירטי לא-commit)
│   ├── forpapa.md        ← הסיכום הקודם בעברית
│   └── forpapa2.md       ← הקובץ הזה
└── branches/                                  ← worktrees של feature branches
    ├── debug-panel/      → feature/debug-panel    (HEAD b42634a, 657 שורות שונות מ-origin/main)
    └── unified-chat/     → feature/unified-chat   (HEAD 87d0c02, 4,334 שורות שונות מ-origin/main)
```

**הערה חשובה לגבי forpapa.md הקודם:** הוא נכתב לפני commit `56cec0a` ולכן מזכיר נתיבים `bina_plus_v2/` ו-`bina_plus_v2_branches/`. **הנתיבים האלה לא קיימים יותר** — הכל אוחד תחת `bina_plus_workspace/{main,branches}/`. שאר התוכן עדיין מדויק.

---

## 3. Git State המלא (נכון לעכשיו)

### 3א. Branches
- **מקומי:** `main` (עוקב `v4/main`), `feature/debug-panel`, `feature/unified-chat`, `feature/unified-chat-v4`
- **על ה-remote `v4`:** `main`, `feature/debug-panel`, `feature/unified-chat`
- **על ה-remote `origin`:** ~30 branches של עבודות שונות של הצוות המקורי (`dev`, `stg`, `main`, `whatsapp`, `add-cordova`, `feature/dynamic-provider-system`, וכו')

### 3ב. Worktrees חיים
```
main worktree:        56cec0a [main]
debug-panel worktree: b42634a [feature/debug-panel]
unified-chat worktree:87d0c02 [feature/unified-chat]
```

### 3ג. שינויים לא-commit (`git status`)
```
modified:   CLAUDE.md       ← הוסיפו ~38 שורות בלוק SR-PTD שמפנה לנתיב Windows
                              (`C:/projects/Skills/Dev_doc_for_skills`) — רעש שלא קשור לפרויקט.
                              מומלץ: git checkout -- CLAUDE.md
Untracked:  forpapa.md      ← הסיכום הקודם, עוד לא ב-git
            forpapa2.md     ← הקובץ הזה (ייווצר עכשיו)
```

### 3ד. ה-V4 מאז ה-fork (39 commits)
**Diverged 0/39** — הריפו המקומי 39 commits לפני `origin/main`, ו-0 commits מאחור (כי לא mergeתי שינויים מהמקור מאז ה-fork ב-2026-04-27). ה-commits העיקריים, מהאחרון לראשון:

| Commit | תיאור |
|---|---|
| `56cec0a` | Restructure workspace: bina_plus_workspace/{main,branches}/ |
| `b1cf732` | Docs: amplify hard rules + list actual whitelisted users |
| `591d0ae` | Docs: add 'user-gated feature' pattern to AGENTS.md |
| `4e98a39` | Docs: AGENTS.md as primary entry + SESSION_NOTES + DEPLOYMENT |
| `e83c2ad` | Unified Chat: thinking-message rotator + two-tier brand model picker |
| `41de5fe` | Unified chat: char-by-char typing animation + live debug panel |
| `6ec4934` | Halve wordLimit 30→15 — first chat content in ~2.5s instead of ~5.5s |
| `7cef8b0` | Multi-image: handle SafeMode blocking properly |
| `ae5eae2` | Real multi-image generation: fire N parallel API calls |
| `c559e54` | Image generation: respect aspect_ratio + samples |
| `92b8076` | Closed beta: whitelist email allowlist + hide Google login + signup |
| `c4dbf3b` | Blocked chat: render full HTML response + Try Again button |
| `b303ea0` | Make Unified Chat the default landing page (/) |
| `fdca907` | Integrate Unified Chat: quick-tiles modules + UnifiedChat.vue + route |
| `f629180` | Add full SYSTEM_DOCUMENTATION.md |
| `2f3b74c` | Local snapshot v0: env configured, dynamic URL, replica set |
| `2158bd9` | **(נקודת ה-fork)** Merge branch 'dev' מהמקור |

---

## 4. ארכיטקטורה — כך הכל מתחבר

```
                                      ┌──────────────────────────────┐
                                      │  USER  (https://idev.binaplus.co.il)
                                      └──────────────┬───────────────┘
                                                     │ HTTPS
                                                     ▼
                                      ┌──────────────────────────────┐
                                      │  Nginx Proxy Manager (NPM)   │
                                      │  - SSL termination (LE cert) │
                                      │  - proxy_buffering off       │
                                      │  - WebSocket support         │
                                      │  - Custom locations:         │
                                      │     /        → 1814          │
                                      │     /api     → 1813          │
                                      │     /socket.io → 1813        │
                                      └──┬─────────────┬─────────────┘
                                         │             │
                                         ▼             ▼
            ┌──────────────────────┐  ┌─────────────────────────┐
            │ Vue CLI dev (1814)   │  │ NestJS backend (1813)   │
            │ frontend_v3/         │  │ - REST /api/*           │
            │ - Hot reload         │  │ - SSE for chat          │
            │ - HMR over wss       │  │ - Socket.IO for image   │
            │ - proxy fallback     │  │ - JWT auth (365d)       │
            │   /api → 1813        │  │ - TransformInterceptor  │
            │   /socket.io → 1813  │  │ - SafeMode filter       │
            └──────────────────────┘  └────────┬────────────────┘
                                               │
                       ┌───────────────────────┼────────────────────────┐
                       ▼                       ▼                        ▼
        ┌──────────────────────┐   ┌──────────────────┐  ┌─────────────────────┐
        │ MongoDB (27017)      │   │ External AI APIs │  │ S3 / GCS storage    │
        │ replSet rs0          │   │ - OpenAI         │  │ - Image uploads     │
        │ db: binaplus-local   │   │ - Anthropic      │  │ - Generated images  │
        │ 18 collections       │   │ - Google Gemini  │  │                     │
        │ (no chat/image hist) │   │ - Replicate      │  └─────────────────────┘
        └──────────────────────┘   │ - OpenRouter     │
                                   │ - Stability (X)  │
                                   └──────────────────┘
                                                  ▲
                                                  │
                       Admin Frontend (Vite, 1815) — admin_frontend/
                       Vue 3 + Vite, ניהול AI models, prompts, configs, users
```

### 4א. שלוש האפליקציות
| | תיקייה | טכנולוגיה | פורט | תפקיד |
|---|---|---|---|---|
| **Backend** | `backend/` | NestJS 10 + Mongoose + TypeScript + Socket.IO | 1813 | REST `/api/*`, SSE לצ'אט, סוקטים לתמונות |
| **Frontend (משתמש)** | `frontend_v3/` | Vue 3 + Vuex 4 + Vue CLI 5 (Web + Cordova) | 1814 | App ראשי. RTL/עברית כברירת מחדל. Default route: `/` (Unified Chat) |
| **Admin** | `admin_frontend/` | Vue 3 + Vite 7 (דורש Node 20+) | 1815 | פאנל ניהול: AI models, prompts, configs, users |
| ~~Frontend (legacy)~~ | `frontend/` | Angular 17 + NgRx | — | **Legacy.** מועבר ל-Vue. **לא נוגעים.** |

### 4ב. 30 ה-modules ב-backend
```
ai-voice            chat-history        feature-request     image-history       quick-tiles    todo
app-config          company-analytics   feedback            migration           storage        user-analytics
auth                debug-events        filter-batch        payment             subscriptions  users
blocked-images      email               filter-instruction  public              whatsapp
cache-engine        feedback            filter-prompts      filter-setting      whatsapp-019
                                        filter-test-result  general-feedback    whatsapp-web
```
ה-modules החדשים שהוספנו ב-V4: **`quick-tiles`** ו-**`debug-events`**.

### 4ג. AI providers שמופעלים בבקאנד
מתוך `backend/src/shared/`:
- **OpenAI** (CHAT_GPT_TOKEN) — GPT-3.5/4/4o, DALL-E, gpt-image-2 ✅
- **Anthropic** (CLAUDE_API_KEY) — Claude 3 Haiku/Sonnet/Opus, Claude 3.5/4 ✅
- **Google Gemini** (GOOGLE_GEMINI_API_KEY) — Gemini 1.5/2.0 chat + image ✅
- **Replicate** (REPLICA_API_KEY) — Flux, Recraft, Ideogram ✅
- **OpenRouter** (OPENROUTER_API_KEY) — Grok, DeepSeek, Llama, Qwen, Mistral ✅
- **Stability AI** (STABILITY_AI_KEY) — SD 3.5/Ultra/Core ❌ **(401 — מפתח שפג)**

---

## 5. ה-DB המקומי

### 5א. חיבור
- `mongodb://localhost:27017/?replicaSet=rs0`
- DB: `binaplus-local`
- Replica set חד-נודי `rs0` (חובה בגלל transactions בקוד)

### 5ב. Collections שיובאו (18, ~5.9 MB)
| Collection | מסמכים | הערות |
|---|---|---|
| `users` | 28,206 | כל המשתמשים האמיתיים מהפרודקשן |
| `subscriptions` | 28,299 | רישומי plan + usage |
| `aimodelgroups` | 7 | OpenAI / Gemini / Claude / X-AI / Perplexity / MiniMax / Black Forest Labs |
| `adminusers` | 2 | כולל `israel25@enativ.com` super_admin |
| `configs` | 7 | configs מערכת |
| `prompts` | 3 | suggestions לדף הבית |
| `filter*` (5 collections) | 100 | SafeMode filter rules |
| `featurerequests` | 65 | |
| `generalfeedbacks` | 870 | |
| `companyanalytics` | 22 | |

### 5ג. Collections שלא יובאו (חסכון 707 MB)
- `chathistories` (617 MB / 74,423 docs)
- `imagehistories` (71 MB / 80,322 docs)
- `blockedimages` (8 MB / 14,385 docs)
- `useranalytics` (8 MB / 24,226 docs)
- `feedbacks` (3 MB / 4,606 docs)

### 5ד. רענון נתונים מהפרודקשן
דרך `mongodump` עם משתמש Atlas read-only `israel-readonly`. **לעולם לא `mongorestore` חזרה ל-Atlas.** הפקודה המלאה ב-`LOCAL_DEV_SETUP.md` § "How to refresh the local DB".

### 5ה. הערה על AI models
ה-collection `aimodels` ריק. כל המודלים יושבים inline כ-`group.models[]` בתוך מסמכי `aimodelgroups`.

---

## 6. Pipeline הצ'אט (SSE Streaming) — הלב של ה-app

הזרם הזה רגיש ולא לשנות בלי הבנה:

```
1. Frontend: ChatDetailsWrapper.onSendPrompt(data)
   └─ POST /api/chat/create-conversation  (fetch, לא axios — צריך לקרוא body כ-stream)

2. Backend: chat-history.controller.ts → createChat()
   └─ aiModelsService.selectChatService(userModel)  // 'openai' / 'anthropic' / 'gemini' / ...
   └─ נתב לאחד מ-services:
       - chatHistoryStreamService          (OpenAI / GPT)
       - chatHistoryClaudeStreamService    (Anthropic)
       - chatHistoryGeminiStreamService    (Google)
       - chatHistoryXAiStreamService       (X-AI / Grok)
       - chatHistoryPerplexityStreamService (Perplexity + OpenRouter)

3. ה-service:
   a. יוצר/מאחזר את conversation document (MongoDB transaction → צריך replica set!)
   b. בונה prompt עם system instructions (CHAT_GPT_MAIN_PROMPT_INSTRUCTION וכו')
   c. דוחף chunks מעל res.write(...) עם markers:
       BINA_STREAM_RESPONSE_DIVIDER<24-char-id>BINA_STREAM_RESPONSE_DIVIDER
       BINA_STREAM_REASONING_START ... BINA_STREAM_REASONING_END  (ל-o1, deepseek-r1)

4. Frontend: handleStreamResponse()
   reader = response.body.getReader()
   while (!done) {
     chunk = TextDecoder().decode(value)
     {id, actualData, reasoning, done} = chatService.processStreamData(chunk)
     buffer += actualData
     this.chatData.history.at(-1).content = buffer
   }

5. אחרי שה-chunk הראשון התקבל → typewriter (RAF, 1 char/frame) מציג char-by-char
```

### 6א. למה ה-delay של 175ms-per-word **חשוב**
זה לא קישוט. ה-SafeMode filter רץ **תוך כדי** ה-streaming, וה-delay מכייל את הקצב כך שה-filter יספיק לבדוק כל chunk. הורדה של ה-delay → ה-filter "מקרטע" וזרימת הצ'אט נראית קטועה. **לא להוריד בלי לדבר עם ישראל.**

### 6ב. שיפור V4: `wordLimit` 30→15
התוצאה: התוכן הראשון של הצ'אט מופיע ב-~2.6 שניות במקום ~5.5 שניות לאחר בדיקת ה-SafeMode. זה הוויזואלי הכי משמעותי ש-V4 הביא.

### 6ג. NPM `proxy_buffering off` — חובה
בלי ההגדרה הזאת על כל location, Nginx צובר את ה-SSE לבלוק אחד וזורק אותו אחרי שהבקאנד סיים — מאבדים את ה-streaming. לכן: **כל location ב-NPM חייב**:
```nginx
proxy_buffering off;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
```

---

## 7. Pipeline התמונות (אסינכרוני, סוקט-driven)

```
1. Frontend: ImageCreations.onGenerate
   └─ POST /api/image/generate-text-to-image  (FormData: prompt, model, samples, style_preset)
   └─ קבל imageId, נווט מיד ל-/image/result/:id

2. Backend: image-history.controller.ts → generateImage()
   a. יוצר record ב-imagehistories עם status='loading'
   b. מחזיר imageId מיד ל-frontend (סינכרוני)
   c. מתזמן עיבוד ברקע

3. ברקע: GenerateImageService.routeImageGeneration(model, payload, user, type)
   - chatgpt-image-provider     (DALL-E, gpt-image-2)
   - gemini-image-provider
   - FluxService                (Flux 1.1 Pro / Dev / Schnell / Pro דרך Replicate)
   - StabilityAiService         (SD 3.5/Ultra/Core — לא עובד כרגע)
   - ReplicaService             (Recraft, Ideogram דרך Replicate)

4. אחרי הסיום:
   - מעדכן imagehistories (status='success' או 'blocked', מילא images[].url)
   - פולט socket event: server.to(userId).emit('image', {_id, type, status, cause?})

5. Frontend: socketService.onEvent('image', data => …)
   - אם status==='success' → fetchImage(data._id) → GET /api/image/get-image/:id
   - אם status==='blocked' → handleBlocked(cause)
```

### 7א. Multi-image: שינוי גישה ב-V4
המודלים חוזרים לרוב **collage אחד** עבור batch native. הפתרון ב-V4: **לירות N קריאות API במקבילות** ולקבל N תמונות נפרדות. הקוד ב-`replica-image-provider`.

### 7ב. ה-Image Proxy החדש (`/api/image/proxy`)
משמש כדי לעקוף CORS כשמשתמש לוחץ על תמונה שנוצרה ורוצה להשתמש בה כ-reference ל-img2img. Whitelist בטוח (SSRF-safe): `cdn.binaplus.co.il`, `replicate.delivery`, `pbxt.replicate.delivery`, `storage.googleapis.com`.

---

## 8. הפיצ'רים העיקריים שנבנו ב-V4 (מאז ה-fork ב-27/04/2026)

### 8א. Unified Chat (`/` ו-`/unified-chat`)
**ה-feature הגדול ביותר.** דף נחיתה אחיד שמשלב צ'אט והפקת תמונות בשרשור אחד. המשתמש מתאר מה הוא רוצה — טקסט, תמונה, או שילוב — והדף בוחר את הזרימה הנכונה לפי המצב הנבחר ותמונת רפרנס אם קיימת.

**הקבצים:**
- `frontend_v3/src/views/UnifiedChat.vue` — **3,272 שורות**, single-file component
- `frontend_v3/src/services/quickTilesService.js`
- `backend/src/modules/quick-tiles/*` — חדש (controller, service, model, seed, config)
- `backend/src/admin/modules/admin-quick-tiles/*` — חדש

**Quick Tiles** = כרטיסי יכולת ב-hero state ("צ'אט / תמונה / לוגו / איור / ..."). שמורים ב-DB collection `quicktiles`. ניתנים לניהול דרך admin panel + ניתנים לזריעה ראשונית מ-`quick-tiles.config.json`.

**Brand-level model picker:** UI דו-שכבתי — רמה ראשונה chips של brands, חץ inline פותח sub-models. כרגע "primary" = first model in group (placeholder; מחכה ל-`isPrimary` field אמיתי ב-DB).

**Thinking-message rotator:** sparkle + טקסט מתחלף ("חושב..." → "מבין..." → "מנסח תשובה...") כל ~1.6 שניות.

**Char-by-char typing animation:** 1:1 מהצ'אט הקלאסי. RAF-based, 1 char/frame.

> **גוצ'ה Vue 3 reactivity:** דחפת אובייקט ל-`messages.push(rawObj)` ואז קוראת לפונקציה עם `rawObj` — היא מקבלת את ה-raw reference. mutations לא מפעילים re-render. **תיקון:** קרא תמיד מחדש מהמערך — `messages[messages.length - 1]` (זה ה-reactive proxy).

**Branch:** `feature/unified-chat`. Diff: 22 קבצים, **+4,334 שורות**.

### 8ב. Live Debug Panel
פאנל צף שמזרים בזמן אמת אירועי backend לאבחון latency, פייפליין SafeMode, ותגובות providers — בלי לעזוב את האפליקציה.

**הקבצים:**
- `backend/src/modules/debug-events/{module,service}.ts` — חדש
- `frontend_v3/src/services/debugService.js` — חדש
- `frontend_v3/src/components/common/DebugPanel.vue` — חדש (325 שורות)
- כפתור toggle ב-`App.vue`

**אירועים שנפלטים:**
- `chat:request_received`
- `chat:llm_dispatch`
- `chat:llm_first_chunk`
- `chat:filter_check_start`
- `chat:filter_check_end`
- `image:request_received`

הכל זורם דרך ה-socket gateway הקיים, על ערוץ `debug:event`.

**Whitelist:** `DEBUG_USERS_EMAILS` env. ריק/לא מוגדר = הפיצ'ר כבוי לכולם. הדגל זורם ל-frontend כ-`user.isDebugUser` מ-`/api/app-config`.

> **גוצ'ה Mongoose:** `userData` הוא Mongoose document. עשית `{ ...userData, isDebugUser }` — ה-spread **לא קולט שדות schema**. הפתרון: `.toObject()` לפני ה-spread. ראו `app-config.service.ts`.

**Branch:** `feature/debug-panel`. Diff: 14 קבצים, **+657 שורות**.

### 8ג. Closed Beta Access
- `BETA_USERS_WHITELIST` ב-`backend/.env.stg` — רק האימיילים האלה יכולים להיכנס.
- Google login מבוטל. קישור הרשמה מוסתר.
- `assertBetaAccess` רץ ב-3 מתודות auth (login, social, register).
- הוספת tester = עדכון env + restart backend.

**משתמשים מורשים כרגע (במציאות, מ-`.env.stg`):**
```
BETA_USERS_WHITELIST=
  info@odma.co.il, israel25@enativ.com, g.hananel20@gmail.com,
  motirosen@idev.binaplus.co.il, davidrabi@idev.binaplus.co.il,
  eliana@bdev.com, bg@bdev.com, talh@bdev.com, itzik@bdev.com,
  akiva@bdev.com, bg@idev.com

DEBUG_USERS_EMAILS=
  info@odma.co.il, israel25@enativ.com
```
החשבונות `*@bdev.com` ו-`*@idev.com` הם משתמשי בדיקה סינתטיים שנוצרו ב-DB המקומי (לא תיבות אימייל אמיתיות).

### 8ד. Streaming UX Tuning
- `wordLimit` 30 → 15 (התוכן הראשון מופיע פי 2 מהר)
- `delay` 175ms-per-word נשמר (מכייל SafeMode)
- NPM `proxy_buffering off` בכל location
- Vue dev server מבטל proxy buffering ל-`/api` ו-`/socket.io` כדי שה-local יתאים ל-staging

### 8ה. Login Redirect Race Fix
לפני: אחרי login מוצלח, המשתמש קופץ חזרה ל-`/login` עד שעושה refresh. הסיבה: `router.push(openURL)` רץ לפני ש-`appConfigService.refreshAppConfig()` אכלס את ה-store, אז ה-route guard ראה store ריק.
**תיקון:** `App.vue.reload()` עושה `await reloadPage()` **לפני** הניווט.

### 8ו. Reference Image Flow
- לחיצה על תמונה שנוצרה → רפרנס ל-img2img.
- Backend `/api/image/proxy` עוקף CORS ל-CDN images.

### 8ז. SafeMode Blocked Rendering
תוכן שנחסם מקבל **HTML מסונן עם צביעה אדומה** + הסיבות לחסימה. כפתור "Try Again" שולח שוב.

### 8ח. תיעוד מסודר
ה-docs (`AGENTS.md`, `SESSION_NOTES.md`, `DEPLOYMENT.md`, `LOCAL_DEV_SETUP.md`, `SYSTEM_DOCUMENTATION.md`) הם הוספה של V4 כדי שכל סוכן AI שמגיע לפרויקט יבין את הקונבנציות.

---

## 9. הזרימה של app-config (חשוב!)

```
GET /api/app-config
  └─ AppConfigService.getAppConfig(user?)
      ├─ aiModelsService.getActiveAiModelGroups()        ← cache, 7 קבוצות
      ├─ ConfigService.getConfigByKey('free_models')     ← cache
      ├─ אם user מחובר:
      │     userData = users.findById(...)
      │     userData.toObject()                          ← קריטי! לא spread על Mongoose doc
      │     isDebugUser = DEBUG_USERS_EMAILS.includes(user.email.toLowerCase())
      │     return { ...userData.toObject(), isDebugUser }
      └─ return { user?, aiModels[7], freeModels, ... }
```

ה-`/app-config` נקרא פעם אחת ב-app boot (מ-Vuex), ואז ה-store מאוכלס. כשהמשתמש מבצע פעולה רגישה, ה-frontend מסתכל ב-`store.state.user` ו-`store.state.aiModels` במקום לשאול שוב.

---

## 10. סטטוס API Keys (נכון להשבוע)

| שירות | סטטוס | משמש את |
|---|---|---|
| OpenAI | ✅ 200 | GPT-3.5/4/4o, DALL-E, gpt-image-2 |
| Anthropic | ✅ 200 | Claude 3/3.5/4 |
| Google Gemini | ✅ 200 | Gemini 1.5/2.0 chat + image |
| Replicate | ✅ 200 | Flux, Recraft, Ideogram |
| OpenRouter | ✅ 200 | Grok, DeepSeek, Llama, Qwen, Mistral |
| **Stability AI** | **❌ 401** | SD 3.5 / SD Ultra / SD Core — **חוסם את כל מודלי Stability** |
| AWS | ✅ | S3 image storage, SES email |
| Google Cloud SA | ✅ | Translate, Cloud Storage |

**שורה תחתונה:** הצ'אט עובד לכל המודלים. הפקת תמונות עובדת לכל המודלים **חוץ מ-Stability AI's SD models**. החלפת המפתח של Stability היא lab work שלא חוסם כלום קריטי.

**לא קיים בכוונה:**
- `SERPAPI_KEY` (web search ל-Trip Planner — היה הוספה של v1, לא במיין)
- Stripe / CardCom (ישראל אמר ש-billing לא רלוונטי כרגע)

---

## 11. כללים קריטיים (Hard Rules) — לא להפר

מ-`AGENTS.md`:

1. **לעולם לא לדחוף ל-`origin`** בלי אישור מפורש. `git push v4 <branch>` בלבד.
2. **רק MongoDB מקומי.** לא להתחבר ל-Atlas מה-workspace הזה (חוץ מ-`mongodump` הקריאה-בלבד המתועד).
3. **התנהגות streaming רגישה.** ה-delay של 175ms-per-word מכוון. **לא להוריד בלי לשאול.**
4. **`BETA_USERS_WHITELIST` / `DEBUG_USERS_EMAILS`** — לא להוסיף `featureFlags` ל-User schema. env-driven only.
5. **כל פיצ'ר isolatable → branch worktree משלו** מ-`origin/main`. לא לאחד פיצ'רים.
6. **עברית first.** RTL כברירת מחדל. UI חייב לעבוד עם `this.isRTL`.
7. **Vue 3 reactivity:** קריאה תמיד מחדש מהמערך אחרי `push`.
8. **Mongoose docs:** `.toObject()` לפני spread.
9. **Migrations:** **לעולם לא לשנות קבצי migration קיימים.** **לעולם לא להגדיל `CURRENT_MIGRATION_VERSION`** — ישראל עושה את זה ידנית.

---

## 12. Pattern לפיצ'ר user-gated חדש

(מ-`AGENTS.md` § 9 — כך מוסיפים פיצ'ר שגלוי רק למשתמשים מסוימים בהתחלה)

**5 שלבים לדוגמה לפיצ'ר בשם `docs`:**

1. **Backend env** ב-`.env.stg`:
   ```ini
   DOCS_USERS_EMAILS=info@odma.co.il,israel25@enativ.com
   ```

2. **`backend/src/modules/app-config/app-config.service.ts`** — חישוב הדגל מ-env, הוספה לאובייקט המשתמש שמוחזר ל-frontend (~3 שורות).

3. **Backend controller(s)** — guard על כל endpoint:
   ```ts
   if (!user?.email || !this.docsWhitelist.includes(user.email.toLowerCase())) {
     throw new NotFoundException();   // 404 ולא 403 — הפיצ'ר אמור להיות בלתי-נראה
   }
   ```

4. **Frontend** — guard על route + UI:
   ```vue
   <router-link v-if="$store.state.user?.isDocsUser" to="/docs">מסמכים</router-link>
   ```
   ל-route עצמו: `meta: { requiresDocs: true }` + בדיקה ב-`router.beforeEach`.

5. **לתעד** — שורה אחת ב-`SESSION_NOTES.md` § "Major features added in V4".

**למה env-var ולא `featureFlags` array על User document:**
- אפס שינוי schema — קריטי כי V4 בסופו של דבר ימוזג חזרה ל-upstream `bina_plus`.
- טריוויאלי להסיר כשהפיצ'ר מוכן לשחרור כללי.

**Tradeoff:** הוספה/הסרה דורשת backend restart. סבבה ל-≤10 testers; אם פיצ'ר יגיע ל->50 testers נשדרג ל-DB-backed.

---

## 13. מה פתוח / הצעדים הבאים

### 13א. מעוצב, עוד לא נבנה

1. **`isPrimary` flag למודלי AI** *(קטן, ~יום)*
   - להוסיף `isPrimary: boolean` ל-`ai-models.model.ts`
   - לחשוף דרך `admin-ai-models` panel
   - שה-Unified Chat יקרא מזה במקום `models[0]` כ-placeholder

2. **Auto router לצ'אט / תמונות** *(גדול, module שלם)*
   - `gpt-auto`, `claude-auto` — auto-tier בתוך brand (זול → חכם לפי prompt)
   - `image-auto` — היוריסטי לפי style preset + scan מילות מפתח ("צילום" → Flux, "לוגו" → Ideogram)
   - Module חדש `backend/src/modules/model-router/` עם `model-router.config.json` ב-Phase 1, DB+admin UI ב-Phase 2
   - Frontend שולח `model: '<brand>-auto'` → backend פותר → מחזיר את המודל הנבחר בתשובה

3. **Conversation history ל-Unified Chat** *(ערך גבוה)*
   - לצ'אט הקלאסי יש sidebar היסטוריה; ל-Unified אין
   - תוכנית: שימוש חוזר ב-`chat-history` הקיים עם הרחבת schema — שדה `mode: 'chat' | 'unified'`

4. **Deep links ל-Unified Chat**
   - `/unified-chat/:conversationId` כמו `/chat/:conversationId` הקלאסי
   - בא טבעי עם #3

### 13ב. בעיות ידועות / Tradeoffs

- **Stability.AI key 401** — לא חוסם, רק SD לא עובד. להחליף כשנוח.
- **`SERPAPI_KEY` חסר** — Trip Planner web search לא קיים. דלג אם מבקשים.
- **`subscription.plan` יכול להיות undefined** לחשבונות בלי subscription. כבר מוגן `?.` ב-sidebar.vue. לבדוק דפוסים דומים.

### 13ג. תיעוד / nice-to-have

- לתעד את אירועי ה-Debug Panel ב-`SYSTEM_DOCUMENTATION.md` § 6 ו-§ 7.
- `BETA_USERS_WHITELIST` ו-`DEBUG_USERS_EMAILS` לא ב-`.env.stg.original` — כשמרעננים env מ-upstream, להוסיף שוב.

---

## 14. צעדים מומלצים לפני שמשהו אחר מתחיל

1. **השינוי ב-`CLAUDE.md`** — בלוק ה-SR-PTD (~38 שורות) הוסף **בכוונה ע"י skill** והוא לא בעיה. **לא להריץ `git checkout -- CLAUDE.md` אוטומטית.** אם בכל זאת מפריע — לערוך ידנית, לא להחזיר עם git.

2. **לקבע את `forpapa.md` ו-`forpapa2.md` ב-git** (אם רלוונטי), או להוסיף ל-`.gitignore`.

3. **סנכרון עם `origin/main`** — **לא נדרש.** ה-state האמיתי הוא `0 behind / 39 ahead`. שני ה-commits האחרונים שנראים ב-`git log origin/main` (`d7955d2` whatsapp content-type, `9de7d98` 019 thinking text) **כבר ancestors של ה-HEAD שלנו** — הם נכנסו דרך ה-Merge ב-`2158bd9` שהיא בעצמה נקודת ה-fork. אומת ב-`git merge-base --is-ancestor`. אין מה למשוך.

---

## 15. רשימת תיעוד קיים (לעיון מהיר)

| קובץ | תוכן | מתי לקרוא |
|---|---|---|
| [`CLAUDE.md`](./CLAUDE.md) | אינדקס 5 שורות שמפנה לכל השאר | ראשון, תמיד |
| [`AGENTS.md`](./AGENTS.md) | Repo conventions, git remotes, worktree workflow, commands, hard rules, user-gated pattern | קריאה ראשונה אחרי CLAUDE.md |
| [`SESSION_NOTES.md`](./SESSION_NOTES.md) | מה נבנה ב-V4 מאז ה-fork + open items | להבין את הסטטוס הנוכחי |
| [`DEPLOYMENT.md`](./DEPLOYMENT.md) | איך staging מחווט (NPM/SSL, env vars, mongo) | לעבודה על תשתית או deployment |
| [`LOCAL_DEV_SETUP.md`](./LOCAL_DEV_SETUP.md) | פורטים מדויקים, DB collections, API keys, רענון data | להעלות סביבה / לרענן data |
| [`SYSTEM_DOCUMENTATION.md`](./SYSTEM_DOCUMENTATION.md) | צלילה עמוקה ב-auth, SSE, image flow, admin, file cheat-sheet | להבין pipeline ספציפי |
| [`forpapa.md`](./forpapa.md) | סיכום קודם בעברית (מ-2026-05-05) | רקע, לפני ה-restructure |
| **[`forpapa2.md`](./forpapa2.md)** | **המסמך הזה — סקירה מעודכנת ועצמאית** | המקום לעדכון אחרי ה-restructure |

---

## 16. הערה אישית למסירה

הפרויקט במצב טוב. ה-V4 מתפקד כצריך — שלושת השרתים פועלים, ה-DB מאוכלס, ה-AI providers הגדולים זמינים, ה-streaming עובד נקי דרך ה-NPM, וה-Unified Chat הוא דף הנחיתה הראשי בפועל. ההפרדה בין `origin` (הפרודקשן) ל-`v4` (הפיתוח) שמורה היטב — לא נדחף שום commit ל-`origin` מאז ה-fork. שלושה commits של תיעוד וסידור workspace הם מה שנעשה בשבוע האחרון, וזה הכל לגיטימי.

הדבר הכי חשוב לזכור: **`https://idev.binaplus.co.il` הוא שיקוף חי של מה שיש בקבצים על המכונה הזו**. שמירה של קובץ ב-`frontend_v3/` או `backend/` → השינוי על האוויר תוך שניות. אין step "deploy". זה גם הכוח הגדול וגם המקום הכי שביר — אם backend מתרסק, האתר על האוויר נופל. הלוגים ב-`/tmp/v2_backend.log` ו-`/tmp/v2_frontend.log` הם נקודת ההתחלה לכל debugging.

הפיצ'רים ה-isolated ב-worktree branches (`feature/unified-chat`, `feature/debug-panel`) הם הנכס היקר — הם מאפשרים cherry-pick מסודר חזרה ל-`origin` כשהזמן יבוא. **אל תמזגו אותם ל-`main` בלי לשמור עליהם נפרדים.**

---

**זהו הסיכום הכולל. אם צריך פירוט נוסף על pipeline ספציפי, על קומפוננטה מסוימת, או על איך לבנות פיצ'ר חדש — פתחו את `AGENTS.md` ו-`SYSTEM_DOCUMENTATION.md`, הם הולכים לעומק.**

— Claude Opus 4.7, 2026-05-05