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.49296% with 158 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 ⚠️
src/components/Request/IdentifySigner.vue	48.71%	10 Missing and 10 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/utils/participantRole.ts	73.33%	2 Missing and 2 partials ⚠️
src/components/Request/SignerSelect.vue	66.66%	1 Missing and 2 partials ⚠️
src/components/validation/SignerDetails.vue	57.14%	3 Missing ⚠️
... 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.60% <ø> (-0.10%)	⬇️
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/components/validation/SignerDetails.vue	44.55% <57.14%> (+4.68%)	⬆️
src/utils/participantRole.ts	73.33% <73.33%> (ø)
... 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]

If possible, could you also add a few screenshots to the PR description showing the observer flow?

It would be useful to show:

• the Add menu with Signer and Observer;
• the Signers and Observers sections;
• the validation page with an observer.

Also, sorry for reviewing this PR while it is still a draft. I added the comments now only to help keep the work close to the expected flow and avoid bigger changes later.

For the next review, it is better to add me as a reviewer and request the review when the PR is ready and is no longer a draft. After pushing new changes, when the PR is ready for review again, use the GitHub option to request my review again. This makes it clear when a new review is needed.

[lfals]

If possible, could you also add a few screenshots to the PR description showing the observer flow?

It would be useful to show:

• the Add menu with Signer and Observer;
• the Signers and Observers sections;
• the validation page with an observer.

Also, sorry for reviewing this PR while it is still a draft. I added the comments now only to help keep the work close to the expected flow and avoid bigger changes later.

For the next review, it is better to add me as a reviewer and request the review when the PR is ready and is no longer a draft. After pushing new changes, when the PR is ready for review again, use the GitHub option to request my review again. This makes it clear when a new review is needed.

No problem, I left it as a draft after the changes you requested. I was fixing the tests that broke. I'm going to add the observer flow and let you know when it's ready for review.

@vitormattos

[vitormattos]

Only a small change:

At file appinfo/info.xml, change from:

16.0.0-dev.1

to:

16.0.0-dev.2

This will make all environments of all developers to run the migration because will identify that the version was changed.

[vitormattos]

Could you also check this?

It would be useful to show:

• the Add menu with Signer and Observer;
• the Signers and Observers sections;
• the validation page with an observer.

[vitormattos]

I found another case during manual testing.

I created a signature request with one signer while the Observer policy was disabled. Then I enabled the Observer policy in Administration Settings and opened the same request again.

The UI correctly showed Add → Observer, but saving the observer returned:

Observer participants are not enabled

This happens because the frontend uses the current policy, while the backend keeps the old false value from the file snapshot.

I think the expected behavior should be:

1. If an existing request has Observer disabled and the current policy becomes enabled, Observer can be added while the request can still be edited.
2. After an Observer is added to this request, disabling the global policy later must not remove Observer from this existing flow. It should still be possible to keep and add observers to this request.
3. New requests should continue to use the current policy value.

The saved policy state may need to move from false to true when Observer is first added to an existing request. Once enabled for that request, it should stay enabled for this flow.

There is also a frontend error handling problem in this case. The API returned HTTP 422 with the message Observer participants are not enabled, but the UI did not show this message.

IdentifySigner.vue should show the error message returned by the API when saving a participant fails, instead of losing it in the catch.

Please add regression tests for both parts:

• backend/integration: create a request with Observer disabled, enable the policy, add an observer, disable the policy again, and confirm that the same request can still use observers;
• frontend: make the participant save request fail with a 422 OCS response and confirm that the API error message is shown to the user and the participant modal stays open.

[vitormattos]

I also found a frontend issue during manual testing.

Observers are shown in the Signature positions screen and can be selected to add a visible signature position.

This is in src/components/Request/VisibleElements.vue, where both sidebarSigners and pdfEditorSigners use all participants without filtering by role.

Only participants with the signer role should be available in this screen.

Please filter observers from both lists and add a frontend test with one signer and one observer. The test should confirm that only the signer is shown.

[vitormattos]

I found a problem during manual testing with mixed identify methods.

I enabled Account and Email identification, added the admin as a signer using Account, and added an observer using Email.

The signature request was created, but the observer never received the email with the link to view the document.

The current Playwright test uses Email for both the signer and the observer, so this case is not covered.

We should cover this at different levels:

• integration/Behat: create a request with an Account signer and an Email observer and confirm that the observer sign request is created with the correct role and notification state;
• PHPUnit: confirm that an observer with Email identification is marked for notification and that the mail listener sends the observer email with the validation link;
• Playwright: confirm the full user flow, including that the external observer receives the email, opens the validation page without an account, and cannot sign.

This will also define the expected journey for an observer that does not have a Nextcloud account.

[vitormattos]

Observers also need a way to receive the notification again.

At the moment canSendReminder() always returns false for observers. In the UI, an observer can only have the message edited or be deleted, but there is no action to send the document link again.

The action does not need to be called Send reminder, because the observer is not waiting to sign. Something like Send notification can be clearer for observers.

The notification should use the observer validation link and include the custom message when it is set.

Add frontend coverage for this action and backend coverage to confirm that sending the notification for an observer uses the validation link.

[vitormattos]

The same rule also needs backend protection.

lib/Service/FileElementService.php currently accepts the signRequestId for a visible element without checking if this participant can sign.

The API must reject a visible signature element when the signRequestId belongs to an observer.

Please add a unit test for this validation and an integration/Behat scenario that sends an observer signRequestId and confirms that the API rejects it. Keep a signer case to confirm the normal flow still works.