Node.js backend structure

I'll provide you with a comprehensive updated step-by-step guide to test your complete shelf coordination backend API using Postman, including all the new additions.

Updated Setup & Prerequisites

1. Start Your Server

# Install dependencies
npm install

# Create uploads directory
mkdir uploads

# Start development server
npm run dev

2. Updated Postman Collection Setup

Open Postman
Create Collection: "Shelf Coordination API - Complete"
Set Environment Variables:
- baseUrl = http://localhost:8000
- authToken = (will be set after login)
- adminToken = (will be set after admin login)
- supervisorToken = (will be set after supervisor login)
- coordinatorToken = (will be set after coordinator login)

Complete Step-by-Step Testing Guide

PHASE 1: Authentication & User Setup

1.1 Admin Signup

POST {{baseUrl}}/api/auth/signup

Headers:

Content-Type: application/json

Body (JSON):

{
  "name": "System Admin",
  "email": "admin@shelfapp.com",
  "password": "123456",
  "passwordConfirm": "123456",
  "phone": "+201234567890",
  "role": "admin"
}

📝 Save the token as adminToken

1.2 Admin Login

POST {{baseUrl}}/api/auth/login

Body (JSON):

{
  "email": "admin@shelfapp.com",
  "password": "123456"
}

PHASE 2: Organizational Structure Setup

2.1 Create Market (Admin Only)

POST {{baseUrl}}/api/markets

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "name": "Cairo Central Market"
}

📝 Save the _id as marketId

2.2 Create Multiple Markets

{
  "name": "Alexandria Market"
}

{
  "name": "Giza Market"
}

2.3 Get All Markets

GET {{baseUrl}}/api/markets

Headers:

Authorization: Bearer {{adminToken}}

2.4 Create Branch

POST {{baseUrl}}/api/branches

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "name": "Nasr City Branch",
  "location": "Nasr City, Cairo, Egypt",
  "marketId": "{{marketId}}"
}

📝 Save the _id as branchId

2.5 Create More Branches

{
  "name": "Heliopolis Branch",
  "location": "Heliopolis, Cairo, Egypt",
  "marketId": "{{marketId}}"
}

2.6 Get All Branches

GET {{baseUrl}}/api/branches

Query Parameters:

marketId: {marketId}
page: 1
limit: 10

PHASE 3: User Management

3.1 Create Supervisor

POST {{baseUrl}}/api/users

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "name": "Sarah Supervisor",
  "email": "supervisor@shelfapp.com",
  "password": "123456",
  "phone": "+201234567891",
  "role": "supervisor"
}

📝 Save the _id as supervisorId

3.2 Create Coordinator

POST {{baseUrl}}/api/users

Body (JSON):

{
  "name": "Ahmed Coordinator",
  "email": "coordinator@shelfapp.com",
  "password": "123456",
  "phone": "+201234567892",
  "role": "coordinator",
  "branchId": "{{branchId}}"
}

📝 Save the _id as coordinatorId

3.3 Login as Supervisor

POST {{baseUrl}}/api/auth/login

Body (JSON):

{
  "email": "supervisor@shelfapp.com",
  "password": "123456"
}

📝 Save token as supervisorToken

3.4 Login as Coordinator

POST {{baseUrl}}/api/auth/login

Body (JSON):

{
  "email": "coordinator@shelfapp.com",
  "password": "123456"
}

📝 Save token as coordinatorToken

3.5 Get All Users (Admin View)

GET {{baseUrl}}/api/users

Headers:

Authorization: Bearer {{adminToken}}

Query Parameters:

role: coordinator
status: active
page: 1
limit: 10

3.6 Get My Profile (Any User)

GET {{baseUrl}}/api/users/getMe

Headers:

Authorization: Bearer {{coordinatorToken}}

3.7 Update My Profile

PUT {{baseUrl}}/api/users/updateMe

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: application/json

Body (JSON):

{
  "name": "Ahmed Updated Coordinator",
  "phone": "+201234567999"
}

3.8 Change User Status (Admin Only)

PUT {{baseUrl}}/api/users/{{coordinatorId}}/status

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "status": "suspended"
}

PHASE 4: Product Management

4.1 Create Products

POST {{baseUrl}}/api/products

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "name": "Coca Cola 330ml",
  "barcode": "1234567890123",
  "category": "Beverages",
  "shelf": "A1-B2",
  "stockQuantity": 50,
  "availabilityStatus": "high"
}

📝 Save the _id as productId1

4.2 Create More Products

{
  "name": "Pepsi 330ml",
  "barcode": "1234567890124",
  "category": "Beverages",
  "shelf": "A1-B3",
  "stockQuantity": 30,
  "availabilityStatus": "high"
}

{
  "name": "Lays Chips Original",
  "barcode": "1234567890125",
  "category": "Snacks",
  "shelf": "B2-C1",
  "stockQuantity": 5,
  "availabilityStatus": "low"
}

4.3 Get Products with Filters

GET {{baseUrl}}/api/products

Query Parameters:

category: Beverages
availabilityStatus: high
search: Coca
page: 1
limit: 10

4.4 Get Product by Barcode

GET {{baseUrl}}/api/products/barcode/1234567890123

Headers:

Authorization: Bearer {{coordinatorToken}}

PHASE 5: Task Management

5.1 Create Stock Check Task (Supervisor)

POST {{baseUrl}}/api/tasks

Headers:

Authorization: Bearer {{supervisorToken}}
Content-Type: application/json

Body (JSON):

{
  "title": "Weekly Stock Check - Beverages",
  "description": "Check stock levels for all beverage products in section A and update quantities",
  "type": "StockCheck",
  "branchId": "{{branchId}}",
  "marketId": "{{marketId}}",
  "assignedTo": "{{coordinatorId}}",
  "scheduledDate": "2024-01-20T09:00:00.000Z"
}

📝 Save the _id as taskId1

5.2 Create RTV Task

POST {{baseUrl}}/api/tasks

Body (JSON):

{
  "title": "Return Expired Products",
  "description": "Identify and return all expired products to vendor",
  "type": "RTV",
  "branchId": "{{branchId}}",
  "marketId": "{{marketId}}",
  "assignedTo": "{{coordinatorId}}",
  "scheduledDate": "2024-01-21T10:00:00.000Z"
}

📝 Save the _id as rtvTaskId

5.3 Create Planogram Task

POST {{baseUrl}}/api/tasks

Body (JSON):

{
  "title": "Planogram Compliance Check",
  "description": "Verify product placement according to planogram guidelines",
  "type": "Planogram",
  "branchId": "{{branchId}}",
  "marketId": "{{marketId}}",
  "assignedTo": "{{coordinatorId}}",
  "scheduledDate": "2024-01-22T11:00:00.000Z"
}

📝 Save the _id as planogramTaskId

5.4 Get Tasks (Coordinator View)

GET {{baseUrl}}/api/tasks

Headers:

Authorization: Bearer {{coordinatorToken}}

Query Parameters:

status: pending
type: StockCheck

5.5 Update Task Status (Coordinator)

PUT {{baseUrl}}/api/tasks/{{taskId1}}

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: application/json

Body (JSON):

{
  "status": "in-progress"
}

5.6 Complete Task

PUT {{baseUrl}}/api/tasks/{{taskId1}}

Body (JSON):

{
  "status": "done"
}

5.7 Get Task Analytics (Supervisor)

GET {{baseUrl}}/api/tasks/analytics

Headers:

Authorization: Bearer {{supervisorToken}}

PHASE 6: RTV (Return to Vendor) Management

6.1 Create RTV Product (Manual)

POST {{baseUrl}}/api/rtv

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: application/json

Body (JSON):

{
  "productId": "{{productId1}}",
  "taskId": "{{rtvTaskId}}",
  "addedMethod": "manual",
  "reason": "Product expired - expiry date 2024-01-15",
  "quantity": 10
}

6.2 Add RTV Product by Barcode

POST {{baseUrl}}/api/rtv/barcode

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: application/json

Body (JSON):

{
  "barcode": "1234567890124",
  "taskId": "{{rtvTaskId}}",
  "reason": "Damaged packaging during transport",
  "quantity": 5
}

6.3 Get All RTV Products

GET {{baseUrl}}/api/rtv

Headers:

Authorization: Bearer {{coordinatorToken}}

Query Parameters:

taskId: {rtvTaskId}
addedMethod: barcode

6.4 Get Specific RTV Product

GET {{baseUrl}}/api/rtv/{{rtvId}}

6.5 Update RTV Product

PUT {{baseUrl}}/api/rtv/{{rtvId}}

Body (JSON):

{
  "reason": "Updated: Product expired and damaged packaging",
  "quantity": 12
}

PHASE 7: Planogram Management

7.1 Create Planogram Submission with Images

POST {{baseUrl}}/api/planogram

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: multipart/form-data

Body (Form-data):

taskId: {planogramTaskId}
notes: Initial planogram setup for beverages section
imageBefore: [Upload image file - before.jpg]
imageAfter: [Upload image file - after.jpg]

7.2 Get All Planogram Submissions

GET {{baseUrl}}/api/planogram

Headers:

Authorization: Bearer {{supervisorToken}}

7.3 Get Specific Planogram Submission

GET {{baseUrl}}/api/planogram/{{planogramId}}

7.4 Update Planogram Submission

PUT {{baseUrl}}/api/planogram/{{planogramId}}

Body (JSON):

{
  "notes": "Updated notes: Compliance achieved after adjustments"
}

PHASE 8: Offers Management

8.1 Create Offer with Image (Coordinator)

POST {{baseUrl}}/api/offers

Headers:

Authorization: Bearer {{coordinatorToken}}
Content-Type: multipart/form-data

Body (Form-data):

productId: {productId1}
details: Special weekend discount - Buy 2 Get 1 Free
price: 25.99
image: [Upload image file - offer.jpg]

8.2 Get All Offers (Admin View)

GET {{baseUrl}}/api/offers

Headers:

Authorization: Bearer {{adminToken}}

Query Parameters:

status: pending

8.3 Approve Offer (Admin)

PUT {{baseUrl}}/api/offers/{{offerId}}/status

Headers:

Authorization: Bearer {{adminToken}}
Content-Type: application/json

Body (JSON):

{
  "status": "approved"
}

8.4 Reject Offer (Admin)

PUT {{baseUrl}}/api/offers/{{offerId}}/status

Body (JSON):

{
  "status": "rejected"
}

PHASE 9: Advanced Testing Scenarios

9.1 Complete Workflow Test

Step 1: Login as Supervisor

POST {{baseUrl}}/api/auth/login

Step 2: Create Task

POST {{baseUrl}}/api/tasks

Step 3: Login as Coordinator

POST {{baseUrl}}/api/auth/login

Step 4: View Assigned Tasks

GET {{baseUrl}}/api/tasks

Step 5: Start Task

PUT {{baseUrl}}/api/tasks/{{taskId}}

{
  "status": "in-progress"
}

Step 6: Complete Task with Attachments

PUT {{baseUrl}}/api/tasks/{{taskId}}

Form-data:

status: done
attachments: [Upload files]

9.2 Role-Based Access Testing

Test 1: Try accessing admin route with coordinator token (Should fail)

GET {{baseUrl}}/api/users
Authorization: Bearer {{coordinatorToken}}

Expected Response:

{
  "message": "You are not allowed to access this route"
}

Test 2: Try accessing other user's tasks (Should fail)

GET {{baseUrl}}/api/tasks/{{otherUserTaskId}}
Authorization: Bearer {{coordinatorToken}}

9.3 Password Reset Flow

Step 1: Forgot Password

POST {{baseUrl}}/api/auth/forgotPassword

{
  "email": "coordinator@shelfapp.com"
}

Step 2: Check email for reset code, then verify

POST {{baseUrl}}/api/auth/verifyResetCode

{
  "resetCode": "123456"
}

Step 3: Reset Password

PUT {{baseUrl}}/api/auth/resetPassword

{
  "email": "coordinator@shelfapp.com",
  "newPassword": "newpassword123"
}

Updated Environment Variables

Variable	Value	Description
baseUrl	http://localhost:8000	Base API URL
adminToken	Bearer TOKEN	Admin authentication token
supervisorToken	Bearer TOKEN	Supervisor authentication token
coordinatorToken	Bearer TOKEN	Coordinator authentication token
marketId	MARKET_ID	Created market ID
branchId	BRANCH_ID	Created branch ID
supervisorId	USER_ID	Supervisor user ID
coordinatorId	USER_ID	Coordinator user ID
productId1	PRODUCT_ID	First product ID
taskId1	TASK_ID	First task ID
rtvTaskId	TASK_ID	RTV task ID
planogramTaskId	TASK_ID	Planogram task ID

Testing Checklist

Authentication

Admin signup/login
Supervisor signup/login
Coordinator signup/login
Password reset flow
Token validation

User Management

Create users with different roles
Get user profile
Update profile
Change password
Update user status

Organizational Structure

Create markets
Create branches
Link branches to markets
Filter branches by market

Product Management

Create products
Search products
Get by barcode
Update stock levels
Filter by category/availability

Task Management

Create different task types
Assign tasks to coordinators
Update task status
Upload task attachments
View task analytics

RTV Management

Add RTV products manually
Add RTV by barcode
Link to RTV tasks
Update RTV details

Planogram Management

Submit planogram with images
AI processing simulation
View compliance results
Update submissions

Offers Management

Create offers with images
Admin approval workflow
Status updates
Filter by status

File Uploads

Task attachments
Planogram images
Offer images
File validation

Role-Based Access

Admin-only routes
Supervisor permissions
Coordinator restrictions
Cross-user access prevention

Common Issues & Solutions

Issue 1: File Upload Errors

{
  "message": "Only Images allowed"
}

Solution: Ensure you're uploading image files (jpg, png, gif)

Issue 2: Branch Creation Fails

{
  "errors": [
    {
      "msg": "Invalid market ID format"
    }
  ]
}

Solution: Use valid MongoDB ObjectId for marketId

Issue 3: Coordinator Creation Fails

{
  "errors": [
    {
      "msg": "Branch ID required for coordinator role"
    }
  ]
}

Solution: Always provide branchId when creating coordinators

Issue 4: Task Assignment Fails

{
  "message": "Task can only be assigned to coordinators"
}

Solution: Ensure assignedTo field contains a coordinator's user ID

This comprehensive testing guide covers all the new features and ensures your complete shelf coordination backend is working perfectly! Start with Phase 1 and work through each phase systematically.

Added Services:

Added Routes:

Added Validators:

Enhanced Features:

New API Endpoints:

Markets:

Branches:

Users:

RTV:

Planogram:

Updated Setup & Prerequisites

1. Start Your Server

2. Updated Postman Collection Setup

Complete Step-by-Step Testing Guide

PHASE 1: Authentication & User Setup

1.1 Admin Signup

1.2 Admin Login

PHASE 2: Organizational Structure Setup

2.1 Create Market (Admin Only)

2.2 Create Multiple Markets

2.3 Get All Markets

2.4 Create Branch

2.5 Create More Branches

2.6 Get All Branches

PHASE 3: User Management

3.1 Create Supervisor

3.2 Create Coordinator

3.3 Login as Supervisor

3.4 Login as Coordinator

3.5 Get All Users (Admin View)

3.6 Get My Profile (Any User)

3.7 Update My Profile

3.8 Change User Status (Admin Only)

PHASE 4: Product Management

4.1 Create Products

4.2 Create More Products

4.3 Get Products with Filters

4.4 Get Product by Barcode

PHASE 5: Task Management

5.1 Create Stock Check Task (Supervisor)

5.2 Create RTV Task

5.3 Create Planogram Task

5.4 Get Tasks (Coordinator View)

5.5 Update Task Status (Coordinator)

5.6 Complete Task

5.7 Get Task Analytics (Supervisor)

PHASE 6: RTV (Return to Vendor) Management

6.1 Create RTV Product (Manual)

6.2 Add RTV Product by Barcode

6.3 Get All RTV Products

6.4 Get Specific RTV Product

6.5 Update RTV Product

PHASE 7: Planogram Management

7.1 Create Planogram Submission with Images

7.2 Get All Planogram Submissions

7.3 Get Specific Planogram Submission

7.4 Update Planogram Submission

PHASE 8: Offers Management

8.1 Create Offer with Image (Coordinator)

8.2 Get All Offers (Admin View)

8.3 Approve Offer (Admin)

8.4 Reject Offer (Admin)

PHASE 9: Advanced Testing Scenarios

9.1 Complete Workflow Test

9.2 Role-Based Access Testing

9.3 Password Reset Flow

Updated Environment Variables

Testing Checklist

Authentication

User Management

Organizational Structure

Product Management

Task Management

RTV Management

Planogram Management

Offers Management

File Uploads

Role-Based Access

Common Issues & Solutions

Issue 1: File Upload Errors