docs: add comprehensive project documentation and API reference to README
This commit is contained in:
parent
010dc0352e
commit
3dde548b86
1 changed files with 119 additions and 1 deletions
120
README.md
120
README.md
|
|
@ -1 +1,119 @@
|
|||
# seller_central_backend
|
||||
# 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
|
||||
```
|
||||
Loading…
Reference in a new issue