134 lines
6.9 KiB
Markdown
134 lines
6.9 KiB
Markdown
# AI 记账应用框架
|
||
|
||
基于《项目设计蓝图》与《UI 设计规范》搭建的前后端 Monorepo。当前版本提供可运行的基础框架、示例数据与 API 接口骨架，现已补齐账户认证、预算管理、交易通知入库等核心流程，便于继续迭代为完整的 AI 记账应用。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── apps
|
||
│ ├── backend # Node.js + Express + TypeScript，提供 REST API 骨架
|
||
│ └── frontend # Vue 3 + Vite + TailwindCSS，包含移动端风格 UI
|
||
├── pnpm-workspace.yaml
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
1. 安装依赖（首次执行已完成可跳过）：
|
||
```bash
|
||
pnpm install
|
||
```
|
||
2. （可选）启动内置 MongoDB（需 Docker 环境）：
|
||
```bash
|
||
pnpm db:up
|
||
pnpm --filter backend seed # 首次运行：写入默认用户/预算/交易
|
||
```
|
||
结束后可通过 `pnpm db:down` 停止容器。
|
||
3. 启动后端（默认端口 4000）：
|
||
```bash
|
||
pnpm dev:backend
|
||
```
|
||
4. 启动前端（默认端口 5173）：
|
||
```bash
|
||
pnpm dev:frontend
|
||
```
|
||
5. 或者并行启动：
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
## 后端说明（apps/backend）
|
||
- 技术栈：Express、TypeScript、Zod、Mongoose、Pino。
|
||
- `.env.example` 给出了基础环境变量；开发时可复制为 `.env.local`。
|
||
- 支持 MongoDB 或内存双模式运行：当 `MONGODB_URI` 未设置时自动回退到示例数据，方便离线体验。若使用内置 Docker 服务，可配置 `MONGODB_URI=mongodb://root:example@127.0.0.1:27017/ai-bill?authSource=admin`。
|
||
- 核心 API：
|
||
- `POST /api/auth/login|register|refresh|logout|forgot-password`
|
||
- `GET /api/transactions`、`POST /api/transactions`、`PATCH /api/transactions/:id`、`DELETE /api/transactions/:id`
|
||
- `POST /api/transactions/notification`（HMAC 签名校验的通知入库）
|
||
- `GET /api/analysis/habits`（基于实时交易聚合）与 `POST /api/analysis/calories`
|
||
- `GET /api/budgets`、`POST /api/budgets`、`PATCH /api/budgets/:id`、`DELETE /api/budgets/:id`
|
||
- `GET /api/notifications/status`（返回 webhook 地址、密钥提示、通知包名白名单及最近入库信息）
|
||
- `pnpm --filter backend build` 进行编译，`pnpm --filter backend lint` 执行 ESLint。
|
||
|
||
## 前端说明（apps/frontend）
|
||
- 技术栈：Vue 3、TypeScript、Pinia、Vue Router、@tanstack/vue-query、TailwindCSS。
|
||
- UI 与交互设计遵循 `UI设计规范 design_system.md` 与 `ui_mockup.html`。
|
||
- 关键页面与能力：
|
||
- 仪表盘：展示当月收入/支出统计、预算剩余、快捷操作。
|
||
- 交易列表：支持按类型筛选、新增、备注、删除，区分数据来源（手动/通知/OCR/AI）。
|
||
- AI 分析：实时消费洞察 + 卡路里估算对话体验。
|
||
- 设置中心：账户信息、偏好开关、预算卡片管理（新增/删除、阈值滑杆）。
|
||
- 认证流程：登录/注册/找回密码，提供「体验模式」快捷入口。
|
||
- 默认通过 Axios 访问后端 API，无法连接时自动回退到本地示例数据。
|
||
- 若需要跨端访问，可在 `apps/frontend/.env.local` 中调整 `VITE_API_BASE_URL`（默认指向 `http://localhost:4000/api`）。
|
||
- 构建与预览：
|
||
```bash
|
||
pnpm --filter frontend build
|
||
pnpm --filter frontend preview
|
||
```
|
||
|
||
## 下一步建议
|
||
- 接入真实登录态（JWT 校验、刷新、登出）、以及通知监听插件（Android `NotificationListenerService`）调用示例。
|
||
- 引入 OCR / LLM 能力（Google Vision、Gemini 等）补齐票据识别与消费分析的真实数据链路。
|
||
- 补充自动化测试：Vitest（前端组件/状态）、Jest + Supertest（后端 API）、Playwright（端到端流程）。
|
||
- 优化移动端体验：离线缓存、渐进式加载、通知权限引导流程。
|
||
|
||
## 功能调试指南
|
||
|
||
### 通知监听接口调试
|
||
后端已提供 `POST /api/transactions/notification` 接口，通过 HMAC-SHA256 校验签名后写入交易。调试步骤：
|
||
1. 在后端启动（`pnpm dev:backend`）前，确认 `.env.local` 中的 `NOTIFICATION_WEBHOOK_SECRET`、`HOST=0.0.0.0` 配置，前端使用相同局域网地址；
|
||
2. 构造签名：`payload = packageName|title|body|timestamp`；`signature = HMAC-SHA256(payload, secret)`，示例脚本：
|
||
```bash
|
||
secret="38f71dbf99ab510d970165e43979f945f992848406117c8597a892837331a853"
|
||
package="com.eg.android.AlipayGphone"
|
||
title="支付宝到账"
|
||
body="到账 88.88 元"
|
||
timestamp=$(date +%s000)
|
||
|
||
payload="${package}|${title}|${body}|${timestamp}"
|
||
signature=$(printf '%s' "$payload" | openssl dgst -sha256 -hex -hmac "$secret" | awk '{print $2}')
|
||
|
||
curl -X POST "http://<后端IP>:4000/api/transactions/notification" \
|
||
-H "Content-Type: application/json" \
|
||
-d "{
|
||
\"packageName\": \"${package}\",
|
||
\"title\": \"${title}\",
|
||
\"body\": \"${body}\",
|
||
\"receivedAt\": ${timestamp},
|
||
\"signature\": \"${signature}\"
|
||
}"
|
||
```
|
||
3. 返回 `202` 表示接口验证成功；前端「设置中心 → 通知监听」卡片会显示入库次数、最近时间，并在交易列表里出现新的 `pending` 记录。
|
||
4. 若要模拟多条通知，可调整 `packageName`、金额或时间戳；若签名不匹配，后端会返回 `401` 并在日志输出 “Notification signature mismatch”。
|
||
|
||
### Android 打包与真机测试
|
||
前端目前为 Web 工程，可通过 Capacitor 集成 Android 壳。建议步骤：
|
||
1. 在 `apps/frontend` 下安装 Capacitor：
|
||
```bash
|
||
pnpm add @capacitor/core @capacitor/cli @capacitor/android
|
||
pnpm add -D @capacitor/assets
|
||
pnpm cap init # 或使用现有配置
|
||
pnpm cap add android
|
||
```
|
||
在 `capacitor.config.ts` 中配置开发服务器地址、`webDir: 'dist'`。
|
||
新增通知监听后，需要在 `apps/frontend/android/gradle.properties`（或运行 `gradlew` 时的命令行）写入：
|
||
```
|
||
API_BASE_URL=http://<你的后端IP>:4000/api
|
||
NOTIFICATION_WEBHOOK_SECRET=<与后端一致的 HMAC 密钥>
|
||
```
|
||
2. 开发模式：`pnpm dev:frontend -- --host 0.0.0.0` + `pnpm dev:backend`，将手机/模拟器连接同一局域网，Capacitor `server.url` 指向 `http://<电脑IP>:5173`，即可在真机上加载开发版 Web 页面。
|
||
3. 生产版打包：
|
||
```bash
|
||
pnpm --filter frontend build
|
||
pnpm cap copy android
|
||
```
|
||
打开 `apps/frontend/android/`，在 Android Studio 中构建（`Build > Build APK(s)`），或生成签名 APK。
|
||
4. 原生通知监听：在 Android 工程里实现 `NotificationListenerService`（或接入自定义插件）将捕获的通知调用上述 webhook（HMAC 签名规则一致），即可验证完整通知→后端→前端流程。
|
||
|
||
A 自带的调试技巧包括：
|
||
- `adb reverse tcp:4000 tcp:4000` / `adb reverse tcp:5173 tcp:5173`（模拟器访问电脑服务）；
|
||
- `adb shell cmd notification post -S bigtext <package> <title> <text>`（模拟通知）；
|
||
- 使用 Android Studio Network Inspector/Logcat 观察上传请求；后端终端输出或 `GET /api/notifications/status` 查看最新入库情况。
|