Promote release candidate and add release evidence
This commit is contained in:
@@ -0,0 +1,44 @@
|
||||
# Team access and hotel setup
|
||||
|
||||
Owners manage colleagues in **Your team**. The **Hotel setup** page shows progress derived from the hotel's saved MongoDB settings, approved answers, mailbox synchronization and active staff accounts. It does not enable any external action. Preview accounts and progress are temporary.
|
||||
|
||||
## Invite and recover staff
|
||||
|
||||
1. Enter the colleague's name and work email in Your team and create an invitation link.
|
||||
2. Verify the intended recipient and share the link privately through your established workplace channel. GuestOps does **not** email the link. The link grants access to set that account's password; treat it as a temporary credential.
|
||||
3. The colleague opens the link, chooses and confirms a unique password of 14–128 characters, then signs in normally. Staff cannot manage hotel controls or team accounts.
|
||||
|
||||
Invitations expire after 48 hours. **Reset password** issues a 30-minute link for an active staff account. The current password and sessions continue to work until the reset is accepted; then previous sessions are invalidated on their next request. **Revoke link** invalidates an outstanding link without changing an active account's password. Issuing another link replaces the previous one.
|
||||
|
||||
**Disable access** invalidates existing sessions and outstanding links. **Restore access** issues a 48-hour link that requires a new password before the disabled account becomes active. It does not restore access using the old password. Owner accounts cannot be disabled or recovered through staff controls.
|
||||
|
||||
An email belongs to one hotel account. Existing active accounts cannot be reassigned through an invitation. The 50-account pilot limit is a best-effort administrative limit, not an atomic quota. Roles in this release are Owner and Staff; granular roles, per-user preferences, MFA, public registration and self-service email recovery are future work.
|
||||
|
||||
## Owner recovery on the Linux server
|
||||
|
||||
The server administrator must verify the owner's identity before issuing a recovery link. On the server, in the directory containing the deployed Compose file and its private environment file:
|
||||
|
||||
```sh
|
||||
read -r -p 'Verified owner email: ' RECOVERY_EMAIL
|
||||
export RECOVERY_EMAIL
|
||||
docker compose run --rm --no-deps -e RECOVERY_EMAIL api --recover-owner
|
||||
unset RECOVERY_EMAIL
|
||||
```
|
||||
|
||||
The command uses the configured database, generates a private link, prints it to the administrator's terminal and exits. Share it only with the verified owner. Do not paste it into tickets, chat logs, build logs or source control; avoid running this command in a recorded terminal. It expires in 30 minutes and can be consumed once. Running the command again invalidates the earlier link. Bootstrap remains a create-only command and cannot reset passwords.
|
||||
|
||||
`PublicUrl` must be the configured HTTPS origin, normally `https://sandbox-guestops.futuresens.co.uk`. Request Host headers never determine recovery-link origins. The Development-only preview uses `http://127.0.0.1:5173`.
|
||||
|
||||
## Storage and session behavior
|
||||
|
||||
MongoDB stores the SHA-256 hash of a random 256-bit token, its purpose and expiry. The raw token is returned only when issuing the link. Expiry is checked during inspection and again during atomic acceptance. Account records are not TTL-deleted when a link expires. Password hashing, version checks and a new security stamp prevent concurrent reuse and invalidate older sessions. Existing pre-migration accounts default to an empty stamp; their cookies remain valid until reset, disablement or normal expiry.
|
||||
|
||||
Tokens travel in URL fragments and are removed from browser history as the account page opens; submission uses POST with CSRF validation. API responses are not cached and referrer policy is `no-referrer`. The frontend holds the token only in component memory. Reloading after the fragment was removed requires reopening the original link. No analytics or third-party scripts are included on this page.
|
||||
|
||||
Account endpoints have rate limits. Because the reverse proxy currently forwards HTTPS status but not client IP addresses, anonymous recovery limits are shared behind that proxy. This can temporarily limit concurrent users; per-client limiting requires a separately reviewed trusted-proxy configuration.
|
||||
|
||||
Account changes appear in workspace activity without links, password hashes or tokens. Automated notification emails are not implemented, including password-change alerts. Recovery is an administrator-assisted process until verified transactional email is added. This is not a claim of production identity-provider completeness.
|
||||
|
||||
## Acceptance
|
||||
|
||||
Automated tests cover invitation/recovery acceptance, concurrent single-use enforcement with real MongoDB, expiry, reissue/revocation, session invalidation, staff restrictions, owner protection, cross-hotel access, configured origins and secret-free API views. Before inviting real staff, verify the deployed HTTPS link, private handoff process, owner recovery command and backup/restore procedure with test accounts.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Controlled FAQ auto-replies
|
||||
|
||||
The first automatic-response implementation supports seven exact English questions about check-in, check-out, parking, breakfast, Wi-Fi and the hotel's address. An owner maps each question to approved hotel knowledge. Responses use that answer verbatim plus the hotel signature; no AI classification or rewriting occurs.
|
||||
|
||||
## Start with test mode
|
||||
|
||||
Open **FAQ automation**, choose a question and approved answer, enable the rule and save it. Use **Try a question** to inspect the content match without sending. This tester does not simulate recipient, MIME, Gmail-thread or quota checks. Use **Test mode** with a connected sandbox mailbox to evaluate newly received messages and inspect the actual incoming-message results. Test matches do not create deliveries or consume quotas.
|
||||
|
||||
Matching tolerates case, whitespace and trailing question marks/full stops. It does not remove greetings, signatures, quoted text or additional requests. Subjects must be blank, one of the supported questions, or a short permitted heading such as `Question`, `Quick question`, `Parking question`, `Check-in`, `Breakfast` or `WiFi`. Unsupported content stays with staff.
|
||||
|
||||
The first version requires a top-level plain-text MIME message. HTML and multipart messages are held for staff because the alternate body may contain context missing from plain text. Attachments, multiple recipients, CC/BCC, reply threads, mailing lists, automated-message headers, mismatched Reply-To and no-reply senders are also excluded. Old imported messages without the new eligibility flag cannot qualify.
|
||||
|
||||
## Enable live mode after acceptance
|
||||
|
||||
Keep `AUTO_REPLY_ENABLE_LIVE=false` in the deployment `.env` until the Google send/reconciliation workflow and FAQ test-mode results have been accepted. Then set it true and restart both API and worker. Gmail sending must be configured, the hotel must enable staff sending, and the mailbox must have send consent. Finally, the owner explicitly confirms test-mode acceptance and selects **Enable live replies**.
|
||||
|
||||
All modes default to Off. Every mode change creates a new activation boundary and invalidates previous queued automatic approvals. Only untouched messages received after activation and within the last 24 hours are eligible. Switching Test to Live does not send replies to previous test matches. The evaluation worker runs about every 30 seconds; the existing delivery worker handles approved outgoing messages.
|
||||
|
||||
## Limits and rechecks
|
||||
|
||||
MongoDB uniquely reserves one automatic reply per Gmail thread, one per recipient per UTC day across the hotel's mailboxes, and at most 20 daily hotel slots. Slots are reserved before queueing and are not recycled after rejection or failure. Deliveries cannot carry their approval into a later UTC day. Limits concern GuestOps automation, not messages sent manually in Gmail. UTC boundaries are not rolling 24-hour windows.
|
||||
|
||||
The worker rechecks hotel mode, activation, server enablement, rule version, approved knowledge version and exact reply text before sending. It reads the current Gmail thread and requires the original inbox message to be its only message. A rule/answer edit or a new thread reply therefore stops queued automation. Changes made after the final read and provider submission cannot be eliminated atomically; a message already submitted to Gmail cannot be recalled by the stop control.
|
||||
|
||||
Automatic MIME includes `Auto-Submitted: auto-replied` and `X-Auto-Response-Suppress: All`, following the loop-prevention guidance in [RFC 3834](https://www.rfc-editor.org/rfc/rfc3834). This does not guarantee cooperation from every mail system.
|
||||
|
||||
## Staff handover and recovery
|
||||
|
||||
Non-matches remain in the inbox with an evaluation reason. Existing staff edits, drafts and deliveries are never overwritten. Editing an approved knowledge answer invalidates its FAQ rules until an owner reviews and saves them again.
|
||||
|
||||
A rejected automatic delivery was stopped before Gmail submission. **Return to staff review** releases its draft for manual review and preserves the rejected approval evidence. Uncertain outcomes cannot be released or automatically replayed; use the existing read-only Gmail Sent verification. Turning automation off stops pending automatic deliveries at the next pre-send check. Manual staff-approved replies remain governed by their own controls.
|
||||
|
||||
The database retains thread/recipient/quota reservations and evaluation evidence. The UI shows evaluated messages among the latest 500 inbox records. An evaluation interrupted before queueing can consume a slot without sending; it is deliberately not automatically retried.
|
||||
|
||||
## Acceptance and follow-on work
|
||||
|
||||
Automated tests use fake provider handlers and MongoDB; they never send live emails. They cover exact matching, exclusions, tenant boundaries, changed answers, concurrent evaluation, quotas, rule/epoch invalidation, Gmail-thread changes and uncertain delivery. Live acceptance remains pending.
|
||||
|
||||
Test allowed questions and exclusions with your sandbox mailbox, verify duplicate prevention across restarts, inspect the actual received email, and exercise the stop control before enabling a hotel. Broad natural-language matching, multilingual questions, greetings/signature stripping, HTML/multipart equivalence and higher throughput are follow-on work requiring representative evaluation. PMS actions, payment requests and complex guest issues remain staff workflows.
|
||||
+4
-4
@@ -44,7 +44,7 @@ docker compose run --rm --no-deps -e BOOTSTRAP_EMAIL -e BOOTSTRAP_HOTEL -e BOOTS
|
||||
unset BOOTSTRAP_EMAIL BOOTSTRAP_HOTEL BOOTSTRAP_PASSWORD
|
||||
```
|
||||
|
||||
There is no development/demo account in production. Staff invitation and password recovery UI are follow-on work; do not treat this as a public self-service service yet.
|
||||
There is no development/demo account in production. Owners can issue staff invitation and assisted recovery links through Team; see [account setup](accounts.md). Passwords must be 14–128 characters. Public self-registration is not enabled.
|
||||
|
||||
## 4. Configure HTTPS
|
||||
|
||||
@@ -62,7 +62,7 @@ Create or select your Google Cloud project, enable Gmail API, and configure a We
|
||||
|
||||
`https://sandbox-guestops.futuresens.co.uk/api/integrations/google/callback`
|
||||
|
||||
Configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the server's `.env` and recreate the API/worker services. Sign in as hotel owner, open Settings and connect a dedicated test mailbox. The only requested Gmail scope is `gmail.readonly`.
|
||||
Configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the server's `.env` and recreate the API/worker services. Sign in as hotel owner, open Settings and connect a dedicated test mailbox. By default the only requested Gmail scope is `gmail.readonly`. Optional staff-approved sending adds `gmail.send` after server configuration and reconnection; see [AI drafts and reply delivery](replies.md).
|
||||
|
||||
OAuth requests expire after ten minutes, are bound to the signed-in user and hotel, and can be consumed once. Refresh tokens are protected with ASP.NET Data Protection. API and worker share the private persistent key volume; back it up securely with the database. Losing it prevents existing mailbox tokens and sessions from being decrypted. Filesystem protection for the key volume is required; it is separate from MongoDB and must not be publicly served or committed.
|
||||
|
||||
@@ -70,6 +70,6 @@ A multi-hotel production launch using Gmail restricted scopes requires planning
|
||||
|
||||
## 6. Acceptance and rollback
|
||||
|
||||
Verify separate hotels cannot read or edit each other's records; save and reload settings; restart services and confirm persistence; import test messages twice without duplicates; check the worker resumes a paginated import; confirm no mail is sent. Review the activity log and Google account used by the connection.
|
||||
Verify separate hotels cannot read or edit each other's records; save and reload settings; restart services and confirm persistence; import test messages twice without duplicates; check the worker resumes a paginated import; confirm no mail is sent without explicit staff approval and that default-disabled sending remains blocked. Review the activity log and Google account used by the connection.
|
||||
|
||||
Keep reviewed image tags for rollback and backups of both MongoDB and the key volume. Do not remove named volumes to fix application errors. The initial release has no automatic schema migration that destroys data. Establish retention, off-server backup and a restore drill before importing real guest data.
|
||||
Keep reviewed image IDs and release images for rollback and backups of both MongoDB and the key volume. Do not remove named volumes to fix application errors. The initial release has no automatic schema migration that destroys data. Use the [operational preflight, encrypted backup and isolated restore drill](operations.md), and establish retention and off-server copies before importing real guest data. `/health/ready` checks database reachability; the owner's Workspace health page also reports worker heartbeat and mailbox/reply exceptions.
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# Google mailbox management
|
||||
|
||||
Owners manage Google connections in **Settings → Google mailbox**. Staff can see synchronization health but cannot disconnect, reconnect or restart imports. The panel refreshes every 30 seconds while visible and offers a manual status refresh.
|
||||
|
||||
## Connection and recovery
|
||||
|
||||
- **Connect Google mailbox** starts OAuth consent. Initial import covers seven days of inbox messages, in pages of up to 25 messages per worker cycle.
|
||||
- **Reconnect Google** requires the same email address as the selected connection. Reconnection retains the mailbox ID and imported history, clears the page token and resumes the existing import window. It does not create a second copy of imported messages.
|
||||
- **Restart import pass** clears the current page checkpoint without advancing the window. Use it for an import that needs another pass. It cannot bypass an active retry delay or repair revoked consent; those require waiting or reconnection respectively.
|
||||
- **Disconnect from GuestOps** clears the stored encrypted refresh token, removes sending capability and stops new work once workers recheck the connection. Imported messages and drafts remain. Requests already in progress may finish.
|
||||
|
||||
Disconnect is local to GuestOps. To revoke Google's authorization as well, use the Google account connections link shown after disconnection and remove GuestOps access. This is deliberately separate: revoking a shared Google app grant can affect other sessions. GuestOps does not claim that a local disconnect revokes provider consent. Google's [OAuth documentation](https://developers.google.com/identity/protocols/oauth2/web-server#tokenrevoke) describes revocation and account settings.
|
||||
|
||||
An OAuth flow started before the most recent connection change cannot reactivate that old connection. Concurrent connection changes use version checks. A mailbox email stays assigned to its hotel even after disconnect; moving it to another hotel requires a separately reviewed administrator migration.
|
||||
|
||||
## Health states
|
||||
|
||||
The panel shows the last successful import page, last attempt, next scheduled attempt, whether additional pages remain, and a safe explanation. It never returns refresh tokens, provider page tokens or raw provider error bodies.
|
||||
|
||||
- **Reconnect needed:** revoked/expired refresh access, rejected access authorization, or unreadable protected credentials. The import worker stops trying until reconnection.
|
||||
- **Waiting for retry:** temporary network/provider failures and quota responses. Import retries use an increasing delay, starting at about one minute and capped at about one hour, with jitter. A provider Retry-After can extend this up to one day.
|
||||
- **Configuration or permission failure:** directs the administrator to review the Google app configuration or authorization; subsequent checks are spaced about an hour apart.
|
||||
- **Catching up:** another page remains in the current import window. The last successful time refers to a page, not proof that the entire inbox is current.
|
||||
|
||||
Google's [Gmail error guidance](https://developers.google.com/workspace/gmail/api/guides/handle-errors) informs the error classification. A message returning 404 after listing is skipped. If Google rejects a saved pagination request with 400, GuestOps clears its page token, waits one minute and restarts the same window. Other malformed data can still require operator investigation; this is not a full mailbox repair or quarantine system.
|
||||
|
||||
## Reply behavior across connection changes
|
||||
|
||||
Each new delivery approval records the current mailbox connection identity. Disconnect/reconnect changes that identity. Earlier pending approvals fail before submission and need explicit staff review/retry; automatic FAQ replies can return to staff review. A final connection check also runs after token acquisition. Requests already submitted to Google cannot be recalled. An uncertain delivery remains held and is never blindly resent.
|
||||
|
||||
Existing mailbox documents without a Version field remain compatible. Their connection identity defaults to empty until the next connection change. Sync updates require matching credentials, version and connected state, preventing an older worker from overwriting a disconnect or explicit checkpoint restart.
|
||||
|
||||
## Acceptance before a hotel pilot
|
||||
|
||||
Automated fixtures cover pagination, duplicate imports, deleted messages, invalid grants, throttling, client configuration failures, reconnect account matching, missing read scope, cross-hotel ownership, stale workers, interrupted connections and queued-reply protection. MongoDB and HTTP tests exercise persistence, legacy documents, owner-only controls and preview isolation. These tests do not contact Google.
|
||||
|
||||
With a dedicated test mailbox on the HTTPS sandbox, verify consent and callback configuration, initial import, disconnect, manual removal of Google access, reconnect, read-only and send scopes, retained drafts, and staff review of rejected approvals. Keep FAQ live sending and other external writes off until their separate acceptance procedures pass. Full Gmail thread aggregation, history-repair tooling and attachments remain future work.
|
||||
+40
-8
@@ -12,20 +12,52 @@ Local JSON stores and process mutexes are not reused in production. MongoDB enfo
|
||||
|
||||
The UI is an operational inbox rather than a port of the desktop booking grid. Real installations start empty. The sample hotel exists only in explicitly enabled Development preview mode. The preview banner remains visible at compact widths.
|
||||
|
||||
Authentication uses ASP.NET cookie protection and its password hasher. Sessions expire after eight hours and validate the user's active status and role on each request. Owner provisioning is an administrator CLI operation; no staff invitation or self-service recovery flow is claimed yet. A staff-facing pilot should not expand beyond administrator-supported accounts until those flows are added.
|
||||
Authentication uses ASP.NET cookie protection and its password hasher. Sessions expire after eight hours and validate the user's active status and role on each request. Owner provisioning remains an administrator CLI operation. Milestone 6 adds owner-issued staff invitations and assisted account recovery; transactional email recovery remains future work.
|
||||
|
||||
Gmail permissions are read-only. The worker fetches plain-text bodies and skips automated/list/bounce messages. It does not fetch attachments, mark messages read, delete them, send mail, or call a PMS. Initial import is seven days, 25 messages per worker cycle. Unfinished pages retain their checkpoint, and overlap between synchronization windows is deduplicated. Invalid provider pagination tokens currently require operator reconnection/reset of the mailbox checkpoint; there is no full history-repair UI yet.
|
||||
Gmail permissions are read-only. The worker fetches plain-text bodies and skips automated/list/bounce messages. It does not fetch attachments, mark messages read, delete them, send mail, or call a PMS. Initial import is seven days, 25 messages per worker cycle. Unfinished pages retain their checkpoint, and overlap between synchronization windows is deduplicated. Milestone 7 adds guarded checkpoint restart and connection recovery; full history repair remains future work.
|
||||
|
||||
## Next milestones
|
||||
## Milestone 2: AI drafts and staff-approved delivery
|
||||
|
||||
1. Test Google connection with a dedicated test mailbox; add provider fixture tests, disconnect/revocation, refresh failure recovery and full thread aggregation.
|
||||
2. Add staff invitations, account recovery, granular roles, user preferences and an onboarding wizard.
|
||||
3. Add AI draft generation from approved hotel knowledge, evidence display, evaluation cases and explicit staff escalation. Approve the data-processing arrangements for the selected AI provider.
|
||||
4. Implement a tenant-scoped durable send outbox, operator reconciliation and guarded FAQ auto-replies. Preserve the desktop rule that uncertain sends are never blindly replayed.
|
||||
5. Port supported PMS/payment adapters with vendor sandbox contract tests and reconciliation UI. Do not enable these by merely copying desktop settings or toggling a feature flag.
|
||||
Implemented optional OpenAI draft generation, validated hotel answer references, per-hotel owner controls, staff-approved Gmail sending, immutable MongoDB approval snapshots, worker claims and uncertain-delivery verification. Live provider acceptance remains pending. See [reply setup and recovery](replies.md). Automatic sending remains disabled. The read-only description above describes milestone 1 defaults; sending now requires explicit additional configuration and consent.
|
||||
|
||||
## Milestone 3: reviewed OHIP reservation updates
|
||||
|
||||
Implemented exact confirmation lookup, internal notes and owner-approved stay-date changes, with tenant-specific server credentials, MongoDB proposals, duplicate approval prevention, stale-booking checks and read-only recovery of uncertain results. Live OHIP sandbox acceptance is pending; writes remain off by default. See [PMS setup and limitations](pms.md).
|
||||
|
||||
## Milestone 4: NMI hosted invoices and reconciliation
|
||||
|
||||
Implemented owner-reviewed invoice creation, unique payment references, customer-email approval, tenant-specific merchant configuration, partial/paid invoice status and read-only recovery after lost responses. The hosted payment link is delivered by NMI's invoice email; the published API does not guarantee a URL for insertion into GuestOps replies. Live sandbox acceptance remains pending. See [payment setup and limits](payments.md).
|
||||
|
||||
## Milestone 5: controlled FAQ auto-replies
|
||||
|
||||
Implemented seven exact FAQ question rules, approved-answer version binding, test/live modes, durable daily quotas, Gmail thread rechecks and staff handover for rejected automatic replies. Plain-text messages only; broad natural-language matching is not claimed. Live Gmail and rule acceptance remains pending. See [automation setup and limits](auto-replies.md).
|
||||
|
||||
## Milestone 6: team accounts and hotel onboarding
|
||||
|
||||
Implemented owner-issued single-use invitation and recovery links, staff disable/restore controls, session invalidation after password changes, server-admin owner recovery and a setup checklist derived from saved hotel state. Links are copied and shared privately; GuestOps does not send recovery emails. See [account setup and limits](accounts.md).
|
||||
|
||||
## Milestone 7: Google mailbox lifecycle and recovery
|
||||
|
||||
Implemented owner-only disconnect/reconnect and import restart controls, synchronization health, revoked-access recovery, retry delays, page recovery and connection-bound reply approvals. Local disconnect removes saved credentials; provider grant revocation is a separate Google account action. See [mailbox operation and acceptance](mailboxes.md).
|
||||
|
||||
## Milestone 8: operational readiness
|
||||
|
||||
Implemented owner-only workspace health, database readiness, worker heartbeat, Linux deployment preflight, maintenance-window encrypted database/key/configuration backup and an isolated restore drill. The drill verifies collection counts, indexes and actual key decryption. Scheduling, off-server copies and production disaster cutover remain operator tasks; the Debian server rehearsal is still required. See [operations and recovery](operations.md).
|
||||
|
||||
## Remaining milestones
|
||||
|
||||
1. Run dedicated Google test-mailbox acceptance, add full thread aggregation and history repair, and rehearse server backup/restore before the first hotel pilot.
|
||||
2. Add verified transactional email for invitations and recovery notifications, MFA, granular roles and user preferences.
|
||||
3. Run a representative live AI draft evaluation, improve retrieval and evidence presentation, and approve the selected provider data-processing arrangements.
|
||||
4. Extend the implemented durable reply queue with operator recovery tooling and broaden the controlled FAQ rules only after live acceptance. Preserve the rule that uncertain sends are never blindly replayed.
|
||||
5. Validate the OHIP adapter against the property sandbox, extend supported PMS operations and validate NMI hosted invoices with the merchant sandbox. Add direct payment URLs only when a supported provider contract is available. Do not enable these by merely copying desktop settings or toggling a feature flag.
|
||||
|
||||
Windows DPAPI settings must not be copied to Linux as usable credentials. Re-enter provider credentials through the server setup and reauthorize each mailbox. No existing hotel data has been transferred.
|
||||
|
||||
## Capacity and operations
|
||||
|
||||
Target supplied by the owner: Debian 12, 4 CPU cores, 7.6 GiB RAM, 18 GiB free disk; MongoDB on the same machine. Compose includes conservative starting memory limits and capped logs, not a capacity guarantee. Keep database/key backups off-server and do not import entire mailboxes by default. Establish retention and restore testing before real guest data is used.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# Operations and recovery
|
||||
|
||||
The owner-only **Workspace health** page reports database reachability, the worker's last heartbeat, mailbox recovery counts and reply exceptions. A heartbeat older than three minutes is marked stale. It proves that the worker process recently reached MongoDB, not that every provider or job succeeded. Reply totals cover at most the latest 500 conversations in this hotel. The page does not verify backups. `/health/ready` returns only readiness status and HTTP 503 when the database cannot be reached.
|
||||
|
||||
## Release evidence and rollback
|
||||
|
||||
Every non-pull-request CI build packages the API and worker images under the full Git commit SHA. The accompanying `release-record.json` binds the archive checksum, application version, commit, image references and immutable Docker image IDs. Retain both files together in restricted off-host release storage; the CI artifact is a transfer mechanism, not the permanent archive.
|
||||
|
||||
Before deployment, verify the archive against its record without loading it:
|
||||
|
||||
```sh
|
||||
python3 - <<'PY'
|
||||
import hashlib, json, pathlib
|
||||
r = json.load(open('release-record.json', encoding='utf-8'))
|
||||
p = pathlib.Path(r['artifact']['name'])
|
||||
assert hashlib.sha256(p.read_bytes()).hexdigest() == r['artifact']['sha256']
|
||||
print(r['commit'], r['version'], r['images'])
|
||||
PY
|
||||
```
|
||||
|
||||
Load the archive, verify each loaded image ID matches the record, set `GUESTOPS_API_IMAGE` and `GUESTOPS_WORKER_IMAGE` to the recorded full-SHA references, and run the deployment preflight. Record the CI run, commit, checksum and operator in the change ticket. A release tag is an approval marker; do not move or reuse an existing tag. The application and web versions must match before the record can be created.
|
||||
|
||||
For rollback, first disable worker-driven external writes and reconcile any sending, payment or PMS operation that may have completed since the prior release. Confirm the previous release archive and record are retained, verify its checksum and image IDs, take an encrypted backup, then select the previous recorded image references in `.env` and recreate only the API and worker. Do not roll back MongoDB or the key volume merely to change application images. Run the online preflight, readiness check and read-only smoke test before re-enabling the worker or provider writes. If a release introduced an incompatible data change, follow its release-specific recovery plan rather than starting an older image against newer data.
|
||||
|
||||
## Deployment preflight
|
||||
|
||||
Run from the dedicated GuestOps checkout on Linux with Python 3.11 or later, Docker with Compose, and GnuPG installed. The tool supports the supplied three-service Compose deployment and the `guestops` database only. Docker access is administrator-equivalent; use the designated server operator account. Load the reviewed API, worker and MongoDB images first, configure `.env` with mode 600, and follow [deployment](deployment.md).
|
||||
|
||||
```sh
|
||||
python3 deploy/ops.py preflight --offline
|
||||
# After Nginx, DNS, TLS and services are running:
|
||||
python3 deploy/ops.py preflight
|
||||
```
|
||||
|
||||
Preflight checks production settings, shared persistent keys, unpublished MongoDB/worker ports, a loopback API port, required images and mounts, private secret files, and at least 8 GiB free disk. The online check also verifies the configured HTTPS readiness URL. This is not a firewall, capacity or provider acceptance test. Allow additional disk space for the database, images and temporary backup/restore files; the supplied server initially had 18 GiB free.
|
||||
|
||||
Configured provider files must be readable by the API container's `app` user while inaccessible to other users. Set their ownership to that image's application UID and mode 600, and run the backup as an authorized operator able to read them (for example root with its designated public GPG keyring). Keep their parent directory private. Empty shipped example files contain no credentials and do not need this ownership change. Check the UID in the reviewed image rather than assuming it matches your host login.
|
||||
|
||||
## Encrypted backup
|
||||
|
||||
Keep the recovery private key on an administrator-controlled recovery machine, with a securely stored passphrase and a second protected recovery copy. Import only its public key on the server and verify its full 40-character fingerprint through a trusted channel. The tool selects that exact fingerprint; it does not establish who owns the key. Do not put private keys, decrypted backups or provider secrets in GitHub.
|
||||
|
||||
```sh
|
||||
gpg --import /secure/path/recovery-public.asc
|
||||
gpg --fingerprint
|
||||
install -d -m 700 "$HOME/guestops-backups"
|
||||
read -r -p 'Verified recovery key fingerprint: ' BACKUP_RECIPIENT
|
||||
python3 deploy/ops.py backup --recipient "$BACKUP_RECIPIENT" \
|
||||
--output "$HOME/guestops-backups/guestops-$(date -u +%Y%m%dT%H%M%SZ).tar.gpg" \
|
||||
--confirm-maintenance
|
||||
unset BACKUP_RECIPIENT
|
||||
```
|
||||
|
||||
This command causes a maintenance interruption. It stops the API and worker, temporarily pauses MongoDB's TTL expiry monitor, dumps MongoDB, and saves the shared Data Protection keys and deployed configuration. The configuration includes credentials and provider files, so the entire bundle is encrypted. Services and the previous TTL setting are restored in a `finally` block before encryption finishes. A successful backup message does not prove that restarted services are healthy; run the online preflight afterwards.
|
||||
|
||||
No other application or administrator may write to this database during the snapshot. Standalone MongoDB dumps need coordinated writes for consistency; see the [MongoDB backup guidance](https://www.mongodb.com/docs/v8.0/tutorial/backup-and-restore-tools/). The tool is intentionally limited to the dedicated stack. It requires the hexadecimal MongoDB root password generated in the deployment guide.
|
||||
|
||||
Copy the encrypted file off-server to restricted storage after every successful backup. Retain the exact API, worker and MongoDB images with the release: an image tag alone can change, and the drill requires matching image IDs. Agree the backup schedule, retention and tolerated data loss before a hotel pilot. Scheduling, off-server transfer, deletion and alerting are operator responsibilities in this milestone; none is silently installed.
|
||||
|
||||
Temporary plaintext files are held in private directories and removed on normal completion or exceptions. Process termination or power loss can leave temporary data, stopped services or TTL expiry disabled. After an interrupted run, inspect the dedicated project and remove only its identified abandoned temporary directory after securing any recovery material. Restore the recorded TTL setting (normally true) and restart the services:
|
||||
|
||||
```sh
|
||||
docker compose exec -T mongo mongosh --quiet --nodb --eval 'const c=new Mongo("mongodb://127.0.0.1"); c.getDB("admin").auth(process.env.MONGO_INITDB_ROOT_USERNAME,process.env.MONGO_INITDB_ROOT_PASSWORD); const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:true}); if(!r.ok)quit(1);'
|
||||
docker compose start api worker
|
||||
python3 deploy/ops.py preflight
|
||||
```
|
||||
|
||||
Use the previous value instead of true if TTL expiry was deliberately disabled beforehand. Do not remove production volumes to recover from a failed backup.
|
||||
|
||||
## Isolated restore drill
|
||||
|
||||
Use a trusted encrypted backup and the recovery key on a Linux recovery machine. Unlock the key through the local GPG agent before running the batch command; never pass its passphrase on the command line. Load the exact reviewed images from the backed-up release first.
|
||||
|
||||
```sh
|
||||
python3 deploy/ops.py restore-drill /secure/path/guestops-backup.tar.gpg \
|
||||
--api-image guestops-api:REVIEWED_RELEASE \
|
||||
--mongo-image mongo:8.0
|
||||
```
|
||||
|
||||
The drill decrypts into a private temporary directory, checks the four expected files and their hashes, rejects unsafe archive entries, and verifies that the restored keys decrypt a protected test value. It then restores MongoDB into a newly created container with no external network or published ports and compares every restored collection's count and indexes. TTL expiry is disabled in this disposable database so expired token records do not disappear during comparison. The exact temporary container and its volumes are removed afterwards. No worker or production application is started.
|
||||
|
||||
The decrypted bundle is capped at 8 GiB for this pilot tool. Leave room for the encrypted file, decrypted archive, extracted files and restored database. GPG's [output limit](https://www.gnupg.org/documentation/manuals/gnupg/GPG-Input-and-Output.html) bounds decrypted output; checksums detect corruption, not the identity of the backup creator. Use backups from the trusted operator only. A drill checks counts, indexes and key decryption, not every document's business meaning or live provider connectivity.
|
||||
|
||||
## Actual disaster recovery
|
||||
|
||||
This milestone implements a rehearsal, not an automatic production restore or cutover command. Before real guest data is accepted, rehearse a separate recovery deployment and document its precise image IDs, volume names, secret locations and operator responsibilities.
|
||||
|
||||
Restore into new isolated MongoDB and key volumes; preserve the damaged original for investigation. Reconstruct reviewed configuration from the encrypted bundle without copying old Docker container IDs or blindly executing archived configuration. Restore the `guestops` database with the compatible MongoDB tools and restore the matching key files with the application's required ownership. Check hotel/account records and saved settings before exposing the recovered API. Keep the worker stopped, provider writes disabled and external network access restricted throughout this process.
|
||||
|
||||
**A restored database can predate emails, invoices and PMS changes that providers already completed.** Review pending, sending and uncertain records against provider evidence before enabling any worker, including automatic FAQ rules. Do not replay an older approval merely because the restored record says it is pending. Reconcile external effects, validate account sessions and mailbox authorization, and explicitly approve the cutover only after these checks. Rotate credentials if compromise prompted the recovery. Keep the old deployment stopped when enabling the replacement.
|
||||
|
||||
CI exercises a synthetic encrypted backup and isolated restore drill, including actual key decryption and database comparison. A successful CI drill is separate from the required rehearsal on the Debian server with its actual deployment configuration.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# NMI hosted payment requests
|
||||
|
||||
The Payments page prepares a reviewed invoice, creates it once through NMI, and checks its status. MongoDB stores each hotel's enablement setting, immutable proposal details and the latest verification result. Invoice creation and verification require an owner account. Provider credentials stay on the server.
|
||||
|
||||
## Configure a sandbox merchant
|
||||
|
||||
Copy `deploy/payments.example.json` to a private `payments.local.json` outside the checkout:
|
||||
|
||||
```json
|
||||
{
|
||||
"Payments": {
|
||||
"Hotels": {
|
||||
"REPLACE_WITH_INTERNAL_GUESTOPS_HOTEL_ID": {
|
||||
"BaseUrl": "https://sandbox.nmi.com",
|
||||
"MerchantAccount": "YOUR_STABLE_MERCHANT_ACCOUNT_ID",
|
||||
"SecurityKey": "YOUR_NMI_V5_MERCHANT_KEY",
|
||||
"CreatesEnabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the internal 32-character hotel ID shown on the Payments page. `MerchantAccount` is an administrator-maintained identity binding: verify it against the merchant account behind the key. Do not reuse the same identity for a different merchant. The API accepts only `https://sandbox.nmi.com` and `https://secure.nmi.com`; confirm the correct environment and key with NMI.
|
||||
|
||||
Set `PAYMENTS_CONFIG_FILE_HOST` in the deployment `.env` to the absolute private file path. Compose mounts it read-only in the API only. Restrict file permissions to the administrator and the container user/group that needs read access. Determine the image's user with `docker run --rm --entrypoint id YOUR_API_IMAGE -u` before assigning permissions. Restart the API after changes. The default empty example disables the integration. Do not commit private configuration or put keys in the browser.
|
||||
|
||||
After sandbox acceptance, enable `CreatesEnabled` on the server and **Allow owner-approved payment invoices** in the hotel's Payments page. Both controls are required. Turning off creation leaves read-only reconciliation available. Key rotation preserves reconciliation for the same merchant binding; pending approvals require the original credential revision and must be replaced after rotation. Changing the merchant identity blocks reconciliation until the original binding is restored.
|
||||
|
||||
## Staff workflow
|
||||
|
||||
1. Enter a unique payment reference, customer email, description, amount and currency. This milestone supports GBP, EUR and USD, with two decimal places and a maximum of 100,000 per invoice. Confirm the merchant supports the chosen currency.
|
||||
2. Prepare the request. This only writes a proposal to MongoDB. Check the guest's agreed amount and booking terms separately; preparation does not reserve inventory.
|
||||
3. Review and approve the amount, currency, recipient and customer email. Approval expires after fifteen minutes. Creating an NMI invoice can email the customer a hosted payment link. GuestOps does not call a separate send endpoint.
|
||||
4. Use **Verify with NMI** to refresh invoice status. It verifies invoice ID, order reference, recipient, amount and currency before accepting a known status. Partial payment is displayed separately. `Paid` means NMI reports the invoice paid; it is not proof of bank settlement and does not create or update a booking.
|
||||
|
||||
NMI's published [Create Invoice](https://docs.nmi.com/reference/create-invoice-v5) and [Get Invoice](https://docs.nmi.com/reference/get-invoice-v5) schemas were inspected on 2026-09-14. The published InvoiceResponse does not guarantee a `payment_url`. This implementation relies on NMI's hosted invoice email; it does not construct checkout URLs or insert a payment URL into Gmail drafts. Confirm invoice email delivery and hosted checkout with your sandbox merchant before enabling live creation.
|
||||
|
||||
## Interrupted requests and reconciliation
|
||||
|
||||
Every request has a unique hotel/payment reference enforced by MongoDB, including cancelled requests. Concurrent approvals create at most one local submission. No provider idempotency guarantee is assumed. A timeout or ambiguous response remains `NeedsReview` and creation cannot be repeated. Do not work around an uncertain result by inventing a new reference.
|
||||
|
||||
Verification is read-only. If the invoice ID was lost, GuestOps searches NMI by the server-generated order ID, starting one day before proposal creation, with at most ten pages of 100 invoices. An incomplete search, duplicate matches, missing invoice or mismatched details stays held for merchant-portal investigation. Interrupted `Creating` requests become eligible after five minutes; active requests have a ninety-second deadline. No automatic polling, invoice recreation, email retry or force-clear is implemented.
|
||||
|
||||
Only unsubmitted proposals can be cancelled in GuestOps. Invoice closure, refunds, disputes and settlement reconciliation are handled in the NMI merchant portal. Keep the operation reference and invoice ID when investigating. The latest 500 local records are shown; records are retained rather than automatically deleted. Status is an observation at the displayed verification time, not a live balance.
|
||||
|
||||
## Acceptance before live use
|
||||
|
||||
Automated tests use an in-process fake HTTP handler and never contact NMI. They cover tenant isolation, amount/currency/identity mismatches, partial status, concurrent approvals, lost create responses, pagination and merchant changes. CI checks the production configuration mount and disabled defaults.
|
||||
|
||||
Use a dedicated sandbox merchant and recipient to validate authentication, supported currency, exact request/response fields, preservation of `order_details.order_id`, customer invoice email and hosted checkout, partial/full payments and interrupted-request recovery. Live acceptance remains pending. Planet, direct payment links in GuestOps replies, automatic booking after payment, automated expiry/closure and background polling are follow-on work.
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
# OHIP reservations and approved changes
|
||||
|
||||
GuestOps supports exact confirmation lookup, internal reservation notes and stay-date changes for reservations in `Reserved` status. Each change is saved in MongoDB and reviewed by an owner before a single OHIP update attempt. Creation, cancellation, room/rate changes and payment links are not implemented in this milestone.
|
||||
|
||||
## Server configuration
|
||||
|
||||
Copy `deploy/pms.example.json` to a private `pms.local.json` outside your checkout and populate this structure, replacing the hotel ID with the internal GuestOps ID shown on the Reservations page:
|
||||
|
||||
```json
|
||||
{
|
||||
"Pms": {
|
||||
"Hotels": {
|
||||
"REPLACE_WITH_32_CHARACTER_GUESTOPS_HOTEL_ID": {
|
||||
"BaseUrl": "https://YOUR-OHIP-GATEWAY",
|
||||
"HotelCode": "YOUR_PROPERTY_CODE",
|
||||
"ClientId": "YOUR_CLIENT_ID",
|
||||
"ClientSecret": "YOUR_CLIENT_SECRET",
|
||||
"AppKey": "YOUR_APPLICATION_KEY",
|
||||
"EnterpriseId": "YOUR_ENTERPRISE_ID",
|
||||
"Scope": "urn:opc:hgbu:ws:__myscopes__",
|
||||
"WritesEnabled": false,
|
||||
"NoteType": "RESERVATION",
|
||||
"NoteLocation": "GEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the client-credentials grant and property permissions supplied for your OHIP environment. Confirm the note type and notification-location codes with the property. The gateway must be an HTTPS origin, without a path. There is no shared fallback configuration between hotels.
|
||||
|
||||
Set `PMS_CONFIG_FILE_HOST` in the deployment `.env` to the absolute private file path. Compose mounts it read-only into the API; the worker does not receive these credentials. Restrict host permissions to the administrator and the API container's user/group, while allowing that user to read the file. Obtain the image's user ID with `docker run --rm --entrypoint id YOUR_API_IMAGE -u` before assigning permissions. Never put credentials in the browser, repository or an image. Restart the API after configuration changes; this file is not hot-reloaded.
|
||||
|
||||
The default deployment mounts an empty example and makes no OHIP calls. Begin with sandbox credentials and `WritesEnabled: false`. Lookups can be tested without enabling writes. After sandbox acceptance, server write enablement and the hotel's owner-controlled MongoDB setting must both be enabled. Every operation still needs individual owner approval.
|
||||
|
||||
## Review and recovery
|
||||
|
||||
1. Look up the exact confirmation number and check guest, property, dates and booking details.
|
||||
2. Prepare an internal note or changed dates. Preparation saves a proposal; it does not update OHIP. Snapshots and approvals expire after ten minutes.
|
||||
3. For date changes, check availability, rate consequences and guest agreement in the PMS. GuestOps does not calculate or guarantee the resulting price.
|
||||
4. Review and approve. GuestOps re-reads the booking and rejects a changed snapshot before submitting. Only one active operation per hotel/reservation is allowed.
|
||||
5. GuestOps reads the result back. An HTTP success alone is insufficient. A timeout, interrupted request or mismatched result is held for verification and is never automatically replayed.
|
||||
|
||||
Use **Verify current PMS state** for uncertain results. An interrupted `Applying` operation becomes eligible after five minutes; the request deadline is ninety seconds. Verification only reads OHIP. Matching dates prove the observed state, not who changed it. Disabling writes does not prevent verification. Rotating credentials or changing the property binding invalidates old proposals and requires administrator investigation of unresolved operations.
|
||||
|
||||
A proposal can be cancelled before application. An uncertain applied operation cannot be cancelled or force-cleared from the UI: an operator must reconcile it with the PMS and audit history. There is no background retry or unsafe override. Lookup snapshots expire from MongoDB after one day; operation journals retain embedded before/after snapshots. The UI displays the latest 500 journal entries.
|
||||
|
||||
## Validation and limits
|
||||
|
||||
The adapter follows Oracle's [property reservation schema](https://github.com/oracle/hospitality-api-docs/blob/main/rest-api-specs/property/v1/rsv.json), version 26.3.0.0 inspected on 2026-09-10 (SHA-256 `8d95a8a060f2898eee7c9f749c83255ffde426258412c735e3f55180c0c000c1`). Notes use `putReservation`, preserving the existing comment array; dates update arrival/departure without inventing rate data.
|
||||
|
||||
Automated fixture tests cover tenant isolation, concurrent approvals, changed reservations, payload preservation, write controls, interrupted results and read-only reconciliation. They do not call OHIP and are not vendor certification. Before live enablement, validate your property's sandbox responses, note codes and retention, date/rate/inventory effects, credentials and permissions, and interrupted-request handling.
|
||||
|
||||
The adapter does not have a vendor-guaranteed conditional-write transaction. Re-reading before submission reduces stale updates but cannot eliminate a change made by another PMS user between that read and the write. Reservation updates therefore remain explicitly reviewed, narrow operations. Preview mode shows a sample proposal and blocks real PMS actions.
|
||||
@@ -0,0 +1,39 @@
|
||||
# AI drafts and staff-approved Gmail delivery
|
||||
|
||||
This milestone adds AI suggestions and a persistent send queue. It does not enable automatic replies, PMS writes or payments. No live OpenAI/Gmail acceptance testing has been performed; tests use HTTP fixtures that cannot forward requests to providers.
|
||||
|
||||
## Enable on the sandbox
|
||||
|
||||
1. Deploy the reviewed images using the deployment guide. Existing hotel records default to AI off and sending off.
|
||||
2. Set `AI_API_KEY` and `AI_MODEL` in the server's private `.env`. Choose a model available to your OpenAI project that supports the Responses API and strict JSON-schema output. No model is silently selected and no key is stored in frontend code or MongoDB. Only the API container receives the AI key.
|
||||
3. Recreate API/worker containers. In hotel Settings, the owner can enable AI drafts. The opt-in explains that staff-requested generation sends the message subject/body and selected approved hotel answers to OpenAI. Requests use `store: false`; this does not replace reviewing the provider's data-processing and retention arrangements.
|
||||
4. For sending, set `GOOGLE_ENABLE_SENDING=true`, recreate API/worker, and reconnect Google. The OAuth request then includes `gmail.readonly` and `gmail.send`. An existing read-only refresh token is not assumed to have send permission; the returned grant must explicitly include `gmail.send`.
|
||||
5. Enable staff-approved sending in that hotel's Settings. Use a dedicated test mailbox and synthetic guest messages for live acceptance tests before enabling a real hotel mailbox.
|
||||
|
||||
Google's consent-screen and verification requirements still apply. Never paste provider credentials into an issue, chat message or repository file.
|
||||
|
||||
## Staff workflow
|
||||
|
||||
Save edits before generating a new suggestion. Generation uses only approved answers from the signed-in hotel, with bounded keyword-based selection. The result includes answer IDs and a review note; invalid or foreign source IDs are rejected. Missing information or a provider-requested escalation leaves an empty draft for staff handling. The AI has no tools for sending, payments or PMS operations. Factual correctness still requires staff review and evaluation with representative guest emails.
|
||||
|
||||
Review and send shows the exact saved reply and destination before approval. The destination comes from a single valid Reply-To address, or From when Reply-To is absent. Staff cannot supply a different recipient through the API. No CC, BCC or reply-all is included. Check the address as well as the answer.
|
||||
|
||||
Approval atomically stores a body/recipient snapshot and stable message ID inside the conversation, using its current MongoDB version. The snapshot is locked against edits. One approval is allowed per imported incoming message. Multiple workers use the same version check before submitting the request. Gmail thread ID and RFC reply headers are included.
|
||||
|
||||
## Delivery and recovery
|
||||
|
||||
- **Pending:** approved and awaiting the worker. The worker checks hotel sending controls and mailbox permissions again before sending.
|
||||
- **Sending:** a worker claimed the request. A token or metadata failure before entering Gmail send becomes Rejected.
|
||||
- **Rejected:** nothing reached the Gmail send operation. Fix configuration and choose Retry approved reply; the original approved recipient/body are retained.
|
||||
- **Sent:** Gmail returned a message ID, or a matching message was verified in Gmail Sent. This means Gmail accepted the message, not proof the recipient read or received it without a later bounce.
|
||||
- **Needs verification:** a send timed out, returned an unexpected result, or was interrupted by restart. It is never automatically resent. Verify in Gmail Sent searches the stable message ID and checks the SENT label, sender and recipient. No unique match means the state stays uncertain; it is not evidence that sending failed. Staff must reconcile manually before any follow-up.
|
||||
|
||||
Switching off the hotel's sending control stops queued requests when the worker next checks them. It cannot recall an in-flight send. There is no automatic retry after entering Gmail send, even for an HTTP error. The worker's request deadline is shorter than the restart-recovery threshold.
|
||||
|
||||
Current limitations: messages imported before reply headers were stored must be handled in Gmail; this release does not backfill them. Full Gmail thread aggregation, reply-all, attachments, cancelling queued approval, a general reconciliation editor, staff invitation/recovery UI and automated FAQ sending remain later work. The sample preview never calls OpenAI or sends real mail.
|
||||
|
||||
## Verification
|
||||
|
||||
The test suite covers competing workers, send identity/thread headers, invalid recipients, header injection, uncertain outcomes, restart recovery, pre-send token failure, disabling hotel sending, cross-hotel access, Gmail reconciliation mismatches, AI source isolation, invalid citations, escalations and incomplete responses. CI also runs production container login/restart-persistence smoke checks. Live acceptance must additionally verify Google consent, actual threading, grant revocation, a representative AI draft evaluation set and provider error behaviour with the configured accounts.
|
||||
|
||||
Implementation references: [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [Gmail sending](https://developers.google.com/workspace/gmail/api/guides/sending), [Gmail threads](https://developers.google.com/workspace/gmail/api/guides/threads).
|
||||
Reference in New Issue
Block a user