mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 21:14:02 +00:00
81 lines
2.1 KiB
Markdown
81 lines
2.1 KiB
Markdown
# HOUSEBOT-011: Monthly Settlement Engine
|
|
|
|
## Summary
|
|
|
|
Implement a deterministic monthly settlement use-case that computes per-member dues from rent, utilities, and shared purchases.
|
|
|
|
## Goals
|
|
|
|
- Compute per-member net due amounts deterministically.
|
|
- Support utility split modes: equal and weighted-by-days.
|
|
- Model purchase offsets where payer reimbursement reduces their due.
|
|
|
|
## Non-goals
|
|
|
|
- Persistence adapters.
|
|
- Telegram command handlers.
|
|
|
|
## Scope
|
|
|
|
- In: pure settlement use-case logic and tests.
|
|
- Out: DB writes, HTTP/bot integration.
|
|
|
|
## Interfaces and Contracts
|
|
|
|
- Input: `SettlementInput` from `@household/domain`.
|
|
- Output: `SettlementResult` with per-member line breakdown.
|
|
- Entry point: `calculateMonthlySettlement(input)` in application package.
|
|
|
|
## Domain Rules
|
|
|
|
- Use integer minor units only via `Money` value object.
|
|
- Rent is split evenly among active members.
|
|
- Utility split:
|
|
- `equal`: evenly among active members.
|
|
- `weighted_by_days`: proportional to `utilityDays` for each active member.
|
|
- Purchase offset per member:
|
|
- `purchaseSharedCost - purchasePaid`
|
|
- Net due:
|
|
- `rentShare + utilityShare + purchaseOffset`
|
|
|
|
## Data Model Changes
|
|
|
|
- None.
|
|
|
|
## Security and Privacy
|
|
|
|
- No PII required in settlement computation.
|
|
- Uses internal typed member IDs only.
|
|
|
|
## Observability
|
|
|
|
- Explanations list on each line provides deterministic calculation fragments.
|
|
|
|
## Edge Cases and Failure Modes
|
|
|
|
- No active members.
|
|
- Weighted utility split with invalid or missing day values.
|
|
- Purchase payer not in active members.
|
|
- Negative monetary inputs.
|
|
- Currency mismatch across input values.
|
|
|
|
## Test Plan
|
|
|
|
- Unit:
|
|
- 3-member equal split with purchase offset.
|
|
- 4-member weighted utility split.
|
|
- 5-member deterministic fixture with multiple purchases.
|
|
- Invalid weighted utility day input.
|
|
- Invalid purchase payer.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Equal utility split default implemented.
|
|
- [ ] Day-based utility split implemented.
|
|
- [ ] Deterministic fixtures for 3-5 roommate scenarios.
|
|
- [ ] Explicit errors for invalid settlement inputs.
|
|
|
|
## Rollout Plan
|
|
|
|
- Merge as dependency for bot command handlers and statement generation flow.
|