Clinic Management System

=== Clinic Management System === Contributors: ahmadalfaisal Tags: attendance, clock-in, staff, clinic, time-tracking, kiosk, cleaning, checklists Requires at least: 5.8 Tested up to: 6.6 Requires PHP: 7.4 Stable tag: 2.0.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html

A complete clinic management system. Staff clock in/out from a frontend kiosk page, complete and submit room checklists, and admins view reports in wp-admin.

== Description ==

Clinic Management System is a self-contained WordPress plugin that provides a complete management system for clinics: staff attendance tracking and room checklists.

Key Features:

• Frontend kiosk page via shortcode [clinic_staff_attendance]
• Employee login using employee code + 4-digit PIN (no WordPress user account needed)
• Clock In, Start Break, End Break, and Clock Out actions
• Live clock, worked-time counter, and activity log on the kiosk screen
• Room Checklists — digitised clinic room checklists for employees
• Employees complete exact room/checklist/task forms on a phone, tablet, or desktop
• Checklist runs are linked to the employee's active shift and stored with task snapshots for accurate audit history
• Manager reports in wp-admin: filter by date, employee, room, and checklist section
• CSV export of the filtered checklist report
• Admin dashboard with today's attendance summary
• Employee management (add, edit, deactivate, reset PIN)
• Attendance records viewer with filters
• Reports: daily, weekly, monthly, and custom date range
• Export reports to CSV (Excel-compatible) and PDF (print)
• Brand-color styling (#fcf3da, #122269, #c1a355)
• Responsive, tablet-friendly, touch-optimized UI
• Dark mode support
• Secure: PINs hashed with bcrypt, nonce validation, capability checks

== Installation ==

1. Download the plugin zip file.
2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Choose the clinic-staff-attendance.zip file and click Install Now.
4. Activate the plugin.
5. The plugin automatically creates its custom database tables on activation.

No external dependencies required. The plugin works out of the box.

== Setup & Usage ==

Step 1: Create a Kiosk Page

1. Go to Pages → Add New.

2. Title it "Staff Clock" (or similar).

3. In the content area, add the shortcode:

   [clinic_staff_attendance]

4. Publish the page.

5. The page is now accessible at /staff-clock (or your chosen slug).

Step 2: Add Employees

1. Go to Attendance → Employees in the WordPress admin menu.

2. Click Add Employee.

3. Fill in:

   • Full Name — e.g., "Jane Smith"
   • Employee Code — e.g., "EMP001" (used for login)
   • 4-Digit PIN — e.g., "1234"

4. Click Save Employee.

5. Provide the employee with their employee code and PIN.

Step 3: Staff Clock In / Out

1. Staff members visit the kiosk page (e.g., /staff-clock).
2. Enter their Employee Code and 4-digit PIN.
3. Click Sign In.
4. After signing in they see:
   • Their name and a live clock.
   • Status indicator (Working / On Break / Clocked Out).
   • Time worked today.
   • Action buttons: Clock In, Start Break, End Break, Clock Out (only relevant actions appear).
   • Today's activity log.
5. They tap the appropriate button to clock in, take a break, or clock out.

Step 4: View Reports (Admin)

1. Go to Attendance → Reports.
2. Select a period: Daily, Weekly, Monthly, or Custom.
3. Optionally filter by a specific employee.
4. Click Generate.
5. The report shows per-employee, per-day:
   • First clock-in time
   • Last clock-out time
   • Total worked time (breaks deducted)
   • Total break time
   • Event count
   • Warnings for incomplete or bad sequences

Step 5: Export Reports

1. On the Reports page, after generating a report, click:
   • Export CSV — downloads a CSV file that opens in Excel, Google Sheets, etc.
   • Export PDF — opens a printer-friendly page; use your browser's "Save as PDF" to save.

Step 6: Dashboard & Records

• Dashboard — view today's attendance overview (active employees, currently working count, events today).
• Records — browse all raw attendance events, filterable by employee and date range.

Step 7: Settings

• Go to Attendance → Settings to change:
  • Company / Clinic name (displayed on dashboard and kiosk).
  • Break reminder minutes (reserved for future notifications).

Step 8: Room Checklists

1. Go to Pages → Add New.

2. Title it "Room Checklists" (or similar).

3. In the content area, add the shortcode:

   [clinic_cleaning_checklists]

4. Publish the page.

Employee workflow:

1. Employees open the checklist page and sign in with their existing employee code + 4-digit PIN.
2. They must have an active shift (clocked in on the attendance kiosk) before submitting a checklist.
3. They choose a room/template, then a checklist section (e.g. Start of Day).
4. Every task appears as a large checkbox row; all tasks must be ticked before the checklist can be submitted.
5. Submission is stored with a unique reference and the exact task wording at the time of submission.

Manager workflow:

1. Go to Clinic Management → Room Checklists.
2. Filter by date range, employee, room/template, and checklist section.
3. Use View to open the full submission detail (task snapshots and completion state).
4. Use Export CSV to download the current filtered result set.

== Shortcode Reference ==

[clinic_staff_attendance]

Place this shortcode on any WordPress page to embed the attendance kiosk.

Optional attribute:

[clinic_staff_attendance title="Staff Kiosk"]

[clinic_cleaning_checklists]

Place this shortcode on a separate page to embed the Room Checklists interface. Employees sign in with their existing code + PIN and must have an active shift before submitting.

== Frequently Asked Questions ==

Q: Do staff members need WordPress user accounts?

No. Staff log in using their employee code and 4-digit PIN, which are managed entirely within the plugin. They never access wp-admin.

Q: Is the PIN stored securely?

Yes. PINs are hashed using WordPress's wp_hash_password() (bcrypt). The plain-text PIN is never stored in the database.

Q: Can I use this on a tablet in the staff room?

Absolutely. The frontend UI is designed with large, touch-friendly buttons and a clean interface that works great on tablets.

Q: Does this work with any theme?

Yes. The plugin uses its own styling and does not depend on your theme's CSS. The kiosk page is fully self-contained.

Q: What about timezone handling?

The plugin uses WordPress's configured timezone (Settings → General → Timezone) for all timestamps.

Q: Can I export data for payroll?

Yes. The CSV export is Excel-compatible and includes employee name, dates, clock-in/out times, worked hours, and break time.

== Database Tables ==

The plugin creates seven custom tables:

1. {prefix}csa_employees — employee records (name, code, hashed PIN, active status)
2. {prefix}csa_attendance_events — all clock-in/out and break events
3. {prefix}csa_checklist_templates — room checklist templates (rooms)
4. {prefix}csa_checklist_sections — checklist sections within each template
5. {prefix}csa_checklist_tasks — individual tasks within each section
6. {prefix}csa_checklist_runs — shared daily checklist runs (room, checklist, date, submitter, initials/signature)
7. {prefix}csa_checklist_run_tasks — per-task snapshots for each run with who completed each task and when (audit history)

All tables use the WordPress $wpdb->prefix for multisite compatibility.

== Hooks & Filters ==

The plugin does not currently expose public hooks or filters. Customization can be done by extending the plugin classes. If you need specific hooks, please request them.

== Limitations & Future Improvements ==

• PDF Export — Currently uses browser print-to-PDF. A server-side PDF library (TCPDF/Dompdf) could be added for direct download.
• No email/SMS notifications — Break reminders and overtime alerts are not yet implemented.
• No overtime calculation — Overtime rules are not defined; the system tracks actual worked hours.
• Single kiosk per page — Each page should have only one [clinic_staff_attendance] shortcode.
• No geolocation check — IP is logged, but location-based verification is not implemented.
• No bulk import — Employees must be added one at a time through the admin UI.
• i18n — Translation-ready but no .pot file is included yet.

== Changelog ==

= 2.0.0 =

• New: Fully completed and submitted checklists are permanently locked (read-only) — items, submit button, submitted-by, and initials cannot be changed, even after signing out and back in.
• New: Partially completed checklists can be re-opened, continued, and re-submitted.
• Improved: Login brute-force protection — failed sign-in attempts are throttled per employee code and per device.
• Improved: CSV exports are hardened against spreadsheet formula injection.
• Improved: Drawn signatures now display correctly in the admin submission detail and PDF export.
• Improved: Section titles are aligned consistently across all admin tabs, with a refined premium design (gradient headers, accent titles, polished cards and buttons).
• New: Both kiosk shortcodes are listed with copy buttons under Settings → Plugin Information.
• Security: Removed an unused endpoint that exposed employee codes to unauthenticated visitors.

= 1.2.0 =

• New: Room checklist progress is now shared between all employees on the same room, checklist, and day. Tasks are saved to the database immediately when checked, so another employee opening the same checklist sees the same completed tasks.
• New: Once a checklist is submitted, every employee sees it as already submitted for that day (read-only) — no duplicate work.
• New: Each completed task records which employee completed it and when; the employee-facing receipt and admin detail view show this attribution.
• New: Required Initials field before submission — typed on desktop, drawn signature pad on phones/iPads. Initials/signature are saved with the submission record and shown in the admin detail and PDF.
• New: Room Checklist Setup section in Settings — administrators can add, edit, reorder, and delete rooms/templates, checklists/sections, and to-do items. Changes apply to future submissions only; historical records are preserved.
• New: Settings is now the last tab in the admin navigation menu.
• New: "Export to PDF" for a completed checklist submission (print-to-PDF, formatted for audit/printing). The Reference column is no longer shown in the employee receipt, admin reports, or CSV/PDF exports.
• Removed: Reference column from all user-facing surfaces (kept internally in the database for records/imports).

= 1.1.0 =

• New: Room Checklists module.
• New: [clinic_cleaning_checklists] shortcode for the employee checklist page.
• New: Seeded clinic cleaning templates (rooms), sections, and exact task wording.
• New: Checklist runs linked to the employee's active shift with task text snapshots.
• New: Manager "Room Checklists" report page with filters, pagination, and submission detail view.
• New: CSV export of the filtered checklist report.
• Added five custom database tables for checklist templates, sections, tasks, runs, and run tasks.
• Checklist templates seed only once and never duplicate on reactivation.

= 1.0.0 =

• Initial release.
• Employee management with code + PIN login.
• Clock in, break start, break end, clock out.
• Daily, weekly, monthly, and custom reports.
• CSV and PDF export.
• Responsive kiosk UI with brand colors.
• Dark mode support.

== Upgrade Notice ==

= 2.0.0 = Major update: fully completed checklists are now permanently locked, login brute-force protection is enabled, and the admin interface has been redesigned. No database changes are required — fully completed legacy submissions are automatically detected and locked on their next open. No manual steps required.

= 1.2.0 = The plugin automatically adds new columns (run date, submitter, initials, signature, per-task completed-by) to the checklist tables on the next admin page load after upgrading. Existing submissions are preserved unchanged. No manual steps required.

= 1.1.0 = The plugin automatically creates the new checklist tables and seeds the room checklist templates on the next admin page load after upgrading. No manual steps required.

= 1.0.0 = First release. No upgrade steps needed.