FinPilot

FinPilot is an AI-powered zero-based budgeting copilot built as a WeChat Mini Program. Income is allocated 100% into budget buckets (with forced savings lock); spending is parsed from natural language, approved by a rule engine (LLM writes copy only), and tracked separately from payment accounts. Stack: Taro/React, FastAPI, SQLite, multi-LLM Provider Adapter, wx.login + Bearer auth.

---

FinPilot 是一款 AI 零基预算 Copilot 微信小程序。收入 100% 零基分仓（储蓄强制锁定），自然语言记消费，规则引擎审批额度（LLM 仅生成文案），预算仓与支付账户分离。技术栈：Taro/React、FastAPI、SQLite、多模型 LLM Adapter、微信静默登录。

---

AI 零基预算 Copilot — 微信小程序（Taro/React）+ FastAPI + SQLite。

收入先 100% 分入 Budget Bucket，储蓄仓强制锁定（可支配 = 收入 − 储蓄分仓）；消费经 NL 解析后由规则引擎审批仓额度；LLM 只做结构化解析与文案。预算仓（能不能花）≠ 支付账户（从哪付）。领域规则与设计详见 docs/。

---

快速开始

1. 后端

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API 文档与健康检查：http://127.0.0.1:8000/docs

真机 / 微信登录测试：在 .env 填入 WECHAT_APP_SECRET（与 miniapp/project.config.json 的 AppID 一致）。配置后后端将拒绝 X-User-Id bypass，小程序启动时强制 wx.login。

2. 小程序

cd miniapp
npm install
npm run dev:weapp

用微信开发者工具打开 miniapp/（miniprogramRoot = dist/）；本地开发勾选「不校验合法域名」。

场景	miniapp/config/dev.ts
本机模拟器	TARO_APP_API_BASE: "http://127.0.0.1:8000"
局域网真机	改为电脑 WLAN IP，如 "http://192.168.1.13:8000"（URL 勿含空格）
跳过登录（仅模拟器）	TARO_APP_ALLOW_DEV_USER: "true"

默认 TARO_APP_ALLOW_DEV_USER: "false"，真机扫码会走微信登录。

3. LLM（可选）

编辑 backend/.env：

Provider	配置
Ollama（默认本地）	LLM_PROVIDER=ollama，OLLAMA_MODEL=qwen3.5:2b
通义 DashScope	LLM_PROVIDER=dashscope，填 DASHSCOPE_API_KEY
DeepSeek	LLM_PROVIDER=deepseek，填 DEEPSEEK_API_KEY

4. 本地 Docker（可选）

无需域名，仅跑 API 容器：见 docs/deploy-local.md

---

演示

90 秒演示脚本（含 seed 与口播）：docs/demo-90s.md

curl.exe -X POST http://127.0.0.1:8000/v1/demo/seed -H "X-User-Id: 1"
# 需未配置 WECHAT_APP_SECRET，或带 Bearer token

---

架构

miniapp (Taro)  --HTTP-->  FastAPI /v1
                              ├── auth (wx.login → Bearer)
                              ├── incomes (零基校验)
                              ├── transactions + approval rules
                              ├── ai (parse / approve)
                              ├── analysis (聚合 + 文案)
                              ├── buckets (预算仓 CRUD)
                              └── llm/* Provider Adapter

储蓄仓规则（强制储蓄）

• 收入到账后：可支配额度 = 收入 − 储蓄分仓金额；非储蓄仓消费不得超出可支配池。
• 当 收入 − 总支出 < 储蓄分仓金额 时，判定为已动用储蓄（含非储蓄超支与储蓄仓直接支出）。
• 审批时非储蓄仓的可用剩余 = min(仓剩余, 可支配池剩余)。

---

测试

cd backend
.\.venv\Scripts\Activate.ps1
pytest -q

---

Limitations

• 非银行级账务；账户无真实余额同步
• 微信登录需配置 AppSecret；开发可临时设 TARO_APP_ALLOW_DEV_USER=true 跳过
• 支持自定义预算仓；系统储蓄仓不可删除
• 审批建议与月度结论中的定性描述非审计结论
• 体验版上云（域名 + HTTPS）见 docs/deploy-experience.md，当前可暂缓

---

许可证

© 2026 Bosx HUO（@SomeH-Bosx）。保留所有权利。

本项目为个人作品集，未经授权请勿用于商业用途或再分发。