rospatent 1.2.0 → 1.3.0

data/README.md

@@ -15,7 +15,7 @@ A comprehensive Ruby client for the Rospatent patent search API with advanced fe
 - 📊 **Structured Logging** - JSON/text logging with request/response tracking
 - 🚀 **Batch Operations** - Process multiple patents concurrently
 - ⚙️ **Environment-Aware** - Different configurations for dev/staging/production
-- 🧪 **Comprehensive Testing** - 96% test coverage with integration tests
+- 🧪 **Comprehensive Testing** - 219 tests with 465 assertions, comprehensive integration testing
 - 📚 **Excellent Documentation** - Detailed examples and API documentation
 
 ## Installation
@@ -41,7 +41,7 @@ $ gem install rospatent
 ## Quick Start
 
 ```ruby
-# Basic configuration
+# Minimal configuration
 Rospatent.configure do |config|
   config.token = "your_jwt_token"
 end
@@ -101,25 +101,149 @@ Rospatent.configure do |config|
 end
 ```
 
-### Environment Variables
+### Environment-Specific Configuration
 
-Configure via environment variables:
+The gem automatically adjusts settings based on environment with sensible defaults:
+
+#### Development Environment
+
+```ruby
+# Optimized for development
+Rospatent.configure do |config|
+  config.environment = "development"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :debug
+  config.log_requests = true
+  config.log_responses = true
+  config.cache_ttl = 60          # Short cache for development
+  config.timeout = 10            # Fast timeouts for quick feedback
+end
+```
+
+#### Staging Environment
+
+```ruby
+# Optimized for staging
+Rospatent.configure do |config|
+  config.environment = "staging"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :info
+  config.cache_ttl = 300         # Longer cache for performance
+  config.timeout = 45            # Longer timeouts for reliability
+  config.retry_count = 3         # More retries for resilience
+end
+```
+
+#### Production Environment
+
+```ruby
+# Optimized for production
+Rospatent.configure do |config|
+  config.environment = "production"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :warn
+  config.cache_ttl = 600         # Longer cache for performance
+  config.timeout = 60            # Longer timeouts for reliability
+  config.retry_count = 5         # More retries for resilience
+end
+```
+
+### Environment Variables & Rails Integration
+
+⚠️ **CRITICAL**: Understanding environment variable priority is essential to avoid configuration issues, especially in Rails applications.
+
+#### Token Configuration Priority
+
+1. **Rails credentials**: `Rails.application.credentials.rospatent_token`
+2. **Primary environment variable**: `ROSPATENT_TOKEN`
+3. **Legacy environment variable**: `ROSPATENT_API_TOKEN`
 
 ```bash
-ROSPATENT_ENV=production
-ROSPATENT_CACHE_ENABLED=true
-ROSPATENT_CACHE_TTL=600
-ROSPATENT_LOG_LEVEL=info
-ROSPATENT_POOL_SIZE=10
+# Recommended approach
+export ROSPATENT_TOKEN="your_jwt_token"
+
+# Legacy support (still works)
+export ROSPATENT_API_TOKEN="your_jwt_token"
+```
+
+#### Log Level Configuration Priority
+
+```ruby
+# Environment variable takes precedence over Rails defaults
+config.log_level = if ENV.key?("ROSPATENT_LOG_LEVEL")
+                     ENV["ROSPATENT_LOG_LEVEL"].to_sym
+                   else
+                     Rails.env.production? ? :warn : :debug
+                   end
 ```
 
-### Environment-Specific Defaults
+⚠️ **Common Issue**: Setting `ROSPATENT_LOG_LEVEL=debug` in production will override Rails-specific logic and cause DEBUG logs to appear in production!
+
+#### Complete Environment Variables Reference
+
+```bash
+# Core configuration
+ROSPATENT_TOKEN="your_jwt_token"           # API authentication token
+ROSPATENT_ENV="production"                 # Override Rails.env if needed
+ROSPATENT_API_URL="custom_url"            # Override default API URL
+
+# Logging configuration
+ROSPATENT_LOG_LEVEL="warn"                # debug, info, warn, error
+ROSPATENT_LOG_REQUESTS="false"            # Log API requests
+ROSPATENT_LOG_RESPONSES="false"           # Log API responses
+
+# Cache configuration
+ROSPATENT_CACHE_ENABLED="true"            # Enable/disable caching
+ROSPATENT_CACHE_TTL="300"                 # Cache TTL in seconds
+ROSPATENT_CACHE_MAX_SIZE="1000"           # Maximum cache items
+
+# Connection configuration
+ROSPATENT_TIMEOUT="30"                    # Request timeout in seconds
+ROSPATENT_RETRY_COUNT="3"                 # Number of retries
+ROSPATENT_POOL_SIZE="5"                   # Connection pool size
+ROSPATENT_KEEP_ALIVE="true"               # Keep-alive connections
+
+# Environment-specific overrides
+ROSPATENT_DEV_API_URL="dev_url"           # Development API URL
+ROSPATENT_STAGING_API_URL="staging_url"   # Staging API URL
+```
+
+#### Best Practices for Rails
+
+1. **Use Rails credentials for tokens**:
+   ```bash
+   rails credentials:edit
+   # Add: rospatent_token: your_jwt_token
+   ```
+
+2. **Set environment-specific variables**:
+   ```bash
+   # config/environments/production.rb
+   ENV["ROSPATENT_LOG_LEVEL"] ||= "warn"
+   ENV["ROSPATENT_CACHE_ENABLED"] ||= "true"
+   ```
+
+3. **Avoid setting DEBUG level in production**:
+   ```bash
+   # ❌ DON'T DO THIS in production
+   export ROSPATENT_LOG_LEVEL=debug
+   
+   # ✅ DO THIS instead
+   export ROSPATENT_LOG_LEVEL=warn
+   ```
 
-The gem automatically adjusts settings based on environment:
+### Configuration Validation
 
-- **Development**: Fast timeouts, verbose logging, short cache TTL
-- **Staging**: Moderate settings for testing
-- **Production**: Longer timeouts, optimized for reliability
+```ruby
+# Validate current configuration
+errors = Rospatent.validate_configuration
+if errors.any?
+  puts "Configuration errors:"
+  errors.each { |error| puts "  - #{error}" }
+else
+  puts "Configuration is valid ✓"
+end
+```
 
 ## Basic Usage
 
@@ -137,20 +261,66 @@ results = client.search(qn: "rocket engine design")
 # Advanced search with all options
 results = client.search(
   q: "ракета AND двигатель",
-  limit: 20,
-  offset: 0,
+  limit: 50,
+  offset: 100,
+  datasets: ["ru_since_1994"],
   filter: {
     "classification.ipc_group": { "values": ["F02K9"] },
-    "biblio.application_date": { "from": "2020-01-01" }
+    "application.filing_date": { "range": { "gte": "20200101" } }
   },
-  sort: :pub_date,
-  group_by: :patent_family,
+  sort: "publication_date:desc", # same as 'sort: :pub_date'; see Search#validate_sort_parameter for other sort options
+  group_by: "family:dwpi",         # Patent family grouping: "family:docdb" or "family:dwpi"
   include_facets: true,
-  highlight: true,
+  pre_tag: "<mark>",           # Both pre_tag and post_tag must be provided together
+  post_tag: "</mark>",         # Can be strings or arrays for multi-color highlighting
+  highlight: {                 # Advanced highlight configuration (independent of pre_tag/post_tag)
+    "profiles" => [
+      { "q" => "космическая", "pre_tag" => "<b>", "post_tag" => "</b>" },
+      "_searchquery_"
+    ]
+  }
+)
+
+# Simple highlighting with tags (both pre_tag and post_tag required)
+results = client.search(
+  q: "ракета",
   pre_tag: "<mark>",
   post_tag: "</mark>"
 )
 
+# Multi-color highlighting with arrays
+results = client.search(
+  q: "космическая ракета", 
+  pre_tag: ["<b>", "<i>"],     # Round-robin highlighting
+  post_tag: ["</b>", "</i>"]   # with different tags
+)
+
+# Advanced highlighting with profiles (independent of pre_tag/post_tag)
+results = client.search(
+  q: "ракета",
+  highlight: {
+    "profiles" => [
+      { "q" => "космическая", "pre_tag" => "<b>", "post_tag" => "</b>" },
+      "_searchquery_"  # References main search query highlighting
+    ]
+  }
+)
+
+# Patent family grouping (groups patents from the same invention)
+results = client.search(
+  q: "rocket",
+  group_by: "family:docdb",    # DOCDB simple patent families
+  datasets: ["dwpi"],
+  limit: 10
+)
+
+results = client.search(
+  q: "rocket",
+  group_by: "family:dwpi",     # DWPI simple patent families  
+  datasets: ["dwpi"],
+  limit: 10
+)
+
 # Process results
 puts "Found #{results.total} total results (#{results.available} available)"
 puts "Showing #{results.count} results"
@@ -158,12 +328,153 @@ puts "Showing #{results.count} results"
 results.hits.each do |hit|
   puts "ID: #{hit['id']}"
   puts "Title: #{hit.dig('biblio', 'ru', 'title')}"
-  puts "Date: #{hit.dig('biblio', 'publication_date')}"
-  puts "IPC: #{hit.dig('classification', 'ipc')}"
+  puts "Date: #{hit.dig('common', 'publication_date')}"
+  puts "IPC: #{hit.dig('common', 'classification', 'ipc')&.map {|c| c['fullname']}&.join('; ')}"
   puts "---"
 end
 ```
 
+### Advanced Filter Parameters
+
+The `filter` parameter supports complex filtering with automatic validation and format conversion:
+
+#### List Filters (require `{"values": [...]}` format)
+
+```ruby
+# Classification filters
+results = client.search(
+  q: "artificial intelligence",
+  filter: {
+    "classification.ipc_group": { "values": ["G06N", "G06F"] },
+    "classification.cpc_group": { "values": ["G06N3/", "G06N20/"] }
+  }
+)
+
+# Author and patent holder filters
+results = client.search(
+  q: "invention",
+  filter: {
+    "authors": { "values": ["Иванов И.И.", "Петров П.П."] },
+    "patent_holders": { "values": ["ООО Компания"] },
+    "country": { "values": ["RU", "US"] },
+    "kind": { "values": ["A1", "U1"] }
+  }
+)
+
+# Document ID filters
+results = client.search(
+  q: "device",
+  filter: {
+    "ids": { "values": ["RU134694U1_20131120", "RU2358138C1_20090610"] }
+  }
+)
+```
+
+#### Date Range Filters (require `{"range": {"operator": "YYYYMMDD"}}` format)
+
+```ruby
+# Automatic date format conversion
+results = client.search(
+  q: "innovation",
+  filter: {
+    "date_published": { "range": { "gte": "2020-01-01", "lte": "2023-12-31" } },
+    "application.filing_date": { "range": { "gte": "2019-06-15" } }
+  }
+)
+
+# Direct API format (YYYYMMDD)
+results = client.search(
+  q: "technology",
+  filter: {
+    "date_published": { "range": { "gte": "20200101", "lt": "20240101" } }
+  }
+)
+
+# Using Date objects (automatically converted)
+results = client.search(
+  q: "patent",
+  filter: {
+    "application.filing_date": { 
+      "range": { 
+        "gte": Date.new(2020, 1, 1),
+        "lte": Date.new(2023, 12, 31) 
+      } 
+    }
+  }
+)
+```
+
+**Supported date operators**: `gt`, `gte`, `lt`, `lte`
+
+**Date format conversion**:
+- `"2020-01-01"` → `"20200101"`
+- `Date.new(2020, 1, 1)` → `"20200101"`
+- `"20200101"` → `"20200101"` (no change)
+
+#### Complex Multi-Field Filters
+
+```ruby
+# Comprehensive filter example
+results = client.search(
+  q: "машинное обучение",
+  filter: {
+    # List filters
+    "classification.ipc_group": { "values": ["G06N", "G06F"] },
+    "country": { "values": ["RU", "US", "CN"] },
+    "kind": { "values": ["A1", "A2"] },
+    "authors": { "values": ["Иванов И.И."] },
+    
+    # Date range filters  
+    "date_published": { "range": { "gte": "2020-01-01", "lte": "2023-12-31" } },
+    "application.filing_date": { "range": { "gte": "2019-01-01" } }
+  },
+  limit: 50
+)
+```
+
+**Supported Filter Fields**:
+
+*List filters (require `{"values": [...]}` format):*
+- `authors` - Patent authors
+- `patent_holders` - Patent holders/assignees  
+- `country` - Country codes
+- `kind` - Document types
+- `ids` - Specific document IDs
+- `classification.ipc*` - IPC classification codes
+- `classification.cpc*` - CPC classification codes
+
+*Date filters (require `{"range": {"operator": "YYYYMMDD"}}` format):*
+- `date_published` - Publication date
+- `application.filing_date` - Application filing date
+
+**Filter Validation**:
+- ✅ Automatic field name validation
+- ✅ Structure validation (list vs range format)
+- ✅ Date format conversion and validation
+- ✅ Operator validation for ranges
+- ✅ Helpful error messages for invalid filters
+
+```ruby
+# These will raise ValidationError with specific messages:
+client.search(
+  q: "test",
+  filter: { "invalid_field": { "values": ["test"] } }
+)
+# Error: "Invalid filter field: invalid_field"
+
+client.search(
+  q: "test", 
+  filter: { "authors": ["direct", "array"] }  # Missing {"values": [...]} wrapper
+)
+# Error: "Filter 'authors' requires format: {\"values\": [...]}"
+
+client.search(
+  q: "test",
+  filter: { "date_published": { "range": { "invalid_op": "20200101" } } }
+)
+# Error: "Invalid range operator: invalid_op. Supported: gt, gte, lt, lte"
+```
+
 ### Retrieving Patent Documents
 
 ```ruby
@@ -172,7 +483,7 @@ patent_doc = client.patent("RU134694U1_20131120")
 
 # Get patent by components
 patent_doc = client.patent_by_components(
-  "RU",                    # country_code
+  "RU",                   # country_code
   "134694",               # number
   "U1",                   # doc_type
   Date.new(2013, 11, 20)  # date (String or Date object)
@@ -257,12 +568,24 @@ cpc_info = client.classification_code("cpc", code: "B63H11/00", lang: "en")
 - `"ru"` - Russian
 - `"en"` - English
 
+### Available datasets list
+
+```ruby
+datasets = client.datasets_tree
+datasets.each do |category|
+  puts "Category: #{category['name_en']}"
+  category.children.each do |dataset|
+    puts "  #{dataset['id']}: #{dataset['name_en']}"
+  end
+end
+```
+
 ### Media and Documents
 
 ```ruby
 # Download patent PDF
 pdf_data = client.patent_media(
-  "National",        # collection_id
+  "National",       # collection_id
   "RU",             # country_code
   "U1",             # doc_type
   "2013/11/20",     # pub_date
@@ -277,14 +600,6 @@ pdf_data = client.patent_media_by_id(
   "National",
   "document.pdf"
 )
-
-# Get available datasets
-datasets.each do |category|
-  puts "Category: #{category['name_en']}"
-  category.children.each do |dataset|
-    puts "  #{dataset['id']}: #{dataset['name_en']}"
-  end
-end
 ```
 
 ## Advanced Features
@@ -363,7 +678,7 @@ shared_logger = Rospatent.shared_logger(level: :debug)
 
 ### Error Handling
 
-Comprehensive error handling with specific error types:
+Comprehensive error handling with specific error types and improved error message extraction:
 
 ```ruby
 begin
@@ -385,6 +700,13 @@ rescue Rospatent::Errors::ConnectionError => e
   puts "Connection error: #{e.message}"
   puts "Original error: #{e.original_error}"
 end
+
+# Enhanced error message extraction
+# The client automatically extracts error messages from various API response formats:
+# - {"result": "Error message"}           (Rospatent API format)
+# - {"error": "Error message"}            (Standard format)
+# - {"message": "Error message"}          (Alternative format)
+# - {"details": "Validation details"}     (Validation errors)
 ```
 
 ### Input Validation
@@ -424,64 +746,6 @@ puts "Cache enabled: #{global_stats[:configuration][:cache_enabled]}"
 puts "API URL: #{global_stats[:configuration][:api_url]}"
 ```
 
-## Environment Configuration
-
-### Development Environment
-
-```ruby
-# Optimized for development
-Rospatent.configure do |config|
-  config.environment = "development"
-  config.token = ENV['ROSPATENT_DEV_TOKEN']
-  config.log_level = :debug
-  config.log_requests = true
-  config.log_responses = true
-  config.cache_ttl = 60          # Short cache for development
-  config.timeout = 10            # Fast timeouts for quick feedback
-end
-```
-
-### Staging Environment
-
-```ruby
-# Optimized for staging
-Rospatent.configure do |config|
-  config.environment = "staging"
-  config.token = ENV['ROSPATENT_TOKEN']
-  config.log_level = :info
-  config.cache_ttl = 300         # Longer cache for performance
-  config.timeout = 45            # Longer timeouts for reliability
-  config.retry_count = 3         # More retries for resilience
-end
-```
-
-### Production Environment
-
-```ruby
-# Optimized for production
-Rospatent.configure do |config|
-  config.environment = "production"
-  config.token = ENV['ROSPATENT_TOKEN']
-  config.log_level = :warn
-  config.cache_ttl = 600         # Longer cache for performance
-  config.timeout = 60            # Longer timeouts for reliability
-  config.retry_count = 5         # More retries for resilience
-end
-```
-
-### Configuration Validation
-
-```ruby
-# Validate current configuration
-errors = Rospatent.validate_configuration
-if errors.any?
-  puts "Configuration errors:"
-  errors.each { |error| puts "  - #{error}" }
-else
-  puts "Configuration is valid ✓"
-end
-```
-
 ## Rails Integration
 
 ### Generator
@@ -494,10 +758,23 @@ This creates `config/initializers/rospatent.rb`:
 
 ```ruby
 Rospatent.configure do |config|
-  config.token = Rails.application.credentials.rospatent_token
-  config.environment = Rails.env
+  # Token priority: Rails credentials > ROSPATENT_TOKEN > ROSPATENT_API_TOKEN
+  config.token = Rails.application.credentials.rospatent_token || 
+                 ENV["ROSPATENT_TOKEN"] || 
+                 ENV["ROSPATENT_API_TOKEN"]
+  
+  # Environment configuration respects ROSPATENT_ENV
+  config.environment = ENV.fetch("ROSPATENT_ENV", Rails.env)
+  
+  # CRITICAL: Environment variables take priority over Rails defaults
+  # This prevents DEBUG logs appearing in production if ROSPATENT_LOG_LEVEL=debug is set
+  config.log_level = if ENV.key?("ROSPATENT_LOG_LEVEL")
+                       ENV["ROSPATENT_LOG_LEVEL"].to_sym
+                     else
+                       Rails.env.production? ? :warn : :debug
+                     end
+  
   config.cache_enabled = Rails.env.production?
-  config.log_level = Rails.env.production? ? :warn : :debug
 end
 ```
 
@@ -617,6 +894,7 @@ The library uses **Faraday** as the HTTP client with redirect support for all en
 
 ⚠️ **Minor server-side limitations**:
 - **Similar Patents by Text**: Occasionally returns `503 Service Unavailable` (a server-side issue, not a client implementation issue)
+
 ⚠️ **Documentation inconsistencies**:
 - **Similar Patents**: According to the documentation, the array of hits is named `hits`, but the real implementation uses the name `data`
 - **Available Datasets**: The `name` key in the real implementation has the localization suffix — `name_ru`, `name_en`
@@ -681,10 +959,7 @@ $ bundle exec rake cache:clear
 $ bundle exec rake doc
 
 # Run integration tests
-$ bundle exec rake test_integration
-
-# Performance benchmarks
-$ bundle exec rake benchmark
+$ ROSPATENT_INTEGRATION_TESTS=true ROSPATENT_TEST_TOKEN='<your_jwt_token>' bundle exec rake test_integration
 
 # Setup development environment
 $ bundle exec rake setup
@@ -826,12 +1101,10 @@ $ bundle exec rake release
 - 📊 **Структурированное логирование** - JSON/текстовое логирование с отслеживанием запросов/ответов
 - 🚀 **Пакетные операции** - параллельная обработка множества патентов
 - ⚙️ **Адаптивные окружения** - различные конфигурации для development/staging/production
-- 🧪 **Комплексное тестирование** - 96% покрытие тестами с интеграционными тестами
+- 🧪 **Комплексное тестирование** - 219 тестов с 465 проверками, комплексное интеграционное тестирование
 - 📚 **Отличная документация** - подробные примеры и документация API
 
-## Быстрый старт
-
-### Установка
+## Установка
 
 Добавьте в ваш Gemfile:
 
@@ -839,70 +1112,497 @@ $ bundle exec rake release
 gem 'rospatent'
 ```
 
+Затем выполните:
+
+```bash
+$ bundle install
+```
 Или установите напрямую:
 
 ```bash
 $ gem install rospatent
 ```
 
-### Базовая настройка
+## Быстрый старт
 
 ```ruby
-require 'rospatent'
-
-# Настройка клиента
+# Минимальная конфигурация
 Rospatent.configure do |config|
   config.token = "ваш_jwt_токен"
 end
 
-# Создание клиента
+# Создание клиента и поиск
 client = Rospatent.client
+results = client.search(q: "ракета", limit: 10)
+
+puts "Найдено #{results.total} результатов"
+results.hits.each do |hit|
+  puts "Патент: #{hit['id']} - #{hit.dig('biblio', 'ru', 'title')}"
+end
 ```
 
-## Основное использование
+## Конфигурация
 
-### Поиск патентов
+### Базовая настройка
 
 ```ruby
-# Простой поиск
-results = client.search(q: "солнечная батарея")
+Rospatent.configure do |config|
+  # Обязательно
+  config.token = "ваш_jwt_токен"
 
-# Расширенный поиск с фильтрами
-results = client.search(
-  q: "искусственный интеллект",
-  limit: 50,
-  offset: 100,
-  datasets: ["ru_since_1994"],
-  sort: "pub_date:desc",
-  highlight: true
-)
+  # Настройки API
+  config.api_url = "https://searchplatform.rospatent.gov.ru/patsearch/v0.2"
+  config.timeout = 30
+  config.retry_count = 3
 
-# Обработка результатов
-puts "Найдено: #{results.total} патентов"
-results.hits.each do |patent|
-  puts "#{patent['id']}: #{patent['title']}"
+  # Окружение (development, staging, production)
+  config.environment = "production"
 end
 ```
 
-### Получение документов патентов
+### Продвинутая настройка
 
 ```ruby
-# По идентификатору документа
-patent = client.patent("RU134694U1_20131120")
+Rospatent.configure do |config|
+  config.token = "ваш_jwt_токен"
 
-# Парсинг содержимого
-abstract = client.parse_abstract(patent)
-description = client.parse_description(patent, format: :text)
+  # Кеширование (включено по умолчанию)
+  config.cache_enabled = true
+  config.cache_ttl = 300              # 5 минут
+  config.cache_max_size = 1000        # Максимум элементов кеша
 
-puts "Реферат: #{abstract}"
-puts "Описание: #{description}"
-```
+  # Логирование
+  config.log_level = :info             # :debug, :info, :warn, :error
+  config.log_requests = true           # Логировать API запросы
+  config.log_responses = true          # Логировать API ответы
 
-### Поиск похожих патентов
+  # Настройки соединения
+  config.connection_pool_size = 5
+  config.connection_keep_alive = true
 
-```ruby
-# Поиск похожих патентов по ID
-similar = client.similar_patents_by_id("RU134694U1_20131120", count: 50)
+  # Управление токенами
+  config.token_expires_at = Time.now + 3600
+  config.token_refresh_callback = -> { refresh_token! }
+end
+```
+
+### Конфигурация для конкретных окружений
+
+Gem автоматически настраивается под окружение с разумными значениями по умолчанию:
+
+#### Окружение разработки
+
+```ruby
+# Оптимизировано для разработки
+Rospatent.configure do |config|
+  config.environment = "development"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :debug
+  config.log_requests = true
+  config.log_responses = true
+  config.cache_ttl = 60          # Короткий кеш для разработки
+  config.timeout = 10            # Быстрые таймауты для быстрой обратной связи
+end
+```
+
+#### Окружение Staging
+
+```ruby
+# Оптимизировано для staging
+Rospatent.configure do |config|
+  config.environment = "staging"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :info
+  config.cache_ttl = 300         # Более длительный кеш для производительности
+  config.timeout = 45            # Более длительные таймауты для надежности
+  config.retry_count = 3         # Больше повторов для устойчивости
+end
+```
+
+#### Продакшн окружение
+
+```ruby
+# Оптимизировано для продакшна
+Rospatent.configure do |config|
+  config.environment = "production"
+  config.token = ENV['ROSPATENT_TOKEN']
+  config.log_level = :warn
+  config.cache_ttl = 600         # Более длительный кеш для производительности
+  config.timeout = 60            # Более длительные таймауты для надежности
+  config.retry_count = 5         # Больше повторов для устойчивости
+end
+```
+
+### Переменные окружения и интеграция с Rails
+
+⚠️ **КРИТИЧНО**: Понимание приоритета переменных окружения необходимо для избежания проблем конфигурации, особенно в Rails приложениях.
+
+#### Приоритет конфигурации токена
+
+1. **Rails credentials**: `Rails.application.credentials.rospatent_token`
+2. **Основная переменная окружения**: `ROSPATENT_TOKEN`
+3. **Устаревшая переменная окружения**: `ROSPATENT_API_TOKEN`
+
+```bash
+# Рекомендуемый подход
+export ROSPATENT_TOKEN="your_jwt_token"
+
+# Поддержка устаревшего формата (все еще работает)
+export ROSPATENT_API_TOKEN="your_jwt_token"
+```
+
+#### Приоритет конфигурации уровня логирования
+
+```ruby
+# Переменная окружения имеет приоритет над настройками Rails по умолчанию
+config.log_level = if ENV.key?("ROSPATENT_LOG_LEVEL")
+                     ENV["ROSPATENT_LOG_LEVEL"].to_sym
+                   else
+                     Rails.env.production? ? :warn : :debug
+                   end
+```
+
+⚠️ **Частая проблема**: Установка `ROSPATENT_LOG_LEVEL=debug` в продакшне переопределит логику Rails и приведёт к появлению DEBUG логов в продакшне!
+
+#### Полный справочник переменных окружения
+
+```bash
+# Основная конфигурация
+ROSPATENT_TOKEN="your_jwt_token"           # Токен аутентификации API
+ROSPATENT_ENV="production"                 # Переопределить Rails.env при необходимости
+ROSPATENT_API_URL="custom_url"            # Переопределить URL API по умолчанию
+
+# Конфигурация логирования
+ROSPATENT_LOG_LEVEL="warn"                # debug, info, warn, error
+ROSPATENT_LOG_REQUESTS="false"            # Логировать API запросы
+ROSPATENT_LOG_RESPONSES="false"           # Логировать API ответы
+
+# Конфигурация кеша
+ROSPATENT_CACHE_ENABLED="true"            # Включить/отключить кеширование
+ROSPATENT_CACHE_TTL="300"                 # TTL кеша в секундах
+ROSPATENT_CACHE_MAX_SIZE="1000"           # Максимальное количество элементов кеша
+
+# Конфигурация соединения
+ROSPATENT_TIMEOUT="30"                    # Таймаут запроса в секундах
+ROSPATENT_RETRY_COUNT="3"                 # Количество повторов
+ROSPATENT_POOL_SIZE="5"                   # Размер пула соединений
+ROSPATENT_KEEP_ALIVE="true"               # Keep-alive соединения
+
+# Переопределения для конкретных окружений
+ROSPATENT_DEV_API_URL="dev_url"           # URL API для разработки
+ROSPATENT_STAGING_API_URL="staging_url"   # URL API для staging
+```
+
+#### Лучшие практики для Rails
+
+1. **Используйте Rails credentials для токенов**:
+   ```bash
+   rails credentials:edit
+   # Добавьте: rospatent_token: your_jwt_token
+   ```
+
+2. **Установите переменные для конкретных окружений**:
+   ```bash
+   # config/environments/production.rb
+   ENV["ROSPATENT_LOG_LEVEL"] ||= "warn"
+   ENV["ROSPATENT_CACHE_ENABLED"] ||= "true"
+   ```
+
+3. **Избегайте установки DEBUG уровня в продакшне**:
+   ```bash
+   # ❌ НЕ ДЕЛАЙТЕ ТАК в продакшне
+   export ROSPATENT_LOG_LEVEL=debug
+   
+   # ✅ ДЕЛАЙТЕ ТАК
+   export ROSPATENT_LOG_LEVEL=warn
+   ```
+
+### Валидация конфигурации
+
+```ruby
+# Валидация текущей конфигурации
+errors = Rospatent.validate_configuration
+if errors.any?
+  puts "Ошибки конфигурации:"
+  errors.each { |error| puts "  - #{error}" }
+else
+  puts "Конфигурация действительна ✓"
+end
+```
+
+## Основное использование
+
+### Поиск патентов
+
+```ruby
+# Простой поиск
+results = client.search(q: "солнечная батарея")
+
+# Поиск на естественном языке
+results = client.search(qn: "конструкция ракетного двигателя")
+
+# Расширенный поиск с всеми опциями
+results = client.search(
+  q: "искусственный интеллект AND нейронная сеть",
+  limit: 50,
+  offset: 100,
+  datasets: ["ru_since_1994"],
+  filter: {
+    "classification.ipc_group": { "values": ["G06N"] },
+    "application.filing_date": { "range": { "gte": "20200101" } }
+  },
+  sort: "publication_date:desc", # то же самое, что 'sort: :pub_date'; см. варианты параметров сортировки в Search#validate_sort_parameter
+  group_by: "family:dwpi",       # Группировка по семействам: "family:docdb" или "family:dwpi"
+  include_facets: true,
+  pre_tag: "<mark>",             # Оба тега должны быть указаны вместе
+  post_tag: "</mark>",           # Могут быть строками или массивами
+  highlight: {                   # Продвинутая настройка подсветки (независимо от тегов)
+    "profiles" => [
+      { "q" => "нейронная сеть", "pre_tag" => "<b>", "post_tag" => "</b>" },
+      "_searchquery_"
+    ]
+  }
+)
+
+# Простая подсветка с тегами (оба тега обязательны)
+results = client.search(
+  q: "ракета",
+  pre_tag: "<mark>",
+  post_tag: "</mark>"
+)
+
+# Многоцветная подсветка с массивами
+results = client.search(
+  q: "космическая ракета", 
+  pre_tag: ["<b>", "<i>"],     # Циклическая подсветка
+  post_tag: ["</b>", "</i>"]   # разными тегами
+)
+
+# Продвинутая подсветка с использованием профилей (независимо от pre_tag/post_tag)
+results = client.search(
+  q: "ракета",
+  highlight: {
+    "profiles" => [
+      { "q" => "космическая", "pre_tag" => "<b>", "post_tag" => "</b>" },
+      "_searchquery_"  # Ссылка на параметры подсветки основного поискового запроса
+    ]
+  }
+)
+
+# Группировка по семействам патентов (группирует патенты одного изобретения)
+results = client.search(
+  q: "ракета",
+  group_by: "family:docdb",    # Простые семейства патентов DOCDB
+  datasets: ["dwpi"],
+  limit: 10
+)
+
+results = client.search(
+  q: "ракета",
+  group_by: "family:dwpi",     # Простые семейства патентов DWPI
+  datasets: ["dwpi"],
+  limit: 10
+)
+
+# Обработка результатов
+puts "Найдено: #{results.total} патентов (доступно #{results.available})"
+puts "Показано: #{results.count}"
+
+results.hits.each do |hit|
+  puts "ID: #{hit['id']}"
+  puts "Название: #{hit.dig('biblio', 'ru', 'title')}"
+  puts "Дата: #{hit.dig('common', 'publication_date')}"
+  puts "МПК: #{hit.dig('common', 'classification', 'ipc')&.map {|c| c['fullname']}&.join('; ')}"
+  puts "---"
+end
+```
+
+### Расширенные параметры фильтрации
+
+Параметр `filter` поддерживает сложную фильтрацию с автоматической валидацией и преобразованием форматов:
+
+#### Списочные фильтры (требуют формат `{"values": [...]}`)
+
+```ruby
+# Фильтры по классификации
+results = client.search(
+  q: "искусственный интеллект",
+  filter: {
+    "classification.ipc_group": { "values": ["G06N", "G06F"] },
+    "classification.cpc_group": { "values": ["G06N3/", "G06N20/"] }
+  }
+)
+
+# Фильтры по авторам и патентообладателям
+results = client.search(
+  q: "изобретение",
+  filter: {
+    "authors": { "values": ["Иванов И.И.", "Петров П.П."] },
+    "patent_holders": { "values": ["ООО Компания"] },
+    "country": { "values": ["RU", "US"] },
+    "kind": { "values": ["A1", "U1"] }
+  }
+)
+
+# Фильтры по ID документов
+results = client.search(
+  q: "устройство",
+  filter: {
+    "ids": { "values": ["RU134694U1_20131120", "RU2358138C1_20090610"] }
+  }
+)
+```
+
+#### Диапазонные фильтры по датам (требуют формат `{"range": {"operator": "YYYYMMDD"}}`)
+
+```ruby
+# Автоматическое преобразование формата дат
+results = client.search(
+  q: "инновация",
+  filter: {
+    "date_published": { "range": { "gte": "2020-01-01", "lte": "2023-12-31" } },
+    "application.filing_date": { "range": { "gte": "2019-06-15" } }
+  }
+)
+
+# Прямой формат API (YYYYMMDD)
+results = client.search(
+  q: "технология",
+  filter: {
+    "date_published": { "range": { "gte": "20200101", "lt": "20240101" } }
+  }
+)
+
+# Использование объектов Date (автоматически конвертируются)
+results = client.search(
+  q: "патент",
+  filter: {
+    "application.filing_date": { 
+      "range": { 
+        "gte": Date.new(2020, 1, 1),
+        "lte": Date.new(2023, 12, 31) 
+      } 
+    }
+  }
+)
+```
+
+**Поддерживаемые операторы дат**: `gt`, `gte`, `lt`, `lte`
+
+**Преобразование формата дат**:
+- `"2020-01-01"` → `"20200101"`
+- `Date.new(2020, 1, 1)` → `"20200101"`
+- `"20200101"` → `"20200101"` (без изменений)
+
+#### Сложные составные фильтры
+
+```ruby
+# Комплексный пример фильтра
+results = client.search(
+  q: "машинное обучение",
+  filter: {
+    # Списочные фильтры
+    "classification.ipc_group": { "values": ["G06N", "G06F"] },
+    "country": { "values": ["RU", "US", "CN"] },
+    "kind": { "values": ["A1", "A2"] },
+    "authors": { "values": ["Иванов И.И."] },
+    
+    # Диапазонные фильтры по датам
+    "date_published": { "range": { "gte": "2020-01-01", "lte": "2023-12-31" } },
+    "application.filing_date": { "range": { "gte": "2019-01-01" } }
+  },
+  limit: 50
+)
+```
+
+**Поддерживаемые поля фильтров**:
+
+*Списочные фильтры (требуют формат `{"values": [...]}`)::*
+- `authors` - Авторы патентов
+- `patent_holders` - Патентообладатели/правопреемники
+- `country` - Коды стран
+- `kind` - Типы документов
+- `ids` - Конкретные ID документов
+- `classification.ipc*` - Коды классификации IPC
+- `classification.cpc*` - Коды классификации CPC
+
+*Фильтры по датам (требуют формат `{"range": {"operator": "YYYYMMDD"}}`)::*
+- `date_published` - Дата публикации
+- `application.filing_date` - Дата подачи заявки
+
+**Валидация фильтров**:
+- ✅ Автоматическая валидация названий полей
+- ✅ Валидация структуры (списочный vs диапазонный формат)
+- ✅ Преобразование и валидация формата дат
+- ✅ Валидация операторов для диапазонов
+- ✅ Полезные сообщения об ошибках для неверных фильтров
+
+```ruby
+# Эти примеры вызовут ValidationError с конкретными сообщениями:
+client.search(
+  q: "тест",
+  filter: { "invalid_field": { "values": ["тест"] } }
+)
+# Ошибка: "Invalid filter field: invalid_field"
+
+client.search(
+  q: "тест", 
+  filter: { "authors": ["прямой", "массив"] }  # Отсутствует обертка {"values": [...]}
+)
+# Ошибка: "Filter 'authors' requires format: {\"values\": [...]}"
+
+client.search(
+  q: "тест",
+  filter: { "date_published": { "range": { "invalid_op": "20200101" } } }
+)
+# Ошибка: "Invalid range operator: invalid_op. Supported: gt, gte, lt, lte"
+```
+
+### Получение документов патентов
+
+```ruby
+# По идентификатору документа
+patent = client.patent("RU134694U1_20131120")
+
+# По компонентам идентификатора
+patent_doc = client.patent_by_components(
+  "RU",                   # country_code
+  "134694",               # number
+  "U1",                   # doc_type
+  Date.new(2013, 11, 20)  # date (String или объект Date)
+)
+
+# Доступ к данным патента
+title = patent_doc.dig('biblio', 'ru', 'title')
+abstract = patent_doc.dig('abstract', 'ru')
+inventors = patent_doc.dig('biblio', 'ru', 'inventor')
+```
+### Парсинг содержимого патента
+
+Получение чистого текста или структурированного содержимого:
+
+```ruby
+# Парсинг аннотации
+abstract_text = client.parse_abstract(patent_doc)
+abstract_html = client.parse_abstract(patent_doc, format: :html)
+abstract_ru = client.parse_abstract(patent_doc, language: "ru")
+
+# Парсинг описания
+description_text = client.parse_description(patent_doc)
+description_html = client.parse_description(patent_doc, format: :html)
+
+# Парсинг описания с разбивкой на секции
+sections = client.parse_description(patent_doc, format: :sections)
+sections.each do |section|
+  puts "Секция #{section[:number]}: #{section[:content]}"
+end
+```
+
+### Поиск похожих патентов
+
+```ruby
+# Поиск похожих патентов по ID
+similar = client.similar_patents_by_id("RU134694U1_20131120", count: 50)
 
 # Поиск похожих патентов по описанию текста
 similar = client.similar_patents_by_text(
@@ -950,12 +1650,24 @@ cpc_info = client.classification_code("cpc", code: "B63H11/00", lang: "en")
 - `"ru"` - Русский
 - `"en"` - Английский
 
+### Список доступных датасетов
+
+```ruby
+datasets = client.datasets_tree
+datasets.each do |category|
+  puts "Категория: #{category['name_ru']}"
+  category.children.each do |dataset|
+    puts "  #{dataset['id']}: #{dataset['name_ru']}"
+  end
+end
+```
+
 ### Медиафайлы и документы
 
 ```ruby
 # Скачивание PDF патента
 pdf_data = client.patent_media(
-  "National",        # collection_id
+  "National",       # collection_id
   "RU",             # country_code
   "U1",             # doc_type
   "2013/11/20",     # pub_date
@@ -970,127 +1682,291 @@ pdf_data = client.patent_media_by_id(
   "National",
   "document.pdf"
 )
-
-# Получение доступных датасетов
-datasets = client.datasets_tree
-datasets.each do |category|
-  puts "Категория: #{category['name_ru']}"
-  category.children.each do |dataset|
-    puts "  #{dataset['id']}: #{dataset['name_ru']}"
-  end
-end
 ```
 
 ## Расширенные возможности
 
 ### Пакетные операции
 
+Эффективная обработка множества патентов с параллельными запросами:
+
 ```ruby
-patent_ids = ["RU134694U1_20131120", "RU2358138C1_20090610"]
+document_ids = ["RU134694U1_20131120", "RU2358138C1_20090610", "RU2756123C1_20210927"]
 
-client.batch_patents(patent_ids) do |patent|
-  puts "Обработка: #{patent['id']}"
-  # Ваша логика обработки
+# Обработка патентов пакетами
+client.batch_patents(document_ids, batch_size: 5) do |patent_doc|
+  if patent_doc[:error]
+    puts "Ошибка для #{patent_doc[:document_id]}: #{patent_doc[:error]}"
+  else
+    puts "Получен патент: #{patent_doc['id']}"
+    # Обработка документа патента
+  end
 end
+
+# Или сбор всех результатов
+patents = []
+client.batch_patents(document_ids) { |doc| patents << doc }
 ```
 
 ### Кеширование
 
+Автоматическое интеллектуальное кеширование улучшает производительность:
+
 ```ruby
-# Конфигурация кеша
-Rospatent.configure do |config|
-  config.cache_enabled = true
-  config.cache_ttl = 600        # 10 минут
-  config.cache_max_size = 1000  # Максимум элементов
-end
+# Кеширование автоматическое и прозрачное
+patent1 = client.patent("RU134694U1_20131120")  # API вызов
+patent2 = client.patent("RU134694U1_20131120")  # Кешированный результат
 
-# Статистика кеша
+# Проверка статистики кеша
 stats = client.statistics
-puts "Попаданий в кеш: #{stats[:cache_stats][:hits]}"
+puts "Процент попаданий в кеш: #{stats[:cache_stats][:hit_rate_percent]}%"
+puts "Всего запросов: #{stats[:requests_made]}"
+puts "Среднее время ответа: #{stats[:average_request_time]}с"
+
+# Использование общего кеша между клиентами
+shared_cache = Rospatent.shared_cache
+client1 = Rospatent.client(cache: shared_cache)
+client2 = Rospatent.client(cache: shared_cache)
+
+# Ручное управление кешем
+shared_cache.clear                    # Очистить все кешированные данные
+expired_count = shared_cache.cleanup_expired  # Удалить истекшие записи
+cache_stats = shared_cache.statistics # Получить детальную статистику кеша
+```
+
+### Настройка логирования
+
+Настройка детального логирования для мониторинга и отладки:
+
+```ruby
+# Создание собственного логгера
+logger = Rospatent::Logger.new(
+  output: Rails.logger,  # Или любой объект IO
+  level: :info,
+  formatter: :json      # :json или :text
+)
+
+client = Rospatent.client(logger: logger)
+
+# Логи включают:
+# - API запросы/ответы с временными метками
+# - Операции кеша (попадания/промахи)
+# - Детали ошибок с контекстом
+# - Метрики производительности
+
+# Доступ к общему логгеру
+shared_logger = Rospatent.shared_logger(level: :debug)
 ```
 
 ### Обработка ошибок
 
+Комплексная обработка ошибок с конкретными типами ошибок и улучшенным извлечением сообщений об ошибках:
+
 ```ruby
 begin
-  results = client.search(q: "поисковый запрос")
+  patent = client.patent("INVALID_ID")
+rescue Rospatent::Errors::ValidationError => e
+  puts "Неверный ввод: #{e.message}"
+  puts "Ошибки полей: #{e.errors}" if e.errors.any?
+rescue Rospatent::Errors::NotFoundError => e
+  puts "Патент не найден: #{e.message}"
+rescue Rospatent::Errors::RateLimitError => e
+  puts "Ограничение скорости. Повторить через: #{e.retry_after} секунд"
 rescue Rospatent::Errors::AuthenticationError => e
   puts "Ошибка аутентификации: #{e.message}"
-rescue Rospatent::Errors::RateLimitError => e
-  puts "Превышен лимит запросов: #{e.message}"
 rescue Rospatent::Errors::ApiError => e
-  puts "Ошибка API: #{e.message}"
+  puts "Ошибка API (#{e.status_code}): #{e.message}"
+  puts "ID запроса: #{e.request_id}" if e.request_id
+  retry if e.retryable?
+rescue Rospatent::Errors::ConnectionError => e
+  puts "Ошибка соединения: #{e.message}"
+  puts "Исходная ошибка: #{e.original_error}"
 end
+
+# Улучшенное извлечение сообщений об ошибках
+# Клиент автоматически извлекает сообщения об ошибках из различных форматов ответов API:
+# - {"result": "Сообщение об ошибке"}     (формат API Роспатента)
+# - {"error": "Сообщение об ошибке"}      (стандартный формат)
+# - {"message": "Сообщение об ошибке"}    (альтернативный формат)
+# - {"details": "Детали валидации"}       (ошибки валидации)
 ```
 
-## Настройка окружения
+### Валидация входных данных
 
-### Разработка
+Все входные данные автоматически валидируются с полезными сообщениями об ошибках:
 
 ```ruby
-# Оптимизировано для разработки
-Rospatent.configure do |config|
-  config.environment = "development"
-  config.token = ENV['ROSPATENT_DEV_TOKEN']
-  config.log_level = :debug
-  config.log_requests = true
-  config.log_responses = true
-  config.cache_ttl = 60          # Короткий кеш для разработки
-  config.timeout = 10            # Быстрые таймауты для быстрой обратной связи
-end
+# Эти примеры вызовут ValidationError с конкретными сообщениями:
+client.search(limit: 0)                    # "Limit must be at least 1"
+client.patent("")                          # "Document_id cannot be empty"
+client.similar_patents_by_text("", count: -1)  # Множественные ошибки валидации
+
+# Валидация включает:
+# - Типы и форматы параметров
+# - Валидация формата ID патента
+# - Валидация формата даты
+# - Валидация значений перечислений
+# - Валидация обязательных полей
 ```
 
-### Staging
+### Мониторинг производительности
+
+Отслеживание производительности и статистики использования:
 
 ```ruby
-# Оптимизировано для staging
-Rospatent.configure do |config|
-  config.environment = "staging"
-  config.token = ENV['ROSPATENT_TOKEN']
-  config.log_level = :info
-  config.cache_ttl = 300         # Более длительный кеш для производительности
-  config.timeout = 45            # Более длительные таймауты для надежности
-  config.retry_count = 3         # Больше повторов для устойчивости
-end
+# Статистика конкретного клиента
+stats = client.statistics
+puts "Выполнено запросов: #{stats[:requests_made]}"
+puts "Общая продолжительность: #{stats[:total_duration_seconds]}с"
+puts "Среднее время запроса: #{stats[:average_request_time]}с"
+puts "Процент попаданий в кеш: #{stats[:cache_stats][:hit_rate_percent]}%"
+
+# Глобальная статистика
+global_stats = Rospatent.statistics
+puts "Окружение: #{global_stats[:configuration][:environment]}"
+puts "Кеш включен: #{global_stats[:configuration][:cache_enabled]}"
+puts "URL API: #{global_stats[:configuration][:api_url]}"
+```
+
+## Интеграция с Rails
+
+### Генератор
+
+```bash
+$ rails generate rospatent:install
 ```
 
-### Продакшн
+Это создает `config/initializers/rospatent.rb`:
 
 ```ruby
-# Оптимизировано для продакшна
 Rospatent.configure do |config|
-  config.environment = "production"
-  config.token = ENV['ROSPATENT_TOKEN']
-  config.log_level = :warn
-  config.cache_ttl = 600         # Более длительный кеш для производительности
-  config.timeout = 60            # Более длительные таймауты для надежности
-  config.retry_count = 5         # Больше повторов для устойчивости
+  # Приоритет токена: Rails credentials > ROSPATENT_TOKEN > ROSPATENT_API_TOKEN
+  config.token = Rails.application.credentials.rospatent_token || 
+                 ENV["ROSPATENT_TOKEN"] || 
+                 ENV["ROSPATENT_API_TOKEN"]
+  
+  # Конфигурация окружения учитывает ROSPATENT_ENV
+  config.environment = ENV.fetch("ROSPATENT_ENV", Rails.env)
+  
+  # КРИТИЧНО: Переменные окружения имеют приоритет над настройками Rails
+  # Это предотвращает появление DEBUG логов в продакшне при ROSPATENT_LOG_LEVEL=debug
+  config.log_level = if ENV.key?("ROSPATENT_LOG_LEVEL")
+                       ENV["ROSPATENT_LOG_LEVEL"].to_sym
+                     else
+                       Rails.env.production? ? :warn : :debug
+                     end
+  
+  config.cache_enabled = Rails.env.production?
 end
 ```
 
-## Интеграция с Rails
+### Использование с логгером Rails
 
 ```ruby
-# config/initializers/rospatent.rb
+# В config/initializers/rospatent.rb
 Rospatent.configure do |config|
   config.token = Rails.application.credentials.rospatent_token
-  config.environment = Rails.env
-  config.cache_enabled = Rails.env.production?
-  config.log_level = Rails.env.production? ? :warn : :debug
 end
 
-# В контроллере или сервисе
+# Создание клиента с логгером Rails
+logger = Rospatent::Logger.new(
+  output: Rails.logger,
+  level: Rails.env.production? ? :warn : :debug,
+  formatter: :text
+)
+
+# Использование в контроллерах/сервисах
 class PatentService
   def initialize
-    @client = Rospatent.client
+    @client = Rospatent.client(logger: logger)
   end
 
-  def search_patents(query, **options)
-    @client.search(q: query, **options)
+  def search_patents(query)
+    @client.search(q: query, limit: 20)
+  rescue Rospatent::Errors::ApiError => e
+    Rails.logger.error "Поиск патентов не удался: #{e.message}"
+    raise
   end
 end
 ```
 
+## Тестирование
+
+### Запуск тестов
+
+```bash
+# Запуск всех тестов
+$ bundle exec rake test
+
+# Запуск конкретного тестового файла
+$ bundle exec ruby -Itest test/unit/client_test.rb
+
+# Запуск интеграционных тестов (требуется API токен)
+$ ROSPATENT_INTEGRATION_TESTS=true ROSPATENT_TEST_TOKEN=ваш_токен bundle exec rake test_integration
+
+# Запуск с покрытием
+$ bundle exec rake coverage
+```
+
+### Настройка тестов
+
+Для тестирования сбрасывайте и настраивайте в методе setup каждого теста:
+
+```ruby
+# test/test_helper.rb - Базовая настройка для модульных тестов
+module Minitest
+  class Test
+    def setup
+      Rospatent.reset  # Чистое состояние между тестами
+      Rospatent.configure do |config|
+        config.token = ENV.fetch("ROSPATENT_TEST_TOKEN", "test_token")
+        config.environment = "development"
+        config.cache_enabled = false  # Отключить кеш для предсказуемых тестов
+        config.log_level = :error     # Уменьшить шум тестов
+      end
+    end
+  end
+end
+
+# Для интеграционных тестов - стабильная конфигурация, сброс не нужен
+class IntegrationTest < Minitest::Test
+  def setup
+    skip unless ENV["ROSPATENT_INTEGRATION_TESTS"]
+
+    @token = ENV.fetch("ROSPATENT_TEST_TOKEN", nil)
+    skip "ROSPATENT_TEST_TOKEN not set" unless @token
+
+    # Сброс не нужен - интеграционные тесты используют согласованную конфигурацию
+    Rospatent.configure do |config|
+      config.token = @token
+      config.environment = "development"
+      config.cache_enabled = true
+      config.log_level = :debug
+    end
+  end
+end
+```
+
+### Пользовательские проверки (Minitest)
+
+```ruby
+# test/test_helper.rb
+module Minitest
+  class Test
+    def assert_valid_patent_id(patent_id, message = nil)
+      message ||= "Ожидается #{patent_id} как действительный ID патента (формат: XX12345Y1_YYYYMMDD)"
+      assert patent_id.match?(/^[A-Z]{2}[A-Z0-9]+[A-Z]\d*_\d{8}$/), message
+    end
+  end
+end
+
+# Использование в тестах
+def test_patent_id_validation
+  assert_valid_patent_id("RU134694U1_20131120")
+  assert_valid_patent_id("RU134694A_20131120")
+end
+```
+
 ## Известные ограничения API
 
 Библиотека использует **Faraday** в качестве HTTP-клиента с поддержкой редиректов для всех endpoints:
@@ -1100,6 +1976,7 @@ end
 
 ⚠️ **Незначительные серверные ограничения**:
 - **Поиск похожих патентов по тексту**: Иногда возвращает `503 Service Unavailable` (проблема сервера, не клиентской реализации)
+
 ⚠️ **Неточности документации**:
 - **Поиск похожих патентов**: Массив совпадений в документации назван `hits`, фактическая реализация использует `data`
 - **Перечень датасетов**: Ключ `name` в фактической реализации содержит признак локализации — `name_ru`, `name_en` 
@@ -1148,41 +2025,29 @@ Rospatent::Errors::TimeoutError
 Rospatent::Errors::ServiceUnavailableError
 ```
 
-## Тестирование
+## Rake задачи
 
-### Запуск тестов
+Полезные задачи для разработки и обслуживания:
 
 ```bash
-# Все тесты
-$ bundle exec rake test
+# Валидация конфигурации
+$ bundle exec rake validate
 
-# Конкретный тестовый файл
-$ bundle exec ruby -Itest test/unit/client_test.rb
+# Управление кешем
+$ bundle exec rake cache:stats
+$ bundle exec rake cache:clear
 
-# Интеграционные тесты (требуется API токен)
-$ ROSPATENT_INTEGRATION_TESTS=true ROSPATENT_TEST_TOKEN=ваш_токен bundle exec rake test_integration
+# Генерация документации
+$ bundle exec rake doc
 
-# Запуск с покрытием
-$ bundle exec rake coverage
-```
+# Запуск интеграционных тестов
+$ ROSPATENT_INTEGRATION_TESTS=true ROSPATENT_TEST_TOKEN='<ваш_jwt_токен>' bundle exec rake test_integration
 
-### Настройка тестов
+# Настройка среды разработки
+$ bundle exec rake setup
 
-```ruby
-# test/test_helper.rb
-module Minitest
-  class Test
-    def setup
-      Rospatent.reset
-      Rospatent.configure do |config|
-        config.token = ENV.fetch("ROSPATENT_TEST_TOKEN", "test_token")
-        config.environment = "development"
-        config.cache_enabled = false
-        config.log_level = :error
-      end
-    end
-  end
-end
+# Проверки перед релизом
+$ bundle exec rake release_check
 ```
 
 ## Советы по производительности
@@ -1245,6 +2110,62 @@ Rospatent.configure do |config|
 end
 ```
 
+## Разработка
+
+После клонирования репозитория выполните `bin/setup` для установки зависимостей. Затем запустите `rake test` для выполнения тестов.
+
+### Настройка разработки
+
+```bash
+$ git clone https://hub.mos.ru/ad/rospatent.git
+$ cd rospatent
+$ bundle install
+$ bundle exec rake setup
+```
+
+### Запуск тестов
+
+```bash
+# Модульные тесты
+$ bundle exec rake test
+
+# Интеграционные тесты (требуется API токен)
+$ ROSPATENT_INTEGRATION_TESTS=true ROSPATENT_TEST_TOKEN=ваш_токен bundle exec rake test_integration
+
+# Стиль кода
+$ bundle exec rubocop
+
+# Все проверки
+$ bundle exec rake ci
+```
+
+### Интерактивная консоль
+
+```bash
+$ bin/console
+```
+
+## Содействие
+
+Отчеты об ошибках и pull request приветствуются на MosHub по адресу https://hub.mos.ru/ad/rospatent.
+
+### Руководство по разработке
+
+1. **Пишите тесты**: Убедитесь, что все новые функции имеют соответствующие тесты
+2. **Следуйте стилю**: Выполните `rubocop` и исправьте любые проблемы стиля
+3. **Документируйте изменения**: Обновите README и CHANGELOG
+4. **Валидируйте конфигурацию**: Запустите `rake validate` перед отправкой
+
+### Процесс релиза
+
+```bash
+# Проверки перед релизом
+$ bundle exec rake release_check
+
+# Обновление версии и релиз
+$ bundle exec rake release
+```
+
 ---
 
 ## Changelog