SmartAssistant/DEPLOYMENT_REVIEW.md

SmartAssistant v1.0.3 — סיכום מנהלים לפריסה בפיתוח

תאריך: 2026-03-31 גרסה: 1.0.3 | תאריך שחרור: 2026-03-29 סביבת יעד: EspoCRM Development (https://espocrm.dev.marcus-law.co.il) מחבר: klear | דרישות: EspoCRM >= 8.0.0, PHP >= 8.1

---

1. תיאור כללי

SmartAssistant הוא מודול עוזר AI מאוחד למשרד עורכי דין.

המודול מספק:

• ממשק צ'אט צף (Floating Action Button) בכל דפי המערכת
• מצב משרד — סקירה כללית, התראות, סטטיסטיקות עומס עבודה
• מצב תיק — סיוע מעמיק בתיק ספציפי עם הקשר מלא
• מערכת זיכרון תיק (CaseMemory) — מאגר ידע מובנה לכל תיק ב-7 קטגוריות
• ביצוע פעולות באישור — יצירת משימות, פתקים, דיונים, שינוי סטטוס
• אינטגרציה עם Stream — כל אינטראקציה מופיעה בציר הזמן של התיק
• התראות בסרגל ניווט — תיקים לא פעילים, משימות באיחור, דיונים קרובים

---

2. מה בוצע

2.1 Backend (PHP) — 16 קבצים

רכיב	קובץ	תפקיד
Controller	Controllers/SmartAssistant.php	10 נקודות קצה API (chat, execute, summary, alerts, history, conversations, conversationMessages, searchHistory, caseMemory, saveMemory)
שירות ראשי	Services/SmartAssistantService.php	תזמור מלא: בניית הקשר → קריאת webhook → טיפול בפעולות → שמירת שיחה
בונה הקשר תיק	Services/CaseContextBuilder.php	אוסף: נתוני תיק, אנשי קשר, משימות פתוחות, דיונים קרובים, פתקים אחרונים, זיכרון
בונה הקשר משרד	Services/OfficeContextBuilder.php	סטטיסטיקות כלליות, התראות, עומס עבודה לפי משתמש, drill-down לתיקים
מחשבון התראות	Services/AlertCalculator.php	6 סוגי התראות: תיקים לא פעילים (14/30 יום), משימות באיחור, דיונים קרובים, תיקים ללא שיוך, משימות בעדיפות גבוהה
מבצע פעולות	Services/ActionExecutor.php	8 כלים: create_task, add_note, change_status, create_meeting, schedule_hearing, list_documents, analyze_document, save_memory, rename_document
שירות זיכרון	Services/CaseMemoryService.php	CRUD מלא לאנטיטי CaseMemory
ספק הקשר זיכרון	Services/CaseMemoryContextProvider.php	הזרקת זיכרון מוצמד/חשוב להקשר AI
מאגר שיחות	Services/ConversationRepository.php	שמירה ואחזור שיחות ב-AssistantConversation
מנתח מסמכים	Services/DocumentAnalyzer.php	סריקת מסמכים דרך FileStorage
Hook - שינוי תיק	Hooks/Case/CaseFieldChangeMemory.php	זיכרון אוטומטי בשינוי: סטטוס, שופט, בית משפט, מועד דיון
Hook - דיון	Hooks/Meeting/HearingScheduledMemory.php	זיכרון אוטומטי בקביעת דיון חדש
FileStorage	Classes/FileStorage/*	4 קבצים: Interface, Factory, WebDav, NextCloud

2.2 Frontend (JavaScript) — 9 קבצים

רכיב	תפקיד
floating-chat.js	ממשק צ'אט צף (~1500 שורות): שליחת הודעות, היסטוריה, זיכרון, אישור/דחיית פעולות, עיצוב RTL, Material Design
site/navbar.js	אייקון התראות בסרגל ניווט עם badge מספרי
dashlets/smart-assistant.js	דשלט לדשבורד: סיכום מדדים + התראות אחרונות
dashlets/options/smart-assistant.js	הגדרות דשלט
case/modals/add-memory.js	מודל להוספת זיכרון ידנית לתיק
stream/notes/smart-request.js	תצוגת הודעת משתמש ב-Stream
stream/notes/smart-response.js	תצוגת תשובת עוזר ב-Stream
stream/notes/smart-action.js	תצוגת פעולה שבוצעה ב-Stream

2.3 מטא-נתונים וקונפיגורציה — 17 קבצי JSON

• routes.json — 10 נתיבי API
• module.json — רישום מודול עם clientModule
• entityDefs/ — CaseMemory (אנטיטי חדש, 15 שדות, 4 אינדקסים), Case (שדה cNextHearing), Note (סוגי stream חדשים)
• scopes/CaseMemory.json — הגדרות scope
• layouts/CaseMemory/ — 4 layouts (list, detail, listSmall, detailSmall)
• dashlets/SmartAssistant.json — הגדרת דשלט
• integrations/SmartAssistant.json — 6 שדות הגדרה (webhookUrl, apiKey, maxMessagesPerHour, inactivityWarningDays, inactivityCriticalDays, upcomingHearingDays)
• clientDefs/App.json — רישום navbar

2.4 תרגומים — 10 קבצים

• en_US — 5 קבצי תרגום (SmartAssistant, CaseMemory, Case, Global, Integration)
• fa_IR — 5 קבצי תרגום מקבילים (עברית/פרסית)

2.5 בנייה והפצה

• build.sh — סקריפט בנייה: קורא גרסה מ-manifest.json, מעדכן README, יוצר ZIP
• composer.json — הגדרת חבילה ל-Composer Registry
• 4 גרסאות ZIP — 1.0.0, 1.0.1, 1.0.2, 1.0.3

---

3. היסטוריית גרסאות ותיקוני באגים

v1.0.0 — a148e0f

• פיצ'ר ראשוני — מודול SmartAssistant מלא עם case memory

v1.0.0 → v1.0.1 — תיקונים

Commit	תקלה	תיקון
0cdbf6d	דשלט ירש מ-DashletView שלא קיים בגרסאות חדשות	שונה ל-base View + הוספת getTitle()
ffd966a	לא היה composer.json לפרסום אוטומטי	נוסף composer.json
bd1cd17	גרסה ב-README לא מתעדכנת אוטומטית	build.sh מעדכן README
95ca8a0	חסר תיעוד מקיף	נוסף README מלא בעברית
fbe4f82	נתיבי client לא תואמים לפורמט מודולים של EspoCRM	מיגרציה לנתיבי מודול תקניים

v1.0.1 → v1.0.2 — f380542

תקלה	תיקון
נתיבי CSS ו-script שגויים ב-app/client.json metadata	תיקון הנתיבים ל-format הנכון

v1.0.2 → v1.0.3 — d5c8a60

תקלה	תיקון
EspoCRM לא מצליח לרזולב templates בצד לקוח כי חסר clientModule	הוספת clientModule ל-module.json

סיכום תקלות שנמצאו ותוקנו

#	תקלה	חומרה	סטטוס
1	דשלט ירש מ-class לא קיים	גבוהה	תוקן v1.0.1
2	נתיבי client לא תקניים לפורמט מודולים	גבוהה	תוקן v1.0.1
3	נתיבי CSS/script שגויים ב-metadata	בינונית	תוקן v1.0.2
4	חסר clientModule לרזולוציית templates	גבוהה	תוקן v1.0.3

---

4. מה נבדק

נבדק ידנית (על סמך תיקוני הבאגים)

• רישום מודול וטעינת client-side assets
• תצוגת דשלט בדשבורד
• רזולוציית templates בצד לקוח
• נתיבי metadata (CSS, scripts)

לא נבדק (אין קבצי טסט בפרויקט)

• אין בדיקות יחידה (unit tests) לקוד PHP
• אין בדיקות אינטגרציה ל-API endpoints
• אין בדיקות E2E לממשק הצ'אט
• אין CI/CD pipeline (אין GitHub Actions / Gitea Actions)

---

5. דרישות קדם לפריסה בפיתוח

דרישה	סטטוס	פירוט
EspoCRM >= 8.0.0	לאמת	לוודא גרסה בסביבת dev
PHP >= 8.1	לאמת	לוודא גרסה בשרת
Webhook URL	נדרש הגדרה	יש להגדיר n8n workflow שיקבל את הפניות
API Key	אופציונלי	לאימות webhook
AssistantConversation entity	לאמת	נדרש שהאנטיטי קיים
WebDAV/NextCloud	אופציונלי	רק לפיצ'ר ניתוח מסמכים

---

6. מה נשאר לעשות

קריטי לפני פריסה

#	משימה	עדיפות
1	הגדרת n8n workflow לקבלת webhook מהעוזר (chat endpoint)	קריטי
2	בדיקת תאימות עם גרסת EspoCRM בסביבת dev	קריטי
3	לוודא שאין שאריות של מודולים ישנים בסביבת dev	קריטי
4	הגדרת Integration — webhookUrl + apiKey ב-Admin > Integrations	קריטי
5	בדיקה שאנטיטי AssistantConversation קיים או שצריך ליצור אותו	קריטי

חשוב אחרי פריסה

#	משימה	עדיפות
6	בדיקות ידניות מקיפות — צ'אט במצב משרד ומצב תיק	גבוהה
7	בדיקת פעולות — create_task, add_note, schedule_hearing, change_status	גבוהה
8	בדיקת hooks — שינוי סטטוס תיק → זיכרון אוטומטי	גבוהה
9	בדיקת התראות — navbar badge + דשלט	בינונית
10	בדיקת היסטוריה — שמירה ואחזור שיחות, חיפוש	בינונית

שיפורים עתידיים

#	משימה	עדיפות
11	כתיבת בדיקות יחידה ל-PHP	בינונית
12	הוספת CI/CD pipeline (Gitea Actions)	בינונית
13	הוספת תרגום עברי (he_IL) — כרגע en_US + fa_IR בלבד	בינונית
14	Rate limiting בצד client (כרגע רק בצד server)	נמוכה
15	הצפנת שיחות	נמוכה

---

7. תיעוד מפורט של הקוד והקבצים

7.1 ארכיטקטורה כללית

┌─────────────────────────────────────────────────┐
│                   Frontend (JS)                  │
│  floating-chat.js ←→ navbar.js ←→ dashlet.js    │
│       │              │              │            │
│  [צ'אט צף]    [התראות navbar]  [דשלט דשבורד]     │
└───────────────────────┬─────────────────────────┘
                        │ REST API (10 endpoints)
┌───────────────────────┴─────────────────────────┐
│              Controller/SmartAssistant.php        │
│  chat | execute | summary | alerts | history ... │
└───────────────────────┬─────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────┐
│           SmartAssistantService.php               │
│  תזמור: הקשר → webhook → פעולות → שמירה          │
├──────────┬──────────┬──────────┬─────────────────┤
│ Context  │ Action   │ Memory   │ Conversation    │
│ Builders │ Executor │ Service  │ Repository      │
├──────────┴──────────┴──────────┴─────────────────┤
│  CaseContext  │ OfficeContext │ AlertCalculator   │
│  Builder      │ Builder      │                   │
└───────────────┴──────────────┴───────────────────┘
                        │
              ┌─────────┴──────────┐
              │   External n8n     │
              │   Webhook (AI)     │
              └────────────────────┘

7.2 זרימת צ'אט (Chat Flow)

1. משתמש שולח הודעה ← floating-chat.js
2. POST /SmartAssistant/action/chat { message, caseId?, conversationId }
3. Controller → SmartAssistantService::chat()
4. בניית הקשר:
   ├─ מצב תיק → CaseContextBuilder (נתוני תיק + אנשי קשר + משימות + דיונים + זיכרון)
   └─ מצב משרד → OfficeContextBuilder (סטטיסטיקות + התראות)
5. קריאת webhook חיצוני (n8n) עם: message + context + history
6. קבלת תשובה: { text, actions[] }
7. פעולות מיידיות (list_documents, save_memory) → ביצוע אוטומטי
8. פעולות הדורשות אישור → שמירה + החזרה למשתמש
9. שמירת שיחה ב-ConversationRepository
10. שמירת הודעות ב-Stream (smart-request + smart-response notes)

7.3 פירוט קבצי Backend

Controllers/SmartAssistant.php (168 שורות)

• actionChat() — מקבל message, caseId, conversationId. בודק ACL ל-Case. קורא ל-SmartAssistantService::chat()
• actionExecute() — מקבל actionId, conversationId. מבצע פעולה שאושרה
• actionSummary() — מחזיר סיכום משרדי + התראות
• actionAlerts() — רשימת התראות מלאה
• actionHistory() — היסטוריית שיחות (לפי caseId או אחרונה)
• actionConversations() — רשימת שיחות אחרונות
• actionConversationMessages() — הודעות שיחה ספציפית
• actionSearchHistory() — חיפוש חופשי בשיחות
• actionCaseMemory() — זיכרון תיק לפי קטגוריה
• actionSaveMemory() — שמירת זיכרון ידנית

Services/SmartAssistantService.php (~500 שורות)

הקובץ המרכזי ביותר. אחראי על:

• chat() — הזרימה המלאה: בניית הקשר, קריאת webhook, עיבוד פעולות, שמירת שיחה
• callWebhook() — קריאת CURL ל-n8n עם timeout, headers (X-Api-Key), JSON payload
• processActions() — מיון פעולות: מיידיות vs. דורשות אישור
• executeAction() — ביצוע פעולה שאושרה דרך ActionExecutor
• getSummary() / getAlerts() — מצב משרד
• getConversations() / getHistory() / searchHistory() — ניהול שיחות

Services/CaseContextBuilder.php (~150 שורות)

בונה הקשר עשיר לתיק:

[
  'case' => [...],           // שדות תיק מרכזיים
  'contacts' => [...],       // אנשי קשר מקושרים
  'openTasks' => [...],      // משימות פתוחות (עד 10)
  'upcomingMeetings' => [...], // דיונים קרובים (עד 5)
  'recentNotes' => [...],    // פתקים אחרונים (עד 10)
  'memories' => [...],       // זיכרון מוצמד + חשוב
  'stats' => [...]           // מספרי סיכום
]

Services/OfficeContextBuilder.php (~80 שורות)

בונה סיכום משרדי:

[
  'totalActiveCases' => int,
  'casesByStatus' => [...],
  'overdueTasks' => int,
  'upcomingHearings' => int,
  'userWorkload' => [...],   // עומס לפי משתמש
  'alerts' => [...]
]

Services/ActionExecutor.php (~250 שורות)

מבצע 8 סוגי פעולות:

כלי	פרמטרים	פעולה
create_task	name, dateEnd, priority, description	יצירת Task מקושר לתיק
add_note	text	הוספת Post ב-Stream של התיק
change_status	status	שינוי סטטוס (עם validation מול enum)
create_meeting	name, dateStart, dateEnd, description	יצירת Meeting
schedule_hearing	date, description	עדכון cNextHearing + יצירת Meeting
list_documents	—	רשימת מסמכים (read-only, ללא אישור)
analyze_document	documentId	ניתוח מסמך דרך DocumentAnalyzer
save_memory	name, content, category, importance	שמירת CaseMemory (ללא אישור)
rename_document	documentId, newName	שינוי שם קובץ

Services/AlertCalculator.php (~200 שורות)

6 סוגי התראות:

סוג	לוגיקה	חומרה
תיק לא פעיל (אזהרה)	modifiedAt < now - 14 יום	warning
תיק לא פעיל (קריטי)	modifiedAt < now - 30 יום	critical
משימה באיחור	dateEnd < now, status != Completed	critical
דיון קרוב	dateStart < now + 7 ימים	warning
תיק ללא שיוך	status = New, assignedUserId = null	warning
משימה בעדיפות גבוהה	priority = Urgent, dateEnd < now + 5 ימים	warning

Services/CaseMemoryService.php (106 שורות)

CRUD פשוט:

• getMemories() — לפי caseId, עם סינון אופציונלי לפי category
• saveMemory() — יצירת רשומת CaseMemory
• updateMemory() — עדכון
• deleteMemory() — מחיקה רכה

Services/CaseMemoryContextProvider.php

מזריק זיכרון להקשר AI:

• זיכרון מוצמד (isPinned = true)
• זיכרון בחשיבות high/critical
• ממוין לפי importance DESC, modifiedAt DESC

Services/ConversationRepository.php (~120 שורות)

• save() — שמירת שיחה באנטיטי AssistantConversation
• getHistory() — אחזור לפי caseId או אחרון
• getConversations() — רשימה ממוינת (עד limit)
• getMessages() — הודעות שיחה ספציפית
• search() — חיפוש חופשי בתוכן

Hooks

• CaseFieldChangeMemory — afterSave hook על Case. בודק אם שדות key השתנו (status, cJudge, cCourt, cNextHearing). אם כן, יוצר CaseMemory אוטומטי מסוג auto בקטגוריה המתאימה.
• HearingScheduledMemory — afterSave hook על Meeting. אם סוג Meeting = "Hearing", יוצר CaseMemory בקטגוריה timeline.

7.4 פירוט קבצי Frontend

floating-chat.js (~1500 שורות)

הקובץ הגדול ביותר. View יחיד שמנהל:

• תצוגת צ'אט — קלט הודעה, בועות הודעות (משתמש/עוזר), פעולות בהמתנה
• תצוגת היסטוריה — רשימת שיחות קודמות, טעינת שיחה
• תצוגת זיכרון — tabs לפי קטגוריה, הוספה/מחיקה/הצמדה
• RTL layout — כל ה-CSS מותאם לעברית
• עיצוב Material Design — צבע ראשי #5c6bc0 (אינדיגו), אנימציות slide-up
• רספונסיבי — breakpoint ב-480px למובייל
• Inline CSS — כל הסגנונות מוטמעים בקובץ (לא CSS חיצוני)

site/navbar.js

• מרחיב את navbar הרגיל של EspoCRM
• מוסיף אייקון התראות עם badge מספרי
• קורא ל-GET /SmartAssistant/action/alerts ומציג ספירה
• רענון אוטומטי כל X דקות

dashlets/smart-assistant.js

• דשלט לדשבורד הראשי
• מציג: סה"כ תיקים פעילים, משימות באיחור, דיונים קרובים
• רשימת 5 התראות אחרונות
• ACL scope = Case

Stream Notes (3 קבצים)

• smart-request.js — מציג הודעת משתמש עם אייקון שאלה
• smart-response.js — מציג תשובת עוזר עם markdown rendering
• smart-action.js — מציג פעולה שבוצעה עם סטטוס (approved/rejected/executed)

case/modals/add-memory.js

• מודל Espo.Views.Modal סטנדרטי
• שדות: name, category (dropdown), content (textarea), importance (dropdown)
• POST ל-/SmartAssistant/action/saveMemory

7.5 אנטיטי CaseMemory — מבנה מלא

שדות:
├── name (varchar, required) — כותרת הזיכרון
├── case (link → Case, required) — תיק משויך
├── category (enum) — key_facts | strategy | decisions | contacts_notes | timeline | documents_notes | billing_notes
├── content (text, required) — תוכן מלא
├── source (enum, readOnly) — manual | assistant | auto
├── importance (enum) — low | normal | high | critical
├── isPinned (bool) — הצמדה לגישה מהירה
├── isArchived (bool) — הסתרת רשומות ישנות
├── sourceEntityType (varchar, readOnly) — סוג מקור (למעקב)
├── sourceEntityId (varchar, readOnly) — ID מקור
├── assignedUser (link → User)
├── teams (linkMultiple → Team)
├── createdAt, modifiedAt (datetime)
└── createdBy, modifiedBy (link → User)

אינדקסים:
├── caseId + deleted
├── caseId + category + deleted
├── caseId + isPinned + deleted
└── importance + deleted

7.6 הגדרות אינטגרציה

Admin > Integrations > Smart Assistant:

שדה	סוג	ברירת מחדל	תיאור
webhookUrl	url	—	כתובת webhook (n8n)
apiKey	varchar(255)	—	מפתח אימות, נשלח כ-X-Api-Key header
maxMessagesPerHour	int	30	הגבלת קצב
inactivityWarningDays	int	14	סף אזהרה לחוסר פעילות
inactivityCriticalDays	int	30	סף קריטי
upcomingHearingDays	int	7	חלון דיונים קרובים

7.7 פורמט Webhook

Request (נשלח ל-n8n):

{
  "message": "מה המצב של תיק כהן?",
  "context": {
    "case": { "name": "כהן נ' לוי", "status": "Active", ... },
    "contacts": [...],
    "openTasks": [...],
    "memories": [...]
  },
  "conversationId": "conv_abc123",
  "conversationHistory": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ],
  "mode": "case"
}

Response (נדרש מ-n8n):

{
  "text": "תיק כהן פעיל. יש 3 משימות פתוחות ודיון ב-15 באפריל.",
  "actions": [
    {
      "tool": "create_task",
      "params": { "name": "הכנת סיכומים לדיון", "dateEnd": "2026-04-14" },
      "actionId": "action_xyz789",
      "displayText": "יצירת משימה: הכנת סיכומים לדיון"
    }
  ]
}

---

8. סיכום מוכנות לפריסה

קריטריון	סטטוס	הערות
קוד backend	מוכן	16 קבצי PHP, ארכיטקטורה נקייה
קוד frontend	מוכן	9 קבצי JS, עיצוב RTL
מטא-נתונים	מוכן	תוקן ב-v1.0.1-1.0.3
תרגומים	חלקי	en_US + fa_IR, חסר he_IL ייעודי
קובץ התקנה	מוכן	SmartAssistant-1.0.3.zip
n8n workflow	חסר	צריך לבנות workflow שיטפל ב-chat
בדיקות אוטומטיות	אין	אין unit/integration/E2E tests
CI/CD	אין	אין pipeline
תיעוד	מוכן	README מקיף בעברית

המלצה: המודול מוכן טכנית לפריסה בסביבת פיתוח. יש להגדיר webhook URL (n8n workflow) לפני שהצ'אט יהיה פונקציונלי. מומלץ לבצע בדיקות ידניות מקיפות לאחר ההתקנה.