# seed-bank.online — план платформы (v2, углублённый)

## 1. Позиционирование

Не ещё один seed-shop. **Инфраструктурный хаб** для мировой seed-индустрии: единая точка регистрации для seed banks, ботанических садов, питомников, магазинов семян, садоводов и сборщиков. Oreshka Seeds — первый зарегистрированный магазин, эталонный профиль.

## 2. Типы участников (registry entities)

| Тип | Что делает на платформе |
|---|---|
| Seed bank / генбанк | Публичный профиль, каталог хранимых видов, научное описание |
| Ботанический сад | Профиль, экспозиция видов, возможна раздача/обмен дублирующего материала |
| Питомник (nursery) | Продажа на маркетплейсе, каталог |
| Магазин семян | Продажа на маркетплейсе (Oreshka — первый) |
| Садовод / коллекционер | Обмен, раздача, покупка, личная коллекция |
| Сборщик (collector/wildcrafter) | Продажа/обмен собранного материала, происхождение обязательно |

**Важное уточнение:** не каждый User = Organization. Обычный покупатель (просто пришёл купить семена) регистрируется как индивидуальный аккаунт **без** организации — организация нужна только тем, кто продаёт, обменивает или хочет публичный профиль в директории.

## 3. Роли и права доступа

| Роль | Кто | Доступ |
|---|---|---|
| Guest | Не залогинен | Просмотр директория, маркетплейса, биржи. Покупка требует логина на этапе checkout |
| Buyer | Индивидуальный покупатель | Личный кабинет, история заказов, избранное, участие в обмене как частное лицо (без публичного профиля организации) |
| Org member | Сотрудник организации | Доступ к Vendor Panel своей организации, редактирование листингов, без прав на биллинг/удаление аккаунта |
| Org admin | Владелец/представитель организации | Полный доступ к Vendor Panel: биллинг, подписка, приглашение org member, смена контактов |
| Platform admin | Команда seed-bank.online (Max) | Модерация регистраций, верификация, управление комиссиями, доступ ко всем данным |

Реализация: Mercur/Medusa customer groups (Buyer vs Seller) + отдельная RBAC-таблица `organization_members` с ролью `member`/`admin` — стандартный Mercur seller team pattern, не писать с нуля.

## 4. Персоны и пользовательские сценарии

### 4.1 Садовод-покупатель (Buyer)
**Хочет:** купить редкие семена, надёжно, с доставкой в свою страну.
Сценарий: Guest → поиск в Маркетплейсе (фильтр по виду/зоне зимостойкости) → карточка товара → корзина (может содержать товары от разных продавцов) → регистрация/логин на checkout → раздельная оплата по продавцам (split checkout) → email-подтверждение по каждому под-заказу → трекинг доставки.

### 4.2 Коллекционер/обменник (Grower/Collector)
**Хочет:** обменять свои редкие семена на другие, без денег.
Сценарий: регистрация как Organization(grower) → создание Exchange-листинга (вид, кол-во, "хочет взамен") → другой пользователь находит листинг → контакт напрямую через Telegram/WhatsApp (MVP) → обмен происходит вне платформы → инициатор вручную отмечает листинг как `completed` → +1 к `completed_trades_count`.

### 4.3 Владелец магазина/питомника (Vendor)
**Хочет:** продавать через маркетплейс, не теряя контроль над каталогом.
Сценарий: регистрация Organization(shop/nursery) → форма заявки → **модерация platform admin** (ручная на MVP) → approved → доступ к Vendor Panel → импорт каталога (CSV/API) → настройка доставки/регионов → первая продажа → **выплата за вычетом комиссии** (см. раздел 8) на банковский счёт/Stripe-аккаунт продавца.

### 4.4 Seed bank / ботанический сад (Institutional)
**Хочет:** публичный научный профиль + возможность раздавать дублирующий материал, без коммерции.
Сценарий: регистрация Organization(seed_bank/botanic_garden) → заявка с указанием официального сайта/email на домене организации (сигнал доверия при верификации) → approved → verified badge (см. монетизацию) → публикация коллекции в директории → опционально: Exchange-листинги на раздачу дублей.

### 4.5 Модератор платформы (Platform admin, MVP = Max)
**Хочет:** не пропустить фейковые/мошеннические регистрации, держать каталог чистым.
Сценарий: новая заявка на регистрацию → попадает в **очередь модерации** (Admin Panel) → проверка (email-домен совпадает с заявленным сайтом? есть ли открытая информация об организации?) → approve/reject/request-more-info → при approve — organization становится видна в директории.

## 5. Три направления функционала

### 5.1 Маркетплейс (продажа)
- Multi-vendor: магазины/питомники продают напрямую, платформа берёт комиссию с транзакции
- Витрина = агрегация каталогов зарегистрированных продавцов (Oreshka каталог — первый импорт)
- Единые карточки товара со Schema.org Product разметкой (наследуется опыт Oreshka SEO/GEO)
- Корзина может содержать товары нескольких продавцов → на checkout заказ автоматически разбивается на под-заказы по продавцу (Mercur split-order, встроенная логика)

### 5.2 Биржа (обмен / раздача)
- P2P между садоводами и коллекционерами: seed swap, gift, trade-for-trade
- Без денег по умолчанию — репутационная система (rating, completed trades count)
- Отдельная категория для дублирующего материала ботсадов/генбанков (не для коммерции, посевной фонд)

### 5.3 Директорий (публичная база + верификация)
- Карточка организации: тип, страна, координаты, специализация, контакты, verified-badge
- Публичный поиск "seed bank near me" / "nursery in [region]" — сам по себе SEO/GEO актив (AI-краулеры любят structured directories)
- Verified-статус — платный/премиум (см. монетизацию)
- Гео-поиск: карта (map view) с точками организаций, кластеризация при масштабе "весь мир"

## 6. Data model (расширенная)

```
User
  id, email, role[buyer|org_member|org_admin|platform_admin]
  organization_id (nullable — buyer без организации = null)

Organization
  id, type[seed_bank|botanic_garden|nursery|shop|grower|collector]
  name, country, region, lat/lng, description
  verified: bool, verified_at, verification_notes
  subscription_tier
  contact_link (Telegram/WhatsApp — конвенция без телефонов)
  payout_account_id (Stripe Connect account, nullable до первой продажи)
  completed_trades_count

Listing
  id, organization_id, mode[sell|exchange|donate]
  species, variety, origin_country, quantity_available
  price (nullable для exchange/donate)
  photos[], schema-совместимые поля
  compliance_flag[none|phytosanitary_required|restricted] -- см. раздел 9
  status[draft|pending_review|active|sold_out|withdrawn]

Order (стандартная Medusa order + split по продавцам через Mercur)
  id, buyer_id, sub_orders[] (по одному на organization в корзине)
  status, total, commission_total

Payout
  id, organization_id, order_id, amount, commission_deducted, status[pending|paid|failed]

Review
  id, order_id, buyer_id, organization_id, rating[1-5], text, created_at

ModerationQueueItem
  id, organization_id, submitted_at, status[pending|approved|rejected|info_requested]
  reviewed_by (platform_admin user_id)

Notification
  id, user_id, type[order_status|new_message|listing_approved|...], read: bool

Subscription
  organization_id, tier[free|verified|pro|marketplace_seller]
  price, renews_at, stripe_subscription_id
```

## 7. Доверие и репутация

- **Verified badge** — не автоматический: platform admin проверяет email-домен организации, публичную информацию (сайт, соцсети), при необходимости — запрашивает документ
- **Review только после завершённой транзакции** (Order.status = completed) — защита от накрутки фейковых отзывов
- **Completed trades count** для Exchange — инкремент только по подтверждению **обеих сторон** в Фазе 2 (на MVP — вручную одной стороной, с пометкой "unverified" в UI, честно показываем ограничение, не выдаём за железную метрику)
- **Report/flag** кнопка на любом листинге и профиле — репорты попадают в ту же ModerationQueue, что и новые регистрации

## 8. Платежи и выплаты продавцам (multi-vendor)

- Провайдер: **Stripe Connect** (Express accounts) — стандартная интеграция для multi-vendor маркетплейсов, поддерживается плагинами Medusa/Mercur
- Флоу: покупатель платит один раз за корзину → Stripe разносит средства по под-заказам → комиссия платформы удерживается автоматически (Stripe Connect application fee) → остаток переводится на Stripe-аккаунт продавца по расписанию выплат (напр. еженедельно)
- Продавец обязан пройти Stripe onboarding (KYC уровня Stripe, не платформы — снимает с нас юридическую нагрузку по проверке личности)
- Валюта: EUR по умолчанию (согласовано с Oreshka), Stripe сам конвертирует при мультивалютных продавцах в будущем

## 9. Международная доставка и комплаенс — ВАЖНО, шире чем просто CITES

Оригинальный план флагировал только CITES-регулируемые виды. Проверка показала более широкую картину: <cite index="10-1">ввоз в ЕС растений для посадки (включая семена) из стран вне ЕС по умолчанию требует фитосанитарного сертификата, выданного национальной службой защиты растений страны-экспортёра, согласно Регламенту (EU) 2019/2072</cite>, с ограниченным списком исключений (<cite index="10-1">например, для 5 видов фруктов сертификат не требуется</cite>). Аналогично UK после Brexit — <cite index="7-1">часть товаров требует фитосанитарный сертификат при ввозе из ЕС, некоторые категории дополнительно требуют предварительного уведомления</cite>.

**Вывод: это не нишевый вопрос редких видов — это касается потенциально любой международной пересылки семян между продавцами и покупателями на маркетплейсе.** У Oreshka уже есть опыт международной доставки как у единственного продавца — но multi-vendor маркетплейс распределяет этот риск между множеством независимых продавцов из разных стран, что качественно другая ситуация с точки зрения ответственности платформы.

**Структурные меры (архитектурные, не юридическая консультация):**
- Поле `compliance_flag` на каждом листинге — продавец обязан указать, требует ли вид фитосанитарный сертификат в стране происхождения
- Возможность прикрепить скан фитосанитарного сертификата к листингу/заказу (опционально на MVP, обязательно для Фазы 2 при масштабировании в ЕС/UK продажи)
- Явные Terms of Service: **продавец несёт ответственность за законность экспорта, покупатель — за законность импорта в свою страну**, платформа — техническая инфраструктура, не сторона сделки (стандартная модель маркетплейсов)
- Предупреждение на checkout при выборе страны доставки с высокими фитосанитарными барьерами (не блокировать заказ автоматически на MVP — юридически рискованно давать точные советы без консультации)

**Это прямо в списке открытых вопросов (раздел 13) — рекомендую консультацию с юристом по международной торговле/таможенному праву до открытия регистрации сторонним продавцам за пределами Oreshka**, особенно если в маркетплейс попадут виды, регулируемые CITES или национальными карантинными списками.

## 10. Поиск и обнаружение

- Text search (Meilisearch) по названию вида, латыни, региону, организации
- Faceted-фильтры: тип организации, страна, mode (sell/exchange/donate), verified-статус
- Map view для директория: точки на карте, кластеризация при zoom-out (мировой масштаб)
- Saved search / алерты (Фаза 2): "уведоми, когда появится Nelumbo × в обмене"

## 11. Уведомления

MVP: email только (заказ создан/оплачен/отправлен, заявка на регистрацию одобрена/отклонена, новый отчёт о листинге для админа). Push/in-app — Фаза 2.

## 12. Модерация контента

- Очередь: новые регистрации организаций + репорты на существующие листинги/профили
- MVP: полностью ручная (Max как единственный platform admin), интерфейс — простой список в Admin Panel с approve/reject/request-info
- Автоматические red flags (Фаза 2): email не с корпоративного домена при заявке типа seed_bank/botanic_garden, дублирующееся название организации, подозрительно низкая цена относительно похожих листингов

## 13. Admin-панель платформы (отдельно от Vendor Panel продавцов)

- Очередь модерации (раздел 12)
- Управление комиссией по категориям/продавцам
- Общая аналитика: рост числа организаций по типам, GMV маркетплейса, активность биржи
- Ручное управление verified-статусом и subscription_tier

## 14. Монетизация

| Тариф | Кому | Что даёт | Модель |
|---|---|---|---|
| Free listing | Любая организация | Базовый профиль в директории | Бесплатно — драйвер сети |
| Verified | Seed banks, ботсады, питомники | Verified badge, приоритет в поиске | Подписка (годовая), Stripe Billing |
| Marketplace seller | Магазины, питомники | Продажа через маркетплейс | Комиссия с транзакции (%) через Stripe Connect application fee |
| Exchange | Садоводы/сборщики | Обмен/раздача | Бесплатно (сеть растёт за счёт открытого обмена) |

Логика: **директорий и обмен — бесплатные, чтобы быстро набрать критическую массу участников**. Монетизация — с продавцов на маркетплейсе (комиссия) и с organizations, которым нужен verified-статус для доверия.

## 15. MVP (Фаза 1) — что нужно для первого запуска

1. Регистрация организации (форма + **ручная** модерация platform admin)
2. Публичный директорий-профиль (карточка + поиск по типу/стране, без карты на старте)
3. Импорт каталога Oreshka как первого продавца маркетплейса
4. Базовый marketplace: листинг, split-корзина, checkout через Stripe Connect (Mercur встроенная логика)
5. Простой exchange-модуль: листинг "на обмен/в дар", контакт через мессенджер, ручная отметка `completed`
6. Email-уведомления только по критичным событиям (заказ, модерация)
7. `compliance_flag` поле на листинге (простой selector, без загрузки документов на старте)

**Осознанно НЕ в MVP:** встроенный чат, карта директория, автоматизированная модерация, аналитика продавцов, мультивалютность, push-уведомления, двусторонняя верификация обмена.

## 16. Фаза 2+ (после набора базы)

- Встроенный чат/переговоры по обмену
- Двусторонняя верификация completed trades
- API для генбанков/ботсадов на массовый импорт коллекций
- Аналитика для продавцов (просмотры, конверсия, тренды спроса)
- Мультиязычность (минимум EN/RU, дальше по спросу регионов)
- Map view директория, saved search/алерты
- Автоматизированные red-flags модерации
- Загрузка фитосанитарных документов к заказам

## 17. Data sourcing для мировой базы (холодный старт директория)

- Публичные списки: Millennium Seed Bank Partnership, BGCI (Botanic Gardens Conservation International) — открытые реестры ботсадов
- Национальные генбанки (публичные данные о существовании, не о фондах)
- Self-registration: сами seed banks/питомники/магазины подают заявку — основной канал роста после старта
- Не скрейпить закрытые/приватные базы данных — только публичная информация + добровольная регистрация

## 18. Tech stack (согласовано с бесплатным Oreshka-стеком)

**Выбор Node/TS (Mercur на Medusa) вместо PHP (Bagisto) — обоснование по объективным критериям, не по familiarity (сайт строит LLM-агент):**
- Mercur специализирован под multi-vendor маркетплейсы из коробки (vendor onboarding, комиссии, split payments), Bagisto — generic e-commerce + multivendor add-on
- Medusa headless/API-first по дизайну — чище стыкуется с отдельным Astro-фронтендом, чем Laravel-монолит
- TypeScript даёт статическую типизацию — меньше runtime-багов в LLM-сгенерированном коде
- Общий язык с уже написанным Cloudflare Worker AI-widget — переиспользование типов между function calling и backend API
- Модульный паттерн Medusa задокументирован именно под расширения (exchange, reputation, subscriptions)

- Frontend: Astro (Cloudflare Pages)
- Backend: **Mercur** (open-source marketplace-акселератор на Medusa.js) на Oracle Always Free VM
- Платежи: Stripe Connect (Express accounts) — split payments, комиссия, KYC продавцов через Stripe
- Директорий-поиск: Meilisearch (self-host на той же VM) — гео-фильтр по стране/региону, в перспективе map view
- Auth: Buyer и Organization — разные типы аккаунтов, RBAC через `organization_members` (роль member/admin)

## 19. Открытые вопросы (нужно решить до старта)

- Домен seed-bank.online — проверить доступность/зарегистрировать напрямую в регистраторе
- Модель верификации: кто и как подтверждает, что seed bank/ботсад реальный (документы? официальный email домена организации?)
- **Юридический статус маркетплейса при международных продажах между третьими продавцами и покупателями** — фитосанитарные требования (раздел 9) касаются широкого круга видов, не только CITES. Нужна консультация с юристом по международной торговле до открытия регистрации сторонним продавцам, особенно за пределами Oreshka. Это не блокирует MVP (Oreshka как единственный продавец — уже отработанная модель), но блокирует масштабирование на сторонних vendors
- Модель Stripe Connect Express — проверить доступность в странах, где будут регистрироваться первые продавцы (Stripe Connect не покрывает все страны мира одинаково)