feat: improve Zabbix multi-version compatibility and introduce local development environment

This update enhances compatibility across multiple Zabbix versions and introduces tools for easier local development and testing.

Key improvements and verified version support:
- Verified Zabbix version support: 6.2, 6.4, 7.0, and 7.4.
- Version-specific feature handling:
  - `history.push` is enabled only for Zabbix 7.0+; older versions skip it with a clear error or notice.
  - Conditional JSON-RPC authentication: the `auth` field is automatically added to the request body for versions older than 6.4.
  - Implemented static Zabbix version caching in the datasource to minimize redundant API calls.
- Query optimization refinements:
  - Added mapping for implied fields (e.g., `state` -> `items`, `deviceType` -> `tags`).
  - Automatically prune unnecessary Zabbix parameters (like `selectItems` or `selectTags`) when not requested.
- Local development environment:
  - Added a new `zabbix-local` Docker Compose profile that includes PostgreSQL, Zabbix Server, and Zabbix Web.
  - Supports testing different versions by passing the `ZABBIX_VERSION` environment variable (e.g., 6.2, 6.4, 7.0, 7.4).
  - Provided a sample environment file at `samples/zabbix-local.env`.
- Documentation and Roadmap:
  - Updated README with a comprehensive version compatibility matrix and local environment instructions.
  - Created a new guide: `docs/howtos/local_development.md`.
  - Updated maintenance guides and added "Local Development Environment" as an achieved milestone in the roadmap.
- Test suite enhancements:
  - Improved Smoketest and RegressionTest executors with more reliable resource cleanup and error reporting.
  - Made tests version-aware to prevent failures on older Zabbix instances.

BREAKING CHANGE: Dropped Zabbix 6.0 specific workarounds; the minimum supported version is now 6.2.

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 with a specific Zabbix version (e.g. 6.4)
+ZABBIX_VERSION=alpine-6.4-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.4, 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.