cold_display_guard/findings.md

# Findings

## Existing Local Context

- `~/Code/video_recognition_local/store_dwell_alert` exists, but it tracks people dwell time, not food batch dwell time.
- The new project should be independent and should not share git history with the existing project.

## Domain Model

- The reliable business unit is a display-zone batch, not an individual food item.
- A batch starts when a zone changes from empty to occupied.
- A batch continues while the zone remains occupied, even if the item count decreases.
- A batch ends when the zone becomes empty.
- If a batch is removed after the maximum dwell threshold, the system expects a trash-bin deposit event within a configurable window.
- If a removed over-threshold batch reappears in any display zone before being discarded, that is a violation.
- If food is added while a zone is already occupied, that is a mixed-batch violation.

## v1.1 优化改造 Findings

## Architecture

- The current backend already accepts configured `layout.zone_ids`, so the engine does not require a fixed 2x4 grid internally.
- The current frontend is the main fixed-grid constraint: `web/src/main.js` hard-codes `r1c1` through `r2c4` and draws those region controls.
- `merge_calibration()` already accepts arbitrary zone IDs and clamps polygon points, but it does not enforce the new 1-10 numeric region policy.
- The runtime vision layer consumes `[[zones]]` from config, so it can follow numeric zones once config and frontend write them.
- `BatchEngine` only emits events when a zone changes or pending disposal expires; a time alarm while the batch remains occupied requires a new periodic active-batch check.

## Constraints

- Food regions must be numbered `1` through `N`, with `N` between 1 and 10.
- Trash ROI is a separate region under `[trash]` and must not consume a food zone number.
- The management API should preserve standard-library HTTP behavior.
- Existing JSONL consumers may still expect `event`, `zone_id`, `dwell_seconds`, and timestamps; v1.1 should add fields rather than remove core fields.
- The frontend remains Vite + vanilla JavaScript; no framework migration in this batch.

## Decisions

- Keep `max_dwell_seconds` as the configurable time-alarm threshold to avoid introducing two competing dwell thresholds.
- Add `time_alarm` when an active batch reaches the threshold, while keeping the batch active until the zone clears.
- Once an alarmed batch clears, put it into pending trash confirmation and emit `batch_pending_disposal`.
- If no trash deposit occurs before the confirmation deadline, emit `warning_escalated` with severity `warning`; retain compatibility by using the same pending-disposal mechanism.
- Emit `zone_index` and `zone_label` on every zone event when the zone ID is numeric.
- The backend planning agent suggested `batch_dwell_alert` and `missing_disposal_warning`, but the accepted prototype and user phrasing use `time_alarm` and `warning_escalated`; implementation should follow the accepted prototype names.
- Every future subagent dispatch must begin with the standard context header requested by the user:

```text
[项目: /Users/yoilun/Code/cold_display_guard]
[工作流批次: v1.1 优化改造]
[阶段: 阶段 x]
[角色: 对应智能体角色]
```

Use `阶段 x` only as a workflow stage inside the same `v1.1 优化改造` batch.

## v1.2 轨迹识别 Findings

## Architecture

- `main.py` 当前每轮从 RTSP 截一帧，调用 `ZoneOccupancyDetector.observe()` 得到 `zone_counts`、`trash_deposit_count`、`diagnostics`，再构造 `Observation` 给 `BatchEngine.process()`。
- `vision.py` 当前只有区域占用和垃圾桶动作计数，没有从“来源区域到垃圾桶”的轨迹证据。
- `engine.py` 当前先处理 pending 过期和旧 trash deposit，再处理区域转移，最后对同帧剩余 trash deposit 做兜底；这为同帧 evidence 处理提供了插入点。
- `models.py` 的 `Observation` 是最适合扩展统一 evidence contract 的位置。
- v1.2 设计规格已保存并提交：`docs/superpowers/specs/2026-05-29-lightweight-trajectory-yolo-ready-design.md`，commit `ac6d368`。

## Constraints

- 第一版必须在无 YOLO 依赖下运行。
- 轨迹检测只应在区域变空后的短窗口活跃，避免持续 CPU 压力。
- 垃圾桶内部不可见；确认点是进入垃圾桶口 ROI，不是看到桶内物品。
- 不能让一个来源区域的 evidence 关闭另一个区域的 pending batch。
- 远端部署必须继续排除 `config/example.toml`，以保留 RTSP 和现场标定。

## Decisions

- 新字段命名为 `disposal_evidence`，元素使用 `source_zone_id`、`target`、`confidence`、`method`、`track_points`、可选 `item_class`、`detector_score`。
- `trash_deposit_count` 保留兼容和兜底，但 engine 先使用 zone-scoped evidence。
- 轨迹诊断必须记录 active、emitted、rejected、expired，方便现场调参。
- 后续 YOLO 模型只作为 evidence 增强输入，不能修改 `BatchEngine` 的业务语义。

## Final Review Findings

- Evidence and generic trash fallback must share the same count budget: one matched `disposal_evidence` consumes one observed trash deposit signal when `trash_deposit_count` is also present, but extra trash deposits must still fall back to pending batches.
- A trajectory candidate must not append source-zone-external motion before source motion has been seen. If outside motion appears first and is later followed by source noise, the candidate is rejected with `motion_started_outside_source` instead of producing evidence.
- Runtime diagnostics on the deployed host should be checked for schema only, not by printing config, because the remote config may contain RTSP credentials and calibration.

## Backend Planning Notes

- `EngineSettings.zone_ids` should remain config driven; numeric zones are preferred for new configs, but old `r1c1` style IDs should continue loading.
- v1.1 can derive `zone_index` from numeric `zone_id` when possible.
- Suggested batch additions:
  - `alerted_at`
  - an indicator that the time alarm has already been emitted
- Suggested state flow:
  - `active`: region occupied before threshold.
  - `alerted`: region occupied after `time_alarm`.
  - `pending_disposal`: alarmed food removed and waiting for trash deposit.
  - `discarded`: pending batch matched to trash.
  - `warning`: alarmed food removed and no trash deposit before deadline.
  - `consumed`: non-alarmed food removed.
- `build_summary()` currently counts only `*_violation`; v1.1 should include `severity: alert|warning` in alert summaries.
- FIFO matching of pending batches to trash deposits remains acceptable but should stay covered by tests.

## Frontend Planning Notes

- Replace the fixed `zoneIds` array in `web/src/main.js` with dynamic food-zone state derived from config, constrained to 1-10 zones.
- Keep `trashRoi` separate from `foodZones`; never include it in `zone_index` numbering.
- Suggested frontend state groups:
  - `foodZoneCount`
  - `foodZones: [{id, label, points}]`
  - `trashRoi`
  - active edit target type/index
  - config form values including alarm threshold
  - normalized event rows for display
- Current target must be visually obvious before canvas clicks add points.
- Coordinates must remain normalized relative to the displayed frame/image.
- Reducing zone count should truncate removed zones only after a clear confirmation or obvious UI affordance.
- Re-capturing an RTSP frame must not discard unsaved point edits.
- Event table must safely render old and new events, including `time_alarm` and `warning_escalated`.
- Frontend validation should cover 1/10 zones, food/trash editing, save/reload recovery, old 8-zone config compatibility, and threshold validation.

## Homepage Demo Runtime Notes

- Docker runtime can write diagnostics while no events exist, especially when the configured RTSP stream is unreachable.
- A diagnostics-only summary is not enough to represent the accepted prototype; the home runtime view should show a clearly marked demo state until real events exist.
- Demo runtime content must never look like a real alarm: banner, metrics labels, event source tags, and event file text identify it as demo data.
- Real events take precedence over demo data. Per-zone progress uses the latest event by timestamp when both candidates have timestamps; otherwise it falls back to event order.
- Event-derived progress uses the configured dwell threshold when an event omits `max_dwell_seconds`.
- Any runtime summary value rendered through `innerHTML`, including `latest_zone_counts`, must be HTML-escaped.