inital commit

JAVA_PORT_NOTES.md

@@ -0,0 +1,57 @@
+# Java MultiMailer port notes
+
+This skeleton now contains a first Python port of the important Java domain logic:
+
+- `Field`, `FieldDescription`, `FieldConfiguration`, `FieldContents`
+- `MailTemplate` with `${global::field}` / `${local::field}` replacement
+- `Recipient`, `RecipientList`
+- `MailServerSettings`
+- `MailAttachmentConfig`
+- `MailCampaign`, `MailEntry`, `MailQueue`
+- attachment glob matching
+- encrypted ZIP creation with `pyzipper`
+- MIME assembly using Python's `email.message.EmailMessage`
+- basic SMTP queue sending using `smtplib`
+
+The Java Swing UI was not ported, because the planned UI is React.
+The SimpleJavaMail dependency was replaced by stdlib `email` / `smtplib` equivalents.
+
+Example port of the provided `MultiMailerSettings.java.example`:
+
+```bash
+cd server
+python -m app.mailer.examples.rechnungslegung_2026_05
+```
+
+Current limitations:
+
+- IMAP append-to-Sent is not implemented yet.
+- Server-side persisted campaign/job models are not implemented yet.
+- Attachment storage still uses local filesystem paths in the Java-compatible domain layer; Garage object storage integration is the next layer.
+- ZIP password encryption uses AES via `pyzipper`, not the Java zip4j implementation.
+- The Java `getNotSentFiles` behavior is approximated and should be revisited once we define the new campaign/job data model.
+
+## Added after persistence foundation
+
+- Queue transition for built jobs.
+- Campaign-level queue/pause/resume/cancel API endpoints.
+- Direct CLI queued-job processor for development without Celery.
+- Celery `multimailer.send_email` task now sends DB-backed jobs.
+- Per-campaign Redis-backed rate limiting.
+- Send attempts persisted in `send_attempts`.
+- IMAP status kept independent from SMTP status; actual IMAP APPEND remains next.
+
+## IMAP append implementation
+
+The Python port now implements the Java-era "save to sent folder" concept as a separate post-send worker action:
+
+- SMTP success updates `send_status=sent`.
+- If configured, the job receives `imap_status=pending`.
+- A separate `append_sent` task or CLI command appends the exact generated EML to the IMAP Sent folder.
+- IMAP failures do not undo SMTP success.
+
+This preserves the important distinction between delivery and mailbox archival.
+
+## Reporting/dashboard milestone
+
+Added campaign reporting helpers and API endpoints. This is the backend bridge toward the first web UI: the report contains card-friendly counts, grouped statuses, attachment and issue summaries, delivery/rate-limit estimates, recent failures, and optional per-job rows. No new DB schema is required; the report is derived from persisted campaigns/jobs/attempts.