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.

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.