# Feature announcements ("Nouveautés") — admin specification V2 (single release)

**Replaces:** `feature-announcements-admin.md` (V1) and my earlier review/roadmap.
**Audience:** the admin developer (`dadycar-admin-next`: Next.js 16, React 19, Tailwind, shadcn) and the backend developer.
**Delivery:** **one release.** There is no MVP/phase 2/phase 3 split: the six formats, tours, statistics, reminders and notifications ship together. Build order is in section 12, but nothing is released until all of it works.
**Build approach:** the admin is built first on **mock data** (same repository pattern as the compliance page), then connected to the backend. Everything marked **NEW** or **FIXED** below is something V1 forgot or got wrong.

---

## 0. What changed from V1 (summary)

| # | Type | Change |
|---|---|---|
| 1 | FIXED | The main example (popover on "Bouton Zones") is now buildable: `tour` is in the release, and a **one-step tour is a first-class "info-bulle sur un élément"**. |
| 2 | FIXED | `page_widget` steps may point at an element (optional). `tour` steps must (required). One consistent rule, section 4.3. |
| 3 | FIXED | Statuses: stored `draft / published / archived`; **display states** `scheduled / live / ended` are derived from dates. Section 6. |
| 4 | FIXED | Per-step funnel is part of the release for both step formats. |
| 5 | NEW | **Edit rules once published**: what is locked, what is free, what needs a warning. Section 6.2. |
| 6 | NEW | **Missing catalogs** for the audience pickers (permissions, roles, companies, example vehicles). Section 9. |
| 7 | NEW | **Content limits per format** (characters, image size), image **alt text**, restricted rich text defined. Section 5. |
| 8 | NEW | **"Why isn't it shown?"** eligibility test for a chosen company/user. Section 7.4. |
| 9 | NEW | **Overlap warning** for modals and a **frequency summary** in the editor. Section 7.3. |
| 10 | NEW | **Reset = a new round**; statistics keep every round. Section 6.3. |
| 11 | NEW | **Success metric**: the product team picks the event that means "the feature is really used"; statistics show adoption, not only impressions. Section 8. |
| 12 | NEW | **Reminders** (feature still unused after N days) and **optional notification/e-mail** for major launches, in the same release. Section 8. |
| 13 | NEW | **History** (who created, edited, published, reset) and two permissions: `announcements.manage` and `announcements.publish`. Section 10. |
| 14 | NEW | **In-editor simulation** of every format, plus the real Fleet preview. Section 7.1. |
| 15 | NEW | Paris time zone handling, unsaved-changes guard, draft autosave, duplicate rules. Section 6 and 11. |

---

## 1. The system in one paragraph

The product team writes an announcement (badge, menu spotlight, banner, modal, step card or guided tour) in this admin section, checks who it will reach, previews it, and publishes or schedules it. The backend stores it and decides which Fleet users see it. Fleet shows it and reports what users did. The admin shows the funnel and whether the feature was actually adopted, and can remind people who haven't used it.

## 2. Vocabulary

| Term | Meaning |
|---|---|
| Announcement | One feature-launch message: format, FR/EN content, placement, audience, schedule, rules. |
| Format | `badge`, `sidebar_spotlight`, `banner`, `modal`, `page_widget` (floating card with steps), `tour` (steps pointing at elements; 1 step = info-bulle). |
| Anchor | Stable name of an element of a screen, declared once in the Fleet code (e.g. `sidebar.car-location`, `map.zones-button`). |
| Audience | Who may see it: plans, capabilities, permissions, roles, companies, languages, account age. |
| Round | One exposure cycle. Publishing starts round 1; a **reset** starts a new round. |
| Display state | `draft`, `scheduled`, `live`, `ended`, `archived` (derived, section 6). |
| Success event | The event that proves the feature is used (picked from a catalog). |

## 3. Formats and when to use them (shown in the editor)

| Format | Use it for | Placement |
|---|---|---|
| `badge` | Small feature: a "Nouveau" mark on a menu entry or an element. | element required |
| `sidebar_spotlight` | A feature in a new/moved menu entry: popover on that entry. | menu entry required |
| `banner` | Medium feature or news for everybody: dismissible bar at the top of a page. | page optional |
| `modal` | **Major launch only.** Max one per user per day (Fleet enforces it). | page optional |
| `page_widget` | Explain a page in 2–4 steps in a floating card. | page required |
| `tour` | Guided steps pointing at precise buttons. **One step = an info-bulle on one element.** | page + element on every step |

Good practices shown as short hints in the editor: match the format to the importance; cap the frequency; target users who can use the feature; adoption is a sequence (awareness → education → reinforcement); measure usage, not impressions.

## 4. Placement: page, element, position

The admin never types a URL or technical name: everything comes from lists prepared by developers.

### 4.1 Three choices, in this order
1. **Page** — `GET /pages` (readable names). "Toutes les pages" allowed for `banner` and `modal`.
2. **Element** — `GET /anchors?page=<page_key>`: only the elements of the chosen page, **plus the menu entries (group "Menu"), always listed**. Changing the page clears an element that is not on the new page.
3. **Position** — depends on the format; hidden when there is nothing to choose.

### 4.2 Position by format
| Format | Page | Element | Position choices |
|---|---|---|---|
| `badge` | optional | required (menu entry or element) | none |
| `sidebar_spotlight` | none | required (menu entry) | `right` (default), `bottom` |
| `page_widget` | required | none for the card; optional per step | card corner: `bottom_right` (default), `bottom_left` |
| `banner` | optional | none | fixed: top of the page |
| `modal` | optional | none | fixed: centre |
| `tour` | required | required on every step | per step: `auto` (default), `top`, `right`, `bottom`, `left` |

### 4.3 Step rule (FIXED)
`page_widget`: 2–4 steps, element **optional** per step (highlights it when set). `tour`: 1–8 steps, element **required** per step. A one-step `tour` is presented in the editor as **"Info-bulle sur un élément"**.

### 4.4 Editor behaviour
Show only the choices of the selected format; keep values that still apply and clear the others when the format changes; for a page with an id ("Fiche véhicule") ask for an **example vehicle** (preview only, never stored); under the element picker show: "Si l'élément n'est pas affiché pour un utilisateur (droits, offre), l'annonce ne lui est pas montrée."

### 4.5 The main example, built in the editor
| Field | Value |
|---|---|
| Format | Tour with 1 step ("Info-bulle sur un élément") |
| Page | Localisation des véhicules |
| Element | Bouton Zones |
| Position | `bottom` |
| Text | "Affichez vos zones de géorepérage sur la carte" |
| Audience | plans with the telematics capability; users who can view the map |
| Success event | `geofence_zone_created` |

## 5. Content fields and limits (NEW)

| Field | Stored in | Rules |
|---|---|---|
| Format | `format` | one of the six |
| Key | `key` | slug from the FR title; unique; editable until the first publish |
| Title FR/EN | `title` | FR required; ≤ 60 chars |
| Text FR/EN | `body` | restricted rich text: **bold, italic, line break, internal link** only; ≤ 160 (banner), ≤ 400 (modal, step, widget). Sanitised by the backend with the same whitelist. |
| Badge text FR/EN | `badge_text` | optional, ≤ 12 chars ("Nouveau", "Pro") |
| Category | `category` | optional |
| Icon | `icon` | fixed list, no upload |
| Image | `media_url` | upload via `POST /media`; jpg/png/webp; ≤ 2 MB; 16:9 recommended, min width 800 px |
| **Image alt text FR/EN** | `media_alt` | **NEW, required when an image is set** (accessibility) |
| Button text FR/EN, link | `cta_label`, `cta_path` | link = internal path `/fleet/...` only |
| Page / menu entry / element / position / corner | `page_key`, `target_sidebar_path`, `anchor_key`, `placement`, `widget_corner` | section 4 |
| Steps | `announcement_steps` | per step: title, subtitle, text, icon, image + alt, element, position, button |
| Audience | `audience` (json) | section 7.2 |
| Schedule | `starts_at`, `ends_at`, `priority` | Europe/Paris |
| Rules | `rules` (json) | dismissible (banner/widget default yes; modal must have a close control), max impressions (default 3), hide once the page was visited, account age min/max |
| **Success event** | `success_event` | **NEW**, from `GET /usage-events` |
| **Reminder** | `reminder` (json) | **NEW**, section 8.2 |
| **Notification** | `notify` (json) | **NEW**, section 8.3 |

FR is required, EN optional (Fleet falls back to FR; the editor shows "Repli sur le FR" next to an empty EN field). Validation errors come from the API (`422` with field errors) and show under each field.

## 6. States, lifecycle, editing

### 6.1 Stored status and display state
Stored: `draft`, `published`, `archived`. Display states derived from dates:

| Display state | Rule |
|---|---|
| Brouillon | `draft` |
| Programmée | `published` and `starts_at` in the future |
| En ligne | `published` and now within `starts_at`–`ends_at` |
| Terminée | `published` and `ends_at` passed (no action needed; can be archived) |
| Archivée | `archived` |

| Display state | Actions |
|---|---|
| Brouillon | edit, preview, publish, duplicate, delete |
| Programmée | edit, preview, unpublish |
| En ligne | edit (limited), **reset**, unpublish, archive, statistics |
| Terminée | duplicate, archive, statistics |
| Archivée | duplicate, statistics |

Only a **draft** can be deleted. **Duplicate** creates a draft with a new key and "(copie)" appended to the title; nothing from statistics is copied.

### 6.2 Editing a live announcement (NEW)
| Field group | Rule |
|---|---|
| `key`, `format` | locked after the first publish |
| Number and order of steps | locked after the first publish (users already have a step reached) |
| Texts, images, CTA, icons, step texts | free |
| Step element / position | free, with a warning "vérifiez l'aperçu" |
| Schedule, priority, rules | free |
| Audience | free, with a confirmation that shows the **new "N users match"** and the change (+/– users) |

If a locked change is really needed: duplicate, publish the copy, archive the old one.

### 6.3 Reset = a new round (NEW)
"Reset" shows the announcement again to everybody in its audience. It asks for a confirmation that states the number of users who will see it again. Statistics are kept **per round** (round selector) with an "all rounds" total. History records who reset and why (free-text reason, optional).

### 6.4 Publish validation
Blocks publishing with an error list when: FR title/text missing; required placement missing for the format; image without alt text; CTA not an internal path; step rules of 4.3 broken; audience empty (unless "tous les utilisateurs" is explicitly confirmed); `ends_at` before `starts_at`. Warns (does not block) when "N users match" is 0 or is everybody, or when a modal overlap exists (7.3).

### 6.5 Time zone
All dates are **Europe/Paris**, displayed and entered in Paris time whatever the browser time zone, sent as ISO 8601 with offset.

## 7. Editor screens

### 7.1 Screens
| Screen | Content |
|---|---|
| **List** | Title, format, display state, dates, audience summary, seen / clicked / completed; filters (state, format, dates), search; actions per 6.1. |
| **Editor** | Sections: 1 Format (cards with description) · 2 Content FR/EN · 3 Placement · 4 Steps · 5 Audience · 6 Schedule & rules · 7 Success, reminder, notification. Sticky bar: Save draft / Preview / Publish. Draft **autosave** and an unsaved-changes guard. |
| **Side panel** | Tabs: **Simulation** · **Audience** · **Historique**. |
| **Statistics** | Section 8.1. |

**Simulation (NEW):** a live rendering of the announcement in the admin's own design for every format (badge dot on a mock menu, spotlight popover, banner, modal, step card, tour tooltip), labelled "Aperçu approximatif — le rendu réel est dans Fleet". Updates as the form changes; switches FR/EN.

**Fleet preview:** `POST /{id}/preview-token` (with the example vehicle when needed) → opens Fleet in a new tab at `preview_url` with `?announcement_preview=<token>`. Nothing is recorded; the token is short-lived (30 min). Needs the Fleet base URL in `NEXT_PUBLIC_FLEET_URL`.

### 7.2 Audience
Plans · capabilities required / **missing** (upsell) · permissions · roles · companies include / exclude (searchable) · languages (`fr`, `en`) · new users only · account age. Live **"N users match"** (`GET /{id}/audience-count`, refreshed on change, debounced). Warn at 0 or everybody. Upsell announcements are supported through "capability missing"; their CTA should point to the plans page.

### 7.3 Frequency and overlap (NEW)
Under the rules, a summary sentence: "Max 3 affichages par utilisateur, 1 modal par jour." When another **modal** is published/scheduled with an overlapping period and audience, show a warning listing it ("Seule une modal par jour s'affichera : laquelle passe d'abord dépend de la priorité"). Priority is explained in a tooltip.

### 7.4 "Why isn't it shown?" (NEW)
A small tool in the Audience tab: pick a **company** (and optionally a user) → `GET /{id}/eligibility?company_id=&user_id=` returns `{eligible, reasons[]}`, e.g. "Plan Gratuit non inclus", "Capacité télématique manquante", "Compte créé il y a 400 jours (max 90)", "Hors période". This is the answer to "the client says they never saw it".

## 8. Measure, remind, notify (all in this release)

### 8.1 Statistics
`GET /{id}/stats?round=`:
- **Funnel:** eligible → seen → clicked → completed; **dismissed** and dismiss rate. Definitions: *eligible* = users matching the audience now; *seen* = at least one impression; *clicked* = clicked the CTA; *completed* = finished the steps / reached the last step.
- **Per-step funnel** for `page_widget` and `tour`.
- **"Element not found"** count (`anchor_missing`) per step, with a warning badge to detect a broken placement.
- **Adoption (NEW):** users who triggered the **success event** after seeing the announcement versus eligible users who did not see it, and the adoption rate over time (chart). Link to the PostHog dashboard (configurable URL).
- Round selector and "all rounds".

### 8.2 Reminder (NEW)
`reminder: {enabled, after_days, format: badge|banner, max_reminders}`. If the user saw the announcement and **did not trigger the success event** after `after_days` days, Fleet shows the reminder (default: a banner), at most `max_reminders` times. Preview and count of users concerned ("N utilisateurs seraient relancés").

### 8.3 Notification (NEW)
`notify: {enabled, channels[in_app,email], message_fr, message_en}`. For major launches: sends one notification/e-mail through the existing notification system at publication. The editor shows the number of recipients and asks for an explicit confirmation before publishing.

## 9. API used

All under `/api/admin/announcements`.

| Route | Use |
|---|---|
| `GET /` | List: filters (state, format, dates), search, pagination, aggregated counts |
| `GET /{id}`, `POST /`, `PUT /{id}` | Load / create / save |
| `POST /{id}/publish`, `/unpublish`, `/archive`, `/duplicate`, `/reset` | Lifecycle (`reset` accepts `{reason?}`) |
| `DELETE /{id}` | Drafts only |
| `GET /{id}/audience-count` | "N users match" (also accepts an unsaved audience in the body for live count) |
| `GET /{id}/eligibility` | **NEW** "Why isn't it shown?" |
| `GET /{id}/stats?round=` | Statistics incl. adoption |
| `GET /{id}/history` | **NEW** Who did what |
| `POST /{id}/preview-token` | Preview (`{example_vehicle_id?}`) |
| `POST /media` | Image upload |
| `GET /pages`, `/anchors?page=`, `/sidebar-paths` | Placement pickers |
| `GET /plans`, `/capabilities` | Audience pickers |
| `GET /permissions`, `/roles` | **NEW** audience pickers |
| `GET /example-vehicles?search=` | **NEW** vehicles of the demo company, for the preview |
| `GET /usage-events` | **NEW** catalog for the success event |
| Companies picker | existing `GET /api/admin/companies/options` |

Errors: `422` with `{errors: {field: [messages]}}`; envelope `{status, message, data}`; paginated shape as the other admin lists.

## 10. Permissions and history (NEW)
- `announcements.manage`: see the section, create, edit, preview, duplicate, delete drafts.
- `announcements.publish`: publish, unpublish, schedule, reset, archive, send notifications. This answers "who writes and who publishes": customer success can draft, product publishes.
- Both seeded by the backend and shown in the internal-roles matrix. If only one exists at first, the admin falls back to it.
- **History** records create / edit (changed fields) / publish / unpublish / reset (with reason) / archive, with who and when.

## 11. Quality requirements
Server-side validation messages under each field; keyboard-accessible pickers and step reorder (up/down buttons, no drag-and-drop dependency); every image has alt text; FR/EN i18n for the admin UI itself; responsive layout; follows the admin's own design (Tailwind/shadcn), not Fleet's.

## 12. Build plan (one release, built on mock data first)

Work packages in order. Each one is demoable, but **nothing ships before WP10 is done**.

| WP | Content | Size |
|---|---|---|
| 1 | Foundation: entities, constants (format × field matrix, position matrix, limits), repository interface + mock + impl skeleton, DI, `NEXT_PUBLIC_ANNOUNCEMENTS_MOCK`, i18n FR/EN, nav entry (category "Produit"), route gate | M |
| 2 | List: table, display states, filters, search, pagination, row actions with confirmations | M |
| 3 | Editor core: format cards, per-format fields, FR/EN content, restricted rich text, icon picker, image + alt, CTA validation, key slug, field errors | L |
| 4 | Placement: page → element → position cascade, menu group, clear-on-change, example vehicle | M |
| 5 | Steps editor: widget and tour rules (4.3), up/down reorder, per-step element/position/button | M |
| 6 | Audience builder, live count, eligibility tool, schedule (Paris), priority, rules, overlap warning | L |
| 7 | Simulation of all formats + Fleet preview button/token | L |
| 8 | Lifecycle and editing rules: publish validation, locked fields, reset (rounds), history tab, autosave + unsaved guard | M |
| 9 | Statistics: funnel, per-step, anchor-missing, adoption chart, round selector, PostHog link | M |
| 10 | Success event, reminder, notification (with recipient count + confirmation); polish, accessibility pass, lint/typecheck, screenshots, README | L |
| 11 | Connect: reconcile with the backend document §4.5, switch the flag, replace temporary permission, run the acceptance checklist on the real API | M |

Estimate for WP1–WP10 on mock data: about **14–16 working days**; WP11 depends on the backend.

### Mock data (deterministic, persisted in localStorage)
Eight announcements covering every format and display state (including a 1-step "Zones de géorepérage" tour as the main example and a 3-step widget with per-step stats), ~8 pages with their elements (one page needing an id), menu entries, plans, capabilities, permissions, roles, 12 companies, example vehicles, usage events. "N users match" and eligibility reasons are computed from the audience over a fake population; statistics are generated so the funnel is always consistent (eligible ≥ seen ≥ clicked ≥ completed). The mock returns 422-shaped errors.

## 13. Acceptance criteria
1. A product person creates, previews and publishes an announcement without help.
2. The editor shows only the fields that make sense for the chosen format; the format → fields matrix is data, not scattered conditions.
3. FR required, EN optional with a visible fallback hint.
4. Links are internal Fleet paths only; pages, elements, menu entries, events and companies come from pickers.
5. The element list shows the elements of the chosen page plus the menu; changing the page clears an element not on it.
6. Position choices follow section 4.2; fixed positions are not offered.
7. **The main example (info-bulle on "Bouton Zones") can be created end to end.**
8. A page with an id asks for an example vehicle and the preview opens it.
9. "N users match" updates with the audience; 0 and everybody warn.
10. "Why isn't it shown?" explains the result for a chosen company/user.
11. Overlapping modals produce a warning.
12. Locked fields are locked after publish; audience change shows the user delta.
13. Reset asks for confirmation with the user count and creates a new round; statistics show each round.
14. Statistics show the funnel, the per-step funnel, "element not found" and adoption of the success event.
15. Reminder and notification can be configured, with recipient counts and a confirmation.
16. Two permissions behave as described; history lists every action.
17. Image without alt text, over-length text and invalid links are refused with field errors.
18. All dates are Europe/Paris.

## 14. What the backend document must add (hand this list to the backend developer)
New fields on `announcements`: `media_alt` (FR/EN), `success_event`, `reminder` (json), `notify` (json), `round`. Per-round statistics and a statistic of adoption via the success event. Endpoints: `eligibility`, `history`, `permissions`, `roles`, `example-vehicles`, `usage-events`, `DELETE` (drafts), live `audience-count` from an unsaved audience. Permission `announcements.publish`. Server-side sanitising of rich text with the whitelist of section 5, limits of section 5, and the locked-field rules of 6.2. Reminder and notification delivery. Display states derived from dates (not stored).

## 15. Remaining open questions (defaults used until answered)
| Question | Default used |
|---|---|
| Approval step before publishing | None; the `announcements.publish` permission is the control |
| Announcement for one client only | Yes, through "companies include" |
| Upsell announcements | Yes, through "capability missing" |
| Caps | 1 modal/day, 3 impressions per user |
| Reminder default | after 7 days, banner, max 2 |
