readme added
This commit is contained in:
365
README.md
365
README.md
@@ -0,0 +1,365 @@
|
||||
# Auburn Oil Customer Gateway - Frontend
|
||||
|
||||
A modern, responsive customer portal for Auburn Oil's heating oil delivery service. Built with React and Ant Design for a professional, user-friendly experience.
|
||||
|
||||
```
|
||||
______ _ _
|
||||
| ____| | | | |
|
||||
| |__ _ __ ___ _ __| |_ ___ _ __ ____ | |
|
||||
| __| '__/ _ \| '_ \ __/ _ \ '_ \ / _ || |
|
||||
| | | | | (_) | | | | || __/ | | | (_| ||_|
|
||||
|_| |_| \___/|_| |_|\__\___|_| |_|\__,_|(_)
|
||||
|
||||
Auburn Oil Customer Portal
|
||||
```
|
||||
|
||||
## What This Does
|
||||
|
||||
A self-service portal where Auburn Oil customers can:
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Place Orders** | Order heating oil delivery with real-time pricing |
|
||||
| **View Deliveries** | Track delivery history and status |
|
||||
| **Manage Payments** | Save, update, and remove credit cards securely |
|
||||
| **Tank Photos** | Upload annual tank inspection images |
|
||||
| **Account Management** | Update profile, change password |
|
||||
|
||||
## Screenshots
|
||||
|
||||
### Customer Dashboard
|
||||
- Current oil pricing at a glance
|
||||
- Recent delivery history with status indicators
|
||||
- Tank inspection photo preview
|
||||
- Quick access to place new orders
|
||||
|
||||
### New Customer Registration
|
||||
- 3-step wizard for easy onboarding
|
||||
- Tank photo upload with preview
|
||||
- Automatic account number generation
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Framework**: React 18.2 with Hooks
|
||||
- **UI Library**: Ant Design 5.12 (enterprise-grade components)
|
||||
- **Routing**: React Router DOM 6.21
|
||||
- **HTTP Client**: Axios with interceptors
|
||||
- **Build Tool**: Vite 5.0 (lightning-fast HMR)
|
||||
- **Date Handling**: Day.js
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+ (or use Docker)
|
||||
- API server running (see `/api/README.md`)
|
||||
|
||||
### Option 1: Docker (Recommended)
|
||||
|
||||
**Development** (with hot-reload):
|
||||
```bash
|
||||
cd deploy
|
||||
docker compose -f docker-compose.dev.yml up frontend_dev --build
|
||||
```
|
||||
|
||||
**Production**:
|
||||
```bash
|
||||
cd deploy
|
||||
docker compose -f docker-compose.prod.yml up frontend_prod --build
|
||||
```
|
||||
|
||||
### Option 2: Local Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Configure API endpoint
|
||||
cp .env.dev .env.local
|
||||
# Edit .env.local if needed
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Access the Portal
|
||||
|
||||
| Environment | URL | Notes |
|
||||
|-------------|-----|-------|
|
||||
| Development | http://localhost:5173 | Vite dev server with HMR |
|
||||
| Local | http://localhost:80 | Docker nginx |
|
||||
| Production | https://portal.auburnoil.com | Production build |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── main.jsx # App entry point
|
||||
│ ├── App.jsx # Root component with routing
|
||||
│ ├── pages/
|
||||
│ │ ├── Index.jsx # Dashboard (logged in) / Welcome (logged out)
|
||||
│ │ ├── Login.jsx # Login form
|
||||
│ │ ├── Register.jsx # Existing customer registration
|
||||
│ │ ├── New.jsx # New customer wizard (3 steps)
|
||||
│ │ ├── Order.jsx # Place delivery order
|
||||
│ │ ├── Tank.jsx # Tank photo upload
|
||||
│ │ ├── Payments.jsx # Payment method management
|
||||
│ │ ├── EditCustomer.jsx # Edit profile
|
||||
│ │ ├── ChangePassword.jsx # Change password
|
||||
│ │ ├── ForgotPassword.jsx # Request reset
|
||||
│ │ └── ResetPassword.jsx # Complete reset
|
||||
│ ├── components/
|
||||
│ │ └── Navbar.jsx # Navigation with auth state
|
||||
│ └── utils/
|
||||
│ └── api.js # Axios instance with auth interceptor
|
||||
├── public/ # Static assets
|
||||
├── .env.dev # Development config
|
||||
├── .env.local # Local network config
|
||||
├── .env.prod # Production config
|
||||
├── Dockerfile.dev # Development container
|
||||
├── Dockerfile.local # Local network container
|
||||
├── Dockerfile.prod # Production container (nginx)
|
||||
├── vite.config.js # Vite configuration
|
||||
└── package.json # Dependencies
|
||||
```
|
||||
|
||||
## Pages & Features
|
||||
|
||||
### Dashboard (`/`)
|
||||
|
||||
**Logged Out:**
|
||||
- Welcome message
|
||||
- Links to login and registration
|
||||
|
||||
**Logged In:**
|
||||
- Customer information card
|
||||
- Current oil price display
|
||||
- Tank inspection photos (latest 3 images)
|
||||
- Delivery history table with:
|
||||
- Date, gallons, price, status
|
||||
- Visual status indicators (green = waiting, gold glow = out for delivery)
|
||||
- Emergency delivery contact information
|
||||
|
||||
### Login (`/login`)
|
||||
- Email/password authentication
|
||||
- "Forgot password" link
|
||||
- Registration link for new users
|
||||
|
||||
### Registration (`/register`)
|
||||
- For existing Auburn Oil customers
|
||||
- Requires: Account number + House number (verification)
|
||||
- Creates portal login credentials
|
||||
|
||||
### New Customer (`/new`)
|
||||
- **Step 1**: Customer information (name, address, contact)
|
||||
- **Step 2**: Create account (email, password)
|
||||
- **Step 3**: Upload 3 tank inspection photos
|
||||
- Auto-generates account number (AO-XXXXXX format)
|
||||
|
||||
### Place Order (`/order`)
|
||||
- Select delivery date
|
||||
- Enter gallons (minimum 100)
|
||||
- Real-time price calculation
|
||||
- Payment method selection
|
||||
- Order confirmation
|
||||
|
||||
### Tank Photos (`/tank`)
|
||||
- Upload new inspection photos (3 required)
|
||||
- View photo history by date
|
||||
- Image preview before upload
|
||||
|
||||
### Payments (`/payments`)
|
||||
- View saved cards (masked numbers)
|
||||
- Add new payment method
|
||||
- Edit card details
|
||||
- Remove cards
|
||||
- Set default payment method
|
||||
|
||||
### Profile Management
|
||||
- **Edit Customer** (`/edit-customer`): Update address, phone
|
||||
- **Change Password** (`/change-password`): Update password
|
||||
- **Forgot Password** (`/forgot-password`): Request reset email
|
||||
- **Reset Password** (`/reset-password`): Complete reset with token
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `VITE_BASE_URL` | API server URL | `http://localhost:8000` |
|
||||
|
||||
### Environment Files
|
||||
|
||||
```bash
|
||||
# .env.dev - Development
|
||||
VITE_BASE_URL=http://localhost:8000
|
||||
|
||||
# .env.local - Local network testing
|
||||
VITE_BASE_URL=http://192.168.1.204:8000
|
||||
|
||||
# .env.prod - Production
|
||||
VITE_BASE_URL=https://api.portal.auburnoil.com
|
||||
```
|
||||
|
||||
## Development Guide
|
||||
|
||||
### Available Scripts
|
||||
|
||||
```bash
|
||||
# Start development server (hot-reload)
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### API Integration
|
||||
|
||||
The app uses a centralized Axios instance (`/utils/api.js`) that:
|
||||
|
||||
1. Sets the base URL from environment
|
||||
2. Automatically attaches JWT token to requests
|
||||
3. Handles authentication headers
|
||||
|
||||
```javascript
|
||||
// Example usage in components
|
||||
import api from '../utils/api';
|
||||
|
||||
// GET request
|
||||
const response = await api.get('/info/deliveries');
|
||||
|
||||
// POST request
|
||||
const response = await api.post('/order/', { gallons: 150, date: '2024-01-15' });
|
||||
```
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. User logs in via `/auth/login`
|
||||
2. JWT token stored in `localStorage`
|
||||
3. Axios interceptor adds `Authorization: Bearer <token>` to all requests
|
||||
4. Protected routes check for token presence
|
||||
5. Logout clears token and redirects to login
|
||||
|
||||
### Adding New Pages
|
||||
|
||||
1. Create component in `/src/pages/`
|
||||
2. Add route in `App.jsx`
|
||||
3. Update navbar if needed
|
||||
|
||||
```jsx
|
||||
// App.jsx
|
||||
<Route path="/new-page" element={<NewPage />} />
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
### Ant Design Theme
|
||||
|
||||
The app uses Ant Design's default theme with custom overrides:
|
||||
|
||||
- Primary color: Auburn Oil brand colors
|
||||
- Responsive breakpoints for mobile/desktop
|
||||
- Card-based layout for information sections
|
||||
|
||||
### Responsive Design
|
||||
|
||||
- Mobile-first approach
|
||||
- Breakpoint-aware layouts using Ant Design Grid
|
||||
- Tables convert to cards on mobile
|
||||
- Touch-friendly form inputs
|
||||
|
||||
## Deployment
|
||||
|
||||
### Docker Production Build
|
||||
|
||||
The production Dockerfile:
|
||||
1. Builds React app with Vite
|
||||
2. Serves static files via nginx
|
||||
3. Configures routing for SPA
|
||||
|
||||
```bash
|
||||
# Build and run production container
|
||||
docker build -f Dockerfile.prod -t customer-portal .
|
||||
docker run -p 80:80 customer-portal
|
||||
```
|
||||
|
||||
### Manual Production Build
|
||||
|
||||
```bash
|
||||
# Build static files
|
||||
npm run build
|
||||
|
||||
# Output in /dist folder
|
||||
# Serve with any static file server (nginx, Apache, etc.)
|
||||
```
|
||||
|
||||
### nginx Configuration
|
||||
|
||||
For SPA routing, ensure nginx redirects all routes to `index.html`:
|
||||
|
||||
```nginx
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**API connection failed**
|
||||
```
|
||||
- Check VITE_BASE_URL in .env file
|
||||
- Ensure API server is running
|
||||
- Check for CORS errors in browser console
|
||||
- Verify network connectivity
|
||||
```
|
||||
|
||||
**Login not working**
|
||||
```
|
||||
- Clear localStorage and try again
|
||||
- Check browser console for errors
|
||||
- Verify API is returning valid JWT
|
||||
```
|
||||
|
||||
**Images not loading**
|
||||
```
|
||||
- Check API /images endpoint is accessible
|
||||
- Verify tank images exist in API volume
|
||||
- Check browser network tab for 404s
|
||||
```
|
||||
|
||||
**Build fails**
|
||||
```
|
||||
- Delete node_modules and reinstall: rm -rf node_modules && npm install
|
||||
- Clear Vite cache: rm -rf .vite
|
||||
- Check Node.js version (18+ required)
|
||||
```
|
||||
|
||||
### Browser Support
|
||||
|
||||
- Chrome 90+
|
||||
- Firefox 88+
|
||||
- Safari 14+
|
||||
- Edge 90+
|
||||
|
||||
## Security Notes
|
||||
|
||||
- JWT tokens stored in localStorage (ensure HTTPS in production)
|
||||
- All API calls go through authenticated endpoints
|
||||
- Credit card data never stored locally (handled by Authorize.net)
|
||||
- Image uploads validated on server side
|
||||
|
||||
---
|
||||
|
||||
**Auburn Oil Customer Gateway** - Empowering customers with self-service convenience.
|
||||
|
||||
For API documentation, see `/api/README.md`
|
||||
|
||||
Reference in New Issue
Block a user