# Model Train Webshop Requirements Document (Version 1.0)

## EXECUTIVE SUMMARY
- Platform: WordPress + WooCommerce with customizable interface
- Cookie-based customer preferences storage
- Benelux primary market, Eurozone expansion
- Dropshipping from vendors with bulk wholesale model
- Quality control: Inspect all shipments before customer delivery
- Payment: WERO gateway (iDEAL, Bancontact, Giropay)
- Shipping: Economic/Standard/Express options based on customer preference

---

# SECTION 1 - REQUIREMENT CATEGORIES INDEX

## Module Code | Description
| Req-VENDOR-INTEGRATION | Vendor Direct Integration & API Requirements |
| Req-CUSTOMER-ACCOUNTS | Customer Accounts & Guest Checkout Requirements |
| Req-Loyalty-PROGRAM | Loyalty Points & Tiered Discount System |
| Req-Payment-PROCESSING | Payment Gateway & Transaction Handling |
|Req-COOKIE-PREFERENCES| Cookie-Based User Preferences Storage |
Req-VENDOR-INTEGRATION| Vendor Product Sync Order Management |
Req-CATALOG-MANAGEMENT| Product Catalog Structure & Filtering |
Req-SHIPPING-FULFILLMENT| Shipping Options Routing & Logistics |
Req-QUALITY-CONTROL| Quality Inspection & Warehouse Processes |
Req-NOTIFICATIONS| Price Alerts & Email Communications |
Req-TECHNICAL-NONFUNC | Technical Performance & Security Specs |

---

# REQ-V-ENDOR-INTEGRATION-01 - Vendor Connection Architecture

## 1.1 Vendor Integration Type Classification

### V-1 Direct Link (Current Implementation)
```
Each vendor provides:
• Individual store/product URLs
• Manual product listing upload capability
• Separate stock status pages for monitoring
```

### V-2 CSV/XLS Export (Sync Method)
```
Each vendor must provide:
• Weekly product feed export
• Stock levels and pricing data
• Product images & descriptions
• Format requirements per vendor specification
```

### V-3 API Integration (Future Extension)
```
When available, vendors should support:
• Real-time stock checking via API calls  
• Automatic order forwarding to vendor systems
• Webhook notifications for new product arrivals
```

## 1.2 Product Import Requirements per Vendor
| Field | Required | Format | Notes |
|-------|----------|--------|-------|
| Product Name | Yes | Text | Max 200 chars |
| SKU/Item Code | Yes | String | Unique internal ID |
| Price (EUR) | Yes | Decimal | 2 decimals, min price floor |
| Stock Level | Optional | Integer | -1 if unknown/unavailable |
| Vendor Product URL | Yes | Link | Direct vendor store link |
| Images | Optional | URLs | Max 5 images per product |
| Description | Yes | Text | Rich text, 5k max chars |
| Category Mapping | Yes | Enum | Map to catalog categories |

## 1.3 Stock Synchronization Schedule
- Minimum sync frequency: Weekly (aligns with vendor shipments)
- Recommended: Biweekly for critical categories  
- Emergency manual updates via admin dashboard permitted
- Stock status flags: In stock, Low (<10 units), Out of stock

---

# REQ-CUSTOMER-ACCOUNTS-01 - User Account System

## 2.1 Guest Checkout (Mandatory)
```
Guest user features:
• Browse full catalogue without login required  
• Complete purchase via email address only  
• Receive digital invoice + order confirmation  
• Track orders via email link (no account needed)  
• Abandon cart recovery emails
```

## 2.2 Account Creation Flow
```
Registration triggers:
• First purchase (optional auto-enrollment)
• Direct signup form on site  
• Login + password reset functionality  
• Two-factor authentication option for admin only
```

## 2.3 Account Features per User Tier
| Feature | New Customer | Active Customer | Loyalty Member |
|---------|-------------|----------------|---------------|
| Order History | Read-only | Edit requests | Full management |
| Wishlist | Session-only | Persistent storage | Price alerts |
| Points Balance | Not shown | Viewable if tier 2+ | Transaction details |
| Discount Access | Base rate | Tier-based | Maximum available |

---

# REQ-REWARD-PROGRAM-01 - Loyalty Rewards Structure

## 3.1 Point Accumulation Formula

### Points Earning Rules:
```
Points = Spent (EUR) × Multiplier Factor by tier

Tier 1 (New customer): 1 EUR → 5 points  
Tier 2 (Returning customers): 1 EUR → 7 points  
Tier 3 (VIP loyalty members): 1 EUR → 10 points

Point values:
• 1 point = €0.01 in account value
• Minimum withdrawal threshold: 500 points per discount use
```

## 3.2 Tier Advancement Criteria
| Tier | Discount on Special Offers | Progression Requirement |
|------|---------------------------|-------------------------|
| Standard | 5% off special deals | First purchase completed |
| Active Member | 15-25% off regular + specials | 3+ purchases OR €50 spent |
| VIP | 40% on special offers only | €200 lifetime spend OR 5+ referrals |

## 3.3 Bonus Programs
```
• Welcome bonus: 100 points for first order  
• Birthday week: Double points multiplier  
• Referral bonus: 500 points per friend joined via link  
• Anniversary reward: Points reset for inactive accounts (prevent churn)
```

---

# REQ-REQ-MENT-PROCESSING-02 - WERO Payment Gateway

## 4.1 Payment Methods Supported
| Method | Target Market | Transaction Fee | Notes |
|--------|--------------|----------------|-------|
| iDEAL | Netherlands | 0.10 EUR + 0% | Mandatory for NL orders |
| Bancontact | Belgium, Netherlands | 0.25 EUR | BCA standard |
| Giropay | Germany | 0.20 EUR + 0% | German online standard |
| Credit Card | All markets | 2.9% + €0.30 | VISA/Mastercard via WERO |
| PayPal | All markets | % based | Optional checkout alternative |

## 4.2 Checkout Flow Requirements
Step 1: Cart contents reviewed  
Step 2: Shipping address entered  
Step 3: Payment method selected (WERO or PayPal)  
Step 4: Customer preferences displayed (cookies applied)  
Step 5: Order confirmation + invoice generated  
Step 6: Email notifications sent

## 4.3 Transaction Security
- SSL/TLS 1.2+ encryption throughout checkout  
- PCI-DSS compliance maintained via WERO hosted pages  
- Fraud detection: Address verification, unusual order patterns flagged  
- 3D Secure authentication for cards over €50 value

---

# REQ-COOKIE-PREF-STORAGE-03 - Cookie Storage Specifications

## 5.1 Required Preference Categories
### Category A - Language Settings (Persistent)
```
Options: English (en), Dutch (nl), German (de), French (fr)  
Storage lifetime: Indefinite until browser cleared  
Opt-out capability required: Yes
```

### Category B - Navigation & Accessibility (Session + Persistent)
```
Menu placement: Top bar / Sidebar / Bottom nav  
Category display order: Alphabetical vs. Favorites-first  
Image density: Compact / Standard / Expanded  
Contrast modes: Standard / High contrast  
Text size toggle (for accessibility compliance)
```

### Category C - Order Display Preferences (Persistent)
```
Sort by options: Price (low-high) / Rating / New products  
Filtering preferences: Hide sold items, show only my gauge type  
Category exclusion list (what NOT to see)  
Search term history (3 last searches retained)
```

## 5.2 Secure Preference Storage
```
Implementation notes:
• Store cookie in browser's secure storage  
• SameSite=Lax policy for cross-site cookies  
• Encrypted preference data for logged-in users  
• GDPR-compliant consent banner for marketing preferences only  
• Allow all EU cookie management compliance features
```

## 5.3 Preference Synchronization Logic
```
Priority flow: Account settings override cookies when account exists  
Account creation: Merges existing cookie prefs into account profile  
Cookie storage: Fallback when account not created / session mode  
Admin can override preferences for testing but audit required
```

---

# REQ-VENDOR-MANAGEMENT-01 - Order Sync & Fulfillment

## 6.1 Weekly Bulk Import Workflow
```
Process Flow:
Day 1: Vendor shipments arrive at warehouse
Day 2: Quality inspection begins (accept/reject per package)  
Day 3-4: Repackaging of accepted goods into customer-ready units
Day 5: Update internal inventory system with received stock
Day 6-7: Process pending orders; forward to vendors as needed
Repeat weekly schedule or adjust based on vendor SLA
```

## 6.2 Vendor Order Placing
```
Order placement options per vendor:
1. CSV import of customer order data (vendor accepts this)
2. Web portal order entry with admin credentials
3. Direct API call if vendor supports it  
4. Manual email/phone for very small vendors
```

## 6.3 Stock Availability Verification
- Check vendor stock before adding to active cart? [Yes/No] - Default: No  
- Display only known inventory levels vs. "limited stock" disclaimer?  
- Reserve orders for 24hrs on low-stock items without confirmation

---

# REQ-CATALOG-STRUCTURE-01 - Product Taxonomy

## 7.1 Category Hierarchy
```
Catalog Structure:
├── Locomotives
│   ├── Steam Engine Set (1:87, 1:220)
│   ├── Diesel Locomotive Collection
│   └── Electric Train Assortment
├── Rolling Stock / Other Trains
│   ├── Passenger Carriages (Vintage & Modern)
│   ├── Cargo Wagons (Freight & Tankers)
│   └── Special Purpose Vehicles
├── Tracks & Track Accessories
│   ├── HO Gauge (1:87 scale) Products
│   ├── N Gauge (1:160 scale) Products
│   ├── O Gauge (1:48 scale) Products  
│   ├── Z Gauge Products
│   ├── Switches & Crossings
│   └── Track Sleepers (Wood/Steel/Ballast Options)
├── Accessories - Buildings & Structures
│   ├── Residential Model Houses
│   ├── Commercial Buildings (Stations/Shops)
│   ├── Industrial Facilities (Docks/Factories)
│   └── Bridges, Tunnels, Overpasses
├── Scenery & Landscape Items
│   ├── Terrain Pieces (Mountains/Hills/Rock)  
│   ├── Vegetation Trees/Bushes/Plants
│   ├── Water Features (Rivers/Lakes/Cascades)
│   ├── Custom Signage Boards
├── Special Offers - Promotional Sections
│   ├── Bulk Purchase Bundles (Buy X Get Y Free)
│   ├── Seasonal Holiday Themes
│   └── Closeout/Clearance Sale Items
└── Tools & Maintenance Equipment
    ├── Soldering & Welding Tools
    ├── Layout Cleaning Kits  
    └── Repair & Replacement Parts
```

## 7.2 Product Filter Options
- Gauge type selector (multi-select for cross-gauge searches)  
- Era compatibility filter (Modern/Classic/Vintage era)  
- Brand/scale precision selector  
- Manufacturer/Seller filtering (vendor transparency)  

---

# REQ-FULLMENT-LOGISTICS - Shipping & Routing

## 8.1 Customer Preference Options
| Shipping Type | Delivery Window | Price Level | Notes |
|--------------|----------------|------------|-------|
| Economic | 3-5 business days | Free/Baseline | Standard shipping for orders >X EUR |
| Standard | 2-3 business days | +€1.50 | Priority shipping option |
| Express | 1-2 day / Overnight | +€4.00 | Same-day or next-day available (region based) |

## 8.2 Regional Routing Matrix
```
Destination Primary Carrier       | Backup Carrier  
Netherlands & Belgium             → PostNL/DPD        UPS/PostNL
Germany                           → Deutsche Post     DHL  
France                            → CDG Express      Colis Privé  
Other Eurozone                   → DPD              GLS/FedEx  
```

## 8.3 Shipping Label Generation
```
Label requirements:
• Custom branding with shop logo
• Quality inspection status visible (inspected by TrainWorld)
• Batch number for tracking return shipments
• Country-specific addressing format applied automatically
```

---

# REQ-QUALITY-CHECK - Quality Inspection Workflow

## 9.1 Quality Control Requirements
```
Inspection checklist per package:
✓ Visual damage check on exterior packaging  
✓ Unboxing inspection of product condition  
✓ Functional verification (for electronics motors)  
✓ Authenticity verification for branded items  
✓ Packaging reassembly to retail standard
```

## 9.2 Inspection Staffing & Training
- Warehouse staff trained in model train product handling
- Rejection rate tracking (<5% target)  
- Damaged goods disposal protocol documented  
- Vendor quality issues logged and escalated  

## 9.3 Customer Communication on Quality Issues
```
Inspection outcome handling:
• Acceptable items → Replaced into stock inventory  
• Minor defects noted → Flagged as "pre-owned" category  
• Unacceptable returns → Documented in vendor rejection log  
• Dispute resolution process documented
```

---

# REQ-CUSTOMER-NOTIFICATIONS - Price Alerts & Emails

## 10.1 Wishlist & Alert Features
Feature: Add to wishlist (guest users stored via email hash)  
Trigger: Check price weekly (or on user opt-in, continuous monitoring)  
Alert: Email notification if price drops >10% from current listing  

### Notification Template:
```
Subject: Great news! Your wishlist item "Product X" is now 25% cheaper  

Body: Hi [Customer Name], 

The "Locomotive YZ-1234" you added to your wishlist was just lowered 
to **€[New Price]** (was €[Old Price] - a savings of €[Savings])!

This price drop qualifies for our best loyalty discount.  
Click here to view your wishlist and complete purchase.

Your [TrainWorld Team]
```

## 10.2 Opt-In/Out Requirements
GDPR-compliant consent management:
- Marketing email opt-in required separately  
- Order confirmation includes email preferences section  
- Easy unsubscribe link in every campaign header  

---

# REQ-TECH-NONFUNC - Technical Performance & Security

## 11.1 Response Time Targets
```
Page load < 2 seconds on typical connections (4G/5G)
Cookie preference application: <50ms latency
Email deliverability rate: >95% inbox placement
API/vendor call success rate: >99% uptime goal
```

## 11.2 Security Requirements
```
Mandatory security features:
• SSL/TLS 1.2+ encryption (HTTPS everywhere)  
• Two-factor admin access required  
• Regular WordPress core/plugin updates scheduled  
• Daily automated data backups (offsite storage)  
• GDPR compliance for customer data handling
• Cookie consent management for user tracking
```

---

## DOCUMENT VERSION CONTROL

| Item | Value |
|------|-------|
| Document Version | 1.0 |
| Created Date | Current date |
| Next Review Phase | End of Phase 1 implementation |
| Status: | Final (ready for implementation) |
