# Phase 7: DKV Fleet Module - Context

**Gathered:** 2026-06-26
**Status:** Ready for planning

<domain>
## Phase Boundary

Build a Tessera module that monitors an email inbox for DKV fuel card invoices, parses the PDF attachments, maps license plates to drivers via a configurable vehicle master list, exports a 5-column Excel file, and delivers it via SMTP. Includes processing history and file storage for the last 10 exports.

</domain>

<decisions>
## Implementation Decisions

### Email Inbox Monitoring
- **D-01:** Support both IMAP and Exchange (EWS) as inbox protocols — selectable per module config
- **D-02:** Polling via configurable cron job (interval in minutes, set in module config) + manual "Jetzt prüfen" button in the UI
- **D-03:** Inbox config fields: Protocol (IMAP/Exchange), Host, Port, Username (optional), Password (optional), Encryption (None/STARTTLS/SSL-TLS), Folder, Sender filter (email address to watch for DKV invoices)
- **D-04:** Credentials stored encrypted (AES-256-GCM via existing `crypto.service.ts`)

### SMTP / Email Send
- **D-05:** SMTP settings live in **general settings** (shared, not per-module): Host, Port, Username (optional), Password (optional), Encryption (None/STARTTLS/SSL-TLS), Sender address
- **D-06:** Existing `mail` module (`apps/api/src/mail/`) must be extended to read SMTP config from DB instead of hardcoded env vars
- **D-07:** Export recipient address configured per module (not in general settings)

### PDF Parsing
- **D-08:** Parse DKV E-Rechnung PDF using `pdf-parse` (text extraction + regex) — DKV PDF structure is consistent across invoices
- **D-09:** Parsed data per vehicle block: Kennzeichen (from `VEHICLE: ...` header), per-transaction rows with Lieferdatum, Servicestation Ort, Kilometerstand, Produkt, Menge, Einheit
- **D-10:** On parse failure: 3 retries, then mark as failed in processing history with error message

### Export Format
- **D-11:** Output format: `.xlsx` (Excel), generated with `xlsx` (SheetJS)
- **D-12:** Filename: `DKV_YYYY-MM_<Rechnungsnummer>.xlsx` — example: `DKV_2026-04_26-651566449-001.xlsx`
- **D-13:** Exactly 5 columns in this order:
  1. **Lieferdatum** — format `TT.MM.JJJJ` (e.g., `13.12.2020`)
  2. **Fahrzeug** — format `{Marke}/{Modell}/{Kennzeichen}` (e.g., `Mercedes/GLC 300 de 4MATIC/GP-JL 728E`) — format string configurable in module
  3. **Fahrer** — format `Vorname Nachname` (resolved from vehicle master data via Kennzeichen)
  4. **Ort** — Servicestation Ort from PDF
  5. **Kilometerstand** — numeric, no unit
- **D-14:** One Excel file per processed invoice (not cumulative)
- **D-15:** Last 10 export files stored in `user-files/` directory, downloadable from module UI

### SMTP Send (on export ready)
- **D-16:** On SMTP failure: 3 retries with exponential backoff, then mark as "Versand fehlgeschlagen" in history; export file remains locally available for manual download

### Vehicle Master Data
- **D-17:** Vehicle master data stored in DB per tenant; fields: Kennzeichen, Marke, Modell, Fahrer (Vorname Nachname)
- **D-18:** Importable as CSV (bulk replace or merge); also manually editable in module UI (CRUD table)
- **D-19:** Fahrzeug column format string is configurable (default: `{Marke}/{Modell}/{Kennzeichen}`)

### Processing History
- **D-20:** Processing history table in module UI: Datum/Zeit, Rechnungsnummer, Anzahl Fahrzeuge, Anzahl Transaktionen, Status (Verarbeitet / Fehler / Versand fehlgeschlagen), Export-Dateiname
- **D-21:** History stored in DB; entries kept indefinitely (no auto-purge in v1)

### Claude's Discretion
- DB schema design (vehicle_master, dkv_invoice_history, dkv_module_config tables)
- Cron job implementation (NestJS `@nestjs/schedule` ScheduleModule)
- EWS reuse from existing `ews-javascript-api` (already installed for calendar)
- IMAP library choice (`imapflow` recommended — modern, Promise-based)
- PDF parsing robustness (handle multi-page, multi-vehicle DKV format)
- Frontend component patterns (reuse existing admin table / settings patterns)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Existing modules to extend/reuse
- `apps/api/src/mail/mail.service.ts` — existing mail service (uses @nestjs-modules/mailer, env-based — must be extended for DB SMTP config)
- `apps/api/src/calendar/crypto.service.ts` — AES-256-GCM credential encryption, use for inbox + SMTP passwords
- `apps/api/src/calendar/calendar.service.ts` — reference pattern for provider abstraction (IMAP vs Exchange mirrors CalDAV vs EWS)
- `apps/api/src/calendar/providers/` — EWS provider pattern to follow for Exchange inbox monitoring

### Reference data (user-provided)
- `user-files/invoice.pdf` — real DKV E-Rechnung (April 2026, 4 pages, 27 vehicles) — use as parse target for regex development
- `user-files/fahrzeuge_bereinigt.xlsx` — cleaned vehicle master data — use to understand CSV import schema
- `user-files/Bildschirmfoto 2026-06-24 um 13.27.56.png` — reference UI for the module view

### Installed dependencies (no new install needed)
- `ews-javascript-api@0.15.3` — Exchange inbox access (already in `apps/api/package.json`)
- `nodemailer@^9.0.1` — SMTP send (already in `apps/api/package.json`)

### New dependencies needed
- `imapflow` — IMAP client (modern, Promise-based)
- `pdf-parse` — PDF text extraction
- `xlsx` (SheetJS) — Excel file generation

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `apps/api/src/calendar/crypto.service.ts` — inject directly for encrypting inbox + SMTP credentials
- `apps/api/src/mail/mail.service.ts` — extend (not replace) for DB-driven SMTP config
- `apps/api/src/calendar/providers/` — provider abstraction pattern for IMAP vs Exchange

### Established Patterns
- NestJS module structure: `*.module.ts`, `*.service.ts`, `*.controller.ts`, `dto/` — follow same layout
- Prisma migrations for new tables
- `@nestjs/schedule` for cron (already in NestJS ecosystem)
- Tenant isolation via existing RLS / tenant context

### Integration Points
- `apps/api/src/mail/mail.module.ts` — add DB-SMTP config support here
- `apps/api/src/prisma/` — add new tables: `dkv_module_config`, `dkv_vehicle_master`, `dkv_invoice_history`
- `apps/web/src/app/(portal)/` — new module page follows existing portal route pattern
- `user-files/` directory — already exists, used for file storage

</code_context>

<specifics>
## Specific Ideas

- DKV PDF structure: each vehicle section starts with `VEHICLE: {Kennzeichen} CARD NO.: {CardNumber}`, followed by transaction rows; ends with `TOTAL:` row per vehicle. Regex anchors on these markers.
- The Fahrzeug column format `{Marke}/{Modell}/{Kennzeichen}` should use a configurable template string so admins can change it (e.g., `{Kennzeichen} - {Fahrer}` alternative).
- Screenshot reference shows card-style rows with vehicle thumbnail, driver avatar, km reading, amount — the actual Excel export is a flat table, the UI shows the same data in card style.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 7-DKV Fleet Module*
*Context gathered: 2026-06-26*