From 90a507d9a401b0ac751e4adf6a78ca36daa41b95 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Fri, 31 Jul 2026 14:52:49 +0200 Subject: [PATCH] docs: narrow AdreMa ownership to address provider --- README.md | 15 +- docs/ADDRESS_MODULE_ARCHITECTURE.md | 32 +- docs/ADREMA_CAPABILITY_ASSESSMENT.md | 418 --------------------------- docs/IMPLEMENTATION_PLAN.md | 5 +- 4 files changed, 33 insertions(+), 437 deletions(-) delete mode 100644 docs/ADREMA_CAPABILITY_ASSESSMENT.md diff --git a/README.md b/README.md index 7ee61d8..ea3a99e 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,8 @@ `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. +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. @@ -54,9 +53,9 @@ deletion because Addresses cannot prove that it owns them. `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 +- 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 @@ -69,6 +68,8 @@ It must not own: - 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/`Verteiler` with mixed recipient types ## First Capabilities @@ -112,4 +113,4 @@ decision path, but consumers should not import or duplicate policy logic. - [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md) - [Implementation plan](docs/IMPLEMENTATION_PLAN.md) -- [AdreMa capability assessment](docs/ADREMA_CAPABILITY_ASSESSMENT.md) +- [AdreMa capability assessment and Distribution Lists roadmap](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists/src/branch/main/docs/ADREMA_CAPABILITY_ASSESSMENT.md) diff --git a/docs/ADDRESS_MODULE_ARCHITECTURE.md b/docs/ADDRESS_MODULE_ARCHITECTURE.md index fd7ec06..4ae104c 100644 --- a/docs/ADDRESS_MODULE_ARCHITECTURE.md +++ b/docs/ADDRESS_MODULE_ARCHITECTURE.md @@ -17,7 +17,7 @@ targets layered on top of the same local model and sync contracts. `govoplan-addresses` owns: - scoped address books -- contacts, organizations, households, and postal/email/phone address data +- vCard-compatible contacts and postal/email/phone contact-point 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 @@ -31,9 +31,12 @@ It does not own: - 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 +- IDM identities, typed groups, effective-dated relationships, or identity + lifecycle state +- organization structures, units, function definitions, or function + assignments +- operational distribution lists/`Verteiler` with mixed address contacts, IDM + identities/groups, functions, raw targets, Dataflow rows, and nested lists ## Scopes @@ -55,7 +58,8 @@ 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 +- organization, title, role, department, `KIND`, and `RELATED` values needed for + vCard round-trip compatibility - birthday/anniversary where allowed by policy - photos/avatars where storage and privacy policy allow them - calendar or scheduling addresses where present @@ -180,12 +184,20 @@ 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; +Operational distribution lists and reusable dynamic segments belong in +`govoplan-dist-lists`. They may consume address lists as one entry type, but +they own mixed recipient expansion for address contacts, IDM identities and +typed groups, organization units, functions/effective incumbents, raw targets, +Dataflow-backed rows, and nested lists. Workflow owns `Umlauf` execution state; distribution lists define who is included, not how work circulates. +Organizations owns unit and function definitions. IDM owns effective-dated +identity-to-function assignments and typed group relationships. Identity +lifecycle status is not a business audience status; a selectable business +status is represented by a group, function, or effective-dated relationship. +Addresses may link contact points to stable provider references without copying +those provider-owned facts. + ## Deferred Work The following are valuable but not required for the first functional milestone: @@ -193,6 +205,6 @@ 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 +- richer vCard `KIND`/`RELATED` round-trip and provider-reference linking - advanced consent-policy automation - contact activity timeline across all modules diff --git a/docs/ADREMA_CAPABILITY_ASSESSMENT.md b/docs/ADREMA_CAPABILITY_ASSESSMENT.md deleted file mode 100644 index 967dbbb..0000000 --- a/docs/ADREMA_CAPABILITY_ASSESSMENT.md +++ /dev/null @@ -1,418 +0,0 @@ -# AdreMa Capability Assessment - -## Purpose - -This document records a behavior-level assessment of the historical AdreMa -application supplied in `/mnt/DATA/tmp.tar`. The goal is not to reproduce its -implementation or UI. The goal is to preserve the useful administrative -capabilities while replacing hard-coded queries and output paths with -governed, reusable GovOPlaN contracts. - -The archive was inspected as untrusted historical material. No archived code -was executed. Generated documents and record-level output were excluded from -the analysis. - -## Evidence And Handling - -- Archive SHA-256: - `328edbaf05df084f9c63cc3b9b36f7c5ae0c639942be4b7ad830efc0905a311b` -- Compressed size: about 1.49 GB -- Inventory: 8,966 files and 190 directories -- Uncompressed payload: about 1.79 GB -- The AdreMa selection UI contains 258 distinct segment variables, 265 query - cases, 13 sort definitions, seven action definitions, and 24 - department-specific forms. -- The adjacent configurable list/report layer contains 47 ETI definitions. -- The wider print-server archive contains 127 SQL files, 181 XSLT files, and 82 - Python workflow sources. - -The archive contains generated person-level documents and embedded -credentials. It must not be committed, copied into test fixtures, or treated as -safe sample data. Any credential that could still be valid must be rotated. -Future fixtures derived from this assessment must be synthetic. - -## What AdreMa Actually Is - -AdreMa is not primarily a master address database. It is a role-specific -audience selection and output application over authoritative institutional -databases. - -Its main flow is: - -1. Authenticate against a directory. -2. Show a menu of saved recipient selections permitted for the current user or - department. -3. Run a fixed SQL selection against organization, person, employment, - function, student, geography, and address data. -4. Apply a selected sort order and address variant. -5. Produce a table, spreadsheet, label preview, label file, central print job, - or BCC mail draft. -6. Record a basic process log and recipient count. - -The broader print-server application adds SQL-to-XML extraction, XSLT -transformation, HTML/Excel output, TeX/PDF generation, batch letters, PDF -protection, printer selection, and direct print-queue submission. - -This means an AdreMa replacement should not be one large Addresses feature. -It is a vertical composition of Addresses, Organizations/IDM, Datasources, -Connectors, Dataflow, Distribution Lists, Templates, Campaign, Files, Audit, -Policy, Reporting, Workflow, and a future print-delivery capability. - -## Observed Functional Model - -### Sources And Identities - -The application reads live authoritative data rather than maintaining a -separate copy. Its selections use: - -- people and institutional units -- functions and role assignments -- employment and student state -- effective dates and exclusions -- internal and external organizations -- geography, country, and postal-code ranges -- source-specific person, registration, and unit identifiers - -Access to selections is hard-coded by user and department. Administrative -users receive the union of those menus. - -### Contact And Address Semantics - -Observed recipient fields include: - -- display name, given name, family name, title, and formal salutation -- organization/unit and function context -- phone, fax, email, and URL -- `care of`/`for the attention of` lines -- street, postal code, locality, country, and internal mail routing -- person, registration, and organizational-unit identifiers -- address purpose variants such as private, semester, home, business, service, - and correspondence address -- effective employment or membership data used to decide eligibility - -The legacy system also allows a requested number of labels for an individual -recipient. That quantity belongs to an output job, not to the canonical address -record. - -### Recipient Selection - -Selections cover several distinct patterns: - -- static categories of institutional units -- people assigned to a function or organizational level -- current-state selections with effective-date rules and exclusions -- geographic and demographic selections -- combinations and unions of predefined audiences -- explicit person or unit lookup by source identifier -- department-specific variants of a shared audience -- user-selected additional predicates and sort orders in the adjacent ETI - report layer - -The important reusable abstraction is therefore a versioned, parameterized, -permissioned segment definition. The 265 query branches must not become 265 -new backend endpoints. - -### Output - -The directly observed output modes are: - -- on-screen recipient table with contact and postal fields -- spreadsheet export -- plain-text label preview -- generated label file -- emailed label file -- central label printing -- BCC mail draft - -The adjacent print-server flows additionally produce: - -- formatted lists and grouped reports -- personalized letters and notices -- HTML, spreadsheet-compatible, TeX, PostScript, and PDF artifacts -- printer-specific layouts and direct print jobs -- password-protected output and combined document bundles - -### Configuration - -The ETI layer is an early configuration-driven report system. A definition can -declare: - -- a SQL source -- named optional filter predicates -- named sort orders -- list and label layouts -- page, line, margin, repetition, and format settings -- screen or spreadsheet output - -That is conceptually close to a GovOPlaN combination of a Dataflow template, -typed output template, and Report/Campaign run configuration. - -## Legacy Limitations We Should Not Reproduce - -- users, departments, permissions, query variants, and output paths are - hard-coded -- credentials are embedded in source files -- request values are interpolated into SQL and shell commands -- authentication, authorization, session transfer, and application routing are - coupled -- selection names do not carry version, owner, purpose, legal basis, or - provenance -- past output cannot be reproduced reliably after source data or query code - changes -- exclusions and exceptional recipients are hidden inside SQL -- there is no first-class consent, suppression, address-quality, or duplicate - resolution model -- mail generation relies on client-side `mailto` BCC links -- print operations have weak status, retry, cancellation, and evidence - handling -- temporary files and generated artifacts are not governed records -- the UI does not explain why a recipient was included, excluded, or - inaccessible - -## Current GovOPlaN Coverage - -| Capability | Current state | Primary owner | -| --- | --- | --- | -| Scoped address books and contacts | Implemented | Addresses | -| Multiple email, phone, and postal contact points | Implemented | Addresses | -| Static address lists | Implemented | Addresses | -| vCard import/export and CardDAV sync | Implemented | Addresses | -| Read-only lookup and immutable email-recipient snapshots | Implemented | Addresses | -| Source provenance and sync conflicts | Implemented | Addresses | -| Governed source catalogue, snapshots, and frozen states | Implemented first slice | Datasources | -| Connector-backed tabular acquisition and preview | Implemented first slice | Connectors | -| Graphical/SQL transformations, joins, filters, expressions, quality, and reconciliation | Implemented broad first slice | Dataflow | -| Campaign snapshots, review, mail delivery, and evidence | Implemented for mail | Campaign/Mail | -| Typed template library and document rendering | Scaffold/issue only | Templates | -| BI reports and spreadsheet-grade exports | Scaffold/issue only | Reporting | -| Mixed operational distribution lists | Contract/implementation issues only | Distribution Lists | -| Dynamic address segments, consent, suppression, and preferences | Open issue | Addresses | -| Deduplication, merge, quality, and complete history | Open issue | Addresses | -| Postal recipient resolution and channel-neutral snapshots | Missing | Addresses | -| Direct governed print jobs | Missing | Future Print module plus connector providers | -| End-to-end guided AdreMa workflow | Missing | Workflow plus consuming modules | - -## Target Architecture - -### 1. Canonical Parties And Contact Points - -Addresses should model locally managed parties while linking, rather than -duplicating, authoritative IDM and Organizations records. - -Required additions: - -- party kind: person, organization, household, group, or location -- formal and display-name components, locale, title, and salutation -- optional stable references to identity, organization, unit, and function - providers -- typed relationships such as member, employee, office holder, household - member, assistant, or care-of contact -- effective dates and provenance on relationships and contact points -- postal fields for care-of/addressee lines, PO boxes, country codes, internal - mail routes, and delivery instructions -- purpose and preference metadata for private, business, service, - correspondence, billing, and other address uses - -The model must remain usable when IDM or Organizations is absent. Optional -provider links enrich a local party; they do not make those modules hard -dependencies. - -### 2. Governed Segments - -Addresses owns the address-domain segment definition and user experience. -Dataflow evaluates complex tabular predicates, while Datasources and Connectors -provide governed inputs. - -A segment needs: - -- immutable definition revisions -- system, tenant, group, and user scope -- complete-flow versus reusable-template semantics -- parameters with types, defaults, constraints, and permitted overrides -- explicit include, exclude, and manual-override sets -- source fingerprints and freshness requirements -- preview, count, sample, and "why included/excluded" diagnostics -- schedule/event refresh policy where materialization is wanted -- owner, purpose, legal basis, retention, and policy provenance -- materialized/frozen recipient snapshots for reproducible use - -Simple tag/contact filters can execute in Addresses. Cross-source joins and -complex expressions should compile to a Dataflow revision rather than creating -a second query engine. - -### 3. Recipient Resolution - -The current recipient-source DTO is email-oriented. AdreMa parity needs a -versioned channel-neutral contract that can resolve: - -- email targets -- postal targets -- internal-mail targets -- postbox targets where Postbox is installed -- unresolved or blocked targets with stable reason codes - -Resolution must consider: - -- requested channel and communication purpose -- effective date -- preferred address/contact point -- explicit address-purpose selection and fallback rules -- locale and international postal formatting -- consent, legal basis, suppression, and policy decisions -- duplicate targets and household/organization grouping -- source revision, selected contact-point ID, and complete provenance - -Consumers freeze the resolution result. They never retain only a live pointer -to an address list or segment. - -### 4. Static And Operational Lists - -The existing split remains correct: - -- Addresses owns address-only lists and address-domain segments. -- Distribution Lists owns mixed operational `Verteiler` containing address - records, identities, users, groups, organization units, functions, roles, - raw targets, and nested distribution lists. -- Workflow/Tasks owns an `Umlauf` with ordering, state, deadlines, escalation, - and decisions. - -Distribution-list entries need stable IDs. A consumer stores an immutable -expansion snapshot. Consumer-specific enrichment belongs to that consumer; -reusable derived lists are separate, revision-pinned definitions. - -### 5. Templates, Artifacts, And Delivery - -Templates should provide typed render contracts for: - -- labels and label sheets -- envelopes -- form and serial letters -- email and postbox messages -- list/report layouts - -Templates declare required fields and output capabilities. Rendering produces a -managed Files artifact with template revision, input snapshot hash, renderer -version, page/count summary, and diagnostics. - -Campaign should orchestrate postal batches in the same way it orchestrates -mail: freeze recipients, validate required fields, review exceptions, render, -approve, deliver or export, reconcile outcomes, and retain evidence. - -Direct physical printing deserves a dedicated domain boundary once implemented: - -- Print owns printers, queues, jobs, status, cancellation, retry, accounting, - secure release, and job evidence. -- Connectors supplies IPP/CUPS, Windows print-server, or provider-specific - connection profiles. -- Campaign, Templates, Files, and Workflow consume a versioned print capability. - -Downloading a generated PDF is a valid deployment without Print installed. -Matching AdreMa's direct central-print behavior requires Print. - -### 6. Governance And Quality - -Parity is not sufficient without: - -- purpose- and channel-specific consent/legal-basis records -- do-not-contact and returned/invalid-address suppression -- normalization and validation with original-value preservation -- duplicate candidates, survivorship rules, manual merge/split, and undo - evidence -- field-level provenance and source-of-truth precedence -- stale-source and stale-segment warnings -- field/row/export policy decisions with user-readable explanations -- complete audit events for read, export, resolution, merge, rendering, and - delivery -- retention, legal hold, and deletion behavior for source records and frozen - output evidence - -### 7. Guided User Experience - -The default journey should be: - -1. Choose or create an address list/segment. -2. Preview the authorized audience and inspect included, excluded, duplicate, - invalid, and suppressed counts. -3. Select channel, address purpose/fallback, sort, and grouping. -4. Freeze a recipient snapshot. -5. Select a compatible template/output format. -6. Review individual exceptions and approve the run. -7. export, send, or print through available capabilities. -8. inspect progress, outcomes, returned items, and evidence. - -Workflow may package this as a reusable guided process and activate a focused -View. Every underlying resource must remain independently accessible and -permission-checked. - -## Representative Golden Flow - -Before migrating any historical selection, build a synthetic AdreMa fixture -covering: - -- people, organizations, units, functions, and effective-dated assignments -- multiple postal-purpose variants and internal mail -- a function-based segment -- an organization-unit segment -- a geography-based segment -- a union of segments -- explicit inclusion and exclusion -- duplicate and suppressed recipients -- deterministic sorting and address fallback -- frozen postal and email snapshots -- label, spreadsheet, and letter output expectations - -The fixture should assert exact recipient IDs, selected contact-point IDs, -ordering, exclusion reasons, source fingerprints, and output hashes. It must -contain no archived record-level data. - -## Migration Strategy - -Do not translate the legacy source one query branch at a time into application -code. - -1. Inventory each still-relevant named selection with owner, purpose, legal - basis, source systems, parameters, output type, and expected use frequency. -2. Retire obsolete and duplicate selections before migration. -3. Map source tables to governed Connector/Datasource definitions. -4. Convert reusable predicates into Dataflow templates or simple - Addresses-owned filters. -5. compare the new result against an authorized legacy run using counts and - pseudonymized stable keys. -6. approve and version the new segment. -7. migrate output layouts into typed Templates. -8. retain a migration report and decommission the corresponding legacy path. - -## Recommended Delivery Order - -### Priority 1: Functional Parity Foundation - -1. Typed party, relationship, address-purpose, and effective-date model. -2. Channel-neutral recipient resolution with postal snapshots. -3. Dynamic governed segments through Dataflow/Datasources. -4. Synthetic AdreMa golden-flow fixture. -5. Typed label, envelope, and letter templates with managed artifacts. - -### Priority 2: Operational Parity - -1. Campaign postal-batch review and output flow. -2. Spreadsheet/report exports with exact frozen-snapshot evidence. -3. Consent, suppression, preferences, deduplication, merge, and quality UI. -4. CSV/XLSX and directory/database migration profiles. -5. Distribution-list expansion and Campaign integration. - -### Priority 3: Beyond AdreMa - -1. Direct governed print jobs and secure release. -2. returned-mail and correction workflows. -3. postal-provider/franking integration and delivery reconciliation. -4. scheduled/event-driven segment refresh and recurring campaigns. -5. address analytics, geocoding where policy permits, and quality trends. - -## Completion Standard For The Umbrella Feature - -The AdreMa umbrella is complete when a user can define or reuse a permissioned -audience, explain and freeze the exact recipients, create reviewed label/letter -or digital outputs, send/export/print through installed modules, and later -prove exactly which source data, rules, template, actor, and delivery outcome -were involved. The same flow must degrade cleanly when optional modules such as -Mail, Campaign, Templates, Workflow, Reporting, or Print are absent. diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index 294906a..cfab057 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -216,12 +216,13 @@ Tasks: - Exchange/Microsoft 365 contacts connector - Google Contacts connector - CSV/XLSX/LDIF import mapping profiles -- classical address-list UI and static/dynamic address-domain segments +- classical address-list UI; reusable static/dynamic operational segments move + to `govoplan-dist-lists` - 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 +- richer vCard `KIND`/`RELATED` round-trip and stable links to IDM/Organizations Exit criteria: