208 lines
8.4 KiB
Markdown
208 lines
8.4 KiB
Markdown
# Requirements: Mokosh
|
||
|
||
**Defined:** 2026-05-15
|
||
**Core Value:** When an operator hits a bug, one click produces a self-contained
|
||
archive that lets support reproduce what happened — in under 5 s, no server, no
|
||
password leaks.
|
||
|
||
All requirements below are extracted from the SPEC `Тз расширение фаза1.md`.
|
||
The intel files `.planning/intel/requirements.md`, `.planning/intel/constraints.md`,
|
||
and `.planning/intel/decisions.md` carry the verbatim wording, source citations,
|
||
and technical bindings; this file is the GSD-shaped projection of those facts.
|
||
|
||
## v1 Requirements
|
||
|
||
Requirements for the Phase 1 SPEC. Each maps to one phase in ROADMAP.md.
|
||
|
||
### Video
|
||
|
||
- [ ] **REQ-video-ring-buffer**: The extension maintains an in-memory ring
|
||
buffer containing the most recent 30 seconds of active-tab video. Video is
|
||
captured via `chrome.tabCapture.capture()` at `video/webm; codecs=vp9` @
|
||
400 000 bps with a `MediaRecorder` timeslice of 2000 ms. A single continuous
|
||
recorder per session; tab activation changes trigger re-attach. The first
|
||
emitted chunk (WebM header) is retained indefinitely; subsequent chunks
|
||
rotate out by the 30-second TTL rule. Bindings: DEC-003, DEC-009,
|
||
CON-video-window, CON-video-codec, CON-webm-header-retention.
|
||
- SPEC §10 acceptance criteria: #2, #3, #7.
|
||
|
||
### DOM Capture
|
||
|
||
- [ ] **REQ-rrweb-dom-buffer**: The extension records DOM events via rrweb
|
||
(`rrweb.record()`) running in the Content Script over a rolling 10-minute
|
||
window, capped at 5 000 events (oldest dropped on overflow). Sensitive
|
||
fields are masked via rrweb v2 `maskInputFn` covering `input[type=password]`
|
||
and `[data-sensitive="true"]`. Bindings: DEC-004, CON-rrweb-window,
|
||
CON-sensitive-data-masking.
|
||
- SPEC §10 acceptance criteria: #4.
|
||
|
||
### Event Logging
|
||
|
||
- [ ] **REQ-user-event-log**: The extension logs user and runtime events over
|
||
a rolling 10-minute window. Captured types: `click` (records target selector
|
||
and element text), `input` (excludes password fields), `navigation`
|
||
(`popstate`, `hashchange`, page transitions), `js_error` (`window.onerror`,
|
||
`window.onunhandledrejection`), `network_error` (`fetch` / `XMLHttpRequest`
|
||
with response code >= 400). Each entry conforms to the verbatim
|
||
`CON-event-log-schema`. Bindings: CON-event-log-window, CON-event-log-schema,
|
||
CON-sensitive-data-masking.
|
||
- SPEC §10 acceptance criteria: #5, #8.
|
||
|
||
### Export
|
||
|
||
- [ ] **REQ-screenshot-on-export**: On "Save archive" click, the extension
|
||
captures a PNG screenshot of the active tab via
|
||
`chrome.tabs.captureVisibleTab()` and includes it as `screenshot.png` in the
|
||
archive. Binding: DEC-008.
|
||
|
||
- [ ] **REQ-popup-ui**: The extension exposes a minimal popup with a single
|
||
button labeled "Сохранить отчёт об ошибке" and a sub-label "Последние 30 сек
|
||
видео + 10 мин лога". Button state machine:
|
||
`idle → "Сохраняю..." → "Готово! ✓" → idle` (3 s revert). On click:
|
||
(1) capture screenshot, (2) request video buffer + event log from SW,
|
||
(3) request rrweb snapshots from Content Script, (4) assemble archive,
|
||
(5) trigger download, (6) display "Готово! ✓". Russian strings are part of
|
||
the contract and preserved verbatim.
|
||
|
||
- [ ] **REQ-archive-layout**: The archive is named
|
||
`session_report_YYYY-MM-DD_HH-MM-SS.zip` and contains exactly:
|
||
```
|
||
session_report_2025-05-15_14-32-10.zip
|
||
├── video/
|
||
│ └── last_30sec.webm
|
||
├── rrweb/
|
||
│ └── session.json
|
||
├── logs/
|
||
│ └── events.json
|
||
├── screenshot.png
|
||
└── meta.json
|
||
```
|
||
Binding: CON-archive-layout.
|
||
- SPEC §10 acceptance criteria: #7.
|
||
|
||
- [ ] **REQ-meta-json-schema**: `meta.json` inside the archive conforms to the
|
||
verbatim schema:
|
||
```json
|
||
{
|
||
"timestamp": "2025-05-15T14:32:10Z",
|
||
"url": "https://...",
|
||
"userAgent": "Chrome/...",
|
||
"extensionVersion": "1.0.0",
|
||
"videoBufferSeconds": 30,
|
||
"logDurationMinutes": 10,
|
||
"totalEvents": 143
|
||
}
|
||
```
|
||
All fields required. Binding: CON-meta-json-schema.
|
||
|
||
### Manifest & Install
|
||
|
||
- [ ] **REQ-manifest-permissions**: `manifest.json` declares exactly the
|
||
permission set in DEC-011 (`tabCapture`, `activeTab`, `downloads`, `scripting`,
|
||
`storage`; `host_permissions: ["<all_urls>"]`) and requests a user gesture
|
||
for `tabCapture` on first activation. Binding: DEC-011, CON-manifest-permissions.
|
||
- SPEC §10 acceptance criteria: #1.
|
||
|
||
- [ ] **REQ-install-clean**: The extension installs in Chrome without errors
|
||
via the unpacked-extension load flow.
|
||
- SPEC §10 acceptance criteria: #1.
|
||
|
||
### Performance & Security
|
||
|
||
- [ ] **REQ-archive-export-latency**: From the moment the user clicks the
|
||
export button, the ZIP archive lands in the "Downloads" folder in under
|
||
5 seconds. Binding: CON-archive-export-latency.
|
||
- SPEC §10 acceptance criteria: #6.
|
||
|
||
- [ ] **REQ-password-confidentiality**: Passwords do not appear in rrweb
|
||
snapshots OR the user event log. Masking is enforced via rrweb v2
|
||
`maskInputFn` AND explicit value filtering in the event logger for password
|
||
fields. Binding: CON-sensitive-data-masking.
|
||
- SPEC §10 acceptance criteria: #8.
|
||
|
||
## v2 Requirements
|
||
|
||
Deferred to a future phase per SPEC §9 ("Что НЕ входит в Фазу 1"). Tracked
|
||
but not in current roadmap.
|
||
|
||
### Server & Diagnostics
|
||
|
||
- **SRV-01**: Upload captured archives to a remote server.
|
||
- **SRV-02**: AI-driven diagnostics of captured sessions.
|
||
- **SRV-03**: Automatic ticket creation from captured reports.
|
||
- **SRV-04**: Analytics dashboard summarising captured sessions.
|
||
|
||
### Capture
|
||
|
||
- **CAP-01**: Audio recording in addition to video.
|
||
|
||
## Out of Scope
|
||
|
||
Explicitly excluded in Phase 1. Documented to prevent scope creep.
|
||
|
||
| Feature | Reason |
|
||
|---------|--------|
|
||
| Server upload | SPEC §9 — Phase 2 work. Phase 1 is local-only via `chrome.downloads`. |
|
||
| AI diagnostics | SPEC §9 — Phase 2 work. |
|
||
| Automatic ticketing | SPEC §9 — Phase 2 work. |
|
||
| Analytics dashboard | SPEC §9 — Phase 2 work. |
|
||
| Audio recording | SPEC §9 — Phase 2 work. |
|
||
| `chrome.storage` / IndexedDB persistence of rolling buffers | CON-buffer-storage — buffers are in-memory only in Phase 1. |
|
||
| Recording inactive tabs | CON-tab-capture-binding — `chrome.tabCapture` is active-tab-bound by design. |
|
||
|
||
## Phase 1 Acceptance Criteria (SPEC §10 verbatim)
|
||
|
||
For traceability, all SPEC §10 acceptance criteria are listed once here, each
|
||
cross-referenced to its supporting REQ-* entries. The developer-facing success
|
||
metric for the whole project is "all 9 pass".
|
||
|
||
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. →
|
||
CON-ram-ceiling (NFR, not a functional REQ).
|
||
|
||
## Traceability
|
||
|
||
Which phase covers which requirement. See ROADMAP.md for phase details.
|
||
|
||
| Requirement | Phase | Status |
|
||
|-------------|-------|--------|
|
||
| REQ-video-ring-buffer | Phase 1 | Pending |
|
||
| REQ-rrweb-dom-buffer | Phase 2 | Pending |
|
||
| REQ-user-event-log | Phase 2 | Pending |
|
||
| REQ-password-confidentiality | Phase 2 | Pending |
|
||
| REQ-popup-ui | Phase 3 | Pending |
|
||
| REQ-screenshot-on-export | Phase 3 | Pending |
|
||
| REQ-archive-layout | Phase 3 | Pending |
|
||
| REQ-meta-json-schema | Phase 3 | Pending |
|
||
| REQ-archive-export-latency | Phase 3 | Pending |
|
||
| REQ-manifest-permissions | Phase 3 | Pending |
|
||
| REQ-install-clean | Phase 4 | Pending |
|
||
|
||
**Coverage:**
|
||
- v1 requirements: 11 total
|
||
- Mapped to phases: 11
|
||
- Unmapped: 0 ✓
|
||
|
||
Note on CON-ram-ceiling (SPEC §10 #9): tracked as a non-functional constraint
|
||
verified in Phase 4 (smoke verification) rather than as a standalone
|
||
functional REQ, per the intel synthesis. Phase 4 success criteria include the
|
||
RAM-ceiling check.
|
||
|
||
---
|
||
*Requirements defined: 2026-05-15*
|
||
*Last updated: 2026-05-15 after initial bootstrap from intel synthesis*
|