mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 15:34:03 +00:00
feat(bot): add multi-household reminder delivery
This commit is contained in:
53
docs/specs/HOUSEBOT-075-multi-household-reminder-delivery.md
Normal file
53
docs/specs/HOUSEBOT-075-multi-household-reminder-delivery.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# HOUSEBOT-075 Multi-Household Reminder Delivery
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the current reminder placeholder path with a real multi-household reminder dispatcher.
|
||||
|
||||
## Problem
|
||||
|
||||
Current reminder jobs only claim a dedupe key and return `messageText`. They do not send any Telegram message. They also require a single global `HOUSEHOLD_ID`, which is incompatible with the bot's DB-backed multi-household model.
|
||||
|
||||
## Target behavior
|
||||
|
||||
- Scheduler endpoint accepts `utilities`, `rent-warning`, or `rent-due`
|
||||
- For the target billing period, the bot resolves all configured household reminder targets from the database
|
||||
- A household reminder target uses:
|
||||
- bound `reminders` topic if present
|
||||
- otherwise the household chat itself
|
||||
- For each target household, the bot:
|
||||
- builds deterministic reminder text
|
||||
- claims dedupe for `(householdId, period, reminderType)`
|
||||
- posts the message to Telegram only when the claim succeeds
|
||||
- Dry-run returns the planned dispatches without posting
|
||||
|
||||
## Delivery model
|
||||
|
||||
- Scheduler route remains a single endpoint per reminder type
|
||||
- One request fan-outs across all reminder-enabled households
|
||||
- Logs include an entry per household outcome
|
||||
|
||||
## Data source
|
||||
|
||||
Household config comes from `HouseholdConfigurationRepository`:
|
||||
|
||||
- household chat binding is required
|
||||
- reminder topic binding is optional
|
||||
|
||||
## Runtime contract
|
||||
|
||||
Reminder jobs require:
|
||||
|
||||
- `DATABASE_URL`
|
||||
- one scheduler auth mechanism (`SCHEDULER_SHARED_SECRET` or allowed OIDC service accounts)
|
||||
|
||||
Reminder jobs must not require:
|
||||
|
||||
- `HOUSEHOLD_ID`
|
||||
- group/topic reminder env vars
|
||||
|
||||
## Follow-ups
|
||||
|
||||
- per-household reminder settings
|
||||
- localized reminder copy using persisted household/member locale
|
||||
- scheduler fan-out observability metrics
|
||||
Reference in New Issue
Block a user