Attendance & Salary

Attendance and payroll for small businesses, workshops and daily-wage / contract staff. Employees clock in and out with a 4-digit PIN; the owner sees who is in today, looks back at each employee's week, month or year, and prints salary slips. Runs entirely on free tiers: Next.js on Vercel and Supabase.

Stack

• Next.js 16 (App Router, TypeScript), Tailwind CSS v4, shadcn/ui (new-york), Lucide icons
• Supabase: Postgres, Auth (owners only), Row Level Security, Realtime
• PWA: src/app/manifest.ts, public/sw.js (offline screen only) and Apple web-app meta tags; installs full screen

Getting started

1. Create a free Supabase project.
2. Run each file in supabase/migrations/ in order, pasting its contents into the SQL editor (or supabase db push with the CLI).
3. cp .env.example .env.local and fill in the project URL and anon key.
4. npm install && npm run dev, then open http://localhost:3000.

Layout

Screens say "employee" everywhere. The database and code still use worker in table, column and function names (workers, worker_id, worker_login, …), so no migration was needed for the rename.

supabase/
  migrations/01_schema.sql     tables, enums, triggers, RLS, RPCs (step 1)
  migrations/02_admin.sql      business name on sign-up, worker-photos bucket (step 2)
  migrations/03_function_grants.sql  owner-only functions not callable by anon
  migrations/04_gps.sql        work location + radius, location stored on each punch
  migrations/05_timings_selfies.sql  optional work timings, off days, punch selfies
  tests/                       plain-Postgres behaviour tests for the migration
src/
  proxy.ts                     refreshes the owner's session, guards /admin
  app/
    manifest.ts                PWA manifest: opens on /start, full screen, shortcuts
    login/                     owner sign-in and sign-up (step 2)
    auth/confirm/              sign-up email confirmation link
    admin/                     owner dashboard: live board (step 2)
      employees/               add / edit employees, set PINs
      attendance/              one employee's week / month / year (?e=&view=&d=); add, edit, delete days
      selfie/[id]/             a punch selfie as a JPEG (owner only, by RLS)
      settings/                punch link, work timings, location check, selfie
      payroll/                 salary report, ?from=&to= (default: this month)
      payroll/[workerId]/      printable A4 / phone salary slip
    punch/                     worker kiosk + personal phone mode (step 3)
    punch/login/               one-time phone + PIN login on a worker's own phone
  components/
    ui/                        shadcn/ui primitives
    admin/  punch/  payroll/   feature components
  lib/
    supabase/                  browser, server and proxy clients
    worker-session.ts          httpOnly cookie for personal-mode worker sessions
    format.ts                  minutes, rupees, month ranges
    admin/period.ts            pay period from ?from=&to=
    admin/calendar.ts          week / month / year ranges for the attendance page
    timing.ts                  work timings, off days, owner-time-zone conversions
  types/database.ts            typed schema + RPC result shapes

The punch screen

Open the link from the owner's dashboard (/punch?k=CODE) once on each device. The code is remembered in a cookie and removed from the address bar, so "Add to Home Screen" opens straight to the punch screen.

• Shared tablet: employee taps their photo, enters their PIN, taps the big green CLOCK IN or red CLOCK OUT button, sees a full-screen confirmation for 3 seconds. An employee's screen goes back to the photo grid after 20 seconds without a tap.
• Own phone: "On your own phone? Log in once here" asks for phone number and PIN, then the phone stays logged in for 90 days (httpOnly cookie; changing the PIN logs it out).
• Labels have a short Hindi line under the English.

Location check (GPS)

Off by default. On the Settings page (gear icon), the owner stands at the workplace, taps "Use my current location" (or pastes coordinates from Google Maps), picks an allowed distance (200 m is a good start) and ticks "Check location when employees punch".

• With the check on, every clock-in and clock-out, on the tablet or an employee's own phone, sends the browser's GPS fix. do_punch refuses it when it is farther than the allowed distance plus the fix's accuracy (counted up to 100 m), and refuses a punch with no location.
• Every punch that sent a location stores it (clock_in_lat, clock_in_distance_m, …). The Today board shows "In 44 m", linking to the spot on Google Maps, in red when outside the distance.
• The browser's location can be faked with mock-GPS apps. This check stops the everyday case (punching from home or on the way), not a determined cheat.

Work timings and off days

Both optional, on the Settings page.

• Business timing (e.g. 10:30 AM to 7:30 PM). An employee can have their own timing instead (part time), set in their Employees form. With a timing, a day is present when they worked less than 1 h 30 min short of the timing (late in, early out or both), half day at half of it, absent below that; overtime is time past the timing, and clocking in more than 10 minutes after the start shows a "Late" tag. Timings past midnight (night shift) work.
• No timing at all: any day the employee clocks in and out is a full day, with no overtime.
• Off days (Sunday by default): punches are still recorded and shown, but left out of the salary. A monthly salary is divided over the month's working days (days that aren't off days).

Changing a timing applies to punches from then on; past days keep their status.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗