docs(plan): add Phase 1, 2, 3 implementation specs

2026-07-05 08:51:38 -04:00
parent f540cbe7ef
commit c9dd9ba076
12 changed files with 3041 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Phase 2 — User Experience & Advanced Filtering
+
+## Scope
+
+This phase introduces **user-facing features** that significantly improve the experience of keyword tracking. Currently, every matching ad triggers an instant notification regardless of price, location, or time of day — leading to noise for popular keywords.
+
+After this phase:
+- Users can configure price ranges and postcodes per keyword
+- Notifications respect mute hours (no alerts at 3 AM)
+- Users opt into digest mode (bundled summaries instead of individual pings)
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  User Interaction Layer                       │
+│                                              │
+│  Telegram Bot Commands:                       │
+│  /set_price_min <kw> <€>                     │
+│  /set_price_max <kw> <€>                     │
+│  /set_postcode  <kw> <list>                  │
+│  /mute_hours   <start>-<end>                 │
+│  /digest     on|off                          │
+│                                              │
+└──────────┬───────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Database Schema (extended)                   │
+│                                              │
+│  keywords table:                              │
+│    + price_min      int                       │
+│    + price_max      int                       │
+│    + allowed_postcodes text[]                 │
+│                                              │
+│  user_settings table (new):                   │
+│    telegram_id   text PK                     │
+│    mute_start    time                        │
+│    mute_end      time                        │
+│    digest_mode   bool DEFAULT false          │
+│    digest_interval int DEFAULT 60            │
+└──────────┬───────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Notification Pipeline (modified)             │
+│                                              │
+│  For each new ad:                             │
+│    ├─ filter by price_min/max? → skip        │
+│    ├─ filter by allowed_postcodes? → skip     │
+│    ├─ user in mute hours?                    │
+│    │   digest_on → buffer to digest_table   │
+│    │   digest_off→ skip notification         │
+│    └─ normal → send now                      │
+│                                              │
+│  Digest scheduler (separate task):            │
+│    every digest_interval:                    │
+│      collect buffered notifications per user │
+│      format as summary message               │
+│      send single message                     │
+│      clear buffer                            │
+└──────────────────────────────────────────────┘
+```
+
+## Tasks
+
+| Task | File | Description |
+|------|------|-------------|
+| Price range filters per keyword | [task-price-filters.md](./task-price-filters.md) | Add `price_min` and `price_max` columns to the keywords table; filter ads during processing based on these thresholds. Bot commands to set/unset. |
+| Location / postcode filters per keyword | [task-postcode-filters.md](./task-postcode-filters.md) | Add `allowed_postcodes` text[] column to keywords; only notify if an ad's location matches any allowed postcode. |
+| Mute hours per user | [task-mute-hours.md](./task-mute-hours.md) | Create `user_settings` table with configurable mute window (start/end time in UTC); suppress notifications during this window. |
+| Digest / summary notifications | [task-digest-notifications.md](./task-digest-notifications.md) | Buffer notifications for users with digest mode enabled; send a bundled summary at configured intervals instead of individual alerts. |
+
+## General Acceptance Criteria
+
+- [ ] Users can set price min/max on any keyword and only receive notifications within that range
+- [ ] Postcode filtering works — ads outside allowed postcodes are silently skipped (not counted as new)
+- [ ] Mute hours suppress all notifications to a user during the configured window, regardless of keyword
+- [ ] Digest mode buffers individual alerts and sends one summary message at the configured interval
+- [ ] All filters combine correctly: an ad is only notified if it passes price + postcode checks AND the user is not muted (or digest mode active)
+- [ ] The bot provides clear feedback when a filter setting is changed ("Keyword X: price range set to €100–€500")
+- [ ] Admin can view all keyword filters and user settings via `/keywords` command output