# RTSP Windowed People Flow Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add an RTSP mode that samples one frame per second, emits independent 30-minute JSON summaries, and preserves the existing offline video and batch workflows.

**Architecture:** Keep the existing offline pipeline untouched and add a dedicated RTSP pipeline path that reuses the counting and attribute aggregation components. Introduce a small RTSP configuration model and window-summary writer so the stream loop can reconnect, flush windowed JSON files, and reset state cleanly.

**Tech Stack:** Python, OpenCV, Ultralytics YOLO, DeepFace, PyYAML, dataclasses

---

### Task 1: Add RTSP configuration models

**Files:**
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/models.py`
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/config.py`
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/configs/default_config.yaml`

**Step 1: Add an RTSP config dataclass**

- Add a dataclass with interval, window duration, reconnect delay, idle sleep, and output subdirectory fields.
- Attach it to `AppConfig`.

**Step 2: Load RTSP config from YAML**

- Update config loading to parse the new section.
- Keep backward compatibility when the section is absent.

**Step 3: Set sensible defaults in YAML**

- Add `sample_interval_seconds: 1`
- Add `window_seconds: 1800`
- Add reconnect and idle sleep defaults.

**Step 4: Run a compile check**

Run: `python3 -m compileall main.py src`
Expected: PASS

### Task 2: Add the RTSP CLI entrypoint

**Files:**
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/main.py`

**Step 1: Add a new `rtsp` subcommand**

- Accept `--input` as the RTSP URL.
- Reuse global config and output arguments.

**Step 2: Wire the command to the pipeline**

- Call a new `process_rtsp()` method.
- Print the output directory and latest JSON path once the command starts.

**Step 3: Verify CLI help**

Run: `python3 main.py rtsp --help`
Expected: PASS and shows the RTSP input argument.

### Task 3: Implement the RTSP processing loop

**Files:**
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/io_utils.py`

**Step 1: Add RTSP output helpers**

- Add a helper that creates `/rtsp_stream/windows`.
- Add a helper that writes a timestamped JSON file and refreshes `latest.json`.

**Step 2: Add RTSP window summary generation**

- Reuse the existing summary-building logic, but parameterize it with `source`, `window_start`, and `window_end`.
- Keep the same count keys and track payload structure.

**Step 3: Add `process_rtsp()`**

- Open the RTSP stream with OpenCV.
- Reconnect on open/read failures after a delay.
- Sample one frame per second based on wall-clock time.
- Reuse YOLO tracking, crossing detection, and DeepFace aggregation on sampled frames only.
- Flush a JSON summary every 30 minutes.
- Reset counting and attribute state after each flush.

**Step 4: Keep long-running behavior explicit**

- Do not save annotated RTSP video by default.
- Ensure zero-count windows still emit JSON.

### Task 4: Preserve offline behavior

**Files:**
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`

**Step 1: Refactor only shared summary code**

- Extract helper methods where useful.
- Do not change the existing `video`/`batch` outputs or file naming.

**Step 2: Re-run offline CLI smoke tests**

Run: `python3 main.py --help`
Expected: PASS

Run: `python3 main.py video --help`
Expected: PASS

Run: `python3 main.py batch --help`
Expected: PASS

### Task 5: Update docs and validate

**Files:**
- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README.md`

**Step 1: Document the new RTSP mode**

- Add example commands.
- Explain the 1 FPS sampling and 30-minute window JSON behavior.

**Step 2: Run final validation**

Run: `python3 -m compileall main.py src`
Expected: PASS

Run: `python3 main.py rtsp --help`
Expected: PASS

Run: `python3 main.py --help`
Expected: PASS