Sync Repo-docs-IMPLEMENTATION-PLAN from project files
188
Repo-docs-IMPLEMENTATION-PLAN.-.md
Normal file
188
Repo-docs-IMPLEMENTATION-PLAN.-.md
Normal file
@@ -0,0 +1,188 @@
|
|||||||
|
<!-- codex-wiki-sync:6d138bdd7653d6a9617f531e -->
|
||||||
|
|
||||||
|
> 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.
|
||||||
Reference in New Issue
Block a user