add-ideas/govoplan-addresses
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

intermittent commit

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-14 13:22:09 +02:00
parent 420120af2f
commit f19350e65d
32 changed files with 11772 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
docs/ADDRESS_MODULE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,193 @@
# GovOPlaN Addresses Module Architecture
## Decision
`govoplan-addresses` owns reusable contact and recipient-source data. Campaigns,
mail, scheduling, portal, postbox, forms, reporting, and other modules consume
address data through core-mediated capabilities and APIs, not by importing
address-module internals.
The implementation reference for contact data is vCard. CardDAV is the primary
address-book sync protocol. LDAP/Active Directory, Exchange/Microsoft 365,
Google Contacts, CSV/XLSX, LDIF, and batch vCard import/export are connector
targets layered on top of the same local model and sync contracts.
## Ownership
`govoplan-addresses` owns:
- scoped address books
- contacts, organizations, households, and postal/email/phone address data
- vCard import/export and vCard-compatible field mapping
- reusable recipient sources and classical address lists
- contact tags, categories, communication preferences, consent, and legal basis
- deduplication, merge, address quality checks, and suppression lists
- contact provenance, audit history, soft delete, and restore
- external-source bindings, sync state, conflicts, and read-only source markers
It does not own:
- campaign-local recipient snapshots and evidence
- mail transport, mailbox access, or delivery queues
- calendar events or iCalendar event storage
- global identity authentication or authorization decisions
- organization structure or internal function assignments
- operational distribution lists/`Verteiler` with mixed users, identities,
groups, functions, roles, raw recipients, and nested lists
## Scopes
Address books can live in these scopes:
- `user`: personal address books and remembered contacts
- `group`: team/shared address books
- `tenant`: tenant-wide directories and approved shared lists
- `system`: platform-wide public/shared directories where policy allows it
The scope determines visibility, default permissions, sync credentials, and
whether downstream modules may reuse or mutate entries.
## Data Model Principles
The canonical model should preserve enough vCard semantics to round-trip common
fields:
- name components and formatted names
- nicknames and display names
- email addresses, phone numbers, postal addresses, URLs, notes, categories
- organizations, titles, roles, departments, and relationships
- birthday/anniversary where allowed by policy
- photos/avatars where storage and privacy policy allow them
- calendar or scheduling addresses where present
- source IDs, revisions, ETags, sync tokens, and provenance
The model should support both normalized query fields and a preserved original
representation for import/export and conflict handling.
The local baseline implements scoped address books, contacts, normalized
email/phone/postal-address tables, tags, source kind/reference fields,
first-class source payload/revision fields, and provenance JSON. Imported
vCards preserve raw source payload and revision metadata for audit/debugging.
Sync sources, attempt state, tombstones, conflicts, and diagnostics are now
first-class backend tables and API resources. Connector-specific diffing,
CardDAV discovery, and conflict-resolution UI remain part of the connector
milestones.
## Capabilities
The first stable capabilities are:
- `addresses.recipient_source`: return immutable recipient snapshots for
campaigns, forms, reporting, and other send/build workflows.
- `addresses.lookup`: provide read-only lookup and autocomplete for mail,
campaign, scheduling, postbox, portal, and case workflows.
- `addresses.contact_writer`: provide address-book-scoped write target decisions
and contact creation for local or otherwise writable sources.
Capabilities use DTOs and source IDs. Consumers must not receive ORM objects or
write address tables directly. Consumers that need historical evidence must
store their own immutable snapshot with source ID, source revision, and
provenance; they must not treat live address records as historical evidence.
`addresses.recipient_source` exposes both complete address books and classical
address lists. Address-book sources use `addresses:address_book:<id>`.
Address-list sources use `addresses:address_list:<id>` and include the
address-list entry ID in each recipient's provenance. The current snapshot DTO
is email-recipient oriented; postal-only list entries are valid address-list
members but are skipped by the email recipient-source path until postal
recipient DTOs are added.
The writer capability is intentionally address-book specific. It answers
whether the current principal may perform an operation such as `create_contact`,
`update_contact`, or `delete_contact` against a concrete address book. The
decision payload includes:
- `allowed`
- stable `reason`
- user-facing `message`
- required scopes
- source kind
- read-only state
- scope and tenant provenance
Policy modules or connector sync state may later add inputs to this decision,
but consumers must continue to call the address capability/API instead of
importing policy logic or address services directly. Disabled or read-only UI
actions should surface the returned `message` on hover.
## Sync Model
Every synced address book tracks or can track:
- connector type and external account/source
- external address-book ID and display name
- local address-book scope
- sync direction: read-only, one-way import, one-way export, two-way
- sync token, ETag/revision, last successful sync, last attempted sync
- deleted markers/tombstones
- conflict status and resolution decision
- connector diagnostics and rate-limit/backoff state
Sync conflict UX must show the local value, remote value, source, timestamp, and
available action. Silent overwrite is not acceptable.
Sync infrastructure is intentionally connector-neutral. CardDAV, LDAP,
Exchange/Microsoft 365, Google Contacts, CSV/XLSX/LDIF import profiles, and
future connectors must write through `addresses_sync_sources` and related
records instead of inventing connector-specific status tables. Connector jobs
may mark a source `running`, `succeeded`, `failed`, or `conflict`; read-only and
one-way-import sources propagate a read-only decision to the owning address
book, which in turn blocks normal contact writes through the existing writer
capability/API.
The first CardDAV implementation supports discovery, source binding, dry-run
preview, inbound vCard sync, outbound create/update/delete for writable
sources, sync-token/full-sync fallback, tombstones, diagnostics, and persisted
conflicts. Outbound writes use ETag preconditions; stale local state must become
a conflict instead of silently overwriting remote data. The first conflict
review UI compares stored local and remote field payloads and can apply a
stored remote vCard payload or a manual per-field local/remote merge payload.
Source disconnect/delete removes the source binding and related sync records
while keeping local contacts.
## Connector Direction
Implement connectors in this order:
1. vCard import/export and batch import.
2. CardDAV address books.
3. LDAP/Active Directory read-only directories.
4. Exchange/Microsoft 365 and Google Contacts.
5. CSV/XLSX/LDIF import mapping profiles.
Connector runtime behavior should reuse shared connector concepts where useful:
configured endpoints, credentials, dry-run, diagnostics, rate limits, and audit
events.
## Cross-Module Integration
Campaigns should consume `addresses.recipient_source` through the platform
registry and freeze snapshots into campaign versions. Mail should consume
`addresses.lookup` for autocomplete and `addresses.contact_writer` for "add
contact" workflows. Scheduling should use lookup for attendees and organizers.
Portal, postbox, cases, forms, and reporting should link to contact records by
stable IDs while keeping their own domain evidence. Cross-module UI must hide
write actions when no writable target exists, or show the writer decision
message when a disabled action remains visible for context.
Operational distribution lists belong in `govoplan-dist-lists`. They may later
consume address lists as one entry type, but they own mixed recipient expansion
for users, identities, organization units, groups, functions, roles, raw
recipients, and nested lists. Workflow and Tasks own `Umlauf` execution state;
distribution lists define who is included, not how work circulates.
## Deferred Work
The following are valuable but not required for the first functional milestone:
- automatic deduplication and merge suggestions
- two-way sync conflict UI
- Microsoft/Google connectors
- household and relationship editing
- advanced consent-policy automation
- contact activity timeline across all modules

236
docs/IMPLEMENTATION_PLAN.md Normal file
View File

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