108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
# GovOPlaN Addresses
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** module (domain).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
`govoplan-addresses` is the reusable address and recipient-source module. It
|
|
owns long-lived address directories and makes them available to campaigns,
|
|
mail, forms, reporting, portal, and postbox modules 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. Imported vCards preserve
|
|
source payload and revision metadata for later sync/conflict work.
|
|
|
|
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.
|
|
|
|
## Boundary
|
|
|
|
`govoplan-addresses` owns:
|
|
|
|
- Adrema-style person, organization, household, and postal-address records
|
|
- reusable email address lists and postal-letter recipient views
|
|
- segments and reusable recipient-source definitions
|
|
- 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
|
|
- operational distribution lists/`Verteiler` with mixed recipient types
|
|
|
|
## First Capabilities
|
|
|
|
The module exposes three core-mediated capabilities:
|
|
|
|
- `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.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.
|
|
|
|
Consumers must store their own immutable snapshot when they need historical
|
|
evidence. The addresses module remains the owner of the reusable source, not of
|
|
the consumer's historical records. 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.
|
|
|
|
## Design Documents
|
|
|
|
- [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md)
|
|
- [Implementation plan](docs/IMPLEMENTATION_PLAN.md)
|