docs: add pre-request with magic link (#759)

Author: avine

client/src/app/request-feedback/request-feedback.component.ts

@@ -1,3 +1,4 @@
+import { APP_BASE_HREF } from '@angular/common';
 import { Component, DOCUMENT, ViewEncapsulation, inject } from '@angular/core';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { NonNullableFormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
@@ -11,6 +12,7 @@ import { MatSlideToggleModule } from '@angular/material/slide-toggle';
 import { MatTooltipModule } from '@angular/material/tooltip';
 import { ActivatedRoute, Router } from '@angular/router';
 import { concatMap, from, toArray } from 'rxjs';
+import { environment } from '../../environments/environment';
 import { AuthService } from '../shared/auth';
 import { MultiAutocompleteEmailComponent } from '../shared/autocomplete-email';
 import { ConfirmBeforeSubmitDirective } from '../shared/confirm-before-submit';
@@ -57,6 +59,8 @@ import {
 export class RequestFeedbackComponent {
   private document = inject(DOCUMENT);
 
+  private appBaseHref = inject(APP_BASE_HREF);
+
   private router = inject(Router);
 
   private activatedRoute = inject(ActivatedRoute);
@@ -187,11 +191,21 @@ export class RequestFeedbackComponent {
     this.feedbackService.preRequestToken({ message, shared }).subscribe(({ token }) => {
       this.navigateToSuccess({
         method: 'generate',
-        magicLink: `${this.document.location.origin}/pre-request/token/${token}`,
+        magicLink: this.buildMagicLink(token),
       });
     });
   }
 
+  private buildMagicLink(token: string) {
+    // IMPORTANT NOTE:
+    // The magic link does not contain the locale.
+    // The redirection to `/fr` or `/en` occurs when the colleague visits the magic link page (see `src/404.html` for details).
+    // However, since this redirection is not functional in the `dev-local` environment, the locale is explicitly added only in this case.
+    const locale = environment.alias === 'dev-local' ? this.appBaseHref : '/';
+
+    return `${this.document.location.origin}${locale}pre-request/token/${token}`;
+  }
+
   private navigateToSuccess(state: RequestFeedbackSuccess) {
     this.router.navigate(['success'], { relativeTo: this.activatedRoute, state });
   }

docs-source/docs/business-cases/pre-request-feedback.md

@@ -0,0 +1,113 @@
+# Pre-request feedback with magic link
+
+## User story
+
+As a Zenika employee, I would like to request feedback from colleagues when I don't know their email addresses upfront. Instead of specifying individual emails, I can generate a shareable "magic link" that colleagues can use to provide their email address and trigger a feedback request.
+
+This is particularly useful when:
+
+- I want to share the request in a Slack channel or Teams group
+- My colleagues' company blocks emails sent via Mailgun. However, they can still give me feedback using their personal email addresses, which I don't know in advance.
+
+Once a colleague uses the magic link and provides their email, they receive a feedback request email just like in the standard feedback request workflow.
+
+## Technical specifications
+
+Be sure to read [Request feedback](./request-feedback) first, as this feature is an enhancement of that workflow.
+
+### Magic link generation workflow
+
+1. The requester (authenticated user) navigates to `/request`
+2. Selects **"With a magic link"** method
+3. Fills and Submits the form (the recipients field is disabled for this method)
+4. Client calls `POST /feedback/pre-request/token`
+5. Server creates a document in the `feedbackPreRequestToken` collection and returns `{ token: string }`
+6. Client navigates to the success page displaying the magic link
+
+The requester can copy this link and share it through any channel (Slack, Teams, email, etc.).
+
+### Firestore schema
+
+A document is added in the `feedbackPreRequestToken` collection to store magic link tokens:
+
+```ts
+const preRequestToken: FeedbackPreRequestToken = {
+  receiverEmail: 'pinocchio@zenika.com', // Who will receive the feedback
+  message: 'Hi team, please share your feedback...', // Encrypted
+  shared: true, // Whether to share with manager
+  expiresAt: 1711662999463, // Timestamp
+  usedBy: ['gimini@gmail.com', 'gepetto@gmail.com'], // Emails that used this token
+};
+```
+
+- The document ID is the token itself (auto-generated by Firestore).
+- The `usedBy` array tracks which emails have already used this token
+- Each use of the token triggers a separate feedback request
+
+### Magic link format
+
+The magic link format is: `{origin}/pre-request/token/{token}`
+
+**Example:**
+
+```txt
+https://feedzback.znk.io/pre-request/token/abc123xyz
+```
+
+The magic link does not contain the locale.
+The redirection to `/fr` or `/en` occurs when the colleague visits the magic link page (see `src/404.html` for details).
+
+However, since this redirection is not functional in the `dev-local` environment, the locale is explicitly added only in this case.
+
+**Example in `dev-local` environment:**
+
+```txt
+https://feedzback.znk.io/fr/pre-request/token/abc123xyz
+```
+
+### Magic link usage workflow
+
+When a colleague accesses the magic link:
+
+1. The colleague (not authenticated) visits `/pre-request/token/{token}`
+2. The colleague's browser redirects to the appropriate locale (example: `/fr/pre-request/token/{token}`)
+3. Client calls `GET /feedback/check-pre-request/{token}` to validate the token
+4. If valid, the page displays the details of the pre-request and a form field allowing the colleague to enter their email address
+5. The colleague enters their email and submits
+6. Client calls `POST /feedback/pre-request/email` with `{ token, recipient }`
+7. Server validates the token and email, then:
+   - Adds the email to the `usedBy` array in `feedbackPreRequestToken` document
+   - Triggers the standard feedback request workflow:
+     - Creates `feedback` and `feedbackRequestToken` documents
+     - Sends a feedback request email to the colleague
+8. Client navigates to a success page confirming the email was sent
+
+From this point forward, the flow is identical to the standard [Reply to feedback request](./reply-to-feedback-request) workflow.
+
+### Token constraints
+
+- **Expiration** configured via `FEEDBACK_PRE_REQUEST_EXPIRATION_IN_DAYS` constant (3 days)
+- **Maximum uses** configured via `FEEDBACK_PRE_REQUEST_MAX_USES` constant (10 uses per token)
+
+When a colleague attempts to use a magic link, the following checks are performed:
+
+| Validation       | Error Type               | Description                                     |
+| ---------------- | ------------------------ | ----------------------------------------------- |
+| Token exists     | `token_invalid`          | The token doesn't exist in the database         |
+| Not expired      | `token_expired`          | The current time exceeds `expiresAt`            |
+| Under max uses   | `token_max_uses_reached` | The `usedBy` array length has reached the limit |
+| Email not used   | `recipient_already_used` | The email is already in the `usedBy` array      |
+| Not self-request | `recipient_forbidden`    | The email matches the `receiverEmail`           |
+
+If any validation fails, a `BadRequestException` or `ForbiddenException` is thrown with the corresponding error type.
+
+## Links
+
+- **Client**
+  - [`RequestFeedbackComponent`](https://github.com/Zenika/feedzback/blob/main/client/src/app/request-feedback/request-feedback.component.ts)
+  - [`PreRequestFeedbackComponent`](https://github.com/Zenika/feedzback/blob/main/client/src/app/pre-request-feedback/pre-request-feedback.component.ts)
+- **Server**
+  - [`FeedbackController`](https://github.com/Zenika/feedzback/blob/main/server/src/feedback/feedback.controller.ts)
+    - `preRequestToken` - Creates pre-request token
+    - `checkPreRequest` - Validates token and returns details
+    - `preRequestEmail` - Processes email submission and triggers feedback request

docs-source/sidebars.ts

@@ -10,6 +10,7 @@ const sidebars: SidebarsConfig = {
       label: 'Business cases',
       items: [
         'business-cases/request-feedback',
+        'business-cases/pre-request-feedback',
         'business-cases/reply-to-feedback-request',
         'business-cases/give-spontaneous-feedback',
         'business-cases/feedback-draft',

docs/404.html

@@ -5,8 +5,8 @@
 <meta name="generator" content="Docusaurus v3.9.2">
 <title data-rh="true">Page Not Found | FeedZback</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://feedzback.znk.io/feedzback/404.html"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_tag" content="default"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:docusaurus_tag" content="default"><meta data-rh="true" property="og:title" content="Page Not Found | FeedZback"><link data-rh="true" rel="icon" href="/feedzback/img/favicon.svg"><link data-rh="true" rel="canonical" href="https://feedzback.znk.io/feedzback/404.html"><link data-rh="true" rel="alternate" href="https://feedzback.znk.io/feedzback/404.html" hreflang="en"><link data-rh="true" rel="alternate" href="https://feedzback.znk.io/feedzback/404.html" hreflang="x-default"><link rel="alternate" type="application/rss+xml" href="/feedzback/blog/rss.xml" title="FeedZback RSS Feed">
 <link rel="alternate" type="application/atom+xml" href="/feedzback/blog/atom.xml" title="FeedZback Atom Feed"><link rel="stylesheet" href="/feedzback/assets/css/styles.acc3dc83.css">
-<script src="/feedzback/assets/js/runtime~main.acc19b4f.js" defer="defer"></script>
-<script src="/feedzback/assets/js/main.62bfbbe3.js" defer="defer"></script>
+<script src="/feedzback/assets/js/runtime~main.c7d965f2.js" defer="defer"></script>
+<script src="/feedzback/assets/js/main.1fecb4e7.js" defer="defer"></script>
 </head>
 <body class="navigation-with-keyboard">
 <svg style="display: none;"><defs>