first commit

README.md

@@ -0,0 +1,75 @@
+# 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（端到端流程）。
+- 优化移动端体验：离线缓存、渐进式加载、通知权限引导流程。