feat(es_extended): add Vehicle Identification Number (VIN) system

[Nonanti]

Description

This PR introduces a robust Vehicle Identification Number (VIN) system to the ESX Framework, providing unique identifiers for all vehicles. The implementation follows real-world VIN standards adapted for FiveM use.

Motivation

This addition addresses issue #1638 by implementing a comprehensive VIN system that enables:

• Unique vehicle identification: Each vehicle gets a unique 17-character VIN following modified ISO 3779 standard
• Vehicle tracking: Track vehicles across ownership changes and modifications
• Data integrity: Check digit validation prevents VIN tampering
• Backward compatibility: Existing vehicles work seamlessly, VINs are generated when needed

Implementation Details

1. VIN Generation Module

• 17-character format: 1ES XXXXX X Y ZZZZZZ
• Check digit calculation for validation
• Model-specific encoding when available
• Guaranteed uniqueness with database verification

2. Vehicle Class Integration

• New methods: getVIN(), getFromVIN()
• VIN preserved during plate changes
• Automatic VIN generation for vehicles without one
• Entity statebag integration for client access

3. Database Changes

• Added vin column to owned_vehicles table
• Indexed for fast lookups
• Optional VIN history tracking table
• Migration script with stored procedure for existing vehicles

4. Export Functions

• ESX.GenerateVehicleVIN(modelHash?, owner?) - Generate unique VIN
• ESX.ValidateVehicleVIN(vin) - Validate VIN format and check digit
• ESX.DecodeVehicleVIN(vin) - Extract information from VIN
• ESX.GetExtendedVehicleFromVIN(vin) - Get vehicle by VIN

Testing

Comprehensive test suite included (/testvin command):

• VIN generation and uniqueness
• Check digit validation
• VIN decoding
• Vehicle class integration
• Backward compatibility

All tests pass successfully.

Usage Example

-- Generate VIN for new vehicle
local vin = ESX.GenerateVehicleVIN(GetHashKey("adder"), xPlayer.identifier)

-- Get vehicle by VIN
local xVehicle = ESX.GetExtendedVehicleFromVIN("1ES2X3Y45S1X123456")
if xVehicle then
    print(xVehicle:getPlate())
end

-- Validate VIN
if ESX.ValidateVehicleVIN(vin) then
    local info = ESX.DecodeVehicleVIN(vin)
    print("Year:", info.modelYear)
end

Migration

1. Run the SQL migration: [SQL]/add_vin_support.sql
2. Optionally generate VINs for existing vehicles: CALL GenerateVINsForExistingVehicles();
3. No breaking changes - existing code continues to work

Files Changed

• server/modules/vin.lua - Core VIN generation and validation module
• server/classes/vehicle.lua - Extended with VIN support
• server/functions.lua - New VIN-related exports
• fxmanifest.lua - Include VIN module
• [SQL]/add_vin_support.sql - Database migration
• tests/test_vin.lua - Comprehensive test suite
• VIN_FEATURE_DOCUMENTATION.md - Detailed documentation

---

PR Checklist

• My commit messages and PR title follow the Conventional Commits standard.
• My changes have been tested locally and function as expected.
• My PR does not introduce any breaking changes.
• I have provided a clear explanation of what my PR does, including the reasoning behind the changes and any relevant context.

Related Issues

Closes #1638

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 4 committers have signed the CLA.

✅ Kr3mu
✅ Kenshiin13
❌ github-actions[bot]
❌ Nonanti
_{You have signed the CLA already but the status is still pending? Let us recheck it.}