`QUICKSTART.md`

234 lines
# Quick Start - Get Running in 5 Minutes

## Prerequisites
✅ Node.js installed
✅ npm installed
✅ Dependencies already installed
✅ Database already initialized

## 3 Steps to Start

### Step 1: Add Your OpenAI API Key (Required)
```bash
nano .env
```

Change this line:
```
OPENAI_API_KEY=your_openai_api_key_here
```

To your actual key:
```
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
```

Save and exit (CTRL+X, Y, Enter)

**Get an API key:** https://platform.openai.com/api-keys

---

### Step 2: Start the Server
```bash
npm start
```

You should see:
```
🚀 Japanese Handbag Arbitrage Platform
📍 Server running on http://0.0.0.0:7989
🔥 Monitoring deals >= 20% below market
```

**Open in browser:** http://localhost:7989

*(The site will be empty until you run a crawl)*

---

### Step 3: Run Your First Crawl (Optional - takes 10-15 min)

In a **new terminal window**:
```bash
cd /root/WebsitesMisc/handbags
npm run crawler
```

This will:
1. Scrape Komehyo, Yahoo Auctions JP, Mercari JP
2. Find 200-500 handbag listings
3. Save to database

Then run AI analysis:
```bash
node ai/analyzer.js
```

This will:
1. Analyze each listing with OpenAI
2. Compare prices with US markets
3. Calculate deal percentages
4. Flag the best deals

**Refresh your browser** to see results!

---

## That's It!

You now have:
- ✅ Web interface running on port 7989
- ✅ Live data from Japanese markets
- ✅ AI-powered deal detection
- ✅ Sortable/filterable listings
- ✅ CSV export capability

---

## Optional: Add Slack Notifications

1. Get a Slack webhook: https://api.slack.com/messaging/webhooks
2. Add to `.env`:
```
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
```
3. Check for deals:
```bash
node scripts/deal-notifier.js check
```

You'll get notifications for high-value deals!

---

## Optional: Enable Auto-Crawling (Every 6 Hours)

**Option A: Keep Terminal Open**
```bash
node scripts/setup-cron.js
# Leave this running
```

**Option B: Production (Recommended)**
```bash
# Install PM2
npm install -g pm2

# Start services
pm2 start server.js --name handbags-server
pm2 start scripts/setup-cron.js --name handbags-cron

# Save configuration
pm2 save

# Enable on boot
pm2 startup
# Follow the command it shows
```

Now crawls run automatically every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)

---

## Optional: Open Firewall (If Accessing Remotely)

```bash
sudo bash scripts/configure-firewall.sh
```

Then access from anywhere: http://YOUR_SERVER_IP:7989

---

## Quick Commands Reference

```bash
# Start server
npm start

# Manual crawl
npm run crawler

# AI analysis
node ai/analyzer.js

# Export deals to CSV
node scripts/export-spreadsheet.js deals 30

# Check for new deals (Slack)
node scripts/deal-notifier.js check

# View stats
curl http://localhost:7989/api/stats

# Production deployment
pm2 start server.js --name handbags-server
pm2 logs
```

---

## Troubleshooting

**"Error: OpenAI API key required"**
→ Add your API key to `.env` file

**"Port 7989 already in use"**
→ Kill existing process: `sudo lsof -i :7989` then `kill -9 <PID>`

**Crawl fails**
→ Install Chromium dependencies:
```bash
sudo apt-get update
sudo apt-get install -y chromium-browser
```

**No listings showing**
→ Run a crawl first: `npm run crawler`

---

## What You Get

**Web Interface Features:**
- Thumbnail grid of all listings
- Filter by brand, price, deal %, type
- Sort by deal, price, date
- Click to open original listing
- One-click CSV export

**Deal Detection:**
- 🔥 20-30% off (Good)
- 🔥🔥 30-50% off (Great)
- 🔥🔥🔥 50%+ off (Exceptional)

**Data Sources:**
- Komehyo (Japanese luxury reseller)
- Yahoo Auctions JP (Auctions)
- Mercari JP (C2C marketplace)

**Price Comparison:**
- eBay
- The RealReal
- Vestiaire Collective
- Fashionphile

---

## Next Steps

1. Browse deals at http://localhost:7989
2. Export good deals to CSV
3. Set up Slack notifications
4. Enable automatic crawling with PM2
5. Profit! 💰

For detailed docs, see:
- **SETUP.md** - Full setup guide
- **PROJECT_SUMMARY.md** - Complete feature list
- **DATA_STRUCTURE.md** - Data field reference
- **DEPLOYMENT_CHECKLIST.md** - Production deployment

Happy arbitraging! 🇯🇵💼