2025-08-21 11:07:54 +08:00
|
|
|
|
# Dream-Machine 采购清单管理系统
|
|
|
|
|
|
|
|
|
|
|
|
一个专为 Ubiquiti 网络设备采购管理设计的现代化 Web 应用，提供完整的采购跟踪、预算管理和数据同步功能。
|
|
|
|
|
|
|
|
|
|
|
|
## 🚀 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
### 环境要求
|
|
|
|
|
|
|
|
|
|
|
|
- **Node.js**: v18.0.0 或更高版本
|
|
|
|
|
|
- **npm**: v8.0.0 或更高版本
|
|
|
|
|
|
- **现代浏览器**: Chrome 90+, Firefox 88+, Safari 14+
|
|
|
|
|
|
- **Make** (可选): 推荐安装用于使用 Makefile 命令
|
|
|
|
|
|
|
|
|
|
|
|
### 一键启动（推荐）
|
|
|
|
|
|
|
|
|
|
|
|
#### Linux/macOS
|
|
|
|
|
|
```bash
|
|
|
|
|
|
chmod +x start.sh
|
|
|
|
|
|
./start.sh
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### Windows
|
|
|
|
|
|
```cmd
|
|
|
|
|
|
start.bat
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
这些脚本会自动检查系统要求并提供交互式菜单选择不同的启动方式。
|
|
|
|
|
|
|
|
|
|
|
|
### 开发环境启动
|
|
|
|
|
|
|
|
|
|
|
|
#### 方法1: 使用 Makefile（推荐）
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 安装依赖并启动开发服务器
|
|
|
|
|
|
make dev
|
|
|
|
|
|
|
|
|
|
|
|
# 或者分步执行
|
|
|
|
|
|
make install # 安装依赖
|
|
|
|
|
|
make start # 启动开发服务器
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 方法2: 直接使用 npm
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 安装依赖
|
|
|
|
|
|
npm install
|
|
|
|
|
|
|
|
|
|
|
|
# 启动开发服务器
|
|
|
|
|
|
npm run dev
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2025-08-21 14:56:53 +08:00
|
|
|
|
开发服务器将在 `http://localhost:3003` 启动，支持热重载。
|
2025-08-21 11:07:54 +08:00
|
|
|
|
|
|
|
|
|
|
### 生产环境部署
|
|
|
|
|
|
|
|
|
|
|
|
#### 构建生产版本
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 使用 Makefile
|
|
|
|
|
|
make build
|
|
|
|
|
|
|
|
|
|
|
|
# 或使用 npm
|
|
|
|
|
|
npm run build
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 预览生产版本
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 使用 Makefile
|
|
|
|
|
|
make preview
|
|
|
|
|
|
|
|
|
|
|
|
# 或使用 npm
|
|
|
|
|
|
npm run preview
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 📁 项目结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
src/
|
|
|
|
|
|
├── components/ # 通用组件
|
|
|
|
|
|
│ ├── ui/ # shadcn/ui 组件库
|
|
|
|
|
|
│ └── DataManager.tsx # 数据管理组件
|
|
|
|
|
|
├── features/ # 功能模块
|
|
|
|
|
|
│ └── purchase/ # 采购管理功能
|
|
|
|
|
|
├── hooks/ # 自定义 Hooks
|
|
|
|
|
|
├── lib/ # 工具库
|
|
|
|
|
|
├── pages/ # 页面组件
|
|
|
|
|
|
├── store/ # 状态管理
|
|
|
|
|
|
└── types/ # 类型定义
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 🛠 开发工具
|
|
|
|
|
|
|
|
|
|
|
|
### 代码质量检查
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 使用 Makefile
|
|
|
|
|
|
make lint # 运行 ESLint 检查
|
|
|
|
|
|
make lint-fix # 自动修复可修复的问题
|
|
|
|
|
|
|
|
|
|
|
|
# 或使用 npm
|
|
|
|
|
|
npm run lint
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 清理和重置
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 清理构建文件和 node_modules
|
|
|
|
|
|
make clean
|
|
|
|
|
|
|
|
|
|
|
|
# 重新安装依赖
|
|
|
|
|
|
make clean-install
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## ✨ 核心功能
|
|
|
|
|
|
|
|
|
|
|
|
### 📋 采购清单管理
|
|
|
|
|
|
- 完整的 CRUD 操作（增删改查）
|
|
|
|
|
|
- 实时状态跟踪和可视化
|
|
|
|
|
|
- 支持批量编辑和操作
|
|
|
|
|
|
|
|
|
|
|
|
### 💰 预算跟踪
|
|
|
|
|
|
- 自动计算总预算、已使用和剩余金额
|
|
|
|
|
|
- 多币种支持（SGD/USD → RMB）
|
|
|
|
|
|
- 实时汇率换算
|
|
|
|
|
|
|
|
|
|
|
|
### 🔍 高级筛选和排序
|
|
|
|
|
|
- 按分类、状态、重要程度筛选
|
|
|
|
|
|
- 多字段排序支持
|
|
|
|
|
|
- 筛选偏好自动保存
|
|
|
|
|
|
|
|
|
|
|
|
### 📊 数据管理
|
|
|
|
|
|
- JSON 和 Excel 格式导入导出
|
|
|
|
|
|
- 数据备份和恢复
|
|
|
|
|
|
- 跨设备数据同步
|
|
|
|
|
|
|
|
|
|
|
|
### 🖨 打印功能
|
|
|
|
|
|
- 专业的打印模板
|
|
|
|
|
|
- 无水印输出
|
|
|
|
|
|
- 优化的打印布局
|
|
|
|
|
|
|
|
|
|
|
|
## 🔧 技术栈
|
|
|
|
|
|
|
|
|
|
|
|
- **前端框架**: React 18 + TypeScript
|
|
|
|
|
|
- **构建工具**: Vite 6
|
|
|
|
|
|
- **UI 组件**: shadcn/ui + Tailwind CSS
|
|
|
|
|
|
- **状态管理**: Zustand
|
|
|
|
|
|
- **路由**: React Router v6
|
|
|
|
|
|
- **数据持久化**: LocalStorage + 自动备份
|
|
|
|
|
|
- **表单管理**: React Hook Form + Zod
|
|
|
|
|
|
- **图标**: Lucide React
|
|
|
|
|
|
|
|
|
|
|
|
## 📚 开发指南
|
|
|
|
|
|
|
|
|
|
|
|
### 添加新功能
|
|
|
|
|
|
1. 在 `src/features` 下创建功能模块
|
|
|
|
|
|
2. 使用 Zustand 管理状态
|
|
|
|
|
|
3. 遵循 TypeScript 类型约束
|
|
|
|
|
|
4. 添加对应的测试
|
|
|
|
|
|
|
|
|
|
|
|
### 样式指南
|
|
|
|
|
|
- 使用 Tailwind CSS 工具类
|
|
|
|
|
|
- 遵循设计系统规范（见 `src/index.css`）
|
|
|
|
|
|
- 优先使用 shadcn/ui 组件
|
|
|
|
|
|
|
|
|
|
|
|
### 状态管理
|
|
|
|
|
|
- 组件内状态使用 `useState`
|
|
|
|
|
|
- 跨组件状态使用 Zustand store
|
|
|
|
|
|
- 持久化数据使用 `persist` 中间件
|
|
|
|
|
|
|
|
|
|
|
|
## 🐛 问题排查
|
|
|
|
|
|
|
|
|
|
|
|
### 常见问题
|
|
|
|
|
|
|
|
|
|
|
|
1. **开发服务器启动失败**
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 清理缓存后重试
|
|
|
|
|
|
make clean-install
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
2. **构建失败**
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 检查代码质量
|
|
|
|
|
|
make lint
|
|
|
|
|
|
# 修复后重新构建
|
|
|
|
|
|
make build
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
3. **类型错误**
|
|
|
|
|
|
- 检查 TypeScript 配置
|
|
|
|
|
|
- 确保所有类型定义正确
|
|
|
|
|
|
|
|
|
|
|
|
### 调试技巧
|
|
|
|
|
|
- 使用浏览器开发者工具
|
|
|
|
|
|
- 查看控制台错误信息
|
|
|
|
|
|
- 检查网络请求状态
|
|
|
|
|
|
|
|
|
|
|
|
## 📋 部署checklist
|
|
|
|
|
|
|
|
|
|
|
|
- [ ] 运行 `make lint` 确保代码质量
|
|
|
|
|
|
- [ ] 运行 `make build` 确保构建成功
|
|
|
|
|
|
- [ ] 运行 `make preview` 测试生产版本
|
|
|
|
|
|
- [ ] 检查所有功能正常工作
|
|
|
|
|
|
- [ ] 验证响应式设计
|
|
|
|
|
|
- [ ] 测试数据导入导出功能
|
|
|
|
|
|
|
|
|
|
|
|
## 🤝 贡献指南
|
|
|
|
|
|
|
|
|
|
|
|
1. Fork 项目
|
|
|
|
|
|
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
|
|
|
|
|
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
|
|
|
|
|
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
|
|
|
|
|
5. 打开 Pull Request
|
|
|
|
|
|
|
|
|
|
|
|
## 📄 许可证
|
|
|
|
|
|
|
|
|
|
|
|
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
|
|
|
|
|
|
|
|
|
|
|
## 📞 支持
|
|
|
|
|
|
|
|
|
|
|
|
如果遇到问题或需要帮助，请：
|
|
|
|
|
|
1. 查看本文档的问题排查部分
|
|
|
|
|
|
2. 检查已知问题列表
|
|
|
|
|
|
3. 创建新的 Issue 描述问题
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
**Happy Coding! 🎉**
|
