intermittent commit

docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,236 @@
+# GovOPlaN Addresses Implementation Plan
+
+## Milestone 1: Functional Local Address Books
+
+Goal: make `govoplan-addresses` useful without external sync.
+
+Primary issue: `govoplan-addresses#3`.
+
+Status: implemented. The persistent backend, router, migration, permissions,
+role templates, lookup endpoint, restore support, multi-value contact editor,
+and first WebUI are in place.
+
+Tasks:
+
+- [x] add backend tables and migrations for address books, contacts, contact
+  methods, postal addresses, tags, and provenance
+- [x] add permissions and role templates for viewing and managing address books
+- [x] implement address-book CRUD API
+- [x] implement contact CRUD API
+- [x] implement scoped WebUI views for user, group, tenant, and system books
+- [x] support soft delete
+- [x] add restore API/UI for soft-deleted address books and contacts
+- [x] expose read-only contact lookup for the WebUI
+
+Exit criteria:
+
+- [x] an admin can create tenant/system books
+- [x] a user can create a personal book and contacts
+- [x] address data survives restart and appears in the address-book UI
+- [x] disabled or read-only actions explain why they are unavailable
+
+## Milestone 2: vCard Foundation
+
+Goal: make the model standards-based before adding sync.
+
+Primary issue: `govoplan-addresses#4`.
+
+Status: implemented. The module can import and export common vCard fields for
+local books, preserves imported raw vCard payload and revision metadata in
+first-class source fields, reports field/card import issues, and has round-trip
+and partial-import tests. Full two-way connector conflict resolution remains in
+the sync milestones.
+
+Tasks:
+
+- [x] define vCard-compatible DTOs
+- [x] preserve original imported vCard data and normalized query fields
+- [x] import `.vcf` files into a selected address book
+- [x] export contacts/address books as vCard
+- [x] add validation for common vCard fields
+- [x] add tests for round-trip import/export of names, emails, phones, postal
+  addresses, organization fields, notes, categories, and URLs
+- [x] add field/card validation messages for batch import
+- [x] promote original payload and revision handling into first-class contact
+  source fields
+
+Exit criteria:
+
+- [x] common vCard files can be imported and exported without losing core fields
+- [x] normalized search fields are populated during import
+- [x] invalid entries produce field-level actionable validation messages
+
+## Milestone 3: Core Capabilities
+
+Goal: allow other modules to use addresses without dependencies.
+
+Primary issue: `govoplan-addresses#5`.
+
+Tasks:
+
+- [x] implement `addresses.lookup`
+- [x] implement `addresses.recipient_source`
+- [x] define immutable recipient snapshot DTOs
+- [x] expose source provenance in capability responses
+- [x] expose classical address lists as `addresses.recipient_source` sources
+- [x] add module presence/capability tests
+- [x] document consumer rules for campaign, mail, scheduling, portal, postbox, and
+  reporting
+
+Exit criteria:
+
+- [x] campaign can request a recipient source via core-mediated capability
+- [x] mail/scheduling can request autocomplete candidates via core-mediated lookup
+- [x] consumers do not import `govoplan_addresses`
+
+## Milestone 4: Campaign Integration
+
+Goal: replace campaign-local reusable address concepts with address-module
+sources.
+
+Primary issue: `govoplan-campaign#55`.
+
+Tasks:
+
+- [x] add campaign recipient-source picker when `addresses.recipient_source` exists
+- [x] snapshot selected address-source rows into the campaign version
+- [x] store source ID, revision, and provenance in campaign evidence
+- [x] show stale-source warnings when an address source changed after selection
+- [x] keep campaign import for one-off local recipient data
+- [x] define classical address lists as reusable address-domain sources
+- [x] add address-list selection and management UI in addresses/campaign
+- [ ] define segments/dynamic filters before exposing them as campaign sources
+      Deferred deliberately: classical address lists are stable now; dynamic
+      segments need their own filter model, stale-source semantics, and audit
+      evidence before campaign can snapshot them safely.
+
+Exit criteria:
+
+- [x] campaign works without addresses installed
+- [x] campaign offers address-source selection when addresses is installed
+- [x] built campaigns remain auditable after source contacts change
+
+## Milestone 5: Mail And Scheduling Integration
+
+Goal: make contacts visible where users naturally need them.
+
+Primary issues: `govoplan-mail#13` and `govoplan-scheduling#2`.
+
+Tasks:
+
+- [x] add mail recipient/autocomplete integration through `addresses.lookup`
+      at API/capability level; visible compose UI reuse follows when mail
+      compose exists
+- [x] expose `addresses.contact_writer` for explicit address-book write
+      decisions, required scopes, read-only/source reasons, and provenance
+- [ ] add "add sender/contact" actions in consuming UIs by using
+      `addresses.contact_writer`
+- [x] add scheduling attendee/organizer lookup integration
+- [x] preserve module independence when addresses is absent
+
+Exit criteria:
+
+- [x] mail and scheduling build without addresses installed
+- [x] when addresses is installed, lookup improves recipient/attendee entry
+- [x] address write decisions expose why actions are unavailable for read-only
+      sources, deleted books, missing scopes, or unsupported operations
+- [ ] consuming UI write actions are hidden or explained with the
+      `addresses.contact_writer` decision payload
+
+## Milestone 6: Sync Infrastructure
+
+Goal: prepare external address books without committing to all connectors at
+once.
+
+Primary issue: `govoplan-addresses#6`.
+
+Status: implemented for the first connector path. The connector-neutral backend
+substrate is in place: sync sources, source status, read-only propagation,
+tombstones, conflicts, diagnostics, attempt transitions, dry-run preview,
+audit-event emission, and a first sync inspection UI.
+
+Tasks:
+
+- [x] add address-source connector configuration
+- [x] add sync state, ETags, revisions, tokens, tombstones, and conflict records
+- [x] add sync diagnostics
+- [x] add audit events for sync attempts, conflicts, previews, completions, and
+      resolutions
+- [x] support read-only and writable source flags
+- [x] add dry-run and preview for connector changes
+- [x] add admin/user UI for source status, diagnostics, tombstones, and conflicts
+
+Exit criteria:
+
+- [x] a connector can report planned creates/updates/deletes before applying them
+- [x] sync failures are visible in the UI
+- [x] conflicts are persisted and do not silently overwrite data
+
+## Milestone 7: CardDAV
+
+Goal: implement the first real standards-based sync connector.
+
+Primary issue: `govoplan-addresses#7`.
+
+Status: implemented for the first standards-based sync path. Discovery, source
+binding, full/sync-token inbound sync, outbound create/update/delete for
+writable sources, dry-run preview, diagnostics, tombstones, and persisted
+conflict records are implemented. Source disconnect/delete UX and conflict
+review are implemented; stored remote vCard payloads can be applied from the
+review UI, and manual per-field local/remote merge choices are supported.
+
+Tasks:
+
+- [x] add CardDAV account/address-book discovery
+- [x] sync vCard resources into scoped address books
+- [x] support read-only and writable source flags
+- [x] push local creates, updates, and deletes to writable CardDAV sources with
+      ETag preconditions
+- [x] handle ETag changes, deletes, and conflicts
+- [x] add connection discovery and diagnostics
+- [x] add source disconnect/delete UX that keeps local contacts
+- [x] add conflict review UI with local/remote field comparison
+- [x] apply stored remote vCard payloads from conflict resolution
+- [x] support manual per-field local/remote merge choices for stored vCard payloads
+
+Exit criteria:
+
+- [x] a CardDAV source can be connected, synced, and inspected
+- [x] CardDAV source disconnect/delete UI
+- [x] contacts can be refreshed without duplicating entries
+- [x] conflict and permission states are visible to the user
+- [x] outbound CardDAV writes for writable remote books
+- [x] field-level conflict review UI
+- [x] manual per-field merge editing
+
+## Milestone 8: Additional Connectors And Advanced Address Features
+
+Goal: expand beyond CardDAV after the model and sync engine are stable.
+
+Primary issues: `govoplan-addresses#8`, `govoplan-addresses#9`,
+`govoplan-addresses#10`, and `govoplan-connectors#8`.
+
+Tasks:
+
+- LDAP/Active Directory read-only directory connector
+- Exchange/Microsoft 365 contacts connector
+- Google Contacts connector
+- CSV/XLSX/LDIF import mapping profiles
+- classical address-list UI and static/dynamic address-domain segments
+- operational distribution lists move to `govoplan-dist-lists`
+- consent, legal-basis, suppression, and communication preferences
+- deduplication and merge workflow
+- address quality checks and normalization
+- relationship/household/organization editing
+
+Exit criteria:
+
+- each connector or advanced feature can be enabled independently
+- users can understand where data came from and whether they may edit it
+- downstream modules can safely use contacts without owning them
+
+## First Implementation Recommendation
+
+Start with Milestone 1 and enough of Milestone 2 to define the data model
+correctly. Do not start CardDAV before the local vCard-compatible storage and
+API are stable.