@7365admin1/core 3.23.0 → 3.24.0

package/docs/hid-amico-diagram.md

@@ -182,8 +182,8 @@ flowchart TB
 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]
+  Router[Site subnet route<br/>&lt;site-lan-cidr&gt;]
+  HID[HID Reader<br/>&lt;hid-reader-lan-ip&gt;:80]
   API[Deployed iService365 API]
 
   VN --> VPN

package/docs/hid-amico-integration.md

@@ -453,20 +453,45 @@ Support both because real deployment networks may differ by site.
 
 ## Network Notes
 
-The Philippines reader observed during testing:
+The Philippines reader observed during early LAN testing:
 
 ```text
-IP: 192.168.20.123
-Netmask: 255.255.255.0
-Gateway: 192.168.20.1
+IP: <hid-reader-lan-ip>
+Netmask: <site-netmask>
+Gateway: <site-gateway-ip>
 Web Port: 80
 ```
 
-Remote access from Vietnam requires routing into the Philippines LAN, for example:
+Current OpenVPN lab topology:
 
-- Tailscale subnet route `192.168.20.0/24`
-- Site VPN
-- A deployed backend that has network access to the reader
+```text
+OpenVPN server machine: <openvpn-server-lan-ip>
+Router/gateway: <site-gateway-ip>
+Public/DDNS endpoint: <ddns-hostname> -> <public-wan-ip>
+Port forward: UDP 1194 -> <openvpn-server-lan-ip>:1194
+HID Amico LAN IP: <hid-reader-lan-ip>
+HID Amico VPN IP: <hid-reader-vpn-ip>
+Backend reader baseUrl for remote access: http://<hid-reader-vpn-ip>
+```
+
+OpenVPN server requirements:
+
+- `client-to-client` must be enabled so external clients or backend services can reach the HID VPN client.
+- Each client should use a unique certificate/common name. Reusing the same client profile will drop the previous session unless `duplicate-cn` is explicitly enabled.
+- The Philippines router must keep DHCP reservation for the OpenVPN server machine and keep UDP `1194` forwarded to that reserved IP.
+- DDNS should point to the current public WAN IP so client profiles do not need to change when the ISP IP changes.
+
+Client profile guidance:
+
+- HID Amico is on the same LAN as the OpenVPN server, so its `.ovpn` can use `remote <openvpn-server-lan-ip> 1194` if the router does not support NAT loopback.
+- External clients and backend machines should use `remote <ddns-hostname> 1194`.
+- iService365 should store the reader `baseUrl` as the stable VPN address, for example `http://<hid-reader-vpn-ip>`, not the LAN address.
+
+Production recommendation:
+
+- Prefer running the VPN client on the backend/server side so normal web users do not need VPN setup.
+- Do not expose the reader LAN/VPN endpoint in frontend tables, detail dialogs, test dialogs, or edit dialogs.
+- Add the endpoint only during reader creation or via a controlled backend/admin maintenance path.
 
 ## Security Notes
 

package/docs/hid-amico-postman-api.md

@@ -96,7 +96,7 @@ Body:
   "site": "{{siteId}}",
   "name": "Philippines HID Amico",
   "location": "Lobby",
-  "baseUrl": "http://192.168.20.123",
+  "baseUrl": "http://<hid-reader-vpn-ip>",
   "username": "<hid username>",
   "password": "<hid password>",
   "deviceId": "PH-HID-01",
@@ -117,6 +117,8 @@ Notes:
 - `password` is encrypted before saving.
 - Response will not return the password.
 - Response includes `passwordSet`.
+- `baseUrl` is required when creating a reader. In the current OpenVPN lab, use the HID VPN URL, for example `http://<hid-reader-vpn-ip>`.
+- Normal frontend edit UI should not expose or update `baseUrl`. Treat endpoint changes as a controlled admin/backend maintenance action.
 
 ## 4. List Readers
 
@@ -549,7 +551,7 @@ Use:
 /api/access-management/hid/readers
 ```
 
-### `ECONNREFUSED 127.0.0.1:5001`
+### `ECONNREFUSED localhost:<api-port>`
 
 API-core is not running on port `5001`, or Postman `base_url` is wrong.
 

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

@@ -75,6 +75,9 @@ POST   /api/access-management/hid/readers/:readerId/sync
 Design notes:
 
 - Do not display saved password value.
+- Do not display saved Base URL / endpoint in the reader table, reader detail, test connection modal, or edit reader modal.
+- Add reader still requires Base URL / IP address because the backend needs a target endpoint for the hardware.
+- Edit reader must omit `baseUrl` from the submitted payload so the saved endpoint cannot be viewed or accidentally changed from normal UI.
 - Display `passwordSet` as a simple status.
 - Allow disabling a reader without deleting it.
 - Show a clear status for connection test: success, failed, last tested.
@@ -352,7 +355,7 @@ 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.
+- For private-network testing, use VPN/subnet routing. In the current OpenVPN lab, backend/client access should target the reader VPN URL, for example `http://<hid-reader-vpn-ip>`.
 - Callback is optional if the system relies on pull-based access logs.
 
 ## 7. Door / Relay Actions

package/package.json

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