README

English | 中文

A Symfony bundle for coupon command code system that provides command-based coupon distribution and management functionality.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Core Concepts
• JsonRPC Interface
• Admin Interface
• Architecture
• Usage Examples
• Advanced Usage
• Service Configuration
• Error Handling
• Testing
• Contributing
• Support
• License
• Changelog

Features

• Command Management: Create, edit, and delete coupon command codes
• Usage Restrictions: Multi-dimensional usage restrictions (time, count, user groups, etc.)
• JsonRPC Interface: Standard JSON-RPC 2.0 API endpoints
• Admin Interface: Complete management interface based on EasyAdmin
• Usage Records: Complete command usage tracking and statistics
• Flexible Restrictions: Time windows, usage limits, and user targeting
• User Group Targeting: Allow specific users or user tags to use commands

Requirements

• PHP 8.1+
• Symfony 6.4+
• Doctrine ORM 3.0+
• tourze/coupon-core-bundle
• tourze/json-rpc-core

Installation

Install via Composer

composer require tourze/coupon-command-bundle

Enable the Bundle

Add to config/bundles.php:

return [
    // ...
    Tourze\CouponCommandBundle\CouponCommandBundle::class => ['all' => true],
];

Database Migration

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Quick Start

use Tourze\CouponCommandBundle\Service\CommandValidationService;
use Tourze\CouponCommandBundle\Service\CommandManagementService;

// Validate command
$validationService = $container->get(CommandValidationService::class);
$result = $validationService->validateCommand('NEWUSER2024', 'user123');

if ($result['valid']) {
    // Command is valid, can be used
    $useResult = $validationService->useCommand('NEWUSER2024', 'user123');
    
    if ($useResult['success']) {
        echo "Coupon claimed successfully, ID: " . $useResult['couponId'];
    }
}

Core Concepts

Restriction Types

1. Time Restrictions: Set valid time range for commands
2. Count Restrictions: Total usage count and per-user usage limits
3. User Restrictions: Specify allowed user groups for command usage
4. Status Control: Enable/disable command restrictions

JsonRPC Interface

Validate Command - ValidateCouponCommand

Validates command validity without actually using the command.

Request Parameters:

{
    "command": "string",     // Command content
    "userId": "string"       // User ID (optional)
}

Response Example:

{
    "valid": true,
    "couponInfo": {
        "id": "1234567890",
        "name": "New User Coupon",
        "type": "discount",
        "amount": 100
    },
    "commandConfig": {
        "id": "9876543210",
        "command": "NEWUSER2024"
    }
}

Use Command - UseCouponCommand

Use command to claim coupon.

Request Parameters:

{
    "command": "string",     // Command content
    "userId": "string"       // User ID (required)
}

Response Example:

{
    "success": true,
    "couponId": "1234567890",
    "message": "Coupon claimed successfully"
}

Admin Interface

The bundle provides complete EasyAdmin management interface:

1. Command Configuration Management - CommandConfigCrudController

   • Create and edit commands
   • Link to coupons
   • View usage statistics

2. Restriction Configuration Management - CommandLimitCrudController

   • Set usage restrictions
   • Configure time windows
   • Manage user group restrictions

3. Usage Record Viewing - CommandUsageRecordCrudController

   • View detailed usage records
   • Success/failure statistics
   • User usage tracking

Architecture

Entity Relationships

• CommandConfig: Command configuration, linked to specific coupons
• CommandLimit: Command usage restriction configuration
• CommandUsageRecord: Command usage tracking records

Service Layer

• CommandValidationService: Command validation and execution
• CommandManagementService: Command management and statistics

Core Features

• Audit Trails: All usage is tracked with IP, user, and timestamp information
• Flexible Validation: Time-based, count-based, and user-based restrictions
• Admin Interface: Complete CRUD operations via EasyAdmin controllers

Usage Examples

Basic Usage

// Create command configuration
$managementService = $container->get(CommandManagementService::class);
$commandConfig = $managementService->createCommandConfig('SPRING2024', $coupon);

// Add usage restrictions
$managementService->addCommandLimit(
    $commandConfig->getId(),
    maxUsagePerUser: 1,        // 1 use per person
    maxTotalUsage: 1000,       // 1000 total uses
    startTime: new \DateTime('2024-03-01'),
    endTime: new \DateTime('2024-03-31')
);

Advanced Usage

User Group Restrictions

// Create command with user group restrictions
$managementService->addCommandLimit(
    $commandConfigId,
    maxUsagePerUser: 3,
    allowedUsers: ['vip_user_1', 'vip_user_2'],  // Only allow VIP users
    allowedUserTags: ['premium', 'gold']         // Allow specific tagged users
);

// Get usage statistics
$stats = $managementService->getCommandConfigDetail($commandConfigId);
echo "Total usage: " . $stats['stats']['totalUsage'];
echo "Successful usage: " . $stats['stats']['successUsage'];

Service Configuration

In services.yaml, the bundle automatically registers the following services:

• CommandValidationService: Command validation service
• CommandManagementService: Command management service
• JsonRPC methods: ValidateCouponCommand, UseCouponCommand

Error Handling

Common Error Messages

Logging

All command usage is logged with detailed information:

• Usage timestamp
• User information
• Success/failure status
• Failure reason
• Additional context information

Testing

Run the test suite:

./vendor/bin/phpunit packages/coupon-command-bundle/tests

Test coverage includes:

• Entity unit tests
• Service layer business logic tests
• Integration tests
• JsonRPC interface tests

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

Support

For issues or suggestions, please submit an Issue or Pull Request on the main repository.

License

MIT License

Changelog

v0.0.1

• Initial version release
• Complete command system functionality
• JSON-RPC 2.0 interface support
• EasyAdmin management interface
• Complete unit test coverage