# forpapa.md — סיכום מצב פרויקט Bina Plus V4

> **מסמך זה מסכם בדיוק את מה שהבנתי מהפרויקט אחרי קריאה יסודית של AGENTS.md, SESSION_NOTES.md, SYSTEM_DOCUMENTATION.md, DEPLOYMENT.md, LOCAL_DEV_SETUP.md, ה-git log המלא מאז ה-fork, ושני ה-worktrees הפעילים.**
>
> **תאריך כתיבה:** 2026-05-05
> **כתב:** Claude Opus 4.7 בסביבה הזו (לבקשת Israel — `israel25@enativ.com`)

---

## 1. מה זה הפרויקט הזה בכלל?

יש לנו **שני workspaces נפרדים** על אותה מכונה:

| Workspace | תפקיד | פורטים | סטטוס |
|---|---|---|---|
| `/home/user/bina_plus/` | ה-workspace הישן — ה-codebase המקורי כפי שהוא בפרודקשן (Heroku + Atlas) | 1811 / 1812 | פועל, לא נוגעים בו |
| **`/home/user/bina_plus_v2/`** | **ה-workspace החדש — סנדבוקס לפיתוח V4 על גבי `origin/main`. כאן אנחנו עובדים.** | **1813 / 1814 / 1815** | פעיל |

ה-V2 הוא בעצם copy של הפרויקט (clone של `origin/main` מ-2026-04-27) שעליו אנחנו בונים את **גרסת V4** — הדור הבא של Bina Plus.

---

## 2. מבנה הקוד (מה נמצא איפה)

```
/home/user/bina_plus_v2/
├── backend/          NestJS 10, TypeScript, MongoDB Mongoose         פורט 1813
├── frontend_v3/      Vue 3, Vue CLI 5, RTL/עברית כברירת מחדל          פורט 1814
├── admin_frontend/   Vue 3, Vite 7 (דורש Node 20+)                    פורט 1815
└── frontend/         Angular 17 + NgRx — **legacy, לא נוגעים בו יותר**
```

ה-frontend הישן (Angular) מועבר בהדרגה ל-Vue 3 — כל פיצ'ר חדש נכתב ב-`frontend_v3/` בלבד.

---

## 3. שני ה-Git Remotes (זה הקריטי ביותר להבנה)

```
origin → git@github.com:israel25569/bina_plus.git       ← הפרויקט המקורי (פרודקשן)
v4     → git@github.com:israel25569/binaplusV4.git      ← ה-fork שלנו לפיתוח V4
```

- **`origin`** = הריפו המקורי שמייצר את הפרודקשן ב-`binaplus.co.il` (Heroku).
  - **לא דוחפים אליו לעולם** בלי אישור מפורש מהמשתמש.
  - ה-branches שלהם: `dev` (פיתוח) → `stg` (staging) → `main` (פרודקשן).
- **`v4`** = הריפו של V4. ה-branch המקומי `main` עוקב אחרי `v4/main`. דוחפים לכאן בחופשיות.

**שורה תחתונה:** `git push v4 <branch>` — בטוח. `git push origin <branch>` — מסוכן.

---

## 4. קונבנציית Worktrees לפיצ'רים מבודדים

כל פיצ'ר שניתן לבודד נמצא ב-**branch נפרד עם worktree משלו** מבוסס על `origin/main` נקי. ככה אפשר לעשות לכל פיצ'ר code review בנפרד, cherry-pick ל-origin, או revert בלי לפגוע באחרים.

```
/home/user/bina_plus_v2/                       → main             (V4 trunk, מכיל את הכל)
/home/user/bina_plus_v2_branches/debug-panel   → feature/debug-panel    (רק ה-Debug Panel)
/home/user/bina_plus_v2_branches/unified-chat  → feature/unified-chat   (רק ה-Unified Chat)
```

**אימות שפיצ'ר באמת מבודד:**
```bash
git diff origin/main feature/<name>     # אמור להראות רק קבצים של הפיצ'ר הזה
```

---

## 5. כל הפיצ'רים שנבנו ב-V4 מאז ה-fork (מ-2026-04-27)

מאז ה-fork נעשו **38 commits**. הנה הקבוצות העיקריות של פיצ'רים:

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

- **Files:** `frontend_v3/src/views/UnifiedChat.vue` (~3,272 שורות), `services/quickTilesService.js`. Backend: `backend/src/modules/quick-tiles/*` ו-`admin/modules/admin-quick-tiles/*`.
- **Quick tiles** — כרטיסי יכולת ב-hero state ("צ'אט / תמונה / לוגו / איור / ..."). שמורים ב-DB, ניתנים לניהול דרך ה-admin. אפשר לזרוע מ-`quick-tiles.config.json`.
- **Image proxy** — endpoint `/image/proxy` עם whitelist בטוח (SSRF-safe) — משמש כדי לעקוף CORS כשתמונה שהמודל החזיר משמשת מחדש כ-reference ל-img2img.
- **Aspect ratio + samples** — מועברים ב-`ImageDto`/`ImageToImageDto` עד `replica-image-provider`. Multi-sample מומש על ידי **שליחת N קריאות API מקבילות** במקום הסתמכות על batch native של המודל (שלרוב מחזיר collage אחד).
- **Brand-level model picker** — UI דו-שכבתי נקי: רמה ראשונה מציגה chips של brands (ChatGPT, Claude, Gemini...), חץ inline פותח sub-models (Sonnet/Haiku/Opus וכו'). כרגע "primary" = המודל הראשון בקבוצה (placeholder); יוחלף ב-`isPrimary` field אמיתי ב-DB כשנוסיף תמיכה ב-admin.
- **Thinking-message rotator** — בזמן המתנה לתשובה מציג sparkle + טקסט מתחלף ("חושב..." → "מבין..." → "מנסח תשובה..." → ...) כל ~1.6 שניות. סט נפרד להפקת תמונות.
- **Char-by-char typing animation** — הועתק 1:1 מהצ'אט הקלאסי (RAF-based, 1 char/frame). יש כאן bug של reactivity ששווה לזכור: כשדוחפים אובייקט raw ל-`messages` ואז משתמשים בו במשתנה ביישום — ה-mutations לא מפעילים re-render. הפתרון: לקרוא תמיד מחדש מהמערך — `this.messages[this.messages.length - 1]` (זה ה-reactive proxy).
- **Branch מבודד:** `feature/unified-chat` (worktree ב-`/home/user/bina_plus_v2_branches/unified-chat`). Diff: 22 קבצים, ~4,334 שורות נוספו.

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

- **Files:** `backend/src/modules/debug-events/{module,service}.ts`, `frontend_v3/src/services/debugService.js`, `frontend_v3/src/components/common/DebugPanel.vue`, כפתור toggle ב-`App.vue`.
- **Backend:** `DebugEventsService` global; פולט אירועים מסוגים: `chat:request_received`, `chat:llm_dispatch`, `chat:llm_first_chunk`, `chat:filter_check_start`, `chat:filter_check_end`, `image:request_received` — דרך ה-socket gateway הקיים, מוגבל למשתמשים ב-whitelist.
- **Frontend:** `debugService.js` אוסף אירועים מ-HTTP (axios interceptor), sockets, וערוץ `debug:event` ייעודי. מחלק לקטגוריות (http / chat / image / socket / error). `DebugPanel.vue` מרנדר פאנל כהה צף עם פילטרים.
- **Whitelist:** `DEBUG_USERS_EMAILS` env (מופרד בפסיקים). ריק/לא מוגדר = הפיצ'ר כבוי לכולם. הדגל זורם ל-frontend כ-`user.isDebugUser` מ-`app-config`.
- **גוצ'ה חשוב:** כשקוראים `userData` (Mongoose document) ועושים spread (`{ ...userData, isDebugUser }`) — ה-spread לא קולט את שדות ה-schema. צריך לקרוא ל-`.toObject()` קודם. ראו `app-config.service.ts`.
- **Branch מבודד:** `feature/debug-panel`. Diff: 14 קבצים, ~657 שורות נוספו.

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

### ד. Streaming UX Tuning — כיוון של ה-streaming
- **`wordLimit` בבקאנד הוקטן 30 → 15.** התוכן הראשון של הצ'אט מופיע ב-~2.6 שניות במקום ~5.5 שניות אחרי בדיקת SafeMode.
- **שמירה על delay של 175ms לכל מילה (מכוון).** זה מכייל את בדיקת ה-filter — הפחתה גורמת לסינון להיראות מקרטע. **לא להוריד בלי לשאול.**
- **NPM `proxy_buffering off`** ברמת location — חובה כדי ש-SSE יזרום chunked מעל HTTPS.
- **Vue dev server** גם מבטל proxy buffering ל-`/api` ו-`/socket.io` כך ש-local dev יתאים ל-staging.

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

### ו. Reference Image Flow — זרימת תמונת רפרנס
- לחיצה על תמונה שנוצרה בצ'אט → היא הופכת לרפרנס ל-img2img.
- Backend proxy endpoint (`/image/proxy`) עוקף CORS לתמונות שמאוחסנות ב-CDN.
- Whitelist של hosts מורשים: `cdn.binaplus.co.il`, `replicate.delivery`, `pbxt.replicate.delivery`, `storage.googleapis.com`.

### ז. SafeMode Blocked Rendering — רינדור תוכן חסום
גם הצ'אט הקלאסי וגם ה-unified עכשיו מרנדרים **HTML מלא** לתוכן שנחסם (השרת מחזיר HTML מסונן עם צביעה אדומה והסיבות לחסימה). כפתור "Try Again" מנסה שוב את אותה prompt.

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

---

## 6. איפה הכל רץ (Infrastructure)

### Local (אותה מכונה)
- **Backend:** `npm run start:dev` בתיקיית `backend/` → `localhost:1813` (NODE_ENV=stg, watch mode).
- **Frontend (משתמש):** `npm run serve` בתיקיית `frontend_v3/` → `localhost:1814`.
- **Admin:** `PATH=/usr/local/n/versions/node/20.19.6/bin:$PATH npm run dev` בתיקיית `admin_frontend/` → `localhost:1815` (Node 20+ נדרש כי Vite 7 משתמש ב-`crypto.hash`).
- **MongoDB:** `mongod` כ-systemd service, פורט 27017, replica set `rs0` (חד-נודי, נדרש בגלל transactions).
  - DB: `binaplus-local` עם 18 collections מהפרודקשן (ללא chat/image histories — חסך 707 MB).

### Staging (גישה ציבורית)
- **URL:** `https://idev.binaplus.co.il`
- **לא Heroku** — רץ על אותה המכונה הזו עם **Nginx Proxy Manager (NPM)** מקדימה ל-SSL termination + routing.
- DNS: Netlify DNS (בלי Cloudflare).
- SSL: Let's Encrypt דרך NPM, מתחדש אוטומטית.
- ב-NPM:
  - Public host `idev.binaplus.co.il` → `127.0.0.1:1814` (Vue dev server).
  - Custom location `/api` → `127.0.0.1:1813` (Nest backend).
  - Custom location `/socket.io` → `127.0.0.1:1813` עם WebSocket support.
- **קריטי:** כל location חייב `proxy_buffering off; proxy_read_timeout 600s; proxy_send_timeout 600s;` אחרת SSE ו-Socket.IO נשברים.

### Production (לא נוגעים)
- `binaplus.co.il` — Heroku + Netlify + Atlas `bina-plus-main`.
- שייך לריפו ה-`origin`. אנחנו לא דוחפים שם.

### Logs
- Backend: `/tmp/v2_backend.log`
- Frontend: `/tmp/v2_frontend.log`
- Admin: `/tmp/v2_admin.log`

---

## 7. סטטוס בדיקת API Keys (נכון ל-2026-04-27)

| שירות | סטטוס | תפקיד |
|---|---|---|
| OpenAI | ✅ 200 | GPT-3.5/4/4o, DALL-E |
| Anthropic | ✅ 200 | Claude 3 Haiku/Sonnet/Opus, Claude 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, etc. |
| **Stability AI** | **❌ 401** | **SD 3.5 / SD Ultra / SD Core — צריך מפתח חדש** |
| AWS | ✅ | S3 image storage, SES email |
| Google Cloud SA | ✅ | Translate, Cloud Storage |

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

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

---

## 8. מה פתוח (Open Items)

### עוצב, לא נבנה עדיין

1. **`isPrimary` flag למודלי AI.** ה-brand-level model picker משתמש כרגע ב-"first model in group" כ-placeholder. צריך:
   - להוסיף `isPrimary: boolean` ל-`ai-models.model.ts`
   - לחשוף דרך פאנל ה-`admin-ai-models`
   - לגרום ל-unified chat לקרוא מזה
   - **גודל משימה:** קטנה.

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

3. **היסטוריית שיחות ל-unified chat.** לצ'אט הקלאסי יש sidebar עם היסטוריה מלאה; ל-unified אין עדיין. תוכנית: לעשות שימוש חוזר באותו backend (chat-history) אבל להרחיב את ה-schema עם שדה `mode` (`chat` / `unified`) כדי שההיסטוריה של unified תהיה queryable בנפרד.

4. **Deep links לכל שיחה ב-unified chat** (`/unified-chat/:conversationId` כמו `/chat/:conversationId` הקלאסי).

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

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

### תיקונים קטנים / תיעוד

- לתעד את אירועי ה-debug החדשים ב-`SYSTEM_DOCUMENTATION.md` § 6 (chat flow) ו-§ 7 (image flow).
- ה-env vars `BETA_USERS_WHITELIST` ו-`DEBUG_USERS_EMAILS` לא ב-`.env.stg.original` — כשמרעננים env מ-upstream, להוסיף אותם מחדש.

---

## 9. כללים קריטיים (Hard Rules)

מ-AGENTS.md § "ground rules" — אסור להפר:

1. **עברית first.** המשתמש כותב בעברית. UI חייב לעבוד RTL. ברירת המחדל `lang === 'HB'`.
2. **רק mongo מקומי.** לעולם לא להתחבר ל-Atlas מה-workspace הזה (חוץ מ-mongodump הקריאה-בלבד המתועד).
3. **לעולם לא לדחוף ל-`origin`** בלי אישור מפורש. `v4` בסדר.
4. **התנהגות streaming רגישה.** ה-delay של 175ms לכל מילה הוא **מכוון** (מכייל את בדיקת ה-SafeMode). לא להוריד בלי לשאול.
5. **`BETA_USERS_WHITELIST`** — האתר ב-staging מאפשר רק לאימיילים ספציפיים להיכנס. הוספת tester = עדכון env + restart בקאנד.
6. **`DEBUG_USERS_EMAILS`** — רק האימיילים האלה רואים את ה-Live Debug Panel.
7. **כל פיצ'ר isolatable → branch worktree משלו** מ-`origin/main`. לא לאחד פיצ'רים. המשתמש רוצה לאפשר revert / cherry-pick אינדיווידואלי.
8. **Vue 3 reactivity:** כשמוסיפים אובייקטים למערך ריאקטיבי ואז משנים אותם — תמיד לקרוא מחדש דרך `array[i]` כדי לקבל את ה-proxy. הרפרנס המקורי שדחפת הוא ה-target הגלם.
9. **Mongoose docs ו-spread לא מסתדרים.** להשתמש ב-`.toObject()` לפני `{ ...doc, extra }`.

---

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

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

ברירת המחדל לכל פיצ'ר שאמור להיכנס לפרודקשן אבל להיות **גלוי רק למשתמשים ספציפיים בהתחלה** (early access, פנימי, debug, דפים נסתרים, etc.). בנוי על אותו pattern של ה-Debug Panel — מונע ע"י env var, ללא שינויי schema.

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

1. **Backend env** ב-`.env.stg`:
   ```ini
   DOCS_USERS_EMAILS=info@odma.co.il,israel25@enativ.com
   ```
2. **Backend `app-config.service.ts`** — מחשבים את הדגל מה-env ומוסיפים לאובייקט המשתמש שמוחזר ל-frontend (~3 שורות).
3. **Backend controller(s)** — שומר על כל endpoint:
   ```ts
   if (!user?.email || !this.docsWhitelist.includes(user.email.toLowerCase())) {
     throw new NotFoundException();   // 404 ולא 403 — הפיצ'ר אמור להיות בלתי-נראה
   }
   ```
4. **Frontend** — שומר 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, מוחקים את החישוב של `isDocsUser`, מוחקים את ה-`v-if` ואת ה-route guard. הפיצ'ר נהיה גלוי לכולם בלי DB cleanup.

**למה לא לשים `featureFlags` array על User document:** כי ה-V4 בסופו של דבר מועבר חזרה ל-upstream `bina_plus`. הוספת שדה ל-User schema = DB migration + קונפליקט פוטנציאלי. env-var = 0 footprint ב-schema, טריוויאלי להסיר.

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

---

## 11. סטטוס נוכחי של הקוד (נכון להרגע, 2026-05-05)

```
Branch: main (עוקב אחרי v4/main)
HEAD: 591d0ae — Docs: add 'user-gated feature' pattern to AGENTS.md
שינויים לא commit: CLAUDE.md בלבד
```

### השינוי הלא-commit ב-CLAUDE.md

נוספו ~38 שורות בלוק "MANDATORY: Post-Task Documentation (SR-PTD)" שמפנות לנתיב Windows (`C:/projects/Skills/Dev_doc_for_skills`) — זה ככל הנראה הוסף אוטומטית ע"י skill ולא רלוונטי לסביבת ה-Linux הזו. **מומלץ לעשות `git checkout -- CLAUDE.md` ולמחוק את התוספת.**

### Worktrees פעילים

```
/home/user/bina_plus_v2/                        591d0ae [main]
/home/user/bina_plus_v2_branches/debug-panel    b42634a [feature/debug-panel]
/home/user/bina_plus_v2_branches/unified-chat   87d0c02 [feature/unified-chat]
```

שניהם מסונכרנים עם `v4/feature/<name>` ב-remote.

### שרתים פעילים

נכון להרגע — **backend, frontend ו-admin לא רצים**. צריך להפעיל ידנית.

---

## 12. המלצות למה להמשיך (לפי סדר עדיפות)

1. **לנקות את השינוי הלא-מתוכנן ב-`CLAUDE.md`** (בלוק SR-PTD שלא קשור).
2. **`isPrimary` flag** — קטן, חוסם את ה-brand picker מלהיות אמיתי. ~יום אחד.
3. **Conversation history ל-unified chat** — מוסיף ערך גדול למשתמש (אין דרך כרגע לחזור לשיחה ישנה ב-unified). דורש הרחבת schema של chat-history.
4. **Deep links ל-unified chat** — בא ביחד טבעית עם #3.
5. **Auto router** — פיצ'ר UX משמעותי, אבל גדול יותר ודורש module חדש שלם.
6. לתעד את ה-debug events ב-`SYSTEM_DOCUMENTATION.md` (קוסמטי, אבל מוכן).
7. להחליף את מפתח Stability.AI כשנוח (lab work, לא חוסם כלום).

---

## 13. רשימת התיעוד הקיים (להפניות עתידיות)

| מסמך | תוכן |
|---|---|
| `AGENTS.md` | קונבנציות repo, git remotes, worktree workflow, פקודות נפוצות, hard rules, pattern user-gated. **קריאה ראשונה.** |
| `SESSION_NOTES.md` | מה נבנה ב-V4 מאז ה-fork + open items. |
| `DEPLOYMENT.md` | איך staging (`idev.binaplus.co.il`) ופרודקשן מחווטים (NPM/SSL, env vars, mongo replica set). |
| `LOCAL_DEV_SETUP.md` | פורטים מדויקים, DB collections, API keys, איך לרענן data מקומי. |
| `SYSTEM_DOCUMENTATION.md` | צלילה עמוקה ב-auth, streaming SSE, image flow, פאנלי admin, file cheat-sheet. |
| `CLAUDE.md` | אינדקס 5 שורות שמפנה לכל ה-Above. |
| `README.md` | README כללי של הפרויקט. |
| **`forpapa.md`** (זה הקובץ) | סיכום הכל בעברית למסירה. |

---

**זהו. זה כל מה שהבנתי על הפרויקט אחרי קריאה יסודית. אם משהו לא ברור או חסר — לשאול.**