# Feature announcements ("Nouveautés") — what Fleet calls

The admin section "Nouveautés" (dadycar-admin-next) writes, targets and publishes announcements;
this backend decides who gets them. Fleet (fleet-react-app) draws them and reports what users did.
Everything below is under the Fleet auth (`auth.service`), open to every plan.

## GET /api/v1/fleet/announcements/active

What the current user should see now, already filtered (published, inside its dates, user in the
audience, not closed, finished, snoozed or over its impressions in this round, at most one modal a
day) and in the language Fleet shows: the `Accept-Language` Fleet sends with every call (`fr` or
`en`), else the account's (`language_id`, else `preferred_language`); French when the English text
is empty. The audience's "Langues" reads the account's. Ordered by priority, highest first. Read it
again on a page change: an announcement unpublished in the admin is no longer in it.

```json
{ "status": true, "message": "Annonces", "data": [{
  "id": 6, "key": "zones-de-georeperage", "round": 1, "format": "tour",
  "title": "Zones de géorepérage", "body": null, "badge_text": "Nouveau",
  "icon": "MapPin", "media_url": null, "media_alt": null,
  "cta_label": null, "cta_path": null,
  "page_key": "car-location", "page_path": "/fleet/car-location",
  "anchor_key": null, "target_sidebar_path": null, "placement": "auto", "widget_corner": "bottom_right",
  "steps": [{ "id": "12", "title": "Vos zones sur la carte", "subtitle": null, "body": "Affichez vos <b>zones</b>…",
              "icon": "MapPin", "media_url": null, "media_alt": null,
              "anchor_key": "map-zones-toggle", "placement": "bottom", "cta_label": null, "cta_path": null }],
  "rules": { "dismissible": true, "hide_after_page_visit": false },
  "state": { "impressions": 0, "step_reached": 0, "dismissed": false, "snoozed_until": null, "completed": false },
  "is_reminder": false
}]}
```

- `format`: badge, sidebar_spotlight, banner, modal, page_widget, tour. A reminder comes with
  `is_reminder: true` and the reminder's format (badge or banner).
- `page_path` may hold `:id` (a vehicle page): match it as a route pattern.
- `body` texts are restricted HTML: `<b>`, `<i>`, `<br>`, `<a href="/fleet/...">` only.
- `step_reached`: steps already passed, the step to resume on.

**Preview.** The admin opens Fleet at `<page>?announcement_preview=<token>`. Send that token as is:
`GET /active?announcement_preview=<token>` returns that announcement alone, whatever its status and
audience. Send no event while previewing. An expired or altered token answers 404.

## POST /api/v1/fleet/announcements/{id}/events

```json
{ "round": 1, "type": "seen", "step_id": "12", "anchor_key": "map-zones-toggle", "snooze_days": 3 }
```

| type | when | effect |
|---|---|---|
| `seen` | the announcement is drawn | one impression |
| `clicked` | its button is followed | for a format without steps, also completed |
| `dismissed` | the user closes it | not shown again this round |
| `snoozed` | "later", with `snooze_days` (1–30) | hidden until then |
| `step_seen`, `step_completed` | a step drawn / passed (`step_id` required) | passing the last step completes it |
| `completed` | the user reached the end | not shown again this round |
| `anchor_missing` | the element is not on the page (`anchor_key`, `step_id` when a step) | counted in the admin's statistics |
| `page_visited` | the user opened the announcement's page | hides it when `hide_after_page_visit` |
| `reminder_seen` | a reminder is drawn | counts towards `max_reminders` |

Send the `round` received from `/active`. `{"recorded": false}` means the event no longer counts
(an earlier round after a reset, an unpublished announcement, an unknown step). Throttled per user.
Events sent at the same time (a step passed and the next one seen) are all kept.

A badge or a pop-up on a menu entry lives in the menu, on every page (the page set never limits
it), is seen only once really on screen (not in the phone's closed menu) and is clicked only on the
entry itself (a click on its closed group just opens it). A tour step shows only next to its
element; one not on the page is passed over with `anchor_missing`.

## POST /api/v1/fleet/announcements/usage

`{ "event": "geofence_zone_created" }` when the user really does the action. It feeds adoption in
the statistics and stops the reminders. Events: `config/announcements.php`, `usage_events`.

## Anchors (where an announcement points)

- A menu entry is `sidebar.<page key>`: the sidebar item's path after `/fleet/`, lowercased, `/`
  read as `.` (`/fleet/car-location` → `sidebar.car-location`). Put
  `data-announcement-anchor="sidebar.<page key>"` on every sidebar item.
- A menu group (a sidebar section of several entries: « Véhicules », « Services »…) is
  `sidebar-group.<section id>`, on the group's header. Like a menu entry, it is offered on every
  page and to the menu formats (badge, pop-up on the menu).
- An element of a page is listed in `config/announcements.php` (`anchors`), its key equal to the
  element's `data-announcement-anchor` (or the `data-testid` it already carries). A new element
  is one line there and the attribute in Fleet. A tab drawn by `CustomTabs` gets
  `<anchorPrefix>-<tab key>` (the vehicle page: `vehicle-tab-<key>`).
- A page behind an id (`/fleet/employees/:id`: every employee page) is listed in `pages` with its
  `example` kind and `fallback` list: the admin's preview opens an example of the demo tenants,
  else the list. `page_path` keeps `:id`, which Fleet matches against any id.

## Admin side, to switch on

1. `php artisan migrate` (tables + the `feature_announcement` notification type).
2. `php artisan auth:add-announcements` (permissions `announcements.manage` and
   `announcements.publish`, granted to the internal super_admin; others from "Paramètres des rôles").
3. Admin: `NEXT_PUBLIC_ANNOUNCEMENTS_MOCK=false`.
4. Optional: `ANNOUNCEMENTS_POSTHOG_URL` (link shown in the statistics).

## Menu labels (« BETA »)

The admin's « Étiquettes du menu » sets a Fleet menu entry's status label: `GET /api/admin/announcements/menu-labels`
(the menu, section by section) and `PUT /api/admin/announcements/menu-labels/{sidebar item}` with
`{ "shown": true, "text": "V2" }` (`announcements.publish`; `text` 12 characters at most, « Beta » when empty). They
are the entry's `beta` and `special_label`, which Fleet already receives with its menu; a change clears every user's
copy of the menu, so Fleet shows it on its next page load, for every client, whatever the announcements flag.
