113 lines
6.1 KiB
Markdown
113 lines
6.1 KiB
Markdown
# Webhook Case Management Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Build local case management plus outbound/inbound webhook support on top of the existing runtime batch-event flow.
|
|
|
|
**Architecture:** Keep `BatchEngine` as the factual event source, then add a separate case-state module that consumes selected events and persists case snapshots. Add a webhook delivery module for both batch events and case events, expose management APIs for case listing and handling, and render the resulting case workflow in the existing management console without mixing facts and workflow state.
|
|
|
|
**Tech Stack:** Python 3.12 via pyenv, Python standard library HTTP/JSON/TOML stack, JSONL files, unittest, Vite + vanilla JavaScript, Node test runner.
|
|
|
|
---
|
|
|
|
## File Map
|
|
|
|
- Create: `src/cold_display_guard/cases.py`
|
|
- Create: `src/cold_display_guard/webhooks.py`
|
|
- Modify: `src/cold_display_guard/config.py`
|
|
- Modify: `src/cold_display_guard/main.py`
|
|
- Modify: `src/cold_display_guard/manage_api.py`
|
|
- Modify: `web/src/main.js`
|
|
- Modify: `web/src/zone-state.js`
|
|
- Create: `tests/test_cases.py`
|
|
- Create: `tests/test_webhooks.py`
|
|
- Modify: `tests/test_manage_api.py`
|
|
- Modify: `tests/test_main.py`
|
|
- Modify: `web/test/zone-state.test.js`
|
|
|
|
### Task 1: Backend Case State Layer
|
|
|
|
**Files:**
|
|
- Create: `src/cold_display_guard/cases.py`
|
|
- Create: `tests/test_cases.py`
|
|
- Modify: `src/cold_display_guard/main.py`
|
|
- Modify: `tests/test_main.py`
|
|
|
|
- [ ] Write failing tests for case creation, case escalation, manual/callback/auto close, and restore behavior in `tests/test_cases.py`.
|
|
- [ ] Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v`
|
|
Expected: failing assertions or import errors for missing case helpers.
|
|
- [ ] Implement minimal case dataclasses, JSONL load/save helpers, event-to-case transitions, and restore logic in `src/cold_display_guard/cases.py`.
|
|
- [ ] Wire runtime event processing in `src/cold_display_guard/main.py` so emitted batch events produce persisted case snapshots.
|
|
- [ ] Run:
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v`
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_main.py -v`
|
|
Expected: PASS.
|
|
|
|
### Task 2: Webhook Configuration And Delivery
|
|
|
|
**Files:**
|
|
- Create: `src/cold_display_guard/webhooks.py`
|
|
- Create: `tests/test_webhooks.py`
|
|
- Modify: `src/cold_display_guard/config.py`
|
|
- Modify: `src/cold_display_guard/main.py`
|
|
|
|
- [ ] Write failing tests for webhook config parsing, batch event payload delivery, case event payload delivery, and delivery-failure logging in `tests/test_webhooks.py`.
|
|
- [ ] Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
|
|
Expected: FAIL because webhook helpers/config support do not exist yet.
|
|
- [ ] Implement webhook settings parsing/saving in `src/cold_display_guard/config.py` and synchronous delivery plus audit logging in `src/cold_display_guard/webhooks.py`.
|
|
- [ ] Integrate webhook sending into `src/cold_display_guard/main.py` after local event and case persistence.
|
|
- [ ] Run:
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_config.py -v`
|
|
Expected: PASS.
|
|
|
|
### Task 3: Management API For Cases And Callback Handling
|
|
|
|
**Files:**
|
|
- Modify: `src/cold_display_guard/manage_api.py`
|
|
- Modify: `tests/test_manage_api.py`
|
|
- Modify: `src/cold_display_guard/config.py`
|
|
|
|
- [ ] Write failing API tests for `/api/manage/cases`, `/api/manage/cases/summary`, `/api/manage/cases/{case_id}/handle`, and `/api/manage/webhooks/case-update` in `tests/test_manage_api.py`.
|
|
- [ ] Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v`
|
|
Expected: FAIL because the new endpoints and case summary behavior are missing.
|
|
- [ ] Implement case listing, case summary, manual handle, and token-protected callback handling in `src/cold_display_guard/manage_api.py`.
|
|
- [ ] Ensure config payloads expose webhook settings and case/log sink paths without leaking secrets unnecessarily.
|
|
- [ ] Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v`
|
|
Expected: PASS.
|
|
|
|
### Task 4: Frontend Case Management UI
|
|
|
|
**Files:**
|
|
- Modify: `web/src/main.js`
|
|
- Modify: `web/src/zone-state.js`
|
|
- Modify: `web/test/zone-state.test.js`
|
|
|
|
- [ ] Write failing frontend tests for case summary mapping, case table rendering helpers, event/case separation, and manual handle request shaping in `web/test/zone-state.test.js`.
|
|
- [ ] Run: `node --test web/test/zone-state.test.js`
|
|
Expected: FAIL because case helpers and UI state handling do not exist yet.
|
|
- [ ] Implement frontend model helpers and UI rendering for case summaries, case rows, and manual handle actions while preserving the existing runtime event table semantics.
|
|
- [ ] Run:
|
|
- `node --test web/test/zone-state.test.js`
|
|
- `cd web && pnpm build`
|
|
Expected: PASS.
|
|
|
|
### Task 5: Full Verification And Documentation Alignment
|
|
|
|
**Files:**
|
|
- Modify: `README_zh.md`
|
|
- Modify: `tasks/todo.md`
|
|
|
|
- [ ] Update documentation for new webhook config, case logs, and management endpoints if implementation changed the documented surface area.
|
|
- [ ] Run targeted verification:
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v`
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v`
|
|
- `node --test web/test/zone-state.test.js`
|
|
Expected: PASS.
|
|
- [ ] Run full verification:
|
|
- `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest discover -s tests -v`
|
|
- `cd web && pnpm build`
|
|
Expected: PASS.
|
|
- [ ] Record final verification outcomes and any environmental caveats in `tasks/todo.md`.
|