# 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

- [x] v1.1 所有工作项完成。
- [x] 必要 Python 测试通过。
- [x] 前端构建通过。
- [x] `docs/project.md` 更新项目目标、架构、配置、运行方式和关键决策。
- [x] 没有 blocking bug 或未处理的高风险问题。
- [x] 如果同一问题连续 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`。
- 首页运行页在事件为空或运行数据不完整时显示标记为演示的数据，避免空白页面；真实事件数据存在时优先展示真实数据。
- 后续每次派发智能体任务，都必须在任务正文开头加入标准上下文头：

```text
[项目: /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 | complete | 集成 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 派发必须使用标准上下文头：

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