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