mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 22:34: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
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# HOUSEBOT-002: Finance Domain Model
|
|
|
|
## Summary
|
|
|
|
Define domain entities and invariants for rent, utilities, shared purchases, and monthly settlements.
|
|
|
|
## Goals
|
|
|
|
- Create a deterministic model for monthly household accounting.
|
|
- Encode money-safe arithmetic with integer minor units.
|
|
- Support equal split by default with optional day-based utility override.
|
|
|
|
## Non-goals
|
|
|
|
- Telegram command handlers.
|
|
- Mini app rendering.
|
|
|
|
## Scope
|
|
|
|
- In: domain entities, use-case contracts, and validation rules.
|
|
- Out: persistence adapter implementation.
|
|
|
|
## Interfaces and Contracts
|
|
|
|
- `Money` value object (`currency: GEL`, `amountMinor: bigint | number`).
|
|
- `SettlementInput` contract with members, rent, utilities, purchases, overrides.
|
|
- `SettlementResult` contract with per-member due and explanation lines.
|
|
|
|
## Domain Rules
|
|
|
|
- Rent is fixed per cycle and split equally among active members.
|
|
- Utilities split equally unless per-member day override is provided.
|
|
- Shared purchases reduce payer due amount and distribute cost across members.
|
|
- No floating-point operations.
|
|
|
|
## Data Model Changes
|
|
|
|
- Define required table contracts (implemented in later DB ticket):
|
|
- `billing_cycles`
|
|
- `rent_rules`
|
|
- `utility_bills`
|
|
- `presence_overrides`
|
|
- `purchase_entries`
|
|
- `settlements`, `settlement_lines`
|
|
|
|
## Security and Privacy
|
|
|
|
- Do not store unnecessary personal data.
|
|
- Use internal IDs for members in calculations.
|
|
|
|
## Observability
|
|
|
|
- Structured calculation logs (input hash, cycle id, result totals).
|
|
- Error event on invalid settlement state.
|
|
|
|
## Edge Cases and Failure Modes
|
|
|
|
- Member count is zero.
|
|
- Utility day overrides sum to zero.
|
|
- Negative amounts from malformed inputs.
|
|
- Duplicate purchase entries.
|
|
|
|
## Test Plan
|
|
|
|
- Unit:
|
|
- money arithmetic and normalization
|
|
- equal split and day-weighted split cases
|
|
- purchase offsets and reconciliation checks
|
|
- Integration: not in this ticket.
|
|
- E2E: not in this ticket.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Value objects implemented and tested.
|
|
- [ ] Settlement input/output contracts defined.
|
|
- [ ] Deterministic settlement math covered by tests.
|
|
- [ ] Edge cases produce explicit domain errors.
|
|
|
|
## Rollout Plan
|
|
|
|
- Merge as dependency for settlement engine and bot handlers.
|