feat:Android notification

README.md

@@ -73,3 +73,61 @@
 - 引入 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` 查看最新入库情况。