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.

## 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.