feat: stabilize cold display runtime deployment

findings.md

@@ -14,3 +14,84 @@
 - 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.