chore: sync GovOPlaN module split state

docs/CONNECTOR_BOUNDARY.md

@@ -0,0 +1,65 @@
+# File Connector Boundary
+
+GovOPlaN Files owns the managed-file boundary: frozen blobs, versions, shares,
+campaign attachment evidence, provenance, connector policy, connector profiles,
+and read-only browse/import APIs that turn external files into managed
+GovOPlaN files.
+
+The built-in connector layer is intentionally on-demand. It does not run remote
+indexing, background sync, remote mutation, or upstream permission management.
+Connectors may browse an external source, import one selected file, freeze it as
+a managed file, record provenance, and audit the access.
+
+## Built-In Baseline
+
+The files module may keep small baseline providers when they are needed for
+normal product workflows and can share the same governance model:
+
+- Seafile through the native read/download API
+- Nextcloud through WebDAV
+- generic WebDAV
+- SMB through the optional `smb` extra
+
+These providers are surfaced through connector descriptors at
+`GET /api/v1/files/connectors/providers`. Provider descriptors declare whether
+the provider is implemented, whether its optional dependency is installed, and
+which browse/import behaviors are available.
+
+## Separate Connector Module Candidates
+
+A separate connector module becomes appropriate when integration needs exceed
+on-demand browse/import:
+
+- background indexing or synchronization
+- bidirectional remote mutation
+- long-running transfer workers
+- provider-specific credential lifecycle or OAuth flows
+- DMS/eAkte metadata models, registers, retention, or filing plans
+- S3-compatible object store administration
+- NFS host-mount lifecycle or sidecar coordination
+- provider-specific WebUI administration beyond profile fields
+
+In that model, `govoplan-files` should keep the managed-file import contract,
+policy checks, provenance model, and audit events. A connector module should own
+provider-specific discovery, synchronization, credentials, health checks, and
+any remote write behavior.
+
+## Provider Responsibilities
+
+Every provider must:
+
+- enforce GovOPlaN profile visibility and connector policy before browse/import
+- keep credentials as environment variables or secret references, never API
+  response values
+- import external files into managed storage before they are used in campaigns
+  or workflows
+- preserve source provenance and revision metadata
+- emit connector audit events for imported or accessed files
+- treat remote ACLs as upstream checks, not as a replacement for GovOPlaN policy
+
+## Non-Goals For Files
+
+Files does not own collaborative editing, comments, document review workflows,
+remote lock orchestration, DMS records management, or external system data
+models. Those belong to future document, workflow, DMS, or connector modules and
+should integrate through capabilities and managed-file imports.

docs/CONNECTOR_SPACES.md

@@ -0,0 +1,147 @@
+# Connector Spaces
+
+GovOPlaN Files should treat external file shares as two separate product
+objects:
+
+1. A governed connection profile defines a reusable remote endpoint such as a
+   WebDAV server, Nextcloud account, Seafile server, or SMB share. Profiles are
+   administered in settings at system or tenant scope, with the same
+   inheritance and limit semantics used by mail-server profiles.
+2. A governed credential profile defines reusable authentication material for
+   one provider or for any compatible provider. Credentials are administered
+   separately from connection profiles and can carry their own allow/deny
+   policy.
+3. A linked file space binds one concrete remote folder or library path from an
+   allowed profile to a user or group. Linked spaces appear beside "My files"
+   and group file spaces in the files module.
+
+This keeps secrets, endpoint governance, and tenant limits in settings, while
+keeping user/group workspaces and concrete folder choices in the files module.
+
+## Model
+
+Connection profile:
+
+- provider: `seafile`, `nextcloud`, `webdav`, `smb`, or a future provider
+- endpoint URL and optional base path
+- scope: `system` or `tenant` for administered profiles; user/group profiles
+  may be allowed later only when policy explicitly permits them
+- optional credential profile id
+- capabilities: browse, sync, import, optional write when a provider supports it
+- profile-local policy for allow/deny rules
+
+Credential profile:
+
+- provider: a specific provider or any provider
+- scope: `system` or `tenant` for administered credentials
+- credential mode: anonymous, environment reference, secret reference, or
+  encrypted stored password/token
+- username and redacted secret configuration
+- credential-local policy for allow/deny rules
+
+Connector policy:
+
+- system policy is the baseline
+- tenant policy inherits system policy and may narrow it unless system allows
+  lower-level relaxation
+- future user/group policy may narrow tenant policy for self-service links
+- policies can allow or block providers, profile ids, endpoint URLs, external
+  path prefixes, credential ids, credential inheritance, and local linked-space
+  creation
+
+Linked connector space:
+
+- owner type: user or group
+- display name
+- connector profile id
+- remote library id or share id
+- remote root path
+- sync mode: manual initially; background sync is future work
+- read-only flag from provider/policy
+- active/deleted state
+
+The linked space should be addressable as a normal file space in the files UI.
+For the first implementation slice, actions may use the existing connector
+browse/sync APIs and managed file storage. A linked space can therefore browse
+the remote folder and sync selected files into managed storage. Later slices can
+add a native remote listing view or background sync jobs.
+
+## Policy Semantics
+
+Use mail-profile terminology because administrators already see it there:
+
+- must use: lower scopes are restricted to selected profile ids or providers
+- can use: lower scopes may choose from inherited allowed profiles
+- shall not use anything outside: endpoint URLs and path prefixes are enforced
+  by deny/allow rules before browse, import, or sync
+- may create local links: controls whether users/groups can add linked spaces
+  from inherited profiles
+
+Connector policy should provide an explainable effective policy response with
+source path entries: system, tenant, user, group, campaign when applicable.
+
+## Current State
+
+Implemented:
+
+- provider descriptors for Seafile, Nextcloud, WebDAV, and SMB
+- database-backed connector profiles with system and tenant scope
+- database-backed connector credentials with system and tenant scope
+- encrypted stored password/token support for database credentials
+- JSON/environment-defined connector profiles with system, tenant, user, group,
+  and campaign visibility
+- connector allow/deny policy enforcement before browse/import/sync, including
+  provider, connection profile, credential profile, and path checks
+- read-only browse endpoints
+- import and sync into managed files with provenance and revision metadata
+- audit events for connector import, sync, and access
+- settings/admin UI sections for system and tenant file connections and
+  credentials
+- linked connector-space rows owned by users or groups
+- file-space API responses that include linked connector spaces
+- Files UI entry point to create linked connector spaces from a browsed remote
+  profile/folder
+- Files UI sync dialog for choosing a profile, browsing a remote folder, and
+  syncing a selected file into a managed destination folder
+- Files UI connector-space view with provider/read-only/manual-sync state
+- Docker dev stack smoke checks for WebDAV, Nextcloud, and SMB
+
+Missing:
+
+- explicit connector profile policy rows equivalent to mail-profile policies
+- effective connector policy/explain UI equivalent to mail-profile policies
+- edit/manage actions for existing linked connector spaces
+- optional background sync or remote-write semantics
+
+## Implementation Phases
+
+1. Persist governed connector profiles and policies.
+   - `file_connector_profiles` exists for system and tenant profiles.
+   - `file_connector_credentials` exists for system and tenant credentials.
+   - Environment JSON profiles remain bootstrap/compatibility profiles.
+   - Profile and credential CRUD endpoints exist for database-backed records.
+   - Remaining: `file_connector_policies` plus effective policy/explain output.
+
+2. Add linked connector spaces.
+   - `file_connector_spaces` exists with owner user/group, profile id, library
+     id, remote path, display label, sync mode, and active state.
+   - Connector policy is enforced before creating or using a link.
+   - Linked connector spaces are returned from `/api/v1/files/spaces`.
+
+3. Surface linked spaces in the Files UI.
+   - Linked spaces appear beside managed user/group spaces.
+   - The add-space dialog browses an allowed profile and links the current
+     remote folder/library root.
+   - The connector browser/sync flow is reused when a linked space is open.
+   - Remaining: edit/manage actions for existing linked spaces.
+
+4. Add sync orchestration.
+   - Manual sync selected file is already available.
+   - Add folder-level manual sync.
+   - Add optional scheduled/background sync with conflict reporting.
+
+5. Add provider-specific expansion.
+   - OAuth/secret-store credentials.
+   - Remote write and delete only where policy and provider support it.
+   - DMS/eAkte metadata integrations in a separate connector or documents
+     module.

docs/DOCUMENT_COLLABORATION_BOUNDARY.md

@@ -0,0 +1,54 @@
+# Document Collaboration Boundary
+
+GovOPlaN Files is the governed managed-file module. It stores uploaded/imported
+blobs, versions, shares, provenance, ZIP imports/exports, connector imports, and
+campaign attachment evidence. It should stay reliable, auditable, and simple.
+
+Collaborative document behavior should be owned by a future documents module or
+by provider-specific connector modules when the behavior is delegated to systems
+such as Nextcloud, Seafile, Collabora, OnlyOffice, OpenDesk, or DMS/eAkte
+platforms.
+
+## Files Owns
+
+- managed blobs and immutable version evidence
+- owner-scoped user/group file spaces
+- shares and access checks for managed files
+- connector browse/import into managed storage
+- source provenance, source revision, and audit events
+- freeze-before-send campaign attachment behavior
+- previews generated from managed file versions
+
+## Documents Or Connectors Should Own
+
+- co-editing sessions and editor launch URLs
+- comments, suggestions, document tasks, and review state
+- check-in/check-out, remote locks, and lock timeouts
+- semantic document versions beyond blob versions
+- template merge flows and generated-document lifecycle
+- external DMS metadata, filing plans, record categories, and retention classes
+- provider-specific sync state and conflict resolution
+- collaborative presence and notification behavior
+
+## Integration Shape
+
+The documents layer should integrate with files through stable contracts:
+
+- create or import a managed file version for evidence points
+- attach source provenance when a file came from an external editor or DMS
+- ask files for read/download access rather than importing files internals
+- emit workflow/audit events when a collaborative document reaches a governed
+  state such as reviewed, approved, frozen, sent, or archived
+- use connector providers for provider-specific browse/import/write behavior
+
+Files may expose links to a document or connector module, but it should not own
+the collaboration state machine. A collaborative document can produce many
+working states; GovOPlaN Files should persist the governed snapshots that other
+modules can safely use as evidence.
+
+## Practical Rule
+
+If a feature is about storing, sharing, importing, downloading, or freezing a
+file, it belongs in `govoplan-files`. If a feature is about people jointly
+editing, reviewing, locking, commenting on, or routing a document through a
+semantic process, it belongs in a documents/workflow/DMS integration module.