Deployment and Operations Guide

You are assisting with deploying and operating the vehicle insurance data analysis platform. This project uses a simple deployment model suitable for internal teams and small-scale production.

When to Use This Skill

Activate this skill when the user needs help with:

• Setting up local development environment
• Running the application (start_server.sh)
• Building frontend for production
• Deploying to a server
• Managing services (starting/stopping)
• Troubleshooting deployment issues
• Viewing logs and monitoring

Project Deployment Model

Current Approach: Simple, single-server deployment

• NOT using: Docker, Kubernetes, complex CI/CD
• NOT using: Gunicorn/uWSGI in production yet
• Currently using: Direct Python execution via start_server.sh

This is appropriate for:

• Internal business tools
• Team size: < 50 users
• Data refreshed daily (not real-time)

Quick Start (Local Development)

Prerequisites Check

Guide the user to verify:

# Check Python (3.11+ required)
python3 --version

# Check Node.js (18+ recommended)
node -v

# Check if in correct directory
pwd  # Should show /path/to/签单日报dayreport

Option 1: One-Command Start (Recommended)

# Start backend with the provided script
./start_server.sh

# Output:
# ========================================
#    每日签单平台趋势分析系统
# ========================================
# [1/3] 检查Python环境...
# [2/3] 检查依赖包...
# [3/3] 启动API服务器...
# 服务器地址: http://localhost:5000

What this script does:

1. Checks Python environment (python3 or python)
2. Auto-installs dependencies if missing (Flask, Pandas, etc.)
3. Starts Flask backend on port 5000
4. Serves static HTML from /static/index.html

Option 2: Manual Start (for development)

# Terminal 1: Start backend
cd backend
python3 api_server.py

# Terminal 2: Start frontend dev server (if doing frontend dev)
cd frontend
npm install  # First time only
npm run dev  # Starts Vite on http://localhost:5173

Environment Setup Details

Python Environment

Install dependencies:

# From project root
pip3 install -r requirements.txt

# Requirements (from requirements.txt):
# - flask==3.0.0
# - flask-cors==4.0.0
# - numpy>=2.2,<3
# - pandas>=2.2.3,<3
# - openpyxl==3.1.2

Optional: Use virtual environment:

# Create venv (recommended for clean dependency management)
python3 -m venv .venv

# Activate
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install deps
pip install -r requirements.txt

Node.js Environment (Frontend Development Only)

Only needed if user wants to modify Vue components:

cd frontend

# Install dependencies
npm install

# Available commands
npm run dev      # Start dev server (http://localhost:5173)
npm run build    # Build for production (outputs to dist/)
npm run preview  # Preview production build
npm run lint     # Run ESLint

Production Build

Step 1: Build Frontend

cd frontend

# Production build
npm run build

# Output:
# vite v5.0.10 building for production...
# ✓ 104 modules transformed.
# dist/index.html                   0.48 kB
# dist/assets/index-xxx.js         80.68 kB │ gzip: 31.98 kB
# dist/assets/index-xxx.css        14.05 kB │ gzip:  2.86 kB

Build artifacts: frontend/dist/

• index.html - Entry point
• assets/ - Bundled JS/CSS with content hashes

Step 2: Deploy to Server

Simple deployment (current method):

# 1. Copy entire project to server
scp -r /path/to/签单日报dayreport user@server:/opt/dayreport/

# 2. SSH to server
ssh user@server

# 3. Install Python deps
cd /opt/dayreport
pip3 install -r requirements.txt

# 4. Start service
./start_server.sh

# Or run in background
nohup ./start_server.sh > app.log 2>&1 &

Step 3: Access Application

# If using start_server.sh (default):
http://server-ip:5000/static/index.html

# If using frontend dev server:
http://server-ip:5173

Service Management

Check if Services Running

# Check backend (port 5000)
lsof -i :5000
# Or
ps aux | grep api_server

# Check frontend dev server (port 5173)
lsof -i :5173

Start/Stop Services

# Stop backend
pkill -f api_server

# Stop frontend dev server
# (Ctrl+C in terminal, or)
pkill -f vite

# Restart backend
cd backend && python3 api_server.py &

# Restart frontend
cd frontend && npm run dev &

Background Execution

# Run backend in background
nohup python3 backend/api_server.py > backend.log 2>&1 &

# Get process ID
echo $!  # Save this PID

# Stop later
kill <PID>

Log Management

Backend Logs

Location: backend/backend.log

# View real-time logs
tail -f backend/backend.log

# View last 50 lines
tail -n 50 backend/backend.log

# Search for errors
grep -i "error" backend/backend.log

# View logs with timestamps
tail -f backend/backend.log | while read line; do echo "$(date): $line"; done

Frontend Logs

Browser console: Open DevTools (F12) → Console tab

Build logs: Terminal output during npm run build

Common Deployment Issues

Issue 1: Port Already in Use

Symptom:

OSError: [Errno 48] Address already in use

Solution:

# Find and kill process using port 5000
lsof -i :5000
kill -9 <PID>

# Or change port in api_server.py
# app.run(host='0.0.0.0', port=5001)  # Use different port

Issue 2: Dependencies Not Found

Symptom:

ModuleNotFoundError: No module named 'flask'

Solution:

# Verify Python environment
which python3
python3 -m pip list

# Reinstall dependencies
pip3 install -r requirements.txt

# If still failing, check if using correct Python
python3 -c "import flask; print(flask.__version__)"

Issue 3: Permission Denied on start_server.sh

Symptom:

-bash: ./start_server.sh: Permission denied

Solution:

# Add execute permission
chmod +x start_server.sh

# Then run
./start_server.sh

Issue 4: CSV Files Not Found

Symptom:

FileNotFoundError: 车险清单_2025年10-11月_合并.csv not found

Solution:

# Check if file exists
ls -la *.csv

# Check data directory
ls -la data/

# Verify file paths in data_processor.py match actual locations

Issue 5: Frontend Build Fails

Symptom:

npm ERR! code ENOENT

Solution:

# Clean install
rm -rf node_modules package-lock.json
npm install

# If disk space issue
df -h  # Check available space

# If memory issue
NODE_OPTIONS=--max-old-space-size=4096 npm run build

Performance Monitoring

Check Resource Usage

# CPU and memory (macOS)
top -o CPU

# Specific process
ps aux | grep python3 | grep api_server

# Disk usage
df -h
du -sh /path/to/签单日报dayreport/*

API Performance

# Test API response time
time curl http://localhost:5000/api/latest-date

# Multiple requests benchmark
for i in {1..10}; do
  time curl -s http://localhost:5000/api/kpi?period=day > /dev/null
done

Data Backup

Important files to backup:

# 1. Merged CSV data
车险清单_2025年10-11月_合并.csv

# 2. Staff mapping
业务员机构团队归属.json

# 3. Raw Excel files (optional)
data/*.xlsx

# Backup command
tar -czf backup-$(date +%Y%m%d).tar.gz \
  车险清单_2025年10-11月_合并.csv \
  业务员机构团队归属.json \
  data/

# Restore
tar -xzf backup-20250108.tar.gz

Advanced Deployment (Future)

Note: These are NOT currently implemented but can be added later:

Option A: Nginx Reverse Proxy

# /etc/nginx/sites-available/dayreport
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
    }
}

Option B: Systemd Service

# /etc/systemd/system/dayreport.service
[Unit]
Description=Dayreport API Service

[Service]
Type=simple
WorkingDirectory=/opt/dayreport
ExecStart=/usr/bin/python3 backend/api_server.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable dayreport
sudo systemctl start dayreport

For detailed advanced deployment, refer to ADVANCED_DEPLOYMENT.md.

Environment Variables (Optional)

Create .env file (if needed for configuration):

# .env
FLASK_ENV=production
FLASK_DEBUG=False
DATA_DIR=/opt/dayreport/data
PORT=5000

Load in Python:

# backend/api_server.py
import os
from dotenv import load_dotenv

load_dotenv()
PORT = int(os.getenv('PORT', 5000))

Deployment Checklist

Before deploying to production:

• Frontend built (npm run build)
• Dependencies installed (pip install -r requirements.txt)
• CSV data files copied to server
• Mapping JSON file present
• Port 5000 accessible
• Logs directory writable
• Tested API endpoints (curl localhost:5000/api/latest-date)
• Browser can access UI

Quick Reference

Essential Commands

# Start
./start_server.sh

# Stop
pkill -f api_server

# Logs
tail -f backend/backend.log

# Build frontend
cd frontend && npm run build

# Check status
lsof -i :5000
ps aux | grep api_server

File Locations

项目/
├── start_server.sh          # Main startup script
├── requirements.txt         # Python dependencies
├── backend/
│   ├── api_server.py       # Flask app (runs on :5000)
│   ├── data_processor.py   # Pandas logic
│   └── backend.log         # Runtime logs
├── frontend/
│   ├── package.json        # Node dependencies
│   └── dist/               # Built artifacts (after npm run build)
├── data/                   # Excel source files
└── *.csv                   # Processed CSV data

Summary

This skill covers the actual deployment model used by this project:

• Simple startup via start_server.sh
• Direct Python execution (no container orchestration)
• Suitable for internal tools and small teams

Key principle: Start simple, scale when needed. The current deployment is appropriate for the project's scope.

For enterprise-grade deployment patterns (Docker, K8s, load balancing), refer to advanced guides only if project requirements change.