内容
# 家庭财务管理 - 所有的家庭财务记录，尽在一处
自托管的家庭财务应用程序：共享支出/收入账本、预算、投资组合（自动获取PSX和巴基斯坦共同基金价格）、贷款（债务）、定期账单和天课助手。
**API优先**：网页应用程序可以做的任何事情，任何AI代理也可以通过MCP或普通的REST做到。
## 技术栈
一个Node进程（Hono）提供REST API、一个MCP端点和一个React PWA，以及Postgres。
两个容器，一次`docker compose up`。
## 快速开始
```bash
cp .env.example .env # 设置DB_PASSWORD、BETTER_AUTH_SECRET（openssl rand -base64 32）、APP_URL
docker compose up -d --build
```
打开应用程序（默认`http://localhost:3000`，可以通过`.env`中的`APP_PORT`更改主机端口）：
1. **注册** — 创建您的账户。
2. **创建您的家庭** — 您将获得一个邀请码。
3. 您的配偶注册并**使用邀请码加入** → 共享账本，记录归属个人。
4. **更多 → 代理和API密钥** — 为每个代理创建API密钥（一个用于您，一个用于您的配偶的代理等）。
## 连接代理
每个操作都通过两种方式公开；两者都使用每个用户的API密钥进行身份验证。
密钥所有者被记录为代理创建的记录的付款人。
### MCP（Claude、ChatGPT和任何支持MCP的代理）
`https://your-host/mcp`上的可流式HTTP端点 — 26种工具（`add_transaction`、`get_budget_status`、`get_portfolio`、`get_monthly_report`、`add_loan`等）。
```bash
# Claude 代码
claude mcp add finance --transport http https://your-host/mcp --header "x-api-key: YOUR_KEY"
```
`Authorization: Bearer YOUR_KEY`也适用于仅支持Bearer身份验证的客户端。
### REST（Hermes、OpenClaw、脚本等）
在`/api/v1/*`下使用`x-api-key`头进行相同的操作 — 例如，您的WhatsApp Hermes代理记录一项支出：
```bash
curl -X POST https://your-host/api/v1/transactions \
-H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
-d '{"type":"expense","amount":2500,"category":"Groceries","note":"Imtiaz weekly run"}'
```
资源：`transactions`、`categories`、`budgets`（+ `/budgets/status`）、`accounts`、
`portfolio`、`holdings`、`instruments`、`prices`（+ `/prices/refresh`）、`loans`（+ `/:id/payments`）、
`recurring`、`reports/monthly`、`reports/overview?period=week|month|quarter|year&offset=-N`
（或`?from=YYYY-MM-DD&to=YYYY-MM-DD`用于自定义范围 — 总计、上期比较、
趋势桶、类别/成员细分；也是`get_report` MCP工具）、`zakat`、`household`。
金额以PKR为单位；日期为`YYYY-MM-DD`（Asia/Karachi）。
## 价格数据（自动）
每日作业（18:30和22:00 PKT）获取：
- **PSX股票** — 从`dps.psx.com.pk`获取的收盘价（非官方端点；软失败）。
- **共同基金** — 从[MUFAP NAV表](https://www.mufap.com.pk/Industry/IndustryStatDaily?tab=3)抓取的日NAV。
添加基金时，使用**确切的基金名称**，如其在那里出现（例如`Al Meezan Mutual Fund`、`Mahaana Islamic Cash Fund`）。
- **其他资产**（黄金、财产等）— 通过*设置价格*进行手动估值；手动价格始终优于获取的价格。
定期账单在到期日（00:15 PKT，停机后补齐）转化为账本记录。
## 使用Cloudflare Tunnel公开
从任何地方（手机、WhatsApp代理等）访问应用程序（及其`/mcp`端点），无需打开端口：
1. 将您的域名添加到Cloudflare（免费计划足够）。
2. [Zero Trust仪表盘](https://one.dash.cloudflare.com) → **网络 → 隧道 → 创建隧道** → *Cloudflared*连接器 → 为其命名（例如`hisaab`）。
3. 在连接器页面选择**Docker**，复制显示的命令中的令牌，并将其放入`.env`中作为`TUNNEL_TOKEN=...`。
4. 添加**公共主机名**：`hisaab.yourdomain.com` → 服务**HTTP** → `app:3000`。
5. 更新`.env`：
```
APP_URL=https://hisaab.yourdomain.com
TRUSTED_ORIGINS=http://localhost:3000 # 保持本地登录可用（匹配您的APP_PORT）
```
6. `docker compose --profile public up -d --build`
7. 在公共URL上注册您的家庭成员，然后在`.env`中设置`DISABLE_SIGNUPS=true`并重启 — 您的实例上无法创建新账户。
代理然后从任何地方连接到`https://hisaab.yourdomain.com/mcp`（头部`x-api-key`）。
## 开发
```bash
docker compose up -d db # Postgres在localhost:5433
npm install
npm run dev # API + SPA在:3000上提供（PORT=3001更改）
npm run dev:web # 可选：带有HMR的Vite开发服务器，代理/api → :3001
npm run db:generate # 在编辑src/db/schema.ts后重新生成SQL迁移
npm run typecheck && npm run build
```
身份验证表（`src/db/auth-schema.ts`）生成：
`npx @better-auth/cli generate --config scripts/auth-config.ts --output src/db/auth-schema.ts`。
布局：`src/services/`包含所有业务逻辑；`src/routes.ts`（REST）和`src/mcp.ts`（MCP工具）
是同一服务的薄包装，因此两个接口不会漂移。
