Add Google mailbox lifecycle controls and guarded sync recovery

This commit is contained in:
wolf-demon
2026-09-16 15:18:22 +01:00
parent 7fcf51c900
commit bc7cbc1492
20 changed files with 314 additions and 33 deletions
+37
View File
@@ -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.
+7 -2
View File
@@ -14,7 +14,7 @@ The UI is an operational inbox rather than a port of the desktop booking grid. R
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.
## Milestone 2: AI drafts and staff-approved delivery
@@ -36,9 +36,13 @@ Implemented seven exact FAQ question rules, approved-answer version binding, tes
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).
## Remaining milestones
1. Test Google connection with a dedicated test mailbox; add provider fixture tests, disconnect/revocation, refresh failure recovery and full thread aggregation.
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.
@@ -52,3 +56,4 @@ Target supplied by the owner: Debian 12, 4 CPU cores, 7.6 GiB RAM, 18 GiB free d