@7365admin1/core 3.8.0 → 3.10.0

package/docs/hid-amico-ui-design-scope.md

@@ -0,0 +1,441 @@
+# HID Amico UI Design Scope
+
+This document summarizes the product features needed for HID Amico integration UI design.
+
+## Core Product Concept
+
+The HID reader recognizes faces locally. iService365 does not perform face recognition.
+
+iService365 is responsible for:
+
+- Registering and managing HID readers.
+- Testing reader connectivity.
+- Pulling enrolled HID users.
+- Pulling HID access logs.
+- Mapping HID users/cards to iService365 records.
+- Showing access history and unmapped scans.
+- Receiving callback/monitor events when the network supports it.
+- Providing restricted admin tools for low-level HID object operations.
+
+## Recommended Navigation
+
+```text
+Access Management
+  - HID Readers
+  - HID Users
+  - Identity Mapping
+  - Access Logs
+  - Monitor / Callback
+  - Admin Object Tools
+```
+
+## 1. HID Reader Management
+
+Purpose: register and manage HID readers per site.
+
+Main screens:
+
+- Reader list
+- Add reader
+- Edit reader
+- Reader detail
+- Connection test result
+- Sync/operation history
+
+Reader fields:
+
+```text
+Name
+Site
+Base URL / IP address
+Username
+Password
+Device ID
+Monitor path
+Enabled
+Status
+Last seen at
+Last sync at
+Last sync status
+Last sync message
+Password set
+```
+
+Backend APIs:
+
+```text
+GET    /api/access-management/hid/readers
+POST   /api/access-management/hid/readers
+PATCH  /api/access-management/hid/readers/:readerId
+DELETE /api/access-management/hid/readers/:readerId
+POST   /api/access-management/hid/readers/:readerId/test
+POST   /api/access-management/hid/readers/:readerId/sync
+```
+
+Design notes:
+
+- Do not display saved password value.
+- Display `passwordSet` as a simple status.
+- Allow disabling a reader without deleting it.
+- Show a clear status for connection test: success, failed, last tested.
+- Show whether the backend can reach the reader network.
+
+## 2. HID Users
+
+Purpose: show users enrolled on the HID reader.
+
+HID source object:
+
+```text
+users
+```
+
+Known fields:
+
+```text
+id
+name
+registration
+user_type_id
+image_timestamp
+last_access
+```
+
+Backend API:
+
+```text
+POST /api/access-management/hid/readers/:readerId/objects
+```
+
+Payload:
+
+```json
+{
+  "operation": "load",
+  "object": "users",
+  "limit": 100,
+  "offset": 0
+}
+```
+
+Recommended UI:
+
+- HID users table
+- Search by name
+- Search by HID user ID
+- Show face/image enrolled status
+- Show last access time
+- Show mapped/unmapped badge
+- Action: create identity mapping
+
+Design notes:
+
+- HID `users.id` is not the iService365 `user` ObjectId.
+- Some HID users have empty `registration`.
+- Unmapped HID users are expected and should be easy to map.
+
+## 3. Identity Mapping
+
+Purpose: connect a HID identity to an iService365 record.
+
+Mapping keys:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+Can map to:
+
+```text
+iService365 user
+Person
+Member
+Visitor
+```
+
+Supported identity types:
+
+```text
+resident
+staff
+contractor
+visitor
+unknown
+```
+
+Backend APIs:
+
+```text
+GET    /api/access-management/hid/readers/:readerId/identities
+POST   /api/access-management/hid/readers/:readerId/identities
+PATCH  /api/access-management/hid/identities/:identityId
+DELETE /api/access-management/hid/identities/:identityId
+```
+
+Recommended UI:
+
+- Mapping list
+- Create mapping
+- Edit mapping
+- Delete mapping
+- Search mappings
+- Filter by type/status
+- Badge states: mapped, unmapped, inactive, deleted
+
+Design notes:
+
+- At least one of `hidUserId`, `registration`, or `cardNo` is required.
+- `user`, `person`, `member`, and `visitor` must be MongoDB ObjectIds.
+- Numeric HID ids should go into `hidUserId`, not `user`.
+- Duplicate active/inactive mappings for the same reader and same HID key are blocked.
+
+## 4. Access Logs / Scan History
+
+Purpose: show face/card scan history from the HID reader.
+
+HID source object:
+
+```text
+access_logs
+```
+
+Known fields:
+
+```text
+id
+time
+event
+device_id
+identifier_id
+user_id
+portal_id
+identification_rule_id
+card_value
+qrcode_value
+pin_value
+confidence
+mask
+log_type_id
+```
+
+Important:
+
+- `time` is Unix time in seconds.
+- For Philippines sites, display using `Asia/Manila`.
+- `access_logs.user_id` maps to HID `users.id`.
+- It does not directly map to iService365 `user`.
+
+Backend API:
+
+```text
+POST /api/access-management/hid/readers/:readerId/objects
+```
+
+Payload:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+Filter by HID user:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "where": {
+    "access_logs": {
+      "user_id": 3
+    }
+  },
+  "limit": 20
+}
+```
+
+Recommended UI:
+
+- Access logs table
+- Timeline view
+- Filter by reader
+- Filter by HID user
+- Filter by date range
+- Show mapped user/person/member/visitor when available
+- Show raw HID user id when unmapped
+- Show confidence
+- Show event time in site timezone
+
+Design notes:
+
+- A scan can appear in the HID web portal before iService365 has pulled it.
+- Unmapped scans should be visible, not hidden.
+- Show an "Unmapped" warning badge and offer a mapping action.
+
+## 5. Backend Event Logs
+
+Purpose: show backend-side integration events.
+
+Backend API:
+
+```text
+GET /api/access-management/hid/readers/:readerId/logs?page=1&limit=20
+```
+
+Examples:
+
+```text
+test
+sync
+sync_failed
+objects_load
+objects_create
+objects_modify
+objects_destroy
+objects_load_failed
+callback event types
+```
+
+Recommended UI:
+
+- Technical event log list
+- Filter by event type
+- Status
+- Created time
+- Payload viewer
+- Error details
+- Matched identity if available
+
+Design notes:
+
+- This is an admin/debug feature.
+- Collapse raw payload by default.
+- Use this for troubleshooting integration issues.
+
+## 6. Monitor / Callback
+
+Purpose: receive push events from HID when a scan or device event occurs.
+
+Backend endpoint:
+
+```text
+POST /api/access-management/hid/notifications/:readerId/:type
+```
+
+Potential event types:
+
+```text
+new_user_identified
+access_photo
+door
+card
+pin
+push_result
+```
+
+Recommended UI:
+
+- Callback URL display
+- Copy callback URL
+- Last callback received
+- Last callback payload preview
+- Last callback identity resolution status
+- Callback setup status
+
+Design notes:
+
+- HID must be able to reach the backend URL.
+- `localhost:5001` will not work from the HID reader.
+- For deployed usage, use the deployed API domain.
+- For private-network testing, use VPN/subnet routing.
+- Callback is optional if the system relies on pull-based access logs.
+
+## 7. Door / Relay Actions
+
+Purpose: support door/relay actions only if the device firmware supports them.
+
+Backend APIs:
+
+```text
+GET  /api/access-management/hid/readers/:readerId/door-state
+POST /api/access-management/hid/readers/:readerId/actions
+```
+
+Observed test result:
+
+```json
+{
+  "error": "Invalid command: door_state",
+  "code": 1
+}
+```
+
+Design notes:
+
+- Door state is not guaranteed for all firmware.
+- Open door/open relay should be optional.
+- UI should show "Not supported by this device" when the command fails with invalid command.
+
+Possible UI actions:
+
+```text
+Open door
+Open relay
+Check door state
+Check relay state
+```
+
+## 8. Admin Object Tools
+
+Purpose: low-level HID API testing and support.
+
+Backend API:
+
+```text
+POST /api/access-management/hid/readers/:readerId/objects
+```
+
+Supported operations:
+
+```text
+load
+create
+modify
+destroy
+```
+
+Known working objects:
+
+```text
+users
+access_logs
+```
+
+Recommended UI:
+
+- Object name input/select
+- Operation select
+- JSON payload editor
+- Response viewer
+- Error viewer
+
+Design notes:
+
+- Restrict this to admin/dev roles.
+- Destructive operations must require confirmation.
+- This is not a normal resident/staff workflow.
+
+## Product Rules
+
+- HID is the source of biometric enrollment.
+- HID is the source of raw access logs.
+- iService365 maps HID identities to internal records.
+- iService365 should display unmapped scans.
+- Callback and pull logs are separate integration modes.
+- Door/relay features depend on firmware support.
+- UI should separate normal operations from admin/debug tools.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",