household-bot/docs/specs/HOUSEBOT-041-miniapp-finance-dashboard.md

HOUSEBOT-041: Mini App Finance Dashboard

Summary

Expose the current settlement snapshot to the Telegram mini app so household members can inspect balances and included ledger items without leaving Telegram.

Goals

• Reuse the same finance service and settlement calculation path as bot statements.
• Show per-member balances for the active or latest billing cycle.
• Show the ledger items that contributed to the cycle total.
• Keep the layout usable inside the Telegram mobile webview.

Non-goals

• Editing balances or bills from the mini app.
• Historical multi-period browsing.
• Advanced charts or analytics.

Scope

• In: backend dashboard endpoint, authenticated mini app access, structured balance payload, ledger rendering in the Solid shell.
• Out: write actions, filters, pagination, admin-only controls.

Interfaces and Contracts

• Backend endpoint: POST /api/miniapp/dashboard
• Request body:
  • initData: string
• Success response:
  • authorized: true
  • dashboard.period
  • dashboard.currency
  • dashboard.totalDueMajor
  • dashboard.members[]
  • dashboard.ledger[]
• Membership failure:
  • authorized: false
  • reason: "not_member"
• Missing cycle response:
  • 404
  • error: "No billing cycle available"

Domain Rules

• Dashboard totals must match the same settlement calculation used by /finance statement.
• Money remains in minor units internally and is formatted to major strings only at the API boundary.
• Ledger items are ordered by event time, then title for deterministic display.

Security and Privacy

• Dashboard access requires valid Telegram initData and a mapped household member.
• CORS follows the same allow-list behavior as the mini app session endpoint.
• Only household-scoped finance data is returned.

Observability

• Reuse existing HTTP request logs from the bot server.
• Handler errors return explicit 4xx responses for invalid auth or missing cycle state.

Edge Cases and Failure Modes

• Invalid or expired initData returns 401.
• Non-members receive 403.
• Empty household billing state returns 404.
• Missing purchase descriptions fall back to Shared purchase.

Test Plan

• Unit: finance command service dashboard output and ledger ordering.
• Unit: mini app dashboard handler auth and payload contract.
• Integration: full repo typecheck, tests, build.

Acceptance Criteria

• Mini app members can view current balances and total due.
• Ledger entries match the purchase and utility inputs used by the settlement.
• Dashboard totals stay consistent with the bot statement output.
• Mobile shell renders balances and ledger states without placeholder-only content.