寻迹（Financial Analyzer）API 概览

文档版本：2026-04-02 后端服务：finance-analyzer-backend（端口 3001） 前端应用：Financial_Analyzer（React + Vite，用户端）

一、架构概览

┌─────────────────────────────────────────────────────────────┐
│                    Financial_Analyzer 前端                     │
│                  (React + Vite, port 5173)                   │
└─────────────────────┬───────────────────────────────────────┘
                      │ axios (baseURL: /api)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                finance-analyzer-backend                      │
│              (Express, port 3001, SQLite)                    │
│                                                              │
│  路由：                                                       │
│    /api/auth/*          — 认证、注册、登录、刷新Token            │
│    /api/bills/*         — 账单管理、成员管理、邀请                │
│    /api/transactions/*  — 交易记录、CSV 导入                    │
│    /api/apikeys/*       — AI Key 管理、解析、跨账单共享          │
│    /api/ai/*            — AI 对话、语音转写                      │
└─────────────────────────────────────────────────────────────┘

Admin 后台（finance-admin-backend，端口 3002）通过 /api/admin/* 提供管理 API，与 Analyzer 前端无关。

二、数据库表一览

表名 说明 归属
users 用户账号 auth
refresh_tokens Refresh Token 存储 auth
bills 账单主表 bills
bill_members 账单成员与角色 bills
bill_invitations 邀请记录（24h 有效期） bills
categories 分类（per bill） bills
transactions 交易流水（per bill） transactions
bill_csv_uploads CSV 上传元数据（per bill） transactions
accounts 账户表（余额管理） -
recurring 定期账单 -
budgets 预算 -
budget_alerts 预算预警 -
attachments 附件 -
notifications 通知 -
api_keys AI API Keys（per bill, per user） apikeys
user_provider_order 用户自定义 Key 排序 apikeys
api_logs AI API 调用日志 -

注：accounts、recurring、budgets、budget_alerts、attachments、notifications、api_logs 等表的完整 CRUD API 尚未在 Analyzer 前端页面中实现（对应功能可能由 Admin 后台管理，或未开发）。

三、API 路由清单

3.1 认证 /api/auth

方法 路径 说明 文档
GET /register-captcha 获取注册图形验证码 选填 未文档化
GET /login-captcha 获取登录图形验证码 选填 未文档化
POST /send-register-email 发送注册邮箱验证码 必填 01-auth.md
POST /send-reset-email 发送密码重置邮件 必填 01-auth.md
POST /reset-password 重置密码（含 Token） 必填 01-auth.md
POST /register 注册账号 必填 01-auth.md
POST /login 用户登录 必填 01-auth.md
POST /refresh 刷新 Access Token 必填 01-auth.md
POST /logout 登出 必填 01-auth.md
GET /me 获取当前用户信息 必填 01-auth.md
PUT /me/profile 更新用户资料 必填 01-auth.md
POST /guest-login 游客登录 必填 01-auth.md
POST /upgrade-guest 升级游客为正式账号 必填 01-auth.md
POST /me/onboard-done 标记新手引导完成 必填 01-auth.md
POST /dev/reset-ip 重置 IP 限制（developer 专用） 必填 01-auth.md

3.2 账单 /api/bills

方法 路径 说明 文档
GET / 获取用户所有账单 必填 02-bills.md
GET /:id 获取账单详情（含成员、分类） 必填 02-bills.md
POST / 创建新账单 必填 02-bills.md
PUT /:id 更新账单（名称、描述） 必填 02-bills.md
DELETE /:id 删除账单 必填 02-bills.md
GET /:id/members 获取账单成员列表 必填 02-bills.md
PUT /:id/members/:memberId 修改成员角色 必填 02-bills.md
DELETE /:id/members/:memberId 移除账单成员 必填 02-bills.md
PUT /:id/prompt 更新用户在账单的 AI Prompt 必填 02-bills.md
GET /:id/categories 获取账单分类列表 必填 02-bills.md
POST /:id/invite 邀请成员加入账单 必填 02-bills.md

3.3 交易 /api/transactions

方法 路径 说明 文档
GET /:billId 获取账单所有交易记录 必填 03-transactions.md
POST /:billId/upload 上传 CSV（覆盖式导入） 必填 03-transactions.md

3.4 API Keys /api/apikeys

方法 路径 说明 文档
GET /user 获取用户在账单下的 Key 列表 必填 04-apikeys.md
POST /verify/user 验证 Key 有效性 必填 04-apikeys.md
PUT /user 创建或更新 Key 必填 04-apikeys.md
DELETE /user/:provider 删除 Key 必填 04-apikeys.md
GET /resolve/:billId 获取账单最优 Key 列表 必填 04-apikeys.md
GET /resolve-all/:billId 获取账单所有可用 Key 必填 04-apikeys.md
GET /suggestions 获取跨账单 Key 导入建议 必填 04-apikeys.md
POST /import 跨账单导入 Key 配置 必填 04-apikeys.md
PATCH /user/share 切换 Key 共享状态 必填 04-apikeys.md
PATCH /order/user 批量更新 Key 排序 必填 04-apikeys.md

3.5 AI /api/ai

方法 路径 说明 文档
POST /transcribe 音频转写（Whisper） 必填 05-ai.md
POST /voice-chat 语音直发对话 必填 05-ai.md
POST /chat 文本对话（流式 SSE） 必填 05-ai.md
POST /chat-simple 文本对话（非流式） 必填 05-ai.md

四、前端页面与 API 映射

前端页面 路由 核心 API 调用 数据来源
LoginPage /login POST /auth/login, POST /auth/register DataContext (auth)
HomePage / GET /bills, GET /bills/:id, GET /transactions/:billId DataContext
BillPage /bill 账单管理全功能：CRUD /bills, /bills/:id/members, POST /transactions/:billId/upload DataContext
SettingsPage /settings /apikeys/* (Key 管理) 直接调用 api
ApiGuidePage /api-guide 无后端调用（纯前端代码示例生成） -
DeveloperPage /dev /dev/perf-pulse（仅开发者模式可见） 直接调用 api

注：DataContext 是全局状态管理器，在应用启动时从 /api/auth/me 获取用户信息，页面切换时通过 selectBill(billId) 触发数据加载。

五、文档完成度

文档 状态 备注
00-overview.md（本文） 🆕 新增 API 全局索引
01-auth.md 必填 完整 覆盖全部 auth 路由
02-bills.md 必填 完整 bills + members + invitations + categories
03-transactions.md 必填 完整 transactions + CSV upload + bill_csv_uploads
04-apikeys.md 必填 完整 全部 8 个端点 + 表结构
05-ai.md 必填 完整 chat + transcribe + voice-chat

未文档化端点（minor，Admin 或内部使用）：

六、待补充功能（未在 Analyzer 前端实现）

以下后端表有基础路由，但前端无对应页面：

功能 说明 建议
账户管理（accounts） 余额账户增删改 需前端开发
定期账单（recurring） 每月固定收支 需前端开发
预算（budgets） 月度预算设置 需前端开发
预算预警（budget_alerts） 阈值触发提醒 需前端开发
附件（attachments） 上传图片等 需前端开发
通知（notifications） 系统通知列表 需前端开发
AI 日志（api_logs） API 调用记录查询 需前端开发

这些功能可能由 Admin 后台（finance-admin）管理，不在用户端（Analyzer）暴露。

← 概览认证 Auth →