ماژول «حضور و غیاب و مرخصی»

ما قصد داریم یک ماژول حضور و غیاب و مرخصی توسعه بدیم به‌صورت MVP. قابلیت‌ها شامل: • ثبت ورود/خروج پرسنل بر اساس موقعیت (Geofence) یا دورکاری. • تعریف شیفت و دفتر توسط ادمین. • ثبت و تأیید/رد مرخصی (روزانه/ساعتی). • گزارش روزانه وضعیت حضور (برای ادمین و مدیر تیم). • ارسال SMS هشدار برای دیرکرد یا عدم ثبت ورود. MVP: سند MVP ماژول «حضور و غیاب و مرخصی» هدف پیاده‌سازی یک سرویس بک‌اند برای مدیریت حضور و غیاب و درخواست‌های مرخصی شامل: • ثبت ورود/خروج (با Geofence یا دورکاری) • مدیریت شیفت و دفاتر • ثبت و تأیید/رد مرخصی • گزارش وضعیت روز • ارسال SMS هشدار برای دیرکرد یا عدم ثبت ورود ⸻ 1) نقش‌ها و دسترسی‌ها • کاربر (User): • ثبت ورود/خروج خودش (فقط وقتی در محدوده دفتر یا Remote). • ثبت درخواست مرخصی. • مشاهده تاریخچه 7 روز اخیر و وضعیت مرخصی‌های خودش. • مدیر تیم (Manager): • مشاهده وضعیت حضور اعضای تیمش. • تأیید یا رد درخواست مرخصی اعضای تیم. • دریافت SMS وقتی یکی از اعضا دیر کرده یا ورود نزده. • ادمین/مالک (Admin/Owner): • مدیریت دفاتر (Office) و شیفت‌ها (Shift). • انتساب شیفت به کاربران. • مشاهده گزارش وضعیت کل سازمان. • تأیید/رد همه درخواست‌های مرخصی. • دریافت SMS برای کل سازمان (اختیاری). ⸻ 2) قابلیت‌های اصلی الف) حضور و غیاب • ورود/خروج فقط در محدوده دفتر فعال است (Geofence: lat/lng + radius). • اگر کاربر خارج از محدوده باشد → دکمه‌ها غیرفعال. • بعد از ورود → فقط دکمه خروج فعال. • بعد از خروج → هیچ دکمه‌ای فعال نیست. • حالت «دورکاری» (Remote) → دکمه‌های ورود/خروج فعال بدون Geofence. • رویدادها ذخیره می‌شوند با زمان و نوع (GPS/Wi-Fi/Beacon/Remote). ب) مرخصی • درخواست مرخصی روزانه (Date Range) یا ساعتی (Date + از/تا). • وضعیت: PENDING → APPROVED → REJECTED. • مدیر فقط مرخصی اعضای تیم خودش را می‌تواند تأیید یا رد کند. • ادمین همه را می‌تواند مدیریت کند. • در بازه مرخصی تأییدشده → ورود/خروج بلاک می‌شود. ج) شیفت‌ها • تعریف شیفت: نام، ساعت شروع/پایان، روزهای هفته، Grace (مهلت تأخیر). • انتساب شیفت به کاربر (ادمین) یا تیم (ادمین). • کاربران فقط شیفت خود را می‌بینند. • بر اساس ساعت شروع + Grace وضعیت «به‌موقع/دیرکرد» محاسبه می‌شود. د) دفاتر • تعریف دفتر با lat/lng + radius. • حضور کاربران فقط در شعاع معتبر قابل‌ثبت است. • MVP: فقط دایره‌ای (Polygon در آینده). هـ) گزارشات • ادمین: تعداد کل کاربران، تعداد به‌موقع، تعداد دیرکرد، تعداد غیبت. لیست کاربران با وضعیتشان. • مدیر: فقط برای تیم خودش. • کاربر: فقط تاریخچه 7 روز اخیر خودش. و) SMS Service • عدم ثبت ورود: اگر کاربر تا 10 دقیقه بعد از شروع شیفت ورود نزده باشد → SMS به کاربر و مدیرش. • دیرکرد: اگر ورود بعد از ساعت شروع + Grace باشد → SMS به کاربر و مدیرش. • مدیر فقط پیام اعضای تیمش را دریافت می‌کند. • همه پیام‌ها در جدول sms_logs ذخیره می‌شوند. • هر پیام فقط یک‌بار در روز برای هر وضعیت ارسال می‌شود (Anti-Spam). ⸻ 3) مدل داده (اصلی) • Users (id, name, role, team_id, …) • Teams (id, name, manager_id) • Offices (id, name, lat, lng, radius) • Shifts (id, name, start_time, end_time, days, grace_min, office_id) • User_Shifts (id, user_id, shift_id, valid_from, valid_to) • Attendance_Events (id, user_id, office_id, type=CHECK_IN/OUT, mode=ONSITE/REMOTE, ts, …) • Leave_Requests (id, user_id, kind=DAILY/HOURLY, date_from, date_to, time_from, time_to, status, reviewed_by, …) • SMS_Logs (id, user_id, type=PENDING/LATE, sent_to, sent_at, status) ⸻ 4) API (خلاصه) Auth • POST /auth/login → JWT حضور • POST /attendance/check-in (کاربر خودش) • POST /attendance/check-out (کاربر خودش) • GET /attendance/today?user_id=me (کاربر خودش) • GET /admin/attendance/today?team_id=... (مدیر/ادمین) مرخصی • POST /leave-requests (کاربر) • GET /leave-requests?user_id=me • GET /admin/leave-requests?team_id=... (مدیر/ادمین) • POST /admin/leave-requests/{id}/approve • POST /admin/leave-requests/{id}/reject شیفت • POST /shifts (ادمین) • GET /shifts • POST /user-shifts (ادمین) • GET /user-shifts?user_id=... دفاتر • POST /offices (ادمین) • GET /offices ⸻ 5) Business Rules • دکمه‌های ورود/خروج فقط داخل محدوده فعال‌اند. • خارج محدوده: همیشه غیرفعال. • مرخصی Approved → حضور بلاک. • Idempotency برای Check-in/out (کلید یکتا). • SMS برای عدم ورود: 10 دقیقه بعد از شروع شیفت. • SMS دیرکرد: ورود بعد از start+grace. • مانع اسپم: هر پیام یک‌بار در روز. ⸻ 6) پذیرش (Acceptance Criteria) • کاربر خارج محدوده نمی‌تواند ورود/خروج بزند. • کاربر در بازه مرخصی تأییدشده نمی‌تواند ورود/خروج بزند. • SMS به کاربر و مدیر درست ارسال می‌شود در صورت عدم ورود یا دیرکرد. • مدیر فقط درخواست‌های تیم خودش را می‌تواند تأیید/رد کند. • ادمین همه‌چیز را مدیریت می‌کند (شیفت، دفتر، گزارش، مرخصی). • گزارش ادمین شامل تعداد کل، به‌موقع، دیرکرد، غایب است. ⸻ 7) تکنیکال MVP • زبان: Node.js/Go/Python (انتخاب پیمانکار). • پایگاه‌داده: Postgres. • Auth: JWT + RBAC. • مستندات: OpenAPI/Swagger. • استقرار: Docker Compose.