refactor(hardlink): migrate Go module to v2

This commit is contained in:
2026-11-04 18:50:00 +00:00
parent 814d87768d
commit e07afd9df1
55 changed files with 1187 additions and 131 deletions
+192
View File
@@ -0,0 +1,192 @@
# Operations
[Project overview](../README.md) | [Configuration](configuration.md) | [Payment API](payment-api.md)
## 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`.
See [configuration](configuration.md) for local settings, the CMS payment field
mapping and the room-ticket layout.
## Door cards
`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`. Success returns:
```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 complete [K720 issuance contract](hardware/k720.md) covers worker ownership,
preparation, uncertain-handoff recovery, delivery clearance, cancellation and
idle maintenance. It includes the single `LockSequence`, shared three-shake
budget, log-only delivery errors and best-effort next-card prestaging rules.
Concurrent recovery with the actual dispenser and lock server still requires
controlled physical validation.
## 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.
## Additional endpoints
| Endpoint | Purpose |
| --- | --- |
| `GET /dispenserstatus` | Cached stock/status in a `code`/`message` JSON response |
| `POST /testissuedoorcard` | Operational diagnostic, available regardless of TestMode: encode and retain the card inside the dispenser; no guest delivery |
| `GET /ping-pdq` | Read ChipDNA terminal status |
| `POST /logerror` | Receive ChipDNA error notifications |
`/testissuedoorcard` is an operational hardware diagnostic available regardless
of TestMode. It prepares and encodes a card without FC0 guest delivery; the card
remains inside the dispenser for reuse. Its registration and hardware sequence
are separate from normal issuance and are not restricted to development kiosks.
## Native-only endpoint cleanup
The modern `/api/payment/sale`, `/api/payment/preauth`, `/issuedoorcard` and `/printroomticket` endpoints serve native Fyne HTTP clients. They no longer emit browser CORS headers or accept OPTIONS preflight requests; non-POST methods receive the existing method-rejection format. Successful POST payloads, responses, payment execution and hardware sequences are unchanged. Keycard requests need only `roomField`, `checkinTime`, `checkoutTime` and `followStr`.
`/dispenserstatus` and `/ping-pdq` are GET diagnostics (other methods return 405 with `Allow: GET`). The ChipDNA sidecar's asynchronous POST `/logerror`, error notifications and availability debounce remain operational. Background dispenser polling is unchanged.
`/testissuedoorcard` is unconditionally registered on production kiosks and retains its encoded card for reuse. No TestMode gate or automatic ejection has been added. The deprecated XML `/takepayment` and `/takepreauth` handlers and their required response/redirect helpers remain for their explicitly retained contract. Do not remove the active sidecar or printer/lock-server protocols as browser legacy.
## 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'
$env:TEMP = $env:GOTMPDIR
$env:TMP = $env:GOTMPDIR
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.
The existing `run_tests.sh` is not an offline verification entry point: it runs
`go mod tidy` and unfiltered full tests, including the live-email test. Use the
explicit commands above instead. Do not launch the service against hotel
configuration as part of offline 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
```
## Coordinated application releases
Deploy compatible ChipDNAClientCLI, Hardlink and native Fyne versions together.
The module path is `gitea.futuresens.co.uk/futuresens/hardlink/v2`; internal and
public package imports include `/v2`. The application `buildVersion` does not
publish a module tag automatically.
The owner must commit and publish the intended v2 release before the Fyne
applications pin its actual tag with `go get` and regenerate sums with
`go mod tidy`. Until publication, their zero pseudo-version marker is local-only
and resolves through ignored alternate modfiles replacing the `/v2` module with
the sibling checkout. Do not commit that replacement or invent remote checksums.
The existing Fyne/CMS/translate dependency replacements are independent.
Hardlink itself builds and tests from this checkout using its tracked module
files. Release history is recorded in [releases](releases.md).