@7365admin1/core 3.8.0 → 3.9.0

package/docs/hid-amico-diagram.md

@@ -0,0 +1,201 @@
+# HID Amico Hardware Integration Diagrams
+
+## 1. Overall Architecture
+
+```mermaid
+flowchart LR
+  Admin[Admin / Web App / Postman]
+
+  subgraph API[iService365 API Core]
+    Route[/api/access-management/hid]
+  end
+
+  subgraph Core[iService365 Core]
+    Controller[HID Controller<br/>validate + call service]
+    Service[HID Service<br/>business logic + HID HTTP client]
+    Repo[HID Repository<br/>MongoDB only]
+    Model[HID Model<br/>types + Joi schemas]
+  end
+
+  subgraph DB[(MongoDB)]
+    Readers[hid-amico-readers]
+    Events[hid-amico-events]
+    Identities[hid-amico-identities]
+    Existing[Existing iService365<br/>users/persons/members/visitors]
+  end
+
+  subgraph HID[HID Amico Reader]
+    HidWeb[HID Web Portal]
+    HidApi[HID HTTP API]
+    Face[Face / card scan]
+  end
+
+  Admin --> Route
+  Route --> Controller
+  Controller --> Model
+  Controller --> Service
+  Service --> Repo
+  Repo --> Readers
+  Repo --> Events
+  Repo --> Identities
+  Identities -. maps to .-> Existing
+  Service --> HidApi
+  HidWeb --> HidApi
+  Face --> HidApi
+```
+
+## 2. Reader Registration And Connection Test
+
+```mermaid
+sequenceDiagram
+  participant Admin as Admin / Postman
+  participant API as iService365 API
+  participant Service as HID Service
+  participant DB as MongoDB
+  participant HID as HID Reader
+
+  Admin->>API: POST /readers
+  API->>Service: createReader()
+  Service->>Service: encrypt password
+  Service->>DB: insert hid-amico-readers
+  DB-->>API: readerId
+  API-->>Admin: created reader without password
+
+  Admin->>API: POST /readers/:readerId/test
+  API->>Service: testReader(readerId)
+  Service->>DB: get reader with password
+  Service->>HID: POST /hidlogin.fcgi
+  HID-->>Service: session
+  Service->>HID: POST /session_is_valid.fcgi?session=...
+  HID-->>Service: valid
+  Service->>HID: POST /logout.fcgi?session=...
+  Service->>DB: update lastSeenAt + add test event
+  API-->>Admin: connection result
+```
+
+## 3. Pull HID Users And Access Logs
+
+```mermaid
+sequenceDiagram
+  participant Admin as Admin / Web App / Postman
+  participant API as iService365 API
+  participant Service as HID Service
+  participant DB as MongoDB
+  participant HID as HID Reader
+
+  Admin->>API: POST /readers/:readerId/objects<br/>operation=load, object=users
+  API->>Service: runObjectOperation(load)
+  Service->>DB: get active reader with password
+  Service->>HID: POST /hidlogin.fcgi
+  HID-->>Service: session
+  Service->>HID: POST /load_objects.fcgi?session=...
+  HID-->>Service: users[]
+  Service->>DB: add backend event objects_load
+  API-->>Admin: HID users
+
+  Admin->>API: POST /readers/:readerId/objects<br/>operation=load, object=access_logs
+  API->>Service: runObjectOperation(load)
+  Service->>HID: POST /load_objects.fcgi?session=...
+  HID-->>Service: access_logs[]
+  Service->>DB: add backend event objects_load
+  API-->>Admin: raw HID access logs
+```
+
+## 4. Face Scan Recognition And Pull-Based Review
+
+```mermaid
+sequenceDiagram
+  participant Person as Resident / Staff / Visitor
+  participant HID as HID Reader
+  participant Portal as HID Web Portal
+  participant Admin as iService365 Admin
+  participant API as iService365 API
+
+  Person->>HID: Face scan
+  HID->>HID: Local biometric recognition
+  HID->>Portal: Shows access notification/log
+
+  Admin->>API: Load access_logs from reader
+  API->>HID: /load_objects.fcgi object=access_logs
+  HID-->>API: access_logs with user_id/time
+  API-->>Admin: Raw logs for mapping/review
+```
+
+## 5. Callback / Monitor Flow
+
+```mermaid
+sequenceDiagram
+  participant Person as Resident / Staff / Visitor
+  participant HID as HID Reader
+  participant API as iService365 API
+  participant Service as HID Service
+  participant DB as MongoDB
+  participant App as Web / Mobile App
+
+  Person->>HID: Face/card scan
+  HID->>HID: Local match
+  HID->>API: POST /notifications/:readerId/:type
+  API->>Service: receiveNotification(readerId, type, payload)
+  Service->>DB: get reader
+  Service->>DB: find identity by hidUserId/registration/cardNo
+
+  alt Identity mapped
+    Service->>DB: save event with mapped identity
+    API-->>HID: 202 Accepted
+    App->>API: read backend HID logs
+    API-->>App: event linked to user/person/member/visitor
+  else Identity not mapped
+    Service->>DB: save event with identity=null and identityLookup
+    API-->>HID: 202 Accepted
+    App->>API: read backend HID logs
+    API-->>App: unmapped event
+  end
+```
+
+## 6. Identity Mapping
+
+```mermaid
+flowchart TB
+  HidUser[HID user<br/>users.id / registration]
+  HidCard[HID card<br/>cardNo]
+  Mapping[hid-amico-identities]
+  User[iService365 user]
+  Person[Person]
+  Member[Member]
+  Visitor[Visitor]
+  Log[access_logs.user_id]
+  Event[hid-amico-events]
+
+  HidUser --> Mapping
+  HidCard --> Mapping
+  Mapping --> User
+  Mapping --> Person
+  Mapping --> Member
+  Mapping --> Visitor
+  Log --> HidUser
+  Mapping --> Event
+```
+
+## 7. Remote Network Access
+
+```mermaid
+flowchart LR
+  VN[Developer / Backend<br/>Vietnam]
+  VPN[Tailscale / Site VPN]
+  Router[Philippines subnet route<br/>192.168.20.0/24]
+  HID[HID Reader<br/>192.168.20.123:80]
+  API[Deployed iService365 API]
+
+  VN --> VPN
+  VPN --> Router
+  Router --> HID
+  API -. production network route .-> HID
+```
+
+## Notes
+
+- iService365 authentication uses `Authorization: Bearer <sid>`.
+- Reader callback endpoint is unauthenticated so HID can call it.
+- Face recognition happens on the HID reader.
+- iService365 receives or pulls the resulting event, then maps it to an iService365 identity.
+- Door-state support depends on firmware; the tested reader returned `Invalid command: door_state`.

package/docs/hid-amico-integration.md

@@ -0,0 +1,491 @@
+# HID Amico Integration
+
+This document explains the current iService365 backend integration for HID Amico VL35LF / VL70LF biometric readers.
+
+## Source Documents
+
+- `HID Amico Biometric Reader API Guide.pdf`
+- `PLT-07752 A.2 - HID Amico Biometric Readers VL35LF and VL70LF User Guide.pdf`
+
+Important confirmed behavior:
+
+- Face recognition is performed by the HID reader, not by iService365.
+- The backend connects to the reader through the HID HTTP API.
+- The backend can register readers, test connectivity, execute generic HID object operations, pull users/access logs, and receive notification callbacks.
+- Raw HID users/access logs must be mapped to existing iService365 records before the product can show a known resident/staff/visitor.
+
+## Repositories And Packages
+
+Core package: `iservice365-core`
+
+```text
+src/models/hid-amico.model.ts
+src/repositories/hid-amico.repo.ts
+src/services/hid-amico.service.ts
+src/controllers/hid-amico.controller.ts
+src/index.ts
+```
+
+API package: `iservice365-API-core`
+
+```text
+src/routes/hid-amico.route.ts
+src/routes/index.ts
+```
+
+Route mount:
+
+```text
+/api/access-management/hid
+```
+
+## Layer Responsibilities
+
+### Model
+
+File: `src/models/hid-amico.model.ts`
+
+Responsibilities:
+
+- Type definitions for readers, events, and identities.
+- Joi schemas for request validation.
+- Model factories:
+  - `MHidAmicoReader`
+  - `MHidAmicoEvent`
+  - `MHidAmicoIdentity`
+
+Joi schemas are kept in the model file to match the existing codebase convention.
+
+### Repository
+
+File: `src/repositories/hid-amico.repo.ts`
+
+Responsibilities:
+
+- MongoDB access only.
+- Reader CRUD.
+- Event insert/list.
+- Identity mapping CRUD.
+- Reader password sanitization before returning data.
+- Identity duplicate guard.
+
+Repository should not call HID hardware APIs.
+
+### Service
+
+File: `src/services/hid-amico.service.ts`
+
+Responsibilities:
+
+- Business logic.
+- Reader password encryption/decryption.
+- Active reader checks.
+- HID hardware HTTP client.
+- Reader connection test.
+- Sync/object operations.
+- Notification enrichment and identity lookup.
+
+Reader passwords are encrypted with AES-256-GCM. The encryption key comes from:
+
+```text
+HID_AMICO_SECRET
+```
+
+Fallback:
+
+```text
+ACCESS_TOKEN_SECRET
+```
+
+### Controller
+
+File: `src/controllers/hid-amico.controller.ts`
+
+Responsibilities:
+
+- Validate `params`, `query`, and `body` using model schemas.
+- Call service methods.
+- Return API responses.
+
+Controller should not call repository methods directly.
+
+### API Route
+
+File: `iservice365-API-core/src/routes/hid-amico.route.ts`
+
+Responsibilities:
+
+- Mount authenticated admin APIs.
+- Expose unauthenticated reader notification callback.
+
+## Data Collections
+
+### `hid-amico-readers`
+
+Stores configured HID devices.
+
+Key fields:
+
+```text
+site
+name
+location
+baseUrl
+username
+password
+deviceId
+monitorPath
+enabled
+status
+lastSeenAt
+lastSyncAt
+lastSyncStatus
+lastSyncMessage
+createdAt
+updatedAt
+deletedAt
+```
+
+Notes:
+
+- `password` is encrypted.
+- API responses do not return `password`.
+- API responses include `passwordSet` so UI can show whether a password exists.
+
+### `hid-amico-identities`
+
+Maps HID users/cards to iService365 records.
+
+Key fields:
+
+```text
+reader
+site
+hidUserId
+registration
+cardNo
+person
+user
+member
+visitor
+type
+status
+metadata
+```
+
+At least one of these is required:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+Supported identity types:
+
+```text
+resident
+staff
+contractor
+visitor
+unknown
+```
+
+### `hid-amico-events`
+
+Stores backend-side HID events.
+
+Examples:
+
+```text
+test
+sync
+sync_failed
+objects_load
+objects_create
+objects_modify
+objects_destroy
+objects_load_failed
+notification callback event types
+```
+
+This collection is not the same as the raw HID `access_logs` table. Raw access logs live on the reader and can be pulled using the generic object API.
+
+## API Surface
+
+Base path:
+
+```text
+/api/access-management/hid
+```
+
+Reader management:
+
+```text
+GET    /readers
+POST   /readers
+PATCH  /readers/:readerId
+DELETE /readers/:readerId
+```
+
+Reader operations:
+
+```text
+POST /readers/:readerId/test
+POST /readers/:readerId/sync
+GET  /readers/:readerId/door-state
+POST /readers/:readerId/actions
+POST /readers/:readerId/objects
+GET  /readers/:readerId/logs
+```
+
+Identity mapping:
+
+```text
+GET    /readers/:readerId/identities
+POST   /readers/:readerId/identities
+PATCH  /identities/:identityId
+DELETE /identities/:identityId
+```
+
+Reader callback:
+
+```text
+POST /notifications/:readerId/:type
+```
+
+The notification endpoint is unauthenticated because the HID reader must be able to call it directly.
+
+## HID HTTP API Mapping
+
+The service wraps these HID endpoints:
+
+```text
+/hidlogin.fcgi
+/session_is_valid.fcgi
+/logout.fcgi
+/create_objects.fcgi
+/load_objects.fcgi
+/modify_objects.fcgi
+/destroy_objects.fcgi
+/door_state.fcgi
+/execute_actions.fcgi
+```
+
+Observed working operations against the Philippines reader:
+
+```text
+hidlogin.fcgi
+session_is_valid.fcgi
+load_objects.fcgi
+logout.fcgi
+```
+
+Known working object names:
+
+```text
+users
+access_logs
+```
+
+Observed unsupported endpoint:
+
+```text
+door_state.fcgi
+```
+
+The tested reader returned:
+
+```json
+{
+  "error": "Invalid command: door_state",
+  "code": 1
+}
+```
+
+Keep door/relay features optional in product UI.
+
+## Generic Object Operation
+
+Backend endpoint:
+
+```text
+POST /api/access-management/hid/readers/:readerId/objects
+```
+
+Load users:
+
+```json
+{
+  "operation": "load",
+  "object": "users",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+Load access logs:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+Filter access logs by HID user id:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "where": {
+    "access_logs": {
+      "user_id": 3
+    }
+  },
+  "limit": 20,
+  "offset": 0
+}
+```
+
+Important: for HID object operations, use a nested `where` object keyed by the table/object name when the reader requires it.
+
+Create objects:
+
+```json
+{
+  "operation": "create",
+  "object": "users",
+  "values": [
+    {
+      "name": "Example User"
+    }
+  ]
+}
+```
+
+Validation:
+
+- `create` and `modify` require `values`.
+- `destroy` requires `where`.
+- `load` can be called without `where`.
+
+## Access Log Timestamp
+
+HID `access_logs.time` is Unix time in seconds.
+
+Example:
+
+```json
+{
+  "user_id": 3,
+  "time": 1780561438
+}
+```
+
+This is:
+
+```text
+2026-06-04 16:23:58 Asia/Manila
+```
+
+For Philippines sites, display times in `Asia/Manila`.
+
+## Identity Mapping Flow
+
+1. Pull HID users from the reader:
+
+```text
+POST /readers/:readerId/objects
+object = users
+```
+
+2. Create a mapping in iService365:
+
+```text
+POST /readers/:readerId/identities
+```
+
+3. Pull access logs or receive callbacks.
+
+4. Backend attempts to match the event using:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+5. If matched, the saved event payload includes the mapped iService365 identity.
+
+6. If not matched, the event is still saved with `identity: null` and `identityLookup`.
+
+## Callback / Monitor Flow
+
+Callback endpoint:
+
+```text
+POST /api/access-management/hid/notifications/:readerId/:type
+```
+
+The reader must be able to reach the backend URL. `localhost` cannot work from the HID reader unless the reader is running on the same machine, which it is not.
+
+For deployed backend:
+
+```text
+https://<api-domain>/api/access-management/hid/notifications/:readerId/:type
+```
+
+For private site network testing:
+
+- Use VPN or subnet routing, such as Tailscale.
+- Ensure the reader can reach the backend host and port.
+
+Callback and pull logs are separate modes:
+
+- Callback: HID pushes events to backend.
+- Pull logs: backend calls `load_objects.fcgi` to read `access_logs`.
+
+Support both because real deployment networks may differ by site.
+
+## Network Notes
+
+The Philippines reader observed during testing:
+
+```text
+IP: 192.168.20.123
+Netmask: 255.255.255.0
+Gateway: 192.168.20.1
+Web Port: 80
+```
+
+Remote access from Vietnam requires routing into the Philippines LAN, for example:
+
+- Tailscale subnet route `192.168.20.0/24`
+- Site VPN
+- A deployed backend that has network access to the reader
+
+## Security Notes
+
+- Do not log reader passwords.
+- Do not return reader passwords in API responses.
+- HID request errors redact the `session` query value.
+- Use a stable `HID_AMICO_SECRET` in production; changing it will make existing encrypted reader passwords undecryptable.
+- Callback endpoint is unauthenticated by design, so it should be treated as an ingestion endpoint and validated by `readerId`, network rules, and deployment controls.
+
+## Verification
+
+Current local verification command:
+
+```bash
+D:\HRM\iservice365-core\node_modules\.bin\tsc.cmd
+```
+
+Status:
+
+```text
+PASS
+```