Sync Repo-README from project files
223
Repo-README.-.md
Normal file
223
Repo-README.-.md
Normal file
@@ -0,0 +1,223 @@
|
|||||||
|
<!-- codex-wiki-sync:c58af68e9a33245bd76cc0b0 -->
|
||||||
|
|
||||||
|
> Mirrored from `/mnt/DATA/git/mousehold/README.md`.
|
||||||
|
> Origin: `repository`.
|
||||||
|
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||||
|
|
||||||
|
---
|
||||||
|
# Mousehold
|
||||||
|
|
||||||
|
Household finance ledger scaffold for an evidence-driven household budget and settlement system.
|
||||||
|
|
||||||
|
The first milestone is a local proof of concept:
|
||||||
|
|
||||||
|
- Python/FastAPI backend with SQLite by default.
|
||||||
|
- React/Vite web app.
|
||||||
|
- Local-agent scaffold for bank, CSV, statement, and IMAP ingestion.
|
||||||
|
- Raw observations become candidate, announced, outstanding, or confirmed financial events.
|
||||||
|
- Settlement and project summaries are calculated from confirmed ledger state.
|
||||||
|
|
||||||
|
## Run
|
||||||
|
|
||||||
|
```sh
|
||||||
|
python -m venv .venv
|
||||||
|
. .venv/bin/activate
|
||||||
|
pip install -r requirements-dev.txt
|
||||||
|
pip install -e .
|
||||||
|
mousehold-api
|
||||||
|
```
|
||||||
|
|
||||||
|
In another shell:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm install
|
||||||
|
npm run dev:web
|
||||||
|
```
|
||||||
|
|
||||||
|
Open `http://127.0.0.1:5173`.
|
||||||
|
|
||||||
|
The API listens on `http://127.0.0.1:8000` and exposes OpenAPI at `/docs`.
|
||||||
|
If `8000` is already occupied:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
uvicorn mousehold_api.main:app --host 127.0.0.1 --port 8001
|
||||||
|
cd apps/web
|
||||||
|
VITE_API_URL=http://127.0.0.1:8001 npm run dev -- --host 127.0.0.1 --port 5173
|
||||||
|
```
|
||||||
|
|
||||||
|
Or start both processes with matching local-dev CORS settings:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
scripts/launch-dev.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## MVP workflow
|
||||||
|
|
||||||
|
Use `Setup` to create a household, users, accounts, and connector profiles. The
|
||||||
|
top bar has a `Signed in` selector; choosing a user creates a local session
|
||||||
|
cookie for that browser. This is passwordless local-session support for the
|
||||||
|
self-hosted MVP, not a hosted multi-tenant auth system.
|
||||||
|
|
||||||
|
Create FinTS, IMAP, or CSV/statement connector profiles in `Setup` before using
|
||||||
|
the `Bank`, `Mail`, or `Statements` pages. Those pages use the saved profile for
|
||||||
|
defaults and import attribution, while PIN/TAN, IMAP password, and selected CSV
|
||||||
|
files stay ephemeral.
|
||||||
|
|
||||||
|
Use `Inbox` after manual entry or imports to review source observations. You can
|
||||||
|
keep an observation, confirm its linked event, ignore just the observation,
|
||||||
|
ignore the linked event too, or link the observation to an existing ledger event.
|
||||||
|
Use `Import runs` on the dashboard or connector pages to see imported,
|
||||||
|
duplicate, and event counts from each sync.
|
||||||
|
|
||||||
|
Use `Setup -> Backup` to export the household as JSON or create a local SQLite
|
||||||
|
backup file.
|
||||||
|
|
||||||
|
Browser-driven FinTS access is embedded in the API under `/agent/fints/...`.
|
||||||
|
Use the `FinTS` panel in the web app. PIN/TAN inputs go to the API process you
|
||||||
|
are running locally or self-hosting; normalized observations are imported into
|
||||||
|
the ledger only when you click import.
|
||||||
|
|
||||||
|
For comdirect, choose the `comdirect` preset in the FinTS panel. Enter your
|
||||||
|
comdirect Zugangsnummer as the bank user ID, leave customer ID empty, and enter
|
||||||
|
your registered FinTS product ID.
|
||||||
|
|
||||||
|
IMAP access is embedded under `/agent/imap/...` and available from the `Mail`
|
||||||
|
panel. Enter the IMAP host, login, app password, folder, and filters, then list
|
||||||
|
folders or scan. The scan uses a read-only folder selection and stages parsed
|
||||||
|
messages in the browser. Ledger observations are stored only when you click
|
||||||
|
import.
|
||||||
|
|
||||||
|
Use the `Statements` panel for PayPal Activity Download CSV files and Klarna CSV
|
||||||
|
statements. It previews rows in the browser and imports them as `paypal_csv` or
|
||||||
|
`klarna_csv` confirmation evidence.
|
||||||
|
|
||||||
|
Use the `Reconcile` panel after imports to find likely links between early mail
|
||||||
|
evidence, PayPal/Klarna statement rows, and bank/FinTS cash movement. Accepting a
|
||||||
|
suggestion links the evidence and can upgrade the original announced/outstanding
|
||||||
|
event to confirmed.
|
||||||
|
|
||||||
|
## Local Agent
|
||||||
|
|
||||||
|
Register a local agent after creating a household and user:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent register \
|
||||||
|
--household-id <household-id> \
|
||||||
|
--owner-user-id <user-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
Import demo observations:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent sync-demo \
|
||||||
|
--connection-id <connection-id> \
|
||||||
|
--household-id <household-id> \
|
||||||
|
--owner-user-id <user-id> \
|
||||||
|
--source-account-id <account-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
Import bank or PayPal CSV:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent sync-csv \
|
||||||
|
--connection-id <connection-id> \
|
||||||
|
--household-id <household-id> \
|
||||||
|
--owner-user-id <user-id> \
|
||||||
|
--source-account-id <account-id> \
|
||||||
|
--source-type bank_csv \
|
||||||
|
--path ./transactions.csv
|
||||||
|
```
|
||||||
|
|
||||||
|
Discover FinTS accounts locally:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent fints-accounts \
|
||||||
|
--profile my-bank \
|
||||||
|
--blz <bank-blz> \
|
||||||
|
--server <fints-endpoint-url> \
|
||||||
|
--bank-user-id <bank-login-id> \
|
||||||
|
--with-balances
|
||||||
|
```
|
||||||
|
|
||||||
|
Display recent FinTS transactions locally:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent fints-transactions \
|
||||||
|
--profile my-bank \
|
||||||
|
--blz <bank-blz> \
|
||||||
|
--server <fints-endpoint-url> \
|
||||||
|
--bank-user-id <bank-login-id> \
|
||||||
|
--iban <iban> \
|
||||||
|
--days 30
|
||||||
|
```
|
||||||
|
|
||||||
|
Import FinTS transactions into the ledger:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent sync-fints \
|
||||||
|
--api-url http://127.0.0.1:8001 \
|
||||||
|
--connection-id <connection-id> \
|
||||||
|
--household-id <household-id> \
|
||||||
|
--owner-user-id <user-id> \
|
||||||
|
--source-account-id <account-id> \
|
||||||
|
--profile my-bank \
|
||||||
|
--blz <bank-blz> \
|
||||||
|
--server <fints-endpoint-url> \
|
||||||
|
--bank-user-id <bank-login-id> \
|
||||||
|
--iban <iban> \
|
||||||
|
--days 30 \
|
||||||
|
--display
|
||||||
|
```
|
||||||
|
|
||||||
|
The FinTS connector prompts for the PIN if `MOUSEHOLD_FINTS_PIN` or `--pin` is
|
||||||
|
not supplied. TAN mechanism and TAN medium selection are handled interactively
|
||||||
|
and cached under `~/.config/mousehold/fints/<profile>.json`; the cache does not
|
||||||
|
store the PIN.
|
||||||
|
|
||||||
|
You can also run the FinTS browser bridge as a separate local-only process:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mousehold-agent serve --host 127.0.0.1 --port 8765
|
||||||
|
```
|
||||||
|
|
||||||
|
Set `VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765` in `apps/web/.env.development`
|
||||||
|
if you choose this mode.
|
||||||
|
|
||||||
|
CLI IMAP scanning can still use local environment variables:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
MOUSEHOLD_IMAP_HOST=imap.example.com
|
||||||
|
MOUSEHOLD_IMAP_USERNAME=you@example.com
|
||||||
|
MOUSEHOLD_IMAP_PASSWORD=app-password
|
||||||
|
MOUSEHOLD_IMAP_SENDER_FILTERS=klarna,paypal,bestellung,order,invoice
|
||||||
|
```
|
||||||
|
|
||||||
|
In embedded connector mode, the API process receives FinTS PIN/TAN and IMAP
|
||||||
|
password inputs while the request is running. In separate local-agent mode,
|
||||||
|
those inputs stay out of the API process. In both modes, connector metadata and
|
||||||
|
normalized observations are what get stored; credentials are not written to the
|
||||||
|
database.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
FinTS account and transaction retrieval is implemented and can run embedded in
|
||||||
|
the API or in the separate local agent. It still depends on your bank supporting
|
||||||
|
FinTS PIN/TAN access and on you providing the bank-specific endpoint and login
|
||||||
|
data. IMAP folder listing, scanning, email parsing, preview, and import are
|
||||||
|
implemented for the PoC. PayPal CSV and email evidence are the supported PayPal
|
||||||
|
PoC path. PSD2 aggregator connectors are still scaffolded.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pytest
|
||||||
|
npm run lint:web
|
||||||
|
npm run build:web
|
||||||
|
```
|
||||||
|
|
||||||
|
The Playwright MVP smoke test expects the API and web app to be running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npx playwright install
|
||||||
|
npm run test:e2e
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user