# Locker Management System — Enhanced Feature Specification

**Scope:** Admin Panel Only (staff use only — members never log in)
**Hardware:** Physical lockers with traditional keys held by clients
**Notifications:** Email + SMS + WhatsApp
**Payments:** Cash / Manual + Local Bangladesh gateways (bKash, Nagad, SSLCommerz)
**Stack:** React (frontend) + Laravel (backend) + MySQL

This document takes your original feature list and adds the missing pieces a production-ready gym locker system needs. New features I'm suggesting are marked **[ADDED]**; features you already had are kept as-is or lightly expanded.

---

## 1. Client Management Module

### 1.1 Client Registration

Add new clients with complete details: Full Name, Phone Number, Email Address, National ID / Passport (optional), Address, Notes / Remarks.

**[ADDED] — recommended fields:**
- Profile photo upload (so staff can identify clients at the desk)
- Gender — important because gym lockers are zone-segregated (men's / women's / family)
- Date of Birth — useful for age-based pricing or analytics
- Emergency contact (name + phone)
- ID document photo upload (NID/Passport scan)
- Client signature capture (for terms acceptance)
- Membership/Plan tier reference if the gym uses tiered memberships
- Registration date (auto)
- Referred by (optional — useful for marketing analytics)

### 1.2 Client Profile Management

Edit client information, update contact details, delete or deactivate client accounts, view complete client history.

**[ADDED]:**
- Soft-delete (deactivate) vs. hard-delete — for compliance and audit, never permanently delete client records. Use status: Active / Inactive / Banned.
- Client blacklist / ban flag with reason (for clients who repeatedly lose keys, damage lockers, etc.)
- Tags/labels (e.g., "VIP", "Corporate", "Long-term")
- Internal notes timeline (staff can leave dated notes on a client)

### 1.3 Client Search & Filtering

Search by Name, Phone, Email, Locker Number. Advanced filters.

**[ADDED]:**
- Search by NID/Passport number
- Filter by status (Active / Inactive / Banned)
- Filter by gender / zone
- Filter by registration date range
- Filter by payment status (has dues / paid / overdue)

### 1.4 **[ADDED]** Bulk Import / Export

- Import existing client list from CSV/Excel during initial setup
- Export filtered client list to Excel/CSV

---

## 2. Locker Management Module

### 2.1 Locker Creation & Configuration

Create unlimited locker entries, assign unique locker numbers/IDs, define category/type (Small, Medium, Large).

**[ADDED]:**
- **Locker Zone / Section** — Men's, Women's, Family, Staff, VIP. This is essential for a gym and should drive which clients can be assigned (filter by client gender).
- **Floor / Room location** — useful for multi-floor gyms
- **Physical key identifier** — every locker has a key tag/number. Track which physical key belongs to which locker.
- Custom category beyond S/M/L (e.g., Day-use, Premium, Standard)
- Configurable pricing per category × duration

### 2.2 Locker Assignment

Assign lockers to specific clients, set assignment date and duration, auto-link locker with client profile.

**[ADDED] — Key Handling Workflow (critical for your physical-key setup):**
- **Key issued to client** — record that the physical key was handed over (timestamp + staff who handed it over)
- **Key returned by client** — record return on cancellation/expiry
- **Key deposit collected** — many gyms charge a refundable deposit for keys (e.g., ৳500). Track deposit amount and refund on key return.
- **Lost key reporting** — if client loses key, log incident, deduct from deposit or charge replacement fee, mark old key as compromised, issue new key/lock.
- Assignment requires gender-zone match (men's locker can only go to male client) — soft warning with override

### 2.3 Locker Status Tracking

Real-time availability: Available, Assigned, Expired, Maintenance.

**[ADDED]:**
- **Reserved** — held for a client who hasn't yet paid
- **Out of Service** — distinct from Maintenance (e.g., damaged beyond repair)
- **Cleaning** — short-lived status while cleaning between rentals

### 2.4 Visual Locker Dashboard

Grid-based locker visualization, color-coded status indicators, quick overview.

**[ADDED]:**
- Filter grid by zone, floor, size, status
- Click locker → see current client + history without leaving the grid
- Quick-action context menu on each locker tile (Assign / Release / Mark Maintenance)
- Optional floor-plan layout view (Phase 2)

### 2.5 Locker History & Audit

Track previous assignments, view client usage history, full activity records.

**[ADDED]:**
- Time-on-locker analytics (how long each rental lasted)
- Number of distinct clients per locker (turnover rate)

### 2.6 **[ADDED]** Bulk Locker Operations

- Bulk create lockers (e.g., "create 50 lockers, prefix M-, numbered 001-050, zone Men's, size Medium")
- Bulk status change (e.g., mark a whole row as Maintenance)

### 2.7 **[ADDED]** Maintenance & Incident Log

- Open a maintenance ticket against a locker (description, photo, priority)
- Track ticket status: Open / In Progress / Resolved
- Damage/incident report linked to client if applicable
- Maintenance history visible from locker detail page

### 2.8 **[ADDED]** Lost & Found / Abandoned Items Log

When a rental expires and the client doesn't return, staff need to open the locker and inventory the contents. Track:
- Items found (description + photos)
- Date locker was cleaned out
- Storage location for items
- Claim / disposal date

---

## 3. Expiry & Renewal Management

### 3.1 Expiry Date Management

Set custom expiry dates, auto-calculate rental duration.

**[ADDED]:**
- Standard duration presets: Daily, Weekly, Monthly, Quarterly, Half-yearly, Yearly
- Custom duration in days

### 3.2 Locker Renewal System

Renew anytime, extend expiry instantly, maintain renewal history.

**[ADDED]:**
- One-click renew (uses same duration as last term)
- Bulk renew for multiple clients at once
- Renewal carries over discount/pricing rules

### 3.3 Expired Locker Monitoring

Separate list for expired lockers, easy ID of overdue clients.

### 3.4 Upcoming Expiry Alerts

Dashboard alerts, automated reminder system.

**[ADDED]:**
- Configurable reminder schedule (e.g., 7 days before, 3 days before, on the day, 3 days overdue)
- Per-channel reminder rules (e.g., email at 7 days, SMS at 3 days, WhatsApp on day-of)

### 3.5 **[ADDED]** Grace Period

- Configurable grace period after expiry (e.g., 3 days) before locker is considered abandoned and contents moved to Lost & Found

---

## 4. Payment & Billing Module

### 4.1 Locker Pricing Management

Configure rental fees, different pricing per category.

**[ADDED]:**
- Pricing matrix: Category × Zone × Duration
- Discount rules (e.g., 10% off for yearly, 5% off for corporate clients)
- Promotional/coupon codes with expiry
- Tax/VAT configuration

### 4.2 Payment Tracking

Statuses: Paid, Due, Partial Paid, Overdue.

**[ADDED]:**
- Refunded
- Cancelled
- Pending (for online gateways awaiting confirmation)

### 4.3 Payment Collection Reports

Daily / monthly / yearly summaries.

### 4.4 Due Payment Reports

Pending dues, outstanding balance tracking.

### 4.5 Invoice & Receipt Generation

Professional invoices, printable receipts, PDF download.

**[ADDED]:**
- Configurable invoice numbering (prefix, starting number, format)
- Company logo, address, VAT/BIN number on invoice
- Bengali + English bilingual invoice support
- Auto-email invoice to client after payment

### 4.6 **[ADDED]** Payment Gateway Integration

- **Cash / Manual** — staff records cash received, system prints receipt
- **bKash Merchant API** — payment from client's bKash to gym's merchant account, with verification callback
- **Nagad** — similar merchant flow
- **SSLCommerz** — gateway aggregator covering cards + mobile banking + internet banking in Bangladesh
- Each transaction stores: gateway, transaction ID, reference number, status, raw response (for audit)

### 4.7 **[ADDED]** Deposit & Refund Management

- Separate ledger for key deposits (deposit is a liability, not revenue)
- Auto-prompt to refund deposit on key return
- Deduct lost-key fee from deposit before refund

### 4.8 **[ADDED]** Partial Payments & Payment Plans

- Accept partial payment with auto-tracking of remaining balance
- Optional installment schedule for long-duration rentals

---

## 5. Notification & Alert System

### 5.1 Client Registration Notification

Automatic email after registration.

**[ADDED]:** Also send welcome SMS / WhatsApp with gym info, hours, locker rules.

### 5.2 Locker Assignment Notification

Email upon assignment.

**[ADDED]:** Multi-channel — Email + SMS + WhatsApp with locker number, key number, expiry date, and gym hours.

### 5.3 Expiry Reminder Notifications

Automated reminders before expiry.

**[ADDED]:**
- Multi-stage reminders (configurable: 7d, 3d, 1d, on expiry, 3d overdue)
- Per-channel templates (SMS short, WhatsApp rich with payment link, email formal with invoice)

### 5.4 Admin Dashboard Alerts

Real-time expiry and due payment notifications.

### 5.5 **[ADDED]** Notification Templates Management

- Editable templates for each notification type (registration, assignment, reminder, payment, overdue)
- Variables/placeholders ({{client_name}}, {{locker_number}}, {{expiry_date}}, {{amount}})
- Bilingual templates (Bengali + English) with auto-selection based on client preference

### 5.6 **[ADDED]** Notification Delivery Log

- Track every notification sent (channel, recipient, content, status: sent/failed/delivered)
- Retry failed notifications
- Cost tracking for SMS/WhatsApp (these have per-message fees)

### 5.7 **[ADDED]** Gateway Configuration

- SMS gateway settings (e.g., SSL Wireless, Banglalink, Robi)
- WhatsApp Business API credentials
- SMTP / email settings

---

## 6. Reports & Analytics

### 6.1 Dashboard Statistics

Total Lockers, Assigned, Available, Expired, Due Payments, Total Revenue.

**[ADDED]:**
- Occupancy rate (%) overall and by zone
- Monthly revenue trend chart
- New clients this month
- Renewal rate (% of expiring rentals that get renewed)
- Top 10 longest-tenured clients

### 6.2 Report Export System

Export to Excel, PDF, CSV.

### 6.3 Financial Reporting

Revenue reports, payment history, due collection summaries.

**[ADDED]:**
- Revenue breakdown by zone / size / duration
- Payment method breakdown (cash vs. bKash vs. Nagad vs. SSLCommerz)
- Deposit ledger report
- Refund report
- Tax/VAT report (if applicable)

### 6.4 **[ADDED]** Operational Reports

- Locker utilization heatmap (which lockers get the most use)
- Maintenance frequency per locker (which lockers need replacement)
- Lost-key incidents per client (identifies problem clients)
- Average rental duration

### 6.5 **[ADDED]** Client Reports

- Client retention rate
- Inactive clients (eligible for re-engagement)
- Top-paying clients

---

## 7. Security & System Management

### 7.1 Activity Log System

Track all admin activities, login history, changes.

**[ADDED]:**
- IP address logging
- Browser/device info
- Filterable activity log (by user, by action type, by date range)
- Export activity log to CSV for audit

### 7.2 Data Backup & Recovery

Automatic database backup, restore functionality.

**[ADDED]:**
- Configurable backup schedule (daily/weekly)
- Offsite backup option (cloud storage upload)
- One-click restore from a backup point
- Backup retention policy (keep last N backups)

### 7.3 Secure Authentication

Admin login protection, password encryption, session management.

**[ADDED]:**
- **Two-Factor Authentication (2FA)** via SMS or authenticator app for admin login — strongly recommended even for admin-only systems
- Failed login attempt lockout (e.g., 5 failed → lock for 15 min)
- Password complexity rules + expiry policy
- Forced logout of all sessions on password change

### 7.4 Role-Based Access Control

Multiple admin roles, permission-based access.

**[ADDED] — recommend including in MVP, not as future upgrade:**
- Suggested roles:
  - **Super Admin** — everything including settings, user management, financial reports
  - **Manager** — everything except super-admin settings
  - **Front Desk / Receptionist** — register clients, assign lockers, collect payments, view their own activity
  - **Accountant** — view financial reports, no client/locker modification
- Granular permissions per module (view / create / edit / delete)

### 7.5 **[ADDED]** Data Privacy

- Client data export on request (NID, photos, all PII)
- Client data deletion request workflow with retention rules
- Consent log (when client agreed to T&Cs)

---

## 8. Additional Advanced Features

### 8.1 Responsive Admin Panel

Mobile, tablet, desktop friendly.

### 8.2 Dark / Light Mode UI

### 8.3 Advanced Search & Sorting

Smart filtering for clients, lockers, payments.

### 8.4 System Settings Panel

Configure: Company info, Currency, Email settings, Notification settings.

**[ADDED] settings:**
- Default timezone (Asia/Dhaka)
- Default language (Bengali / English)
- Working hours / holiday calendar
- Default locker rental durations + prices
- Reminder schedule (days before expiry)
- Grace period after expiry
- Key deposit amount
- Lost-key fee
- Tax/VAT rate
- Invoice numbering format

### 8.5 Multi-Branch Support (Future)

Manage multiple locations.

### 8.6 **[ADDED]** Quick Actions / Keyboard Shortcuts

For front-desk speed: "Cmd/Ctrl+K" → quick search any client, locker, payment. Front-desk staff handle dozens of clients an hour; this saves real time.

### 8.7 **[ADDED]** Bilingual UI (Bengali + English)

Toggle between Bengali and English in the admin panel. Important for Bangladeshi gyms where some staff are more comfortable in Bengali.

### 8.8 **[ADDED]** Printable Client Card

Generate a printable / QR-coded client card with name, photo, member ID, locker number — useful for the gym to issue as a physical card.

### 8.9 **[ADDED]** Terms & Conditions / Liability Waiver

Configurable T&C text shown at registration with a captured signature/timestamp for legal protection.

---

## 9. Suggested Module Structure (Backend)

This is the Laravel module organization that maps to the features above:

1. **Authentication Module** (Sanctum-based admin auth + 2FA)
2. **Dashboard Module**
3. **Client Management Module**
4. **Locker Management Module** (lockers, zones, keys, maintenance, lost & found)
5. **Rental & Renewal Module** (assignment lifecycle, expiry, grace period)
6. **Payment & Billing Module** (pricing, invoices, gateway integrations, deposits)
7. **Notification Module** (templates, multi-channel dispatcher, delivery log)
8. **Reports Module** (financial + operational + client reports + exports)
9. **Settings Module** (company info, pricing rules, reminder rules, gateways)
10. **User & Role Management Module** (RBAC)
11. **Activity Log Module**
12. **Backup Module**

---

## 10. Recommended Tech Stack (aligned with your project)

- **Frontend:** React 18 + Vite + TailwindCSS + a component library (recommend **shadcn/ui** or **Ant Design** — both have excellent admin/dashboard primitives)
- **State management:** React Query (server state) + Zustand or Context (UI state)
- **Forms:** React Hook Form + Zod for validation
- **Charts:** Recharts or Chart.js for analytics dashboards
- **Backend:** Laravel 11+ with PHP 8.2+
- **API:** REST JSON, versioned (`/api/v1/...`)
- **Authentication:** Laravel Sanctum (cookie-based SPA auth — see research doc for rationale)
- **Database:** MySQL 8 (or MariaDB)
- **Queues:** Laravel Queues (Redis driver) — essential for sending SMS/WhatsApp without blocking the UI
- **PDF Generation:** **barryvdh/laravel-dompdf** (simpler) or **Spatie Browsershot** (better Bengali font rendering — recommended)
- **Excel/CSV Export:** **Maatwebsite/Laravel-Excel**
- **Email:** SMTP or transactional service (SendGrid, Mailgun)
- **SMS:** SSL Wireless / Banglalink / Robi gateway integration via simple HTTP
- **WhatsApp:** WhatsApp Business Cloud API (Meta) or a BSP like Twilio
- **Payments:** Direct SDK integration for bKash Merchant API, Nagad, SSLCommerz
- **Backup:** **Spatie/Laravel-Backup** package — covers DB + files + cloud upload + scheduling
- **Activity Log:** **Spatie/Laravel-Activitylog**
- **RBAC:** **Spatie/Laravel-Permission**

(Your original list mentioned "PHP Laravel or Node.js" and "HTML, CSS, Bootstrap/Tailwind" — I've aligned everything above with your project setting of **React + Laravel**.)

---

## 11. Recommended Build Sequence

Don't build everything at once. Suggested phases:

**Phase 1 — Core MVP (4–6 weeks)**
Auth + RBAC, Clients, Lockers, Locker assignment + key tracking, Manual cash payments, Invoice/receipt PDF, Basic dashboard, Email notifications, Activity log.

**Phase 2 — Operations (2–3 weeks)**
Renewals + expiry reminders, SMS + WhatsApp notifications, Maintenance + Lost & Found, Bulk operations, Advanced reports + exports.

**Phase 3 — Online Payments (2 weeks)**
bKash + Nagad + SSLCommerz integration, deposit ledger, refunds.

**Phase 4 — Polish (1–2 weeks)**
Dark mode, bilingual UI, keyboard shortcuts, backup automation, 2FA, printable client cards.

**Phase 5 — Future**
Multi-branch, floor-plan view, smart-lock hardware (if ever needed), member self-service portal.

---

## Summary of What I Added

The most important suggested additions to your original list:

The first and biggest is **physical key management** (deposit, issue, return, lost-key handling) — your business model uses physical keys, so this needs its own first-class workflow.

Second, **gender-segregated zones** for lockers since this is a gym — without this, the system can't correctly enforce men's vs. women's locker rooms.

Third, **multi-channel notifications** (Email + SMS + WhatsApp) with delivery logging and templates, since you confirmed all three channels matter for the Bangladeshi market.

Fourth, **local payment gateways** (bKash, Nagad, SSLCommerz) properly integrated with transaction logging and deposit ledger separated from revenue.

Fifth, **RBAC in MVP** rather than future scope — even a small gym has more than one staff member, and you don't want the receptionist seeing financial reports or deleting clients.

Sixth, operational features your list was missing: **maintenance tickets, lost & found, bulk operations, grace period, partial payments, 2FA, bilingual UI, and printable client cards** — all things a real gym front desk needs day-to-day.
