diff --git a/docs/specs/HOUSEBOT-076-miniapp-admin-billing-controls.md b/docs/specs/HOUSEBOT-076-miniapp-admin-billing-controls.md new file mode 100644 index 0000000..adf2a16 --- /dev/null +++ b/docs/specs/HOUSEBOT-076-miniapp-admin-billing-controls.md @@ -0,0 +1,118 @@ +# Mini App Admin Billing Controls + +## Summary + +Allow household admins to manage billing-cycle configuration from the mini app: rent amount, reminder timing, utility timing, utility categories, and admin promotion. + +## Goals + +- Let admins control billing settings without bot commands or Terraform edits. +- Persist household-level billing preferences in the database. +- Support configurable utility categories per household. +- Let admins promote other household members to admin from the mini app. +- Provide a stable API contract for future reminder and finance UI. + +## Non-goals + +- Full accounting redesign. +- Per-member notification preferences. +- Utility OCR/import integrations. +- Member removal/deactivation in this slice. + +## Scope + +- In: household billing settings persistence, utility category management, admin promotion, mini app admin endpoints/UI. +- Out: historical category migration tools, reminder delivery redesign, presence/day-based utility UI. + +## Interfaces and Contracts + +- Mini app admin endpoints: + - `POST /api/miniapp/admin/settings` + - `POST /api/miniapp/admin/settings/update` + - `POST /api/miniapp/admin/utility-categories/upsert` + - `POST /api/miniapp/admin/members/promote` +- Admin-only mini app settings screen sections: + - Rent + - Utility categories + - Reminder timing + - Admins + +## Domain Rules + +- Only active household admins may update household billing settings. +- Billing timing is household-scoped, not user-scoped. +- Utility categories are household-scoped and deterministic in display order. +- Promotion can only target active household members of the same household. +- At least one admin must remain in the household. +- Money remains stored in minor units only. + +## Data Model Changes + +- Add `household_billing_settings` one-to-one table: + - `household_id` + - `rent_currency` + - `rent_amount_minor` nullable until configured + - `rent_due_day` + - `rent_warning_day` + - `utilities_due_day` + - `utilities_reminder_day` + - `timezone` + - timestamps +- Add `household_utility_categories` table: + - `household_id` + - `slug` + - `name` + - `sort_order` + - `is_active` + - timestamps +- Seed default categories for new and existing households: + - `internet` + - `gas_water` + - `cleaning` + - `electricity` +- Add nullable `utility_category_id` to `utility_bills` in a later follow-up if needed for entry-level classification. + +## Security and Privacy + +- All endpoints require authenticated mini app sessions. +- All write endpoints require admin authorization from persisted membership. +- Promote-admin actions should be logged with actor and target IDs. + +## Observability + +- Structured logs for settings updates, category writes, and admin promotion. +- Include `householdId`, `actorMemberId`, `targetMemberId`, and changed fields. + +## Edge Cases and Failure Modes + +- Invalid day values outside 1..31. +- Reminder day later than due day. +- Duplicate category slug in one household. +- Promote-admin target missing or already admin. +- Missing settings record for an existing household should auto-bootstrap defaults. + +## Test Plan + +- Unit: + - settings validation rules + - category upsert ordering and duplicate handling + - admin promotion authorization +- Integration: + - DB adapter round-trips for settings and categories +- E2E: + - admin changes settings in mini app and sees persisted values on reload + +## Acceptance Criteria + +- [ ] Admin can view and update household billing settings in the mini app. +- [ ] Admin can manage household utility categories in the mini app. +- [ ] Admin can promote an active member to admin in the mini app. +- [ ] Reminder timing values are persisted per household. +- [ ] Existing households auto-bootstrap sensible defaults. + +## Rollout Plan + +- Add schema and repository support first. +- Ship read-only settings payload next. +- Enable admin writes after UI is wired. +- Keep bot command paths working during rollout.