feat(miniapp): add finance dashboard view

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

@@ -0,0 +1,79 @@
+# 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.