# Attendance (Manage)

**Portal:** Manage · **Routes:** `manage.attendance.*` (list) + `webhooks.zkteco.*` (terminal) ·
**Nav:** Setting → **Attendance** (tab beside Devices) · **Permission:** `view-attendance`

## What it does
Records staff clock-in / clock-out from the office **ZKTeco face terminal** and shows one row
per person per day: first punch, last punch, hours between them, and the punch count.

The terminal pushes straight to petav3 over ZKTeco's **ADMS "PUSH" protocol** — no ZKBio Time
server, no office PC in between. A terminal can push to only ONE server, so once it points here
ZKBio Time no longer receives its punches.

## How it works
- **Terminal → `/iclock/*`** ([`ZktecoAdmsController`](/app/Http/Controllers/Webhooks/ZktecoAdmsController.php)),
  registered from [`routes/iclock.php`](/routes/iclock.php) with **no middleware group** (no
  session, no CSRF, no throttle — the terminal sends no cookies and polls every
  `ATTENDANCE_POLL_DELAY` seconds).
  - `GET cdata` — handshake; replies with push options (`ATTLOGStamp=None` = send all history).
  - `POST cdata?table=ATTLOG` — the punches. Other tables (OPERLOG, USERINFO, photos) are
    acknowledged and ignored.
  - `GET getrequest` / `POST devicecmd` — command channel; we never send commands, so both reply `OK`.
  - Every reply is plain-text **200**. A storage failure replies `ERROR` so the terminal keeps the
    batch and resends it later.
- **Gate:** the protocol carries no secret, so only serials listed in
  `ATTENDANCE_DEVICE_SERIALS` ([`config/attendance.php`](/config/attendance.php)) are stored. An
  unknown serial is answered `OK` (so it stops retrying) and logged as
  `[ZktecoAdms] Terminal not in ATTENDANCE_DEVICE_SERIALS` — that log line is where the serial
  to allow can be read.
- **Parsing** — `AttendanceLog::parseAttlog()`: tab-separated `PIN, time, state, verify, …`. The
  time has no offset; it is read in `ATTENDANCE_DEVICE_TIMEZONE` and stored in `app.timezone`.
  Malformed lines are skipped.
- **Idempotent** — unique `(device_sn, employee_no, punched_at)` + `insertOrIgnore`: the terminal
  resends its log after a reconnect and duplicates are dropped silently.
- **Who is who** — the terminal's user ID is stored as `employee_no` and matched to
  `admins.employee_no` **when the list is read**, never stored as `admin_id`. Setting an admin's
  employee number later re-attributes all of their past punches. An unmatched ID shows as
  "Not linked to an admin".
- **List** ([`AttendanceController`](/app/Http/Controllers/Manage/Attendance/AttendanceController.php))
  — one row per `employee_no` + `DATE(punched_at)`, paginated in SQL; the raw scans behind the
  page's rows are then loaded in one query and summarised in PHP. Search matches the employee
  number or a staff name / email; the date range filters `punched_at`.
- **Day rules** — `AttendanceLog::summarizeDay()`. The terminal sends punch state 255 (it does not
  know in from out), so direction is inferred from order:
  1. **Repeat scans fold** into a burst: every scan within `ATTENDANCE_DUPLICATE_WINDOW_MINUTES`
     (default **2**) of the burst's **opening** scan (double reads, "did it work?" re-scans).
     Kept short on purpose: a toilet trip folded into one scan would flip every later scan.
  2. Bursts **alternate IN, OUT, IN, OUT …**; an IN counts by its first scan, an OUT by its last.
  3. **Even** count → `DAY_COMPLETE`: In Office = sum of IN→OUT periods; each gap between them
     (lunch, toilet, errand) is listed as time Away. **Odd, three or more** → `DAY_CHECK`
     (a scan was missed; gaps cannot be told apart, so nothing is deducted — In Office =
     first→last). **One** burst → `DAY_OPEN` ("In office" today, "No clock-out" on a past day).
  4. **Today is judged live**, not as a finished day (the controller passes `$now`): an odd count
     means the last scan was IN → `DAY_IN_OFFICE` (In Office counts up to now); an even count →
     `DAY_OUT` (lunch, errand, or gone home). Without this, coming back from lunch would read as a
     missed scan.
  The **"In office now"** panel above the list runs the same rule over every person's scans today
  (independent of the list's filters / page) and shows each one with the time of their latest IN.
  Clock-in = first IN; clock-out = last scan's time when there are two or more bursts. Nothing is
  deleted: the page lists every raw scan tagged IN / OUT, and strikes through the folded ones.
  Clock-out is decided in PHP, so it is not a sortable column. Limitation: a shift crossing
  midnight splits into two days.

## Setup (one terminal)
1. On the terminal: **Menu → System Info → Device Info** — note the **Serial Number**.
2. Production `.env`: `ATTENDANCE_DEVICE_SERIALS=<serial>` then `php artisan config:cache`.
3. On the terminal: **Menu → COMM → Cloud Server Setting** — Server Mode **ADMS**, Server Address
   = the site's domain, Port **443** with HTTPS on (or 80 if the firmware cannot do TLS). Proxy off.
4. On the terminal: **User Mgt → New User** — the **User ID must equal the admin's
   `employee_no`** in petav3, then enrol the face.
5. Grant `view-attendance` to the roles that may read it (Setting → Roles).

## Related files
**Backend**
- [`app/Http/Controllers/Webhooks/ZktecoAdmsController.php`](/app/Http/Controllers/Webhooks/ZktecoAdmsController.php)
- [`app/Http/Controllers/Manage/Attendance/AttendanceController.php`](/app/Http/Controllers/Manage/Attendance/AttendanceController.php)
- [`app/Http/Requests/Manage/Attendance/AttendanceQueryRequest.php`](/app/Http/Requests/Manage/Attendance/AttendanceQueryRequest.php)
- [`src/Attendance/AttendanceLog.php`](/src/Attendance/AttendanceLog.php)
- [`src/Attendance/Repositories/AttendanceLogRepository.php`](/src/Attendance/Repositories/AttendanceLogRepository.php)
- [`config/attendance.php`](/config/attendance.php)
- [`src/Auth/Permission.php`](/src/Auth/Permission.php) — `VIEW_ATTENDANCE`
- [`app/Providers/RouteServiceProvider.php`](/app/Providers/RouteServiceProvider.php) — `mapAttendanceTerminalRoutes()`

**Frontend**
- [`resources/js/Pages/Manage/Attendance/Index.vue`](/resources/js/Pages/Manage/Attendance/Index.vue)
- [`resources/js/Components/SettingTabs.vue`](/resources/js/Components/SettingTabs.vue) — the Attendance tab

**Migrations**
- [`2026_10_13_100000_create_attendance_logs.php`](/database/migrations/2026_10_13_100000_create_attendance_logs.php)
- [`2026_10_13_100001_add_view_attendance_permission.php`](/database/migrations/2026_10_13_100001_add_view_attendance_permission.php)

**Routes**
- [`routes/iclock.php`](/routes/iclock.php) — terminal endpoints
- [`routes/web.php`](/routes/web.php) — `manage.attendance.index`

**Tests**
- [`tests/Feature/Attendance/ZktecoAdmsTest.php`](/tests/Feature/Attendance/ZktecoAdmsTest.php)
- [`tests/Unit/Attendance/SummarizeDayTest.php`](/tests/Unit/Attendance/SummarizeDayTest.php) — the repeat-scan rule
