Migrate Addresses interface patterns

src/govoplan_addresses/backend/manifest.py

@@ -35,6 +35,7 @@ from govoplan_core.core.provider_governance import (
     ProviderObjectDeclaration,
     declared_module_architecture,
 )
+from govoplan_core.core.views import ViewSurface
 from govoplan_core.db.base import Base
 from govoplan_addresses.backend.provider_state import (
     CARDDAV_PROVIDER_ID,
@@ -312,6 +313,14 @@ manifest = ModuleManifest(
         package_name="@govoplan/addresses-webui",
         routes=(FrontendRoute(path="/address-book", component="AddressBookPage", required_any=("addresses:contact:read",), order=80),),
         nav_items=(NavItem(path="/address-book", label="Address Book", icon="book-user", required_any=("addresses:contact:read",), order=80),),
+        view_surfaces=(
+            ViewSurface(id="addresses.page", module_id="addresses", kind="route", label="Address Book", order=80),
+            ViewSurface(id="addresses.sources", module_id="addresses", kind="section", label="Address sources", order=10),
+            ViewSurface(id="addresses.contacts", module_id="addresses", kind="section", label="Contacts", order=20),
+            ViewSurface(id="addresses.detail", module_id="addresses", kind="section", label="Contact detail", order=30),
+            ViewSurface(id="addresses.governance", module_id="addresses", kind="action", label="Communication governance", order=40),
+            ViewSurface(id="addresses.sync", module_id="addresses", kind="action", label="Address synchronization", order=50),
+        ),
     ),
     migration_spec=MigrationSpec(
         module_id="addresses",
@@ -380,6 +389,16 @@ manifest = ModuleManifest(
             audience=("tenant_admin", "operator", "module_admin"),
             related_modules=("campaigns", "mail", "forms", "reporting", "portal", "postbox"),
             order=30,
+            metadata={
+                "seed": True,
+                "help_contexts": [
+                    "addresses.page",
+                    "addresses.sources",
+                    "addresses.contacts",
+                    "addresses.detail",
+                    "addresses.state.read-only",
+                ],
+            },
         ),
         DocumentationTopic(
             id="addresses.contact-point-resolution",
@@ -396,6 +415,16 @@ manifest = ModuleManifest(
             audience=("tenant_admin", "operator", "module_admin"),
             related_modules=("dist_lists", "campaigns", "policy", "templates"),
             order=31,
+            metadata={
+                "seed": True,
+                "help_contexts": [
+                    "addresses.governance",
+                    "addresses.field.channel",
+                    "addresses.field.contact-point",
+                    "addresses.field.communication-purpose",
+                    "addresses.field.effective-period",
+                ],
+            },
         ),
         DocumentationTopic(
             id="addresses.tabular-imports",
@@ -450,6 +479,44 @@ manifest = ModuleManifest(
             related_modules=("campaigns", "dist_lists", "policy", "audit"),
             order=32,
         ),
+        DocumentationTopic(
+            id="addresses.reference.fields-and-consequences",
+            title="Address fields, scope, and action consequences",
+            summary="Scope, source authority, contact points, list membership, archival, synchronization, and merge consequences.",
+            body=(
+                "Address books are scoped to a user, group, tenant, or authorized system context. Inherited and externally authoritative "
+                "books may remain visible but read-only. Contacts own reusable name, organization, electronic, phone, postal, tag, note, "
+                "quality, and provenance facts; address lists reference contact points from the same book and do not replace Distribution "
+                "Lists. Archival hides a book, list, or contact from ordinary selection while preserving governed history and references. "
+                "CardDAV and LDAP sources expose their direction, authority, freshness, diagnostics, conflict, and stale-state behavior. "
+                "Imports and synchronization require preview before mutation. Contact merges select a survivor and field provenance, repair "
+                "list references transactionally, and retain redirects and evidence so a matching merge can be undone or split."
+            ),
+            layer="configured",
+            documentation_types=("admin", "user"),
+            audience=("tenant_admin", "operator", "module_admin", "power_user"),
+            related_modules=("dist_lists", "connectors", "datasources", "campaigns", "policy", "audit"),
+            order=35,
+            metadata={
+                "seed": True,
+                "help_contexts": [
+                    "addresses.field.book-scope",
+                    "addresses.field.contact-identity",
+                    "addresses.field.organization",
+                    "addresses.field.contact-point",
+                    "addresses.action.archive",
+                    "addresses.action.import",
+                    "addresses.action.sync",
+                    "addresses.action.merge",
+                ],
+                "consequence_classes": {
+                    "archive": "Removes the object from ordinary selection while retaining governed history and references.",
+                    "import_or_sync": "Applies only a reviewed bounded plan and retains source revision, diagnostics, and provenance.",
+                    "merge": "Repoints governed references to a survivor and retains reversible redirect and provenance evidence.",
+                    "governance_fact": "Adds or ends an effective-dated communication decision without erasing prior facts.",
+                },
+            },
+        ),
     ),
     external_providers=(CARDDAV_PROVIDER, LDAP_PROVIDER),
     external_provider_state_providers=(