feat:新增离线存储

README.md

@@ -15,25 +15,30 @@
 
 ## 快速开始
 
-1. 安装依赖（首次执行已完成可跳过）：
+1. 复制环境变量模板：
+   ```bash
+   cp apps/backend/.env.example apps/backend/.env.local
+   ```
+   若使用本地 MongoDB，请根据实际连接串调整 `MONGODB_URI`（例如 `mongodb://127.0.0.1:27017/ai-bill`）。
+2. 安装依赖：
    ```bash
    pnpm install
    ```
-2. （可选）启动内置 MongoDB（需 Docker 环境）：
+3. （可选）启动内置 MongoDB（需 Docker 环境）：
    ```bash
    pnpm db:up
    pnpm --filter backend seed   # 首次运行：写入默认用户/预算/交易
    ```
    结束后可通过 `pnpm db:down` 停止容器。
-3. 启动后端（默认端口 4000）：
+4. 启动后端（默认端口 4000）：
    ```bash
    pnpm dev:backend
    ```
-4. 启动前端（默认端口 5173）：
+5. 启动前端（默认端口 5173）：
    ```bash
    pnpm dev:frontend
    ```
-5. 或者并行启动：
+6. 或者并行启动：
    ```bash
    pnpm dev
    ```
@@ -41,7 +46,8 @@
 ## 后端说明（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`。
+- **必须** 连接 MongoDB：如使用内置 `docker-compose`，可直接使用 `MONGODB_URI=mongodb://mongo:27017/ai-bill`。
+- 所有 `/api` 接口（除 `/api/auth/*` 与签名校验的 `/api/transactions/notification`）均需要 `Authorization: Bearer <accessToken>` 访问。
 - 核心 API：
   - `POST /api/auth/login|register|refresh|logout|forgot-password`
   - `GET /api/transactions`、`POST /api/transactions`、`PATCH /api/transactions/:id`、`DELETE /api/transactions/:id`
@@ -51,6 +57,20 @@
   - `GET /api/notifications/status`（返回 webhook 地址、密钥提示、通知包名白名单及最近入库信息）
 - `pnpm --filter backend build` 进行编译，`pnpm --filter backend lint` 执行 ESLint。
 
+### Docker Compose 快速部署
+
+项目根目录提供 `Dockerfile` 与 `docker-compose.yml`，可一键启动 MongoDB + 后端服务：
+
+```bash
+docker compose up -d
+```
+
+默认暴露端口：
+- `mongodb://localhost:27017`（数据库名 `ai-bill`）
+- `http://localhost:4000/api`（后端 API）
+
+请在生产环境中覆盖 `docker-compose.yml` 中的占位密钥（`JWT_SECRET`、`NOTIFICATION_WEBHOOK_SECRET` 等），或使用 `env_file` 注入。
+
 ## 前端说明（apps/frontend）
 - 技术栈：Vue 3、TypeScript、Pinia、Vue Router、@tanstack/vue-query、TailwindCSS。
 - UI 与交互设计遵循 `UI设计规范 design_system.md` 与 `ui_mockup.html`。
@@ -74,6 +94,41 @@
 - 补充自动化测试：Vitest（前端组件/状态）、Jest + Supertest（后端 API）、Playwright（端到端流程）。
 - 优化移动端体验：离线缓存、渐进式加载、通知权限引导流程。
 
+## 部署指引（后端）
+
+### 方案一：自建服务器 + Docker Compose
+1. 准备 `.env` 文件（建议基于 `apps/backend/.env.example` 修改），确保密钥使用随机字符串：
+   ```
+   NODE_ENV=production
+   HOST=0.0.0.0
+   PORT=4000
+   MONGODB_URI=mongodb://mongo:27017/ai-bill
+   JWT_SECRET=<随机 64 位字符串>
+   JWT_REFRESH_SECRET=<随机 64 位字符串>
+   NOTIFICATION_WEBHOOK_SECRET=<与客户端一致的 HMAC 密钥>
+   ```
+2. 运行 `docker compose up -d`，Dockerfile 会自动构建并启动后端。
+3. 如需对外提供 HTTPS，可在服务器前再挂一层 Nginx/Traefik。
+
+### 方案二：托管平台（Railway / Fly.io / Render 等）
+1. 连接 Git 仓库，选择 Node 运行时；
+2. 配置上述环境变量；
+3. 构建命令 `pnpm install && pnpm --filter backend build`；启动命令 `node apps/backend/dist/main.js`；
+4. 平台提供的 HTTPS 域名可直接写入前端/安卓配置。
+
+### 部署后验证
+1. 访问 `GET /api/health`（或 `/api/notifications/status`）确认服务正常；
+2. 更新前端配置：`VITE_API_BASE_URL`、`gradle.properties`（Android）指向云端地址；
+3. 使用 curl 或 Android 真机测试通知上报流程。
+
+## 下一步规划（roadmap）
+- **数据解析**：完善通知正则识别逻辑、自动识别金额/类型/分类、提供幂等处理；
+- **多用户与权限**：前后端对接真实登录，支持注销、Token 刷新、路由守卫；
+- **体验优化**：交易/预算手动刷新、错误反馈 Toast、个性化偏好按钮交互优化；
+- **原生能力**：Android 完善通知权限引导、OCR 插件、摄像头票据扫描；
+- **部署与监控**：完善 Dockerfile/CI/CD、引入日志告警、Grafana/Prometheus 监控；
+- **扩展功能**：预算提醒、AI 分析历史记录、账本导出、团队共享账本。
+
 ## 功能调试指南
 
 ### 通知监听接口调试