243 lines
6.8 KiB
Markdown
243 lines
6.8 KiB
Markdown
# StudSpider Status Dashboard
|
|
|
|
A real-time inventory management dashboard that integrates with Square POS, Brickset.com, and a SQL database to track and visualize LEGO inventory changes.
|
|
|
|
## 📋 Overview
|
|
|
|
StudSpider Status is a comprehensive dashboard application designed to monitor and track inventory discrepancies between Square's inventory system and actual stock levels. The application provides real-time insights into inventory changes, theme distributions, and system statistics.
|
|
|
|
## 🎯 Key Features
|
|
|
|
- **Real-Time Inventory Tracking**: Monitor changes between Square inventory and database records
|
|
- **Square Integration**: Direct integration with Square POS API for inventory management
|
|
- **Brickset.com API**: Fetch LEGO set information and theme data
|
|
- **SQL Database Backend**: Persistent storage for tracking historical inventory changes
|
|
- **Visual Analytics**: Interactive charts and graphs showing inventory distribution by theme
|
|
- **Change Log**: Detailed timeline of all inventory modifications (additions, updates, deletions)
|
|
- **Statistics Dashboard**: Quick overview of total sets, themes, and recent changes
|
|
|
|
## 🛠️ Technology Stack
|
|
|
|
### Frontend
|
|
- **Vue 3**: Modern reactive JavaScript framework with Composition API
|
|
- **Vuetify 3**: Material Design component library
|
|
- **Vue Router**: Client-side routing for single-page application
|
|
- **Pinia**: State management solution
|
|
- **Vite**: Next-generation frontend build tool
|
|
- **ApexCharts/Vuetify Charts**: Data visualization
|
|
|
|
### Backend Integration
|
|
- **Square API**: Point of sale and inventory management
|
|
- **Brickset API**: LEGO set database and information
|
|
- **SQL Database**: Inventory change tracking and historical data
|
|
|
|
## 📦 Installation
|
|
|
|
### Prerequisites
|
|
- Node.js (v16 or higher)
|
|
- pnpm (recommended) or npm
|
|
- Access to Square API credentials
|
|
- Brickset API key
|
|
- SQL database connection
|
|
|
|
### Setup
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd studspider-status
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
3. Configure environment variables:
|
|
Create a `.env` file in the root directory:
|
|
```env
|
|
VITE_SQUARE_API_KEY=your_square_api_key
|
|
VITE_SQUARE_ACCESS_TOKEN=your_square_access_token
|
|
VITE_BRICKSET_API_KEY=your_brickset_api_key
|
|
VITE_DATABASE_URL=your_database_connection_string
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
5. Build for production:
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
## 🚀 Usage
|
|
|
|
### Development
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
Access the application at `http://localhost:5173`
|
|
|
|
### Production Build
|
|
```bash
|
|
pnpm build
|
|
pnpm preview
|
|
```
|
|
|
|
### Linting
|
|
```bash
|
|
pnpm lint
|
|
```
|
|
|
|
## 📊 Features Breakdown
|
|
|
|
### Dashboard View
|
|
- **Recent Changes Panel**: Real-time list of inventory modifications with timestamps
|
|
- **Statistics Cards**: Quick metrics showing total sets, total themes, and weekly changes
|
|
- **Theme Distribution Chart**: Visual pie chart displaying inventory breakdown by LEGO theme
|
|
|
|
### Navigation
|
|
- **Dashboard**: Main inventory overview
|
|
- **Review**: Inventory review and reconciliation
|
|
- **Statistics**: Detailed analytics and reporting
|
|
- **Demo**: Component showcase and UI examples
|
|
|
|
## 🔌 API Integration
|
|
|
|
### Square API
|
|
The application connects to Square's Inventory API to:
|
|
- Fetch current inventory levels
|
|
- Track inventory adjustments
|
|
- Monitor stock changes in real-time
|
|
|
|
### Brickset API
|
|
Integration with Brickset.com provides:
|
|
- LEGO set information and details
|
|
- Theme categorization
|
|
- Set metadata and specifications
|
|
|
|
### Database
|
|
SQL database stores:
|
|
- Historical inventory snapshots
|
|
- Change logs with timestamps
|
|
- User actions and modifications
|
|
- Theme and set relationships
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
studspider-status/
|
|
├── src/
|
|
│ ├── assets/ # Static assets
|
|
│ ├── components/ # Reusable Vue components
|
|
│ │ ├── AppFooter.vue
|
|
│ │ ├── HelloWorld.vue
|
|
│ │ └── DynamicPieChart.vue
|
|
│ ├── layouts/ # Page layout templates
|
|
│ │ └── default.vue
|
|
│ ├── pages/ # Application pages (auto-routed)
|
|
│ │ ├── index.vue # Dashboard home page
|
|
│ │ ├── demo.vue # Component demo page
|
|
│ │ ├── stats.vue # Statistics page
|
|
│ │ └── review.vue # Review page
|
|
│ ├── plugins/ # Vue plugins (Vuetify, Router, etc.)
|
|
│ │ ├── index.js
|
|
│ │ └── vuetify.js
|
|
│ ├── router/ # Vue Router configuration
|
|
│ │ └── index.js
|
|
│ ├── stores/ # Pinia state management
|
|
│ │ ├── app.js
|
|
│ │ └── index.js
|
|
│ ├── styles/ # Global styles and SCSS
|
|
│ │ └── settings.scss
|
|
│ ├── App.vue # Root application component
|
|
│ └── main.js # Application entry point
|
|
├── public/ # Public static files
|
|
├── .env # Environment variables (not committed)
|
|
├── package.json # Project dependencies
|
|
├── vite.config.mjs # Vite configuration
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🎨 Customization
|
|
|
|
### Adding New Pages
|
|
1. Create a new `.vue` file in `src/pages/`
|
|
2. Add route metadata at the bottom:
|
|
```vue
|
|
<route lang="yaml">
|
|
name: yourpage
|
|
layout: default
|
|
</route>
|
|
```
|
|
3. Add navigation item in `App.vue`:
|
|
```vue
|
|
<v-list-item
|
|
prepend-icon="mdi-your-icon"
|
|
title="Your Page"
|
|
value="yourpage"
|
|
to="/yourpage"
|
|
/>
|
|
```
|
|
|
|
### Modifying Themes
|
|
Edit the color palette in component files or update Vuetify theme settings in `src/plugins/vuetify.js`.
|
|
|
|
## 🔒 Security Notes
|
|
|
|
- Never commit API keys or sensitive credentials
|
|
- Use environment variables for all API configuration
|
|
- Implement proper authentication for production deployments
|
|
- Secure database connections with appropriate credentials
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Development Server Won't Start
|
|
```bash
|
|
# Clear node modules and reinstall
|
|
rm -rf node_modules
|
|
pnpm install
|
|
|
|
# Clear Vite cache
|
|
rm -rf .vite
|
|
```
|
|
|
|
### Routing Not Working
|
|
- Ensure all pages have proper route metadata
|
|
- Check that `unplugin-vue-router` is configured in `vite.config.mjs`
|
|
- Verify the layout system is properly set up
|
|
|
|
## 📝 License
|
|
|
|
[Add your license here]
|
|
|
|
## 👥 Contributing
|
|
|
|
Contributions are welcome! Please follow these steps:
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Commit your changes
|
|
4. Push to the branch
|
|
5. Open a Pull Request
|
|
|
|
## 🔮 Future Enhancements
|
|
|
|
- [ ] Real-time WebSocket updates for inventory changes
|
|
- [ ] Export reports to PDF/Excel
|
|
- [ ] Advanced filtering and search capabilities
|
|
- [ ] User authentication and role-based access
|
|
- [ ] Email notifications for inventory discrepancies
|
|
- [ ] Mobile app version
|
|
- [ ] Automated inventory reconciliation
|
|
- [ ] Barcode scanning integration
|
|
- [ ] Multi-location inventory support
|
|
|
|
## 📧 Support
|
|
|
|
For issues and questions, please open an issue on the GitHub repository.
|
|
|
|
---
|
|
|
|
Built with ❤️ using Vue 3 and Vuetify 3 |