מאזן הבית

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

יכולות עיקריות

• ייבוא קובצי XLS,‏ XLSX ו־CSV של בנקים וכרטיסי אשראי, כולל דוחות שנשמרו כ־HTML או כ־XML בשם ‎.xls.
• טעינת דוח כרטיס שואלת תחילה אם הכרטיס בנקאי או חוץ-בנקאי ומי הנפיק אותו — ויזה, כאל, ישראכרט, מקס, לאומי קארד, דיינרס או אמריקן אקספרס — ושומרת את שתי התשובות על התנועות.
• כל שורה בטבלת התנועות מציגה את מקורה: בנק, שם מנפיק הכרטיס, או „הזנה ידנית” לשורה שהוקלדה. שורה שיובאה בלי לציין מנפיק מציגה „כרטיס אשראי” ולא ניחוש.
• תמונת מצב חודשית, קטגוריות — כולל פנאי ובידור כקטגוריה נפרדת — תקרות תקציב וחיובים חוזרים.
• תחזית תזרים והמלצות פעולה לפי הנתונים שיובאו.
• „מצפן הוצאה” בראש הדשבורד: סכום פנוי אחד עד ההכנסה הבאה, עם יעד שבועי ויומי ותחשיב שקוף של היתרה פחות התחייבויות צפויות.
• שמונה סוכנים עצמאיים: שיוך לומד באישור, חריגות, חיובים חסרים, כפילויות, מנויים, הצעת תקציב, הזדמנויות לחיסכון וחישוב עד המשכורת הבאה.
• מסך קישורים לכלים רשמיים ולחברות המנהלות פנסיה, גמל, קרנות השתלמות ותיקי השקעות.
• ממשק מלא בעברית, אנגלית, אמהרית וצרפתית, כולל מעבר RTL/LTR.
• גיבוי ושחזור של הנתונים המקומיים.

שמונת הסוכנים הפיננסיים

כל הסוכנים מחושבים מחדש מהמידע המקומי ואינם שולחים תנועות לשירות חיצוני. התוצאות הן אינדיקציות לבדיקה ולא קביעות חשבונאיות.

1. סוכן שיוך לומד — לאחר ששתי תנועות בעלות תיאור מנורמל דומה שויכו ידנית לאותה קטגוריה, הוא מציע כלל טקסט חדש. הכלל נשמר רק לאחר לחיצה על „אישור הכלל”; השיוכים הידניים נשארים בעלי העדיפות הגבוהה ביותר.
2. סוכן חריגות — משווה את החיוב האחרון לחציון ההיסטורי של אותו בית עסק. הוא מציג חריגה כשהעלייה היא לפחות 30% וגם גבוהה ביותר מ־15% מהחיוב ההיסטורי הגבוה ביותר, לאחר שלושה חודשי היסטוריה לפחות.
3. סוכן חיובים חסרים — מחפש חיוב או הכנסה שהופיעו בשני חודשים לפחות, חסרים בחודש האחרון, ואיחרו ביותר מארבעה ימים מהמועד החודשי הטיפוסי שלהם.
4. סוכן כפילויות — מסמן שני חיובים מאותו בית עסק, בסכום זהה בקירוב, שנרשמו בהפרש של יום עד חמישה ימים. הסימון דורש בדיקה אנושית משום שחיובים דומים עשויים להיות לגיטימיים.
5. סוכן מנויים — מאתר חיובים עד ₪600 שהופיעו בשלושה חודשים לפחות ובעלי טווח סכומים יציב. הוא מציג עלות חודשית, עלות שנתית והתייקרות של 5% ומעלה.
6. סוכן תקציב מציע — מחשב לכל קטגוריית הוצאה את האחוזון ה־75 של עד שלושת החודשים האחרונים ומעגל את ההצעה ל־₪50. התקרה נשמרת רק לאחר אישור המשתמש.
7. סוכן הזדמנויות לחיסכון — מאחד מנויים לבדיקה, התייקרויות חוזרות, עמלות וכפילויות להזדמנויות מדידות. הוא מפריד בין פוטנציאל שנתי לחד־פעמי, מציג את מספר תנועות הראיה ואת ביטחון הזיהוי, ואינו מבטל שירות או מבטיח שהחיסכון יתממש.
8. סוכן עד המשכורת הבאה — מזהה את ההכנסה החודשית הקבועה הגדולה ביותר, מפחית מהיתרה את החיובים הקבועים הצפויים לפניה, ומציג את הסכום הפנוי. „מצפן ההוצאה” מתרגם אותו גם ליעד שבועי ויומי ומציג תחשיב נפתח; כשאין יתרה או הכנסה מזוהה הוא אומר זאת במפורש ואינו ממציא תחזית. יום הכנסה או חיוב שאינו קיים בחודש קצר, למשל 31 בפברואר, מוצמד ליום האחרון שקיים באותו חודש ואינו גולש לחודש הבא.

האלגוריתמים הטהורים והטיפוסים שלהם נמצאים ב־fe/src/financial-agents.ts. כל מנוע מממש FinancialAgentStrategy, והמחלקה FinancialAgentsOrchestrator מקבלת את האסטרטגיות ב־dependency injection ומחזירה תוצאה טיפוסית אחת; runFinancialAgents הוא Facade תואם לשכבת התצוגה. RuleBasedTransactionCategorizer מרכז את סדר הקדימויות: שיוך ידני, כלל מאושר, זיהוי הכנסה ולבסוף „אחר”. העברות בין חשבונות ומשיכה לחשבון מסווגות כ״חיסכון והעברות״, ומזונות היוצאים מסווגים בקטגוריה משלהם; מזונות שנכנסים הם הכנסה; תיאור לא מספק אינו מסווג בניחוש. שכבת התצוגה והאישור נמצאת ב־fe/src/app.ts. כלל שנלמד נשמר במערך rules; תקרת תקציב שאושרה נשמרת ב־budgets. הממצאים והזדמנויות החיסכון נגזרים מחדש ואינם נשמרים כמצב נוסף.

הפעלה מקומית

נדרשים Node.js,‏ npm ו־Python 3.12.

npm install
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
npm run build             # כולל strict typecheck לגבולות החדשים
npm run typecheck:strict  # בדיקת strict עצמאית

להרצת האתר דרך שרת מקומי:

ruby -run -ehttpd . -p 8765

לאחר מכן פותחים את http://127.0.0.1:8765/mazan-habait.html.

ניפוי שגיאות של האפליקציה

npm run debug

הפקודה מריצה את המהדר במצב --watch עם source maps ומעלה שרת סטטי על פורט 8765 (אם כבר רץ שרת על הפורט — למשל זה שנשאר מבדיקות הדפדפן — היא משתמשת בו במקום לנסות להאזין שוב). אפשר לשנות פורט באמצעות APP_PORT.

ה־source maps הם העיקר: בלעדיהם הדפדפן מציג את ה־JavaScript המהודר שב־dist/, ואי אפשר לשים breakpoint בקוד ה־TypeScript שנכתב בפועל. מכיוון שהשרת מגיש את שורש הפרויקט, dist/app.js.map מפנה אל fe/src/app.ts והדפדפן טוען את המקור המקורי — ב־DevTools ‏→ Sources ‏→ 127.0.0.1:8765 ‏→ fe/src/. שמירה של קובץ מהדרת מחדש; מספיק לרענן את הדף.

נקודות עצירה שימושיות לייבוא דוחות: handleFiles ב־fe/src/app.ts לבדיקת הקובץ שנבחר, readWorkbook ב־fe/src/spreadsheet-reader.ts כדי לראות לאיזה פורמט הקובץ נותב, ו־headerMap ב־fe/src/credit-card-importer.ts כדי לראות אילו עמודות זוהו.

קובצי ה־.map נשארים ב־dist/ בלבד, ש־gitignore מתעלם ממנו, ו־prepare-vercel-output מסנן אותם בעת ההעתקה ל־public/ כדי שקוד המקור לא ייארז לפריסה. הסינון מתבצע בהעתקה ולא במחיקה מ־dist/, כדי ש־npm run build לא ישבור סשן ניפוי שגיאות שרץ במקביל. עם זאת npm run build מהדר בלי source maps ולכן מסיר את הפניות ה־sourceMappingURL; כדי לחזור לנפות שגיאות מריצים שוב npm run debug.

לוגים

לשני הצדדים אותו פורמט רשומה — שורת JSON אחת לכל אירוע — כדי שאפשר יהיה לקרוא לוג של דפדפן ולוג של שרת יחד, למיין לפי ts ולהבחין ביניהם לפי source:

{"ts":"2026-08-28T09:15:00.000Z","level":"info","source":"web","event":"report.read","context":{"format":"xlsx","sheets":1,"rows":42}}

בדפדפן אין מערכת קבצים, ולכן הלוג הוא חוצץ טבעתי בזיכרון בגודל קבוע (500 רשומות; הישנות נדחקות החוצה) שגם נכתב ל־console. הוא זמין כ־window.__log, ומייצאים אותו מה־DevTools:

copy(__log.toText())   // כל הרשומות כ־JSON Lines, מוכן להדבקה בדוח תקלה
__log.setLevel('debug')

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗