updated readme.md

This commit is contained in:
2026-10-23 14:33:24 +01:00
parent 8c5e61efd0
commit 568adc034b
+220 -104
View File
@@ -1,153 +1,269 @@
# Access Point
# Hardlink
This service handles door card issuance and room ticket printing for hotels. It interacts with the card dispenser over serial, the Assa Abloy lock server, and prints receipts.
Hardlink is the Windows hotel-kiosk service for K720 card dispensing, door-key
encoding, room-ticket and payment-receipt printing, and terminal payments. It
supports Assa Abloy, Omnitec, Salto, TLJ and dormakaba lock servers, and CreditCall
(ChipDNA), Dojo and PayBridge payment providers.
## Deployment
## Build and run
We use Salt for deployment. To build and deploy a new version:
Run from the repository root on Windows with Go 1.23.2 or newer and access to the
private Gitea modules. The entry point is `cmd/hardlink`, not the repository root.
1. **Push your branch** with a meaningful commit message:
```bash
git push origin <branch>
```
2. **Tag and build**:
```bash
./tagbuild.sh
```
This script:
- Builds the latest `hardlink.exe` binary
- Tags the repository with the new version
- Copies `hardlink_<tag>.exe` to `salt/hardlink/files`
3. **Commit the new binary** in Salt:
```bash
cd salt
git add hardlink/files/hardlink_<tag>.exe
git commit -m "added hardlink"
git push
```
4. **Update pillar** (`pillar/hardlink/init.sls`) to point to the new version.
5. **Apply the state** on your hosts:
```bash
salt '*' state.apply hardlink
```
```powershell
go build -mod=readonly -o hardlink.exe ./cmd/hardlink
go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release
./hardlink.exe
```
`preauth-release.exe` is a separate task for releasing due CreditCall
preauthorizations; the HTTP service does not run it automatically.
Start Hardlink with the deployment directory as its working directory:
```text
hardlink/
hardlink.exe
config.yml
TicketLayout.xml
ChipDNAClient/ # Required for CreditCall
ChipDnaClient.exe
... SDK dependencies and terminal configuration
hardlink-preauth-release/
preauth-release.exe
config.yml # Configuration for the separate release task
logs/
```
`config.yml` and the ChipDNA executable path are relative to the working
directory. `TicketLayout.xml` is loaded beside the Hardlink executable. Configure
the release task's working directory to contain its own `config.yml`.
The HTTP server binds to `:<port>` on all interfaces; the default port is `9091`.
## Configuration
Place `config.yml` alongside `hardlink.exe`:
Example `config.yml` for card issuance and printing:
```yaml
port: 9091
lockType: "assaabloy"
lockservUrl: "http://192.168.4.109:4000"
encoderAddr: "1"
dispensPort: "COM9"
dispensAddr: "15"
printerName: "EPSON TM-T82II Receipt"
logdir: "./logs"
isPayment: false
```
Provide `TicketLayout.xml` for print layout:
- `lockType` is required: `assaabloy`, `omnitec`, `salto`, `tlj` or `kaba`.
- `cert` supplies the certificate value used by TLJ's GuestCard API.
- `dispensAddr` is the two-character serial device address.
- `printerName` must match an installed Windows printer.
- Payment setup additionally uses `isPayment`, `hotel`, `kiosk`, `cmsurl` and,
when CMS does not select a provider, `paymentProvider` (`creditcall`, `dojo` or
`paybridge`). Provider-specific terminal settings are read from CMS.
- SQL configuration uses `dbport`, `dbname`, `dbuser` and `dbpassword`; configure
these for monetary CreditCall PREAUTH persistence and the release task.
- `senderroremails` contains recipients for operational error emails.
- `timeoutSeconds` defaults to `300` for the generic payment handler. CreditCall
retains its independent 300-second start/confirmation call bounds.
Example `TicketLayout.xml`:
```xml
<LayoutOptions>
<LogoPath>C:/Logo/logo.png</LogoPath>
<TopMostText>Welcome to The Bike and Boot</TopMostText>
<TopMostText>Welcome to the hotel</TopMostText>
<BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
<BeforeDirectionsText></BeforeDirectionsText>
<HotelSpecificDetails>This is the hotel details section</HotelSpecificDetails>
<HotelSpecificDetails>Hotel information</HotelSpecificDetails>
<CheckOutTimeText>Check Out Time</CheckOutTimeText>
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
</LayoutOptions>
```
## Build & Run
## Door cards and K720 recovery
```bash
# Install dependencies
go mod tidy
`POST /issuedoorcard` accepts `Content-Type: application/json`:
# Build the executable
go build -o hardlink.exe
# Run
./hardlink.exe
```json
{
"roomField": "101",
"checkinTime": "2026-10-23 15:00:00 +0100",
"checkoutTime": "2026-10-24 11:00:00 +0100",
"followStr": "0"
}
```
The HTTP server listens on `http://localhost:<port>` (default `9091`).
Times use `2006-01-02 15:04:05 -0700`. A successful response is:
## API Endpoints
```json
{"code":200,"message":"Card issued successfully"}
```
### 1. Issue Door Card
Errors use the same `code`/`message` JSON structure with an HTTP error status.
Exact physical empty (`0x38`) during preparation returns `503`; preparation
exhaustion and encoding errors return `502`.
- **Endpoint**: `POST /issuedoorcard`
- **Headers**: `Content-Type: application/json`
- **Body**:
```json
{
"roomField": "101",
"checkinTime": "2025-04-08 11:16:05 +0100",
"checkoutTime": "2025-04-08 12:00:00 +0100",
"followStr": "0"
}
```
- **Responses**:
- `200 OK`
```json
{ "Code": 200, "Message": "Card issued successfully" }
```
- `4XX` / `5XX`
```json
{ "Code": <status>, "Message": "<error>" }
```
The serial worker exclusively owns AP, RS, FC7 and FC0 communication. Preparation
uses fresh AP observations, a 32-second preparation budget, one-second polling,
and at most three RS/shake recoveries. A valid encoder position permits encoding
immediately. Uncertain or unusable observations after FC7 share a four-second
window before an uncertain handoff may permit one encoding attempt.
### 2. Print Room Ticket
Only an uncertain handoff enables recovery concurrently with the single
`LockSequence`. It carries forward the shakes already used and runs the remaining
`RS -> 2-second settle -> AP -> FC7 -> AP` recovery sequence. Encoder confirmation
stops recovery, including before FC7 if the diagnostic AP confirms the card.
Unusable diagnostic AP is logged; it does not create a new fatal encoding error.
There is no second `LockSequence` or extra plain FC7 retry.
- **Endpoint**: `POST /printroomticket`
- **Headers**: `Content-Type: application/xml`
- **Body**:
```xml
<roomdetails>
<customername>John Doe</customername>
<checkoutdatetime>16/05/2025 11:00 am</checkoutdatetime>
<roomno>103</roomno>
<roommap>map.png</roommap>
<roomdirections>Follow corridor...</roomdirections>
</roomdetails>
```
- **Responses**:
- `200 OK`
```json
{ "Code": 200, "Message": "Print job sent successfully" }
```
- `4XX` / `5XX`
```json
{ "Code": <status>, "Message": "<error>" }
```
When `LockSequence` returns, the handler cancels and joins recovery before one
FC0 delivery attempt. Caller cancellation stops recovery; already-started encoding
retains its original lock-server timeout and result. Recovery/FC0 errors do not
replace that result. Successful encoding keeps the existing best-effort next-card
prestage. Idle maintenance and passive status polling remain separate from the
foreground issuance operation.
## Packages
See the [K720 dispenser contract](internal/dispenser/K720_DISPENSER_CONTRACT.md)
for status classifications, clearance rules, recovery limits and cancellation.
Concurrent recovery still requires validation with the physical K720 and lock server.
### `main`
- Entry point: reads config, sets up logging, initializes dispenser and lock server, loads print layout, and starts HTTP server.
## Room tickets
### `dispenser`
- Communicates with the card dispenser via serial port.
- Commands: check status, move card, eject card.
`POST /printroomticket` accepts `Content-Type: application/xml`:
### `lockserver`
- Manages TCP connection to the Assa Abloy lock server.
- Sends heartbeat and encoding commands.
```xml
<roomdetails>
<customername>John Doe</customername>
<checkoutdatetime>24/10/2026 11:00 am</checkoutdatetime>
<roomno>103</roomno>
<roommap>map.png</roommap>
<roomdirections>Follow the corridor...</roomdirections>
</roomdetails>
```
### `printer`
- Loads `TicketLayout.xml` into `LayoutOptions`.
- Provides `printLogo`, `printMap`, `BuildRoomTicket`, `SendToPrinter`.
- Converts images to ESC/POS raster commands with dithering and transparency support.
Success returns HTTP `200` with:
### `cmstypes`
- Defines JSON and XML payload structures for door cards and room details.
```json
{"code":200,"message":"Print job sent successfully"}
```
The printer package loads the ticket layout, renders ESC/POS text and raster
images, and sends the output to the configured Windows printer.
## Payments
| Endpoint | Request | Purpose |
| --- | --- | --- |
| `POST /api/payment/sale` | JSON | SALE streaming for CreditCall, Dojo or PayBridge |
| `POST /api/payment/preauth` | JSON | CreditCall PREAUTH/account-verification streaming |
| `POST /takepayment` | `text/xml` | Legacy CreditCall SALE |
| `POST /takepreauth` | `text/xml` | Legacy CreditCall PREAUTH/account verification |
The streaming endpoints return `application/x-ndjson`: progress frames followed
by a final result. CreditCall's structured final frame uses `result`;
Dojo/PayBridge use their existing `response` frame. Progress is observational and
never determines payment success or failure.
SALE JSON example (integer minor units):
```json
{"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"}
```
CreditCall monetary PREAUTH JSON example (string fields):
```json
{"amount":"3100","transactionType":"Sale","checkoutDate":"2026-10-24 00:00:00 +0000"}
```
Zero-value account verification:
```json
{"amount":"","transactionType":"AccountVerification","checkoutDate":""}
```
CreditCall SALE confirms approved starts; PREAUTH does not confirm. PREAUTH uses
the provider-returned `TRANSACTION_TYPE` and `TOTAL_AMOUNT`. Approved returned
`ACCOUNT VERIFICATION` needs no amount and is not persisted. Approved returned
`SALE` schedules persistence using the returned amount; it never substitutes the
request amount. SQL failures fall back to `preauth_spool.ndjson` in `logdir`.
The current SQL release date is checkout plus 96 hours, using the existing
local-midnight date conversion.
After financial dispatch, a kiosk disconnect stops stream delivery without
cancelling CreditCall result processing, SALE confirmation, receipts or PREAUTH
persistence scheduling. Never restart a transaction or fall back to a legacy
endpoint because streaming delivery failed.
Deploy a matching ChipDNAClient build: Hardlink starts
`./ChipDNAClient/ChipDnaClient.exe` and calls it on `127.0.0.1:18181`. That deployed
EXE must include `TRANSACTION_TYPE` and optional `TOTAL_AMOUNT` in its streaming
allowlist; an older build can support SALE while breaking PREAUTH classification.
See [CreditCall streaming](CREDITCALL_STREAMING.md) for frame schemas, progress
ownership and timeout details. The current SQL implementation in
`internal/db/db.go` defines release scheduling.
## Additional endpoints
| Endpoint | Purpose |
| --- | --- |
| `/dispenserstatus` | Cached stock/status in a `code`/`message` JSON response |
| `POST /testissuedoorcard` | Diagnostic issuance path; not the normal delivery workflow |
| `/ping-pdq` | Read ChipDNA terminal status |
| `POST /logerror` | Receive ChipDNA error notifications |
## Logging
Logs are written in JSON format to `<logdir>/hardlink.log`.
JSON logs are written to `<logdir>/hardlink.log`. Weekly rotation uses local
Monday midnight and retains `hardlink.1.log` through `hardlink.13.log`. The separate
release task writes `preauth-release.log` with the same rotation policy.
---
K720 logs include uncertain handoff, raw AP status/classification, RS/FC7 attempts,
remaining shake budget, recovery stop reason and encoding duration. PREAUTH logs
include processor result/type, transaction reference, approval/persistence
decision, missing fields, and SQL/spool outcomes without card or receipt payloads.
MIT © FutureSens Systems
## Verification
Use repository-local build and temporary caches from PowerShell:
```powershell
New-Item -ItemType Directory -Force .cache/go-build, .cache/tmp | Out-Null
$env:GOCACHE = Join-Path $PWD '.cache/go-build'
$env:GOTMPDIR = Join-Path $PWD '.cache/tmp'
go test -mod=readonly -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -race -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -count=1 -skip '^Test_SendMail$' ./...
go vet -mod=readonly ./...
go build -mod=readonly ./...
git diff --check
```
`Test_SendMail` sends real email and is excluded from offline verification.
Automated tests do not replace physical dispenser, encoder, terminal or printer
validation.
## Deployment
Production deployment uses Salt. Build the intended revision and deploy the
versioned Windows package through the Salt repository and Hardlink pillar.
Where installed, local release tooling is invoked as `bash ./winbuild.sh <version>`
from the `development` branch. It builds Hardlink and the release task, packages
the existing `ChipDNAClient/` directory into `hardlink_windows_<version>.zip`, and
copies it to `salt/hardlink/files`. It also checks out/pulls the Salt and pillar
repositories and commits/pushes the package in Salt; it does not create a Git tag.
Ensure `ChipDNAClient/` contains the intended build before packaging.
Update `pillar/hardlink/init.sls` to select the package version, then apply the
Hardlink state to the intended hosts:
```bash
salt '<target-minion>' state.apply hardlink
```