seller_central_backend/README.md

# Seller Central Backend

A robust Django-based backend REST API for **Seller Central**, a web platform designed to streamline and empower suppliers. This backend supports registration, mock OTP verification, profile completion, product catalog management, order fulfillment cycles, customer returns, and financial transactions.

---

## 🛠️ Architecture & Technology Stack
- **Framework**: Django & Django REST Framework (DRF)
- **Database**: SQLite (default, easily configured for PostgreSQL/MySQL)
- **Containerization**: Docker & Docker Compose
- **Testing Framework**: Pytest with `pytest-django`
- **CORS Support**: Configured for cross-origin frontend communication (`django-cors-headers`)

---

## 📦 Core E2E Modules & Business Logic

### 1. Onboarding & Authentication
- **Registration & Login**: Secure user registration and login endpoints utilizing Django's built-in authentication system.
- **OTP Verification**: A simulated 2FA verification system (mock code: `123456`) that verifies onboarding/logins.
- **Detailed Profiles**: Stores supplier coordinates (latitude/longitude), contact details, store branding details, and document references (Aadhar, PAN, and verified GSTIN).

### 2. Product Catalog
- **CRUD Operations**: Complete management of products, including title, category, price, stock, and SKU details.
- **Bulk Upload**: Batch create products using a structured JSON payload to efficiently scale inventory.

### 3. Order Management & Fulfillment
- **Fulfillment Pipeline**: Transition orders through realistic stages:
  `Pending Acceptance ➡️ Ready to Ship ➡️ Shipped ➡️ Delivered`
- **Actions**: Suppliers can accept or reject pending orders. Accepting automatically assigns tracking numbers, shipping carriers, and estimates transit times.

### 4. Returns & Customer Service
- **Return Processing**: Suppliers can inspect customer returns, view return reasons, and track return packages.
- **Resolution**: Actions to approve (marks status as `In Transit`) or reject returns.

### 5. Wallet & Payout System
- **Financial Ledger**: Tracks outstanding payouts and total withdrawn balances.
- **Payout Withdrawals**: Securely requests withdraws from outstanding balances, generating transaction receipts (`TX-XXXX`) for audit trails.

---

## 🗺️ API Reference

### Authentication & Profile
- **`POST /api/auth/register/`**: Register a new supplier.
- **`POST /api/auth/login/`**: Authenticate and initiate a session.
- **`POST /api/auth/verify-otp/`**: Validate verification codes (use code `123456` for successful verification).
- **`GET /api/profile/`**: Retrieve the authenticated profile.
- **`PUT /api/profile/`**: Update GSTIN, bank details, and business settings.

### Products Catalog
- **`GET /api/products/`**: List all products owned by the supplier.
- **`POST /api/products/`**: Create a new product.
- **`DELETE /api/products/<id>/`**: Delete a product.
- **`POST /api/products/bulk-upload/`**: Bulk create products in a single call.

### Order Processing
- **`GET /api/orders/`**: List all orders.
- **`POST /api/orders/<id>/accept/`**: Accept a pending order (updates carrier & tracking).
- **`POST /api/orders/<id>/reject/`**: Reject a pending order.

### Customer Returns
- **`GET /api/returns/`**: List return requests.
- **`POST /api/returns/<id>/action/`**: Approve or reject a return request.

### Wallet & Financials
- **`GET /api/wallet/`**: Retrieve wallet balance and transactions list.
- **`POST /api/wallet/withdraw/`**: Request payout/withdrawal.

---

## 🚀 Getting Started

### Prerequisites
- Python 3.12+
- Docker & Docker Compose (Optional)

### Local Setup
1. **Clone the Repository** and navigate to the project directory:
   ```bash
   git clone <repo_url>
   cd seller_central_backend
   ```
2. **Set up Virtual Environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```
3. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```
4. **Run Migrations**:
   ```bash
   python manage.py migrate
   ```
5. **Run the Development Server**:
   ```bash
   python manage.py runserver
   ```
   The backend will be running at `http://127.0.0.1:8000/`.

---

## 🐳 Docker Deployment
You can build and run the entire stack inside Docker containers:
```bash
docker-compose up --build
```
This serves the application on port `8000`.

---

## 🧪 Running Tests
We use `pytest` for automated test coverage of authentication, profile updates, products CRUD, bulk uploads, order state transitions, and payouts.
To execute tests, run:
```bash
pytest
```