Add reviewed AI drafts and durable staff-approved Gmail delivery

This commit is contained in:
wolf-demon
2026-09-10 09:26:40 +01:00
parent 41f8d805e8
commit b1548ed6e6
19 changed files with 456 additions and 22 deletions
+2 -2
View File
@@ -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.
+7 -3
View File
@@ -16,12 +16,16 @@ Authentication uses ASP.NET cookie protection and its password hasher. Sessions
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.
## Next milestones
## Milestone 2: AI drafts and staff-approved delivery
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.
## Remaining milestones
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.
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 guarded FAQ auto-replies after live acceptance. Preserve the 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.
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.
+39
View File
@@ -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).