270 lines
10 KiB
Markdown
270 lines
10 KiB
Markdown
# Hardlink
|
|
|
|
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.
|
|
|
|
## Build and run
|
|
|
|
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.
|
|
|
|
```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
|
|
|
|
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
|
|
```
|
|
|
|
- `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 hotel</TopMostText>
|
|
<BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
|
|
<BeforeDirectionsText></BeforeDirectionsText>
|
|
<HotelSpecificDetails>Hotel information</HotelSpecificDetails>
|
|
<CheckOutTimeText>Check Out Time</CheckOutTimeText>
|
|
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
|
|
</LayoutOptions>
|
|
```
|
|
|
|
## Door cards and K720 recovery
|
|
|
|
`POST /issuedoorcard` accepts `Content-Type: application/json`:
|
|
|
|
```json
|
|
{
|
|
"roomField": "101",
|
|
"checkinTime": "2026-10-23 15:00:00 +0100",
|
|
"checkoutTime": "2026-10-24 11:00:00 +0100",
|
|
"followStr": "0"
|
|
}
|
|
```
|
|
|
|
Times use `2006-01-02 15:04:05 -0700`. A successful response is:
|
|
|
|
```json
|
|
{"code":200,"message":"Card issued successfully"}
|
|
```
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Room tickets
|
|
|
|
`POST /printroomticket` accepts `Content-Type: application/xml`:
|
|
|
|
```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>
|
|
```
|
|
|
|
Success returns HTTP `200` with:
|
|
|
|
```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
|
|
|
|
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.
|
|
|
|
## 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
|
|
```
|