whekin/household-bot
1
0
Fork 0
mirror of https://github.com/whekin/household-bot.git synced 2026-03-31 10:24:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(bot): add multi-household reminder delivery

Browse Source
This commit is contained in:
whekin
2026-03-09 16:50:57 +04:00
parent 12f33e7aea
commit 16f9981fee
27 changed files with 412 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/runbooks/dev-setup.md
View File

@@ -62,10 +62,10 @@ bun run review:coderabbit
- Typed environment validation lives in `packages/config/src/env.ts`.
- Copy `.env.example` to `.env` before running app/database commands.
- Local bot feature flags come from env presence:
- finance commands require `DATABASE_URL` and `HOUSEHOLD_ID`
- purchase ingestion also requires `TELEGRAM_HOUSEHOLD_CHAT_ID` and `TELEGRAM_PURCHASE_TOPIC_ID`
- anonymous feedback also requires `TELEGRAM_FEEDBACK_TOPIC_ID`
- reminders require `SCHEDULER_SHARED_SECRET` or `SCHEDULER_OIDC_ALLOWED_EMAILS`
- finance commands require `DATABASE_URL` plus household setup in Telegram via `/setup`
- purchase ingestion requires `DATABASE_URL` plus a bound purchase topic via `/bind_purchase_topic`
- anonymous feedback requires `DATABASE_URL` plus a bound feedback topic via `/bind_feedback_topic`
- reminders require `DATABASE_URL` plus `SCHEDULER_SHARED_SECRET` or `SCHEDULER_OIDC_ALLOWED_EMAILS`
- mini app CORS can be constrained with `MINI_APP_ALLOWED_ORIGINS`
- Migration workflow is documented in `docs/runbooks/migrations.md`.
- First deploy flow is documented in `docs/runbooks/first-deploy.md`.

53
docs/specs/HOUSEBOT-075-multi-household-reminder-delivery.md Normal file
View 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