feat: initialize managed portal

2026-04-27 10:04:36 +08:00
commit d4e351df71
145 changed files with 13425 additions and 0 deletions
--- a/managed/people_flow_project/.dockerignore
+++ b/managed/people_flow_project/.dockerignore
@@ -0,0 +1,7 @@
+.git
+.venv
+__pycache__
+*.pyc
+outputs
+people_flow_project_backup_2026-04-08
+docs/plans
--- a/managed/people_flow_project/.gitignore
+++ b/managed/people_flow_project/.gitignore
@@ -0,0 +1,8 @@
+.DS_Store
+.venv/
+__pycache__/
+config/local.yaml
+outputs/
+wheelhouse/
+weights/*.pt
+weights/deepface/*.h5
--- a/managed/people_flow_project/Dockerfile
+++ b/managed/people_flow_project/Dockerfile
@@ -0,0 +1,44 @@
+FROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim-bookworm
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
+    DEEPFACE_HOME=/root/.deepface \
+    TF_CPP_MIN_LOG_LEVEL=2
+
+WORKDIR /opt/people-flow
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    libglib2.0-0 \
+    libgl1 \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements-docker.txt ./requirements-docker.txt
+
+RUN python -m pip install --upgrade pip setuptools wheel && \
+    pip install "numpy<2" && \
+    pip install --extra-index-url https://download.pytorch.org/whl/cpu \
+        "torch==2.6.0+cpu" "torchvision==0.21.0+cpu" && \
+    pip install "tensorflow==2.16.1" "tf-keras==2.16.0" && \
+    pip install -r requirements-docker.txt
+
+COPY . .
+COPY scripts/docker-entrypoint.sh /opt/people-flow/scripts/docker-entrypoint.sh
+
+RUN test -f /opt/people-flow/weights/yolo11n.pt && \
+    test -f /opt/people-flow/weights/deepface/age_model_weights.h5 && \
+    test -f /opt/people-flow/weights/deepface/gender_model_weights.h5 && \
+    test -f /opt/people-flow/weights/deepface/retinaface.h5 && \
+    mkdir -p /root/.deepface/weights /opt/people-flow/outputs && \
+    cp /opt/people-flow/weights/deepface/*.h5 /root/.deepface/weights/ && \
+    chmod +x /opt/people-flow/scripts/docker-entrypoint.sh
+
+EXPOSE 18082
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:18082/api/manage/health', timeout=3).read()" || exit 1
+
+ENTRYPOINT ["/opt/people-flow/scripts/docker-entrypoint.sh"]
--- a/managed/people_flow_project/README.md
+++ b/managed/people_flow_project/README.md
@@ -0,0 +1,144 @@
+# People Flow Project
+
+People flow analysis for street videos using YOLO tracking and face-based demographic estimation.
+
+## What it does
+
+- Counts unique people when they cross a configured line
+- Estimates one age bucket per counted track: `minor`, `adult`, or `senior`
+- Estimates one gender bucket per counted track: `male` or `female`
+- Writes an annotated output video, per-video JSON, and batch summary CSV
+
+## Pipeline
+
+1. Detect and track `person` objects with Ultralytics YOLO.
+2. Assign a stable `track_id` with BoT-SORT or ByteTrack.
+3. Count each track once when it crosses the configured line.
+4. Sample person crops for each track and run DeepFace age/gender analysis.
+5. Use track-level voting so each counted person lands in only one age bucket and one gender bucket.
+
+## Project Layout
+
+- `main.py`: CLI entrypoint
+- `src/people_flow/`: application modules
+- `configs/default_config.yaml`: default runtime settings
+- `outputs/`: generated result files
+- `docs/plans/`: design and implementation notes
+
+## Recommended Environment
+
+- Linux
+- NVIDIA GPU with CUDA
+- Python `3.10` or `3.11`
+
+`deepface` and its transitive dependencies are not a good fit for Python `3.14`, so do not build this environment on the current local interpreter version.
+
+## Install
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Single Video
+
+```bash
+python main.py video \
+  --input "/path/to/video.mp4" \
+  --line "0.1,0.55,0.9,0.55"
+```
+
+## Batch Directory
+
+```bash
+python main.py batch \
+  --input-dir "/path/to/videos" \
+  --line "0.1,0.55,0.9,0.55"
+```
+
+## RTSP Stream
+
+```bash
+python main.py --output-dir outputs rtsp \
+  --input "rtsp://user:password@host:554/stream"
+```
+
+RTSP mode behaves differently from offline video mode:
+
+- The stream is sampled at one processed frame per second
+- Statistics are isolated into 30-minute windows
+- Each completed window writes one JSON file
+- `latest.json` is overwritten on every completed window
+- RTSP mode does not save annotated video by default
+
+## Output Files
+
+Each processed video produces:
+
+- `outputs/<video_stem>/<video_stem>.annotated.mp4`
+- `outputs/<video_stem>/<video_stem>.json`
+
+Batch mode also produces:
+
+- `outputs/batch_summary.csv`
+
+RTSP mode produces:
+
+- `outputs/rtsp_stream/latest.json`
+- `outputs/rtsp_stream/windows/stats_YYYY-MM-DD_HH-MM-SS.json`
+
+## Docker On Ubuntu 24.04 x86_64
+
+The project can be packaged for an x86_64 NVIDIA host with Docker. The expected weight layout is:
+
+- `weights/yolo11n.pt`
+- `weights/deepface/age_model_weights.h5`
+- `weights/deepface/gender_model_weights.h5`
+- `weights/deepface/retinaface.h5`
+
+Build the image:
+
+```bash
+docker build -t people-flow-project:test .
+```
+
+The Docker image uses [`requirements-docker.txt`](/Users/zxmacmini1/Documents/人流检测/people_flow_project/requirements-docker.txt) so the container installs `opencv-python-headless` instead of the desktop OpenCV wheel.
+
+The image bakes in all runtime weights and copies the DeepFace `.h5` files into `~/.deepface/weights` during build.
+
+Run the management API container:
+
+```bash
+docker run -d \
+  --name people-flow-project \
+  --restart unless-stopped \
+  --gpus all \
+  --shm-size 1g \
+  -p 18082:18082 \
+  -e RTSP_URL="rtsp://user:password@host:554/stream" \
+  -v /path/to/config:/opt/people-flow/config \
+  -v /path/to/outputs:/opt/people-flow/outputs \
+  people-flow-project:test
+```
+
+Or use Compose:
+
+```bash
+docker compose up --build people-flow-project
+```
+
+Container behavior:
+
+- Seeds `config/local.yaml` from `config/config.example.yaml` when needed
+- Writes RTSP updates through the child API to `runtime.rtsp_url`
+- Exposes `GET /api/manage/health` on `http://127.0.0.1:18082`
+- Persists config and outputs through mounted `./config` and `./outputs`
+
+## Notes
+
+- `minor` means age `< 18`
+- `adult` means age `18-59`
+- `senior` means age `>= 60`
+- Tracks without a reliable face result are counted only in `total_people` and `unknown_attributes`
--- a/managed/people_flow_project/README_NATIVE.md
+++ b/managed/people_flow_project/README_NATIVE.md
@@ -0,0 +1,65 @@
+# Native RTSP Bundle
+
+This bundle is for lightweight native deployment on an x86_64 Ubuntu host.
+
+## What To Edit
+
+Open [`scripts/run.sh`](/Users/zxmacmini1/Documents/人流检测/people_flow_project/scripts/run.sh) and edit only these two lines:
+
+```bash
+RTSP_URL="rtsp://..."
+OUTPUT_DIR="/home/x/people/output"
+```
+
+## First-Time Setup
+
+From the project root:
+
+```bash
+sudo bash scripts/install.sh
+```
+
+This creates `.venv`, installs Python dependencies, copies the bundled DeepFace weights into `~/.deepface/weights`, installs the `systemd` unit, starts the service, and enables it on boot.
+
+## Build An Offline Dependency Pack
+
+If you want future installs to avoid re-downloading Python packages:
+
+```bash
+./build_wheelhouse.sh
+```
+
+This creates a local `wheelhouse/` directory for Ubuntu 24.04 x86_64 + Python 3.12. After that, `./setup_native_venv.sh` will automatically prefer local wheels.
+
+## Start The RTSP Task
+
+```bash
+sudo systemctl status people-flow.service
+```
+
+The service runs in the foreground under `systemd`.
+
+## Outputs
+
+- Latest half-hour summary: `OUTPUT_DIR/rtsp_stream/latest.json`
+- Historical half-hour summaries: `OUTPUT_DIR/rtsp_stream/windows/`
+- Runtime log: `OUTPUT_DIR/rtsp_run.log`
+
+## Chinese Guide
+
+- `README_zh.md`
+
+## Weights
+
+The project expects these local files:
+
+- `weights/yolo11n.pt`
+- `weights/deepface/age_model_weights.h5`
+- `weights/deepface/gender_model_weights.h5`
+- `weights/deepface/retinaface.h5`
+
+At setup time and each RTSP launch, those `.h5` files are copied into the current user's default DeepFace directory:
+
+- `~/.deepface/weights/`
+
+That keeps the bundle portable across different unpack paths such as `/home/x/people` and `/home/xiaozheng/people`.
--- a/managed/people_flow_project/README_zh.md
+++ b/managed/people_flow_project/README_zh.md
@@ -0,0 +1,72 @@
+# 人流检测项目中文说明
+
+这个项目用于基于 `YOLO + DeepFace` 的视频/RTSP 人流检测与属性统计。
+
+## 当前交付方式
+
+这个版本已经改成：
+
+- 使用 `config/local.yaml` 作为本地运行配置
+- 使用 `scripts/run.sh` 生成本地配置并前台运行
+- 使用 `systemd` 托管长期运行
+- 安装完成后自动启动
+- 开机自动启动
+
+## 目标机器
+
+- `Ubuntu 24.04`
+- `Python 3.12`
+- NVIDIA 显卡可用
+- `nvidia-smi` 可正常执行
+
+## 安装前需要修改
+
+先编辑 `scripts/run.sh`，至少改：
+
+- `RTSP_URL`
+- `OUTPUT_DIR`
+
+## 安装
+
+在项目根目录执行：
+
+```bash
+sudo bash scripts/install.sh
+```
+
+安装脚本会自动：
+
+- 检查并安装 `ffmpeg`
+- 检查并安装 `python3.12-venv`
+- 创建 `.venv`
+- 安装 Python 依赖
+- 复制 DeepFace 权重到 `~/.deepface/weights`
+- 生成 `config/local.yaml`
+- 安装 `systemd` 服务
+- 自动启动服务
+- 设置开机自启
+
+## 服务管理
+
+服务名：
+
+```bash
+people-flow.service
+```
+
+常用命令：
+
+```bash
+sudo systemctl status people-flow.service
+sudo systemctl restart people-flow.service
+sudo systemctl stop people-flow.service
+sudo systemctl start people-flow.service
+sudo systemctl disable people-flow.service
+```
+
+## 输出位置
+
+- 运行日志：`outputs/rtsp_run.log`
+- 最新半小时汇总：`OUTPUT_DIR/rtsp_stream/latest.json`
+- 历史窗口汇总：`OUTPUT_DIR/rtsp_stream/windows/`
+- 本地配置：`config/local.yaml`
--- a/managed/people_flow_project/build_wheelhouse.sh
+++ b/managed/people_flow_project/build_wheelhouse.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$SCRIPT_DIR"
+WHEELHOUSE_DIR="$PROJECT_ROOT/wheelhouse"
+
+mkdir -p "$WHEELHOUSE_DIR"
+
+python3 -m venv "$PROJECT_ROOT/.wheelhouse-venv"
+source "$PROJECT_ROOT/.wheelhouse-venv/bin/activate"
+
+python -m pip install --upgrade pip setuptools wheel
+
+pip download -d "$WHEELHOUSE_DIR" pip setuptools wheel
+pip download -d "$WHEELHOUSE_DIR" "numpy<2"
+pip download -d "$WHEELHOUSE_DIR" \
+  --index-url https://download.pytorch.org/whl/cu126 \
+  --extra-index-url https://pypi.nvidia.com \
+  torch torchvision
+pip download -d "$WHEELHOUSE_DIR" \
+  --extra-index-url https://pypi.nvidia.com \
+  "tensorflow[and-cuda]==2.16.1" "tf-keras==2.16.0"
+pip download -d "$WHEELHOUSE_DIR" \
+  --find-links "$WHEELHOUSE_DIR" \
+  -c "$PROJECT_ROOT/constraints-wheelhouse.txt" \
+  -r "$PROJECT_ROOT/requirements-native.txt"
+
+deactivate
+
+echo "wheelhouse_ready=$WHEELHOUSE_DIR"
--- a/managed/people_flow_project/config/config.example.yaml
+++ b/managed/people_flow_project/config/config.example.yaml
@@ -0,0 +1,41 @@
+runtime:
+  rtsp_url: "rtsp://user:password@camera-ip:554/h264/ch1/main/av_stream"
+  output_dir: "outputs"
+
+yolo:
+  model_path: "weights/yolo11n.pt"
+  tracker: "botsort.yaml"
+  conf: 0.35
+  iou: 0.5
+  imgsz: 1280
+  device: "cuda:0"
+
+counting:
+  line: [0.1, 0.55, 0.9, 0.55]
+  line_mode: "normalized"
+  crossing_tolerance: 12.0
+
+attributes:
+  enabled: false
+  sample_every_n_frames: 12
+  max_samples_per_track: 5
+  min_person_box_width: 80
+  min_person_box_height: 160
+  person_crop_padding: 0.15
+  detector_backend: "retinaface"
+  enforce_detection: false
+
+output:
+  save_video: false
+  save_json: true
+  save_csv: true
+  draw_boxes: false
+  draw_labels: false
+
+rtsp:
+  sample_interval_seconds: 1.0
+  window_seconds: 1800
+  reconnect_delay_seconds: 5.0
+  stream_open_timeout_seconds: 10.0
+  idle_sleep_seconds: 0.05
+  output_subdir: "rtsp_stream"
--- a/managed/people_flow_project/configs/default_config.yaml
+++ b/managed/people_flow_project/configs/default_config.yaml
@@ -0,0 +1,37 @@
+yolo:
+  model_path: "yolo11n.pt"
+  tracker: "botsort.yaml"
+  conf: 0.35
+  iou: 0.5
+  imgsz: 1280
+  device: "cuda:0"
+
+counting:
+  line: [0.1, 0.55, 0.9, 0.55]
+  line_mode: "normalized"
+  crossing_tolerance: 12.0
+
+attributes:
+  enabled: true
+  sample_every_n_frames: 12
+  max_samples_per_track: 5
+  min_person_box_width: 80
+  min_person_box_height: 160
+  person_crop_padding: 0.15
+  detector_backend: "retinaface"
+  enforce_detection: false
+
+output:
+  save_video: true
+  save_json: true
+  save_csv: true
+  draw_boxes: true
+  draw_labels: true
+
+rtsp:
+  sample_interval_seconds: 1.0
+  window_seconds: 1800
+  reconnect_delay_seconds: 5.0
+  stream_open_timeout_seconds: 10.0
+  idle_sleep_seconds: 0.05
+  output_subdir: "rtsp_stream"
--- a/managed/people_flow_project/configs/docker_x86_config.yaml
+++ b/managed/people_flow_project/configs/docker_x86_config.yaml
@@ -0,0 +1,37 @@
+yolo:
+  model_path: "/opt/people-flow/weights/yolo11n.pt"
+  tracker: "botsort.yaml"
+  conf: 0.35
+  iou: 0.5
+  imgsz: 1280
+  device: "cuda:0"
+
+counting:
+  line: [0.1, 0.55, 0.9, 0.55]
+  line_mode: "normalized"
+  crossing_tolerance: 12.0
+
+attributes:
+  enabled: true
+  sample_every_n_frames: 12
+  max_samples_per_track: 5
+  min_person_box_width: 80
+  min_person_box_height: 160
+  person_crop_padding: 0.15
+  detector_backend: "retinaface"
+  enforce_detection: false
+
+output:
+  save_video: false
+  save_json: true
+  save_csv: true
+  draw_boxes: false
+  draw_labels: false
+
+rtsp:
+  sample_interval_seconds: 1.0
+  window_seconds: 1800
+  reconnect_delay_seconds: 5.0
+  stream_open_timeout_seconds: 10.0
+  idle_sleep_seconds: 0.05
+  output_subdir: "rtsp_stream"
--- a/managed/people_flow_project/configs/native_x86_config.yaml
+++ b/managed/people_flow_project/configs/native_x86_config.yaml
@@ -0,0 +1,37 @@
+yolo:
+  model_path: "weights/yolo11n.pt"
+  tracker: "botsort.yaml"
+  conf: 0.35
+  iou: 0.5
+  imgsz: 1280
+  device: "cuda:0"
+
+counting:
+  line: [0.1, 0.55, 0.9, 0.55]
+  line_mode: "normalized"
+  crossing_tolerance: 12.0
+
+attributes:
+  enabled: true
+  sample_every_n_frames: 12
+  max_samples_per_track: 5
+  min_person_box_width: 80
+  min_person_box_height: 160
+  person_crop_padding: 0.15
+  detector_backend: "retinaface"
+  enforce_detection: false
+
+output:
+  save_video: false
+  save_json: true
+  save_csv: true
+  draw_boxes: false
+  draw_labels: false
+
+rtsp:
+  sample_interval_seconds: 1.0
+  window_seconds: 1800
+  reconnect_delay_seconds: 5.0
+  stream_open_timeout_seconds: 10.0
+  idle_sleep_seconds: 0.05
+  output_subdir: "rtsp_stream"
--- a/managed/people_flow_project/constraints-wheelhouse.txt
+++ b/managed/people_flow_project/constraints-wheelhouse.txt
@@ -0,0 +1,5 @@
+numpy<2
+tensorflow==2.16.1
+tf-keras==2.16.0
+torch==2.11.0+cu126
+torchvision==0.26.0+cu126
--- a/managed/people_flow_project/deploy/people-flow.service.tpl
+++ b/managed/people_flow_project/deploy/people-flow.service.tpl
@@ -0,0 +1,19 @@
+[Unit]
+Description=People Flow RTSP Service
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=__PROJECT_DIR__
+User=__RUN_USER__
+Group=__RUN_GROUP__
+Environment=PYTHONUNBUFFERED=1
+ExecStart=__PROJECT_DIR__/.venv/bin/python __PROJECT_DIR__/main.py --config __CONFIG_PATH__ rtsp
+Restart=always
+RestartSec=5
+StandardOutput=append:__PROJECT_DIR__/outputs/rtsp_run.log
+StandardError=append:__PROJECT_DIR__/outputs/rtsp_run.log
+
+[Install]
+WantedBy=multi-user.target
--- a/managed/people_flow_project/docker-compose.yml
+++ b/managed/people_flow_project/docker-compose.yml
@@ -0,0 +1,22 @@
+services:
+  people-flow-project:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: people-flow-project:local
+    container_name: people-flow-project
+    restart: unless-stopped
+    gpus: all
+    shm_size: "1gb"
+    ports:
+      - "18082:18082"
+    environment:
+      CONFIG_PATH: /opt/people-flow/config/local.yaml
+      RTSP_URL: ${RTSP_URL:-}
+      OUTPUT_DIR: /opt/people-flow/outputs
+      API_HOST: 0.0.0.0
+      API_PORT: 18082
+      DEVICE: ${DEVICE:-cuda:0}
+    volumes:
+      - ./config:/opt/people-flow/config
+      - ./outputs:/opt/people-flow/outputs
--- a/managed/people_flow_project/docs/plans/2026-04-07-people-flow-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-07-people-flow-design.md
@@ -0,0 +1,66 @@
+# People Flow Design
+
+## Goal
+
+Build a standalone project under `Documents/人流检测/people_flow_project` that analyzes street videos and produces:
+
+- unique people-flow counts
+- one mutually exclusive age bucket per counted person
+- one mutually exclusive gender bucket per counted person
+- annotated videos plus machine-readable summaries
+
+## Approved Decisions
+
+- Runtime target: Linux with NVIDIA GPU
+- Entry points: both single-video mode and batch-directory mode
+- Count logic: one `track_id` is counted once when it crosses a configured line
+- Age buckets:
+  - `minor`: age `< 18`
+  - `adult`: age `18-59`
+  - `senior`: age `>= 60`
+- Gender buckets:
+  - `male`
+  - `female`
+- Unknown face attributes:
+  - If a counted person does not yield a reliable face result, count that person only in `total_people`
+  - Also increment `unknown_attributes`
+
+## Architecture
+
+The pipeline uses Ultralytics YOLO for person detection and tracking, then DeepFace for face attribute analysis. Person tracking and counting stay separate from attribute inference so the demographic model can be replaced later without touching the counting core.
+
+The application stores votes per `track_id`. When the video finishes, each counted track is resolved to at most one final age bucket and one final gender bucket by majority voting.
+
+## Modules
+
+- `main.py`: CLI parsing and mode dispatch
+- `src/people_flow/config.py`: config loading and overrides
+- `src/people_flow/tracking.py`: track extraction from YOLO results
+- `src/people_flow/counting.py`: line-crossing logic and unique counting
+- `src/people_flow/attributes.py`: DeepFace integration and voting
+- `src/people_flow/io_utils.py`: video, JSON, and CSV output helpers
+- `src/people_flow/pipeline.py`: process orchestration
+
+## Outputs
+
+For each video:
+
+- annotated MP4
+- JSON summary
+
+For batch runs:
+
+- one CSV summary with one row per video
+
+## Error Handling
+
+- Missing dependencies should raise clear installation guidance.
+- If a video cannot be opened, fail that video with a readable error.
+- If face inference fails for a sample, continue processing and treat that sample as unavailable.
+- If no video files are found in batch mode, fail fast with a clear message.
+
+## Limitations
+
+- Age and gender quality depend on clear, sufficiently large faces.
+- Street scenes with strong occlusion, side views, masks, or low light will increase `unknown_attributes` and lower reliability.
+- The default line is a placeholder and should be adjusted per camera view.
--- a/managed/people_flow_project/docs/plans/2026-04-07-people-flow-implementation.md
+++ b/managed/people_flow_project/docs/plans/2026-04-07-people-flow-implementation.md
@@ -0,0 +1,128 @@
+# People Flow Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a standalone Python project that counts unique line crossings in street videos and adds track-level age/gender summaries.
+
+**Architecture:** Use Ultralytics YOLO to detect and track persons frame by frame, then run DeepFace on sampled person crops to infer face attributes. Keep counting, tracking, and attribute voting in separate modules so the demographic backend can be swapped later.
+
+**Tech Stack:** Python, Ultralytics YOLO, OpenCV, DeepFace, PyYAML, pandas
+
+---
+
+### Task 1: Scaffold the project
+
+**Files:**
+- Create: `README.md`
+- Create: `requirements.txt`
+- Create: `pyproject.toml`
+- Create: `configs/default_config.yaml`
+- Create: `docs/plans/2026-04-07-people-flow-design.md`
+
+**Step 1: Write the initial files**
+
+Add installation instructions, runtime expectations, and default settings.
+
+**Step 2: Verify structure**
+
+Run: `find . -maxdepth 3 | sed -n '1,120p'`
+Expected: project files and directories exist.
+
+**Step 3: Commit**
+
+This workspace is not a git repository. Skip the commit step unless the user later initializes git here.
+
+### Task 2: Build the CLI and config loader
+
+**Files:**
+- Create: `main.py`
+- Create: `src/people_flow/__init__.py`
+- Create: `src/people_flow/config.py`
+- Create: `src/people_flow/models.py`
+
+**Step 1: Implement argument parsing**
+
+Support `video` and `batch` subcommands, config overrides, output directory selection, and line overrides.
+
+**Step 2: Implement config loading**
+
+Load YAML defaults and merge CLI overrides into typed dataclasses.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall main.py src`
+Expected: compile succeeds without syntax errors.
+
+### Task 3: Implement tracking and counting
+
+**Files:**
+- Create: `src/people_flow/tracking.py`
+- Create: `src/people_flow/counting.py`
+
+**Step 1: Extract tracked `person` detections**
+
+Convert YOLO result objects into simple track observations with `track_id`, bounding box, confidence, and center point.
+
+**Step 2: Implement line-cross counting**
+
+Count one crossing per track by monitoring the sign change of the track center relative to the configured line.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall src`
+Expected: compile succeeds.
+
+### Task 4: Implement attribute voting and output helpers
+
+**Files:**
+- Create: `src/people_flow/attributes.py`
+- Create: `src/people_flow/io_utils.py`
+
+**Step 1: Integrate DeepFace**
+
+Sample person crops, run `age` and `gender` analysis, normalize labels, and store per-track votes.
+
+**Step 2: Implement output helpers**
+
+Write JSON summaries, CSV summaries, and draw overlays onto frames.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall src`
+Expected: compile succeeds.
+
+### Task 5: Implement the processing pipeline
+
+**Files:**
+- Create: `src/people_flow/pipeline.py`
+
+**Step 1: Build the main loop**
+
+Open the video, run YOLO tracking on frames, update counters, sample attributes, draw overlays, and save artifacts.
+
+**Step 2: Build batch mode**
+
+Discover supported video files recursively and run the same pipeline per file, then write `outputs/batch_summary.csv`.
+
+**Step 3: Verify**
+
+Run: `python3 -m compileall main.py src`
+Expected: compile succeeds.
+
+### Task 6: Final verification
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Smoke-check the CLI**
+
+Run: `python3 main.py --help`
+Expected: help text shows the `video` and `batch` commands.
+
+**Step 2: Document limitations**
+
+Make sure README notes Python version constraints and face-quality limitations.
+
+**Step 3: Commit**
+
+Skip commit because this workspace is not a git repository.
--- a/managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights-design.md
@@ -0,0 +1,17 @@
+# Portable DeepFace Weights Design
+
+**Goal:** Make DeepFace reuse bundled project weights regardless of where the project directory is unpacked.
+
+**Problem:** The current native launcher sets `DEEPFACE_HOME` to a project-local `.deepface` directory. DeepFace then appends its own `.deepface/weights` segment, so runtime lookup becomes `PROJECT_ROOT/.deepface/.deepface/weights`, which bypasses the bundled `weights/deepface` directory and triggers redundant downloads.
+
+**Approach Options:**
+
+1. Copy bundled weights into the current user's default `~/.deepface/weights` directory before startup.
+   This matches DeepFace's default lookup behavior and avoids hard-coded absolute paths. It works whether the project lives under `/home/x/people`, `/home/xiaozheng/people`, or any other directory.
+
+2. Keep using `DEEPFACE_HOME` and reshape the project-local directory tree to match DeepFace's nested expectations.
+   This avoids duplicating files but is more fragile and easier to break when DeepFace internals change.
+
+**Recommendation:** Use option 1. Update the native setup and launcher scripts to sync `weights/deepface/*.h5` into `~/.deepface/weights` and stop overriding `DEEPFACE_HOME`.
+
+**Validation:** Confirm the RTSP process starts without downloading `retinaface.h5`, `age_model_weights.h5`, or `gender_model_weights.h5`, and verify the launcher still works after changing only the project root path.
--- a/managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights.md
@@ -0,0 +1,51 @@
+# Portable DeepFace Weights Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the native RTSP bundle reuse bundled DeepFace weights from any unpack location without extra downloads.
+
+**Architecture:** Remove the custom `DEEPFACE_HOME` override from the native runtime path. Before setup and launch, copy the bundled DeepFace weight files from `weights/deepface/` into the current user's default `~/.deepface/weights/` directory so DeepFace resolves them through its own standard path logic.
+
+**Tech Stack:** Bash, DeepFace, native Python virtual environment, offline wheelhouse bundle
+
+---
+
+### Task 1: Fix native setup and launcher paths
+
+**Files:**
+- Modify: `run_rtsp.sh`
+- Modify: `setup_native_venv.sh`
+- Modify: `README_NATIVE.md`
+
+**Step 1: Update `run_rtsp.sh`**
+
+Remove the `DEEPFACE_HOME` override. Create `"$HOME/.deepface/weights"` and copy bundled `.h5` files from `"$PROJECT_ROOT/weights/deepface"` into that directory before starting the Python process.
+
+**Step 2: Update `setup_native_venv.sh`**
+
+After dependency installation, create `"$HOME/.deepface/weights"` and copy bundled `.h5` files into it so the environment is ready before the first run.
+
+**Step 3: Update native documentation**
+
+Explain that bundled weights are staged into `~/.deepface/weights` automatically and that the project path itself can move without breaking the weight lookup.
+
+### Task 2: Sync and verify on the Ubuntu target
+
+**Files:**
+- Modify: remote copies of the files above under `/home/x/people/people_flow_project`
+
+**Step 1: Sync the changed files to `192.168.5.154`**
+
+Copy the updated launcher, setup script, and documentation.
+
+**Step 2: Stage bundled weights into the target user's home directory**
+
+Run the updated setup logic or equivalent copy command and verify `~/.deepface/weights` contains the expected `.h5` files.
+
+**Step 3: Restart RTSP and inspect logs**
+
+Restart the RTSP job and confirm the log no longer shows downloads from `deepface_models/releases`.
+
+**Step 4: Commit**
+
+Skip commit unless explicitly requested by the user.
--- a/managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle-design.md
@@ -0,0 +1,81 @@
+# Lightweight Native Bundle Design
+
+**Date:** 2026-04-08
+
+**Goal:** Deliver a lightweight native deployment bundle for Ubuntu 24.04 x86_64 that includes project code, required weights, a single editable RTSP run script, and a small setup path on the target host without bundling a full Python environment in the archive.
+
+## Scope
+
+- Target host: `xiaozheng@192.168.5.154`
+- Target path: `/home/x/people/people_flow_project`
+- Bundle contents:
+  - project code
+  - YOLO weight
+  - DeepFace weights
+  - one editable run script
+  - setup and usage documentation
+- Exclude the virtual environment from the compressed bundle to keep size down.
+
+## Deployment Model
+
+The target host already has:
+
+- Ubuntu 24.04 x86_64
+- Python 3.12
+- Docker available, but Docker is intentionally not used here
+- NVIDIA driver and CUDA-capable GPU
+
+The bundle will therefore rely on:
+
+1. a project-local `.venv` created on the target host
+2. host driver compatibility for GPU wheels
+3. project-relative weight paths so no external downloads are needed
+
+## User Editing Surface
+
+The main operator interface is a single shell script:
+
+- `run_rtsp.sh`
+
+The user edits only:
+
+- `RTSP_URL`
+- `OUTPUT_DIR`
+
+The script activates `.venv`, points to the native x86 config, and runs the RTSP pipeline.
+
+## Config Strategy
+
+Add a dedicated native x86 config file with:
+
+- `yolo.model_path` pointing to the local `weights/yolo11n.pt`
+- RTSP timing settings
+- output defaults for RTSP mode
+
+This avoids modifying the existing Jetson-oriented config and keeps host deployment deterministic.
+
+## Setup Strategy
+
+Provide a small setup script that:
+
+- creates `.venv`
+- upgrades pip/setuptools/wheel
+- installs CUDA-enabled PyTorch wheels
+- installs TensorFlow, `tf-keras`, and application dependencies
+
+The setup script keeps the archive light while still making the target directory self-contained after one install step.
+
+## Bundle Output
+
+On the target host, create a compressed archive such as:
+
+- `/home/x/people/people_flow_project_native_bundle_2026-04-08.tar.gz`
+
+The archive will exclude `.venv` so it stays close to the size of code plus weights.
+
+## Success Criteria
+
+- The target host contains a runnable native project directory
+- `run_rtsp.sh` is the only file the operator needs to edit for RTSP URL and output directory
+- All required weights are present locally
+- The lightweight tarball is created successfully
--- a/managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-lightweight-native-bundle.md
@@ -0,0 +1,66 @@
+# Lightweight Native Bundle Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Produce a lightweight native deployment bundle for Ubuntu 24.04 x86_64 with code, weights, one editable RTSP run script, and a local venv setup path.
+
+**Architecture:** Keep all code and weights inside the project directory, add one native config and two helper scripts, then create the venv on the target host instead of bundling it into the archive.
+
+**Tech Stack:** Python 3.12, venv, PyTorch GPU wheels, TensorFlow, DeepFace, shell scripts
+
+---
+
+### Task 1: Add native deployment files
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/configs/native_x86_config.yaml`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/run_rtsp.sh`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/setup_native_venv.sh`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README_NATIVE.md`
+
+**Step 1: Add a native x86 config**
+
+- Point YOLO to the local project weight path.
+- Keep RTSP behavior aligned with the current project.
+
+**Step 2: Add a single editable RTSP launcher**
+
+- Put `RTSP_URL` and `OUTPUT_DIR` at the top of the file.
+- Run the project with `.venv/bin/python`.
+
+**Step 3: Add a setup script**
+
+- Create `.venv`
+- Install GPU-enabled PyTorch
+- Install TensorFlow and project requirements
+
+### Task 2: Deploy to the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Sync the updated project**
+
+- Replace the target project directory while preserving weights if needed.
+
+**Step 2: Ensure weights are in project-relative paths**
+
+- Verify YOLO and DeepFace weights under `weights/`.
+
+### Task 3: Validate and bundle
+
+**Files:**
+- No code changes required
+
+**Step 1: Run setup on the target host**
+
+- Execute the setup script.
+
+**Step 2: Validate the RTSP CLI**
+
+- Run `./.venv/bin/python main.py rtsp --help`.
+
+**Step 3: Create the lightweight tarball**
+
+- Exclude `.venv`
+- Keep code, scripts, configs, docs, and weights
--- a/managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse-design.md
@@ -0,0 +1,46 @@
+# Offline Wheelhouse Design
+
+**Date:** 2026-04-08
+
+**Goal:** Add an offline Python dependency bundle for Ubuntu 24.04 x86_64 with Python 3.12 and NVIDIA GPU support so the project can be installed on similar machines without re-downloading PyTorch, TensorFlow, and application wheels.
+
+## Scope
+
+- Target platform: Ubuntu 24.04 x86_64
+- Python version: 3.12
+- GPU runtime: NVIDIA, using CUDA-enabled PyTorch wheels
+- Bundle type: project code + weights + `wheelhouse/`
+- Setup behavior: prefer offline wheels when present, fall back to network otherwise
+
+## Approach
+
+Add a dedicated wheelhouse build script that downloads:
+
+- `pip`, `setuptools`, `wheel`
+- `numpy<2`
+- CUDA-enabled `torch` and `torchvision`
+- `tensorflow[and-cuda]==2.16.1`
+- `tf-keras==2.16.0`
+- project requirements and their transitive dependencies
+
+Store the wheels inside `wheelhouse/` under the project root.
+
+Update the native setup script so it:
+
+1. creates `.venv`
+2. upgrades installer tooling from `wheelhouse/` when available
+3. installs PyTorch and TensorFlow from local wheels when available
+4. installs project requirements from local wheels when available
+5. falls back to online indexes only if the wheelhouse is missing
+
+## Bundle Layout
+
+- `weights/`
+- `wheelhouse/`
+- `setup_native_venv.sh`
+- `build_wheelhouse.sh`
+- `run_rtsp.sh`
+
+## Tradeoff
+
+This increases the lightweight bundle size, but it removes repeat dependency downloads on future hosts. The user explicitly asked for an offline dependency pack, so this is the right tradeoff now.
--- a/managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse.md
@@ -0,0 +1,51 @@
+# Offline Wheelhouse Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a reusable offline wheelhouse for the native x86 bundle and make setup prefer local wheels.
+
+**Architecture:** Keep the native bundle layout, add one build script that downloads all required wheels into `wheelhouse/`, and update the setup script to install from `wheelhouse/` first.
+
+**Tech Stack:** Python 3.12, pip download, wheelhouse, shell scripts
+
+---
+
+### Task 1: Add offline dependency metadata and scripts
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/requirements-native.txt`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/build_wheelhouse.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/setup_native_venv.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README_NATIVE.md`
+
+**Step 1: Add a native requirements file**
+
+- Pin `numpy<2`
+- Include app-level dependencies used by native setup
+
+**Step 2: Add a wheelhouse build script**
+
+- Download installer tools, PyTorch CUDA wheels, TensorFlow wheels, and project wheels
+- Write everything into `wheelhouse/`
+
+**Step 3: Make setup prefer offline wheels**
+
+- Use `--no-index --find-links wheelhouse` when local wheels are available
+- Fall back to online install otherwise
+
+### Task 2: Sync and build the wheelhouse on the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Sync project changes to `192.168.5.154`**
+
+- Preserve existing weights
+
+**Step 2: Run `build_wheelhouse.sh`**
+
+- Populate `/home/x/people/people_flow_project/wheelhouse`
+
+**Step 3: Validate setup behavior**
+
+- Confirm `setup_native_venv.sh` recognizes local wheelhouse
--- a/managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging-design.md
@@ -0,0 +1,31 @@
+# RTSP Heartbeat Logging Design
+
+**Date:** 2026-04-08
+
+**Goal:** Add periodic heartbeat logs to the RTSP pipeline so operators can confirm the stream is still being processed during long 30-minute windows.
+
+## Scope
+
+- Keep the existing RTSP counting behavior unchanged.
+- Print one heartbeat line every 60 seconds while the RTSP loop is running.
+- Include the current demographic counts in the heartbeat output.
+- Do not change JSON payload structure or window timing.
+
+## Heartbeat Format
+
+Each heartbeat line should report:
+
+- runtime seconds
+- current window index
+- current window frame count
+- total people in the active window
+- age counts
+- gender counts
+- unknown attributes
+- last processed timestamp
+
+This output is intended for `tail -f` style monitoring and should remain single-line and compact.
+
+## Approach
+
+Reuse the existing live stats helper to avoid recomputing counting rules in a second place. The RTSP loop already knows when each sampled frame is processed, so it can track the last successful processing timestamp and emit a heartbeat when 60 seconds have elapsed since the last log.
--- a/managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-rtsp-heartbeat-logging.md
@@ -0,0 +1,47 @@
+# RTSP Heartbeat Logging Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add one-line RTSP heartbeat logs every 60 seconds so operators can monitor progress during long windows.
+
+**Architecture:** Extend the RTSP loop with lightweight heartbeat state. Reuse the existing live stats builder and print one compact log line every 60 seconds after sampled frames are processed.
+
+**Tech Stack:** Python, dataclasses, OpenCV, existing people-flow pipeline
+
+---
+
+### Task 1: Add heartbeat state and log output
+
+**Files:**
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py`
+
+**Step 1: Track heartbeat timing**
+
+- Store the process start time.
+- Store the next heartbeat deadline.
+- Store the last successful processed timestamp.
+
+**Step 2: Print one-line heartbeat logs**
+
+- Reuse current live stats.
+- Include runtime, window index, frame count, totals, demographics, unknown count, and last processed timestamp.
+
+**Step 3: Keep the logging cadence stable**
+
+- Emit at most one heartbeat per 60 seconds.
+- Do not log on every frame.
+
+### Task 2: Validate and synchronize
+
+**Files:**
+- No additional files required
+
+**Step 1: Run compile checks**
+
+Run: `python3 -m compileall main.py src`
+Expected: PASS
+
+**Step 2: Sync to remote host**
+
+- Replace the remote project with the updated local copy.
+- Keep the existing remote backup intact.
--- a/managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow-design.md
@@ -0,0 +1,116 @@
+# RTSP Windowed People Flow Design
+
+**Date:** 2026-04-08
+
+**Goal:** Extend the existing people-flow project with an RTSP mode that samples one frame per second from a live stream, computes people-flow and demographics, and writes a JSON summary every 30 minutes while preserving the existing offline video and batch modes.
+
+## Scope
+
+- Keep the existing `video` and `batch` commands unchanged.
+- Add a new `rtsp` command for continuous live-stream processing.
+- Sample one frame per second based on wall-clock time instead of processing every decoded frame.
+- Maintain a 30-minute independent counting window.
+- Write one timestamped JSON file per finished window.
+- Refresh a `latest.json` file on every window flush.
+- Do not save annotated RTSP video by default.
+- Back up the current project before implementation.
+
+## Approach
+
+The current codebase already has reusable counting and attribute aggregation logic. The least risky change is to keep the offline pipeline as-is and add a dedicated RTSP processing path that reuses the same `LineCrossCounter` and `AttributeAggregator` components.
+
+The RTSP path will:
+
+1. Open an RTSP stream with OpenCV.
+2. Read frames continuously.
+3. Run inference only when at least one second has elapsed since the last processed frame.
+4. Accumulate counts inside the current 30-minute window.
+5. Flush a window summary to JSON when the window boundary is reached.
+6. Reset all per-window state and continue into the next window.
+7. Retry the stream connection when the RTSP source drops.
+
+## Data Flow
+
+### Command Layer
+
+- `main.py` adds an `rtsp` subcommand with an `--input` RTSP URL.
+- Existing global arguments such as `--config`, `--output-dir`, `--line`, and `--device` remain shared.
+- RTSP mode disables video writing by default unless explicitly enabled in config later.
+
+### Configuration
+
+Add a new RTSP config section with:
+
+- `sample_interval_seconds`
+- `window_seconds`
+- `reconnect_delay_seconds`
+- `stream_open_timeout_seconds`
+- `idle_sleep_seconds`
+- `output_subdir`
+
+This keeps timing and output behavior configurable without changing code.
+
+### Processing Loop
+
+Each processed frame will:
+
+1. Pass through YOLO tracking.
+2. Extract `person` track observations.
+3. Optionally run DeepFace sampling on eligible tracks.
+4. Update the line-cross counter.
+5. Check whether the active 30-minute window should be flushed.
+
+Skipped frames are decoded only to keep the stream current; they do not go through YOLO or DeepFace.
+
+### Window Boundaries
+
+Each window starts when the RTSP pipeline starts or right after the previous flush. The summary payload includes:
+
+- `source_type`
+- `source`
+- `window_index`
+- `window_start`
+- `window_end`
+- `window_duration_seconds`
+- `total_people`
+- `age_counts`
+- `gender_counts`
+- `unknown_attributes`
+- `tracks`
+
+After flushing:
+
+- The timestamped JSON is written under `windows/`.
+- `latest.json` is overwritten with the same payload.
+- The counting and attribute state is reset.
+
+## Output Layout
+
+For `--output-dir /path/output`, the RTSP outputs live under:
+
+- `/path/output/rtsp_stream/`
+- `/path/output/rtsp_stream/latest.json`
+- `/path/output/rtsp_stream/windows/stats_YYYY-MM-DD_HH-MM-SS.json`
+
+The timestamp in the filename is the window end time.
+
+## Error Handling
+
+- If the RTSP stream cannot be opened, retry after a configurable delay.
+- If frame reads fail mid-stream, release the capture and reconnect.
+- If DeepFace analysis fails on a crop, treat that sample as unknown and keep running.
+- If a window has zero crossings, still write a valid JSON payload with zero counts so downstream consumers can distinguish inactivity from pipeline failure.
+
+## Compatibility
+
+- `video` mode still writes annotated video and a final JSON after full processing.
+- `batch` mode still writes a final CSV summary.
+- Existing config keys remain valid.
+
+## Testing Strategy
+
+- Validate CLI parsing for the new `rtsp` command.
+- Validate config loading with the new RTSP section.
+- Validate that RTSP mode writes windowed JSON payloads and refreshes `latest.json`.
+- Validate that 30-minute windows reset counts instead of accumulating indefinitely.
+- Keep offline mode behavior intact by running `--help` and Python compile checks.
--- a/managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow.md
@@ -0,0 +1,131 @@
+# 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
--- a/managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration-design.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration-design.md
@@ -0,0 +1,79 @@
+# x86 Docker Migration Design
+
+**Date:** 2026-04-08
+
+**Goal:** Package the RTSP people-flow project for direct use on an Ubuntu 24.04 x86_64 host with an NVIDIA RTX 3080 by using Docker, bundled project files, and host-side model weights.
+
+## Scope
+
+- Target host: `xiaozheng@192.168.5.154`
+- Target path: `/home/x/people`
+- Runtime model: Docker with NVIDIA runtime
+- Input source: RTSP
+- Output: JSON window summaries under a mounted host directory
+- Include required model weights on the target host
+
+## Why Docker
+
+The existing remote runtime was built on Jetson ARM64 and cannot be reused on an x86_64 RTX 3080 machine. The target host only has Python 3.12 installed, and a native port would need additional interpreter and CUDA-specific package work. Docker is the most reliable path because it isolates Python dependencies, preserves a reproducible runtime, and matches the user requirement of direct use on a new CUDA-capable machine.
+
+## Packaging Strategy
+
+### Host Layout
+
+The target host will contain:
+
+- `/home/x/people/people_flow_project/`
+- `/home/x/people/people_flow_project/weights/yolo11n.pt`
+- `/home/x/people/people_flow_project/weights/deepface/age_model_weights.h5`
+- `/home/x/people/people_flow_project/weights/deepface/gender_model_weights.h5`
+- `/home/x/people/people_flow_project/weights/deepface/retinaface.h5`
+- `/home/x/people/output/`
+
+### Container Layout
+
+The container will:
+
+- run on Python 3.12
+- install GPU-enabled PyTorch wheels
+- install the application dependencies
+- read YOLO and DeepFace weights from deterministic in-container paths
+- write outputs to a mounted host output directory
+
+The project source will be copied into the image at build time. The host-side `weights/` directory will also be part of the build context so the final image does not need to download weights on first start.
+
+## Runtime Contract
+
+The image is intended to be built once on the target host and then started with a single `docker run` command using `--gpus all`.
+
+The container command will remain the existing CLI:
+
+`python main.py --config ... --output-dir ... --device cuda:0 rtsp --input ...`
+
+## System Adaptation
+
+The target host already has:
+
+- Ubuntu 24.04
+- Docker installed
+- NVIDIA runtime registered in Docker
+
+The adaptation work is therefore limited to:
+
+- adding the project’s Docker packaging files
+- transferring project code and model weights
+- building the image on the target host
+- validating the container entrypoint and GPU runtime path
+
+## Risks
+
+- The target GPU is currently heavily occupied by another process, so a full inference validation may need to avoid competing for memory.
+- DeepFace and TensorFlow increase image size and build time.
+- Network access is required during image build unless a wheel cache is prepared separately.
+
+## Success Criteria
+
+- The target host contains the project and all required weights under `/home/x/people`
+- `docker build` completes successfully
+- The container can run `main.py rtsp --help`
+- The final run command is documented for direct RTSP use
--- a/managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration.md
+++ b/managed/people_flow_project/docs/plans/2026-04-08-x86-docker-migration.md
@@ -0,0 +1,77 @@
+# x86 Docker Migration Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the RTSP people-flow project directly usable on Ubuntu 24.04 x86_64 with an RTX 3080 by transferring code and weights and building a Docker image on the target host.
+
+**Architecture:** Use a Docker-based runtime for Python 3.12, GPU-enabled PyTorch, DeepFace, and the existing project CLI. Keep weights in a deterministic project directory and bake them into the image during build so runtime startup does not trigger downloads.
+
+**Tech Stack:** Docker, NVIDIA Container Runtime, Python 3.12, PyTorch, Ultralytics, DeepFace
+
+---
+
+### Task 1: Add Docker packaging files
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/Dockerfile`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/docker-compose.yml`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/.dockerignore`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/scripts/run_rtsp_docker.sh`
+- Modify: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/README.md`
+
+**Step 1: Define the image build**
+
+- Base the image on Python 3.12.
+- Install required OS packages for OpenCV and ffmpeg.
+- Install GPU-enabled PyTorch and project dependencies.
+- Copy project source and weights into the image.
+
+**Step 2: Add a Docker run wrapper**
+
+- Provide a shell script that accepts RTSP URL and output directory.
+- Use `--gpus all`.
+
+**Step 3: Update the README**
+
+- Document the Docker build and run commands.
+- Document where weights must live if the host directory is rebuilt.
+
+### Task 2: Prepare the project tree for weights
+
+**Files:**
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/weights/.gitkeep`
+- Create: `/Users/zxmacmini1/Documents/人流检测/people_flow_project/weights/deepface/.gitkeep`
+
+**Step 1: Create weight directories**
+
+- Reserve stable paths for YOLO and DeepFace weights.
+
+### Task 3: Transfer the project and weights to the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Copy the project**
+
+- Transfer the project directory to `/home/x/people/people_flow_project`.
+
+**Step 2: Copy YOLO and DeepFace weights**
+
+- Place YOLO and DeepFace weights into the target project `weights/` tree.
+
+### Task 4: Build and validate on the target host
+
+**Files:**
+- No code changes required
+
+**Step 1: Build the image**
+
+- Run `docker build` under `/home/x/people/people_flow_project`.
+
+**Step 2: Validate the CLI**
+
+- Run the container with `python main.py rtsp --help`.
+
+**Step 3: Provide the final RTSP run command**
+
+- Document the exact `docker run` invocation for the target host.
--- a/managed/people_flow_project/main.py
+++ b/managed/people_flow_project/main.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="People-flow counting with YOLO tracking and DeepFace demographics."
+    )
+    parser.add_argument(
+        "--config",
+        default="configs/default_config.yaml",
+        help="Path to the YAML config file.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=None,
+        help="Directory for generated artifacts.",
+    )
+    parser.add_argument(
+        "--line",
+        help="Override counting line as x1,y1,x2,y2.",
+    )
+    parser.add_argument(
+        "--line-mode",
+        choices=["normalized", "pixel"],
+        help="Coordinate mode for --line.",
+    )
+    parser.add_argument(
+        "--device",
+        help="Override inference device, for example cuda:0 or cpu.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    video_parser = subparsers.add_parser("video", help="Process one video.")
+    video_parser.add_argument("--input", required=True, help="Path to the video file.")
+    video_parser.add_argument(
+        "--skip-video-save",
+        action="store_true",
+        help="Do not write the annotated video.",
+    )
+
+    batch_parser = subparsers.add_parser("batch", help="Process a directory of videos.")
+    batch_parser.add_argument(
+        "--input-dir",
+        required=True,
+        help="Directory scanned recursively for videos.",
+    )
+    batch_parser.add_argument(
+        "--pattern",
+        default="*.mp4",
+        help="Glob pattern used during recursive discovery.",
+    )
+    batch_parser.add_argument(
+        "--skip-video-save",
+        action="store_true",
+        help="Do not write annotated videos.",
+    )
+
+    rtsp_parser = subparsers.add_parser("rtsp", help="Process a live RTSP stream.")
+    rtsp_parser.add_argument("--input", help="RTSP URL.")
+
+    manage_api_parser = subparsers.add_parser("manage-api", help="Start the management API.")
+    manage_api_parser.add_argument("--host", default="0.0.0.0", help="Host for the management API.")
+    manage_api_parser.add_argument("--port", type=int, default=18082, help="Port for the management API.")
+
+    return parser
+
+
+def build_config(args: argparse.Namespace):
+    from src.people_flow.config import load_config, merge_cli_overrides
+
+    save_video = None
+    if hasattr(args, "skip_video_save"):
+        save_video = not args.skip_video_save
+
+    config = load_config(Path(args.config))
+    return merge_cli_overrides(
+        config=config,
+        line=args.line,
+        line_mode=args.line_mode,
+        device=args.device,
+        save_video=save_video,
+    )
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "manage-api":
+        from src.people_flow.manage_api import run_manage_api
+
+        run_manage_api(args.config, host=args.host, port=args.port)
+        return 0
+
+    config = build_config(args)
+    from src.people_flow.pipeline import PeopleFlowPipeline, discover_videos
+
+    output_root = Path(args.output_dir or config.runtime.output_dir)
+    pipeline = PeopleFlowPipeline(config=config, output_root=output_root)
+
+    if args.command == "rtsp":
+        paths = pipeline.get_rtsp_output_paths()
+        print(f"rtsp_output_dir={paths['root']}", flush=True)
+        print(f"latest_json={paths['latest_json']}", flush=True)
+        source = args.input or config.runtime.rtsp_url
+        if not source:
+            raise SystemExit("RTSP source is required. Pass --input or set runtime.rtsp_url in the config.")
+        pipeline.process_rtsp(source)
+        return 0
+
+    if args.command == "video":
+        result = pipeline.process_video(Path(args.input))
+        print(f"processed_video={result['video_name']}")
+        print(f"total_people={result['total_people']}")
+        print(f"unknown_attributes={result['unknown_attributes']}")
+        print(f"json={result['json_path']}")
+        if result.get("video_output_path"):
+            print(f"annotated_video={result['video_output_path']}")
+        return 0
+
+    videos = discover_videos(Path(args.input_dir), pattern=args.pattern)
+    if not videos:
+        raise SystemExit(f"No videos found under {args.input_dir} with pattern {args.pattern}")
+
+    summary = pipeline.process_batch(videos)
+    print(f"videos_processed={len(summary['videos'])}")
+    print(f"csv={summary['csv_path']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/managed/people_flow_project/pyproject.toml
+++ b/managed/people_flow_project/pyproject.toml
@@ -0,0 +1,11 @@
+[project]
+name = "people-flow-project"
+version = "0.1.0"
+description = "Street video people-flow counting with YOLO tracking and face-based age/gender estimation"
+readme = "README.md"
+requires-python = ">=3.10,<3.13"
+dependencies = []
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
--- a/managed/people_flow_project/requirements-docker.txt
+++ b/managed/people_flow_project/requirements-docker.txt
@@ -0,0 +1,7 @@
+flask>=3.1.0
+ultralytics>=8.3.0
+opencv-python-headless>=4.10.0
+deepface>=0.0.93
+pyyaml>=6.0.2
+pandas>=2.2.3
+numpy<2
--- a/managed/people_flow_project/requirements-native.txt
+++ b/managed/people_flow_project/requirements-native.txt
@@ -0,0 +1,8 @@
+flask>=3.1.0
+numpy<2
+ultralytics==8.4.35
+lap>=0.5.12
+opencv-python==4.11.0.86
+deepface==0.0.99
+pyyaml==6.0.3
+pandas==3.0.2
--- a/managed/people_flow_project/requirements.txt
+++ b/managed/people_flow_project/requirements.txt
@@ -0,0 +1,6 @@
+ultralytics>=8.3.0
+opencv-python>=4.10.0
+deepface>=0.0.93
+pyyaml>=6.0.2
+pandas>=2.2.3
+numpy>=1.26.0
--- a/managed/people_flow_project/run_rtsp.sh
+++ b/managed/people_flow_project/run_rtsp.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+exec "$SCRIPT_DIR/scripts/run.sh" "$@"
--- a/managed/people_flow_project/scripts/docker-entrypoint.sh
+++ b/managed/people_flow_project/scripts/docker-entrypoint.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+set -eu
+
+PROJECT_DIR="/opt/people-flow"
+CONFIG_TEMPLATE="${PROJECT_DIR}/config/config.example.yaml"
+CONFIG_PATH="${CONFIG_PATH:-${PROJECT_DIR}/config/local.yaml}"
+OUTPUT_DIR="${OUTPUT_DIR:-${PROJECT_DIR}/outputs}"
+RTSP_URL="${RTSP_URL:-}"
+API_HOST="${API_HOST:-0.0.0.0}"
+API_PORT="${API_PORT:-18082}"
+
+mkdir -p "${OUTPUT_DIR}" "$(dirname "${CONFIG_PATH}")"
+
+if [ ! -f "${CONFIG_PATH}" ]; then
+  cp "${CONFIG_TEMPLATE}" "${CONFIG_PATH}"
+fi
+
+python - "$CONFIG_PATH" "$RTSP_URL" "$OUTPUT_DIR" <<'PY'
+from pathlib import Path
+import sys
+import yaml
+
+config_path = Path(sys.argv[1])
+rtsp_url = sys.argv[2]
+output_dir = sys.argv[3]
+
+raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+runtime = raw.setdefault("runtime", {})
+if rtsp_url:
+    runtime["rtsp_url"] = rtsp_url
+runtime["output_dir"] = output_dir
+yolo = raw.setdefault("yolo", {})
+yolo.setdefault("model_path", "weights/yolo11n.pt")
+config_path.write_text(
+    yaml.safe_dump(raw, allow_unicode=True, sort_keys=False),
+    encoding="utf-8",
+)
+PY
+
+exec python main.py --config "${CONFIG_PATH}" manage-api --host "${API_HOST}" --port "${API_PORT}"
--- a/managed/people_flow_project/scripts/install.sh
+++ b/managed/people_flow_project/scripts/install.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SETUP_SCRIPT="${PROJECT_DIR}/setup_native_venv.sh"
+RUN_SCRIPT="${PROJECT_DIR}/scripts/run.sh"
+INSTALL_SERVICE_SCRIPT="${PROJECT_DIR}/scripts/install_service.sh"
+PROJECT_USER="${SUDO_USER:-$(id -un)}"
+
+run_privileged() {
+  if [[ "$(id -u)" -eq 0 ]]; then
+    "$@"
+    return
+  fi
+  sudo "$@"
+}
+
+run_project_user() {
+  if [[ "$(id -u)" -eq 0 && -n "${SUDO_USER:-}" ]]; then
+    sudo -u "${PROJECT_USER}" -H "$@"
+    return
+  fi
+  "$@"
+}
+
+ensure_system_package() {
+  local command_name="$1"
+  local package_name="$2"
+  if command -v "${command_name}" >/dev/null 2>&1; then
+    return
+  fi
+
+  echo "Installing missing package: ${package_name}"
+  run_privileged apt-get -o Acquire::ForceIPv4=true update
+  run_privileged apt-get -o Acquire::ForceIPv4=true install -y "${package_name}"
+}
+
+ensure_system_package ffmpeg ffmpeg
+
+if [[ ! -d "/usr/lib/python3.12/venv" && ! -d "/usr/lib/python3.12/ensurepip" ]]; then
+  echo "Installing missing package: python3.12-venv"
+  run_privileged apt-get -o Acquire::ForceIPv4=true update
+  run_privileged apt-get -o Acquire::ForceIPv4=true install -y python3.12-venv
+fi
+
+if ! command -v nvidia-smi >/dev/null 2>&1; then
+  echo "nvidia-smi is required but not installed." >&2
+  exit 1
+fi
+
+run_project_user env PYTHON_BIN="${PYTHON_BIN:-python3.12}" bash "${SETUP_SCRIPT}"
+run_project_user bash "${RUN_SCRIPT}" --prepare-only
+bash "${INSTALL_SERVICE_SCRIPT}"
+run_privileged systemctl enable --now people-flow.service
+
+cat <<EOF
+Offline install complete.
+Service started and enabled on boot: people-flow.service
+Runtime log: ${PROJECT_DIR}/outputs/rtsp_run.log
+EOF
--- a/managed/people_flow_project/scripts/install_service.sh
+++ b/managed/people_flow_project/scripts/install_service.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATE_PATH="${PROJECT_DIR}/deploy/people-flow.service.tpl"
+CONFIG_PATH="${CONFIG_PATH:-${PROJECT_DIR}/config/local.yaml}"
+SERVICE_NAME="${SERVICE_NAME:-people-flow.service}"
+OUTPUT_PATH="${PROJECT_DIR}/deploy/${SERVICE_NAME}"
+RUN_USER="${RUN_USER:-${SUDO_USER:-$(id -un)}}"
+RUN_GROUP="${RUN_GROUP:-$(id -gn "${RUN_USER}")}"
+
+if [[ ! -f "${TEMPLATE_PATH}" ]]; then
+  echo "Missing service template: ${TEMPLATE_PATH}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${CONFIG_PATH}" ]]; then
+  echo "Missing config file: ${CONFIG_PATH}" >&2
+  exit 1
+fi
+
+sed \
+  -e "s|__PROJECT_DIR__|${PROJECT_DIR}|g" \
+  -e "s|__CONFIG_PATH__|${CONFIG_PATH}|g" \
+  -e "s|__RUN_USER__|${RUN_USER}|g" \
+  -e "s|__RUN_GROUP__|${RUN_GROUP}|g" \
+  "${TEMPLATE_PATH}" > "${OUTPUT_PATH}"
+
+sudo cp "${OUTPUT_PATH}" "/etc/systemd/system/${SERVICE_NAME}"
+sudo systemctl daemon-reload
+
+echo "Service installed to /etc/systemd/system/${SERVICE_NAME}"
+echo "Enable and start it with: sudo systemctl enable --now ${SERVICE_NAME}"
--- a/managed/people_flow_project/scripts/run.sh
+++ b/managed/people_flow_project/scripts/run.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VENV_PYTHON="${PROJECT_DIR}/.venv/bin/python"
+CONFIG_TEMPLATE="${PROJECT_DIR}/config/config.example.yaml"
+CONFIG_PATH="${PROJECT_DIR}/config/local.yaml"
+RTSP_URL="${RTSP_URL:-rtsp://user:password@camera-ip:554/h264/ch1/main/av_stream}"
+OUTPUT_DIR="${OUTPUT_DIR:-${PROJECT_DIR}/outputs}"
+PREPARE_ONLY=0
+
+if [[ "${1:-}" == "--prepare-only" ]]; then
+  PREPARE_ONLY=1
+  shift
+fi
+
+if [[ ! -x "${VENV_PYTHON}" ]]; then
+  echo "Virtual environment is missing. Run scripts/install.sh first." >&2
+  exit 1
+fi
+
+if [[ "${RTSP_URL}" == "rtsp://user:password@camera-ip:554/h264/ch1/main/av_stream" ]]; then
+  echo "Please edit scripts/run.sh and set RTSP_URL before starting." >&2
+  exit 1
+fi
+
+mkdir -p "${OUTPUT_DIR}" "${PROJECT_DIR}/config"
+
+cp "${CONFIG_TEMPLATE}" "${CONFIG_PATH}"
+sed -i.bak \
+  -e "s|^  rtsp_url: .*|  rtsp_url: \"${RTSP_URL}\"|" \
+  -e "s|^  output_dir: .*|  output_dir: \"${OUTPUT_DIR}\"|" \
+  "${CONFIG_PATH}"
+rm -f "${CONFIG_PATH}.bak"
+
+if [[ "${PREPARE_ONLY}" -eq 1 ]]; then
+  echo "Prepared config at ${CONFIG_PATH}"
+  exit 0
+fi
+
+exec "${VENV_PYTHON}" "${PROJECT_DIR}/main.py" --config "${CONFIG_PATH}" rtsp "$@"
--- a/managed/people_flow_project/scripts/run_rtsp_docker.sh
+++ b/managed/people_flow_project/scripts/run_rtsp_docker.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <rtsp_url> <host_output_dir>"
+  exit 1
+fi
+
+RTSP_URL="$1"
+HOST_OUTPUT_DIR="$2"
+
+mkdir -p "$HOST_OUTPUT_DIR"
+
+docker run -d \
+  --name people-flow-rtsp \
+  --restart unless-stopped \
+  --network host \
+  --gpus all \
+  --shm-size 1g \
+  -v "$HOST_OUTPUT_DIR:/opt/people-flow/output" \
+  people-flow-rtsp:x86-cuda \
+  --config /opt/people-flow/configs/docker_x86_config.yaml \
+  --output-dir /opt/people-flow/output \
+  --device cuda:0 \
+  rtsp \
+  --input "$RTSP_URL"
--- a/managed/people_flow_project/setup_native_venv.sh
+++ b/managed/people_flow_project/setup_native_venv.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$SCRIPT_DIR"
+WHEELHOUSE_DIR="$PROJECT_ROOT/wheelhouse"
+DEEPFACE_SOURCE_DIR="$PROJECT_ROOT/weights/deepface"
+DEEPFACE_TARGET_DIR="${HOME}/.deepface/weights"
+PYTHON_BIN="${PYTHON_BIN:-python3.12}"
+
+cd "$PROJECT_ROOT"
+
+"$PYTHON_BIN" -m venv .venv
+source .venv/bin/activate
+
+if [[ -d "$WHEELHOUSE_DIR" ]] && find "$WHEELHOUSE_DIR" -maxdepth 1 -name '*.whl' | grep -q .; then
+  python -m pip install --no-index --find-links "$WHEELHOUSE_DIR" --upgrade pip setuptools wheel
+  pip install --no-index --find-links "$WHEELHOUSE_DIR" "numpy<2"
+  pip install --no-index --find-links "$WHEELHOUSE_DIR" torch torchvision
+  pip install --no-index --find-links "$WHEELHOUSE_DIR" "tensorflow[and-cuda]==2.16.1" "tf-keras==2.16.0"
+  pip install --no-index --find-links "$WHEELHOUSE_DIR" -r requirements-native.txt
+else
+  python -m pip install --upgrade pip setuptools wheel
+  pip install "numpy<2"
+  pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision
+  pip install "tensorflow[and-cuda]==2.16.1" "tf-keras==2.16.0"
+  pip install -r requirements-native.txt
+fi
+
+mkdir -p "$DEEPFACE_TARGET_DIR"
+if find "$DEEPFACE_SOURCE_DIR" -maxdepth 1 -name '*.h5' | grep -q .; then
+  cp -f "$DEEPFACE_SOURCE_DIR"/*.h5 "$DEEPFACE_TARGET_DIR"/
+else
+  echo "Warning: missing bundled DeepFace weights under $DEEPFACE_SOURCE_DIR"
+  echo "Attribute analysis will stay unavailable until the .h5 files are provided."
+fi
+
+echo "venv_ready=$PROJECT_ROOT/.venv"
--- a/managed/people_flow_project/src/people_flow/init.py
+++ b/managed/people_flow_project/src/people_flow/init.py
@@ -0,0 +1 @@
+"""People flow analysis package."""
--- a/managed/people_flow_project/src/people_flow/attributes.py
+++ b/managed/people_flow_project/src/people_flow/attributes.py
@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from statistics import median
+from typing import Any
+
+import cv2
+import numpy as np
+
+from .models import AttributeConfig, AttributeVote, TrackAttributeSummary, TrackObservation
+
+
+def age_to_bucket(age: int) -> str:
+    if age < 18:
+        return "minor"
+    if age < 60:
+        return "adult"
+    return "senior"
+
+
+def normalize_gender(raw_gender: str | None) -> str | None:
+    if not raw_gender:
+        return None
+    lowered = raw_gender.strip().lower()
+    if lowered in {"man", "male"}:
+        return "male"
+    if lowered in {"woman", "female"}:
+        return "female"
+    return None
+
+
+class AttributeAggregator:
+    def __init__(self, config: AttributeConfig) -> None:
+        self.config = config
+        self.votes: dict[int, list[AttributeVote]] = defaultdict(list)
+        self.samples_taken: dict[int, int] = defaultdict(int)
+        self.last_sampled_frame: dict[int, int] = {}
+        self._deepface = self._load_deepface() if config.enabled else None
+
+    def _load_deepface(self) -> Any:
+        try:
+            from deepface import DeepFace
+        except ImportError as exc:
+            raise RuntimeError(
+                "DeepFace is not installed. Install dependencies with `pip install -r requirements.txt`."
+            ) from exc
+        return DeepFace
+
+    def maybe_collect(self, frame: np.ndarray, frame_index: int, track: TrackObservation) -> None:
+        if self._deepface is None:
+            return
+        if self.samples_taken[track.track_id] >= self.config.max_samples_per_track:
+            return
+        last_frame = self.last_sampled_frame.get(track.track_id)
+        if last_frame is not None and frame_index - last_frame < self.config.sample_every_n_frames:
+            return
+
+        x1, y1, x2, y2 = track.bbox
+        width = x2 - x1
+        height = y2 - y1
+        if width < self.config.min_person_box_width or height < self.config.min_person_box_height:
+            return
+
+        crop = self._crop_person(frame, track.bbox)
+        if crop.size == 0:
+            return
+
+        vote = self._analyze_crop(crop)
+        self.last_sampled_frame[track.track_id] = frame_index
+        if vote is None:
+            return
+
+        self.samples_taken[track.track_id] += 1
+        self.votes[track.track_id].append(vote)
+
+    def reset(self) -> None:
+        self.votes.clear()
+        self.samples_taken.clear()
+        self.last_sampled_frame.clear()
+
+    def _crop_person(self, frame: np.ndarray, bbox: tuple[int, int, int, int]) -> np.ndarray:
+        x1, y1, x2, y2 = bbox
+        height, width = frame.shape[:2]
+        pad_x = int((x2 - x1) * self.config.person_crop_padding)
+        pad_y = int((y2 - y1) * self.config.person_crop_padding)
+        left = max(0, x1 - pad_x)
+        top = max(0, y1 - pad_y)
+        right = min(width, x2 + pad_x)
+        bottom = min(height, y2 + pad_y)
+        return frame[top:bottom, left:right]
+
+    def _analyze_crop(self, crop: np.ndarray) -> AttributeVote | None:
+        rgb_crop = cv2.cvtColor(crop, cv2.COLOR_BGR2RGB)
+        try:
+            analysis = self._deepface.analyze(
+                img_path=rgb_crop,
+                actions=["age", "gender"],
+                detector_backend=self.config.detector_backend,
+                enforce_detection=self.config.enforce_detection,
+                silent=True,
+            )
+        except Exception:
+            return None
+
+        if isinstance(analysis, list):
+            if not analysis:
+                return None
+            analysis = analysis[0]
+
+        age_value = analysis.get("age")
+        gender_value = normalize_gender(analysis.get("dominant_gender"))
+        if age_value is None or gender_value is None:
+            return None
+
+        age_int = int(round(float(age_value)))
+        return AttributeVote(
+            age=age_int,
+            age_bucket=age_to_bucket(age_int),
+            gender=gender_value,
+        )
+
+    def summarize_track(self, track_id: int) -> TrackAttributeSummary | None:
+        votes = self.votes.get(track_id, [])
+        if not votes:
+            return None
+
+        age_bucket_counts = Counter(vote.age_bucket for vote in votes)
+        gender_counts = Counter(vote.gender for vote in votes)
+        if not age_bucket_counts or not gender_counts:
+            return None
+
+        age_bucket = age_bucket_counts.most_common(1)[0][0]
+        gender = gender_counts.most_common(1)[0][0]
+        age_value = int(round(median(vote.age for vote in votes)))
+        return TrackAttributeSummary(
+            track_id=track_id,
+            age=age_value,
+            age_bucket=age_bucket,
+            gender=gender,
+            samples_used=len(votes),
+        )
--- a/managed/people_flow_project/src/people_flow/config.py
+++ b/managed/people_flow_project/src/people_flow/config.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+import yaml
+
+from .models import (
+    AppConfig,
+    AttributeConfig,
+    CountingConfig,
+    OutputConfig,
+    RtspConfig,
+    RuntimeConfig,
+    YoloConfig,
+)
+
+
+def _read_yaml(config_path: Path) -> dict:
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+    with config_path.open("r", encoding="utf-8") as handle:
+        loaded = yaml.safe_load(handle) or {}
+    if not isinstance(loaded, dict):
+        raise ValueError(f"Config file must contain a mapping: {config_path}")
+    return loaded
+
+
+def load_config_document(config_path: Path) -> dict:
+    return _read_yaml(config_path)
+
+
+def save_config_document(config_path: Path, payload: dict) -> None:
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = config_path.with_suffix(config_path.suffix + ".tmp")
+    temp_path.write_text(
+        yaml.safe_dump(payload, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+    temp_path.replace(config_path)
+
+
+def resolve_project_root(config_path: Path) -> Path:
+    return config_path.expanduser().resolve().parent.parent
+
+
+def resolve_project_path(project_root: Path, raw_path: str | Path) -> Path:
+    path = Path(raw_path)
+    if path.is_absolute():
+        return path.resolve()
+    return (project_root.resolve() / path).resolve()
+
+
+def load_config(config_path: Path) -> AppConfig:
+    data = _read_yaml(config_path)
+    config = AppConfig(
+        yolo=YoloConfig(**data.get("yolo", {})),
+        counting=CountingConfig(**_normalize_counting_config(data.get("counting", {}))),
+        attributes=AttributeConfig(**data.get("attributes", {})),
+        output=OutputConfig(**data.get("output", {})),
+        rtsp=RtspConfig(**data.get("rtsp", {})),
+        runtime=RuntimeConfig(**data.get("runtime", {})),
+        config_path=config_path.resolve(),
+    )
+    return config
+
+
+def _normalize_counting_config(data: dict) -> dict:
+    normalized = dict(data)
+    line = normalized.get("line")
+    if line is not None:
+        normalized["line"] = tuple(float(value) for value in line)
+    return normalized
+
+
+def parse_line_override(raw_line: str) -> tuple[float, float, float, float]:
+    parts = [part.strip() for part in raw_line.split(",")]
+    if len(parts) != 4:
+        raise ValueError("--line must contain exactly four comma-separated values")
+    return tuple(float(part) for part in parts)  # type: ignore[return-value]
+
+
+def merge_cli_overrides(
+    config: AppConfig,
+    line: str | None,
+    line_mode: str | None,
+    device: str | None,
+    save_video: bool | None,
+) -> AppConfig:
+    updated = config
+    if line:
+        updated.counting = replace(updated.counting, line=parse_line_override(line))
+    if line_mode:
+        updated.counting = replace(updated.counting, line_mode=line_mode)
+    if device:
+        updated.yolo = replace(updated.yolo, device=device)
+    if save_video is not None:
+        updated.output = replace(updated.output, save_video=save_video)
+    return updated
--- a/managed/people_flow_project/src/people_flow/counting.py
+++ b/managed/people_flow_project/src/people_flow/counting.py
@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from .models import CountingConfig, CrossingEvent, TrackObservation
+
+
+def _line_side(
+    point: tuple[float, float], line: tuple[float, float, float, float]
+) -> float:
+    px, py = point
+    x1, y1, x2, y2 = line
+    return (x2 - x1) * (py - y1) - (y2 - y1) * (px - x1)
+
+
+class LineCrossCounter:
+    def __init__(self, line: tuple[float, float, float, float], config: CountingConfig) -> None:
+        self.line = line
+        self.config = config
+        self.previous_side: dict[int, float] = {}
+        self.counted_ids: set[int] = set()
+        self.crossings: list[CrossingEvent] = []
+
+    def update(self, observations: list[TrackObservation]) -> list[CrossingEvent]:
+        events: list[CrossingEvent] = []
+        for observation in observations:
+            side = _line_side(observation.center, self.line)
+            previous = self.previous_side.get(observation.track_id)
+            self.previous_side[observation.track_id] = side
+
+            if observation.track_id in self.counted_ids:
+                continue
+            if previous is None:
+                continue
+            if abs(previous) <= self.config.crossing_tolerance or abs(side) <= self.config.crossing_tolerance:
+                continue
+            if previous * side >= 0:
+                continue
+
+            direction = "negative_to_positive" if previous < 0 < side else "positive_to_negative"
+            event = CrossingEvent(track_id=observation.track_id, direction=direction)
+            self.counted_ids.add(observation.track_id)
+            self.crossings.append(event)
+            events.append(event)
+        return events
+
+    def reset(self) -> None:
+        self.previous_side.clear()
+        self.counted_ids.clear()
+        self.crossings.clear()
+
+    @property
+    def total_people(self) -> int:
+        return len(self.counted_ids)
--- a/managed/people_flow_project/src/people_flow/io_utils.py
+++ b/managed/people_flow_project/src/people_flow/io_utils.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+import cv2
+
+from .models import TrackObservation
+
+
+def ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def make_video_writer(path: Path, width: int, height: int, fps: float) -> cv2.VideoWriter:
+    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+    return cv2.VideoWriter(str(path), fourcc, fps if fps > 0 else 25.0, (width, height))
+
+
+def write_json(path: Path, payload: dict) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, ensure_ascii=True, indent=2)
+
+
+def write_csv(path: Path, rows: list[dict]) -> None:
+    import pandas as pd
+
+    dataframe = pd.DataFrame(rows)
+    dataframe.to_csv(path, index=False)
+
+
+def write_window_json(windows_dir: Path, latest_path: Path, payload: dict, window_end: datetime) -> Path:
+    ensure_dir(windows_dir)
+    ensure_dir(latest_path.parent)
+    target = windows_dir / f"stats_{window_end.strftime('%Y-%m-%d_%H-%M-%S')}.json"
+    write_json(target, payload)
+    write_json(latest_path, payload)
+    return target
+
+
+def draw_line(frame, line: tuple[float, float, float, float]) -> None:
+    x1, y1, x2, y2 = (int(value) for value in line)
+    cv2.line(frame, (x1, y1), (x2, y2), (0, 255, 255), 2)
+
+
+def draw_tracks(
+    frame,
+    observations: list[TrackObservation],
+    counted_ids: set[int],
+    draw_labels: bool,
+) -> None:
+    for observation in observations:
+        x1, y1, x2, y2 = observation.bbox
+        color = (0, 200, 0) if observation.track_id in counted_ids else (255, 140, 0)
+        cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
+        if draw_labels:
+            label = f"id={observation.track_id} conf={observation.confidence:.2f}"
+            cv2.putText(
+                frame,
+                label,
+                (x1, max(20, y1 - 6)),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.5,
+                color,
+                1,
+                cv2.LINE_AA,
+            )
+
+
+def draw_stats(frame, stats: dict) -> None:
+    lines = [
+        f"total_people: {stats['total_people']}",
+        f"minor: {stats['age_counts']['minor']}",
+        f"adult: {stats['age_counts']['adult']}",
+        f"senior: {stats['age_counts']['senior']}",
+        f"male: {stats['gender_counts']['male']}",
+        f"female: {stats['gender_counts']['female']}",
+        f"unknown_attributes: {stats['unknown_attributes']}",
+    ]
+    x = 12
+    y = 24
+    for text in lines:
+        cv2.putText(
+            frame,
+            text,
+            (x, y),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.65,
+            (255, 255, 255),
+            2,
+            cv2.LINE_AA,
+        )
+        y += 24
--- a/managed/people_flow_project/src/people_flow/manage_api.py
+++ b/managed/people_flow_project/src/people_flow/manage_api.py
@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import json
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from flask import Flask, jsonify, request, send_file
+
+from .config import (
+    load_config,
+    load_config_document,
+    resolve_project_path,
+    resolve_project_root,
+    save_config_document,
+)
+
+
+PROJECT_TYPE = "people_flow_project"
+DEFAULT_MANAGE_PORT = 18082
+MAX_PREVIEW_LINES = 2000
+
+
+@dataclass(slots=True)
+class ManageContext:
+    config_path: Path
+    project_root: Path
+
+
+def create_app(config_path: str | Path) -> Flask:
+    resolved_config = Path(config_path).expanduser().resolve()
+    ctx = ManageContext(
+        config_path=resolved_config,
+        project_root=resolve_project_root(resolved_config),
+    )
+    app = Flask(__name__)
+    app.config["MANAGE_CONTEXT"] = ctx
+
+    @app.get("/api/manage/health")
+    def get_health():
+        return jsonify(
+            {
+                "status": "ok",
+                "project_type": PROJECT_TYPE,
+                "version": "dev",
+                "runtime_status": "running",
+            }
+        )
+
+    @app.get("/api/manage/config")
+    def get_config():
+        return jsonify(_config_payload(ctx))
+
+    @app.put("/api/manage/config")
+    def update_config():
+        payload = request.get_json(silent=True) or {}
+        rtsp_url = payload.get("rtsp_url")
+        if not isinstance(rtsp_url, str) or not rtsp_url.strip():
+            return jsonify({"error": "rtsp_url is required"}), 400
+
+        raw = load_config_document(ctx.config_path)
+        runtime = raw.setdefault("runtime", {})
+        runtime["rtsp_url"] = rtsp_url.strip()
+        save_config_document(ctx.config_path, raw)
+        return jsonify(_config_payload(ctx))
+
+    @app.get("/api/manage/summary")
+    def get_summary():
+        return jsonify(_build_summary(ctx))
+
+    @app.get("/api/manage/windows")
+    def get_windows():
+        page = max(_int_arg("page", 1), 1)
+        page_size = max(_int_arg("page_size", 24), 1)
+        limit = request.args.get("limit")
+
+        items = list(_load_window_stats(ctx))
+        if limit is not None:
+            items = items[: max(_int_value(limit), 0)]
+
+        start = (page - 1) * page_size
+        end = start + page_size
+        return jsonify(
+            {
+                "items": items[start:end],
+                "page": page,
+                "page_size": page_size,
+                "total": len(items),
+            }
+        )
+
+    @app.get("/api/manage/files")
+    def get_files():
+        return jsonify({"files": _list_result_files(ctx)})
+
+    @app.get("/api/manage/files/preview")
+    def preview_file():
+        target = _resolve_sandbox_file(ctx, request.args.get("path", ""))
+        lines = _tail_lines(target, _bounded_preview_lines(request.args.get("lines")))
+        return jsonify(
+            {
+                "path": _relative_path(ctx, target),
+                "lines": lines,
+                "count": len(lines),
+            }
+        )
+
+    @app.get("/api/manage/files/download")
+    def download_file():
+        target = _resolve_sandbox_file(ctx, request.args.get("path", ""))
+        return send_file(target, as_attachment=True, download_name=target.name)
+
+    @app.errorhandler(ValueError)
+    def handle_value_error(error: ValueError):
+        return jsonify({"error": str(error)}), 400
+
+    @app.errorhandler(FileNotFoundError)
+    def handle_missing_file(error: FileNotFoundError):
+        return jsonify({"error": str(error)}), 404
+
+    return app
+
+
+def run_manage_api(
+    config_path: str | Path,
+    host: str = "0.0.0.0",
+    port: int = DEFAULT_MANAGE_PORT,
+) -> None:
+    app = create_app(config_path)
+    app.run(host=host, port=port)
+
+
+def parse_args() -> ArgumentParser:
+    parser = ArgumentParser(description="People flow management API")
+    parser.add_argument("--config", required=True, help="Path to YAML config file")
+    parser.add_argument("--host", default="0.0.0.0", help="Host for the management API")
+    parser.add_argument("--port", type=int, default=DEFAULT_MANAGE_PORT, help="Port for the management API")
+    return parser
+
+
+def main() -> int:
+    parser = parse_args()
+    args = parser.parse_args()
+    run_manage_api(args.config, host=args.host, port=args.port)
+    return 0
+
+
+def _config_payload(ctx: ManageContext) -> dict:
+    config = load_config(ctx.config_path)
+    output_root = resolve_project_path(ctx.project_root, config.runtime.output_dir)
+    return {
+        "project_type": PROJECT_TYPE,
+        "config_path": str(ctx.config_path),
+        "runtime": {
+            "rtsp_url": config.runtime.rtsp_url,
+            "output_dir": str(output_root),
+        },
+        "rtsp": {
+            "output_subdir": config.rtsp.output_subdir,
+            "window_seconds": config.rtsp.window_seconds,
+        },
+    }
+
+
+def _build_summary(ctx: ManageContext) -> dict:
+    summary_path, payload = _load_summary_payload(ctx)
+    all_window_stats = _load_window_stats(ctx)
+    if payload is None:
+        latest_json = _latest_json_path(ctx)
+        return {
+            "result_type": PROJECT_TYPE,
+            "headline": "No RTSP summary output yet",
+            "metrics": {
+                "latest_path": str(latest_json),
+                "recent_window_stats": all_window_stats[:24],
+                "all_window_stats": all_window_stats,
+            },
+        }
+
+    tracks = payload.get("tracks", [])
+    direction_counts: dict[str, int] = {}
+    if isinstance(tracks, list):
+        for item in tracks:
+            if not isinstance(item, dict):
+                continue
+            direction = _string_value(item.get("direction"))
+            if not direction:
+                continue
+            direction_counts[direction] = direction_counts.get(direction, 0) + 1
+
+    total_people = _int_value(payload.get("total_people"))
+    window_end = _string_value(payload.get("window_end"))
+    return {
+        "result_type": PROJECT_TYPE,
+        "headline": f"Latest window counted {total_people} people",
+        "last_result_time": window_end,
+        "metrics": {
+            "summary_path": str(summary_path) if summary_path else "",
+            "window_start": _string_value(payload.get("window_start")),
+            "window_end": window_end,
+            "total_people": total_people,
+            "direction_counts": direction_counts,
+            "age_counts": _map_string_int(payload.get("age_counts")),
+            "gender_counts": _map_string_int(payload.get("gender_counts")),
+            "unknown_attributes": _int_value(payload.get("unknown_attributes")),
+            "recent_window_stats": all_window_stats[:24],
+            "all_window_stats": all_window_stats,
+        },
+    }
+
+
+def _load_summary_payload(ctx: ManageContext) -> tuple[Path | None, dict | None]:
+    candidates: list[Path] = []
+    latest_json = _latest_json_path(ctx)
+    if latest_json.exists():
+        candidates.append(latest_json)
+
+    window_files = _window_files(ctx)
+    if window_files:
+        candidates.extend(window_files[:1])
+
+    for candidate in candidates:
+        try:
+            payload = json.loads(candidate.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            continue
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"invalid summary json: {candidate}") from exc
+        if isinstance(payload, dict):
+            return candidate, payload
+    return None, None
+
+
+def _load_window_stats(ctx: ManageContext) -> list[dict]:
+    stats: list[dict] = []
+    for path in _window_files(ctx):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError):
+            continue
+        if not isinstance(payload, dict):
+            continue
+        stats.append(
+            {
+                "window_start": _string_value(payload.get("window_start")),
+                "window_end": _string_value(payload.get("window_end")),
+                "total_people": _int_value(payload.get("total_people")),
+                "age_counts": _map_string_int(payload.get("age_counts")),
+                "gender_counts": _map_string_int(payload.get("gender_counts")),
+                "unknown_attributes": _int_value(payload.get("unknown_attributes")),
+            }
+        )
+    stats.sort(key=lambda item: item["window_end"], reverse=True)
+    return stats
+
+
+def _list_result_files(ctx: ManageContext) -> list[dict]:
+    files: list[dict] = []
+    for path, label in (
+        (_latest_json_path(ctx), "Latest Summary"),
+        (_runtime_log_path(ctx), "Runtime Log"),
+    ):
+        if path.exists() and path.is_file():
+            files.append(_build_result_file(ctx, path, label))
+
+    for path in _window_files(ctx):
+        if path.exists() and path.is_file():
+            files.append(_build_result_file(ctx, path, "Window Summary"))
+
+    return files
+
+
+def _build_result_file(ctx: ManageContext, path: Path, label: str) -> dict:
+    info = path.stat()
+    return {
+        "path": _relative_path(ctx, path),
+        "name": path.name,
+        "label": label,
+        "kind": path.suffix.lstrip(".").lower(),
+        "size": info.st_size,
+        "modified_at": datetime.fromtimestamp(info.st_mtime).astimezone().isoformat(),
+    }
+
+
+def _output_root(ctx: ManageContext) -> Path:
+    config = load_config(ctx.config_path)
+    return resolve_project_path(ctx.project_root, config.runtime.output_dir)
+
+
+def _rtsp_output_root(ctx: ManageContext) -> Path:
+    config = load_config(ctx.config_path)
+    return _output_root(ctx) / config.rtsp.output_subdir
+
+
+def _latest_json_path(ctx: ManageContext) -> Path:
+    return _rtsp_output_root(ctx) / "latest.json"
+
+
+def _windows_dir(ctx: ManageContext) -> Path:
+    return _rtsp_output_root(ctx) / "windows"
+
+
+def _runtime_log_path(ctx: ManageContext) -> Path:
+    return _output_root(ctx) / "rtsp_run.log"
+
+
+def _window_files(ctx: ManageContext) -> list[Path]:
+    windows_dir = _windows_dir(ctx)
+    if not windows_dir.exists():
+        return []
+    return sorted(
+        [path for path in windows_dir.iterdir() if path.is_file()],
+        key=lambda path: path.name,
+        reverse=True,
+    )
+
+
+def _resolve_sandbox_file(ctx: ManageContext, raw_path: str) -> Path:
+    relative = raw_path.strip().lstrip("/")
+    if not relative:
+        raise ValueError("path is required")
+
+    target = (ctx.project_root / relative).resolve()
+    project_root = ctx.project_root.resolve()
+    if target != project_root and project_root not in target.parents:
+        raise ValueError("invalid file path")
+    if not target.exists() or not target.is_file():
+        raise FileNotFoundError(relative)
+    return target
+
+
+def _relative_path(ctx: ManageContext, target: Path) -> str:
+    return target.resolve().relative_to(ctx.project_root.resolve()).as_posix()
+
+
+def _tail_lines(path: Path, line_count: int) -> list[str]:
+    lines: list[str] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for raw_line in handle:
+            lines.append(raw_line.rstrip("\n"))
+            if len(lines) > line_count:
+                lines = lines[1:]
+    return lines
+
+
+def _bounded_preview_lines(raw_value: str | None) -> int:
+    if raw_value is None:
+        return 200
+    value = _int_value(raw_value)
+    if value <= 0:
+        return 200
+    return min(value, MAX_PREVIEW_LINES)
+
+
+def _int_arg(name: str, default: int) -> int:
+    value = request.args.get(name)
+    if value is None:
+        return default
+    return _int_value(value)
+
+
+def _string_value(value) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _int_value(value) -> int:
+    if value is None:
+        return 0
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    try:
+        return int(str(value).strip())
+    except ValueError:
+        return 0
+
+
+def _map_string_int(value) -> dict[str, int]:
+    if not isinstance(value, dict):
+        return {}
+    return {str(key): _int_value(raw) for key, raw in value.items()}
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/managed/people_flow_project/src/people_flow/models.py
+++ b/managed/people_flow_project/src/people_flow/models.py
@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class YoloConfig:
+    model_path: str = "yolo11n.pt"
+    tracker: str = "botsort.yaml"
+    conf: float = 0.35
+    iou: float = 0.5
+    imgsz: int = 1280
+    device: str = "cuda:0"
+
+
+@dataclass
+class CountingConfig:
+    line: tuple[float, float, float, float] = (0.1, 0.55, 0.9, 0.55)
+    line_mode: str = "normalized"
+    crossing_tolerance: float = 12.0
+
+    def to_pixel_line(self, width: int, height: int) -> tuple[float, float, float, float]:
+        x1, y1, x2, y2 = self.line
+        if self.line_mode == "pixel":
+            return x1, y1, x2, y2
+        return x1 * width, y1 * height, x2 * width, y2 * height
+
+
+@dataclass
+class AttributeConfig:
+    enabled: bool = True
+    sample_every_n_frames: int = 12
+    max_samples_per_track: int = 5
+    min_person_box_width: int = 80
+    min_person_box_height: int = 160
+    person_crop_padding: float = 0.15
+    detector_backend: str = "retinaface"
+    enforce_detection: bool = False
+
+
+@dataclass
+class OutputConfig:
+    save_video: bool = True
+    save_json: bool = True
+    save_csv: bool = True
+    draw_boxes: bool = True
+    draw_labels: bool = True
+
+
+@dataclass
+class RtspConfig:
+    sample_interval_seconds: float = 1.0
+    window_seconds: int = 1800
+    reconnect_delay_seconds: float = 5.0
+    stream_open_timeout_seconds: float = 10.0
+    idle_sleep_seconds: float = 0.05
+    output_subdir: str = "rtsp_stream"
+
+
+@dataclass
+class RuntimeConfig:
+    rtsp_url: str = "rtsp://user:password@camera-ip:554/h264/ch1/main/av_stream"
+    output_dir: str = "outputs"
+
+
+@dataclass
+class AppConfig:
+    yolo: YoloConfig = field(default_factory=YoloConfig)
+    counting: CountingConfig = field(default_factory=CountingConfig)
+    attributes: AttributeConfig = field(default_factory=AttributeConfig)
+    output: OutputConfig = field(default_factory=OutputConfig)
+    rtsp: RtspConfig = field(default_factory=RtspConfig)
+    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
+    config_path: Path | None = None
+
+
+@dataclass
+class TrackObservation:
+    track_id: int
+    bbox: tuple[int, int, int, int]
+    confidence: float
+    center: tuple[float, float]
+
+
+@dataclass
+class CrossingEvent:
+    track_id: int
+    direction: str
+
+
+@dataclass
+class AttributeVote:
+    age: int
+    age_bucket: str
+    gender: str
+
+
+@dataclass
+class TrackAttributeSummary:
+    track_id: int
+    age: int
+    age_bucket: str
+    gender: str
+    samples_used: int
--- a/managed/people_flow_project/src/people_flow/pipeline.py
+++ b/managed/people_flow_project/src/people_flow/pipeline.py
@@ -0,0 +1,445 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import cv2
+
+from .attributes import AttributeAggregator
+from .counting import LineCrossCounter
+from .io_utils import (
+    draw_line,
+    draw_stats,
+    draw_tracks,
+    ensure_dir,
+    make_video_writer,
+    write_csv,
+    write_json,
+    write_window_json,
+)
+from .models import AppConfig
+from .tracking import extract_person_tracks
+
+
+SUPPORTED_EXTENSIONS = {".mp4", ".mov", ".mkv", ".avi"}
+
+
+def discover_videos(root: Path, pattern: str = "*.mp4") -> list[Path]:
+    if not root.exists():
+        raise FileNotFoundError(f"Input directory not found: {root}")
+    videos = [
+        path
+        for path in root.rglob(pattern)
+        if path.is_file() and path.suffix.lower() in SUPPORTED_EXTENSIONS
+    ]
+    return sorted(videos)
+
+
+class PeopleFlowPipeline:
+    def __init__(self, config: AppConfig, output_root: Path) -> None:
+        self.config = config
+        self.output_root = ensure_dir(output_root)
+        self.model = self._load_model()
+
+    def _load_model(self) -> Any:
+        try:
+            from ultralytics import YOLO
+        except ImportError as exc:
+            raise RuntimeError(
+                "Ultralytics is not installed. Install dependencies with `pip install -r requirements.txt`."
+            ) from exc
+        return YOLO(self.config.yolo.model_path)
+
+    def get_rtsp_output_paths(self) -> dict[str, Path]:
+        root = ensure_dir(self.output_root / self.config.rtsp.output_subdir)
+        windows = ensure_dir(root / "windows")
+        latest_json = root / "latest.json"
+        return {"root": root, "windows": windows, "latest_json": latest_json}
+
+    def process_batch(self, videos: list[Path]) -> dict:
+        rows: list[dict] = []
+        for video_path in videos:
+            rows.append(self.process_video(video_path))
+
+        csv_path = self.output_root / "batch_summary.csv"
+        if self.config.output.save_csv:
+            csv_rows = [
+                {
+                    "video_name": row["video_name"],
+                    "video_path": row["video_path"],
+                    "total_people": row["total_people"],
+                    "minor": row["age_counts"]["minor"],
+                    "adult": row["age_counts"]["adult"],
+                    "senior": row["age_counts"]["senior"],
+                    "male": row["gender_counts"]["male"],
+                    "female": row["gender_counts"]["female"],
+                    "unknown_attributes": row["unknown_attributes"],
+                    "json_path": row["json_path"],
+                    "video_output_path": row.get("video_output_path"),
+                }
+                for row in rows
+            ]
+            write_csv(csv_path, csv_rows)
+
+        return {"videos": rows, "csv_path": str(csv_path)}
+
+    def process_video(self, video_path: Path) -> dict:
+        if not video_path.exists():
+            raise FileNotFoundError(f"Video file not found: {video_path}")
+
+        capture = cv2.VideoCapture(str(video_path))
+        if not capture.isOpened():
+            raise RuntimeError(f"Failed to open video: {video_path}")
+
+        width = int(capture.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
+        height = int(capture.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
+        fps = float(capture.get(cv2.CAP_PROP_FPS) or 25.0)
+        pixel_line = self.config.counting.to_pixel_line(width=width, height=height)
+
+        video_output_dir = ensure_dir(self.output_root / video_path.stem)
+        video_output_path = video_output_dir / f"{video_path.stem}.annotated.mp4"
+        json_path = video_output_dir / f"{video_path.stem}.json"
+
+        writer = None
+        if self.config.output.save_video:
+            writer = make_video_writer(video_output_path, width=width, height=height, fps=fps)
+
+        counter = LineCrossCounter(pixel_line, self.config.counting)
+        attributes = AttributeAggregator(self.config.attributes)
+
+        frame_index = 0
+        while True:
+            ok, frame = capture.read()
+            if not ok:
+                break
+
+            observations = self._track_frame(frame)
+
+            for observation in observations:
+                attributes.maybe_collect(frame=frame, frame_index=frame_index, track=observation)
+
+            counter.update(observations)
+
+            if writer is not None:
+                frame_stats = self._build_live_stats(counter, attributes)
+                annotated = frame.copy()
+                draw_line(annotated, pixel_line)
+                if self.config.output.draw_boxes:
+                    draw_tracks(
+                        annotated,
+                        observations=observations,
+                        counted_ids=counter.counted_ids,
+                        draw_labels=self.config.output.draw_labels,
+                    )
+                draw_stats(annotated, frame_stats)
+                writer.write(annotated)
+
+            frame_index += 1
+
+        capture.release()
+        if writer is not None:
+            writer.release()
+
+        summary = self._finalize_summary(video_path, counter, attributes, json_path)
+        if not self.config.output.save_video:
+            summary["video_output_path"] = None
+        else:
+            summary["video_output_path"] = str(video_output_path)
+        return summary
+
+    def process_rtsp(self, source: str) -> dict:
+        rtsp_paths = self.get_rtsp_output_paths()
+        sample_interval = max(float(self.config.rtsp.sample_interval_seconds), 0.01)
+        window_seconds = max(int(self.config.rtsp.window_seconds), 1)
+        reconnect_delay = max(float(self.config.rtsp.reconnect_delay_seconds), 0.1)
+        open_timeout_seconds = max(float(self.config.rtsp.stream_open_timeout_seconds), 1.0)
+        idle_sleep = max(float(self.config.rtsp.idle_sleep_seconds), 0.0)
+
+        window_index = 0
+        process_started_at = datetime.now().astimezone()
+        window_start = datetime.now().astimezone()
+        window_end = window_start + timedelta(seconds=window_seconds)
+        last_processed_at = 0.0
+        last_processed_wall_time: datetime | None = None
+        next_heartbeat_at = time.monotonic() + 60.0
+        frame_index = 0
+        capture = None
+        pixel_line = None
+        counter = None
+        attributes = AttributeAggregator(self.config.attributes)
+
+        try:
+            while True:
+                now = datetime.now().astimezone()
+                while now >= window_end:
+                    payload = self._build_rtsp_summary(
+                        source=source,
+                        window_index=window_index,
+                        window_start=window_start,
+                        window_end=window_end,
+                        counter=counter,
+                        attributes=attributes,
+                    )
+                    json_path = write_window_json(
+                        rtsp_paths["windows"],
+                        rtsp_paths["latest_json"],
+                        payload,
+                        window_end,
+                    )
+                    print(f"window_json={json_path}", flush=True)
+                    print(f"window_total_people={payload['total_people']}", flush=True)
+                    window_index += 1
+                    window_start = window_end
+                    window_end = window_start + timedelta(seconds=window_seconds)
+                    if counter is not None:
+                        counter.reset()
+                    attributes.reset()
+                    now = datetime.now().astimezone()
+
+                if capture is None or not capture.isOpened():
+                    capture = self._open_rtsp_capture(source, open_timeout_seconds)
+                    if capture is None:
+                        time.sleep(reconnect_delay)
+                        continue
+
+                ok, frame = capture.read()
+                if not ok or frame is None:
+                    capture.release()
+                    capture = None
+                    time.sleep(reconnect_delay)
+                    continue
+
+                if pixel_line is None:
+                    height, width = frame.shape[:2]
+                    pixel_line = self.config.counting.to_pixel_line(width=width, height=height)
+                    counter = LineCrossCounter(pixel_line, self.config.counting)
+
+                current_time = time.monotonic()
+                if current_time - last_processed_at < sample_interval:
+                    if idle_sleep > 0:
+                        time.sleep(idle_sleep)
+                    continue
+
+                last_processed_at = current_time
+                observations = self._track_frame(frame)
+                for observation in observations:
+                    attributes.maybe_collect(frame=frame, frame_index=frame_index, track=observation)
+                if counter is not None:
+                    counter.update(observations)
+                    if current_time >= next_heartbeat_at:
+                        self._print_rtsp_heartbeat(
+                            process_started_at=process_started_at,
+                            window_index=window_index,
+                            frame_index=frame_index + 1,
+                            counter=counter,
+                            attributes=attributes,
+                            last_processed_wall_time=now,
+                        )
+                        next_heartbeat_at = current_time + 60.0
+                last_processed_wall_time = now
+                frame_index += 1
+        except KeyboardInterrupt:
+            pass
+        finally:
+            if capture is not None:
+                capture.release()
+
+        return {
+            "rtsp_output_dir": str(rtsp_paths["root"]),
+            "latest_json": str(rtsp_paths["latest_json"]),
+        }
+
+    def _track_frame(self, frame) -> list:
+        results = self.model.track(
+            frame,
+            persist=True,
+            tracker=self.config.yolo.tracker,
+            conf=self.config.yolo.conf,
+            iou=self.config.yolo.iou,
+            imgsz=self.config.yolo.imgsz,
+            device=self.config.yolo.device,
+            verbose=False,
+            classes=[0],
+        )
+        result = results[0] if isinstance(results, list) else results
+        return extract_person_tracks(result)
+
+    def _open_rtsp_capture(self, source: str, timeout_seconds: float):
+        capture = cv2.VideoCapture()
+        open_timeout = getattr(cv2, "CAP_PROP_OPEN_TIMEOUT_MSEC", None)
+        read_timeout = getattr(cv2, "CAP_PROP_READ_TIMEOUT_MSEC", None)
+        if open_timeout is not None:
+            capture.set(open_timeout, timeout_seconds * 1000.0)
+        if read_timeout is not None:
+            capture.set(read_timeout, timeout_seconds * 1000.0)
+        buffersize = getattr(cv2, "CAP_PROP_BUFFERSIZE", None)
+        if buffersize is not None:
+            capture.set(buffersize, 1)
+        capture.open(source)
+        if capture.isOpened():
+            return capture
+        capture.release()
+        return None
+
+    def _build_live_stats(self, counter: LineCrossCounter, attributes: AttributeAggregator) -> dict:
+        age_counts = {"minor": 0, "adult": 0, "senior": 0}
+        gender_counts = {"male": 0, "female": 0}
+        unknown_attributes = 0
+
+        for track_id in counter.counted_ids:
+            summary = attributes.summarize_track(track_id)
+            if summary is None:
+                unknown_attributes += 1
+                continue
+            age_counts[summary.age_bucket] += 1
+            gender_counts[summary.gender] += 1
+
+        return {
+            "total_people": counter.total_people,
+            "age_counts": age_counts,
+            "gender_counts": gender_counts,
+            "unknown_attributes": unknown_attributes,
+        }
+
+    def _print_rtsp_heartbeat(
+        self,
+        process_started_at: datetime,
+        window_index: int,
+        frame_index: int,
+        counter: LineCrossCounter,
+        attributes: AttributeAggregator,
+        last_processed_wall_time: datetime | None,
+    ) -> None:
+        stats = self._build_live_stats(counter, attributes)
+        runtime_seconds = int((datetime.now().astimezone() - process_started_at).total_seconds())
+        last_processed = (
+            last_processed_wall_time.isoformat(timespec="seconds")
+            if last_processed_wall_time is not None
+            else None
+        )
+        print(
+            "heartbeat "
+            f"runtime_seconds={runtime_seconds} "
+            f"window_index={window_index} "
+            f"window_frames={frame_index} "
+            f"total_people={stats['total_people']} "
+            f"minor={stats['age_counts']['minor']} "
+            f"adult={stats['age_counts']['adult']} "
+            f"senior={stats['age_counts']['senior']} "
+            f"male={stats['gender_counts']['male']} "
+            f"female={stats['gender_counts']['female']} "
+            f"unknown_attributes={stats['unknown_attributes']} "
+            f"last_processed_at={last_processed}",
+            flush=True,
+        )
+
+    def _collect_track_summaries(
+        self,
+        counter: LineCrossCounter | None,
+        attributes: AttributeAggregator,
+    ) -> tuple[dict[str, int], dict[str, int], int, list[dict]]:
+        age_counts = {"minor": 0, "adult": 0, "senior": 0}
+        gender_counts = {"male": 0, "female": 0}
+        unknown_attributes = 0
+        track_summaries: list[dict] = []
+
+        if counter is None:
+            return age_counts, gender_counts, unknown_attributes, track_summaries
+
+        for event in counter.crossings:
+            summary = attributes.summarize_track(event.track_id)
+            if summary is None:
+                unknown_attributes += 1
+                track_summaries.append(
+                    {
+                        "track_id": event.track_id,
+                        "direction": event.direction,
+                        "age": None,
+                        "age_bucket": None,
+                        "gender": None,
+                        "samples_used": 0,
+                    }
+                )
+                continue
+
+            age_counts[summary.age_bucket] += 1
+            gender_counts[summary.gender] += 1
+            track_summaries.append(
+                {
+                    "track_id": summary.track_id,
+                    "direction": event.direction,
+                    "age": summary.age,
+                    "age_bucket": summary.age_bucket,
+                    "gender": summary.gender,
+                    "samples_used": summary.samples_used,
+                }
+            )
+
+        return age_counts, gender_counts, unknown_attributes, track_summaries
+
+    def _build_rtsp_summary(
+        self,
+        source: str,
+        window_index: int,
+        window_start: datetime,
+        window_end: datetime,
+        counter: LineCrossCounter | None,
+        attributes: AttributeAggregator,
+    ) -> dict:
+        age_counts, gender_counts, unknown_attributes, track_summaries = self._collect_track_summaries(
+            counter,
+            attributes,
+        )
+        total_people = 0 if counter is None else counter.total_people
+        return {
+            "source_type": "rtsp",
+            "source": source,
+            "window_index": window_index,
+            "window_start": window_start.isoformat(),
+            "window_end": window_end.isoformat(),
+            "window_duration_seconds": int((window_end - window_start).total_seconds()),
+            "config_path": str(self.config.config_path) if self.config.config_path else None,
+            "line": {
+                "coordinates": list(self.config.counting.line),
+                "mode": self.config.counting.line_mode,
+            },
+            "total_people": total_people,
+            "age_counts": age_counts,
+            "gender_counts": gender_counts,
+            "unknown_attributes": unknown_attributes,
+            "tracks": track_summaries,
+        }
+
+    def _finalize_summary(
+        self,
+        video_path: Path,
+        counter: LineCrossCounter,
+        attributes: AttributeAggregator,
+        json_path: Path,
+    ) -> dict:
+        age_counts, gender_counts, unknown_attributes, track_summaries = self._collect_track_summaries(
+            counter,
+            attributes,
+        )
+
+        payload = {
+            "video_name": video_path.name,
+            "video_path": str(video_path),
+            "config_path": str(self.config.config_path) if self.config.config_path else None,
+            "line": {
+                "coordinates": list(self.config.counting.line),
+                "mode": self.config.counting.line_mode,
+            },
+            "total_people": counter.total_people,
+            "age_counts": age_counts,
+            "gender_counts": gender_counts,
+            "unknown_attributes": unknown_attributes,
+            "tracks": track_summaries,
+        }
+        if self.config.output.save_json:
+            write_json(json_path, payload)
+
+        payload["json_path"] = str(json_path)
+        return payload
--- a/managed/people_flow_project/src/people_flow/tracking.py
+++ b/managed/people_flow_project/src/people_flow/tracking.py
@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .models import TrackObservation
+
+
+def extract_person_tracks(result: Any) -> list[TrackObservation]:
+    boxes = getattr(result, "boxes", None)
+    if boxes is None:
+        return []
+    if getattr(boxes, "id", None) is None:
+        return []
+
+    xyxy = boxes.xyxy.int().cpu().tolist()
+    ids = boxes.id.int().cpu().tolist()
+    confs = boxes.conf.cpu().tolist()
+    classes = boxes.cls.int().cpu().tolist()
+
+    observations: list[TrackObservation] = []
+    for bbox, track_id, confidence, class_id in zip(xyxy, ids, confs, classes, strict=False):
+        if int(class_id) != 0:
+            continue
+        x1, y1, x2, y2 = bbox
+        center_x = (x1 + x2) / 2.0
+        center_y = (y1 + y2) / 2.0
+        observations.append(
+            TrackObservation(
+                track_id=int(track_id),
+                bbox=(int(x1), int(y1), int(x2), int(y2)),
+                confidence=float(confidence),
+                center=(center_x, center_y),
+            )
+        )
+    return observations
--- a/managed/people_flow_project/tests/test_manage_api.py
+++ b/managed/people_flow_project/tests/test_manage_api.py
@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from src.people_flow.manage_api import create_app
+
+
+def build_client(project_root: Path):
+    config_path = project_root / "config" / "local.yaml"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(
+        "runtime:\n"
+        "  rtsp_url: rtsp://before-update\n"
+        "  output_dir: outputs\n"
+        "rtsp:\n"
+        "  output_subdir: rtsp_stream\n",
+        encoding="utf-8",
+    )
+
+    rtsp_dir = project_root / "outputs" / "rtsp_stream"
+    windows_dir = rtsp_dir / "windows"
+    windows_dir.mkdir(parents=True, exist_ok=True)
+    latest_payload = {
+        "source_type": "rtsp",
+        "window_start": "2026-04-16T09:30:00+08:00",
+        "window_end": "2026-04-16T10:00:00+08:00",
+        "total_people": 7,
+        "age_counts": {"minor": 1, "adult": 5, "senior": 1},
+        "gender_counts": {"male": 4, "female": 3},
+        "unknown_attributes": 2,
+        "tracks": [
+            {"track_id": 1, "direction": "in"},
+            {"track_id": 2, "direction": "out"},
+            {"track_id": 3, "direction": "in"},
+        ],
+    }
+    (rtsp_dir / "latest.json").write_text(
+        json.dumps(latest_payload),
+        encoding="utf-8",
+    )
+    (windows_dir / "stats_2026-04-16_09-00-00.json").write_text(
+        json.dumps(
+            {
+                "window_start": "2026-04-16T09:00:00+08:00",
+                "window_end": "2026-04-16T09:30:00+08:00",
+                "total_people": 5,
+                "age_counts": {"minor": 0, "adult": 4, "senior": 1},
+                "gender_counts": {"male": 2, "female": 3},
+                "unknown_attributes": 1,
+            }
+        ),
+        encoding="utf-8",
+    )
+    (windows_dir / "stats_2026-04-16_09-30-00.json").write_text(
+        json.dumps(latest_payload),
+        encoding="utf-8",
+    )
+    (project_root / "outputs" / "rtsp_run.log").write_text("rtsp ok\n", encoding="utf-8")
+
+    app = create_app(config_path)
+    app.testing = True
+    return app.test_client(), config_path
+
+
+def test_get_manage_health(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get("/api/manage/health")
+
+    assert response.status_code == 200
+    assert response.json["status"] == "ok"
+    assert response.json["project_type"] == "people_flow_project"
+    assert response.json["runtime_status"] == "running"
+
+
+def test_get_manage_config(tmp_path: Path):
+    client, config_path = build_client(tmp_path)
+
+    response = client.get("/api/manage/config")
+
+    assert response.status_code == 200
+    assert response.json["config_path"] == str(config_path)
+    assert response.json["runtime"]["rtsp_url"] == "rtsp://before-update"
+    assert response.json["rtsp"]["output_subdir"] == "rtsp_stream"
+
+
+def test_put_manage_config_updates_rtsp_url(tmp_path: Path):
+    client, config_path = build_client(tmp_path)
+
+    response = client.put(
+        "/api/manage/config",
+        json={"rtsp_url": "rtsp://after-update"},
+    )
+
+    assert response.status_code == 200
+    assert response.json["runtime"]["rtsp_url"] == "rtsp://after-update"
+
+    saved = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    assert saved["runtime"]["rtsp_url"] == "rtsp://after-update"
+
+
+def test_get_manage_summary(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get("/api/manage/summary")
+
+    assert response.status_code == 200
+    assert response.json["result_type"] == "people_flow_project"
+    assert response.json["last_result_time"] == "2026-04-16T10:00:00+08:00"
+    assert response.json["metrics"]["total_people"] == 7
+    assert response.json["metrics"]["direction_counts"] == {"in": 2, "out": 1}
+    assert response.json["metrics"]["recent_window_stats"][0]["window_end"] == "2026-04-16T10:00:00+08:00"
+
+
+def test_get_manage_windows(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get("/api/manage/windows?page=1&page_size=1")
+
+    assert response.status_code == 200
+    assert response.json["total"] == 2
+    assert response.json["page"] == 1
+    assert response.json["page_size"] == 1
+    assert response.json["items"][0]["window_end"] == "2026-04-16T10:00:00+08:00"
+    assert response.json["items"][0]["total_people"] == 7
+
+
+def test_get_manage_files(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get("/api/manage/files")
+
+    assert response.status_code == 200
+    assert {item["path"] for item in response.json["files"]} == {
+        "outputs/rtsp_run.log",
+        "outputs/rtsp_stream/latest.json",
+        "outputs/rtsp_stream/windows/stats_2026-04-16_09-00-00.json",
+        "outputs/rtsp_stream/windows/stats_2026-04-16_09-30-00.json",
+    }
+
+
+def test_get_manage_files_preview(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get(
+        "/api/manage/files/preview?path=outputs/rtsp_stream/latest.json&lines=1"
+    )
+
+    assert response.status_code == 200
+    assert response.json["path"] == "outputs/rtsp_stream/latest.json"
+    assert response.json["count"] == 1
+    assert "total_people" in response.json["lines"][0]
+
+
+def test_get_manage_files_download(tmp_path: Path):
+    client, _ = build_client(tmp_path)
+
+    response = client.get("/api/manage/files/download?path=outputs/rtsp_run.log")
+
+    assert response.status_code == 200
+    assert response.data == b"rtsp ok\n"
--- a/managed/people_flow_project/weights/.gitkeep
+++ b/managed/people_flow_project/weights/.gitkeep
@@ -0,0 +1 @@
+
--- a/managed/people_flow_project/weights/deepface/.gitkeep
+++ b/managed/people_flow_project/weights/deepface/.gitkeep
@@ -0,0 +1 @@
+