# FINEART Shop Manager Plugin

WordPress plugin for managing shop partnerships, consignment sales, inventory, and invoicing.

## Version
1.0.0 - Base Foundation

## Requirements
- WordPress 6.0+
- PHP 7.4+
- WooCommerce (for restock integration)

## Installation

1. Upload the `fineart-shop-manager` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Navigate to "Shop Partners" in the admin menu

## Current Features

### ✅ Implemented (Base Foundation)
- Custom database tables for inventory, sales, damages, invoices, artist payments
- Custom `shop_partner` role with appropriate capabilities
- Custom `shop_partner` post type
- Admin menu structure with dashboard, shops list, financials, damages, artist payments
- Basic admin dashboard with statistics and recent activity
- Inventory management class (basic stock tracking)
- Placeholder classes for sales, damages, invoices, QR codes, WooCommerce integration
- AJAX handler structure for frontend/backend communication

### ✅ Implemented

**Phase 2 - Shop Management:**
- Shop meta boxes with all required fields (partnership details, contact info, addresses, business info, system fields)
- Automatic shop code generation
- Data validation and sanitization
- Interactive JavaScript features (address copying, field validation)
- Integration with WordPress user system

### 🚧 To Be Implemented (Next Phases)

**Phase 3 - Core Functionality:**
- Sales declaration system (manual + QR code)
- Damage reporting system
- Invoice generation and PDF creation
- Payment tracking (3 states: unpaid/pending/paid)
- Artist commission calculation and tracking

**Phase 3 - Frontend Dashboard:**
- Shop partner frontend dashboard
- Stock management interface
- Sales declaration modals
- Damage reporting forms
- Invoice viewing and payment declaration
- Restock request system

**Phase 4 - Advanced Features:**
- QR code generation (requires `chillerlan/php-qrcode` library)
- Batch sales entry
- Discount handling (5%, 10%, 15%, 20%)
- Quarterly audit tools
- Email notifications
- Analytics and reporting

## Database Schema

### Tables Created on Activation:

- `wp_fineart_shop_inventory` - Individual print tracking with unique codes
- `wp_fineart_shop_sales` - Sales transactions and commission calculations
- `wp_fineart_shop_damages` - Damage/loss reports and fees
- `wp_fineart_shop_invoices` - Invoice management and payment tracking
- `wp_fineart_artist_payments` - Artist commission tracking

## File Structure

```
fineart-shop-manager/
├── fineart-shop-manager.php          # Main plugin file
├── includes/                          # Core functionality
│   ├── class-database.php             # Database schema
│   ├── class-roles.php                # Custom roles
│   ├── class-shop-post-type.php       # Custom post type
│   ├── class-inventory.php            # Inventory management
│   ├── class-sales.php                # Sales processing
│   ├── class-damages.php              # Damage handling
│   ├── class-invoices.php             # Invoice generation
│   ├── class-qr-codes.php             # QR code system
│   └── class-woocommerce-integration.php
├── admin/                             # Admin interface
│   ├── class-admin-menu.php           # Menu structure
│   ├── class-admin-dashboard.php      # Dashboard widgets
│   ├── class-shop-meta-boxes.php      # Shop editing interface
│   └── views/                         # Admin page templates
│       ├── dashboard.php
│       ├── financials.php
│       ├── damages.php
│       └── artist-payments.php
├── public/                            # Frontend (shop dashboard)
│   ├── class-shop-dashboard.php       # Frontend dashboard
│   └── class-ajax-handler.php         # AJAX endpoints
├── assets/                            # CSS/JS assets
│   ├── css/
│   │   └── admin.css
│   └── js/
│       └── admin.js
└── languages/                         # Translation files
```

## Development Roadmap

### Current Status: PHASE 2 COMPLETE ✅

**What's Working:**
- ✅ Base foundation (database, roles, post type, admin structure)
- ✅ Shop meta boxes with all required fields
- ✅ Automatic shop code generation
- ✅ Data validation and interactive UI

**Next Steps:**
1. Build sales declaration system (3 entry points: QR, button, batch)
2. Create damage reporting workflow
3. Implement invoice generation with PDF creation
4. Build payment tracking (3-state system)
5. Create frontend shop dashboard
6. Add QR code generation
7. Implement email notifications
8. Add comprehensive error handling

## Usage

### For Administrators:

1. **Add a New Shop:**
   - Go to Shop Partners → Add New Shop
   - Enter shop name in the title field
   - Fill in Partnership Details:
     - Set status (Active/Inactive/Suspended)
     - Commission percentage (default: 50%)
     - Payment terms (Net 15/30/45/60 or Immediate)
     - Contract start date
   - Enter Contact Information:
     - Shop contact person (name, email, phone)
     - FINEART contact person for this shop
   - Add Addresses:
     - Delivery address (required for auto-generating shop code)
     - Invoicing address (can copy from delivery with checkbox)
   - Fill Business Information:
     - Tax ID / VAT Number
     - Business registration (SIRET, etc.)
   - System Information:
     - Shop code (auto-generated or manual)
     - Link to WordPress user with shop_partner role
   - Click Publish to save

2. **Manage Inventory:**
   - (Coming in Phase 3)

3. **Generate Invoices:**
   - (Coming in Phase 3)

### For Shop Partners:

1. **Access Dashboard:**
   - Log in with shop partner credentials
   - Navigate to shop dashboard (frontend)
   - (Coming in Phase 3)

## Technical Notes

### Database Versioning
- Database version stored in `fineart_shop_db_version` option
- Schema updates handled via `dbDelta()` function

### Custom Capabilities
Shop partners have these capabilities:
- `access_shop_dashboard`
- `view_shop_inventory`
- `report_shop_sales`
- `report_shop_damages`
- `request_shop_restock`
- `view_shop_financials`
- `download_shop_invoices`

### Security
- All AJAX actions require nonce verification
- Shop partners can only view their own data
- Input sanitization and validation on all forms
- SQL queries use prepared statements

## Support

For questions or issues, contact: Loïc Kernen (FINEART Gallery)

## License

GPL v2 or later

## Changelog

### 1.0.1 (2026-02-12) - Phase 2: Shop Management
- ✅ Complete shop meta boxes implementation
  - Partnership details (status, commission %, payment terms, contract date)
  - Contact information (shop contact + FINEART contact)
  - Addresses (delivery + invoicing with auto-copy feature)
  - Business information (tax ID, business registration)
  - System fields (shop code, linked WordPress user)
- ✅ Automatic shop code generation based on city
- ✅ Data validation and sanitization for all fields
- ✅ Interactive JavaScript features
  - "Same as delivery" checkbox for invoicing address
  - Real-time field validation
  - Auto-uppercase shop codes
  - Required fields warning before publish
- ✅ Integration with WordPress user system for shop_partner role

### 1.0.0 (2026-02-12) - Phase 1: Base Foundation
- Initial base foundation
- Database schema created
- Custom role and post type implemented
- Admin menu structure created
- Basic dashboard with statistics
- Placeholder classes for future development