תיעוד TaskUnity
מדריך מלא לשימוש במערכת ניהול המשימות והפרויקטים
# מדריך ליצירת עוזר אישי חכם דרך WhatsApp במערכת TaskUnity
## 1. הקדמה - מה זה עוזר אישי בWhatsApp?
עוזר אישי חכם דרך WhatsApp הוא AI Agent שמאפשר למשתמשים לנהל את המשימות, הפרויקטים והלקוחות שלהם ישירות מדפדפן WhatsApp או WhatsApp Business, בעזרת הודעות טקסט פשוטות.
הוא יכול לבצע פעולות כמו:
- יצירת משימות חדשות
- עדכון סטטוס משימות
- חיפוש נתונים
- שליחת הודעות ללקוחות
- ניתוח וסיכום מידע
## 2. אדריכלות המערכת
### רכיבי התשתית הנדרשים:
- **Agent JSON** - הגדרת ה-AI agent ויכולותיו
- **Backend Functions** - פונקציות שרת לביצוע פעולות
- **WhatsApp Integration** - חיבור לAPI של WhatsApp
- **Entity Access** - גישה לנתונים (Task, Project, Client, etc.)
### זרימת המידע:
```
משתמש WhatsApp → Agent → Backend Functions → Database → Response → WhatsApp
```
## 3. שלב 1: יצירת ה-Agent
צור קובץ JSON בתיקיית `agents/`:
```json
{
"description": "סוכן חכם לניהול משימות, פרויקטים ותקשורת עם לקוחות דרך WhatsApp",
"instructions": "אתה עוזר וירטואלי למערכת TaskUnity. תפקידך לסייע למשתמשים לנהל את המשימות, הפרויקטים והלקוחות שלהם. עליך להיות ידידותי, מקצועי, יעיל ולדבר תמיד בעברית. כאשר אתה יוצר ישות חדשה, אמור למשתמש מה יצרת.",
"tool_configs": [
{
"entity_name": "Task",
"allowed_operations": ["create", "update", "read", "delete"]
},
{
"entity_name": "Project",
"allowed_operations": ["create", "read", "update", "delete"]
},
{
"entity_name": "Client",
"allowed_operations": ["create", "read", "update", "delete"]
},
{
"function_name": "sendWhatsAppMessage",
"description": "שליחת הודעות WhatsApp ללקוחות"
},
{
"function_name": "mboLeadLookup",
"description": "חיפוש לקוחות במערכת"
},
{
"function_name": "mboClientUpdateStatus",
"description": "עדכון סטטוס לקוח"
}
],
"whatsapp_greeting": "שלום! 👋 אני העוזר החכם של TaskUnity.\n\nאני יכול לעזור לך ליצור ולנהל משימות, פרויקטים ולקוחות ישירות מכאן.\n\nמה תרצה/י לעשות?"
}
```
### הסבר על השדות:
- **description**: תיאור קצר של מה שה-agent עושה
- **instructions**: הוראות מפורטות ל-AI איך להתנהג
- **tool_configs**: רשימת הכלים שה-agent יכול להשתמש בהם
- **whatsapp_greeting**: ההודעה הראשונה שהמשתמש יראה
## 4. שלב 2: יצירת Backend Functions
### דוגמה: חיפוש לקוחות
```javascript
// functions/mboLeadLookup.js
import { createClientFromRequest } from 'npm:@base44/sdk@0.7.1';
Deno.serve(async (req) => {
try {
const base44 = createClientFromRequest(req);
const user = await base44.auth.me();
if (!user) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
const { query } = await req.json();
if (!query || query.trim().length < 2) {
return Response.json({ error: 'Query must be at least 2 characters' }, { status: 400 });
}
const clients = await base44.entities.Client.list();
const results = clients
.filter(client => {
const searchText = query.toLowerCase();
return (
client.name?.toLowerCase().includes(searchText) ||
client.email?.toLowerCase().includes(searchText) ||
client.phone?.includes(searchText) ||
client.company?.toLowerCase().includes(searchText)
);
})
.slice(0, 5)
.map(client => ({
client_id: client.id,
name: client.name,
phone: client.phone || 'לא צוין',
email: client.email || 'לא צוין',
company: client.company || 'לא צוין',
status: client.status || 'active',
notes: client.notes || ''
}));
return Response.json({
success: true,
results: results,
query: query,
count: results.length
});
} catch (error) {
console.error('Error in lead lookup:', error);
return Response.json({
success: false,
error: error.message
}, { status: 500 });
}
});
```
### דוגמה: שליחת הודעות WhatsApp
```javascript
// functions/sendWhatsAppMessage.js
import { createClientFromRequest } from 'npm:@base44/sdk@0.7.1';
Deno.serve(async (req) => {
try {
const base44 = createClientFromRequest(req);
const user = await base44.auth.me();
if (!user) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
const { companyId, toNumber, templateName, variables } = await req.json();
if (!companyId || !toNumber || !templateName) {
return Response.json({
error: 'Missing required parameters: companyId, toNumber, templateName'
}, { status: 400 });
}
// חפש את ארגון והגדרות WhatsApp שלו
const organization = await base44.asServiceRole.entities.Organization.get(companyId);
if (!organization) {
return Response.json({ error: 'Organization not found' }, { status: 404 });
}
if (!organization.whatsapp_api_url || !organization.whatsapp_api_token) {
return Response.json({
error: 'WhatsApp API credentials not configured for this organization'
}, { status: 400 });
}
// בנה את payload ל-WhatsApp API
const payload = {
messaging_product: "whatsapp",
to: toNumber,
type: "template",
template: {
name: templateName,
language: { code: "he" },
components: variables ? [{
type: "body",
parameters: variables.map(v => ({ type: "text", text: v }))
}] : []
}
};
// שלח ל-WhatsApp API
const whatsappResponse = await fetch(`${organization.whatsapp_api_url}/messages`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${organization.whatsapp_api_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const responseData = await whatsappResponse.json();
const success = whatsappResponse.ok;
// שמור רשומה
await base44.asServiceRole.entities.WhatsAppMessage.create({
organization_id: companyId,
phone_number: toNumber,
message_type: "outgoing",
status: success ? "sent" : "failed",
template_used: templateName,
content: `Template: ${templateName}`,
whatsapp_message_id: success ? responseData.messages?.[0]?.id : null,
error_message: success ? null : responseData.error?.message || 'Unknown error',
sent_by: user.id
});
return Response.json({
success: success,
message_id: success ? responseData.messages?.[0]?.id : null,
whatsapp_response: responseData
});
} catch (error) {
console.error('Error sending WhatsApp message:', error);
return Response.json({
success: false,
error: error.message
}, { status: 500 });
}
});
```
## 5. שלב 3: הגדרת WhatsApp Integration
### A. הוסף שדות WhatsApp לארגון
וודא שישות `Organization` כוללת:
```json
{
"whatsapp_api_url": {"type": "string"},
"whatsapp_api_token": {"type": "string"},
"whatsapp_phone_number": {"type": "string"}
}
```
### B. צור ישות להודעות WhatsApp
```json
{
"name": "WhatsAppMessage",
"type": "object",
"properties": {
"organization_id": {"type": "string"},
"phone_number": {"type": "string"},
"message_type": {"type": "string", "enum": ["incoming", "outgoing"]},
"status": {"type": "string", "enum": ["sent", "delivered", "read", "failed"]},
"template_used": {"type": "string"},
"content": {"type": "string"},
"whatsapp_message_id": {"type": "string"},
"error_message": {"type": "string"},
"sent_by": {"type": "string"}
},
"required": ["organization_id", "phone_number", "message_type"]
}
```
## 6. שלב 4: הוספת UI להתחברות WhatsApp
### A. הוסף כפתור חיבור ב-Layout
```javascript
// בתוך Layout.js
import { agentSDK } from "@/agents";
// בתוך הקומפוננט:
const whatsappURL = agentSDK.getWhatsAppConnectURL('taskManager');
// בחלק ה-JSX:
<a href={whatsappURL} target="_blank" className="flex items-center gap-2 text-green-600">
💬 WhatsApp Assistant
</a>
```
### B. הוסף דף הגדרות WhatsApp
```javascript
// components/settings/WhatsAppSettings.jsx
import React from 'react';
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
export default function WhatsAppSettings({ organization, onSave }) {
const [settings, setSettings] = React.useState({
whatsapp_api_url: organization?.whatsapp_api_url || '',
whatsapp_api_token: organization?.whatsapp_api_token || '',
whatsapp_phone_number: organization?.whatsapp_phone_number || ''
});
const handleSave = async () => {
await onSave(settings);
};
return (
<Card>
<CardHeader>
<CardTitle>הגדרות WhatsApp Business</CardTitle>
</CardHeader>
<CardContent className="space-y-4">
<div>
<Label htmlFor="api_url">WhatsApp API URL</Label>
<Input
id="api_url"
value={settings.whatsapp_api_url}
onChange={(e) => setSettings({...settings, whatsapp_api_url: e.target.value})}
placeholder="https://graph.facebook.com/v17.0/YOUR_PHONE_ID"
/>
</div>
<div>
<Label htmlFor="api_token">Access Token</Label>
<Input
id="api_token"
type="password"
value={settings.whatsapp_api_token}
onChange={(e) => setSettings({...settings, whatsapp_api_token: e.target.value})}
placeholder="Your WhatsApp Business API Token"
/>
</div>
<div>
<Label htmlFor="phone_number">מספר טלפון WhatsApp</Label>
<Input
id="phone_number"
value={settings.whatsapp_phone_number}
onChange={(e) => setSettings({...settings, whatsapp_phone_number: e.target.value})}
placeholder="+972501234567"
/>
</div>
<Button onClick={handleSave}>שמור הגדרות</Button>
</CardContent>
</Card>
);
}
```
## 7. Best Practices וטיפים חשובים
### A. אבטחה
- **תמיד אמת משתמשים:** וודא ש-`base44.auth.me()` מחזיר משתמש תקין
- **הגבל הרשאות:** תן רק את ההרשאות הנדרשות לכל function
- **אמת input:** בדוק תמיד את הפרמטרים הנכנסים
### B. חוויית משתמש
- **הודעות ברורות:** תן למשתמש לדעת מה קורה
- **טיפול בשגיאות:** תמיד תן הודעת שגיאה מובנת
- **פידבק מיידי:** אשר פעולות שבוצעו בהצלחה
### C. ביצועים
- **הגבל תוצאות:** אל תחזיר יותר מדי נתונים בבת אחת
- **Cache נתונים:** שמור נתונים שחוזרים על עצמם
- **Timeout:** הגדר timeout לפונקציות ארוכות
## 8. בדיקות ו-Debugging
### A. בדיקת חיבור WhatsApp
```javascript
// functions/testWhatsAppConnection.js
const testResponse = await fetch(`${organization.whatsapp_api_url.replace('/messages', '')}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${organization.whatsapp_api_token}`,
'Content-Type': 'application/json'
}
});
return Response.json({
success: testResponse.ok,
valid: testResponse.ok,
message: testResponse.ok ? 'WhatsApp API connection is valid' : 'Connection failed'
});
```
### B. לוגים ומעקב
- השתמש ב-`console.log` לדיבוג
- שמור activity logs לכל פעולה חשובה
- מיפוי שגיאות נפוצות ופתרונות
## 9. דוגמאות שימוש
### משתמש יכתוב ב-WhatsApp:
- "צור משימה: לבדוק את הדוח החודשי"
- "עדכן משימה X לסטטוס הושלמה"
- "מצא לקוח בשם יוסי"
- "שלח הודעה ללקוח 123 עם תבנית ברכות"
### התגובות שהוא יקבל:
- "✅ יצרתי משימה חדשה: 'לבדוק את הדוח החודשי' וקיצתי אותה אליך"
- "✅ משימה X עודכנה לסטטוס 'הושלמה'"
- "🔍 מצאתי 2 לקוחות בשם יוסי: [פרטים...]"
- "📱 הודעה נשלחה בהצלחה ללקוח 123"
## 10. שגיאות נפוצות ופתרונות
### שגיאה: "Unauthorized"
**פתרון:** וודא שה-function מאמת את המשתמש עם `base44.auth.me()`
### שגיאה: "Entity not found"
**פתרון:** בדוק ש-entity קיים ושיש הרשאות גישה אליו
### שגיאה: "WhatsApp API failed"
**פתרון:** בדוק את ה-tokens וה-URLs בהגדרות הארגון
### שגיאה: "Function timeout"
**פתרון:** פשט את הlogic או חלק לכמה functions קטנים יותר
---
## סיכום
עוזר אישי חכם ב-WhatsApp הוא כלי חזק שמאפשר ניהול יעיל של עסק ישירות מהטלפון.
העקרונות המרכזיים להצלחה:
1. **תכנון מוקדם** - הגדר בדיוק מה העוזר צריך לעשות
2. **אבטחה מלאה** - אמת כל בקשה ומגן על הנתונים
3. **חוויית משתמש פשוטה** - עשה את זה קל ואינטואיטיבי
4. **בדיקות יסודיות** - בדוק כל תרחיש לפני השקה
בהצלחה! 🚀