# Store Dwell Alert on 192.168.5.108

Local planning project for a single-camera RTSP long-stay alert system running on `192.168.5.108`.

Documents:
- `docs/plans/2026-04-15-store-dwell-alert-design.md`
- `docs/plans/2026-04-15-store-dwell-alert.md`

Scope:
- Single RTSP store camera
- `YOLO11n` person detection
- Full-frame tracking and lightweight re-association
- Staff whitelist exclusion
- Local JSONL event sink
- Half-hour dwell reports
- Offline bundle packaging for `.108`-class Ubuntu hosts
- Chinese operations guide: `README_zh.md`

Runtime:
- Default config path: `config/108.local.yaml`
- Event sink path: `logs/events.jsonl`
- Continuous mode: `python -m app.main`
- Single-frame smoke test: `python -m app.main --once`
- Management API mode: `python -m app.manage_api --config config/local.yaml --port 18081`

Staff gallery:
- Directory: `data/staff_gallery/`
- Supported formats:
  - `*.json` signature files
  - `*.jpg`, `*.jpeg`, `*.png`, `*.bmp`, `*.webp` sample crops
- JSON example:

```json
{
  "staff_id": "staff_001",
  "signature": [0.182, 0.244, 0.317]
}
```

Offline bundle:
- Target host assumption: Ubuntu 24.04, Python 3.12, NVIDIA GPU compatible with the `.108` runtime stack
- Bundle script: `bash scripts/package_bundle.sh`
- Bundle output: `dist/store_dwell_alert_bundle_<date>.tar.gz`
- Bundle prerequisites before packaging:
  - place Linux wheels under `wheelhouse/`
  - place `yolo11n.pt` under `weights/yolo11n.pt`

Offline install on target host:
1. Extract `store_dwell_alert_bundle_<date>.tar.gz`
2. Edit `scripts/run.sh` and set `RTSP_URL`
3. Run `sudo bash scripts/install.sh`
4. The installer enables and starts `store-dwell-alert.service`

Optional service install:
1. Run `bash scripts/install_service.sh`
2. Start with `sudo systemctl start store-dwell-alert.service`

Docker image:
- Required runtime weight in build context: `weights/yolo11n.pt`
- Build: `docker build -t store-dwell-alert:test .`
- Compose: `docker compose up --build store-dwell-alert`
- Health: `http://127.0.0.1:18081/api/manage/health`
- Default container entrypoint seeds `config/local.yaml` from `config/config.example.yaml` and then starts the management API
- Persisted host paths:
  - `./config -> /app/config`
  - `./data -> /app/data`
  - `./logs -> /app/logs`

## 中文离线部署说明

适用环境：
- `Ubuntu 24.04`
- `Python 3.12`
- 已安装 NVIDIA 驱动，`nvidia-smi` 可用
- 已安装 `ffmpeg`

离线包准备：
- 成品包示例：`store_dwell_alert_bundle_2026-04-16.tar.gz`
- 包内已经包含：
  - 项目源码
  - `wheelhouse/` 离线依赖
  - `weights/yolo11n.pt`
  - `scripts/install.sh`
  - `scripts/run.sh`
  - `scripts/install_service.sh`

部署步骤：
1. 把离线包传到目标机器
2. 解压：

```bash
tar -xzf store_dwell_alert_bundle_2026-04-16.tar.gz
cd store_dwell_alert_bundle
```

3. 执行离线安装：

```bash
bash scripts/install.sh
```

4. 编辑运行脚本，至少改这几个变量：
   - `RTSP_URL`
   - `CAMERA_ID`
   - `EVENT_SINK_PATH`

```bash
vim scripts/run.sh
```

5. 手工启动：

```bash
bash scripts/run.sh
```

常见输出位置：
- 事件结果：`logs/events.jsonl`
- 本地配置：`config/local.yaml`
- 店员图库：`data/staff_gallery/`

如果需要做店员排除：
- 把店员样本图放到 `data/staff_gallery/`
- 或者放入对应的 `*.json` 特征文件

配置完成后的常驻运行：
1. 安装服务：

```bash
bash scripts/install_service.sh
```

2. 启动服务：

```bash
sudo systemctl start store-dwell-alert.service
```

3. 查看状态：

```bash
sudo systemctl status store-dwell-alert.service
```

4. 停止服务：

```bash
sudo systemctl stop store-dwell-alert.service
```

5. 开机自启：

```bash
sudo systemctl enable store-dwell-alert.service
```

排查建议：
- `scripts/install.sh` 失败时，先确认 `python3.12`、`ffmpeg`、`nvidia-smi` 都存在
- `scripts/run.sh` 失败时，先确认 `RTSP_URL` 已改成真实地址
- 如果程序启动了但没有结果，先看 `logs/events.jsonl` 是否生成
- 如果识别不到店员，先检查 `data/staff_gallery/` 是否有有效样本