Core_Be/scripts/agent-face-photo-contract.md

# Agent contract — `UpsertFacePhoto`

**Status: implemented on both sides.** The agent side lives in `Access-device-agent`
(`Devices/HikvisionIsapiClient.SetUserFaceAsync` and the `UpsertFacePhoto` case in
`Services/CommandWorker.DispatchAsync`). This document remains the reference for the wire
format and the device call.

Not yet verified against a physical terminal — see "Untested" at the end.

## Flow

```
Web  ──POST client/customers/{id}/face-photo──▶  Server
                                                  │ validates JPEG, queues DeviceCommand
                                                  ▼
Agent ──GET  api/agent/commands ─────────────────▶ receives UpsertFacePhoto
      ──ISAPI POST────────────────────▶ Hikvision terminal (gym LAN)
      ──POST api/agent/commands/{id}/result ────▶ Server
                                                  │ purges payload, updates profile
                                                  ▼
                                                SignalR "FacePhotoUpdated" ──▶ browser
```

## Command the agent receives

`GET api/agent/commands` returns the usual envelope; `CommandType` is `UpsertFacePhoto`.

`PayloadJson`:

```json
{
  "bindingId":       "8f1c...",     // guid, AccessDeviceBinding
  "accessProfileId": 6,             // long
  "employeeNo":      "HF6",         // the person id already used by UpsertPerson
  "name":            "Prabodha",
  "faceJpegBase64":  "/9j/4AAQ...", // bare base64, no data: prefix
  "desiredVersion":  4
}
```

The image is already normalised by the browser and re-checked server-side:

| Property | Guaranteed |
|---|---|
| Format | JPEG (magic bytes verified) |
| Dimensions | 480×640 from the web client; ≤ 1920×1920 enforced |
| Size | ≤ 200 KB enforced, typically 60–150 KB |

So the agent does **not** need to resize or convert. Decode the base64 and POST it.

**Ordering:** the person record must exist on the terminal before a face can attach to it.
`employeeNo` is the same value `UpsertPerson` uses. If a face command arrives for a person
the terminal doesn't have, run the person upsert first rather than failing.

## ISAPI call

Face data is attached to an existing person in a face library. Typical shape for the
DS-K1T series (confirm against your firmware — this varies more than Hikvision's docs
suggest):

```
POST /ISAPI/Intelligent/FDLib/FDSetUp?format=json
Content-Type: multipart/form-data; boundary=---boundary
Authorization: Digest ...

---boundary
Content-Disposition: form-data; name="FaceDataRecord"
Content-Type: application/json

{ "faceLibType": "blackFD", "FDID": "1", "FPID": "HF6", "name": "Prabodha" }
---boundary
Content-Disposition: form-data; name="FaceImage"; filename="face.jpg"
Content-Type: image/jpeg

<binary jpeg>
---boundary--
```

- `FPID` should be the `employeeNo`, so the face ties to the same person record.
- Use **Digest** auth, as with the other endpoints.
- Replacing a photo is the same call — the device overwrites the FPID's face.

## Result the agent posts back

`POST api/agent/commands/{id}/result`

**Success:**
```json
{ "success": true, "resultJson": "{\"fpid\":\"HF6\"}" }
```

The server reads `fpid` (also accepts `FPID`, `faceId`, `faceURL`) into
`AccessProfile.FacePhotoFPID` — the handle needed to replace or delete the face later.
Anything longer than 64 chars is truncated.

**Failure:**
```json
{ "success": false, "resultJson": "{\"detail\":\"No frontal face detected in the image\"}" }
```

Put a human-readable reason in `detail` — it is surfaced to gym staff verbatim, so it
should say what to do about it. Real Hikvision rejections worth mapping:

| Device response | Suggested `detail` |
|---|---|
| `lowFaceQuality` / no face found | `No clear frontal face was detected. Retake with the face centred and well lit.` |
| face already bound to another FPID | `This face is already enrolled for another member.` |
| library full | `The terminal's face library is full.` |
| image format rejected | `The terminal rejected the image format.` |

## Retry behaviour

`MaxAttempts` is **3** for face commands (lower than the 5 used for person/state commands):
a face rejected for quality will be rejected identically on every retry, so failing fast
gets the real message in front of staff sooner.

- Retries use the existing exponential backoff.
- On success **or** final failure the server clears `PayloadJson`, so the image is not
  retained. A retry between those points still has the payload available.
- A newer photo supersedes an older queued one — the stale command is marked `Superseded`
  and its payload cleared. The agent should treat `Superseded` as "stop, discard".

## Deleting a face

The **agent** side is implemented (`DeleteUserFaceAsync`, plus a `DeleteFacePhoto` dispatch
case), calling:

```
PUT /ISAPI/Intelligent/FDLib/FDSearch/Delete?format=json&FDID=1&faceLibType=blackFD
{ "FPID": [ { "value": "HF6" } ] }
```

The **server** does not queue this command yet — nothing calls it when a member is removed.
Adding that is a small change: queue `DeleteFacePhoto` with the stored `FacePhotoFPID`
wherever a member is deactivated, then clear the face columns on success.

## Untested

Everything here compiles and the wire format matches on both sides, but **no part of this
has run against a physical Hikvision terminal.** Expect to verify:

- `FDID = "1"` and `faceLibType = "blackFD"` are the right library on your model. Terminals
  with multiple face libraries may need a different FDID.
- The multipart part names (`FaceDataRecord`, `FaceImage`) — these vary between firmware
  generations more than Hikvision's documentation suggests.
- Whether your model accepts 480×640 at ~150 KB, or wants smaller.

The agent logs the full device response for both success and failure
(`SetUserFace {EmployeeNo} ... : {Response}`), which is the fastest way to see what the
terminal actually objects to on the first real run.