feat: add observer participant role for signature requests

[lfals]

Resolves: #6957

📝 Summary

Adds an observer participant role (UI label: Observer / Testemunha) to signature requests. Observers can be invited to follow document progress and open the validation view, but cannot sign. The feature is gated by the new policy enable_observer_profile (default: disabled).

Backend is the source of truth: role validation, signing denial, status/progress calculations, DocMDP signer limits, sequential signing, e-mail/notification routing, and API contracts all treat observers separately from signers. The request UI exposes separate Signers and Observers lists when the policy is enabled.

Also includes pre-merge hardening: preserve observers when reordering signers in ordered flow, require at least one signer before requesting signatures, regenerate OpenAPI/TypeScript types, and focused regression tests.

🧪 How to test

1. Enable the policy Enable observer profile (system, group, or user scope as needed).
2. Open the Files app, select a PDF, and open Request signature.
3. Use Add → Signer and Add → Observer to add participants.
4. Confirm the UI shows two sections (Signers / Observers) and that observer labels use localized copy (e.g. Testemunha in pt_BR).
5. Try requesting signatures with only observers → must be blocked (toast + API error).
6. Add at least one signer and request signatures → request should succeed; observers should not appear as pending signers.
7. As an observer, open the notification/link → should land on validation, not the signing flow.
8. In ordered numeric flow, reorder signers with observers present → observers must remain in the list.
9. Open validation for a document with both roles → signers and observers appear in separate groups; observer status shows Observing when applicable.

🎨 UI / Front‑end changes

• Policy-gated Add → Signer / Observer menu in request signature flow
• Separate Signers and Observers lists in request and validation views
• Observer-specific labels in participant modal (search, name validation, custom message)
• Client-side guard: block signature request when only observers are present
• Fix drag-and-drop reorder in ordered flow so observers are not removed from file.signers
• Screenshots before/after (add images or links)

🏚️ Before	🏡 After
Single signer list only	Signers + Observers sections when policy enabled

• Tested in multiple browsers (Chrome, Firefox, Safari) – optional but appreciated
• Components, Unit (with vitest) and/or e2e (with Playwright) tests added - Required
• Accessibility verified (contrast, keyboard navigation, screen reader friendly) – if applicable
• Design review approved – optional, link to feedback if available
• Documentation updated (if applicable) – docs repository

🚧 Tasks

• Sync translations via Transifex before release (local l10n/ edits included for dev)
• Add/update user-facing documentation for observer role in LibreSign documentation

⚙️ API / Back‑end changes

• New participant_role column on sign requests (signer | observer) with idempotent migration
• New policy provider enable_observer_profile (default false, system/group/user scopes)
• Validation: reject observers when policy disabled; reject signing attempts by observers
• Exclude observers from signing status, envelope progress, sequential signing, and DocMDP signer counts
• Route observer notifications to validation view
• Require at least one signing participant when moving out of draft / requesting signatures
• Map OBSERVING (status 3) in signer summaries; defensive ParticipantRole::fromNullable()
• Unit and/or integration tests added – required for backend changes
• Capabilities updated (if applicable) – if adding/modifying Nextcloud capabilities
• Documentation updated (if applicable) - docs repository
• API documentation updated with the command composer openapi if necessary

🚧 Tasks

• Confirm no environment still depends on dropped participant_profile_id column (migration included)

✅ Checklist

• I have read and followed the contribution guide.
• OpenAPI specs and TypeScript types regenerated (composer openapi, npm run typescript:generate)
• Focused PHPUnit and Vitest suites pass locally
• PHP CS Fixer clean (composer cs:check)
• Conventional Commits with DCO sign-off on all commits

🤖 AI (if applicable)

• The content of this PR was partially or fully generated using AI

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 55.52147% with 145 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...rc/components/RightSidebar/RequestSignatureTab.vue	33.33%	56 Missing and 16 partials ⚠️
...kbench/settings/observer-profile/realDefinition.ts	44.11%	16 Missing and 3 partials ⚠️
src/components/validation/EnvelopeValidation.vue	77.27%	8 Missing and 2 partials ⚠️
src/views/Validation.vue	66.66%	7 Missing and 3 partials ⚠️
src/components/Signers/Signers.vue	70.37%	5 Missing and 3 partials ⚠️
...ngs/observer-profile/ObserverProfileRuleEditor.vue	56.25%	6 Missing and 1 partial ⚠️
src/components/Request/IdentifySigner.vue	50.00%	1 Missing and 4 partials ⚠️
src/components/validation/SignerDetails.vue	28.57%	4 Missing and 1 partial ⚠️
src/utils/participantRole.ts	73.33%	2 Missing and 2 partials ⚠️
src/components/Request/SignerSelect.vue	66.66%	1 Missing and 2 partials ⚠️
... and 2 more
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Files with missing lines	Coverage Δ
src/components/validation/SigningProgress.vue	76.28% <100.00%> (-0.19%)	⬇️
src/constants.js	100.00% <ø> (ø)
src/services/validationDocument.ts	75.70% <ø> (ø)
src/store/files.js	75.50% <100.00%> (+0.64%)	⬆️
...ttings/PolicyWorkbench/settings/realDefinitions.ts	100.00% <ø> (ø)
...omponents/validation/DocumentValidationDetails.vue	92.50% <92.85%> (-0.36%)	⬇️
src/utils/getSignRequestStatusText.ts	20.00% <0.00%> (-5.00%)	⬇️
src/components/Request/SignerSelect.vue	86.20% <66.66%> (-0.22%)	⬇️
src/utils/participantRole.ts	73.33% <73.33%> (ø)
src/components/Request/IdentifySigner.vue	80.83% <50.00%> (-2.50%)	⬇️
... and 7 more

... and 201 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vitormattos]

Please use participantRole as the source of truth for the role.

OBSERVING is a status created by this feature, so we do not need it as a legacy fallback. With the current code, inconsistent data such as participantRole: signer with status: OBSERVING is treated as an observer.

The backend already stores the explicit role. The frontend should not silently change the role based on status. Please update the related unit test too.

[vitormattos]

Please add one focused Playwright test for the observer workflow.

The PR changes many existing E2E tests, but none tests the new feature end to end.

The scenario should:

1. enable enable_observer_profile;
2. add one signer and one observer;
3. request signatures;
4. verify both roles are shown separately;
5. open the observer link;
6. verify the observer goes to validation and cannot enter the signing flow.

This will test the main business flow instead of only the individual frontend and backend pieces.

We also need similar scenario at integration tests with Behat to validate the API contract too.

[vitormattos]

Could we use a real SignRequest entity here instead of mocking __call()?

This test only needs entity data such as UUID, file ID, display name, and participant role. Using the real entity will make the test easier to read and less coupled to the entity magic methods.

The same approach can be used for the file entity if possible.