בניית דף "צריכת קרדיטים" (Integration Credits Dashboard)

המטרה
בנה דף ודאשבורד שמראה על מה נשרפים קרדיטי האינטגרציה של האפליקציה: כמה קרדיטים צרכה כל אינטגרציה (LLM, תמונה, וידאו, מייל, העלאת קובץ וכו'), מפולח לפי סוג השירות ולפי האזור באפליקציה שהפעיל אותו, עם מגמה יומית ורשימת אירועים.
רקע קריטי שחובה להבין לפני שמתחילים
הגישה היחידה המדויקת היא לתעד כל קריאה בעצמנו: מכיוון שכל קריאה לשירות מובנה של Base44 עוברת דרך קוד שאנחנו כותבים (פונקציית Deno או קוד פרונט), נצמיד לכל נקודת קריאה רישום אירוע צריכה עם עלות משוערת, והדף הוא בסך הכול אגרגציה מעל הרישומים האלה.
שני מקורות אמת של Base44 שחובה להיצמד אליהם
טבלת העלות לכל אינטגרציה (מכאן לוקחים את המספרים): https://docs.base44.com/Account-and-billing/Credits#integration-credit-examples
דף השימוש בלוח הבקרה (מקור האמת לאימות, נקשר אליו מהדף שנבנה): Dashboard → Overview → App usage → "By source". תיעוד: https://docs.base44.com/Account-and-billing/Credits#viewing-usage-for-a-single-app

שלב 1 (הכי חשוב, לפני כתיבת שורת קוד): מיפוי כל האינטגרציות והפונקציות
סרוק את כל בסיס הקוד ומצא כל נקודה שקוראת לשירות מובנה של Base44. חפש בפרט:
בבקאנד (פונקציות Deno): asServiceRole.integrations.Core. ואחריו InvokeLLM, GenerateImage, GenerateVideo, GenerateSpeech, SendEmail, SendSMS, UploadFile, ExtractDataFromUploadedFile.
בפרונטאנד: base44.integrations.Core. (אותם שמות).
אוטומציות / Workflows: כל ריצה עולה קרדיט בפני עצמה, בנוסף לכל אינטגרציה שנקראת בתוכה.
In-app agents: כל הודעה לסוכן עולה קרדיטים לפי המודל.
בנה טבלת מיפוי ובה לכל נקודת קריאה: השירות, המודל (ל-LLM), הפונקציה/המסך שבו הוא נמצא, האזור באפליקציה שאליו הוא שייך (feature: למשל analytics / creatives / alerts), ויחידת הכימות (תמונות / שניות וידאו / תווים / מיילים / העלאות).
שתי אזהרות במיפוי:
קריאות ל-API חיצוני עם מפתח משלך (לא דרך Base44) לא צורכות קרדיטי אינטגרציה - אל תספור אותן. למשל קריאה ישירה ל-Graph API של מטא או ל-fal.ai עם מפתח פרטי.
פעולות DB רגילות (קריאה/כתיבה ל-entities) לא עולות קרדיטים - אל תספור אותן.
הצג את טבלת המיפוי למשתמש ואשר איתו שהיא מלאה, לפני שממשיכים לבנייה.
טבלת העלויות (העתק מהדף הרשמי; אלה הערכות, לא מחיר סופי)
InvokeLLM: תלוי מודל. אוטומטי ~3, Gemini 3 Flash ~5, GPT-5 ~15. מודל שאינו בטבלה (למשל Opus) תמחר כשכבת פרימיום וסמן כהנחה.
GenerateImage: 1 לתמונה.
GenerateVideo: 5 לשנייה. (אם הקריאה לא מעבירה משך, זו ההערכה החלשה ביותר: קבע קבוע ASSUMED_VIDEO_SECONDS והצג אותו כהנחה.)
GenerateSpeech: 1 לכל 50 תווים (מקסימום 100 לקריאה).
SendEmail: 1 למייל (2 מדומיין מותאם אישית).
UploadFile: 1 להעלאה. ExtractDataFromUploadedFile: 1 לקריאה.
הרצת אוטומציה: 1 לריצה + כל אינטגרציה בתוכה בנפרד.
הבהרות מהדף: העלות מחושבת אחרי הריצה, אין תצוגה מקדימה של עלות, וההערכות משתנות. הצג הכול כ"הערכה" וקשר לדף האמת של Base44.

שלב 2: מודל נתונים
צור entity אחד, למשל CreditUsageEvent, עם השדות: integration (enum), feature (enum לפי אזורי האפליקציה), model (אופציונלי), quantity (ברירת מחדל 1), unit (enum: call/image/second/email/upload/character), estimated_credits (number), occurred_at (date-time), trigger (enum: manual/cron/backfill), source_entity + source_id (קישור לרשומת המקור לצורך ניווט), ו-dedup_key (למילוי היסטורי אידמפוטנטי). הגדר RLS: קריאה למי שרואה את הדף; כתיבה מוגבלת; מחיקה/עדכון למנהל בלבד.
שלב 3: Logger משותף (fire-and-forget)
מודול יחיד המחזיק את טבלת העלויות + פונקציה logUsage(client, event) ש: (א) מחשבת estimated_credits מהטבלה אם לא הועבר, (ב) קובעת occurred_at/unit/trigger כברירת מחדל, (ג) לעולם לא זורקת ולעולם לא חוסמת את הפעולה האמיתית - תיעוד כושל לא מפיל את מה שהוא מודד. בבקאנד השתמש ב-asServiceRole. אם הפלטפורמה בלי bundler (כמו Base44) - החזק מקור אמת אחד וסנכרן עותק לכל פונקציה צורכת.
שלב 4: חיווט כל נקודות הקריאה
הוסף שורת logUsage אחרי כל קריאה מוצלחת שמופתה בשלב 1. ל-LLM העבר את שם המודל; לווידאו את מספר השניות המשוער; למייל את מספר הנמענים בפועל; היכן שאפשר קשר ל-source_entity/source_id. שמור על חוזה השגיאות הקיים של האפליקציה (אל תשנה את מסלול ה-422/הצלחה).
שלב 5 (רשות): מילוי היסטורי (Backfill)
פונקציה חד-פעמית ואידמפוטנטית שמשחזרת אירועים מרשומות שכבר קיימות (למשל כל דוח/קריאייטיב מרמז אילו קריאות בוצעו), עם dedup_key יציב כדי שהרצה חוזרת לא תיצור כפילויות. סמן אירועים אלה כ-backfill והבהר שהם קירוב.
שלב 6: הדף עצמו
בורר טווח: 7 / 30 / 90 ימים / הכל.
כרטיסי סיכום: סה"כ קרדיטים משוער, מספר אירועים, השירות היקר ביותר, וחלק הווידאו מהסך.
שני פירוקים עם bars: לפי שירות ולפי אזור.
גרף עמודות של צריכה יומית.
טבלת אירועים אחרונים (מועד, אזור, שירות, פרטים, קרדיטים).
פאנל "הנחות החישוב" שמפרט במפורש כל הערכה (מודל ה-LLM, שניות הווידאו וכו').
קישור יוצא לדף App usage בלוח הבקרה של Base44 כמקור האמת לאימות.
כללי רוחב (לבדוק בכל שלב)
הבהרת "הערכה בלבד" בולטת בראש הדף: המספרים עוקבים אחרי הדשבורד אך אינם מדויקים לרמת הקרדיט.
הרשאות/RLS: ודא שמי שלא הוזמן לא רואה את הנתונים.
אם האפליקציה RTL/עברית: כל מחרוזת עוברת דרך מודול ה-labels; שימוש ב-logical properties בלבד; בדיקת רוחב מסך צר. עטוף גרפים ב-dir="ltr" (ספריות גרפים מניחות LTR).
גוצ'ה חשוב: Base44 מחזיר חותמות זמן ב-UTC בלי Z בסוף (למשל 2026-07-04T16:23:40.285000), ו-new Date() יפרש אותן כזמן מקומי ויטעה בשיוך התאריך. נרמל לפני פרסור: הוסף Z כשאין אזור זמן במחרוזת (פלט של toISOString() כבר כולל Z ולא נוגעים בו).
הגדרת "בוצע"
lint נקי, build עובר, כל מפתחות ה-labels שמוזכרים קיימים, אגרגציה נבדקה מול נתונים אמיתיים, ונקודת קריאה מייצגת אחת עדיין מחזירה את שגיאת הוולידציה הרגילה שלה (הוכחה שהתיעוד לא שבר כלום). בדיקה חזותית סופית מתבצעת בדפדפן מחובר של המשתמש.