feat: verify and enhance compatibility with Zabbix 6.0, 6.2, 6.4, and 7.0

This commit comprehensive updates the API to ensure full compatibility across all major Zabbix versions (6.0 LTS, 6.2, 6.4, and 7.0 LTS) and introduces a local development environment for multi-version testing.

Verified Zabbix Versions:
- Zabbix 7.0 (LTS): Full support, including native `history.push` for telemetry.
- Zabbix 6.4: Supported (excluding `history.push`); uses `hostgroup.propagate` and UUID-based matching.
- Zabbix 6.2: Supported (excluding `history.push`); uses `hostgroup.propagate` and `templategroup.*` methods.
- Zabbix 6.0 (LTS): Supported (excluding `history.push`); includes specific fallbacks:
    - JSON-RPC: Restored `auth` field in request body for versions lacking Bearer token support.
    - Permissions: Implemented name-based fallback for host/template groups (no UUIDs in 6.0).
    - Group Expansion: Automatic manual expansion of group rights during import.
    - API Methods: Fallback from `templategroup.*` to `hostgroup.*` methods.

Key Technical Changes:
- Local Development: Added `zabbix-local` Docker Compose profile to launch a complete Zabbix stack (Server, Web, Postgres) from scratch with dynamic versioning via `ZABBIX_VERSION`.
- Query Optimization: Refined dynamic field selection to handle implied fields and ensure consistent output regardless of initial Zabbix parameters.
- Documentation:
    - New `local_development.md` HOWTO guide.
    - Updated `README.md` with detailed version compatibility matrix.
    - Expanded `roadmap.md` with achieved milestones.
- Testing:
    - Updated entire Jest test suite (23 suites, 96 tests) to be version-aware and robust against naming collisions.
    - Enhanced Smoketest and Regression Test executors with better cleanup and error reporting.

docs/howtos/README.md

@@ -22,6 +22,9 @@ Discover how the permission system works, how to define permission levels using
 ### 🛠️ [Technical Maintenance](./maintenance.md)
 Guide on code generation (GraphQL Codegen), running Jest tests, and local Docker builds.
 
+### 💻 [Local Development Environment](./local_development.md)
+Detailed instructions for setting up a fully isolated local development environment with Zabbix using Docker Compose.
+
 ### 🧪 [Test Specification](../tests.md)
 Detailed list of test cases, categories (Unit, Integration, E2E), and coverage checklist.
 

docs/howtos/local_development.md

@@ -0,0 +1,88 @@
+# 💻 Local Development Environment
+
+This guide provides detailed instructions on how to set up a fully isolated local development environment for the Zabbix GraphQL API using Docker Compose.
+
+## 🚀 Overview
+The project includes a Docker Compose profile that launches a complete Zabbix stack alongside the GraphQL API and MCP server. This allows you to develop and test features against different Zabbix versions without needing an external Zabbix installation.
+
+### Included Services
+- **`zabbix-graphql-api`**: The main GraphQL server.
+- **`apollo-mcp-server`**: The Model Context Protocol server for AI integration.
+- **`postgres-server`**: PostgreSQL 16 database for Zabbix.
+- **`zabbix-server`**: Zabbix Server (PostgreSQL version).
+- **`zabbix-web`**: Zabbix Web interface (Nginx/PostgreSQL).
+
+## 🛠️ Step-by-Step Setup
+
+### 1. Start the Environment
+Use the `zabbix-local` profile to start all services. You can optionally specify the Zabbix version using the `ZABBIX_VERSION` environment variable.
+
+```bash
+# Start the latest 7.0 (default)
+docker compose --profile zabbix-local up -d
+
+# Start Zabbix 6.0 (LTS)
+ZABBIX_VERSION=alpine-6.0-latest docker compose --profile zabbix-local up -d
+```
+
+### 2. Configure Zabbix
+Once the containers are running, you need to perform a minimal setup in the Zabbix UI:
+
+1. Open `http://localhost:8080` in your browser.
+2. Log in with the default credentials:
+   - **User**: `Admin`
+   - **Password**: `zabbix`
+3. Navigate to **Administration** > **Users** > **API tokens**.
+4. Create a new token for the `Admin` user (or a dedicated service user) and copy it.
+5. **Create Base Host Group**: The API requires a base host group to exist for importing devices.
+   - Navigate to **Configuration** > **Host groups** (or **Data collection** > **Host groups** in Zabbix 7.0).
+   - Create a host group named `Roadwork` (or the value of `ZABBIX_EDGE_DEVICE_BASE_GROUP` in your `.env`).
+   - **Note**: If your base group is nested (e.g., `Roadwork/Devices`), ensure the full path exists. Zabbix does not automatically create parent groups when creating child groups via the API.
+
+### 3. Connect the API
+To connect the GraphQL API to your local Zabbix instance, update your `.env` file with the following values (referenced in `samples/zabbix-local.env`):
+
+```env
+# Internal Docker network URL
+ZABBIX_BASE_URL=http://zabbix-web:8080/
+
+# The token you created in Step 2
+ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-newly-created-token
+```
+
+### 4. Restart the API
+Apply the configuration by restarting the API container:
+
+```bash
+docker compose restart zabbix-graphql-api
+```
+
+## ✅ Verification
+You can verify the setup by running a simple query against the local API:
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"query": "{ apiVersion zabbixVersion }"}' \
+  http://localhost:4001/
+```
+
+The `zabbixVersion` should match the version you specified in `ZABBIX_VERSION`.
+
+## 💡 Advanced Usage
+
+### Data Persistence
+Zabbix data is stored in a named Docker volume called `zbx_db_data`. This ensures that your configuration, templates, and hosts are preserved even if you stop or remove the containers.
+
+To perform a clean reset of the environment:
+```bash
+docker compose --profile zabbix-local down -v
+```
+
+### Testing Multiple Versions
+The local environment is perfect for testing the API's version-specific logic (e.g. `history.push` vs `zabbix_sender`). Simply change the `ZABBIX_VERSION` variable and restart the stack.
+
+Supported tags can be found on the [Zabbix Docker Hub](https://hub.docker.com/u/zabbix).
+
+---
+**Related Guide**: [Technical Maintenance](./maintenance.md)
+**Related Reference**: [Zabbix Version Compatibility](../../README.md#-zabbix-version-compatibility)

docs/howtos/maintenance.md

@@ -34,6 +34,9 @@ We use [Jest](https://jestjs.io/) for unit and integration testing.
   npm run test
   ```
 
+#### Local Development Setup
+For running integration tests against a real Zabbix instance, it is recommended to use the [Local Development Environment](./local_development.md). This setup allows you to test the API against specific Zabbix versions (e.g. 6.0, 7.0) in an isolated way.
+
 #### Adding New Tests
 - **Location**: Place new test files in `src/test/` with the `.test.ts` extension.
 - **Coverage**: Ensure you cover both successful operations and error scenarios.