寻迹（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 或内部使用）：
GET /auth/register-captcha — 注册图形验证码（纯前端 captcha 集成）GET /auth/login-captcha — 登录图形验证码
六、待补充功能（未在 Analyzer 前端实现）
以下后端表有基础路由，但前端无对应页面：
| 功能 | 说明 | 建议 |
|---|
| 账户管理（accounts） | 余额账户增删改 | 需前端开发 |
| 定期账单（recurring） | 每月固定收支 | 需前端开发 |
| 预算（budgets） | 月度预算设置 | 需前端开发 |
| 预算预警（budget_alerts） | 阈值触发提醒 | 需前端开发 |
| 附件（attachments） | 上传图片等 | 需前端开发 |
| 通知（notifications） | 系统通知列表 | 需前端开发 |
| AI 日志（api_logs） | API 调用记录查询 | 需前端开发 |
> 这些功能可能由 Admin 后台（finance-admin）管理，不在用户端（Analyzer）暴露。