diff --git a/CLAUDE.md b/CLAUDE.md index 0bc005b..469f907 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,7 @@ ### Специфичные правила по кабинетам: - **`wholesale-cabinet-rules.md`** - при работе с кабинетом поставщика +- **`logist-cabinet-rules.md`** - при работе с кабинетом логистики - **`visual-design-rules.md`** - при работе с UI/UX ### Правила взаимодействия: @@ -18,6 +19,7 @@ ### Автоматическая активация: - Упоминание "поставщик", "wholesale", "/warehouse", "/supplier-orders" → читать wholesale-cabinet-rules.md +- Упоминание "логистика", "доставка", "logist", "/logistics-requests", "/routes" → читать logist-cabinet-rules.md - Упоминание "дизайн", "UI", "компонент", "стиль" → читать visual-design-rules.md ## 🚨 ЕДИНСТВЕННЫЙ ИСТОЧНИК ПРАВИЛ diff --git a/logist-cabinet-rules.md b/logist-cabinet-rules.md new file mode 100644 index 0000000..c28f727 --- /dev/null +++ b/logist-cabinet-rules.md @@ -0,0 +1,513 @@ +# ПРАВИЛА КАБИНЕТА ЛОГИСТИКИ (LOGIST) + +> ⚠️ **ВАЖНО**: Это файл с техническими деталями кабинета логистики. +> Общие бизнес-правила находятся в **[rules-complete.md](./rules-complete.md)** + +## Когда использовать этот файл: + +- Работа с компонентами `/logistics-requests`, `/routes` +- GraphQL запросы для логистики +- UI/UX специфика кабинета логистики +- Технические детали реализации доставок + +## 1. 🚚 СТРУКТУРА КАБИНЕТА ЛОГИСТИКИ + +### 1.1 Основные разделы + +**ЛОГИСТИКА (`LOGIST`)** имеет доступ к следующим разделам: + +- **Заявки** (`/logistics-requests`) - управление заявками на доставку +- **Маршруты** (`/routes`) - планирование маршрутов +- **В пути** (`/in-transit`) - отслеживание грузов +- **История** (`/delivery-history`) - архив доставок +- **Партнеры** (`/partners`) - управление контрагентами +- **Мессенджер** (`/messenger`) - связь с партнерами +- **Настройки** (`/settings`) - профиль и настройки +- **Экономика** (`/economics`) - финансовая аналитика + +### 1.2 Навигация и роутинг + +#### При входе в систему: + +```typescript +switch (user?.organization?.type) { + case 'LOGIST': + router.push('/logistics-requests') // Направляем на страницу заявок + break +} +``` + +#### Специальная логика роутинга: + +> 📖 **Бизнес-логика роутинга**: См. [rules-complete.md#4-система-ролей-и-доступов](./rules-complete.md#4--система-ролей-и-доступов) + +## 2. 🎨 UI/UX КОМПОНЕНТЫ + +### 2.1 Dashboard компоненты + +#### Основные компоненты кабинета: + +- `LogisticsRequestsDashboard` - главный компонент заявок +- `RoutesManager` - управление маршрутами +- `DeliveryTracker` - отслеживание доставок +- `LogisticsEconomicsPage` - экономическая аналитика + +#### Wrapper-компоненты: + +- `HomePageWrapper` - маршрутизация по типам организаций +- `EconomicsPageWrapper` - адаптивная экономика по кабинетам + +#### Специализированные компоненты: + +- `LogisticsRequestCard` - карточка заявки на доставку +- `RouteCard` - карточка маршрута +- `DeliveryStatusTracker` - трекер статуса доставки +- `LogisticsStats` - статистика доставок + +### 2.2 Карточка заявки на доставку + +#### Структура карточки: + +```jsx +
+
+ {/* Основная информация */} +
+

Заявка #{request.number}

+

+ {request.fromLocation} → {request.toLocation} +

+
+ + {/* Статус */} + {getStatusLabel(request.status)} +
+ + {/* Детали доставки */} +
+
+ Вес: + {request.weight} кг +
+
+ Объем: + {request.volume} м³ +
+
+
+``` + +### 2.3 Интерфейс отслеживания + +```jsx +
+
+

Статус доставки

+ В пути +
+ + {/* Прогресс доставки */} +
+
+ {deliverySteps.map((step, index) => ( +
+
+ {step.completed ? '✓' : index + 1} +
+
+

{step.label}

+

{step.time}

+
+
+ ))} +
+
+``` + +## 3. 📊 ФУНКЦИОНАЛЬНЫЕ ВОЗМОЖНОСТИ + +> 📖 **Бизнес-правила**: См. [rules-complete.md#12-кабинет-логистики](./rules-complete.md#12--кабинет-логистики) для правил workflow и процессов + +### 3.1 Основные функции логистики + +**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой + +**КЛЮЧЕВЫЕ ФУНКЦИИ**: + +- **ПОДТВЕРЖДЕНИЕ**: Возможности доставки поставок +- **ПЛАНИРОВАНИЕ**: Оптимальных маршрутов +- **УПРАВЛЕНИЕ**: Транспортом и водителями +- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути + +### 3.2 Workflow для логистики + +#### **ЭТАП 1: Получение заявки** + +1. Логистика получает уведомление о новой поставке +2. Заявка появляется в разделе "Заявки" кабинета логистики +3. Логист изучает детали поставки (объем, вес, маршрут) + +#### **ЭТАП 2: Подтверждение доставки** + +4. Логист нажимает кнопку "Одобрить" +5. Статус поставки меняется на `LOGISTICS_CONFIRMED` +6. Уведомления отправляются всем участникам + +#### **ЭТАП 3: Получение груза** + +7. Логистика приезжает к поставщику +8. Поставщик передает товар и документы +9. В системе отмечается "Груз получен" +10. Статус меняется на `IN_TRANSIT` + +#### **ЭТАП 4: Доставка** + +11. Логистика доставляет товар на фулфилмент-центр +12. В кабинете логистики нажимают "Доставлено" +13. Фулфилмент принимает товар и отмечает "Принято" + +### 3.3 Система тарификации + +**ПАРАМЕТРЫ ТАРИФИКАЦИИ**: + +- **Тариф до 1м³** - базовая стоимость для малых грузов +- **Тариф свыше 1м³** - стоимость для крупных грузов +- **Маршруты доставки** - от точки отправления до точки назначения +- **Описание услуг** - дополнительные условия доставки + +**РАСЧЕТ СТОИМОСТИ**: + +- Автоматический расчет стоимости доставки по объему груза +- Отображение примерной стоимости при создании заказа +- Учет специфики маршрута и условий доставки + +#### Пример интерфейса тарификации: + +```jsx +
+

Расчет стоимости доставки

+ +
+
+ Объем груза: + {volume} м³ +
+ +
+ Базовый тариф: + {volume <= 1 ? tariffUnder1m3 : tariffOver1m3} ₽/м³ +
+ +
+
+ Итого: + {calculateTotal(volume, tariff)} ₽ +
+
+
+
+``` + +### 3.4 Управление заявками + +**РАЗДЕЛЫ КАБИНЕТА ЛОГИСТИКИ**: + +- **НОВЫЕ ЗАЯВКИ** - поступившие заявки на доставку +- **В РАБОТЕ** - принятые к исполнению заявки +- **ВЫПОЛНЕННЫЕ** - завершенные доставки +- **ОТКЛОНЕННЫЕ** - заявки, которые не могут быть выполнены + +**ИНФОРМАЦИЯ О ЗАЯВКЕ**: + +- Детали груза (объем, вес, габариты) +- Маршрут доставки (откуда - куда) +- Срочность доставки +- Особые требования к транспортировке +- Контактная информация участников + +#### Интерфейс управления заявками: + +```jsx + + + + Новые + {newCount} + + + В работе + {inProgressCount} + + + Выполненные + + + Отклоненные + + + + +
+ {newRequests.map((request) => ( + + ))} +
+ + +``` + +## 4. 🛠️ GRAPHQL API + +### 4.1 Основные запросы (Queries) + +#### Получение заявок на доставку: + +```graphql +query GetLogisticsRequests { + logisticsRequests(where: { status: PENDING }) { + id + number + fromLocation + toLocation + weight + volume + status + supply { + id + totalAmount + organization { + name # Заказчик + } + } + } +} +``` + +#### Получение активных маршрутов: + +```graphql +query GetActiveRoutes { + routes(where: { status: ACTIVE }) { + id + name + driver { + name + phone + } + deliveries { + id + status + estimatedTime + } + } +} +``` + +#### Получение статистики: + +```graphql +query GetLogisticsStats { + logisticsStats { + totalDeliveries + activeDeliveries + completedToday + averageDeliveryTime + onTimeRate + } +} +``` + +### 4.2 Мутации (Mutations) + +#### Подтверждение доставки: + +```graphql +mutation ConfirmLogistics($supplyId: ID!) { + confirmLogistics(supplyId: $supplyId) { + success + supply { + id + status # Изменится на LOGISTICS_CONFIRMED + } + } +} +``` + +#### Обновление статуса доставки: + +```graphql +mutation UpdateDeliveryStatus($deliveryId: ID!, $status: DeliveryStatus!) { + updateDeliveryStatus(id: $deliveryId, status: $status) { + success + delivery { + id + status + updatedAt + } + } +} +``` + +#### Создание маршрута: + +```graphql +mutation CreateRoute($input: RouteInput!) { + createRoute(input: $input) { + success + route { + id + name + driver { + id + name + } + deliveries { + id + fromLocation + toLocation + } + } + } +} +``` + +### 4.3 Подписки (Subscriptions) + +```graphql +subscription DeliveryTracking($deliveryId: ID!) { + deliveryUpdates(deliveryId: $deliveryId) { + id + status + currentLocation + estimatedArrival + events { + type + timestamp + description + } + } +} +``` + +## 5. 📁 ТЕХНИЧЕСКИЕ КОМПОНЕНТЫ + +### 5.1 Расположение компонентов + +``` +src/components/ +├── logistics/ # Компоненты логистики +│ ├── logistics-requests-dashboard.tsx +│ ├── logistics-request-card.tsx +│ ├── route-manager.tsx +│ └── delivery-tracker.tsx +├── routes/ # Компоненты маршрутов +│ ├── route-card.tsx +│ ├── route-planner.tsx +│ └── driver-assignment.tsx +└── economics/ # Экономика + └── logistics-economics-page.tsx +``` + +### 5.2 Страницы (Pages) + +``` +src/app/ +├── logistics-requests/ +│ └── page.tsx # Страница заявок +├── routes/ +│ └── page.tsx # Страница маршрутов +├── in-transit/ +│ └── page.tsx # Активные доставки +└── delivery-history/ + └── page.tsx # История доставок +``` + +## 6. 🚨 ТЕХНИЧЕСКИЕ ПРАВИЛА И ОГРАНИЧЕНИЯ + +> 📖 **Workflow поставок**: См. [rules-complete.md#5-workflow-поставок](./rules-complete.md#5--workflow-поставок) для бизнес-процессов + +### 6.1 Обязательные проверки: + +- Проверка типа организации: `organization.type === 'LOGIST'` +- Валидация прав доступа на уровне GraphQL резолверов +- Проверка возможности доставки (вес, объем, расстояние) +- Контроль статусов перед изменением + +### 6.2 Правила безопасности доступа: + +#### Контроль на уровне компонентов: + +```typescript +{user?.organization?.type === "LOGIST" && ( + +)} +``` + +#### Проверки в GraphQL резолверах: + +```typescript +// Проверка что пользователь - логистика +if (context.user.organization.type !== 'LOGIST') { + throw new Error('Access denied: Logistics access required') +} + +// Проверка доступа к заявкам +const request = await prisma.logisticsRequest.findFirst({ + where: { + id: requestId, + organizationId: context.user.organizationId, + }, +}) +``` + +### 6.3 Запрещено: + +- Изменять статусы поставок минуя workflow +- Подтверждать доставки без физического получения груза +- Показывать данные других логистических компаний +- Изменять данные после завершения доставки + +### 6.4 Правила статусов доставки: + +- `LOGISTICS_CONFIRMED` → только после проверки возможности +- `IN_TRANSIT` → только после физического получения груза +- `DELIVERED` → требует подтверждения от фулфилмента + +### 6.5 Правила логистики + +**ОБЯЗАТЕЛЬНО**: + +- Своевременное подтверждение заявок +- Соблюдение сроков доставки +- Бережная транспортировка товаров +- Уведомление о статусе доставки +- Документальное оформление приема/передачи груза + +**ЗАПРЕЩЕНО**: + +- Принятие заявок без подтверждения возможности выполнения +- Нарушение сроков доставки без уведомления +- Повреждение товаров при транспортировке +- Передача груза без документального оформления +- Изменение маршрута без согласования + +**ИНТЕГРАЦИЯ С ПАРТНЕРАМИ**: + +- Логистика видит только партнеров-поставщиков и фулфилмент-центры +- Выбор логистики осуществляется из списка партнеров типа `LOGIST` +- Все взаимодействия фиксируются в системе уведомлений + +> 📖 **Критические запреты**: См. [rules-complete.md#17-критические-запреты](./rules-complete.md#17--критические-запреты) + +--- + +**Последнее обновление**: Август 2025 +**Связанные файлы**: + +- [rules-complete.md](./rules-complete.md) - Общие бизнес-правила +- [visual-design-rules.md](./visual-design-rules.md) - Визуальные правила diff --git a/rules-complete.md b/rules-complete.md index 2885dd1..9e5d565 100644 --- a/rules-complete.md +++ b/rules-complete.md @@ -113,7 +113,7 @@ | ----------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------- | | **Типы предметов** | [2](#2--типизация-предметов) | PRODUCT, CONSUMABLE, DEFECT, FINISHED_PRODUCT | | **Кабинет фулфилмента** | [11](#11--кабинет-фулфилмента-полная-документация) | Склад, Услуги, Сотрудники, 6 модулей | -| **Workflow поставок** | [5](#5--workflow-поставок) | 8 статусов, уведомления, логистика | +| **Workflow поставок** | [5](#5--workflow-поставок) | 8 статусов, уведомления, роль логистики | | **GraphQL запросы** | [18](#18--graphql-и-typescript-правила), [24](#24--технические-приложения) | Резолверы, мутации, типизация | | **Система партнерства** | [13](#13--система-партнерства-и-контрагентов) | Counterparty, WHOLESALE, заявки | | **Рынки и маркет** | [10.1](#101-разделение-понятий-рынок-vs-маркет), [18.7](#187-правила-рынков-и-маркета) | РЫНОК ≠ МАРКЕТ, Organization.market | @@ -2309,90 +2309,16 @@ type Supply { ## 12. 🚚 КАБИНЕТ ЛОГИСТИКИ -### 12.1 Основные функции логистики +> 📖 **Технические детали кабинета**: См. [logist-cabinet-rules.md](./logist-cabinet-rules.md) для компонентов, GraphQL, UI/UX и всех технических деталей реализации -**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой +**КРАТКАЯ РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой -**ОСНОВНЫЕ ФУНКЦИИ**: +**КЛЮЧЕВЫЕ ФУНКЦИИ**: -- **ПОДТВЕРЖДЕНИЕ ДОСТАВКИ**: Подтверждение возможности доставки поставок -- **ТРАНСПОРТИРОВКА**: Организация и выполнение доставки товаров -- **КОНТРОЛЬ МАРШРУТОВ**: Управление логистическими маршрутами -- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути - -### 12.2 Workflow для логистики - -#### **ЭТАП 1: Получение заявки** - -1. Логистика получает уведомление о новой поставке -2. Заявка появляется в разделе "Заявки" кабинета логистики -3. Логист изучает детали поставки (объем, вес, маршрут) - -#### **ЭТАП 2: Подтверждение доставки** - -4. Логист нажимает кнопку "Одобрить" -5. Статус поставки меняется на `LOGISTICS_CONFIRMED` -6. Уведомления отправляются всем участникам - -#### **ЭТАП 3: Забор товара** - -7. Логист приезжает к поставщику за товаром -8. Поставщик отгружает товар логисту -9. Поставщик отмечает "Отправлено" -10. Статус меняется на `SHIPPED`, затем `IN_TRANSIT` - -#### **ЭТАП 4: Доставка** - -11. Логистика доставляет товар на фулфилмент-центр -12. В кабинете логистики нажимают "Доставлено" -13. Фулфилмент принимает товар и отмечает "Принято" - -### 12.3 Система тарификации - -**ПАРАМЕТРЫ ТАРИФИКАЦИИ**: - -- **Тариф до 1м³** - базовая стоимость для малых грузов -- **Тариф свыше 1м³** - стоимость для крупных грузов -- **Маршруты доставки** - от точки отправления до точки назначения -- **Описание услуг** - дополнительные условия доставки - -**РАСЧЕТ СТОИМОСТИ**: - -- Автоматический расчет стоимости доставки по объему груза -- Отображение примерной стоимости при создании заказа -- Учет специфики маршрута и условий доставки - -### 12.4 Управление заявками - -**РАЗДЕЛЫ КАБИНЕТА ЛОГИСТИКИ**: - -- **НОВЫЕ ЗАЯВКИ** - поступившие заявки на доставку -- **В РАБОТЕ** - принятые к исполнению заявки -- **ВЫПОЛНЕННЫЕ** - завершенные доставки -- **ОТКЛОНЕННЫЕ** - заявки, которые не могут быть выполнены - -**ИНФОРМАЦИЯ О ЗАЯВКЕ**: - -- Детали груза (объем, вес, габариты) -- Маршрут доставки (откуда - куда) -- Срочность доставки -- Особые требования к транспортировке -- Контактная информация участников - -### 12.5 Правила логистики - -**ОБЯЗАТЕЛЬНО**: - -- Своевременное подтверждение заявок -- Соблюдение сроков доставки -- Бережная транспортировка товаров -- Уведомление о статусе доставки - -**ЗАПРЕЩЕНО**: - -- Принятие заявок без подтверждения возможности выполнения -- Нарушение сроков доставки без уведомления -- Повреждение товаров при транспортировке +- Подтверждение возможности доставки поставок +- Организация и выполнение доставки товаров +- Управление логистическими маршрутами +- Мониторинг грузов в пути ---