megaplan-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

{megaplan_sdk-0.1.0/src/megaplan_sdk.egg-info → megaplan_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: megaplan-sdk
-Version: 0.1.0
+Version: 0.2.1
 Summary: Professional Python SDK for Megaplan API v3
 Author-email: Maxim Borzov <max@borzov.com>
 License-Expression: MIT
@@ -54,6 +54,35 @@ Dynamic: license-file
 
 Библиотека полностью асинхронная, что позволяет эффективно работать с большими объемами данных и выполнять параллельные запросы. Встроенная логика повторных попыток при временных сбоях сервера делает интеграцию более надежной. Модульная архитектура позволяет легко расширять функциональность и добавлять поддержку новых модулей API.
 
+## Содержание
+
+### Основы
+- [Быстрый старт](#быстрый-старт)
+- [Авторизация](#авторизация)
+- [Helper-функции](#helper-функции)
+- [Обработка ошибок](#обработка-ошибок)
+
+### Работа с сущностями
+- [Общие паттерны](#общие-паттерны-работы-с-сущностями)
+- [Задачи](#работа-с-задачами)
+- [Проекты](#работа-с-проектами)
+- [Сделки](#работа-со-сделками)
+
+### Продвинутые возможности
+- [Кэширование сущностей](#кэширование-сущностей)
+- [Глобальные дефолтные лимиты](#глобальные-дефолтные-лимиты)
+- [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
+- [Работа с фильтрами](#работа-с-фильтрами)
+- [Настройка HTTP-клиента](#настройка-http-клиента)
+- [Работа через прокси](#работа-через-прокси)
+- [Ручное управление токенами](#ручное-управление-токенами)
+
+### Справочная информация
+- [Известные ограничения API](#известные-ограничения-api)
+- [Архитектура](#архитектура)
+- [Требования](#требования)
+- [Разработка](#разработка)
+
 ## Возможности
 
 - Полный CRUD для задач, проектов и сделок
@@ -62,6 +91,12 @@ Dynamic: license-file
 - Типобезопасность с Pydantic-моделями и полной типизацией
 - Асинхронность — поддержка async/await во всех операциях
 - Автоматические повторы при ошибках сервера (5xx)
+- Кэширование сущностей с LRU и TTL для оптимизации запросов
+- FilterBuilder для создания фильтров с fluent API
+- Параметр `expand` для автоматической подгрузки связанных сущностей
+- Метод `iterate()` для автоматической пагинации больших списков
+- Helper-функции для создания BaseEntity объектов
+- Глобальные дефолтные лимиты для комментариев и истории
 - Модульная архитектура для легкого расширения
 - Комплексные тесты с покрытием 80%+
 
@@ -163,58 +198,311 @@ deal_ref = make_deal_entity(101)
 contractor_ref = make_contractor_entity(202)
 ```
 
-## Работа с задачами
+## Обработка ошибок
 
-### Получение списка задач
+SDK предоставляет специфичные типы исключений для различных сценариев ошибок:
 
 ```python
-tasks = await client.tasks.list(
-    filter=None,              # TaskFilter: ID фильтра (int) или конфигурация (dict)
-    statuses=None,            # list[str]: Статусы задач для фильтрации
-    limit=None,               # int: Количество элементов на странице
-    page_after=None,          # dict: Загрузить страницу, начиная с этой сущности
-    page_before=None,         # dict: Загрузить страницу строго до этой сущности
-    page_with=None,           # dict: Загрузить страницу с наличием этой сущности
-    fields=None,              # any: Набор дополнительных полей
-    sort_by=None,             # list[dict]: Массив полей сортировки
-    only_requested_fields=None # bool: Отдавать только перечисленные поля
+from megaplan_sdk import (
+    AuthenticationError,      # 401 - Ошибка аутентификации
+    AuthorizationError,        # 403 - Ошибка авторизации (нет прав)
+    NotFoundError,            # 404 - Ресурс не найден
+    ValidationError,          # 422 - Ошибка валидации запроса
+    RateLimitError,           # 429 - Превышен лимит запросов
+    ServerError               # 5xx - Ошибка сервера
 )
-# Возвращает: list[Task] - список объектов Task
+
+try:
+    task = await client.tasks.get(task_id=999)
+except NotFoundError:
+    print("Задача не найдена")
+except AuthenticationError:
+    print("Ошибка аутентификации")
+except ValidationError as e:
+    print(f"Ошибки валидации: {e.errors}")
+    # e.errors содержит список ошибок из API
 ```
 
-**Примеры использования:**
+## Общие паттерны работы с сущностями
+
+Большинство сущностей (задачи, проекты, сделки) поддерживают одинаковые операции CRUD и паттерны работы. В этом разделе описаны общие методы, которые применяются ко всем типам сущностей.
+
+### Базовые операции CRUD
+
+Все ресурсы поддерживают стандартные операции:
+
+#### Получение списка (`list`)
+
+```python
+# Общий формат для всех ресурсов
+entities = await client.{resource}.list(
+    limit=None,              # int: Количество элементов на странице
+    page_after=None,        # dict: Загрузить страницу, начиная с этой сущности
+    page_before=None,       # dict: Загрузить страницу строго до этой сущности
+    page_with=None,         # dict: Загрузить страницу с наличием этой сущности
+    fields=None,            # any: Набор дополнительных полей
+    sort_by=None,           # list[dict]: Массив полей сортировки
+    only_requested_fields=None  # bool: Отдавать только перечисленные поля
+)
+```
 
+**Примеры:**
 ```python
 # Получить все задачи
 tasks = await client.tasks.list()
 
-# С фильтром по статусам
-tasks = await client.tasks.list(
-    statuses=["assigned", "in_progress"],
-    limit=50
+# Получить проекты с лимитом
+projects = await client.projects.list(limit=50)
+
+# Получить сделки с пагинацией
+deals = await client.deals.list(limit=100, page_after={"contentType": "Deal", "id": 100})
+```
+
+#### Получение по ID (`get`)
+
+```python
+entity = await client.{resource}.get({resource}_id=42)
+# Возвращает: объект сущности со всеми полями
+```
+
+**Примеры:**
+```python
+task = await client.tasks.get(task_id=42)
+project = await client.projects.get(project_id=5)
+deal = await client.deals.get(deal_id=200)
+```
+
+#### Создание (`create`)
+
+```python
+entity = await client.{resource}.create({resource}_data={
+    "name": "Название",  # Обязательное поле
+    # ... другие поля
+})
+# Возвращает: созданная сущность
+```
+
+**Примеры:**
+```python
+# Простое создание задачи
+task = await client.tasks.create({"name": "Новая задача"})
+
+# Создание проекта
+project = await client.projects.create({"name": "Новый проект"})
+
+# Создание сделки (требует program)
+deal = await client.deals.create({
+    "name": "Новая сделка",
+    "program": {"contentType": "Program", "id": 10}
+})
+```
+
+#### Обновление (`update`)
+
+```python
+entity = await client.{resource}.update(
+    {resource}_id=42,
+    {resource}_data={
+        "name": "Обновленное название",
+        # ... другие поля для обновления
+    }
 )
+# Возвращает: обновленная сущность
+```
 
-# С фильтром по ID
-tasks = await client.tasks.list(filter=123)
+**Примеры:**
+```python
+task = await client.tasks.update(task_id=42, task_data={"status": "completed"})
+project = await client.projects.update(project_id=5, project_data={"name": "Новое название"})
+deal = await client.deals.update(deal_id=200, deal_data={"sum_base": 60000.0})
+```
 
-# С фильтром по конфигурации
-tasks = await client.tasks.list(filter={"status": "active"})
+#### Удаление (`delete`)
 
-# Итерация по всем задачам с автоматической пагинацией
+```python
+await client.{resource}.delete({resource}_id=42)
+# Возвращает: None
+```
+
+**Примеры:**
+```python
+await client.tasks.delete(task_id=42)
+await client.projects.delete(project_id=5)
+await client.deals.delete(deal_id=200)
+```
+
+### Пагинация
+
+SDK поддерживает несколько способов работы с большими списками:
+
+#### Ручная пагинация
+
+```python
+# Пагинация "после" определенной сущности
+entities = await client.tasks.list(
+    limit=50,
+    page_after={"contentType": "Task", "id": 100}
+)
+
+# Пагинация "до" определенной сущности
+entities = await client.tasks.list(
+    limit=50,
+    page_before={"contentType": "Task", "id": 200}
+)
+
+# Пагинация "с" определенной сущностью
+entities = await client.tasks.list(
+    limit=50,
+    page_with={"contentType": "Task", "id": 150}
+)
+```
+
+#### Автоматическая пагинация с `iterate()`
+
+Метод `iterate()` автоматически обрабатывает пагинацию и возвращает все элементы:
+
+```python
+# Итерация по всем задачам
 async for task in client.tasks.iterate(limit=100):
     print(task.name)
+
+# Итерация по всем проектам
+async for project in client.projects.iterate(limit=50):
+    print(project.name)
+
+# Итерация по всем сделкам
+async for deal in client.deals.iterate(limit=200):
+    print(deal.name)
 ```
 
-### Получение задачи по ID
+### Получение полной информации (`get_full_details`)
+
+Метод `get_full_details()` позволяет получить сущность со всеми связанными данными за один вызов. Все запросы выполняются параллельно для максимальной производительности.
 
+**Общий формат:**
 ```python
-task = await client.tasks.get(task_id=42)
-# Параметры:
-#   task_id: int - Идентификатор задачи
-# Возвращает: Task - объект задачи со всеми полями
+details = await client.{resource}.get_full_details(
+    {resource}_id=42,
+    include_comments=True,          # Загрузить комментарии
+    include_history=True,            # Загрузить историю изменений
+    comments_limit=50,               # Лимит комментариев (опционально)
+    history_limit=100                # Лимит записей истории (опционально)
+    # ... другие специфичные параметры для каждого типа
+)
+```
+
+**Примеры для разных типов:**
+
+```python
+# Задача со всеми данными
+task_details = await client.tasks.get_full_details(
+    task_id=42,
+    include_comments=True,
+    include_sub_tasks=True,
+    include_responsible_details=True
+)
+
+# Проект со всеми данными
+project_details = await client.projects.get_full_details(
+    project_id=5,
+    include_deals=True,
+    include_issues=True,
+    include_comments=True
+)
+
+# Сделка со всеми данными
+deal_details = await client.deals.get_full_details(
+    deal_id=200,
+    include_comments=True,
+    include_status_history=True,
+    include_contractor_details=True
+)
+```
+
+**Доступ к данным:**
+```python
+# Основная сущность
+print(details.task.name)      # для задач
+print(details.project.name)   # для проектов
+print(details.deal.name)      # для сделок
+
+# Связанные данные
+if details.comments:
+    for comment in details.comments:
+        print(comment.text)
+
+if details.history:
+    print(f"Записей в истории: {len(details.history)}")
+```
+
+Подробнее о специфичных параметрах для каждого типа сущностей см. в соответствующих разделах:
+- [Задачи](#работа-с-задачами)
+- [Проекты](#работа-с-проектами)
+- [Сделки](#работа-со-сделками)
+
+## Работа с задачами
+
+> **Примечание:** Базовые операции CRUD (list, get, create, update, delete) и пагинация описаны в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
+
+### Специфичные параметры для задач
+
+#### Получение списка задач с фильтрацией
+
+Метод `list()` поддерживает дополнительные параметры для задач:
+
+```python
+tasks = await client.tasks.list(
+    filter=None,              # TaskFilter: ID фильтра (int/str) или FilterBuilder объект
+    statuses=None,            # list[str]: Статусы задач для фильтрации
+    # ... остальные параметры из общих паттернов
+)
 ```
 
-**Поля объекта Task:**
+**Примеры использования фильтров:**
+
+```python
+# С фильтром по статусам
+tasks = await client.tasks.list(
+    statuses=["assigned", "in_progress"],
+    limit=50
+)
+
+# С фильтром по ID (int или str)
+tasks = await client.tasks.list(filter=123)
+tasks = await client.tasks.list(filter="incoming")
+
+# С FilterBuilder для текстового поиска (рекомендуется)
+from megaplan_sdk import TaskFilterBuilder
+
+# Простой поиск по названию
+filter_obj = TaskFilterBuilder().field("name").contains("договор").build()
+tasks = await client.tasks.list(filter=filter_obj)
+
+# Несколько условий с AND
+filter_obj = (
+    TaskFilterBuilder()
+    .field("name").contains("договор")
+    .and_()
+    .field("name").starts_with("Важный")
+    .build()
+)
+tasks = await client.tasks.list(filter=filter_obj)
+
+# Условия с OR
+filter_obj = (
+    TaskFilterBuilder()
+    .field("name").contains("договор")
+    .or_()
+    .field("name").contains("соглашение")
+    .build()
+)
+tasks = await client.tasks.list(filter=filter_obj)
+```
+
+Подробнее о работе с фильтрами см. раздел [Работа с фильтрами](#работа-с-фильтрами).
+
+### Поля модели Task
+
 - `id: int` - Идентификатор задачи
 - `name: str` - Название задачи
 - `description: str` - Описание
@@ -232,15 +520,11 @@ task = await client.tasks.get(task_id=42)
 - `created_at: str` - Дата создания
 - `updated_at: str` - Дата обновления
 
-### Создание задачи
+### Упрощенные методы создания
 
-#### Упрощенное создание (рекомендуется)
+Помимо стандартного `create()`, задачи поддерживают упрощенные методы:
 
 ```python
-# Простое создание задачи с автоматическим заполнением обязательных полей
-# Автоматически устанавливает isUrgent=False, isTemplate=False
-task = await client.tasks.create({"name": "Новая задача"})
-
 # Создание задачи с текущим пользователем как ответственным
 task = await client.tasks.create_simple(
     "Новая задача",
@@ -248,7 +532,6 @@ task = await client.tasks.create_simple(
 )
 
 # Создание задачи с указанным ответственным
-from megaplan_sdk import make_employee_entity
 task = await client.tasks.create_simple(
     "Новая задача",
     responsible_id=123
@@ -262,54 +545,7 @@ task = await client.tasks.create_in_project(
 )
 ```
 
-#### Полное создание (для продвинутых случаев)
-
-```python
-# Использование helper-функций для создания BaseEntity объектов
-from megaplan_sdk import make_employee_entity, make_project_entity, make_task_entity
-
-task = await client.tasks.create({
-    "name": "Новая задача",                    # str: Название задачи (обязательно)
-    "responsible": make_employee_entity(1),   # BaseEntity: Ответственный (helper)
-    "deadline": "2024-12-31",                 # str: Срок выполнения
-    "subject": "Описание задачи",             # str: Описание
-    "parent": make_project_entity(5),        # BaseEntity: Родительский проект (helper)
-    "priority": "high",                        # str: Приоритет
-    "isUrgent": False,                         # bool: Горящая (обязательно, но можно не указывать)
-    "isTemplate": False,                       # bool: Шаблон (обязательно, но можно не указывать)
-})
-# Возвращает: Task - созданная задача
-
-# Или вручную создавать BaseEntity
-task = await client.tasks.create({
-    "name": "Новая задача",
-    "responsible": {"contentType": "Employee", "id": 1},
-    "parent": {"contentType": "Project", "id": 5},
-})
-```
-
-### Обновление задачи
-
-```python
-task = await client.tasks.update(
-    task_id=42,                               # int: Идентификатор задачи
-    task_data={                               # dict: Данные для обновления
-        "status": "completed",
-        "actualFinish": "2024-01-15",
-        "name": "Обновленное название"
-    }
-)
-# Возвращает: Task - обновленная задача
-```
-
-### Удаление задачи
-
-```python
-await client.tasks.delete(task_id=42)
-# Параметры:
-#   task_id: int - Идентификатор задачи
-# Возвращает: None
-```
+**Примечание:** Стандартный метод `create()` также поддерживается. При создании задачи автоматически устанавливаются `isUrgent=False` и `isTemplate=False`, если они не указаны явно.
 
 ### Получение подзадач
 
@@ -335,6 +571,53 @@ actual_subtasks = await client.tasks.get_actual_sub_tasks(
 # Возвращает: list[Task] - список актуальных подзадач
 ```
 
+### Получение доступных родителей
+
+Методы для получения доступных надзадач и надпроектов (для выбора родителя при создании или перемещении задачи):
+
+```python
+# Глобальный поиск доступных родителей для новой задачи
+# Возвращает список Task и Project объектов
+parents = await client.tasks.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"{type(parent).__name__}: {parent.name}")  # "Task: ..." или "Project: ..."
+
+# Доступные родители для существующей задачи
+# Исключает саму задачу и её потомков
+parents = await client.tasks.get_available_parents_for(
+    task_id=123,
+    is_template=False,
+    limit=10,
+)
+```
+
+**Примечание:** Методы возвращают смешанный список объектов `Task` и `Project`, так как задача может быть вложена как в другую задачу, так и в проект.
+
+### Получение всех участников задачи
+
+Метод `get_all_participants()` возвращает полный список участников задачи (ответственный, соисполнители, аудиторы, владелец) в одном запросе:
+
+```python
+participants = await client.tasks.get_all_participants(
+    task_id=123,
+    limit=None,                               # int: Количество элементов
+    # ... стандартные параметры пагинации
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
+
+for participant in participants:
+    if hasattr(participant, 'display_name'):
+        print(participant.display_name())
+```
+
+**Типы участников:**
+- `Employee` — сотрудник организации
+- `ContractorHuman` — контрагент-физлицо
+- `Group` — группа участников (например, отдел)
+
 ### Получение задач на уровне дерева
 
 ```python
@@ -353,48 +636,23 @@ tasks = await client.tasks.tree_level(
 
 ### Получение полной информации о задаче
 
-Метод `get_full_details()` позволяет получить задачу со всеми связанными данными за один вызов. Все запросы выполняются параллельно для максимальной производительности.
+Метод `get_full_details()` для задач поддерживает следующие специфичные параметры:
 
 ```python
-from megaplan_sdk import MegaplanClient
-
-async with MegaplanClient(...) as client:
-    # Получить задачу со всей информацией
-    details = await client.tasks.get_full_details(
-        task_id=42,
-        include_sub_tasks=True,                    # Загрузить подзадачи
-        include_actual_sub_tasks=True,             # Загрузить актуальные подзадачи
-        include_comments=True,                     # Загрузить комментарии
-        include_history=True,                      # Загрузить историю изменений
-        include_auditors=True,                     # Загрузить список аудиторов
-        include_executors=True,                    # Загрузить соисполнителей
-        include_milestones=True,                   # Загрузить вехи
-        include_responsible_details=True,          # Загрузить полные данные ответственного
-        include_owner_details=True,                # Загрузить полные данные постановщика
-        comments_limit=50,                         # Лимит комментариев (опционально)
-        history_limit=100                          # Лимит записей истории (опционально)
-    )
-
-    # Доступ к основным данным задачи
-    print(f"Задача: {details.task.name}")
-    print(f"Статус: {details.task.status}")
-
-    # Доступ к связанным данным
-    if details.comments:
-        print(f"Комментариев: {len(details.comments)}")
-        for comment in details.comments:
-            print(f"  - {comment.text}")
-
-    if details.sub_tasks:
-        print(f"Подзадач: {len(details.sub_tasks)}")
-        for subtask in details.sub_tasks:
-            print(f"  - {subtask.name}")
-
-    if details.responsible_details:
-        print(f"Ответственный: {details.responsible_details.first_name} {details.responsible_details.last_name}")
-
-    if details.owner_details:
-        print(f"Постановщик: {details.owner_details.first_name} {details.owner_details.last_name}")
+details = await client.tasks.get_full_details(
+    task_id=42,
+    include_sub_tasks=True,              # Загрузить подзадачи
+    include_actual_sub_tasks=True,       # Загрузить актуальные подзадачи
+    include_comments=True,                # Загрузить комментарии
+    include_history=True,                 # Загрузить историю изменений
+    include_auditors=True,                # Загрузить список аудиторов
+    include_executors=True,               # Загрузить соисполнителей
+    include_milestones=True,              # Загрузить вехи
+    include_responsible_details=True,     # Загрузить полные данные ответственного
+    include_owner_details=True,           # Загрузить полные данные постановщика
+    comments_limit=50,                    # Лимит комментариев (опционально)
+    history_limit=100                    # Лимит записей истории (опционально)
+)
 ```
 
 **Поля объекта TaskFullDetails:**
@@ -405,64 +663,105 @@ async with MegaplanClient(...) as client:
 - `history: list[dict] | None` - История изменений
 - `auditors: list[dict] | None` - Аудиторы
 - `executors: list[dict] | None` - Соисполнители
-- `milestones: list[dict] | None` - Вехи
+- `milestones: list[Milestone] | None` - Вехи
 - `responsible_details: Employee | None` - Полные данные ответственного
 - `owner_details: Employee | None` - Полные данные постановщика
 
-**Примеры использования:**
+> **Примечание:** Общее описание метода `get_full_details()` и примеры использования см. в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
+
+### Работа с вехами (Milestones)
+
+Вехи можно получать и создавать для задач и проектов.
+
+#### Получение вех
 
 ```python
-# Минимальный вызов - только основная задача
-details = await client.tasks.get_full_details(task_id=42)
+# Получить вехи задачи
+milestones = await client.tasks.get_milestones(
+    task_id=123,
+    limit=50  # Опционально
+)
 
-# Задача с комментариями и историей
-details = await client.tasks.get_full_details(
-    task_id=42,
-    include_comments=True,
-    include_history=True,
-    comments_limit=20
+# Получить вехи проекта
+milestones = await client.projects.get_milestones(
+    project_id=456,
+    limit=50  # Опционально
 )
 
-# Полная информация для отчета
+# Вехи также доступны через get_full_details()
 details = await client.tasks.get_full_details(
-    task_id=42,
-    include_sub_tasks=True,
-    include_comments=True,
-    include_history=True,
-    include_auditors=True,
-    include_executors=True,
-    include_responsible_details=True,
-    include_owner_details=True
+    task_id=123,
+    include_milestones=True
 )
+if details.milestones:
+    for milestone in details.milestones:
+        print(f"{milestone.name}: {milestone.type}")
 ```
 
-## Работа с проектами
-
-### Получение списка проектов
+#### Создание вехи
 
 ```python
-projects = await client.projects.list(
-    limit=None,                               # int: Количество элементов на странице
-    page_after=None,                          # dict: Загрузить страницу, начиная с этой сущности
-    page_before=None,                         # dict: Загрузить страницу строго до этой сущности
-    page_with=None,                           # dict: Загрузить страницу с наличием этой сущности
-    fields=None,                              # any: Набор дополнительных полей
-    sort_by=None,                             # list[dict]: Массив полей сортировки
-    only_requested_fields=None                # bool: Отдавать только перечисленные поля
+from megaplan_sdk.models.milestone import Milestone
+
+# Создать веху для задачи
+milestone = await client.tasks.add_milestone(
+    task_id=123,
+    milestone_data={
+        "name": "Release 1.0",
+        "description": "Release milestone description",  # Обязательное поле
+        "type": "report",  # Обязательное: "report", "reminder", или "note"
+        "date": "2026-02-01T10:00:00Z"  # Обязательное: ISO 8601 формат
+    }
 )
-# Возвращает: list[Project] - список объектов Project
-```
 
-### Получение проекта по ID
+# Или использовать модель Milestone
+milestone = await client.tasks.add_milestone(
+    task_id=123,
+    milestone_data=Milestone(
+        name="Release 1.0",
+        description="Release milestone description",
+        type="report",
+        date="2026-02-01T10:00:00Z"
+    )
+)
 
-```python
-project = await client.projects.get(project_id=5)
-# Параметры:
-#   project_id: int - Идентификатор проекта
-# Возвращает: Project - объект проекта со всеми полями
+# Создать веху для проекта
+milestone = await client.projects.add_milestone(
+    project_id=456,
+    milestone_data={
+        "description": "Phase 1 completion",
+        "type": "reminder",
+        "date": "2026-03-15T14:00:00Z"
+    }
+)
 ```
 
-**Поля объекта Project:**
+**Обязательные поля при создании вехи:**
+- `description: str` - Описание вехи
+- `type: str` - Тип вехи: `"report"`, `"reminder"`, или `"note"`
+- `date: str | DateTime | dict` - Дата и время вехи (ISO 8601 строка или объект DateTime)
+
+**Поля модели Milestone:**
+- `id: int` - Идентификатор вехи
+- `name: str | None` - Название вехи
+- `description: str | None` - Описание
+- `completed: bool | None` - Признак завершенности
+- `type: str | None` - Тип вехи
+- `date: str | DateTime | dict | None` - Дата и время
+- `owner: BaseEntity | None` - Создатель (Employee)
+- `responsible: BaseEntity | None` - Ответственный (Employee)
+- `task: BaseEntity | None` - Связанная задача
+- `project: BaseEntity | None` - Связанный проект
+
+**Примечание:** Метод `get_milestones()` может вернуть пустой список для некоторых задач/проектов из-за ограничений API (ошибка 500). Это обрабатывается автоматически.
+
+## Работа с проектами
+
+> **Примечание:** Базовые операции CRUD (list, get, create, update, delete) описаны в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
+
+**Важно:** Проекты не поддерживают фильтрацию через API (параметр `filter` недоступен).
+
+### Поля модели Project
 - `id: int` - Идентификатор проекта
 - `name: str` - Название проекта
 - `description: str` - Описание
@@ -479,15 +778,11 @@ project = await client.projects.get(project_id=5)
 - `created_at: str` - Дата создания
 - `updated_at: str` - Дата обновления
 
-### Создание проекта
+### Упрощенные методы создания
 
-#### Упрощенное создание (рекомендуется)
+Помимо стандартного `create()`, проекты поддерживают упрощенный метод:
 
 ```python
-# Простое создание проекта с автоматическим заполнением обязательных полей
-# Автоматически устанавливает isTemplate=False
-project = await client.projects.create({"name": "Новый проект"})
-
 # Создание проекта с текущим пользователем как владельцем и ответственным
 project = await client.projects.create_simple(
     "Новый проект",
@@ -502,44 +797,7 @@ project = await client.projects.create_simple(
 )
 ```
 
-#### Полное создание (для продвинутых случаев)
-
-```python
-# Использование helper-функций
-from megaplan_sdk import make_employee_entity
-
-project = await client.projects.create({
-    "name": "Новый проект",                   # str: Название проекта (обязательно)
-    "owner": make_employee_entity(1),        # BaseEntity: Владелец (helper)
-    "responsible": make_employee_entity(2),   # BaseEntity: Ответственный (helper)
-    "deadline": "2024-12-31",                 # str: Срок выполнения
-    "description": "Описание проекта",        # str: Описание
-    "isTemplate": False,                       # bool: Шаблон (обязательно, но можно не указывать)
-})
-# Возвращает: Project - созданный проект
-```
-
-### Обновление проекта
-
-```python
-project = await client.projects.update(
-    project_id=5,                             # int: Идентификатор проекта
-    project_data={                            # dict: Данные для обновления
-        "name": "Обновленное название",
-        "status": "in_progress"
-    }
-)
-# Возвращает: Project - обновленный проект
-```
-
-### Удаление проекта
-
-```python
-await client.projects.delete(project_id=5)
-# Параметры:
-#   project_id: int - Идентификатор проекта
-# Возвращает: None
-```
+**Примечание:** При создании проекта автоматически устанавливается `isTemplate=False`, если не указано явно.
 
 ### Получение сделок проекта
 
@@ -580,54 +838,65 @@ actual_issues = await client.projects.get_actual_issues(
 # Возвращает: list[Task] - список актуальных задач проекта
 ```
 
-### Получение полной информации о проекте
+### Получение доступных родителей
 
-Метод `get_full_details()` позволяет получить проект со всеми связанными данными за один вызов. Все запросы выполняются параллельно для максимальной производительности.
+Методы для получения доступных родительских проектов (для выбора родителя при создании или перемещении проекта):
 
 ```python
-from megaplan_sdk import MegaplanClient
+# Глобальный поиск доступных родительских проектов
+parents = await client.projects.get_available_parents(
+    is_template=False,                        # bool: Фильтр по шаблонам
+    limit=10,                                 # int: Количество элементов
+)
+for parent in parents:
+    print(f"Project: {parent.name}")
 
-async with MegaplanClient(...) as client:
-    # Получить проект со всей информацией
-    details = await client.projects.get_full_details(
-        project_id=5,
-        include_deals=True,                        # Загрузить связанные сделки
-        include_issues=True,                       # Загрузить задачи проекта
-        include_actual_issues=True,                # Загрузить актуальные задачи
-        include_comments=True,                     # Загрузить комментарии
-        include_history=True,                      # Загрузить историю изменений
-        include_auditors=True,                     # Загрузить список аудиторов
-        include_executors=True,                    # Загрузить соисполнителей
-        include_milestones=True,                   # Загрузить вехи
-        include_responsible_details=True,          # Загрузить полные данные ответственного
-        include_owner_details=True,                # Загрузить полные данные владельца
-        comments_limit=50,                         # Лимит комментариев (опционально)
-        history_limit=100                          # Лимит записей истории (опционально)
-    )
+# Доступные родители для существующего проекта
+# Исключает сам проект и его потомков
+parents = await client.projects.get_available_parents_for(
+    project_id=456,
+    is_template=False,
+    limit=10,
+)
+```
 
-    # Доступ к основным данным проекта
-    print(f"Проект: {details.project.name}")
-    print(f"Статус: {details.project.status}")
+**Примечание:** В отличие от задач, проекты могут быть вложены только в другие проекты, поэтому возвращается список объектов `Project`.
 
-    # Доступ к связанным данным
-    if details.deals:
-        print(f"Сделок: {len(details.deals)}")
-        for deal in details.deals:
-            print(f"  - {deal.name}")
+### Получение всех участников проекта
 
-    if details.issues:
-        print(f"Задач: {len(details.issues)}")
-        for task in details.issues:
-            print(f"  - {task.name}")
+Метод `get_all_participants()` возвращает полный список участников проекта в одном запросе:
 
-    if details.comments:
-        print(f"Комментариев: {len(details.comments)}")
+```python
+participants = await client.projects.get_all_participants(
+    project_id=123,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee | ContractorHuman | Group]
 
-    if details.responsible_details:
-        print(f"Ответственный: {details.responsible_details.first_name} {details.responsible_details.last_name}")
+for participant in participants:
+    print(f"{type(participant).__name__}: {participant.display_name()}")
+```
 
-    if details.owner_details:
-        print(f"Владелец: {details.owner_details.first_name} {details.owner_details.last_name}")
+### Получение полной информации о проекте
+
+Метод `get_full_details()` для проектов поддерживает следующие специфичные параметры:
+
+```python
+details = await client.projects.get_full_details(
+    project_id=5,
+    include_deals=True,                    # Загрузить связанные сделки
+    include_issues=True,                    # Загрузить задачи проекта
+    include_actual_issues=True,            # Загрузить актуальные задачи
+    include_comments=True,                  # Загрузить комментарии
+    include_history=True,                   # Загрузить историю изменений
+    include_auditors=True,                  # Загрузить список аудиторов
+    include_executors=True,                 # Загрузить соисполнителей
+    include_milestones=True,                # Загрузить вехи
+    include_responsible_details=True,        # Загрузить полные данные ответственного
+    include_owner_details=True,             # Загрузить полные данные владельца
+    comments_limit=50,                      # Лимит комментариев (опционально)
+    history_limit=100                      # Лимит записей истории (опционально)
+)
 ```
 
 **Поля объекта ProjectFullDetails:**
@@ -639,66 +908,63 @@ async with MegaplanClient(...) as client:
 - `history: list[dict] | None` - История изменений
 - `auditors: list[dict] | None` - Аудиторы
 - `executors: list[dict] | None` - Соисполнители
-- `milestones: list[dict] | None` - Вехи
+- `milestones: list[Milestone] | None` - Вехи
 - `responsible_details: Employee | None` - Полные данные ответственного
 - `owner_details: Employee | None` - Полные данные владельца
 
-**Примеры использования:**
-
-```python
-# Минимальный вызов - только основной проект
-details = await client.projects.get_full_details(project_id=5)
+> **Примечание:** Общее описание метода `get_full_details()` и примеры использования см. в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
 
-# Проект со сделками и задачами
-details = await client.projects.get_full_details(
-    project_id=5,
-    include_deals=True,
-    include_issues=True
-)
+### Работа с вехами (Milestones)
 
-# Полная информация для отчета
-details = await client.projects.get_full_details(
-    project_id=5,
-    include_deals=True,
-    include_issues=True,
-    include_comments=True,
-    include_history=True,
-    include_responsible_details=True,
-    include_owner_details=True
-)
-```
+Вехи для проектов работают аналогично вехам для задач. См. раздел [Работа с вехами](#работа-с-вехами-milestones) в разделе "Работа с задачами" для подробностей.
 
 ## Работа со сделками
 
-### Получение списка сделок
+> **Примечание:** Базовые операции CRUD (list, get, create, update, delete) описаны в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
+
+### Специфичные параметры для сделок
+
+#### Получение списка сделок с фильтрацией
+
+Метод `list()` поддерживает дополнительные параметры для сделок:
 
 ```python
 deals = await client.deals.list(
-    filter=None,                              # TradeFilter: ID фильтра (int) или конфигурация (dict)
-    status=None,                              # ProgramState: Статус программы для фильтрации
-    q=None,                                   # str: Поисковый запрос
-    base_on=None,                             # BaseEntity: Базовая сущность для фильтрации
-    limit=None,                               # int: Количество элементов на странице
-    page_after=None,                           # dict: Пагинация после
-    page_before=None,                          # dict: Пагинация до
-    page_with=None,                            # dict: Пагинация с
-    fields=None,                               # any: Дополнительные поля
-    sort_by=None,                              # list[dict]: Сортировка
-    only_requested_fields=None                 # bool: Только запрошенные поля
+    filter=None,              # TradeFilter: ID фильтра (int/str) или FilterBuilder объект
+    status=None,              # ProgramState: Статус программы для фильтрации
+    base_on=None,             # BaseEntity: Базовая сущность для фильтрации
+    # ... остальные параметры из общих паттернов
 )
-# Возвращает: list[Deal] - список объектов Deal
 ```
 
-### Получение сделки по ID
+**Примеры использования фильтров:**
 
 ```python
-deal = await client.deals.get(deal_id=200)
-# Параметры:
-#   deal_id: int - Идентификатор сделки
-# Возвращает: Deal - объект сделки со всеми полями
+# С фильтром по ID
+deals = await client.deals.list(filter=123)
+deals = await client.deals.list(filter="active")
+
+# С FilterBuilder для текстового поиска (рекомендуется)
+from megaplan_sdk import TradeFilterBuilder
+
+# Простой поиск по названию
+filter_obj = TradeFilterBuilder().field("name").contains("Leader").build()
+deals = await client.deals.list(filter=filter_obj)
+
+# Несколько условий
+filter_obj = (
+    TradeFilterBuilder()
+    .field("name").contains("Leader")
+    .and_()
+    .field("name").starts_with("Важная")
+    .build()
+)
+deals = await client.deals.list(filter=filter_obj)
 ```
 
-**Поля объекта Deal:**
+Подробнее о работе с фильтрами см. раздел [Работа с фильтрами](#работа-с-фильтрами).
+
+### Поля модели Deal
 - `id: int` - Идентификатор сделки
 - `name: str` - Название сделки
 - `program: BaseEntity` - Программа (схема сделки)
@@ -706,61 +972,19 @@ deal = await client.deals.get(deal_id=200)
 - `contractor: BaseEntity` - Контрагент (ContractorCompany/ContractorHuman)
 - `responsible: BaseEntity` - Ответственный (Employee)
 - `sum_base: float` - Сумма сделки
-- `currency: BaseEntity` - Валюта
-- `deadline: str` - Срок
-- `description: str` - Описание
-- `tags: list[BaseEntity]` - Теги
-- `attaches: list[BaseEntity]` - Вложения
-- `created_at: str` - Дата создания
-- `updated_at: str` - Дата обновления
-
-### Создание сделки
-
-```python
-deal = await client.deals.create(deal_data={
-    "program": {                              # BaseEntity: Программа (обязательно)
-        "contentType": "Program",
-        "id": 10
-    },
-    "name": "Новая сделка",                   # str: Название сделки (обязательно)
-    "contractor": {                           # BaseEntity: Контрагент
-        "contentType": "ContractorCompany",
-        "id": 100
-    },
-    "responsible": {                          # BaseEntity: Ответственный
-        "contentType": "Employee",
-        "id": 1
-    },
-    "sum_base": 50000.0,                      # float: Сумма сделки
-    "deadline": "2024-12-31",                 # str: Срок
-    "description": "Описание сделки"          # str: Описание
-})
-# Возвращает: Deal - созданная сделка
-```
-
-### Обновление сделки
-
-```python
-deal = await client.deals.update(
-    deal_id=200,                              # int: Идентификатор сделки
-    deal_data={                               # dict: Данные для обновления
-        "sum_base": 60000.0,
-        "status": "active"
-    }
-)
-# Возвращает: Deal - обновленная сделка
-```
+- `currency: BaseEntity` - Валюта
+- `deadline: str` - Срок
+- `description: str` - Описание
+- `tags: list[BaseEntity]` - Теги
+- `attaches: list[BaseEntity]` - Вложения
+- `created_at: str` - Дата создания
+- `updated_at: str` - Дата обновления
 
-### Удаление сделки
+**Важно:** При создании сделки обязательно указывать поле `program` (программа/схема сделки).
 
-```python
-await client.deals.delete(deal_id=200)
-# Параметры:
-#   deal_id: int - Идентификатор сделки
-# Возвращает: None
-```
+### Специфичные методы сделок
 
-### Применение перехода (изменение статуса)
+#### Применение перехода (изменение статуса)
 
 ```python
 deal = await client.deals.apply_transition(
@@ -780,6 +1004,23 @@ deal = await client.deals.apply_trigger(
 # Возвращает: Deal - обновленная сделка
 ```
 
+### Получение всех участников сделки
+
+Метод `get_all_participants()` возвращает полный список участников сделки:
+
+```python
+participants = await client.deals.get_all_participants(
+    deal_id=200,
+    limit=None,                               # int: Количество элементов
+)
+# Возвращает: list[Employee]
+
+for employee in participants:
+    print(employee.display_name())
+```
+
+**Примечание:** В отличие от задач и проектов, сделки возвращают только сотрудников (`Employee`).
+
 ### Получение аудиторов сделки
 
 ```python
@@ -813,54 +1054,21 @@ exists = await client.deals.check_exists(deal_params={
 
 ### Получение полной информации о сделке
 
-Метод `get_full_details()` позволяет получить сделку со всеми связанными данными за один вызов. Все запросы выполняются параллельно для максимальной производительности.
+Метод `get_full_details()` для сделок поддерживает следующие специфичные параметры:
 
 ```python
-from megaplan_sdk import MegaplanClient
-
-async with MegaplanClient(...) as client:
-    # Получить сделку со всей информацией
-    details = await client.deals.get_full_details(
-        deal_id=200,
-        include_comments=True,                     # Загрузить комментарии
-        include_history=True,                      # Загрузить историю изменений
-        include_status_history=True,               # Загрузить историю статусов
-        include_auditors=True,                     # Загрузить список аудиторов
-        include_responsible_details=True,          # Загрузить полные данные ответственного
-        include_contractor_details=True,           # Загрузить полные данные контрагента
-        include_related_tasks=True,                # Загрузить связанные задачи
-        comments_limit=50,                         # Лимит комментариев (опционально)
-        history_limit=100                          # Лимит записей истории (опционально)
-    )
-
-    # Доступ к основным данным сделки
-    print(f"Сделка: {details.deal.name}")
-    print(f"Сумма: {details.deal.sum_base}")
-    print(f"Статус: {details.deal.state.name if details.deal.state else 'Не указан'}")
-
-    # Доступ к связанным данным
-    if details.comments:
-        print(f"Комментариев: {len(details.comments)}")
-        for comment in details.comments:
-            print(f"  - {comment.text}")
-
-    if details.history:
-        print(f"Записей в истории: {len(details.history)}")
-
-    if details.status_history:
-        print(f"Изменений статуса: {len(details.status_history)}")
-
-    if details.responsible_details:
-        print(f"Ответственный: {details.responsible_details.first_name} {details.responsible_details.last_name}")
-        print(f"Email: {details.responsible_details.email}")
-
-    if details.contractor_details:
-        print(f"Контрагент: {details.contractor_details.name}")
-
-    if details.related_tasks:
-        print(f"Связанных задач: {len(details.related_tasks)}")
-        for task in details.related_tasks:
-            print(f"  - {task.name}")
+details = await client.deals.get_full_details(
+    deal_id=200,
+    include_comments=True,                # Загрузить комментарии
+    include_history=True,                  # Загрузить историю изменений
+    include_status_history=True,           # Загрузить историю статусов
+    include_auditors=True,                  # Загрузить список аудиторов
+    include_responsible_details=True,      # Загрузить полные данные ответственного
+    include_contractor_details=True,       # Загрузить полные данные контрагента
+    include_related_tasks=True,            # Загрузить связанные задачи
+    comments_limit=50,                     # Лимит комментариев (опционально)
+    history_limit=100                      # Лимит записей истории (опционально)
+)
 ```
 
 **Поля объекта DealFullDetails:**
@@ -873,101 +1081,11 @@ async with MegaplanClient(...) as client:
 - `contractor_details: Contractor | None` - Полные данные контрагента
 - `related_tasks: list[Task] | None` - Связанные задачи
 
-**Примеры использования:**
-
-```python
-# Минимальный вызов - только основная сделка
-details = await client.deals.get_full_details(deal_id=200)
-
-# Сделка с комментариями и историей
-details = await client.deals.get_full_details(
-    deal_id=200,
-    include_comments=True,
-    include_history=True,
-    include_status_history=True,
-    comments_limit=20
-)
-
-# Полная информация для отчета
-details = await client.deals.get_full_details(
-    deal_id=200,
-    include_comments=True,
-    include_history=True,
-    include_status_history=True,
-    include_auditors=True,
-    include_responsible_details=True,
-    include_contractor_details=True,
-    include_related_tasks=True
-)
-
-# Только данные о людях
-details = await client.deals.get_full_details(
-    deal_id=200,
-    include_responsible_details=True,
-    include_contractor_details=True
-)
-```
-
-## Обработка ошибок
-
-SDK предоставляет специфичные типы исключений для различных сценариев ошибок:
-
-```python
-from megaplan_sdk import (
-    AuthenticationError,      # 401 - Ошибка аутентификации
-    AuthorizationError,        # 403 - Ошибка авторизации (нет прав)
-    NotFoundError,            # 404 - Ресурс не найден
-    ValidationError,          # 422 - Ошибка валидации запроса
-    RateLimitError,           # 429 - Превышен лимит запросов
-    ServerError               # 5xx - Ошибка сервера
-)
-
-try:
-    task = await client.tasks.get(task_id=999)
-except NotFoundError:
-    print("Задача не найдена")
-except AuthenticationError:
-    print("Ошибка аутентификации")
-except ValidationError as e:
-    print(f"Ошибки валидации: {e.errors}")
-    # e.errors содержит список ошибок из API
-```
-
-## Продвинутое использование
-
-### Настройка HTTP-клиента
-
-```python
-client = MegaplanClient(
-    base_url="https://my.megaplan.ru",
-    username="user@example.com",
-    password="password",
-    timeout=60.0,                             # float: Таймаут запросов в секундах (по умолчанию 30.0)
-    max_retries=5                              # int: Максимальное количество повторов при 5xx ошибках (по умолчанию 3)
-)
-```
-
-### Ручное управление токенами
-
-```python
-# Получить токен доступа
-token = await client.auth.authenticate("user@example.com", "password")
-# Возвращает: str - access_token
-
-# Обновить токен
-new_token = await client.auth.refresh_token(refresh_token="refresh_token")
-# Параметры:
-#   refresh_token: str | None - Токен обновления (опционально, используется сохраненный)
-# Возвращает: str - новый access_token
-
-# Установить токен вручную
-client.set_access_token("your_token")
+> **Примечание:** Общее описание метода `get_full_details()` и примеры использования см. в разделе [Общие паттерны работы с сущностями](#общие-паттерны-работы-с-сущностями).
 
-# Очистить токены
-client.auth.clear_tokens()
-```
+## Продвинутые возможности
 
-## Кэширование сущностей
+### Кэширование сущностей
 
 SDK автоматически кэширует справочные сущности (сотрудники, контрагенты, отделы) для уменьшения количества API запросов и повышения производительности.
 
@@ -1014,7 +1132,7 @@ if client._cache:
 - Кэш работает автоматически, не требуя изменений в коде
 - При использовании `expand` уникальные сущности загружаются параллельно
 
-## Глобальные дефолтные лимиты
+### Глобальные дефолтные лимиты
 
 SDK позволяет задать глобальные дефолтные значения для параметров `comments_limit` и `history_limit` на уровне клиента. Эти значения будут применяться ко всем вызовам `get_full_details()` для задач, проектов и сделок, если не переопределены явно.
 
@@ -1131,7 +1249,7 @@ projects_details = await client.projects.get_full_details(
 )
 ```
 
-## Автоматическая подгрузка связанных сущностей
+### Автоматическая подгрузка связанных сущностей
 
 Параметр `expand` позволяет автоматически подгружать связанные сущности (сотрудников, контрагентов, отделы) вместо получения только ID.
 
@@ -1263,7 +1381,196 @@ tasks_full = await client.tasks.list(limit=100, expand=["responsible"])
 - С expand: 2 запроса (1 список + 1 батч на 5 сотрудников)
 - **Экономия: 99 запросов (98%)**
 
-## Известные ограничения API
+### Работа с фильтрами
+
+SDK предоставляет удобный `FilterBuilder` для создания фильтров с использованием fluent API. Фильтры поддерживаются для задач (`TaskFilter`) и сделок (`TradeFilter`). **Проекты не поддерживают фильтрацию через API.**
+
+### Базовое использование
+
+```python
+from megaplan_sdk import TaskFilterBuilder, TradeFilterBuilder
+
+# Простой текстовый поиск в задачах
+filter_obj = TaskFilterBuilder().field("name").contains("договор").build()
+tasks = await client.tasks.list(filter=filter_obj)
+
+# Простой текстовый поиск в сделках
+filter_obj = TradeFilterBuilder().field("name").contains("Leader").build()
+deals = await client.deals.list(filter=filter_obj)
+```
+
+### Доступные операции для строковых полей
+
+```python
+# Поиск подстроки (рекомендуется для текстового поиска)
+filter_obj = TaskFilterBuilder().field("name").contains("договор").build()
+
+# Поиск по началу строки
+filter_obj = TaskFilterBuilder().field("name").starts_with("Важный").build()
+
+# Точное совпадение
+filter_obj = TaskFilterBuilder().field("status").equals("active").build()
+
+# Исключение подстроки
+filter_obj = TaskFilterBuilder().field("name").not_contains("архив").build()
+
+# Не равно
+filter_obj = TaskFilterBuilder().field("status").not_equals("completed").build()
+```
+
+### Комбинирование условий
+
+```python
+# Несколько условий с AND
+filter_obj = (
+    TaskFilterBuilder()
+    .field("name").contains("договор")
+    .and_()
+    .field("name").starts_with("Важный")
+    .build()
+)
+
+# Условия с OR
+filter_obj = (
+    TaskFilterBuilder()
+    .field("name").contains("договор")
+    .or_()
+    .field("name").contains("соглашение")
+    .build()
+)
+```
+
+### Использование фильтров по ID
+
+Помимо `FilterBuilder`, можно использовать сохраненные фильтры по их ID:
+
+```python
+# Фильтр по числовому ID
+tasks = await client.tasks.list(filter=123)
+
+# Фильтр по строковому ID
+tasks = await client.tasks.list(filter="incoming")
+deals = await client.deals.list(filter="active")
+```
+
+### Управление фильтрами
+
+SDK предоставляет методы для работы с сохраненными фильтрами:
+
+```python
+# Получить список всех фильтров для задач
+filters = await client.filters.list("task")
+
+# Получить конкретный фильтр
+filter_obj = await client.filters.get("task", filter_id=123)
+
+# Создать новый фильтр
+new_filter = await client.filters.create(
+    "task",
+    filter_id="my_custom_filter",
+    filter_config={
+        "config": {
+            "contentType": "FilterConfig",
+            "termGroup": {
+                "contentType": "FilterTermGroup",
+                "join": "and",
+                "terms": [
+                    {
+                        "contentType": "FilterTermString",
+                        "field": "name",
+                        "comparison": "contains",
+                        "value": "договор"
+                    }
+                ]
+            }
+        }
+    }
+)
+
+# Обновить существующий фильтр
+updated = await client.filters.update("task", filter_id=123, filter_config={...})
+
+# Экспортировать фильтр
+export_data = await client.filters.export("task", filter_id=123)
+```
+
+### Настройка HTTP-клиента
+
+```python
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    username="user@example.com",
+    password="password",
+    timeout=60.0,                             # float: Таймаут запросов в секундах (по умолчанию 30.0)
+    max_retries=5                              # int: Максимальное количество повторов при 5xx ошибках (по умолчанию 3)
+)
+```
+
+### Работа через прокси
+
+SDK поддерживает работу через HTTP/HTTPS/SOCKS5 прокси-серверы. Это полезно для корпоративных сетей, где все запросы должны проходить через прокси.
+
+```python
+# HTTP прокси с аутентификацией
+async with MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    username="user@example.com",
+    password="password",
+    proxy="http://login:pass@proxy.corp.local:8080",
+) as client:
+    tasks = await client.tasks.list()
+
+# HTTP прокси без аутентификации
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="http://proxy.corp.local:8080",
+)
+
+# HTTPS прокси
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="https://proxy.corp.local:8080",
+)
+
+# SOCKS5 прокси (требует httpx[socks])
+client = MegaplanClient(
+    base_url="https://my.megaplan.ru",
+    access_token="token",
+    proxy="socks5://user:pass@proxy.corp.local:1080",
+)
+```
+
+**Поддерживаемые форматы прокси:**
+- `http://proxy:port` - HTTP прокси без аутентификации
+- `http://user:password@proxy:port` - HTTP прокси с аутентификацией
+- `https://proxy:port` - HTTPS прокси
+- `socks5://user:password@proxy:port` - SOCKS5 прокси (требует `pip install httpx[socks]`)
+
+### Ручное управление токенами
+
+```python
+# Получить токен доступа
+token = await client.auth.authenticate("user@example.com", "password")
+# Возвращает: str - access_token
+
+# Обновить токен
+new_token = await client.auth.refresh_token(refresh_token="refresh_token")
+# Параметры:
+#   refresh_token: str | None - Токен обновления (опционально, используется сохраненный)
+# Возвращает: str - новый access_token
+
+# Установить токен вручную
+client.set_access_token("your_token")
+
+# Очистить токены
+client.auth.clear_tokens()
+```
+
+## Справочная информация
+
+### Известные ограничения API
 
 Некоторые эндпоинты Megaplan API имеют ограничения или известные проблемы:
 
@@ -1279,13 +1586,39 @@ API возвращает ошибку 500 при попытке получить
 # comments = await client.contractors.get_comments(contractor_id=123)
 
 # Вместо этого используйте комментарии в сделках контрагента
-deals = await client.deals.list(
-    base_on={"contentType": "Contractor", "id": 123}
-)
+deals = await client.contractors.get_deals(contractor_id=123)
 for deal in deals:
     comments = await client.deals.get_comments(deal.id)
 ```
 
+### Получение сделок контрагента
+
+SDK предоставляет удобный метод `get_deals()` для получения сделок контрагента:
+
+```python
+# Получить все сделки контрагента
+deals = await client.contractors.get_deals(
+    contractor_id=123,
+    limit=50  # Опционально
+)
+
+for deal in deals:
+    print(f"[{deal.id}] {deal.name}")
+    if deal.state:
+        print(f"  Статус: {deal.state}")
+```
+
+Это удобнее, чем использование `FilterBuilder`:
+
+```python
+# Альтернатива через FilterBuilder (более сложный способ)
+from megaplan_sdk import TradeFilterBuilder
+filter_obj = TradeFilterBuilder().field("contractor").equals(
+    {"contentType": "Contractor", "id": 123}
+).build()
+deals = await client.deals.list(filter=filter_obj)
+```
+
 ### Поиск сотрудников
 
 Поиск сотрудников по имени или телефону может работать некорректно и возвращать 0 результатов. Для надежного поиска используйте точный email:
@@ -1298,13 +1631,86 @@ employees = await client.employees.list(q="Иван Иванов")
 employees = await client.employees.list(q="ivan@example.com")
 
 # Или загрузите всех сотрудников и фильтруйте локально
+```
+
+### Проверка существования сделки (check_exists)
+
+Метод `check_exists()` для сделок может возвращать ошибки 500 или 422 из-за ограничений API. SDK автоматически обрабатывает эти ошибки и возвращает `False`. Для проверки существования сделки рекомендуется использовать альтернативные методы:
+
+```python
+# Может вернуть 500/422 ошибку
+# exists = await client.deals.check_exists(query="Deal name")
+
+# Альтернатива: используйте поиск через list()
+deals = await client.deals.list(q="Deal name", limit=1)
+exists = len(deals) > 0
+
+# Или используйте FilterBuilder
+from megaplan_sdk import TradeFilterBuilder
+filter_obj = TradeFilterBuilder().field("name").equals("Deal name").build()
+deals = await client.deals.list(filter=filter_obj, limit=1)
+exists = len(deals) > 0
+```
+
+**Примечание:** SDK автоматически нормализует BaseEntity объекты (конвертирует строковые ID в int), но это не решает проблему багов API.
+
+### Параметр statuses для задач
+
+Параметр `statuses` для фильтрации задач по статусам может возвращать ошибку 422 ValidationError из-за ограничений API. Рекомендуется использовать FilterBuilder для надежной фильтрации:
+
+```python
+# Может вернуть 422 ошибку
+# tasks = await client.tasks.list(statuses=["assigned", "in_progress"])
+
+# Рекомендуется: используйте FilterBuilder
+from megaplan_sdk import TaskFilterBuilder
+filter_obj = TaskFilterBuilder().field_enum("status").in_list(["assigned", "in_progress"]).build()
+tasks = await client.tasks.list(filter=filter_obj)
+```
+
+### Параметр baseOn для сделок
+
+Параметр `baseOn` для фильтрации сделок по связанной сущности может возвращать ошибку 422 ValidationError из-за ограничений API. SDK автоматически нормализует BaseEntity объекты (конвертирует строковые ID в int), но это не всегда решает проблему:
+
+```python
+# Может вернуть 422 ошибку
+# deals = await client.deals.list(base_on={"contentType": "Contractor", "id": 123})
+
+# Альтернатива: используйте FilterBuilder
+from megaplan_sdk import TradeFilterBuilder
+filter_obj = TradeFilterBuilder().field("contractor").equals({"contentType": "Contractor", "id": 123}).build()
+deals = await client.deals.list(filter=filter_obj)
+```
+
+### Пагинация контрагентов
+
+Пагинация через `page_after`, `page_before`, `page_with` для контрагентов может возвращать ошибку 422 ValidationError из-за ограничений API. SDK автоматически нормализует BaseEntity объекты, но рекомендуется использовать `limit` и ручную итерацию:
+
+```python
+# Может вернуть 422 ошибку
+# contractors = await client.contractors.list(page_after={"contentType": "Contractor", "id": 123})
+
+# Рекомендуется: используйте limit и iterate()
+async for contractor in client.contractors.iterate(limit=50):
+    # Обработка контрагента
+    pass
+```
+
+### Нормализация BaseEntity
+
+SDK автоматически нормализует BaseEntity объекты во всех параметрах:
+- Конвертирует строковые ID в int (где возможно)
+- Обеспечивает правильный формат `contentType` и `id`
+- Применяется к параметрам: `page_after`, `page_before`, `page_with`, `baseOn`, вложенным объектам в `deal` для `check_exists()`
+
+Это помогает избежать некоторых ошибок валидации, но не решает все проблемы API.
 all_employees = []
 async for emp in client.employees.iterate():
     if "Иван" in emp.first_name:
         all_employees.append(emp)
 ```
 
-## Архитектура
+### Архитектура
 
 SDK спроектирован с учетом модульности:
 
@@ -1328,13 +1734,13 @@ class MegaplanClient:
         self.new_resource = NewResource(self._http)
 ```
 
-## Требования
+### Требования
 
 - Python 3.11+
 - httpx >= 0.25.0
 - pydantic >= 2.0.0
 
-## Разработка
+### Разработка
 
 ### Установка для разработки