# HIK Sync Phase 3: Sample Mapping and Mirroring

Date: 2026-07-23

## Scope

This phase intentionally maps HIK employee number `1`, reported by the device as
Ricardo Rimando, to the active SMDummy sample employee displayed as Demo2 Demo1.
This is a test mapping only. The two names are not asserted to represent the same
real person.

The continuous HIK agent was not started.

## Confirmed sample employee

- Employee ID: `8784537400`
- Active match count: `1`
- Stored first name: `demo1`
- Stored last name: `demo2`
- Mapping display name: `Demo2 Demo1`

## Backups

Backups were captured before source or database changes:

- `_backups/hik-sync-phase-3-20260723-143814/backend-hik-sync`
- `_backups/hik-sync-phase-3-20260723-143814/employees.sql`
- `_backups/hik-sync-phase-3-20260723-143814/hik_sync_employee_map.sql`
- `_backups/hik-sync-phase-3-20260723-143814/hik_sync_events.sql`
- `_backups/hik-sync-phase-3-20260723-143814/tbl_biometrics_logs.sql`

## Implementation

- Added the versioned migration
  `backend/hik-sync/sql/migrations/20260723_01_hik_sync_employee_map_text_person_id.sql`.
- Changed `hik_sync_employee_map.person_id` from `BIGINT` to `VARCHAR(15)` to
  match `employees.employee_id`.
- Updated `backend/hik-sync/sql/install.sql` with the corrected type.
- Restricted the biometrics insert to the live columns: `person_id`, `name`,
  `department`, `source_file`, `time_log`, and `attendance_status`.
- Mirroring now locks a pending event and performs its biometrics insert and
  `mirrored_at` update in one transaction.
- Each valid raw punch remains a separate biometrics log.

## Mapping

The intentional test mapping is:

| device_key | hik_employee_no | person_id | employee_name | is_active |
| --- | --- | --- | --- | --- |
| smdummy-main | 1 | 8784537400 | Demo2 Demo1 | 1 |

## Validation results

PHP syntax checks passed for:

- `backend/hik-sync/lib.php`
- `backend/hik-sync/replay.php`
- `backend/hik-sync/receive.php`

The first replay reported:

```json
{"ok":true,"mirrored":2,"failed":0}
```

Database verification after the first replay confirmed:

- Both pending HIK events received a non-null `mirrored_at`.
- Both events retained a null `mirror_error`.
- Exactly two `tbl_biometrics_logs` rows were created.
- Both rows have `person_id` `8784537400`.
- Both rows have `name` `Demo2 Demo1`.
- Both rows have `source_file` `hikvision_api`.
- Both rows have normalized `attendance_status` `Check-in`.
- The distinct event times `2026-07-23 13:56:36` and
  `2026-07-23 14:06:40` were preserved.

The second replay reported:

```json
{"ok":true,"mirrored":0,"failed":0}
```

The corresponding biometrics row count was `2` both before and after the
second replay, confirming replay idempotency.

## Continuous synchronization

The continuous agent was not started. The receiver and replay path passed the
sample mapping and idempotency checks, so continuous synchronization is ready
for controlled testing with this mapping. It is not appropriate for real
attendance attribution while the intentional Ricardo Rimando-to-Demo2 Demo1
test mapping remains active.