CONTEXT BLOCKS (КОНТЕКСТБЛОКИ)

# ХОРОШО:
Блок: [ORDERS_CREATE]
Зависимости:
  - [AUTH] для validate_user()
  - [DB] для orders table

# ПЛОХО:
Зависимости:
  - "весь код из AUTH"

# КЕШИРОВАНИЕ вместо полного чтения
# [AUTH] блок:
def validate_token(token: str) -> Dict[str, Any]:
    """
    Возвращает: {user_id, role, exp}
    Ошибки: TokenExpired, TokenInvalid, TokenMissing
    """
    pass

# В контекстблоке:
# Копируем сигнатуру + ошибки, НЕ весь auth.py

Контекстблок: AUTH_VALIDATE

Тип: CODE
Размер: 180 строк

Описание:
  Валидация JWT токенов пользователей.
  Проверка подписи, срока действия, прав.

Границы:
  ДЕЛАЕТ:
    - Проверить подпись JWT
    - Проверить срок действия
    - Вернуть user_id + role
  НЕ ДЕЛАЕТ:
    - Генерация токенов (это [TOKEN_CREATE])
    - Обновление токенов (это [TOKEN_REFRESH])

Вход:
  - token: str (JWT)
  - secret_key: str (из [CONFIG])

Выход:
  - success: {user_id: int, role: str, exp: int}
  - error: TokenExpired | TokenInvalid | TokenMissing

Зависимости:
  - PyJWT (библиотека)
  - [CONFIG] для SECRET_KEY
  - [DB_USER] для проверки существования пользователя

Тесты (критерии проверки):
  ✓ Валидный токен → user_id
  ✓ Истекший токен → TokenExpired
  ✓ Неверная подпись → TokenInvalid
  ✓ Отсутствует токен → TokenMissing
  ✓ Повреждённый JSON → TokenMissing
  ✓ Type check (mypy pass)

Готовность:
  - [ ] Код написан
  - [ ] Все тесты green
  - [ ] Type check mypy pass
  - [ ] Docstring заполнены
  - [ ] Интегрирован в [AUTH_MIDDLEWARE]

1. SPEC        ← Определить границы, вход/выход
   ↓
2. IMPL        ← Реализовать (код/документ/дизайн)
   ↓
3. TEST        ← Протестировать (самостоятельный тест)
   ↓
4. INTEGRATE   ← Интегрировать с другими блоками
   ↓
5. DELIVER     ← Отдать заказчику / merge в main

STATUS: pending
  → SPEC (определены границы)
  → in_progress (выполняется)
  → testing (на тестировании)
  → integrate (интеграция)
  → completed (готово)

Блок: AUTH_VALIDATE

Тип: CODE
Размер: 180 строк Python

Описание: |
  Валидация JWT токенов с проверкой подписи,
  срока действия и прав доступа.

Вход:
  - token: str (JWT)
  - secret_key: str (из конфига)

Выход:
  - success: {user_id: int, role: str, exp: int}
  - error: TokenExpired | TokenInvalid | TokenMissing

Зависимости:
  - PyJWT (externe)
  - [CONFIG] для SECRET_KEY
  - [DB_USER] для проверки пользователя

Тесты:
  ✓ Валидный токен → user_id + role
  ✓ Истекший токен → TokenExpired
  ✓ Неверная подпись → TokenInvalid
  ✓ Отсутствует токен → TokenMissing
  ✓ Повреждённый JSON → TokenMissing

Готовность:
  - [ ] Функция написана
  - [ ] Все 5 тестов green
  - [ ] mypy type check pass
  - [ ] Docstring есть
  - [ ] Интегрирована в middleware

Блок: ORDERS_SYSTEM  ← ПРОБЛЕМА

Проблема:
  - 800+ строк кода
  - Содержит: создание, обновление, удаление, список, статусы, доставку
  - Нельзя протестировать в isolation
  - Нельзя делать параллельно

Решение: Разбить на 5 блоков:

  [ORDERS_CREATE]      ← создание (180 строк)
  [ORDERS_UPDATE]      ← обновление (150 строк)
  [ORDERS_DELETE]      ← удаление (80 строк)
  [ORDERS_LIST]        ← список + фильтры (200 строк)
  [ORDERS_CANCEL]      ← отмена + статусы (150 строк)

Блок: AUTH  ← ПРОБЛЕМА

Проблема:
  - Граница не определена
  - Что входит? Токены? Сессии? Permissions?
  - Что выходит? Строка? Объект?
  - Непонятно где заканчивается AUTH и начинается MIDDLEWARE

Решение: Разбить чётко:

  [AUTH_VALIDATE]      ← валидация токена
  [AUTH_GENERATE]      ← генерация токена
  [AUTH_REFRESH]       ← обновление токена
  [AUTH_PERMISSIONS]   ← проверка прав

# ХОРОШО:
Зависимости:
  - [AUTH_VALIDATE] → функция validate_token()
  - [DB_ORDERS] → класс OrdersRepository
  - PyJWT → для JWT decode

# ПЛОХО:
Зависимости:
  - "весь код из auth.py"
  - "База данных"
  - "внешние библиотеки"

# [AUTH_VALIDATE] блок:
def validate_token(token: str) -> Dict[str, Any]:
    """
    Returns: {user_id, role, exp}
    Raises: TokenExpired, TokenInvalid, TokenMissing
    """
    pass

# [ORDERS_CREATE] блок (зависит от AUTH_VALIDATE):
# Копируем только СИГНАТУРУ + ОШИБКИ из AUTH_VALIDATE
# Не копируем весь auth.py

CACHED_VALIDATE_TOKEN = {
    'signature': 'validate_token(token: str) -> Dict',
    'returns': {'user_id': 'int', 'role': 'str', 'exp': 'int'},
    'errors': ['TokenExpired', 'TokenInvalid', 'TokenMissing']
}

# Используем в коде:
from auth import validate_token
try:
    user = validate_token(token)
except TokenExpired:
    ...

# ХОРОШО (минимум):
[ORDERS_CREATE] зависит от:
  - [AUTH_VALIDATE]    (для проверки пользователя)
  - [DB_ORDERS]        (для сохранения)
  - [NOTIFY]           (для уведомления)

# ПЛОХО (слишком много):
[ORDERS_CREATE] зависит от:
  - [AUTH_VALIDATE]
  - [AUTH_GENERATE]
  - [AUTH_REFRESH]
  - [AUTH_PERMISSIONS]
  - [DB_ORDERS]
  - [DB_USERS]
  - [DB_PRODUCTS]
  - [CACHE_ORDERS]
  - [NOTIFY_EMAIL]
  - [NOTIFY_SMS]
  - [NOTIFY_TELEGRAM]
  - [ANALYTICS]
  - [LOGGING]
  - ...

# ХОРОШО (DAG):
[AUTH_VALIDATE] ← нет зависимостей
         ↓
[ORDERS_CREATE] (зависит от AUTH)
         ↓
[ORDERS_NOTIFY] (зависит от ORDERS)

# ПЛОХО (цикл):
[AUTH] → [DB_USERS]
  ↑         ↓
  ← ← ← ← ←

# SPEC этап
- [ ] Блок имеет имя (KEB_NAME)
- [ ] Блок имеет тип (CODE / DOCS / OPS / ...)
- [ ] Границы чётко определены (что делает / что НЕ делает)
- [ ] Размер ≤ лимиту (300 строк код / 400 строк docs)
- [ ] Вход описан (параметры, данные)
- [ ] Выход описан (результат, интерфейс)
- [ ] Зависимости явные (ссылки на блоки)
- [ ] Тесты определены (критерии проверки, 3-5 тест-кейсов)
- [ ] Может быть выполнен отдельно (проверка независимости)

# IMPL + TEST этап
- [ ] Код/документ написан
- [ ] Все тесты green (если критерии = тесты)
- [ ] Type check pass (если CODE)
- [ ] Нет TODO/FIXME (если не запланировано)
- [ ] Docstring/комментарии есть
- [ ] Готов к интеграции с другими блоками

## Контекстблок: [ИМЯ]

### SPEC (определение)
- [ ] Размер ≤ 300 строк (код) или ≤ 400 строк (docs)
- [ ] Границы чёткие (что делает / что НЕ делает)
- [ ] Зависимости явно указаны (ссылки на блоки)
- [ ] Важные данные из зависимостей кешированы
- [ ] Тесты определены (3-5 критериев проверки)
- [ ] Можно выполнить независимо (без других блоков)
- [ ] Готовность измеряема (чеклист + критерии)

### IMPL (реализация)
- [ ] Код/документ написан
- [ ] Все тесты green
- [ ] Нет TODO/FIXME (или запланировано)
- [ ] Docstring/комментарии есть
- [ ] Type check pass (если CODE)

### INTEGRATE (интеграция)
- [ ] Зависимости установлены
- [ ] Интеграционные тесты pass
- [ ] Документация обновлена
- [ ] Готово к деплою

[PIM_CATEGORY_IMPORT]
  - Тип: CODE
  - Размер: 250 строк
  - Зависимости: [API_1C], [DB_PIM], [VALIDATE]
  - Тесты: 4 критерия (валидный CSV, пропуски, дубли, ошибки)

[PIM_PRODUCT_SYNC]
  - Тип: CODE
  - Размер: 280 строк
  - Зависимости: [API_OZON], [DB_PIM], [CATEGORY_IMPORT]
  - Тесты: 5 критериев (новые товары, обновления, цены, статусы, удаления)

[OZON_ORDERS_FETCH]
  - Тип: OPS
  - Размер: 80 строк (скрипт)
  - Зависимости: [API_OZON], [DB_ORDERS], [SCHEDULER]
  - Тесты: 3 критерия (успешная fetch, retry, ошибка API)

[CATALOG_ARCHITECTURE]
  - Тип: DOCS
  - Размер: 350 строк
  - Зависимости: [PROJECT.md], [API_DOCS]
  - Тесты: Документ полный, ссылки работают

[TRUCKS_CLASSIFIER]
  - Тип: CODE
  - Размер: 220 строк
  - Зависимости: [ML_MODEL], [DB_TRUCKS], [API_1C]
  - Тесты: 4 критерия (известные модели, неизвестные, ошибки, производительность)