From ae231494a406027ac9ce4522c71cd010538cf76e Mon Sep 17 00:00:00 2001 From: zemion Date: Mon, 13 Jul 2026 00:55:29 +0200 Subject: [PATCH] Sync Repo-docs-IMPLEMENTATION-PLAN from project files --- Repo-docs-IMPLEMENTATION-PLAN.-.md | 188 +++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 Repo-docs-IMPLEMENTATION-PLAN.-.md diff --git a/Repo-docs-IMPLEMENTATION-PLAN.-.md b/Repo-docs-IMPLEMENTATION-PLAN.-.md new file mode 100644 index 0000000..4995b39 --- /dev/null +++ b/Repo-docs-IMPLEMENTATION-PLAN.-.md @@ -0,0 +1,188 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-addresses/docs/IMPLEMENTATION_PLAN.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Addresses Implementation Plan + +## Milestone 1: Functional Local Address Books + +Goal: make `govoplan-addresses` useful without external sync. + +Primary issue: `govoplan-addresses#3`. + +Tasks: + +- add backend tables and migrations for address books, contacts, contact + methods, postal addresses, tags, and provenance +- add permissions and role templates for viewing and managing address books +- implement address-book CRUD API +- implement contact CRUD API +- implement scoped WebUI views for user, group, tenant, and system books +- support soft delete and restore +- expose read-only contact lookup for the WebUI + +Exit criteria: + +- an admin can create tenant/system books +- a user can create a personal book and contacts +- address data survives restart and appears in the address-book UI +- 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`. + +Tasks: + +- define vCard-compatible DTOs +- preserve original imported vCard data and normalized query fields +- import `.vcf` files into a selected address book +- export contacts/address books as vCard +- add validation for common vCard fields +- add tests for round-trip import/export of names, emails, phones, postal + addresses, organization fields, notes, categories, and URLs + +Exit criteria: + +- common vCard files can be imported and exported without losing core fields +- normalized search fields are populated during import +- invalid entries produce actionable validation messages + +## Milestone 3: Core Capabilities + +Goal: allow other modules to use addresses without dependencies. + +Primary issue: `govoplan-addresses#5`. + +Tasks: + +- implement `addresses.lookup` +- implement `addresses.recipientSource` +- define immutable recipient snapshot DTOs +- expose source provenance in capability responses +- add module presence/capability tests +- document consumer rules for campaign, mail, scheduling, portal, postbox, and + reporting + +Exit criteria: + +- campaign can request a recipient source via core-mediated capability +- mail/scheduling can request autocomplete candidates via core-mediated lookup +- 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: + +- add campaign recipient-source picker when `addresses.recipientSource` exists +- snapshot selected address-source rows into the campaign version +- store source ID, revision, and provenance in campaign evidence +- show stale-source warnings when an address source changed after selection +- keep campaign import for one-off local recipient data + +Exit criteria: + +- campaign works without addresses installed +- campaign offers address-source selection when addresses is installed +- 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: + +- add mail recipient/autocomplete integration through `addresses.lookup` +- add "add sender/contact" actions where policy allows writing +- add scheduling attendee/organizer lookup integration +- preserve module independence when addresses is absent + +Exit criteria: + +- mail and scheduling build without addresses installed +- when addresses is installed, lookup improves recipient/attendee entry +- write actions are hidden or explained for read-only address sources + +## Milestone 6: Sync Infrastructure + +Goal: prepare external address books without committing to all connectors at +once. + +Primary issue: `govoplan-addresses#6`. + +Tasks: + +- add address-source connector configuration +- add sync state, ETags, revisions, tokens, tombstones, and conflict records +- add sync diagnostics and audit events +- support read-only and writable source flags +- add dry-run and preview for connector changes + +Exit criteria: + +- a connector can report planned creates/updates/deletes before applying them +- sync failures are visible in the UI +- 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`. + +Tasks: + +- add CardDAV account/address-book discovery +- sync vCard resources into scoped address books +- support read-only and writable CardDAV books where the server allows it +- handle ETag changes, deletes, and conflicts +- add connection test and diagnostics + +Exit criteria: + +- a CardDAV source can be connected, synced, inspected, and disconnected +- contacts can be refreshed without duplicating entries +- conflict and permission states are visible to the user + +## 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 +- distribution lists and static/dynamic segments +- 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.