# Biometrics auto-apply procedure

Solidmark uses a guarded hybrid design:

1. `sp_prepare_biometrics_auto_apply` performs the schedule check, per-brand
   lock, canonical identity resolution, event grouping, safety filtering,
   idempotency, and durable queue claim in MariaDB.
2. The thin Node worker submits each claimed group to
   `import_attendance_by_personid.php` so the existing work-schedule, break,
   rest-day, late, undertime, and payroll snapshot calculations remain the
   single source of truth.
3. The worker finalizes every queue row and run record.

The procedure never guesses an unclassified punch. A group is eligible only
when every event is already canonical or has an explicit saved punch review,
and both the shift-in (`morning_in`) and shift-out (`afternoon_out`) exist.
Cross-midnight groups are left for review because calendar-day SQL grouping
cannot safely infer their attendance date without the resolved shift context.

## Deployment order

Run these migrations in order:

1. `20260829_04_biometrics_canonical_employee_identity.sql`
2. `20260829_05_biometrics_brand_scope.sql`
3. `20260829_06_biometrics_auto_apply_procedure.sql`
4. `20260829_02_hik_sync_brand_scope.sql` when HIK sync is installed

Do not enable auto-apply until the verification result sets from migrations 04
and 05 are empty or every remaining row has been investigated.

## Configuration

Use the authenticated endpoint:

- `GET /api/attendance_biometrics/auto_apply_settings`
- `POST /api/attendance_biometrics/auto_apply_settings`

Example POST body:

```json
{
  "is_enabled": true,
  "times_to_apply": ["00:05", "12:05", "18:35"],
  "days_back": 1,
  "minimum_age_minutes": 5,
  "max_groups": 500
}
```

Keep the feature disabled during initial verification. A forced preparation can
be tested through `auto_apply_prepare` without changing the saved schedule.

## Worker

Configure these environment variables in the scheduler account:

- `AUTO_APPLY_BASE_URL`
- `AUTO_APPLY_BRAND_CODE`
- `AUTO_APPLY_BEARER_TOKEN`

Run the worker once per minute:

```text
node backend/scripts/auto_apply_biometrics_procedure.js
```

For a controlled manual run:

```text
node backend/scripts/auto_apply_biometrics_procedure.js --force
```

Use a dedicated admin-portal service identity limited to the intended brand.
Do not put its bearer token in the repository or the command line.

## Direct procedure test

With auto-apply disabled, use `p_force_run = 1` in a controlled database
session:

```sql
CALL sp_prepare_biometrics_auto_apply(1, 1, CURRENT_TIMESTAMP, 1);
```

The first result set is the run summary. The second contains claimed queue rows
compatible with the validated attendance-application endpoint.

Claims abandoned for more than 30 minutes are made retryable by the next run.
An identical event fingerprint that was already applied is never queued again.