Fairflow — Контекст проекта для AI-агента¶

Цель: Один документ, прочитав который агент получает полный контекст проекта и может эффективно работать с кодом, требованиями и бизнес-логикой.

1. Что такое Fairflow¶

Fairflow — проектно-центричная модульная CRM-платформа. Вся работа с клиентами, сделками и данными организована вокруг проектов. Проект — основная единица изоляции данных и масштабирования.

1.1 Ключевые принципы¶

Принцип	Описание
Проект = центр всего	Все CRM-данные живут внутри проекта и изолированы от других проектов
Модульность	Каждый проект включает только нужные модули. Ненужные отключаются
Deal-centric продажи	Единая сущность «Сделка» движется по воронке. Лиды, заявки, продажи — это стадии, а не отдельные сущности
Order-centric исполнение	Тип продукта определяет процесс оформления (тип продажи): поля, этапы, документы
Чистая база	Контакты и компании создаются явно, не автоматически из каждого обращения
Каждая запись имеет владельца	Сущности всегда привязаны к человеку или отделу

1.2 Два режима работы¶

Индивидуальный — физлицо использует платформу самостоятельно или с приглашёнными участниками
Корпоративный — организация (юрлицо) использует платформу как рабочее пространство для команды

2. Глоссарий¶

Термин	Определение
User	Физическое лицо, зарегистрированное в системе
Account	Учётная запись пользователя. Всегда принадлежит физлицу
Organization	Юридическое лицо / ИП. Корпоративное рабочее пространство
Workspace	Контекст владения проектами: личное или пространство организации
Project	Центральная сущность. Все CRM-данные привязаны к проекту
Module	Функциональный блок CRM (контакты, сделки, продажи и т.д.), включается per-project
Deal	Универсальная сущность продажи. Проходит через стадии воронки
Pipeline	Настраиваемая последовательность стадий для сделок
Order	Процесс исполнения/оформления. Создаётся из сделки
Order Type	Шаблон процесса оформления: поля, этапы, документы. Привязывается к продукту
Contact	Физическое лицо в базе CRM. Many-to-many с компаниями
Company	Юридическое лицо клиента. Many-to-many с контактами
Drawer	Глобальная боковая панель для быстрого создания сущностей. 6-8 полей max, без вложенности

3. Структура репозитория¶

fairflow/
├── docs/                                  # Документация
│   ├── promts/                            # Промпты и контекст для агентов
│   │   ├── project-context.md             # ← ЭТОТ ФАЙЛ
│   │   └── system-analyst-backend.md
│   ├── functional/
│   ├── requirements/
│   └── architecture/
├── fairflow-business-process-v5.2.md      # Главная бизнес-спецификация
├── microfrontend/
│   ├── host/                              # Host shell (routing, auth/layout, remote loading)
│   ├── modules/                           # Remote modules (contacts, companies, deals, ...)
│   └── shared-ui/                         # Общие UI-компоненты для host и remotes
└── services/                              # Gateway + доменные gRPC-сервисы

4. Главные документы¶

Документ	Назначение
fairflow-business-process-v5.2.md	Полная спецификация бизнес-процесса: глоссарий, жизненный цикл, авторизация, модель пространств, сделки, продажи, контакты, роли, аудит, биллинг, retention и т.д. ~2200 строк
docs/requirements/	Детализированные требования по доменам (29 файлов)
docs/functional/	Описание экранов, компоновка, элементы, состояния
docs/requirements/17-screen-map.md	Карта всех ~81 экрана и URL
docs/requirements/19-architecture-decisions.md	52 принятых архитектурных решения
docs/requirements/20-moscow.md	Приоритизация Must / Should / Could / Won't
docs/requirements/README.md	Навигация по всем 29 файлам требований

5. Frontend (microfrontend) — технический стек¶

React 19 + TypeScript
Vite 7
React Router 7
Zustand (state)
SWR (data fetching)
Tailwind CSS 4
axios + axios-mock-adapter (все API мокированы)
react-hook-form + zod
@hello-pangea/dnd (drag & drop для канбана)
FullCalendar (календарь активностей)
ApexCharts (графики)

5.1 Конфигурация host¶

microfrontend/host/src/configs/app.config.ts — базовые client-настройки (apiPrefix, auth entry, feature flags)
microfrontend/host/src/configs/navigation.config/index.ts — навигация и moduleKey для Contextual UI
microfrontend/host/src/configs/routes.config/routes.config.ts — маршруты host + lazy загрузка remote-модулей
microfrontend/host/src/utils/loadRemoteModule.ts — реестр remote-модулей
microfrontend/host/vite.config.ts — Module Federation remotes + прокси /api -> gateway

5.2 Ключевые пути¶

Путь	Описание
`microfrontend/host/src/views/`	Host-only экраны (auth, onboarding, account, project settings wrappers)
`microfrontend/host/src/components/`	shell/layout-компоненты host
`microfrontend/host/src/store/`	Zustand stores (включая текущий `projectContext`)
`microfrontend/host/src/services/`	gateway-клиенты (REST/GraphQL adapters)
`microfrontend/modules/*/src/`	remote-экраны портфеля (CRM-модули)
`microfrontend/shared-ui/src/`	shared UI библиотека для host/remotes

5.3 Модули (remote modules)¶

contacts, companies, deals, orders, activities, products, reports, documents, automation, statistics

5.4 Демо-аккаунты (пароль: `123Qwe`)¶

Email	Роль
`anna@fairflow.ru`	PO «Альфа Групп» + Employee «Бета ООО»
`dmitry@fairflow.ru`	Физлицо без организации
`sergey@fairflow.ru`	PA «Альфа Групп»
`maria@fairflow.ru`	Employee «Альфа Групп»

6. Модель данных (TypeScript типы)¶

Основные сущности в microfrontend/host/src/@types/crm.ts:

Contact — firstName, lastName, phone, email, companyId, assigneeId
Company — name, inn, kpp, legalAddress, contactIds
Pipeline — stages (id, name, color, order)
Deal — name, amount, pipelineId, stageId, contactId, companyId, productId, source, assigneeId, stageEnteredAt, result (won/lost/active)
Order — number, typeId, dealId, contactId, companyId, stageId, fields (Record), status, dlqError, driftWarning
OrderType — fields, stages, schemaVersion, webhookEnabled
Activity — type (task/call/meeting/note), status, priority, dueDate, assigneeId, dealId, contactId
Product — name, price, orderTypeId
Project — name, members, modules

7. Карта URL и экранов¶

7.1 Авторизация (12 экранов)¶

/, /auth/signin, /auth/signup, /auth/signup/organization, /auth/forgot-password, /auth/reset-password/:token, /auth/verify-email/:token, /auth/2fa, /auth/invite/:token, /onboarding/profile, /onboarding/first-project, /onboarding/invite-team

7.2 Глобальные¶

/home, /projects, /projects/new

7.3 Аккаунт¶

/account/profile, /account/security, /account/organization, /account/organization/departments, /account/organization/employees, /account/billing, /account/billing/plans, и др.

7.4 Политика project context (D2)¶

Зафиксированная policy:

Контекст проекта хранится в projectStore (и локальном persisted state), а не в path-prefix для CRM-портфеля.
Основные CRM-роуты идут без /p/:pid (например: /contacts, /deals, /orders, /reports).
Префикс /p/:pid сохраняется только для project settings-роутов и редиректов в account-space (/p/:pid/settings/*).
Все backend-запросы в проектных доменах обязаны включать x-project-id/projectId из store-контекста.

7.5 Портфель (без префикса `/p/:pid`)¶

Путь	Экран
`/dashboard`	Дашборд
`/statistics`	Статистика
`/contacts`	Контакты (список, детали, edit, import)
`/companies`	Компании (список, детали, edit, import)
`/deals`, `/deals/kanban`	Сделки (список, канбан)
`/deals/pipelines`	Воронки
`/orders`, `/orders/kanban`, `/orders/types`	Продажи и типы продаж
`/activities`, `/activities/calendar`	Активности
`/products`	Продукты
`/reports`	Отчёты
`/documents`, `/documents/templates`	Документы
`/automation`	Автоматизация
`/members`, `/roles`, `/audit`	Управление проектом в CRM-space
`/p/:pid/settings/*`	Project settings (special-case prefix)

8. Ролевая модель¶

8.1 Системные роли¶

Platform Owner — владелец организации
Platform Admin — администратор организации
Regular User — физлицо без организации
Employee — сотрудник организации

8.2 Проектные роли¶

Project Owner — владелец проекта
Project Admin — полный доступ
Manager — управление данными, воронками, отчётами
Member — работа с назначенными/доступными сущностями (по политике)
Viewer — только просмотр

9. UX-паттерны¶

Drawer — один глобальный, 6-8 полей, Progressive Disclosure для связанных сущностей
Contextual UI — отключённый модуль скрывает все связанные элементы
Списки — фильтры сверху, сортировка по заголовку, пагинация 25/50/100
Канбан — drag & drop для сделок (по стадиям) и продаж (по этапам)
Фильтры в URL — query params, сбрасываются при уходе

10. Бизнес-правила (кратко)¶

Изоляция по проекту — все CRM-запросы фильтруются по projectId
Владелец записи — ownerId (user или department) у каждой сущности
Soft delete — deletedAt, корзина 7 дней
Drift Detection — снимок контакта/компании при привязке к сделке/продаже
Stage log — полный лог переходов по стадиям (включая возвраты)
Передача сделок — только между проектами одной организации, копируется только сделка + lineage
DLQ — retry для webhook при ошибках, статус «Ошибка отправки»

11. Backend (планируется)¶

API: GraphQL (Apollo Server)
БД: MongoDB
Промпт для системного аналитика: docs/promts/system-analyst-backend.md

12. Чек-лист для агента¶

Перед началом работы:

[ ] Прочитал fairflow-business-process-v5.2.md (хотя бы ключевые разделы)
[ ] Понял структуру docs/requirements/ и docs/functional/
[ ] Знаю пути microfrontend/host/src/views/, microfrontend/modules/*/src/, microfrontend/shared-ui/src/
[ ] Учитываю projectId в данных/metadata (не в портфельных URL)
[ ] Учитываю moduleKey для Contextual UI
[ ] Проверяю docs/requirements/19-architecture-decisions.md при архитектурных решениях

13. Быстрые ссылки на файлы¶

Задача	Файл(ы)
Добавить экран host/remotes	`microfrontend/host/src/configs/routes.config/routes.config.ts`, `microfrontend/modules/*/src/`
Изменить типы CRM	`microfrontend/host/src/@types/crm.ts`
Настройки host	`microfrontend/host/src/configs/app.config.ts`
Реестр remote-модулей	`microfrontend/host/src/utils/loadRemoteModule.ts`, `microfrontend/host/vite.config.ts`
Shared UI	`microfrontend/shared-ui/src/index.tsx`
Роли и доступ	`microfrontend/host/src/utils/hooks/useWorkspaceRole.ts`