mokosh/.planning/intel/requirements.md

# Functional Requirements (synthesized from SPEC §4–§7, acceptance §10)

The SPEC `Тз расширение фаза1.md` does not formally label itself as a PRD set,
but sections 4–7 describe user-visible / functional behavior and §10 lists
acceptance criteria. Per the orchestrator's instruction, these are extracted
here as requirements with IDs derived `REQ-{slug}`.

Source key:
- `SPEC §X` → `Тз расширение фаза1.md`, section X
- `DOC` → `README.md`

All requirements below are sourced from the SPEC; the DOC is a confirming
source unless noted otherwise.

---

## REQ-video-ring-buffer

- Source: `Тз расширение фаза1.md` §4.1
- Scope: Continuous video capture of the active tab
- Description: The extension MUST maintain an in-memory ring buffer containing
  the most recent 30 seconds of video from the currently active browser tab.
- Acceptance criteria (from SPEC §10):
  - Video buffer runs continuously on any tab.
  - The buffer never holds more than 30 seconds of footage.
  - The bundled `last_30sec.webm` from the exported archive plays back in a
    browser.
- Technical bindings (see decisions.md):
  - DEC-003 — `chrome.tabCapture.capture()` for acquisition
  - DEC-003 — `video/webm; codecs=vp9` @ 400 000 bps, 2000 ms chunks
  - DEC-009 — header chunk retained indefinitely
- Confirming source: `README.md` §"Использование" and §"Кольцевой буфер".

---

## REQ-rrweb-dom-buffer

- Source: `Тз расширение фаза1.md` §4.2
- Scope: DOM event recording
- Description: The extension MUST record DOM events via rrweb over a rolling
  10-minute window from the active page, capped at 5 000 events.
- Acceptance criteria (from SPEC §10):
  - rrweb records DOM events without errors on typical pages (forms, tables,
    modal windows).
- Technical bindings:
  - DEC-004 — rrweb library
  - DEC-004 — `maskInputSelector` for `input[type=password]` and
    `[data-sensitive="true"]`
  - SPEC §8 — 5 000-event cap; oldest dropped on overflow
  - SPEC §4.2 — 10-minute TTL purge every 60 s
- Confirming source: `README.md` §"Кольцевой буфер".

---

## REQ-user-event-log

- Source: `Тз расширение фаза1.md` §4.3
- Scope: User and runtime event logging
- Description: The extension MUST log user and runtime events over a rolling
  10-minute window.
- Captured event types (SPEC §4.3):
  - `click` — click on any element; records `target` selector and element text
  - `input` — field value change (passwords excluded)
  - `navigation` — `popstate`, `hashchange`, page transitions
  - `js_error` — `window.onerror`, `window.onunhandledrejection`
  - `network_error` — `fetch` / `XMLHttpRequest` with response code `>= 400`
- Log entry schema (SPEC §4.3, verbatim):
  ```json
  {
    "timestamp": 1716800000000,
    "type": "click | input | navigation | error | network",
    "target": "CSS-селектор элемента",
    "value": "текст/значение (маскируется для паролей)",
    "url": "текущий URL",
    "meta": {}
  }
  ```
- Acceptance criteria (from SPEC §10):
  - Event log captures clicks, navigation, and network errors.
  - Passwords do not appear in either the event log or rrweb snapshots.
- Confirming source: `README.md` §"Записываемые события".

---

## REQ-screenshot-on-export

- Source: `Тз расширение фаза1.md` §4.4, §5
- Scope: One-shot visual capture
- Description: At the moment the user clicks "Save archive", the extension MUST
  capture a PNG screenshot of the active tab via `chrome.tabs.captureVisibleTab`
  and include it as `screenshot.png` in the archive.
- Technical binding: DEC-008.

---

## REQ-popup-ui

- Source: `Тз расширение фаза1.md` §5
- Scope: User-facing trigger
- Description: The extension MUST expose a minimal popup with a single button
  labeled "Сохранить отчёт об ошибке" and a sub-label "Последние 30 сек видео
  + 10 мин лога".
- Button state machine (SPEC §5):
  - `idle` → `Сохраняю...` → `Готово! ✓` → `idle` (after 3 s)
- On-click behavior (SPEC §5):
  1. Capture screenshot of active tab.
  2. Request video buffer + event log from Service Worker.
  3. Request rrweb snapshots from Content Script.
  4. Assemble archive (see REQ-archive-layout).
  5. Trigger download via `chrome.downloads.download()`.
  6. Display "Готово! ✓" status.
- Confirming source: `README.md` §"Использование".

---

## REQ-archive-layout

- Source: `Тз расширение фаза1.md` §6
- Scope: ZIP archive structure
- Description: The archive MUST be named
  `session_report_YYYY-MM-DD_HH-MM-SS.zip` and contain exactly:
  ```
  session_report_2025-05-15_14-32-10.zip
  ├── video/
  │   └── last_30sec.webm         # склеенные чанки видеобуфера
  ├── rrweb/
  │   └── session.json            # массив DOM-событий rrweb
  ├── logs/
  │   └── events.json             # лог действий пользователя
  ├── screenshot.png              # скриншот в момент сохранения
  └── meta.json                   # метаданные сессии
  ```
- Acceptance criteria (from SPEC §10):
  - Archive opens cleanly.
  - `last_30sec.webm` plays back in a browser.
- Confirming source: `README.md` §"Структура архива" (byte-identical layout).

---

## REQ-meta-json-schema

- Source: `Тз расширение фаза1.md` §6
- Scope: Archive metadata
- Description: `meta.json` inside the archive MUST conform to the schema:
  ```json
  {
    "timestamp": "2025-05-15T14:32:10Z",
    "url": "https://...",
    "userAgent": "Chrome/...",
    "extensionVersion": "1.0.0",
    "videoBufferSeconds": 30,
    "logDurationMinutes": 10,
    "totalEvents": 143
  }
  ```
- Fields are required (SPEC does not mark any optional).

---

## REQ-manifest-permissions

- Source: `Тз расширение фаза1.md` §7
- Scope: Browser permission surface
- Description: The extension MUST declare exactly the permission set in DEC-011
  and MUST request user gesture for `tabCapture` on first activation.
- Acceptance criteria (from SPEC §10):
  - Extension installs in Chrome without errors.

---

## REQ-archive-export-latency

- Source: `Тз расширение фаза1.md` §10 (acceptance)
- Scope: Performance — archive delivery
- Description: From the moment the user clicks the export button, the ZIP
  archive MUST land in the "Downloads" folder in under 5 seconds.
- Confirming source: `README.md` §"Критерии приёмки Фазы 1".

---

## REQ-password-confidentiality

- Source: `Тз расширение фаза1.md` §4.2, §4.3, §8, §10
- Scope: Sensitive data handling
- Description: Passwords MUST NOT appear in either rrweb snapshots or the user
  event log. Masking MUST be enforced by:
  - rrweb `maskInputSelector` covering `input[type=password]` and
    `[data-sensitive="true"]`
  - the event logger explicitly filtering value capture for password fields
- Acceptance criteria (from SPEC §10):
  - Passwords do not leak into either output stream.
- Confirming source: `README.md` §"Маскирование чувствительных данных".

---

## REQ-install-clean

- Source: `Тз расширение фаза1.md` §10
- Scope: Installability
- Description: The extension MUST install in Chrome without errors via the
  unpacked-extension load flow.
- Confirming source: `README.md` §"Установка расширения в Chrome".

---

## Phase 1 Acceptance Criteria (full list, SPEC §10 verbatim)

For traceability, all SPEC §10 acceptance criteria are listed here once. Each
is also referenced from one or more REQ-* entries above.

1. The extension installs in Chrome without errors. → REQ-install-clean,
   REQ-manifest-permissions
2. The video buffer runs continuously on any tab. → REQ-video-ring-buffer
3. The buffer always contains no more than 30 seconds of video. →
   REQ-video-ring-buffer
4. rrweb records DOM events without errors on typical pages (forms, tables,
   modal windows). → REQ-rrweb-dom-buffer
5. The event log captures clicks, navigation, and network errors. →
   REQ-user-event-log
6. On button press, the archive is downloaded to "Downloads" in < 5 seconds. →
   REQ-archive-export-latency
7. The archive opens; `last_30sec.webm` plays back in a browser. →
   REQ-archive-layout, REQ-video-ring-buffer
8. Passwords do not appear in the log or rrweb snapshots. →
   REQ-password-confidentiality
9. Extension RAM consumption does not exceed 50 MB in the background. → see
   `constraints.md` CON-ram-ceiling (NFR, not a functional REQ).