chore: sync GovOPlaN module split state

docs/RECIPIENT_IMPORT_GUIDE.md

@@ -0,0 +1,87 @@
+# Recipient Import Guide
+
+Recipient import lets campaign authors turn spreadsheet-like source data into
+campaign-local recipient entries. It is intentionally campaign-local today:
+reusable address books and Adrema-style address management belong in the future
+`govoplan-addresses` module.
+
+## Supported Inputs
+
+The current importer is designed for tabular data with a header row. CSV and
+spreadsheet-derived tables should be normalized before import so the campaign UI
+sees:
+
+- column headers
+- row values
+- source filename and sheet name when available
+- a stable ordered and unordered header fingerprint
+
+Avoid importing production secrets or credentials as recipient fields. Recipient
+custom fields may be used in templates and reports, so they should be treated as
+campaign data.
+
+## Mapping Fields
+
+Common headers are detected automatically:
+
+- `email`, `e_mail`, `mail`, `to`, `to_email`, `recipient`,
+  `recipient_email`
+- `name`, `full_name`, `recipient_name`, `to_name`
+- `id`, `entry_id`, `recipient_id`
+
+Authors can map columns to address fields:
+
+- `from`
+- `to`
+- `cc`
+- `bcc`
+- `reply_to`
+
+Rows without a valid `to` address should remain visible with validation issues
+instead of disappearing silently. Authors should be able to fix the source file,
+adjust the mapping, or exclude the row before building the campaign.
+
+## Mapping Profiles
+
+Mapping profiles save a known column layout so repeated imports can reuse the
+same mapping. The importer stores ordered and unordered header fingerprints so a
+profile can distinguish exact column order from equivalent column sets.
+
+Administrators should curate shared profiles only for stable recurring sources.
+Campaign-local profiles are acceptable for one-off work and experiments.
+
+## User Workflow
+
+1. Open the campaign recipient/data import screen.
+2. Upload or paste a tabular source.
+3. Review detected headers and preview rows.
+4. Pick or adjust a mapping profile.
+5. Confirm validation issues, exclusions, and generated recipient ids.
+6. Import into the campaign draft.
+7. Build messages and review recipient-specific evidence before sending.
+
+## Admin Workflow
+
+Administrators should:
+
+- define naming conventions for recurring mapping profiles
+- verify that imported fields have a lawful processing basis for the campaign
+- keep reusable address-directory ownership out of campaigns until
+  `govoplan-addresses` owns that domain
+- use campaign reports and audit evidence to trace which source produced which
+  recipient entries
+- remove obsolete shared profiles when an upstream source layout changes
+
+## Evidence Expectations
+
+The campaign should preserve enough evidence to explain a send:
+
+- source filename and sheet name where available
+- header fingerprints
+- mapping profile id/name when used
+- row number or source id
+- validation status and exclusion reason
+- final recipient addresses used for the built message
+
+The evidence should be available in reports without requiring the original
+source file to be reprocessed.