238 lines
6.0 KiB
Markdown
238 lines
6.0 KiB
Markdown
# Quote & Invoice Management System
|
||
|
||
Professional quote and invoice management system for Bay Area Affiliates, Inc.
|
||
|
||
## Features
|
||
|
||
### Quotes
|
||
- Create and manage professional quotes
|
||
- Support for TBD (To Be Determined) items
|
||
- Rich text descriptions with Quill editor
|
||
- Automatic tax calculations (8.25% Texas sales tax)
|
||
- Tax-exempt option
|
||
- PDF generation
|
||
- **Convert quotes to invoices** with one click
|
||
|
||
### Invoices
|
||
- Create and manage invoices
|
||
- Terms field (default: Net 30)
|
||
- Authorization/P.O. field
|
||
- Rich text descriptions
|
||
- Automatic tax calculations
|
||
- Tax-exempt option
|
||
- PDF generation with accounting@bayarea-cc.com email
|
||
- "Bill To:" instead of "Quote For:"
|
||
- **No TBD items allowed** - quotes with TBD items cannot be converted until updated
|
||
|
||
### Customers
|
||
- Full customer management
|
||
- Address and account number tracking
|
||
- Customer selection in quotes/invoices
|
||
|
||
### Settings
|
||
- Company logo upload for PDFs
|
||
- Logo appears on both quotes and invoices
|
||
|
||
## Installation
|
||
|
||
### Prerequisites
|
||
- Node.js 18+
|
||
- PostgreSQL 12+
|
||
- npm or yarn
|
||
|
||
### Setup
|
||
|
||
1. **Clone or copy the files to your server**
|
||
|
||
2. **Install dependencies:**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. **Set up PostgreSQL database:**
|
||
```bash
|
||
# Create database and user
|
||
createdb quotes_db
|
||
createuser -P quoteuser # Enter password when prompted
|
||
```
|
||
|
||
4. **Run database migrations:**
|
||
|
||
First, run the initial setup:
|
||
```sql
|
||
-- In psql or your PostgreSQL client, run init.sql
|
||
psql -U quoteuser -d quotes_db -f init.sql
|
||
```
|
||
|
||
Then add invoice tables:
|
||
```sql
|
||
-- Run add_invoices.sql
|
||
psql -U quoteuser -d quotes_db -f add_invoices.sql
|
||
```
|
||
|
||
5. **Configure environment (optional):**
|
||
|
||
Create a `.env` file or set environment variables:
|
||
```bash
|
||
DB_USER=quoteuser
|
||
DB_PASSWORD=your_password
|
||
DB_HOST=localhost
|
||
DB_PORT=5432
|
||
DB_NAME=quotes_db
|
||
PORT=3000
|
||
```
|
||
|
||
6. **Start the server:**
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
For development with auto-reload:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
7. **Access the application:**
|
||
Open your browser to: `http://localhost:3000`
|
||
|
||
## Database Schema
|
||
|
||
### Customers Table
|
||
- id, name, street, city, state, zip_code, account_number
|
||
|
||
### Quotes Table
|
||
- id, quote_number, customer_id, quote_date, tax_exempt, tax_rate
|
||
- subtotal, tax_amount, total, has_tbd, created_at, updated_at
|
||
|
||
### Quote Items Table
|
||
- id, quote_id, quantity, description, rate, amount, item_order
|
||
|
||
### Invoices Table
|
||
- id, invoice_number, customer_id, invoice_date, terms, authorization
|
||
- tax_exempt, tax_rate, subtotal, tax_amount, total
|
||
- created_from_quote_id, created_at, updated_at
|
||
|
||
### Invoice Items Table
|
||
- id, invoice_id, quantity, description, rate, amount, item_order
|
||
|
||
## Usage
|
||
|
||
### Creating a Quote
|
||
1. Click "Quotes" tab
|
||
2. Click "+ New Quote"
|
||
3. Select customer
|
||
4. Add items (can use TBD for rates/amounts)
|
||
5. Items support rich text formatting
|
||
6. Check "Tax Exempt" if applicable
|
||
7. Save
|
||
|
||
### Converting Quote to Invoice
|
||
1. Find quote in list
|
||
2. Click "→ Invoice" button
|
||
3. **Note:** Quotes with TBD items cannot be converted
|
||
4. Invoice is automatically created with:
|
||
- Same customer and items
|
||
- Current date
|
||
- Default terms: "Net 30"
|
||
- Empty authorization field
|
||
|
||
### Creating an Invoice
|
||
1. Click "Invoices" tab
|
||
2. Click "+ New Invoice"
|
||
3. Select customer
|
||
4. Enter terms (e.g., "Net 30", "Due on Receipt")
|
||
5. Add authorization if needed (P.O. number, etc.)
|
||
6. Add items (TBD not allowed in invoices)
|
||
7. Check "Tax Exempt" if applicable
|
||
8. Save
|
||
|
||
### PDF Generation
|
||
- **Quotes:** Display "Quote For:" and support@bayarea-cc.com
|
||
- **Invoices:** Display "Bill To:" and accounting@bayarea-cc.com
|
||
- Both include company logo if uploaded
|
||
- Professional formatting with Bay Area Affiliates branding
|
||
|
||
### Managing Customers
|
||
1. Click "Customers" tab
|
||
2. Add/Edit/Delete customers
|
||
3. Customers appear in dropdown for quotes/invoices
|
||
|
||
### Settings
|
||
1. Click "Settings" tab
|
||
2. Upload company logo (PNG/JPG recommended)
|
||
3. Logo appears on all PDFs
|
||
|
||
## File Structure
|
||
|
||
```
|
||
quote-invoice-system/
|
||
├── server.js # Express server with all routes
|
||
├── public/
|
||
│ ├── index.html # Main UI with tabs for quotes/invoices
|
||
│ ├── app.js # Frontend JavaScript
|
||
│ └── uploads/ # Logo storage
|
||
├── package.json # Dependencies
|
||
├── init.sql # Initial database schema
|
||
└── add_invoices.sql # Invoice tables migration
|
||
```
|
||
|
||
## Key Differences: Quotes vs Invoices
|
||
|
||
| Feature | Quotes | Invoices |
|
||
|---------|--------|----------|
|
||
| TBD Items | ✅ Allowed | ❌ Not allowed |
|
||
| Email | support@bayarea-cc.com | accounting@bayarea-cc.com |
|
||
| Label | "Quote For:" | "Bill To:" |
|
||
| Terms Field | No | Yes (e.g., Net 30) |
|
||
| Authorization | No | Yes (optional) |
|
||
| Info Header | Quote #, Account #, Date | Invoice #, Account #, Date, Terms |
|
||
|
||
## API Endpoints
|
||
|
||
### Quotes
|
||
- `GET /api/quotes` - List all quotes
|
||
- `GET /api/quotes/:id` - Get quote details
|
||
- `POST /api/quotes` - Create new quote
|
||
- `PUT /api/quotes/:id` - Update quote
|
||
- `DELETE /api/quotes/:id` - Delete quote
|
||
- `GET /api/quotes/:id/pdf` - Generate quote PDF
|
||
- `POST /api/quotes/:id/convert-to-invoice` - Convert to invoice
|
||
|
||
### Invoices
|
||
- `GET /api/invoices` - List all invoices
|
||
- `GET /api/invoices/:id` - Get invoice details
|
||
- `POST /api/invoices` - Create new invoice
|
||
- `PUT /api/invoices/:id` - Update invoice
|
||
- `DELETE /api/invoices/:id` - Delete invoice
|
||
- `GET /api/invoices/:id/pdf` - Generate invoice PDF
|
||
|
||
### Customers
|
||
- `GET /api/customers` - List all customers
|
||
- `POST /api/customers` - Create customer
|
||
- `PUT /api/customers/:id` - Update customer
|
||
- `DELETE /api/customers/:id` - Delete customer
|
||
|
||
### Settings
|
||
- `GET /api/logo-info` - Check if logo exists
|
||
- `POST /api/upload-logo` - Upload company logo
|
||
|
||
## Technical Details
|
||
|
||
- **Frontend:** Vanilla JavaScript, Tailwind CSS
|
||
- **Backend:** Node.js, Express
|
||
- **Database:** PostgreSQL
|
||
- **PDF Generation:** Puppeteer
|
||
- **Rich Text:** Quill.js editor
|
||
|
||
## Automatic Features
|
||
|
||
- Quote numbers: Format YYYY-NNN (e.g., 2026-001)
|
||
- Invoice numbers: Format YYYY-NNN (e.g., 2026-001)
|
||
- Auto-increment within year
|
||
- Automatic tax calculation (8.25%)
|
||
- Item quantity × rate = amount calculation
|
||
|
||
## Support
|
||
|
||
For issues or questions, contact Bay Area Affiliates, Inc.
|