cold_display_guard/task_plan.md

Cold Display Guard Task Plan

Goal

Create and evolve an independent git project under ~/Code for monitoring food batches in a refrigerated display cabinet. The system tracks each configured food zone, starts a batch timer when food appears, raises a configurable time alarm, and escalates alarmed food to a warning if it is removed without a matching trash-bin deposit.

Confirmed Decisions

• The trash bin is visible in the same camera frame.
• Food zones are configurable; v1.1 supports 1 to 10 numeric zones.
• A zone may contain multiple food items.
• Items in the same zone are treated as one batch.
• Mixed batches are not allowed; a zone must clear before a new batch can start.
• The first implementation is a standalone project, not a modification of store_dwell_alert.

Original Milestones

Milestone	Status	Notes
Create project skeleton	complete	Built under ~/Code/cold_display_guard.
Write design and implementation plan	complete	Saved in docs/plans/.
Implement core state engine	complete	Pure Python, no camera dependency.
Add config, CLI, README	complete	TOML config and JSONL event CLI skeleton.
Add tests	complete	python3 -m unittest discover -s tests -v passes.
Initialize git and commit	complete	Independent repository created.

Errors Encountered

Error	Attempt	Resolution
Ended batches reported 0 dwell seconds	First unittest run	Calculate dwell seconds before assigning ended_at.

v1.1 优化改造

Goal

正式支持 1 到 10 个自定义食品区域、阿拉伯数字区域标注、可编辑垃圾桶 ROI、自定义时间报警阈值，以及“到达报警阈值先报警，报警后移出但未丢垃圾桶则升级为警告”的事件链路。

本节所有需求属于同一个 v1.1 优化改造 批次；下方只是该批次内的工作项，不代表拆成多个独立批次或多个版本。

Stop Conditions

• v1.1 所有工作项完成。
• 必要 Python 测试通过。
• 前端构建通过。
• docs/project.md 更新项目目标、架构、配置、运行方式和关键决策。
• 没有 blocking bug 或未处理的高风险问题。
• 如果同一问题连续 3 次修复失败，暂停并报告原因、已尝试方案和建议下一步。

Workstreams Inside This Batch

Workstream	Status	Goal	Acceptance Criteria
Batch setup and planning	complete	建立 v1.1 优化改造 文件化计划和项目文档	task_plan.md、findings.md、progress.md、docs/project.md 包含 v1.1 范围、工作项、验收标准和风险
Backend event model	complete	状态机支持数字区域、时间报警、报警升级警告	TDD 覆盖 time_alarm、warning_escalated、数字区域元数据；目标测试和全量 Python 测试通过；代码审查通过
Config and management API	complete	配置/API 支持 1-10 区域、报警阈值、垃圾桶 ROI 保存	配置 round trip、校验、summary/events 字段测试通过；代码审查反馈已修复
Frontend management console	complete	管理页支持动态区域标定、垃圾桶 ROI 标点、报警阈值配置和新事件显示	web/src/main.js、web/src/styles.css 实现交互；pnpm build 通过；前端复审通过
Homepage demo runtime display	complete	首页在无真实事件时也展示完整原型样例，并清空旧事件数据	首页默认进入运行页；演示态包含运行摘要、计时进度、事件表和清晰演示标识；真实事件优先；前端测试和构建通过；Docker web 已重建
Documentation and final review	complete	更新 README/project docs，执行最终代码审查和验证	README 与命令/字段一致；代码审查无 blocking；验证证据记录到 progress.md

v1.1 Decisions

• 食品区域使用数字字符串 ID："1" 到 "10"；事件中同时输出 zone_index 和 zone_label。
• 垃圾桶 ROI 保持在 [trash] roi，不占用食品区域编号。
• max_dwell_seconds 继续作为主要时间报警阈值；默认可保持 10800 秒，用户可以改成 1200 秒等。
• 到达阈值时先发 time_alarm，批次继续处于活跃区域。
• 已报警批次从区域移出后进入垃圾桶确认窗口；若窗口内没有垃圾桶动作，发 warning_escalated。
• 首页运行页在事件为空或运行数据不完整时显示标记为演示的数据，避免空白页面；真实事件数据存在时优先展示真实数据。
• 后续每次派发智能体任务，都必须在任务正文开头加入标准上下文头：

[项目: /Users/yoilun/Code/cold_display_guard]
[工作流批次: v1.1 优化改造]
[阶段: 阶段 x]
[角色: 对应智能体角色]

其中 阶段 x 表示同一 v1.1 优化改造 批次内的工作阶段，不代表拆分成独立批次。

v1.2 轨迹识别

Goal

在 /Users/yoilun/Code/cold_display_guard 中完成轨迹识别改造：保留现有 ROI 占用计时和垃圾桶动作兜底，新增轻量轨迹移动检测，输出可被未来 YOLO 物品识别模型复用的统一 disposal_evidence，让报警后移出的物品按来源区域确认是否进入垃圾桶。

Stop Conditions

• v1.2 所有阶段完成。
• 必要 Python 测试通过。
• 前端测试或构建在受影响时通过。
• docs/project.md 记录 v1.2 架构、配置、运行方式和关键决策。
• 没有 blocking bug 或未处理的高风险问题。
• 如果同一问题连续 3 次修复仍失败，暂停并报告原因、已尝试方案和建议下一步。

Phases

Phase	Status	Goal	Acceptance Criteria
1	complete	建立 disposal_evidence 数据契约并让状态机优先按来源区域丢弃	Observation 支持 evidence；engine 能按 source_zone_id 精确关闭 pending batch；同帧移除+evidence 有回归测试；旧 trash_deposit_count 仍可兜底
2	complete	实现无 YOLO 依赖的轻量轨迹检测	synthetic frame 测试覆盖源区域到垃圾桶、非源区域运动、未到垃圾桶、单帧反光、多候选互不串扰；不引入模型依赖
3	pending	集成 runtime 配置、诊断和候选窗口加速采样	main.py 写入 disposal_evidence 与 trajectory diagnostics；配置默认 trajectory_enabled=true、yolo_enabled=false；候选活跃时使用更短采样间隔
4	pending	文档、全量验证和部署准备	README/project/progress 更新；Python 全量测试通过；前端测试/构建按影响范围验证；远端部署命令和风险记录清楚

v1.2 Decisions

• 第一版使用 MotionTrajectoryBackend，不安装 YOLO、PyTorch、ONNX Runtime 或 OpenVINO。
• YOLO 作为后续 YoloDetectionBackend 接入统一 evidence contract，不能绕过轨迹校验直接关闭业务事件。
• 状态机只消费 disposal_evidence，不依赖具体视觉后端。
• 轨迹 evidence 优先级高于 FIFO 垃圾桶动作兜底。
• 子 agent 派发必须使用标准上下文头：

[项目: /Users/yoilun/Code/cold_display_guard]
[工作流批次: v1.2 轨迹识别]
[阶段: 阶段 x]
[角色: 对应智能体角色]