Skip to content

BIDDING_SYSTEM_COMPLETE_FEATURES.md

Latest commit

 

History

History
336 lines (267 loc) · 9.12 KB

BIDDING_SYSTEM_COMPLETE_FEATURES.md

File metadata and controls

336 lines (267 loc) · 9.12 KB
Raw

Bidding System - Complete Features Implementation

Summary

All backend and frontend functionalities for the bidding system have been implemented and integrated.

System Changes

1. Monthly Bidding Cycle (Changed from Quarterly)

Backend Changes:

  • Period: Changed from quarterly (3 months) to monthly (1 month)
  • Price Increase: Now runs on 1st of every month (2% increase)
  • Bidding Window: Entire month (1st to last day)
  • Cron Schedule: @Scheduled(cron = "0 0 0 1 * *") - runs monthly instead of bi-monthly

Files Modified:

  • BiddingService.java - Updated increasePricesForNewMonth() method
  • BiddingService.java - Updated getCurrentSeasonInfo() to return monthly period info
  • SeasonConfigDTO.java - Changed currentSeason to currentPeriod (1-12 instead of 1-4)

Backend API Endpoints

Navigation Hierarchy

GET /api/bidding/categories              - Get all categories
GET /api/bidding/categories/{id}         - Get specific category
GET /api/bidding/categories/{id}/rangs   - Get rangs by category
GET /api/bidding/rangs/{id}/faces        - Get faces by rang
GET /api/bidding/faces/{id}/sections     - Get sections by face
GET /api/bidding/sections/{id}           - Get section details

Bidding Operations

POST   /api/bidding/bids                 - Place a new bid
DELETE /api/bidding/bids/{id}            - Cancel a bid

My Bids (Investor)

GET /api/bidding/my-bids                      - All my bids
GET /api/bidding/my-current-winning-bids      - Bids I'm currently winning (PENDING)
GET /api/bidding/my-winning-bids              - Bids I won (WINNER - closed sections)

Investor Bids by ID (Admin/Self)

GET /api/bidding/investors/{id}/bids                    - All bids by investor
GET /api/bidding/investors/{id}/current-winning-bids    - Currently winning bids
GET /api/bidding/investors/{id}/winning-bids            - Final winning bids

Section Information

GET /api/bidding/sections/{id}/bids      - Bid history for section
GET /api/bidding/sections/{id}/winner    - Current winning bid for section

Admin Operations

GET  /api/bidding/bids                   - All bids (Admin only)
GET  /api/bidding/bids/between           - Bids between dates
POST /api/bidding/sections/{id}/close    - Manually close section

Period/Season Info

GET /api/bidding/season/current          - Current monthly period information

Frontend Implementation

Pages Created/Updated

1. BiddingDashboard.tsx (NEW)

  • Route: /dashboard/bidding-overview
  • Features:
    • Monthly period information display
    • Quick stats (Total Bids, Currently Winning, Total Investment, Days Remaining)
    • Current winning bids preview
    • Period details (start/end dates, bidding window)
    • Quick action buttons
  • API Calls:
    • biddingApi.getSeasonInfo()
    • biddingApi.getMyBids()
    • biddingApi.getMyCurrentWinningBids()

2. MyBids.tsx (UPDATED)

  • Route: /dashboard/my-bids
  • Features:
    • Three tabs:
      1. All Bids - Every bid you placed
      2. Currently Winning - Bids with PENDING status (you're in the lead)
      3. Final Wins - Bids with WINNER status (closed sections you won)
    • Cancel bid functionality for OUTBID bids
    • View section details from bid card
  • API Calls:
    • biddingApi.getMyBids()
    • biddingApi.getMyCurrentWinningBids()
    • biddingApi.getMyWinningBids()
    • biddingApi.cancelBid(bidId)

3. BiddingBrowse.tsx (EXISTING)

  • Route: /dashboard/bidding
  • Features:
    • Browse all categories
    • Navigate to category details

4. BiddingCategory.tsx (EXISTING)

  • Browse rangs, faces, and sections

5. BiddingSection.tsx (UPDATED)

  • Route: /dashboard/bidding/section/:sectionId
  • Features:
    • View section details
    • Place bid
    • View bid history
    • Updated contract description (3-month → monthly)

API Service (api.ts)

All Endpoints Added:

// Navigation
getCategories()
getCategory(id)
getRangsByCategory(categoryId)
getFacesByRang(rangId)
getSectionsByFace(faceId)
getSection(sectionId)

// Bidding Operations
placeBid(data)
cancelBid(bidId)

// My Bids
getMyBids()
getMyCurrentWinningBids()        // NEW
getMyWinningBids()

// Other Investors (Admin)
getInvestorBids(investorId)
getInvestorCurrentWinningBids(investorId)    // NEW
getInvestorWinningBids(investorId)

// Section Info
getBidHistory(sectionId)
getCurrentWinner(sectionId)

// Admin
getAllBids()
getBidsBetweenDates(startDate, endDate)
closeSection(sectionId)

// Season/Period
getSeasonInfo()

Navigation Menu (Sidebar)

Investor Menu (Updated):

1. Bidding Overview     → /dashboard/bidding-overview (NEW)
2. Browse Sections      → /dashboard/bidding
3. My Bids             → /dashboard/my-bids
4. My Products         → /dashboard/products
5. Low Stock           → /dashboard/low-stock
6. Statistics          → /dashboard/statistics
7. Personal Data       → /dashboard/profile

Bid Status Flow

Status Definitions:

  • PENDING - Currently the highest bid (winning for now)
  • OUTBID - Someone else bid higher
  • WINNER - Won the bid after section closed

Status Transitions:

1. User places bid → Status: PENDING
2. Another user bids higher → Previous bid: OUTBID, New bid: PENDING
3. Section closes → Highest bid: WINNER, Others remain: OUTBID

Monthly Cycle Logic

How It Works:

Day 1 of Each Month (Midnight):

  1. All section prices increase by 2%
  2. basePrice and currentPrice updated
  3. Section status reset to "OPEN"
  4. Previous winner cleared
  5. Deadline set to last day of current month

During the Month:

  • Investors can place bids anytime
  • Bids must be higher than current price
  • Each new bid updates section's currentPrice
  • Previous PENDING bids become OUTBID

Last Day of Month (Midnight):

  • Auto-close sections with passed deadlines
  • Highest bid (PENDING) becomes WINNER
  • Section status changes to "CLOSED"
  • Winner assigned to section

Data Flow Example

Scenario: January 2026 Bidding

Jan 1, 00:00 → Price increase (2%), sections reset, deadline = Jan 31
Jan 5       → Investor A bids 1000 DH (Status: PENDING)
Jan 10      → Investor B bids 1100 DH (A becomes OUTBID, B is PENDING)
Jan 15      → Investor A bids 1200 DH (B becomes OUTBID, A is PENDING)
Jan 31      → Section auto-closes, A's bid becomes WINNER
Feb 1, 00:00 → New cycle begins, prices increase 2% again

Testing Checklist

Backend Tests:

  • ✅ Monthly price increase (1st of month)
  • ✅ Auto-close sections (last day of month)
  • ✅ Bid placement and validation
  • ✅ Bid cancellation logic
  • ✅ Current winning bid retrieval
  • ✅ Historical bid queries

Frontend Tests:

  • ✅ View bidding overview with period info
  • ✅ Browse categories → rangs → faces → sections
  • ✅ Place a bid on a section
  • ✅ View all my bids (All/Currently Winning/Final Wins)
  • ✅ Cancel an OUTBID bid
  • ✅ View bid history on section page
  • ✅ Period countdown and status display

Key Features Implemented

Backend:

  1. ✅ Monthly bidding cycle (not quarterly)
  2. ✅ Automatic price increase (1st of month)
  3. ✅ Automatic section closure (last day of month)
  4. ✅ Current winning bids endpoint
  5. ✅ Final winning bids endpoint
  6. ✅ Bid history tracking
  7. ✅ Section management
  8. ✅ Period information API

Frontend:

  1. ✅ Bidding overview dashboard
  2. ✅ Current vs Final winning bids separation
  3. ✅ Period information display
  4. ✅ Quick stats and metrics
  5. ✅ Bid management (place, cancel, view)
  6. ✅ Navigation hierarchy
  7. ✅ Real-time bid status updates
  8. ✅ Responsive UI with proper loading states

Environment Setup

Required Settings:

  • Spring Boot: 2.7+ or 3.x
  • Java: 17+
  • Database: MySQL/PostgreSQL with proper schema
  • Frontend: React 18+, TypeScript, Vite

Important Configuration:

// Enable scheduling in main application class
@EnableScheduling
@SpringBootApplication
public class AnalifyApplication {
    public static void main(String[] args) {
        SpringApplication.run(AnalifyApplication.class, args);
    }
}

Future Enhancements (Optional)

Potential Additions:

  1. Real-time bid notifications (WebSocket)
  2. Email alerts for outbid/won sections
  3. Bid analytics and trends
  4. Admin dashboard for monitoring all bids
  5. Export bid history to CSV/PDF
  6. Mobile app integration
  7. Automated bid strategies (max bid)

Documentation Files

  • BIDDING_SYSTEM_COMPLETE.md - Original implementation guide
  • BIDDING_SYSTEM_IMPLEMENTATION.md - Technical details
  • INVESTOR_BIDDING_GUIDE.md - User guide for investors
  • FRONTEND_BIDDING_IMPLEMENTATION.md - Frontend setup guide
  • BIDDING_SYSTEM_COMPLETE_FEATURES.md - This file (complete feature list)

Support

For issues or questions:

  1. Check endpoint responses in browser DevTools
  2. Verify JWT token is being sent
  3. Check server logs for errors
  4. Ensure database schema is up to date
  5. Verify cron jobs are running (check logs at midnight)

System Status: ✅ All Features Implemented and Integrated Last Updated: January 2, 2026