diff --git a/README.md b/README.md index c1cee24..67d2f62 100644 --- a/README.md +++ b/README.md @@ -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 - ``` -2. **Tag and build**: - ```bash - ./tagbuild.sh - ``` - This script: - - Builds the latest `hardlink.exe` binary - - Tags the repository with the new version - - Copies `hardlink_.exe` to `salt/hardlink/files` -3. **Commit the new binary** in Salt: - ```bash - cd salt - git add hardlink/files/hardlink_.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 `:` 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 C:/Logo/logo.png - Welcome to The Bike and Boot + Welcome to the hotel Your room number is - This is the hotel details section + Hotel information Check Out Time C:/Logo/Roommaps ``` -## 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:` (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": , "Message": "" } - ``` +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 - - John Doe - 16/05/2025 11:00 am - 103 - map.png - Follow corridor... - - ``` -- **Responses**: - - `200 OK` - ```json - { "Code": 200, "Message": "Print job sent successfully" } - ``` - - `4XX` / `5XX` - ```json - { "Code": , "Message": "" } - ``` +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 + + John Doe + 24/10/2026 11:00 am + 103 + map.png + Follow the corridor... + +``` -### `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 `/hardlink.log`. +JSON logs are written to `/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 ` +from the `development` branch. It builds Hardlink and the release task, packages +the existing `ChipDNAClient/` directory into `hardlink_windows_.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 '' state.apply hardlink +```