mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 22:04:03 +00:00
4a26ac81d6
* feat(WHE-15): bootstrap bun workspace with app and package scaffolds * chore(WHE-17): switch workspace typecheck to tsgo * chore(WHE-16): configure oxlint and oxfmt no-semicolon style * chore: address CodeRabbit review feedback * chore: apply coderabbit fixes and add review script * docs: add ADR decision metadata
83 lines
1.9 KiB
Markdown
83 lines
1.9 KiB
Markdown
# HOUSEBOT-004: Reminders and Scheduler
|
|
|
|
## Summary
|
|
|
|
Schedule and deliver household billing reminders to dedicated Telegram topics.
|
|
|
|
## Goals
|
|
|
|
- Automate utility and rent reminders on configured dates.
|
|
- Ensure idempotent sends and reliable retries.
|
|
- Keep scheduling externalized via Cloud Scheduler.
|
|
|
|
## Non-goals
|
|
|
|
- Dynamic natural-language reminder editing.
|
|
- Per-user DM reminders in v1.
|
|
|
|
## Scope
|
|
|
|
- In: scheduler endpoints, reminder generation, send guards.
|
|
- Out: full statement rendering details.
|
|
|
|
## Interfaces and Contracts
|
|
|
|
- HTTP endpoints triggered by Cloud Scheduler:
|
|
- `/jobs/reminder/utilities`
|
|
- `/jobs/reminder/rent-warning`
|
|
- `/jobs/reminder/rent-due`
|
|
- Job payload includes cycle and household references.
|
|
|
|
## Domain Rules
|
|
|
|
- Utilities reminder target: day 3 or 4 (configurable).
|
|
- Rent warning target: day 17.
|
|
- Rent due target: day 20.
|
|
- Duplicate-send guard keyed by household + cycle + reminder type.
|
|
|
|
## Data Model Changes
|
|
|
|
- `reminder_dispatch_log`:
|
|
- `household_id`
|
|
- `billing_cycle`
|
|
- `reminder_type`
|
|
- `sent_at`
|
|
- `telegram_message_id`
|
|
|
|
## Security and Privacy
|
|
|
|
- Scheduler endpoints protected by shared secret/auth header.
|
|
- No sensitive data in scheduler payloads.
|
|
|
|
## Observability
|
|
|
|
- Job execution logs with correlation IDs.
|
|
- Success/failure counters per reminder type.
|
|
- Alert on repeated send failures.
|
|
|
|
## Edge Cases and Failure Modes
|
|
|
|
- Telegram API temporary failure.
|
|
- Scheduler retry causes duplicate call.
|
|
- Missing household topic mapping.
|
|
|
|
## Test Plan
|
|
|
|
- Unit:
|
|
- date and reminder eligibility logic
|
|
- Integration:
|
|
- endpoint auth and idempotency behavior
|
|
- E2E:
|
|
- simulated month schedule through all reminder events
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Scheduler endpoints implemented and authenticated.
|
|
- [ ] Reminder sends are idempotent.
|
|
- [ ] Logs and counters available for each job run.
|
|
- [ ] Retry behavior validated.
|
|
|
|
## Rollout Plan
|
|
|
|
- Deploy with dry-run mode first, then enable live sends.
|