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:

[项目: /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.