PSA/ee/docs/plans/2026-01-11-email-attachments-to-tickets/SCRATCHPAD.md

Scratchpad — Email Attachments → Ticket Documents

Summary (Implemented)

• Implemented a workflow-worker override for process_email_attachment that:

  • Enforces eligibility rules: skip inline/CID, max 100MB, require filename, allow all file types.
  • Downloads attachment bytes from provider (Microsoft Graph or Gmail).
  • Uploads bytes via StorageProviderFactory and creates external_files, documents, and document_associations rows.
  • Attributes uploaded_by_id, created_by, user_id to the configured inbound email “system user” (inbound_ticket_defaults.entered_by).
  • Uses strict idempotency via email_processed_attachments (stable PK: {tenant, provider_id, email_id, attachment_id}) with status + error recording.
  • Treats unsupported Microsoft attachment shapes as skipped (not a workflow failure).

• Citus compatibility:

  • Added tenant predicates to UPDATE email_providers ... in webhook routes to avoid scatter/gather updates and RLS issues.
  • Added a Citus distribution migration for email_processed_attachments (distributed by tenant, colocated with tenants).

Key Files

• Worker action override: services/workflow-worker/src/actions/registerEmailAttachmentActions.ts
• Worker wiring: services/workflow-worker/src/index.ts
• Schema:
  • server/migrations/20260111121500_create_email_processed_attachments.cjs
  • ee/server/migrations/citus/20260111123000_distribute_email_processed_attachments.cjs
• Provider downloads:
  • Microsoft: shared/services/email/providers/MicrosoftGraphAdapter.ts (downloadAttachmentBytes, isInline)
  • Gmail: server/src/services/email/providers/GmailAdapter.ts (downloadAttachmentBytes, isInline/contentId parsing)
• Citus webhook fixes:
  • server/src/app/api/email/webhooks/microsoft/route.ts
  • server/src/app/api/email/webhooks/google/route.ts

Test Coverage

• Vitest integration tests (business logic + DB assertions):

  • server/src/test/integration/emailAttachmentIngestion.integration.test.ts
  • server/src/test/integration/systemEmailProcessingWorkflowAttachments.integration.test.ts
  • server/src/test/integration/citusTenantFilterEmailProviders.integration.test.ts

• Playwright UI verification (documents visible on ticket):

  • ee/server/src/__tests__/integration/email-attachments-to-ticket-documents.playwright.test.ts

Playwright Notes ($playwright-testing)

• Cookie naming: the app suffixes the dev session cookie by port (authjs.session-token.<port>). Updated Playwright auth helpers to mint cookies using the suffixed cookie name/salt so sessions work on non-3000 ports.
• Secret providers: Playwright runs force secret provider read/write to env (avoid developer filesystem secrets clobbering test DB creds).

Isolated Local Test Env Notes ($alga-test-env-setup)

• For side-by-side worktrees/environments, use the alga-test-env-setup scripts to generate unique ports + secrets and avoid collisions:
  • Port detection: ~/.claude/skills/alga-test-env-setup/scripts/detect_ports.py --env-num <N> --json
  • Secrets generation: ~/.claude/skills/alga-test-env-setup/scripts/generate_secrets.py --secrets-dir <worktree>/secrets
  • Then wire server/.env using the detected ports (unified port model: internal + exposed ports match).