100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# Novault Frontend
|
||
|
||
Novault 的前端应用，一个基于 **React**, **TypeScript** 和 **Vite** 构建的现代化、本地优先的个人记账与资产管理应用。
|
||
|
||
## ✨ 特性
|
||
|
||
- **现代化 UI 设计**: 采用 Premium Glassmorphism（高级玻璃拟态）设计语言，提供流畅、美观的用户体验。
|
||
- **本地优先**: 快速响应，数据安全。
|
||
- **资产可视化**: 包含账户关系图谱、收支报表等丰富的数据可视化功能。
|
||
- **全功能记账**: 支持多账户、多币种、预算管理、周期性交易等。
|
||
- **响应式布局**: 完美适配桌面端、平板和移动端设备。
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **核心框架**: [React](https://react.dev/) + [TypeScript](https://www.typescriptlang.org/)
|
||
- **构建工具**: [Vite](https://vitejs.dev/)
|
||
- **路由**: [React Router](https://reactrouter.com/)
|
||
- **状态/样式管理**:
|
||
- CSS Variables & Modules (无第三方 UI 库依赖，完全自定义设计系统)
|
||
- Custom Hooks (Theme, Device, etc.)
|
||
- **数据可视化**: [Apache ECharts](https://echarts.apache.org/) (via `echarts-for-react`)
|
||
- **图标**: [Iconify](https://iconify.design/) (主要使用 Solar Icons 系列)
|
||
|
||
## 📂 目录结构
|
||
|
||
```
|
||
frontend/
|
||
├── public/ # 静态资源 (图标, favicon)
|
||
├── src/
|
||
│ ├── assets/ # 编译期静态资源
|
||
│ ├── components/ # 通用及业务组件
|
||
│ │ ├── account/ # 账户相关组件
|
||
│ │ ├── budget/ # 预算相关组件
|
||
│ │ ├── common/ # 通用 UI 组件 (Layout, Navigation 等)
|
||
│ │ ├── transaction/# 交易相关组件
|
||
│ │ └── ...
|
||
│ ├── config/ # 配置文件 (如类别图标映射)
|
||
│ ├── hooks/ # 自定义 React Hooks (useTheme 等)
|
||
│ ├── pages/ # 页面视图 (路由目标)
|
||
│ ├── router/ # 路由配置
|
||
│ ├── services/ # API 服务层 (处理后端通信)
|
||
│ ├── styles/ # 全局样式系统
|
||
│ │ ├── variables.css # 设计变量 (颜色, 字体, 间距)
|
||
│ │ ├── components.css # 通用组件样式 (Card, Button, Input)
|
||
│ │ ├── themes.css # 主题定义 (Light/Dark)
|
||
│ │ └── animations.css # 动画定义
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── utils/ # 通用工具函数 (格式化, 计算)
|
||
│ ├── App.tsx # 根组件
|
||
│ └── main.tsx # 入口文件
|
||
└── vite.config.ts # Vite 配置
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 预备环境
|
||
|
||
- Node.js (推荐 v18+)
|
||
- npm 或 yarn/pnpm
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
应用将在 `http://localhost:5173` (默认端口) 启动。
|
||
|
||
### 构建生产版本
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建产物将输出到 `dist/` 目录。
|
||
|
||
## 🎨 设计系统
|
||
|
||
本项目采用自定义的 **CSS 变量系统** 进行样式管理，主要文件位于 `src/styles/`：
|
||
|
||
- **色彩**: 定义了语义化的颜色变量（`--color-primary`, `--color-bg`, `--glass-bg` 等），支持自动深色模式切换。
|
||
- **玻璃拟态**: 通过 `.glass-panel`, `.glass-card` 等类名快速应用磨砂玻璃效果。
|
||
- **响应式**: 使用移动优先的策略，通过 CSS 媒体查询适配不同屏幕。
|
||
|
||
## 🤝 贡献规范
|
||
|
||
1. **组件开发**: 新组件应尽可能复用 `styles/components.css` 中的原子类或组件类。
|
||
2. **服务层**: 所有后端请求应封装在 `src/services/` 下的对应服务文件中。
|
||
3. **类型安全**: 尽量避免使用 `any`，并在 `src/types/` 中定义共享类型。
|
||
|
||
## 📄 License
|
||
|
||
MIT
|