govoplan-addresses (0.1.21)
Installation
pip install --index-url https://git.add-ideas.de/api/packages/GovOPlaN/pypi/simple/ --extra-index-url https://pypi.org/simple govoplan-addressesAbout this package
GovOPlaN reusable address and recipient-source module.
GovOPlaN Addresses
Repository type: module (domain).
govoplan-addresses is the reusable address and recipient-source module. It
owns long-lived address directories and contact points and makes them available
to consumers through platform capabilities.
The campaign module may import campaign-local recipient tables, but reusable address management belongs here.
Current State
Milestone 1 is implemented. The module now owns persistent local address books
and contact CRUD under /api/v1/addresses, contributes /address-book to the
WebUI, and registers address permissions, role templates, database migrations,
tenant summaries, and uninstall guards.
The first UI supports user, group, tenant, and system-scoped address books, multi-value contact methods, soft deletion, restore, read-only lookup/search, and vCard import/export for common contact fields. Multi-file vCard imports now create a persisted preview before mutation, expose duplicate suggestions and per-card create/update/ignore choices, reject stale plans, and make identical commit retries idempotent. Pending batches can be reloaded or cancelled. Address-book, address-list, and selected-contact exports explicitly support vCard 3.0 or 4.0 with deterministic ordering and a recorded content hash. Imported vCards preserve source payload and revision metadata for later sync/conflict work, while batch diagnostics expose only bounded metadata.
The backend and WebUI also support classical address lists: reusable groupings
of contacts or specific contact methods within one address book. Campaigns can
import address books and address lists through the core-mediated
addresses.recipient_source capability without importing address-module
internals. Broader operational Verteiler with mixed users, identities,
groups, functions, raw recipients, and nested lists belong in
govoplan-dist-lists.
The backend now also contains connector-neutral sync infrastructure. Address books can be bound to external sources, sync attempts can record status, tokens, ETags, revisions, diagnostics, tombstones, and conflicts, and read-only or one-way-import sources make the owning address book read-only for normal write paths. CardDAV discovery, source binding, dry-run preview, inbound vCard sync, outbound create/update/delete for writable CardDAV sources, diagnostics, tombstones, conflict persistence, source disconnect/delete UX, and a first sync inspection UI are implemented. The conflict review UI compares stored local and remote field payloads, can apply a stored remote vCard payload, and supports manual per-field local/remote merge choices.
Address quality and duplicate handling are implemented as an operator workflow. Contact points retain both their original and normalized values, field-level provenance is append-only, and current quality states can mark a point valid, invalid, returned, stale, or undeliverable. Those states flow into recipient resolution with stable reason codes. The quality dialog shows bounded, explainable duplicate suggestions and a correction queue. Merges record explicit survivorship decisions, repair address-list memberships, preserve redirects for stored contact references, and can be undone or split while the post-merge evidence hash still matches.
API-managed CardDAV credentials are encrypted inside the source record. Source deletion physically removes that credential material and records a non-secret audit event in the same database transaction; destructive module retirement audits every remaining credential before the owning tables are dropped. Legacy external references are detached but are never sent to a secret provider for deletion because Addresses cannot prove that it owns them.
Boundary
govoplan-addresses owns:
- scoped address books, vCard-compatible contacts, and postal/email/phone contact points
- classical address-only lists and recipient-source views
- consent, legal-basis, and communication-preference metadata
- deduplication, merge, and address quality workflows
- import/export of reusable address directories
- source provenance and change history
It must not own:
- campaign-local recipient snapshots
- delivery queues or send attempts
- SMTP/IMAP transport
- file storage
- global identity authentication or RBAC evaluation
- typed IDM groups, identity relationships, organization structures, or effective function assignments
- operational distribution lists/
Verteilerwith mixed recipient types
Capabilities
The module exposes core-mediated capabilities for:
addresses.lookup: read-only contact/recipient lookup for autocomplete.addresses.recipient_source: immutable recipient snapshots for campaign, reporting, mail-build, forms, portal, and postbox workflows.addresses.contact_writer: address-book-scoped write decisions and contact creation for local or otherwise writable sources.addresses.contact_point_resolution: purpose-aware, channel-neutral resolution and immutable snapshots for email, postal, internal-mail, and portal targets.addresses.people_search: privacy-aware contact candidates for shared people pickers.distribution.recipient_channel_facts: current channel, governance, and quality facts for distribution and Policy consumers.privacy.dsar.addresses: tenant-bounded, minimized data-subject discovery across contacts, contact points, list use, governance, provenance, synchronization evidence, and operator attribution.
The DSAR provider accepts corroborated email/account selectors and namespaced Addresses references. It does not export connector state, raw import or sync payloads, opaque metadata, snapshot payloads, or merge before/after payloads. Reusable contacts are never deleted automatically: shared/synchronized contact changes require an authorized dependency review through the ordinary Addresses workflows, while governance, quality, merge, sync, import, and attribution evidence is retained with an explicit reason.
addresses.recipient_source returns:
- source id and display label
- normalized recipient rows
- email recipient fields
- source update marker
- provenance fields suitable for audit and campaign reports
Recipient sources currently include complete address books and classical
address lists. Address-list source IDs use addresses:address_list:<id> and
preserve the address-list entry ID in recipient provenance. Address-list entries
may point at a whole contact, a concrete email address, or a concrete postal
address. Email-oriented consumers snapshot email targets and whole-contact
entries with a usable email address; postal-only entries remain valid list
members for later postal/document workflows.
Legacy addresses.recipient_source consumers must store their own immutable
snapshot when they need historical evidence. Channel-neutral consumers may use
the dedicated freeze operation described below. The addresses module remains
the owner of reusable sources; domain consumers remain responsible for linking
their own records to snapshot evidence. Consumers must resolve these
capabilities through the platform registry and must not import address
ORM/service internals.
addresses.contact_writer returns an explicit decision before a consumer shows
or executes write actions: allowed/blocked, reason, user-facing message,
required scopes, source kind, read-only state, and provenance. The decision is
address-book specific; broader policy modules may later contribute to the same
decision path, but consumers should not import or duplicate policy logic.
For channel-neutral consumers, addresses.contact_point_resolution supersedes
the email-only shape without removing it. It accepts local contact IDs and
stable provider references such as idm:identity:<id>, applies an effective
date, communication purpose, address purpose, fallback rule, locale, and
domestic/international postal formatting, and returns candidates plus excluded
targets with stable reason codes. Bounded previews are live. A frozen snapshot
stores the complete values, source and governance revisions, provenance, and a
deterministic hash in Addresses so later contact edits cannot rewrite evidence.
The corresponding HTTP API is available below /api/v1/addresses:
POST /contact-points/resolvePOST /contact-point-sources/previewPOST /contact-point-snapshotsGET /contact-point-snapshots/{snapshot_id}
Quality, provenance, and reversible merge operations are available through:
GET /address-books/{book_id}/quality-summaryGET /address-books/{book_id}/duplicate-suggestionsGET|POST /contacts/{contact_id}/quality-decisionsGET /contacts/{contact_id}/provenanceGET /contacts/{contact_id}/redirectGET|POST /contact-mergesPOST /contact-merges/{merge_id}/undoPOST /contact-merges/{merge_id}/split