plan-apartmentBilling

Prompt file imported from YehuditHub/apartment-billing (.github/prompts/plan-apartmentBilling.prompt.md). Copyright stays with the author.

Plan: אפליקציית ניהול חיובים לדירות עם Excel גנרי

נבנה אפליקציית Streamlit מקומית בקובץ Python אחד, עם שמירה ל-Excel יחיד (data.xlsx) במבנה Append-Only, כולל גיליון מרכזי לכל ישות עסקית וגם גיליון נפרד לכל דירה לצורך ניידות עתידית למערכות אחרות. ה-UI יכוון ל-3 זרימות מרכזיות: הגדרות, עדכון תעריפים/חיובים קבועים, ועדכון חודשי עם חישוב מים והפקת חשבונות.

✅ סטטוס ביצוע

בוצע:

• ✅ Phase 1 - תשתית קובץ והרשאות נתונים (הושלם)

  • יצירת app.py עם מבנה מלא
  • אתחול data.xlsx עם כל הגיליונות
  • מנגנון יצירת גיליון לכל דירה
  • סכמות עמודות בעברית
  • פונקציות Append-Only

• ✅ Phase 2 - מודל עסקי וכללי ולידציה (הושלם)

  • מודל דירות מלא
  • ולידציה של תפקידי דירות
  • ולידציית קריאות ותעריפים

• ✅ Phase 3 - לוגיקה עסקית מלאה (הושלם)

  • חישוב תעריף לפי תאריך
  • חישוב צריכה
  • לוגיקת מים מיוחדת
  • דירה ראשית
  • חיובים קבועים וחיובים לפי דירה
  • generator לחשבון חודשי

• ✅ Phase 4 - UI לפי הזרימה (הושלם)

  • עמוד הגדרות
  • עמוד תעריפים וחיובים
  • עמוד עדכון חודשי
  • עמוד חשבונות והיסטוריה
  • עמוד תצוגת דירה

• ✅ Phase 5 - מבנה גיליון לכל דירה (הושלם)

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

• ✅ Phase 6 - בדיקות ואימות (הושלם)

  • יצירת מסמך בדיקות מפורט (TESTING.md)
  • רשימת בדיקות מקיפה
  • הוראות הפעלה (README.md)
  • תיעוד מערכת

קבצים שנוצרו:

• ✅ app.py - אפליקציית Streamlit מלאה עם הערות בעברית (1,012 שורות)
• ✅ requirements.txt - תלויות הפרויקט
• ✅ README.md - מדריך שימוש מפורט והוראות הפעלה
• ✅ INSTALL.md - הוראות התקנה והפעלה מהירה
• ✅ TESTING.md - מסמך בדיקות מקיף עם 13 בדיקות מפורטות
• ✅ TECHNICAL_NOTES.md - הסברים מפורטים על כל פונקציה ראשית בקוד
• ✅ .gitignore - הגנה על קובץ הנתונים
• ⏳ data.xlsx - ייווצר אוטומטית בהרצה ראשונה

שגיאות שתוקנו:

• ✅ תוקנה שגיאת indentation בפונקציה get_tariff_by_date() (שורה 361)
• ✅ כל השגיאות הסינטקטיות תוקנו - הקוד מוכן להרצה

הוראות הפעלה:

# 1. התקנת תלויות
pip install -r requirements.txt

# 2. הרצת האפליקציה
streamlit run app.py

# 3. פתיחת הדפדפן בכתובת
http://localhost:8501

Steps

1. Phase 1 - תשתית קובץ והרשאות נתונים.

2. יצירת אפליקציה בקובץ יחיד עם חלוקה פנימית: סכמות, שירותי Excel, לוגיקה עסקית, עמודי UI, router.

3. אתחול data.xlsx עם הגיליונות הנדרשים: דירות, קריאות מונים, תעריפים, חיובים קבועים, חיובים לפי דירה, חשבונות.

4. הוספת מנגנון יצירת גיליון לכל דירה בעת יצירה, ובנוסף יצירת גיליון חדש בכל שינוי שם/תיאור דירה (פורמט מזהה+שם, לדוגמה 001_רוטשילד). בעת יצירת גיליון חדש מועתקת אוטומטית קריאת המונה האחרונה מהגיליון הקודם כרשומת פתיחה לחישוב הבא.

5. הגדרת סכמות עמודות בעברית בלבד לכל הגיליונות המרכזיים + סכמת גיליון דירה.

6. בניית פונקציות Append-Only בלבד: קריאה, סינון, הוספת שורות; ללא עדכון מקום (in-place) לרשומות היסטוריות.

7. Phase 2 - מודל עסקי וכללי ולידציה.

8. מודל דירות גנרי בשליטת משתמש: שם/תיאור דירה, סימון דירת בעלים, סימון דירה ראשית (ללא מונה נפרד), סטטוס מונים.

9. ולידציה של תפקידי דירות: בדיוק דירת בעלים אחת ובדיוק דירה ראשית אחת.

10. ולידציית קריאות: איתור קריאה קודמת, חישוב צריכה חודשית, טיפול בהיעדר קריאה קודמת, מניעת כפילויות תאריך/מונה/דירה.

11. ולידציית תעריפים וחיובים: תוקף תעריף לפי תאריך, סכומים לא שליליים, טווחי תוקף תקינים.

12. Phase 3 - לוגיקה עסקית מלאה (תלוית Phases 1-2).

13. מימוש tariff by date: בחירת התעריף האחרון התקף לתאריך סוף חודש חיוב.

14. מימוש חישוב צריכה לפי מונה: current - previous לכל סוג מונה.

15. מימוש לוגיקת מים מיוחדת:

16. owner_cost = owner_usage * low_tariff.

17. remaining_payment = total_payment - owner_cost.

18. remaining_usage = total_usage - owner_usage.

19. other_tariff = remaining_payment / remaining_usage עם הגנות לחלוקה באפס.

20. מימוש דירה ראשית: main_usage = total_usage - sum(other_apartments_usage) עבור מים בלבד, כולל התראה אם יוצא שלילי.

21. מימוש חיובים קבועים גלובליים לפי טווח תאריכים.

22. מימוש חיובים לפי דירה:

23. חיוב חד-פעמי לדירה (למשל חוב ישן).

24. חיוב קבוע לדירה ספציפית לפי טווח (למשל ארנונה גבוהה יותר לדירה גדולה).

25. מימוש generator לחשבון חודשי פר דירה: שימושים + תעריפים + מים מיוחדים + חיובים קבועים גלובליים + חיובים ייעודיים לדירה.

26. שמירת snapshot לחשבון בגיליון חשבונות, ובנוסף append לשורת סיכום בגיליון הדירה.

27. Phase 4 - UI לפי הזרימה שביקשת.

28. Sidebar עם כפתורים:

29. הגדרות: ניהול דירות, שמות/תיאורים, סימון דירת בעלים ודירה ראשית.

30. תעריפים וחיובים קבועים: הוספת/עדכון תעריפים והוספת חיובים קבועים עם שם חיוב.

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

32. חשבונות והיסטוריה: טבלת חשבונות חודשיים כולל חיובים קבועים וחיובים לפי דירה.

33. עמוד/תצוגת דירה: בחירת דירה והצגת נתוני גיליון הדירה.

34. Phase 5 - מבנה גיליון לכל דירה (Export-friendly).

35. כל גיליון דירה יכיל שורות Append-Only עם שדות עבריים אחידים:

36. מזהה רשומה, דירה מזהה, חודש חיוב, שנת חיוב, סוג רשומה (מונה/חיוב/סיכום), סוג מונה, קריאה קודמת, קריאה נוכחית, צריכה, תעריף, סכום, תיאור, תאריך יצירה.

37. בכל עדכון חודשי, נרשמות בגיליון הדירה:

38. שורת קריאת מים/חשמל (אם קיימת),

39. שורות חיובים נוספים (חד פעמי/קבוע),

40. שורת סיכום חיוב חודשי.

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

42. Phase 6 - בדיקות ואימות.

43. בדיקת זרימה מלאה: יצירת דירות, תעריפים, חיובים קבועים, קריאות חודשיות, הפקת חשבונות.

44. אימות שקיפות: סכום חיובי מים בדירות שווה לחשבון המים הכולל (בכפוף לעיגול).

45. אימות היסטוריה: שינוי תעריף בעתיד לא משנה חשבונות עבר.

46. אימות דפי דירה: לכל דירה קיים גיליון ייעודי עם סיכום חיובים, קריאות מונים, ופירוט חיובים נוספים.

Relevant files

• app.py — קובץ ריצה יחיד של Streamlit (UI + לוגיקה + Excel I/O).
• data.xlsx — מסד הנתונים המקומי בגיליונות מרכזיים + גיליונות דירה.

Verification

1. להריץ Streamlit ולאשר שכל כפתורי הסיידבר עובדים ושומרים נתונים.
2. להוסיף שתי דירות לפחות, לסמן בעלים וראשית, ולאשר חוקיות ההגדרות.
3. להזין קריאות חודשיות ולהשוות חישובי צריכה מול קריאה קודמת.
4. להזין חשבון מים כולל + low tariff ולאשר תמחור בעלים/אחרים לפי הנוסחה.
5. להוסיף חיוב חד-פעמי לדירה וחיוב קבוע לדירה אחרת ולאשר הכללה בחשבון החודשי.
6. לאשר הופעת חיובים קבועים גם בתצוגה החודשית וגם בחשבונות.
7. לפתוח את Excel ולאשר קיום גיליון לכל דירה עם נתוני מונים וחיובים.

Decisions

• חשמל מחושב בתעריף רגיל לפי צריכה (ללא לוגיקת חלוקה מיוחדת).
• חישוב דירה ראשית חל על מים בלבד.
• שינוי תעריף בתוך חודש: נלקח תעריף סוף חודש.
• גיליון דירה ייקרא בפורמט מזהה+שם (לדוגמה 001_רוטשילד); בשינוי שם/תיאור תיווצר לשונית חדשה לדירה, עם העתקת קריאה אחרונה כבסיס לחישובים הבאים.
• גיליון דירה יכלול: סיכום חיובים חודשי, קריאות מונים, ופירוט חיובים נוספים (חד פעמי/קבוע).

Further Considerations

1. מדיניות עיגול: עיגול ל-2 ספרות ושורת התאמה אוטומטית אם נוצר הפרש אגורות.
2. מומלץ מזהים מסוג UUID לרשומות append-only כדי למנוע התנגשויות עתידיות.
3. הרחבה עתידית אפשרית: יצוא PDF לחשבון דירה לאחר ייצוב גרסה ראשונה.