# Runtime MySQL Provider (branch `feature/runtime-mysql-config-provider`)

This branch adds optional MySQL providers for runtime config and sessions, while keeping full legacy file fallback.

## What changed

- `MAIN/config.php`
  - Added provider switches:
    - `RUNTIME_CONFIG_PROVIDER=file|mysql`
    - `RUNTIME_SESSION_PROVIDER=file|mysql`
  - Added DB connection env settings and table names.
- `MAIN/helpers.php`
  - Added provider helpers and MySQL access wrappers.
  - Added provider-aware loaders:
    - `getObjectsData()`
    - `getApiKeys()`
    - `getApiServer()`
    - `getDiscountsConfig()`
    - `getLocalizedObjectName()`
  - Existing business methods now consume provider-aware loaders.
- `MAIN/session.php`
  - Added optional MySQL storage for:
    - chat-to-object mapping
    - user session JSON
  - Legacy file mode remains unchanged as fallback.
- Runtime handlers switched from direct `objects.json` reads to provider wrappers:
  - `MAIN/telegram.php`
  - `MAIN/awaiting_object_code.php`
  - `MAIN/awaiting_phone.php`
  - `MAIN/awaiting_car_number.php`
  - `MAIN/awaiting_discount.php`
  - `MAIN/lang.php`
- `MAIN/validator_api.php`
  - `discounts.json` now resolved through `getDiscountsConfig()`.

## Default behavior

No env changes required. By default:

- `RUNTIME_CONFIG_PROVIDER=file`
- `RUNTIME_SESSION_PROVIDER=file`

So current contour keeps working exactly via files.

## Enable MySQL for new object contour

Set environment variables for runtime process:

```env
RUNTIME_CONFIG_PROVIDER=mysql
RUNTIME_SESSION_PROVIDER=mysql

RUNTIME_DB_HOST=127.0.0.1
RUNTIME_DB_PORT=3306
RUNTIME_DB_NAME=validators_new_object
RUNTIME_DB_USER=validators_app
RUNTIME_DB_PASSWORD=CHANGE_ME
RUNTIME_DB_CHARSET=utf8mb4

# optional (defaults shown)
RUNTIME_DB_TABLE_OBJECTS=runtime_objects
RUNTIME_DB_TABLE_CONFIGS=runtime_object_configs
RUNTIME_DB_TABLE_SESSIONS=runtime_user_sessions
RUNTIME_DB_TABLE_MAPPINGS=runtime_chat_object_mapping
```

Apply schema:

- `DOCS/runtime_mysql_schema.sql`

## Data model approach

To preserve runtime business logic, MySQL stores the same JSON structures:

- `api_keys_json` (legacy `api_keys.json` equivalent)
- `api_server_json` (legacy `api_server.json` equivalent)
- `discounts_json` (legacy `discounts.json` equivalent)

This minimizes risk during first rollout.

## Rollout strategy

1. Keep old objects in file mode.
2. Run only new test object in MySQL mode.
3. Validate end-to-end behavior.
4. Migrate old objects gradually after acceptance.