Syrve / iiko live test playbook

Manual verification procedure for the always-on live IikoConnector bridge. A read-only smoke stays read-only by procedure: do not create or approve a posting.

Database migrations

Before the bridge and live reads, apply both PostgreSQL schemas:

1. PayDbContext — SyrveConnection, SyrveDocumentSnapshot, SyrveDocumentSyncRun, PaymentCandidate, extended allocations/postings.
2. IikoConnector AppDbContext — IikoRestaurantConnection and related bridge tables.

Recommended path (single database, both contexts):

cd backend
dotnet run --project src/MyHoreca.Pay.DbMigrator

The migrator applies Pay and IikoConnector migrations, then seed data. Verify both schemas exist before running bridge/test/sync.

Alternative: API startup can apply Pay migrations via AddPersistence; IikoConnector migrations still require DbMigrator or manual dotnet ef database update on IikoConnector.Persistence.

Read-only live test procedure

The Pay-host runtime is always on. There is no read-only env profile and no runtime/verification status flag block. If deployment replaces the whole Iiko section, preserve transport endpoint and RPC method fields documented in environment variables.

Read-only smoke is limited to connection/version probe, entity revision bootstrap (FromRevision=0, no client truncation) and document/reference reads. Do not execute a payment mutation during this smoke.

Optional credential mode for smoke (Password = plain secret SHA1-hashed for REST /resto/api/auth; PasswordHash = secret is precomputed iiko hash):

SYRVE_CREDENTIAL_MODE=Password
SYRVE_PASSWORD_SECRET_REF=env:TEST_SYRVE_PASSWORD

Result classification

Class	Meaning
PASS	Connected + sync completed + documents found
PASS_READONLY_EMPTY	Connected + sync completed + no documents, no auth/list errors
FAIL_AUTH	Server-info works; auth/session fails
FAIL_SYNC	Auth/session works; document list/sync fails
BLOCKED	Missing credentials, server unavailable, or local infra broken

Automated smoke script

PowerShell (Windows-friendly):

$env:PAY_API_BASE_URL = "http://localhost:5010"
$env:PAY_LOGIN_EMAIL = "admin@myhoreca.id"
$env:PAY_LOGIN_PASSWORD = "ChangeMe123!"
$env:SYRVE_CONNECTION_NAME = "Test Syrve"
$env:SYRVE_BASE_URL = "https://your-test-syrve.example.com"
$env:SYRVE_LOGIN = "demo"
$env:SYRVE_PASSWORD_SECRET_REF = "env:TEST_SYRVE_PASSWORD"
$env:TEST_SYRVE_PASSWORD = "***"
./scripts/syrve-readonly-live-smoke.ps1

Bash (requires curl and jq):

export PAY_API_BASE_URL=http://localhost:5010
# ... same variables ...
./scripts/syrve-readonly-live-smoke.sh

Windows: run with PowerShell 7+ (pwsh). Windows PowerShell 5.x rejects the script #Requires -Version 7.0 guard.

JSON artifacts are written to artifacts/syrve-live-readonly/<timestamp>/ (gitignored). Fill the read-only live test report template from script output and artifacts.

Local dev pitfalls

Symptom	Fix
API cannot reach PostgreSQL (Host=postgres)	Set ConnectionStrings__Default=Host=localhost;Port=5432;...
Gateway 502 to api:8080	Set ReverseProxy__Clusters__api-cluster__Destinations__api__Address=http://localhost:20001
DbMigrator: iiko_restaurant_connections already exists	DB from pay_test init; schemas already present — proceed if tables exist
Connection test auth_failed	Verify test iiko credentials and transport endpoint configuration; check diagnosticCode, authModeAttempted, httpStatusCode in test/health response; try SYRVE_CREDENTIAL_MODE=PasswordHash if secret is a hash

Preconditions

• Test Syrve/iiko server URL (not production unless explicitly approved)
• Login for test server
• Password or password hash available as environment secret (env:VAR_NAME)
• Pay API running and reachable (via Gateway or direct)
• PostgreSQL migrated (PayDbContext + AppDbContext)
• Admin or accountant user with Syrve permissions
• Registered Pay-host runtime and a bridged connection
• Operator commitment not to create or approve postings during the read-only scenario

Read-only scenario

1. Login as admin/accountant.
2. Create SyrveConnection with Environment=Test.
3. Set PasswordSecretRef=env:... pointing to the test secret in deployment env.
4. POST /api/syrve/connections/{id}/bridge
5. POST /api/syrve/connections/{id}/test
6. GET /api/syrve/connections/{id}/health
7. POST /api/syrve/connections/{id}/sync-documents
8. GET /api/syrve/documents/unpaid
9. POST /api/syrve/documents/{id}/refresh
10. Verify LastCheckStatus, LastSyncedAtUtc, PaymentStatus, RawPayloadHash (via DB or API DTO fields).

Expected result

• Bridge created (bridge_created / bridge_linked)
• Connection test returns connected or a clear business error (never fake success)
• Documents synced or sync run shows explicit error code
• No raw secrets in API responses
• No payment posting was created or approved

Payment write dry-run scenario

1. Build payment candidates for a matched bank transaction.
2. Create and confirm payment allocation.
3. Queue a posting and verify that it starts in ApprovalRequired.
4. Run preflight and dry-run; verify RBAC/scope, idempotency, payable/amount/allocation/anomaly checks, server applicability, credentials and method-specific transport readiness.
5. Do not call approve. Verify no IikoConnector write was performed.

Test write scenario — manual approval only

Warning: Run this only after owner approval and only against test Syrve/iiko.

1. Obtain owner approval for a tiny test payment.
2. Create a tiny test document/payment allocation.
3. Queue posting (POST /api/syrve/postings/queue/{allocationId}) and verify ApprovalRequired.
4. Run preflight and dry-run; resolve every safety blocker.
5. Approve posting (POST /api/syrve/postings/{id}/approve).
6. Let PaymentPostingWorker process the queue.
7. GET /api/syrve/postings/{id}/evidence
8. POST /api/syrve/postings/{id}/reconcile
9. Verify result in Syrve/iiko BackOffice.

Current implementation may return write_not_implemented at transport layer until live write facade is fully connected — evidence endpoint should still capture before/request/after snapshot.

Troubleshooting

Symptom	Check
bridge_missing	Run bridge endpoint first
credentials_missing	Env var from PasswordSecretRef exists in API container/host
auth_failed	Login/password for test server
Sync empty	LookbackDays, connection enabled, test server has documents

Related docs

• Syrve payment orchestration
• API — Syrve endpoints
• Environment variables
• Read-only live test report template