feat(hardlink): unify kiosk payments and finalize legacy cleanup

This commit is contained in:
2026-11-04 17:43:10 +00:00
parent 568adc034b
commit 814d87768d
57 changed files with 3624 additions and 1762 deletions
+20 -260
View File
@@ -3,267 +3,27 @@
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.
(ChipDNA), Dojo, PayBridge and Trust Payments providers.
## Build and run
## Documentation
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.
- [Configuration](docs/configuration.md): local service/device settings,
room-ticket layout and CMS-only Trust configuration.
- [Operations](docs/operations.md): builds, deployment layout, hardware HTTP
endpoints, diagnostics, logs and offline verification.
- [Payment API](docs/payment-api.md): unified Sale/PREAUTH requests, NDJSON
results, transaction ownership, receipts and CreditCall streaming details.
- [K720 hardware contract](docs/hardware/k720.md): preparation, uncertain-handoff
recovery, delivery clearance and maintenance invariants.
- [Release history](docs/releases.md).
- [Historical archive](docs/archive/README.md): superseded Trust plans and
audits, retained as dated evidence rather than current operating instructions.
```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
```
Hardlink owns payment-provider selection and terminal processing. The native
Fyne applications use the common Sale/PREAUTH contract and own their financial
calculations, PMS descriptions, PMS posting and guest journeys. Trust settings
come from CMS; no local `trust:` YAML section or currency-evidence flag is needed.
`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
```
The deprecated XML payment routes remain solely for legacy compatibility.
`/testissuedoorcard` remains an operational diagnostic available on production
kiosks regardless of TestMode, and retains the encoded card inside the dispenser.