# Overseas Appointment Backend API

Backend API for the overseas appointment mini program system.

## Tech Stack

- **Runtime**: Node.js 18+
- **Framework**: Express.js 4.x
- **Database**: MySQL 8.0
- **Cache**: Redis 7.0
- **ORM**: Sequelize 6.x
- **Authentication**: JWT
- **Testing**: Jest + Supertest + fast-check

## Project Structure

```
backend/
├── src/
│   ├── config/          # Configuration files
│   │   ├── database.js  # Sequelize database configuration
│   │   ├── env.js       # Environment variables
│   │   └── logger.js    # Winston logger configuration
│   ├── middleware/      # Express middleware
│   ├── models/          # Database models (Sequelize)
│   │   ├── index.js     # Model associations and exports
│   │   ├── User.js      # User model
│   │   ├── Category.js  # Service category model
│   │   ├── Service.js   # Service model
│   │   ├── Appointment.js # Appointment model
│   │   ├── Invitation.js  # Invitation model
│   │   ├── Withdrawal.js  # Withdrawal model
│   │   ├── Notification.js # Notification model
│   │   └── Admin.js     # Admin user model
│   ├── migrations/      # Database migrations
│   ├── seeders/         # Database seed files
│   ├── routes/          # API routes
│   ├── controllers/     # Route controllers
│   ├── services/        # Business logic
│   ├── utils/           # Utility functions
│   ├── tests/           # Test files
│   ├── app.js           # Express app setup
│   └── server.js        # Server entry point
├── logs/                # Application logs
├── uploads/             # Uploaded files
├── .env                 # Environment variables
├── .env.example         # Environment variables template
├── package.json         # Dependencies
└── README.md            # This file
```

## Getting Started

### Prerequisites

- Node.js 18 or higher
- MySQL 8.0
- Redis 7.0

### Installation

1. Install dependencies:
```bash
npm install
```

2. Copy environment variables:
```bash
cp .env.example .env
```

3. Configure your `.env` file with your database and Redis credentials

4. Create the database:
```bash
mysql -u root -p
CREATE DATABASE overseas_appointment;
```

5. Start the development server:
```bash
npm run dev
```

The server will start on `http://localhost:3000`

## Database Models

The system includes the following database models:

- **User**: User accounts with WeChat authentication, language preferences, and invitation codes
- **Category**: Service categories (airport, train, hotel, etc.) with multi-language support
- **Service**: Appointment services with multi-language titles and descriptions
- **Appointment**: User appointment bookings with status tracking
- **Invitation**: Invitation relationships and reward tracking
- **Withdrawal**: User withdrawal requests with admin review workflow
- **Notification**: System notifications with multi-language content
- **Admin**: Admin users for the management portal

All models support:
- UUID primary keys
- Automatic timestamps (created_at, updated_at)
- Multi-language fields (Chinese, English, Portuguese) where applicable
- Proper foreign key relationships and indexes

## Available Scripts

- `npm start` - Start production server
- `npm run dev` - Start development server with auto-reload
- `npm test` - Run tests
- `npm run test:watch` - Run tests in watch mode
- `npm run lint` - Check code style
- `npm run lint:fix` - Fix code style issues
- `npm run format` - Format code with Prettier

## API Endpoints

### Health Check
- `GET /health` - Check server health status

### API Documentation
API documentation will be available at `/api-docs` once implemented.

## Testing

Run the test suite:
```bash
npm test
```

Run tests with coverage:
```bash
npm test -- --coverage
```

## Security Features

- **Helmet**: Security headers
- **CORS**: Cross-origin resource sharing
- **Rate Limiting**: 100 requests per minute per IP
- **Input Validation**: Joi validation
- **JWT Authentication**: Secure token-based auth
- **Request Logging**: Winston logger

## Environment Variables

See `.env.example` for all available configuration options.

## License

ISC