docs(core): define collaboration connector strategy

2026-08-19 23:15:35 +02:00
parent 8d9bcfd8b5
commit 51bf14f376
1 changed files with 67 additions and 0 deletions
@@ -141,6 +141,73 @@ connector or module issue.
 - Owner/priority: `govoplan-mail`, `govoplan-calendar`,
  `govoplan-connectors`, Wave 1/2.
 #### Collaboration-suite boundary and hand-offs
 Collaboration remains connector-first. The product named below never changes
 which GovOPlaN module owns the administrative meaning of the work:
 | External family | Initial posture | GovOPlaN semantic owner | Connector-owned boundary |
 | --- | --- | --- | --- |
 | Collabora Online, OnlyOffice, Nextcloud Office | Link an externally edited document and its editing session; import a governed rendition only when required | DMS owns document/version, lock, review, approval, retention, and collaboration-session evidence; Files owns stored bytes | Discovery, endpoint health, WOPI/vendor session exchange, callbacks, and provider object references |
 | Matrix, Mattermost, Rocket.Chat, Nextcloud Talk | Create or link a room/thread for a governed work context; do not mirror all conversation history by default | The initiating Case, Workflow, or Task owns the work-context link and disposition; DMS/Records own retained evidence deliberately captured from it | Room/thread creation, membership synchronization, webhook/event normalization, and stable external links |
 | Jitsi and BigBlueButton | Provision or link a conference for an existing appointment/event | Appointments owns booking intent; Calendar owns event, attendee, invitation, and time semantics | Conference provisioning, join/moderator references, provider lifecycle, and bounded attendance/result callbacks |
 | OpenProject and comparable project suites | Link first, then publish or synchronize selected work packages | Tasks owns GovOPlaN task state; Workflow owns orchestration; Cases own case state and evidence references | Project/work-package lookup, publish/synchronize transport, webhooks, version tokens, and external URLs |
 | Cross-suite activity streams | Consume normalized, bounded events only for an authorized work context | The receiving module decides whether an event changes state or becomes evidence; Audit records the GovOPlaN operation | Provider subscriptions, cursor/checkpoint handling, signature validation, event normalization, and replay protection |
 Native collaboration behavior is justified only when GovOPlaN must own the
 semantic state, authorization decision, audit evidence, retention/legal-hold
 rule, or configuration-package fragment. Endpoint profiles, tokens, health,
 protocol clients, provider IDs, retries, and webhook transport remain in
 Connectors (or the owning protocol connector). A feature module consumes a
 Core capability/DTO and must still start and fail explicitly when that optional
 connector is absent; it never imports a provider client.
 The minimum hand-off sequences are:
 1. **Appointment to conference:** Appointments confirms the booking intent;
   Calendar creates or updates the event and invitations; an optional
   conference connector provisions the room idempotently and returns an
   opaque join reference. Calendar stores that reference with the event, not
   the provider credential.
 2. **Case or Workflow to collaborative document:** the initiating module asks
   DMS for a governed document/session; DMS requests an optional office-suite
   connector session and retains version, lock, approval, and callback
   evidence. The Case/Workflow keeps only the DMS reference.
 3. **Case, Workflow, or Task to chat:** the semantic owner requests a room or
   thread with an idempotency key and bounded membership intent. The connector
   returns an external reference; capturing messages as evidence requires an
   explicit DMS/Records action and policy decision.
 4. **Task or Workflow to project suite:** Tasks supplies the task payload and
   Workflow supplies correlation; the OpenProject connector publishes or
   reconciles the work package and returns versioned external-reference and
   retry/conflict evidence. Neither consumer writes connector tables.
 Every executable collaboration connector must pass the common connector
 contract checks plus a provider-focused minimum proof:
 - optional-module startup and partial compositions work without the provider;
 - profile health uses secret references and redacts credentials and remote
  response bodies;
 - tenant/resource authorization is checked before discovery, provisioning,
  lookup, synchronization, or evidence capture;
 - dry-run/simulation performs no remote mutation and explains unsupported
  operations;
 - create/publish calls are idempotent, retries preserve the same external
  reference, and outcome-unknown or version conflicts remain reconcilable;
 - callbacks/webhooks verify authenticity, tenant/profile binding, replay
  protection, and bounded payloads;
 - disable/retire behavior revokes new use while preserving non-secret audit and
  external-reference evidence;
 - Collabora/OnlyOffice prove discovery plus one non-production editing-session
  round trip; Matrix/Mattermost/Rocket.Chat prove room lookup/create plus one
  authenticated bounded event; Jitsi/BigBlueButton prove conference
  provision/cancel; OpenProject proves project/work-package lookup, idempotent
  publish, and conflict handling.
 These are connector acceptance tests, not a claim that those connectors are
 already implemented. Their implementation state remains in the owning
 connector issues and catalogue.
 ### Payment And Public Cashier Systems
 - Strategy: integrate/export/import; keep the payment provider or cashier as