Add explicit @version special route token support for API major versioning within a single module

Bắt đầu bằng cách lần theo việc xử lý @version trong src/Router/PatternCompiler.php, src/Router/RouteBuilder.php, src/Router/RouteDispatcher.php, src/Router/MatchedRoute.php và src/Http/Traits/Request/Route.php; trước tiên hãy kiểm tra các template của DemoApi và các dependency #546 và #548. Được xem là hoàn thành khi các major version được cấu hình và được hỗ trợ khớp nhau, các controller nhận biết version được resolve trong một module, các giá trị version vẫn là một phần của route context, và các test bao phủ việc matching và resolution.

Summary

Add API major versioning support based on the explicit special route token:

• @version

so a single API module can expose multiple major API versions concurrently, such as:

• /api/v1/posts
• /api/v2/posts

without treating each version as a separate module.

Why

Quantum needs a clean framework-level API versioning model.

The intended ownership model is:

• one logical Api module
• multiple supported API major versions inside that module

With the special route token foundation in place, versioning can be expressed explicitly in route patterns instead of relying on:

• duplicated route trees
• positional URL conventions
• separate modules per version
• hidden dispatch tricks

Goal

Allow routes to explicitly declare API major version position using:

• @version

and let the framework treat the matched version as framework-owned route context for version-aware controller resolution.

Proposed Direction

API routes that are versioned should explicitly include:

• @version

Examples:

$route->get('@version/posts', 'PostController', 'posts');
$route->get('@version/post/[uuid=:any]', 'PostController', 'post');
$route->post('@version/signin', 'AuthController', 'signin');

This should allow URLs such as:

• /api/v1/posts
• /api/v2/posts
• /api/v1/signin

depending on module prefix configuration and supported versions.

Config Direction

Supported API versions should be declared in module config.

A likely shape is:

'Api' => [
    'prefix' => 'api',
    'enabled' => true,
    'versions' => ['v1', 'v2'],
]

The route token:

• @version

should then match only those configured supported versions.

Controller Resolution Direction

Matched version values should be used by the framework to resolve version-specific controllers inside the same module.

Examples:

• v1 + PostController
  resolves to:

  • {ModuleBaseNamespace}\Api\Controllers\V1\PostController

• v2 + PostController
  resolves to:

  • {ModuleBaseNamespace}\Api\Controllers\V2\PostController

This allows one route shape to map to different major-version controller implementations inside a single module.

Important behavior

The resolved version should be:

• matched through the @version token
• validated against configured supported versions
• made available to framework internals as version route context
• used for version-aware controller resolution
• kept distinct from ordinary controller action parameters by default

Scope

This ticket should focus on major API versioning only.

It should not introduce:

• minor or patch versioning in the URL
• header-based minor/patch runtime negotiation
• separate modules per API version

Minor and patch changes should remain outside the first implementation scope.

Acceptance Criteria

• routes can explicitly declare API version position using @version
• matched @version values are validated against configured supported versions
• a single API module can expose multiple supported major versions concurrently
• matched version values are used for version-aware controller resolution within the same module
• routed version values do not become ordinary positional controller action parameters by default
• tests cover @version route matching and version-aware controller resolution behavior
• templates and examples can be updated to use @version where appropriate

Notes

Relevant code:

• src/Router/PatternCompiler.php
• src/Router/RouteBuilder.php
• src/Router/RouteDispatcher.php
• src/Router/MatchedRoute.php
• src/Http/Traits/Request/Route.php
• src/Module/Templates/DemoApi

This ticket depends on:

• #546
• #548