Integrate Quick Access product presentation

2026-08-06 19:02:56 +02:00
parent 241db623c7
commit f3cfd1bccc
18 changed files with 282 additions and 6 deletions
@@ -15,7 +15,7 @@ GOVOPLAN_DB_MAX_OVERFLOW=10
 GOVOPLAN_DB_POOL_TIMEOUT_SECONDS=30
 GOVOPLAN_DB_POOL_RECYCLE_SECONDS=1800

-ENABLED_MODULES=tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,files,templates,mail,campaigns,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,workflow_engine,workflow,tasks,views,search,risk_compliance,postbox,notifications,services,parties,mandates,decisions,portal,cases,committee,docs,ops
+ENABLED_MODULES=tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,files,templates,mail,campaigns,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,workflow_engine,workflow,tasks,views,quick_access,search,risk_compliance,postbox,notifications,services,parties,mandates,decisions,portal,cases,committee,docs,ops

 CELERY_ENABLED=true
 REDIS_URL=redis://127.0.0.1:6379/0
@@ -75,6 +75,12 @@ surfaces may hide irrelevant functions, but they never grant access. Users can
 escape a focused mode when policy permits and can always understand why
 something is unavailable.

+Configurable product areas organize authorized capabilities around work,
+services, records, communication, meetings, data and institutional
+responsibility. The optional Quick Access rail presents task-local Work,
+Calendar, Messages and Files contributions without merging their owners or
+turning presentation settings into permissions.
+
 ### 8. Evidence and recovery are part of the operation

 Intent, exact input versions, approvals, external effects, receipts,
@@ -146,6 +152,11 @@ package coordinates, and schema details are technical provenance. They are
 visible to administrators and in expandable diagnostics, but they are not the
 primary information architecture for ordinary work.

+The complete permission-derived tool catalogue remains deliberately available
+to power users. Product areas and Quick Access provide sensible system and
+tenant defaults plus governed user personalization; they do not make familiar
+tools harder to reach merely to conceal modular implementation.
+
 ## Maturity Rule

 A repository, route, model, or unit test does not make a capability complete.
@@ -15,6 +15,8 @@ contributions.

 Implementation is tracked in
 [Core #283](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/283).
+The accepted configurable product-area and task-local tool design is defined
+in [Quick Access And Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md).

 ## Current Exposure Inventory

@@ -80,6 +82,22 @@ The default shell should prioritize:
 4. pinned user destinations;
 5. administration and technical module inspection when authorized.

+The baseline product areas are Work, Services and Cases, Records and
+Documents, Communication, Meetings and Decisions, Data and Assurance, and
+People and Responsibility. They are configurable system/tenant defaults and
+Views projections, not hard-coded repository groups. Empty areas disappear;
+single-destination areas may link directly; familiar tools may remain pinned.
+
+The complete permission-derived module rail remains available as **All
+available tools**. Its ability to scroll is useful and is not itself the
+product defect. The defect is requiring people to infer a task or outcome from
+repository topology.
+
+Task-local Work, Calendar, Messages and Files tools may be contributed to the
+optional `govoplan-quick-access` rail. Messages composes Mail, Postbox and
+future governed chat presentation without merging their channel semantics or
+state.
+
 A module route remains a valid deep link. A product area may combine links and
 owner-rendered surfaces from several modules. When a required contribution is
 absent, the area explains the missing outcome rather than rendering a broken
@@ -106,6 +124,12 @@ hiding operational truth.

 ## Migration

+Core's product-area and Quick Access contracts, the optional Quick Access
+module, the first five providers and immutable View presentation revisions are
+implemented. The migration below now concerns broader classification and
+product-language adoption; it is not a prerequisite for safely enabling the
+first rail slice.
+
 ### Slice 1: inventory and aliases

 - classify every route, navigation item, widget, setting, search object, and
@@ -119,6 +143,8 @@ hiding operational truth.
 - make work areas and configured packages the default navigation;
 - move the complete module catalogue to administration and an optional power-
  user surface.
+- implement the configurable Quick Access rail through Core-mediated
+  contributions, system/tenant/user resolution and View/Policy ceilings.

 ### Slice 3: composite journeys

@@ -49,9 +49,17 @@ current context. These actions remain owned by their modules and use bounded
 overlays or workspaces; the shell supplies discovery and return context rather
 than reimplementing them.

+The accepted first presentation is the optional, configurable Quick Access
+rail: Work, Calendar, Messages and Files. Messages may compose Mail, Postbox
+and future chat contributions while preserving their separate authority and
+channel semantics. System and tenant administrators govern availability and
+forced entries; users select categories and ordering within those ceilings.
+Modules register typed contributions through Core and continue to work when
+Quick Access is absent.
+
 This theme is owned by Core experience contracts, Views, Dashboard, Tasks,
-Workflow Engine, Docs, and the contributing feature modules. The first proof is
-the resumable service-to-decision/eAkte journey in GovOPlaN #42.
+Workflow Engine, Quick Access, Docs, and the contributing feature modules. The
+first proof is the resumable service-to-decision/eAkte journey in GovOPlaN #42.

 ### Governed human work

@@ -0,0 +1,193 @@
+# Quick Access And Product Areas
+
+## Purpose
+
+GovOPlaN presents institutional work without requiring ordinary users to
+understand the installed package graph. Two complementary projections provide
+that experience:
+
+- **product areas** group destinations, objects, work and actions by the
+  outcome a person recognizes;
+- **Quick Access** keeps a small set of task-local tools available without
+  leaving the current page, case, record or Workflow context.
+
+Technical modules remain the implementation, release and provenance boundary.
+Product areas and Quick Access are presentation contracts over those owners;
+they do not copy domain state or bypass authorization.
+
+Implementation is tracked by Core #283 and #285, GovOPlaN's product-experience
+umbrella, Views, Policy and `govoplan-quick-access`.
+
+The repository and product name is `govoplan-quick-access`, with module id
+`quick_access`. `govoplan-qar` was rejected because the abbreviation hides the
+purpose in package catalogues, diagnostics, permissions and operations.
+
+## Implementation Status
+
+The first production-shaped slice is implemented:
+
+- Core validates and publishes versioned `product_areas` and
+  `quick_access_tools` manifest contracts;
+- `govoplan-quick-access` derives its live catalogue from installed modules,
+  persists optimistic-concurrency-protected system, tenant and user profiles,
+  and resolves blocked, forced, ordered and stale preferences;
+- the shell hosts the optional right rail and one composed drawer with keyboard
+  dismissal, focus return, responsive mobile behavior and full-page fallbacks;
+- Tasks, Calendar, Mail, Postbox and Files contribute the first owner-rendered
+  tools; Mail and Postbox remain separate sections inside Messages;
+- immutable View revisions now carry grouped/flat navigation, product-area
+  order and optional labels. Scoped Views therefore configure product
+  presentation for system, tenant, group, user and Workflow contexts;
+- the expanded left rail groups classified destinations while retaining
+  Dashboard and every authorized unclassified destination under More tools.
+
+The remaining rollout is classification rather than a missing boundary: other
+user-facing modules must announce their product areas and future bounded tools,
+reference journeys need browser accessibility evidence, and richer active-object
+context should be added only through a separately versioned launch-context
+contract. Until classification is complete, authorized unclassified routes
+remain visible rather than disappearing.
+
+## Quick Access Boundary
+
+Core owns a versioned contribution contract. Feature modules may register a
+tool when they have a useful bounded surface. They do not import Quick Access.
+`govoplan-quick-access` owns configuration, effective resolution, ordering,
+the right-side rail and its drawer. Views may narrow tools for the current
+task. Policy may constrain availability and customization. Access and each
+owner's backend remain authoritative.
+
+The initial categories are:
+
+| Category | Typical contributions |
+| --- | --- |
+| Work | Explicit Tasks, Workflow handoffs, approvals, deadlines and exceptions |
+| Calendar | Today/upcoming agenda, event creation and scheduling launch |
+| Messages | Mail, function-bound Postbox messages and future governed chat providers |
+| Files | Contextual/recent files, attachment selection and upload |
+
+Messages is one shell category but not one data model. Mail, Postbox and future
+chat providers retain their channel semantics, custody, policy, audit and
+delivery behavior. The drawer identifies the channel where that distinction
+matters.
+
+## Contribution Contract
+
+A Quick Access contribution declares:
+
+- a stable id, category and human label;
+- icon, order and optional badge/summary provider;
+- required permissions and optional dependencies;
+- accepted context references and produced return references;
+- an owner-rendered bounded WebUI surface and full-page fallback route;
+- View surface, help context and availability explanation;
+- whether the contribution supports preview, create, select or resume.
+
+The shell passes only bounded references: tenant, acting context, temporal
+read context, active task/Workflow, current institutional object, selected
+resources and a safe return location. The owner reauthorizes every read and
+effect. Credentials, protected content and permission decisions are never
+embedded in launch context.
+
+## Effective Configuration
+
+The effective rail is resolved from:
+
+1. installed and enabled modules and their registered contributions;
+2. system availability, forced entries and ordering defaults;
+3. tenant availability, forced entries and ordering defaults;
+4. group and user View/Policy ceilings where configured;
+5. the user's enabled categories, entries and ordering;
+6. the active View and optional Workflow-step narrowing overlay;
+7. current authorization and contribution availability.
+
+Lower scopes may narrow or reorder allowed entries but cannot enable a tool
+blocked above them. A forced entry cannot be removed below its source. User
+configuration stores stable contribution ids; unavailable or retired ids are
+retained as explained stale preferences without rendering broken controls.
+
+Configuration screens derive their available choices from the live registry.
+Installing or enabling a contributing module adds its permitted choices;
+disabling it removes the runtime tool while preserving harmless preferences.
+If Quick Access is absent, contributors behave exactly as before.
+
+## Interaction Model
+
+Desktop uses a narrow right-side rail with at most four initial category
+buttons and an overflow when an administrator or user adds more categories.
+Selecting a category opens one fixed, owner-neutral drawer. Contributions are
+shown inside that drawer as tabs, sections or commands according to the
+category contract. The default drawer overlays content so DataGrid and fixed
+workspace layouts do not resize unexpectedly; a later explicit pinned mode may
+reserve layout width on sufficiently wide screens.
+
+The drawer preserves host-page state, has a deterministic focus return, closes
+with Escape, supports keyboard traversal, and provides an explicit full-page
+open action. Mobile and narrow layouts use the same category/configuration
+semantics in a bottom sheet or compact menu.
+
+## Product Areas
+
+Product areas are stable configurable identities, not repositories. The
+recommended baseline is:
+
+- Work;
+- Services and Cases;
+- Records and Documents;
+- Communication;
+- Meetings and Decisions;
+- Data and Assurance;
+- People and Responsibility.
+
+Modules contribute routes, objects, actions, widgets, work sources and help to
+one or more areas. Product packages and administrators may define sensible
+system and tenant defaults. Views select, order, rename or narrow allowed
+areas, and users may personalize them within Policy ceilings. An empty area is
+omitted. An area with one destination may open it directly. A multi-destination
+area provides a useful work/recent/action surface rather than another menu.
+
+Familiar product nouns such as Calendar, Mail or Files may remain directly
+pinned. The objective is not to hide every module name; it is to prevent
+repository topology from determining a person's workflow.
+
+## Full Access And Provenance
+
+The existing permission-derived module rail remains available as **All
+available tools** for power users and deliberate escape from a focused View.
+It contains only currently authorized destinations. Technical module,
+capability, provider and package provenance remains visible in administration,
+diagnostics, evidence and expandable details.
+
+Search, deep links and help distinguish three states:
+
+- available in the active View;
+- authorized but outside the active View, with a temporary escape or View
+  switch;
+- unavailable because of authorization, Policy, configuration or a missing
+  capability, with an actionable explanation.
+
+## Delivery Order
+
+1. Define Core product-area and Quick Access contracts and validation.
+2. Implement `govoplan-quick-access` configuration, effective resolution and
+   shell capability.
+3. Contribute Work, Calendar, Messages and Files bounded surfaces.
+4. Add configurable product-area defaults through Views and product packages.
+5. Migrate navigation, breadcrumbs, search, errors, documentation, dashboard
+   and administration toward product terminology.
+6. Prove keyboard, focus, responsive, optional-module and reference-journey
+   behavior before making it the ordinary-user default.
+
+## Acceptance Criteria
+
+- A user can configure allowed Quick Access categories and ordering without
+  gaining authority.
+- System and tenant administrators can make entries available, forced or
+  unavailable with provenance.
+- Mail, Postbox and another future channel can share Messages presentation
+  while retaining independent state and channel semantics.
+- A reference journey can use a bounded tool and return without losing host
+  state or Workflow context.
+- Product areas remain useful under sparse and rich permission sets and under
+  optional-module permutations.
+- All available tools and technical provenance remain deliberately reachable.
@@ -25,6 +25,7 @@ second live status page.
 | Topic | Canonical source |
 | --- | --- |
 | Product-facing experience and hiding technical module boundaries | [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) |
+| Configurable product areas and task-local tools | [Quick Access and Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md) |
 | Federation between autonomous installations | [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md) |
 | Institutional digital twin and continuous assurance | [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) |
 | Assisted and non-digital channels | [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md) |
@@ -134,6 +134,9 @@ journey needs and supplies contracts shared by all five stages.
 12. **Task-local tools.** Mail, Postbox, Templates, Files, and other common
    actions may contribute bounded launch surfaces with return context. The
    shell and Workflow compose them without copying their data or validation.
+    The optional Quick Access module presents configurable Work, Calendar,
+    Messages and Files categories; system/tenant/user settings and View/Policy
+    ceilings resolve their availability and ordering.

 ## Documentation contract for every reference stage

@@ -53,6 +53,13 @@ often present module names and package structure directly. This is appropriate
 for operators, but ordinary users should see work, services, records, and
 outcomes.

+This is not primarily a rail-length or scrolling problem. Sparse permissions
+already reduce navigation and the complete technical rail remains useful for
+power users. The correction is configurable product areas, task-focused Views
+and a bounded Quick Access rail, while preserving deliberate access to every
+authorized tool and technical provenance. The accepted design is maintained in
+[Quick Access And Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md).
+
 ### Status became duplicated

 Roadmaps, target architecture, fit assessments, issue comments, and release
@@ -123,4 +130,3 @@ The reset succeeds when a public institution can install a signed composition,
 configure a named procedure, complete it through digital and assisted channels,
 connect an external source, reconstruct the authority and evidence, recover it
 after failure, and transfer or retire it without custom code.
-
@@ -7,6 +7,11 @@ responsibility, or workflow step. A View can reduce the visible modules,
 navigation entries, routes, page sections, and commands to the interface
 needed for the current job.

+Views also project configurable product areas and Quick Access contributions.
+They may select, order, rename or hide permitted presentation identities but
+do not move ownership or merge Mail, Postbox, Files, Calendar, Tasks or other
+domain state.
+
 Views are optional. If `govoplan-views` is not installed or enabled, the normal
 permission-derived interface remains unchanged.

@@ -119,6 +124,12 @@ Implemented in the initial Views slice:
  prevention
 - surface declarations for every currently installed module that contributes a
  WebUI, including finer-grained shared administration and settings surfaces
+- immutable presentation settings for grouped or flat navigation, product-area
+  order and product-area labels; the shell resolves these settings through the
+  same system, tenant, group, user and Workflow-aware View projection
+- live product-area identities from module manifests, with authorized
+  unclassified destinations retained under More tools during incremental
+  adoption

 Still intentionally separate:

@@ -127,6 +138,11 @@ Still intentionally separate:
 - read-only and layout-replacement projections beyond the version `1`
  visible/hidden contract

+Quick Access ordering and availability remain owned by
+`govoplan-quick-access`; Views only narrow its declared surfaces for the active
+task. Neither contract permits arbitrary layout or styling. See
+`docs/QUICK_ACCESS_AND_PRODUCT_AREAS.md` in the meta repository.
+
 ## Gitea Work Packages

 - `govoplan#17`: task-focused Views user story
@@ -371,6 +371,12 @@
    "description": "GovOPlaN Risk Compliance module behavior or integration.",
    "exclusive": false
  },
+  {
+    "name": "module/quick-access",
+    "color": "c5def5",
+    "description": "GovOPlaN configurable task-local Quick Access behavior and integrations.",
+    "exclusive": false
+  },
  {
    "name": "module/search",
    "color": "bfdadc",
@@ -63,6 +63,7 @@ full = [
  "govoplan-postbox==0.1.18",
  "govoplan-procurement==0.1.18",
  "govoplan-projects==0.1.18",
+  "govoplan-quick-access==0.1.18",
  "govoplan-records==0.1.18",
  "govoplan-reporting==0.1.18",
  "govoplan-resources==0.1.18",
@@ -58,6 +58,7 @@
    {"name": "govoplan-postbox", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-postbox.git", "path": "govoplan-postbox"},
    {"name": "govoplan-procurement", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-procurement.git", "path": "govoplan-procurement"},
    {"name": "govoplan-projects", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-projects.git", "path": "govoplan-projects"},
+    {"name": "govoplan-quick-access", "category": "module", "subtype": "platform", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-quick-access.git", "path": "govoplan-quick-access"},
    {"name": "govoplan-records", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-records.git", "path": "govoplan-records"},
    {"name": "govoplan-reporting", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-reporting.git", "path": "govoplan-reporting"},
    {"name": "govoplan-resources", "category": "module", "subtype": "domain", "remote": "git@git.add-ideas.de:GovOPlaN/govoplan-resources.git", "path": "govoplan-resources"},
@@ -36,6 +36,7 @@
 -e ../govoplan-workflow-engine
 -e ../govoplan-workflow
 -e ../govoplan-tasks
+-e ../govoplan-quick-access
 -e ../govoplan-views
 -e ../govoplan-voting
 -e ../govoplan-search
@@ -96,6 +96,7 @@ PY
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-workflow-engine/tests
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-workflow/tests
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-views/tests
+"$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-quick-access/tests
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-dashboard/tests
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-postbox/tests
 "$PYTHON" -m unittest discover -s /mnt/DATA/git/govoplan-portal/tests
@@ -56,6 +56,7 @@ FULL_MODULES = (
    "workflow",
    "tasks",
    "views",
+    "quick_access",
    "search",
    "risk_compliance",
    "postbox",
@@ -51,7 +51,7 @@ set +a

 export APP_ENV="${APP_ENV:-staging}"
 export GOVOPLAN_INSTALL_PROFILE="${GOVOPLAN_INSTALL_PROFILE:-production-like}"
-export ENABLED_MODULES="${ENABLED_MODULES:-tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,templates,workflow_engine,workflow,tasks,views,search,risk_compliance,notifications,docs,ops}"
+export ENABLED_MODULES="${ENABLED_MODULES:-tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,templates,workflow_engine,workflow,tasks,views,quick_access,search,risk_compliance,notifications,docs,ops}"
 export DATABASE_URL="${DATABASE_URL:-${GOVOPLAN_PRODUCTION_LIKE_DATABASE_URL:-postgresql+psycopg://govoplan:govoplan-dev@127.0.0.1:55433/govoplan}}"
 export GOVOPLAN_DATABASE_URL_PGTOOLS="${GOVOPLAN_DATABASE_URL_PGTOOLS:-${GOVOPLAN_PRODUCTION_LIKE_DATABASE_URL_PGTOOLS:-postgresql://govoplan:govoplan-dev@127.0.0.1:55433/govoplan}}"
 export REDIS_URL="${REDIS_URL:-${GOVOPLAN_PRODUCTION_LIKE_REDIS_URL:-redis://127.0.0.1:56379/0}}"
@@ -66,7 +66,7 @@ export DATABASE_URL="${DATABASE_URL:-${GOVOPLAN_PRODUCTION_LIKE_DATABASE_URL:-po
 export GOVOPLAN_DATABASE_URL_PGTOOLS="${GOVOPLAN_DATABASE_URL_PGTOOLS:-${GOVOPLAN_PRODUCTION_LIKE_DATABASE_URL_PGTOOLS:-postgresql://govoplan:govoplan-dev@127.0.0.1:55433/govoplan}}"
 export REDIS_URL="${REDIS_URL:-${GOVOPLAN_PRODUCTION_LIKE_REDIS_URL:-redis://127.0.0.1:56379/0}}"
 export CELERY_ENABLED="${CELERY_ENABLED:-true}"
-export ENABLED_MODULES="${ENABLED_MODULES:-tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,templates,workflow_engine,workflow,tasks,views,search,risk_compliance,notifications,docs,ops}"
+export ENABLED_MODULES="${ENABLED_MODULES:-tenancy,organizations,identity,idm,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,poll,scheduling,connectors,datasources,dataflow,dist_lists,templates,workflow_engine,workflow,tasks,views,quick_access,search,risk_compliance,notifications,docs,ops}"
 export FILE_STORAGE_BACKEND="${FILE_STORAGE_BACKEND:-local}"
 export FILE_STORAGE_LOCAL_ROOT="${FILE_STORAGE_LOCAL_ROOT:-$META_ROOT/runtime/production-like/files}"
 export DEV_AUTO_MIGRATE_ENABLED="${DEV_AUTO_MIGRATE_ENABLED:-false}"
@@ -114,6 +114,7 @@ PACKAGE_MODULE_REPOS=(
  "$PARENT/govoplan-poll"
  "$PARENT/govoplan-portal"
  "$PARENT/govoplan-procurement"
+  "$PARENT/govoplan-quick-access"
  "$PARENT/govoplan-records"
  "$PARENT/govoplan-resources"
  "$PARENT/govoplan-risk-compliance"