mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 13:54:02 +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
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# Household Bot Roadmap
|
|
|
|
## Vision
|
|
|
|
Build a clean, modular Telegram household finance platform with a mini app, designed for real use and portfolio-grade engineering quality.
|
|
|
|
## Principles
|
|
|
|
- Hexagonal architecture with strict ports/adapters boundaries.
|
|
- Small, composable modules and strong type safety.
|
|
- Incremental delivery with small commits and always-green CI.
|
|
- Money-safe calculations (integer minor units only).
|
|
- Pragmatic v1, explicit enterprise extensions in later phases.
|
|
|
|
## Phase 0 - Foundation
|
|
|
|
Goal: establish architecture, tooling, and delivery guardrails.
|
|
|
|
Deliverables:
|
|
|
|
- Bun workspace monorepo layout.
|
|
- TypeScript strict base config.
|
|
- Oxlint setup and formatting conventions (no semicolons).
|
|
- CI pipeline for typecheck, lint, tests, and build.
|
|
- Initial ADRs and spec template.
|
|
|
|
Exit criteria:
|
|
|
|
- Fresh clone can run quality checks with one command.
|
|
- CI passes on default branch.
|
|
- Architecture boundaries are documented.
|
|
|
|
## Phase 1 - Finance Core
|
|
|
|
Goal: implement deterministic domain logic for monthly settlements.
|
|
|
|
Deliverables:
|
|
|
|
- Domain value objects (`Money`, `BillingPeriod`, IDs).
|
|
- Settlement engine for rent + utility + purchase offsets.
|
|
- Default equal utility split, with optional day-based override.
|
|
- Domain unit tests covering edge cases.
|
|
|
|
Exit criteria:
|
|
|
|
- Settlement logic is adapter-independent.
|
|
- Domain test suite covers normal and failure paths.
|
|
|
|
## Phase 2 - Telegram Bot Core
|
|
|
|
Goal: process household activity and manage billing cycles in Telegram.
|
|
|
|
Deliverables:
|
|
|
|
- grammY bot webhook service.
|
|
- Topic listener for `Общие покупки`.
|
|
- Utility and rent commands.
|
|
- Billing cycle commands and statements.
|
|
- Idempotent message processing.
|
|
|
|
Exit criteria:
|
|
|
|
- Purchase messages are ingested and persisted.
|
|
- Monthly statement can be produced via command.
|
|
|
|
## Phase 3 - Reminders and Scheduling
|
|
|
|
Goal: automate key payment reminders.
|
|
|
|
Deliverables:
|
|
|
|
- Cloud Scheduler jobs.
|
|
- Reminder handlers for day 3/4 utilities, day 17 rent notice, day 20 due date.
|
|
- Dedicated topic posting for reminders.
|
|
|
|
Exit criteria:
|
|
|
|
- Scheduled reminders fire reliably.
|
|
- Duplicate sends are prevented.
|
|
|
|
## Phase 4 - Mini App V1
|
|
|
|
Goal: deliver a usable household dashboard.
|
|
|
|
Deliverables:
|
|
|
|
- SolidJS mini app shell.
|
|
- Telegram initData verification and membership gate.
|
|
- Ledger view, balances, and settlement preview.
|
|
- RU/EN localization.
|
|
|
|
Exit criteria:
|
|
|
|
- Active group members can view current month balances.
|
|
- Financial views are consistent with bot calculations.
|
|
|
|
## Phase 5 - Anonymous Feedback + Safety
|
|
|
|
Goal: support safer household communication.
|
|
|
|
Deliverables:
|
|
|
|
- Anonymous DM flow to bot.
|
|
- Sanitized/rephrased repost to group topic.
|
|
- Rate limits and blocklist moderation.
|
|
|
|
Exit criteria:
|
|
|
|
- Sender identity is hidden from group users.
|
|
- Abuse controls prevent spam and obvious misuse.
|
|
|
|
## Phase 6 - Hardening and Portfolio Polish
|
|
|
|
Goal: production readiness and strong showcase quality.
|
|
|
|
Deliverables:
|
|
|
|
- Sentry integration and structured logging.
|
|
- Integration and end-to-end tests.
|
|
- Runbooks and operational docs.
|
|
- Architecture diagram and demo instructions.
|
|
|
|
Exit criteria:
|
|
|
|
- Incident/debug workflow is documented.
|
|
- Repo can be reviewed as a coherent system design case study.
|
|
|
|
## Deferred (Post-v1)
|
|
|
|
- House wiki pages (Wi-Fi, rules, how-to).
|
|
- Cleaning/karma workflow.
|
|
- Advanced analytics and trend insights.
|
|
- Prometheus/Grafana/Kubernetes stack.
|