נוכחות מעלה גמלא

מערכת ניהול לחינוך הבלתי פורמלי במושב מעלה גמלא: סימון נוכחות מבוסס אירועים, לוז יומי מובנה (כולל סידור אוטומטי עם AI), ודוחות. Next.js 14 (App Router) + Prisma + Postgres (Neon) + Auth.js + Tailwind. עברית מלאה ב-RTL, mobile-first.

מה יש במערכת

מסך	מה עושים בו
/login, /register	התחברות עם אימייל+סיסמה. הרשמה עצמית מוגנת בקוד צוות (SIGNUP_CODE).
/events	רשימת האירועים (קייטנות, ימי פעילות), יצירה ומחיקה.
/events/new	אירוע חדש: שם, טווח תאריכים, כלול שישי/שבת, ובחירת המשתתפים.
/events/[id]	לב המערכת — לכל יום: נוכחות (נוכח/איחור/נעדר), לוז, ותיאור. וכן עריכת האירוע וניהול המשתתפים בו.
/roster	רשימת כל הילדים (שם + כיתה) והקבוצות. ילד יכול להיות בכמה קבוצות.
/admin	מנהל/ת בלבד — תפקידי משתמשים, וסל מחזור לשחזור אירועים וילדים שנמחקו.
/history	כל יום שנרשמה בו נוכחות, עם סיכום.
/reports	דוח לפי ילד/ה: נוכח/איחור/נעדר ואחוז הגעה על פני כל האירועים.

דגשים:

• שני תפקידים: admin ו-staff. מחיקת אירוע, מחיקת ילד/ה, שחזור ושינוי תפקידים — מנהל/ת בלבד. כל השאר פתוח לכל הצוות.

• מחיקה היא רכה. אירוע או ילד/ה שנמחקו נעלמים מכל המסכים אבל הנתונים נשמרים, ומנהל/ת משחזר/ת אותם מ-/admin.

• נוכחות נשמרת מיידית בכל לחיצה, עם markedByUserId.

• עובד בלי קליטה: סימון בשטח נכנס לתור מקומי ונשלח כשהחיבור חוזר. המסך אומר תמיד מה המצב — "✓ נשמר", "שומר…", או "אין חיבור · N ממתינים". אפשר להתקין את האפליקציה למסך הבית (PWA).

• יום האירוע נפתח על היום הנוכחי (או הקרוב לו), לא על היום הראשון.

• בכל יום יש סיכום חי — נוכחים/איחורים/נעדרים/לא סומנו, אפשרות להציג רק את מי שלא סומן, וכפתור "סמן את הנותרים כנעדרים".

• עריכת אירוע: שינוי שם או טווח תאריכים מוסיף ימים חסרים. יום שכבר יש בו נוכחות או לוז לא יימחק גם אם הוא מחוץ לטווח החדש.

• ייצוא ל-Excel / Google Sheets: כל האירוע (/api/events/[id]/export) או יום בודד (/api/event-days/[id]/export) — .xlsx צבעוני ב-RTL, ממוין לפי כיתה.

• מיון לפי כיתה (א→ב→ג…) בכל הרשימות, אוטומטית.

• סידור לוז עם AI: כותבים תיאור חופשי או מצרפים קובץ (טקסט/PDF) ו-Claude ממיר ללוז מסודר. עובד רק אם ANTHROPIC_API_KEY מוגדר; בלעדיו שאר המערכת עובדת כרגיל.

הרצה מקומית

cp .env.example .env         # מלאו DATABASE_URL / DIRECT_URL / AUTH_SECRET
npm install
npm run prisma:generate
npm run prisma:migrate       # יוצר את הטבלאות
npm run seed                 # משתמש צוות ראשון + קבוצת דוגמה
npm run dev                  # http://localhost:3000

AUTH_SECRET אפשר לייצר עם openssl rand -base64 32.

בהרצה מקומית של build (npm run build && npm start, להבדיל מ-npm run dev) יש להגדיר גם AUTH_TRUST_HOST=true, אחרת Auth.js יחזיר UntrustedHost. ב-Vercel זה מזוהה אוטומטית.

בדיקות

npm test         # vitest — הלוגיקה הטהורה (תאריכים, מיון כיתות, ייצוא)
npm run lint
npm run typecheck

משתמשים והרשאות

• הרשמה עצמית — /register עם קוד הצוות (SIGNUP_CODE). כל נרשם/ת מקבל/ת staff. זו הדרך הרגילה להוסיף אנשים.

• seed — npm run seed יוצר/מעדכן את המשתמש מ-SEED_ADMIN_* כ-admin.

• מינוי מנהל/ת נוסף/ת — מ-/admin, על ידי מנהל/ת קיים/ת. שינוי התפקיד נכנס לתוקף מיד, בלי שהמשתמש/ת צריך/ה להתחבר מחדש (התפקיד נקרא מה-DB בכל פעולה רגישה, לא מה-token). הקישור ל-/admin בתפריט מופיע רק אחרי התחברות מחדש, אבל אפשר פשוט לגשת לכתובת.

• מאיפה מגיע המנהל/ת הראשון/ה — המיגרציה add_roles_soft_delete_contacts מקדמת את החשבון הוותיק ביותר ל-admin, כדי שמערכת שכבר רצה לא תישאר בלי אף מנהל/ת. אם צריך בכל זאת ידנית, ב-SQL Editor של Neon:

  UPDATE "User" SET role = 'admin' WHERE email = '[email protected]';
  

---

פריסה (Deployment)

הריפו הוא שורש האפליקציה — אין צורך בהגדרת Root Directory ב-Vercel.

1. Vercel + Neon Postgres

1. ב-vercel.com → Add New → Project → יבוא הריפו.
2. Storage → Create Database → Neon (Postgres) וחברו לפרויקט.
3. הגדירו את משתני הסביבה (Settings → Environment Variables) לפי הטבלה למטה. שינוי משתנה סביבה דורש Redeploy.

2. מיגרציות

רצות אוטומטית בכל build (prisma generate && prisma migrate deploy && next build). ידנית מול ה-DB של Neon: npm run prisma:deploy.

⚠️ שימו לב: Vercel מריץ את ה-build גם ל-preview של כל PR. כלומר מיגרציה בתוך PR מוחלת על בסיס הנתונים שה-preview מוגדר אליו — לפני סקירה ולפני מיזוג. אם משתני הסביבה מוגדרים ל-"All Environments" (ברירת המחדל), זה הפרודקשן. מיגרציה הרסנית ב-PR כלשהו תפגע בנתונים החיים לפני שמישהו הספיק להסתכל. מומלץ להגדיר ל-Preview בסיס נתונים נפרד (Neon תומך ב-branching). פירוט ב-docs/ROADMAP.md.

3. משתני סביבה

משתנה	חובה	תיאור
DATABASE_URL	✓	Postgres pooled — לשימוש הרגיל של האפליקציה
DIRECT_URL	✓	חיבור ישיר (non-pooled) — למיגרציות Prisma
AUTH_SECRET	✓	סוד לחתימת ה-session של Auth.js
SIGNUP_CODE	−	קוד צוות ל-/register. בלעדיו ההרשמה סגורה.
ANTHROPIC_API_KEY	−	לסידור הלוז עם AI
AI_MODEL	−	ברירת מחדל claude-opus-5; אפשר מודל זול יותר
SEED_ADMIN_*	−	אימייל/סיסמה/שם למשתמש הראשון (ל-seed בלבד)

---

החלטות טכניות

• סיסמה במקום magic link — Credentials + bcrypt, בלי צורך ב-SMTP. לכן נוסף passwordHash ל-User. ה-session מסוג JWT.
• role נשאר String עם ברירת מחדל "staff" — הוספת "parent" בעתיד לא דורשת שינוי מבני. כרגע אין הפרדת הרשאות: כל חשבון צוות יכול הכול.
• נוכחות רק דרך אירועים. המודל AttendanceRecord הוא שריד מהגרסה הראשונה (יום יומי עצמאי) ונשאר רק כדי לא למחוק נתונים היסטוריים.
• תאריכים נשמרים כ-@db.Date ומנורמלים לחצות UTC, כדי שאותו "YYYY-MM-DD" תמיד ייתן את אותו יום. "היום" מחושב לפי אזור הזמן Asia/Jerusalem ולא לפי השעון של השרת (ב-UTC, חצות בישראל היא עדיין אתמול).
• Cascade delete — מחיקת אירוע מוחקת את ימיו ואת הנוכחות שלהם; מחיקת ילד מוחקת את רשומות הנוכחות שלו. מחיקת קבוצה לא מוחקת ילדים (שיוך many-to-many). markedBy הופך ל-null אם המשתמש נמחק, כדי לשמור את ההיסטוריה.
• שגיאות API עוברות דרך src/lib/api-error.ts, כדי שרשומה שנמחקה תחזיר 404 ולא 500 עם stack trace.