# 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.