123 lines
7.7 KiB
Markdown
123 lines
7.7 KiB
Markdown
# 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` 的业务语义。
|
||
|
||
## 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.
|