MSP Docs · v1.1.0 — Farmchel Docs

Структура проекта (Architecture map)

Farmchel / Motiv — Laravel + Filament internal platform. Ниже практическая карта кода: где что находится и куда вносить изменения.

Описание страниц админки, URL вида /admin/… и состава левого меню вынесено в отдельный документ: Структура проекта (/docs/project).

Сокращённое дерево

app/
  Filament/
    Pages/                 # Custom pages, включая MotivDashboard
    Widgets/               # Dashboard widgets (Motiv/*)
    Resources/             # CRUD слой сущностей
    RelationManagers/      # Notes/Audit relation managers
    Imports/               # CSV/XLSX importers
    Exports/               # Exporters для таблиц
  Models/                  # Domain models + relations
  Models/Concerns/         # Shared traits (notes/audit behavior)
  Services/                # Domain/service logic (dashboard signals)
  Http/
    Controllers/Api/V1/    # API controllers (versioned)
    Requests/Api/V1/       # API validation (Form Requests)
    Resources/Api/V1/      # API response transformers
    Middleware/            # Token ability middleware
  Policies/                # Role-aware authorization
  Support/                 # UI/status mapping helpers
  Providers/               # Panel providers, app providers

database/migrations/       # Schema evolution (fields, notes/audit, import/export infra, API logs)
resources/views/
  docs/                    # Documentation center (Business/API/MSP)
  filament/widgets/        # Custom widget views
routes/web.php             # Web routes, включая /docs/*
routes/api.php             # Internal API routes (/api/v1/*)
config/                    # Runtime config
public/                    # Web root/static entry
storage/                   # logs, exports/import files
tests/                     # Unit/Feature tests

Filament layer: где искать dashboard и админ-логику

Pages

app/Filament/Pages. Здесь находится MotivDashboard и его режимы отображения.

Widgets

app/Filament/Widgets/Motiv. KPI, Focus, Requires Attention, Activity и executive summary.

Resources

app/Filament/Resources/*. Формы, таблицы, фильтры, actions по сущностям.

Imports/Exports

app/Filament/Imports и app/Filament/Exports. Batch-загрузка и выгрузка данных.

Domain map (core сущности)

Сущность	Где модель	Роль в workflow
Applications	`app/Models/StoreApp.php`	Core портфель: owner/company/strategy/status.
Companies	`app/Models/Company.php`	Организационный контекст и контакты.
Contacts	`app/Models/Contact.php`	Ownership-коммуникация и связь с company/app/strategy.
Strategies	`app/Models/Strategy.php`	Операционный слой исполнения и responsible.
Keywords	`app/Models/Keyword.php`	ASO/маркетинговая семантика и приоритеты.
Analytics	`app/Models/ClickAnalyticsRow.php`	Клики/метрики и status signals.
Notes	`app/Models/Note.php`	Internal operational comments с автором и временем.
AuditLogs	`app/Models/AuditLog.php`	История изменений (кто/когда/что).

Operational data flow

Сущности создаются вручную через ресурсы или батч-импортом через ImportAction.
Ownership и status задаются в ресурсах и проверяются dashboard signal-блоками.
Notes и Audit фиксируют контекст изменений и решения команды.
Analytics rows питают alerts, top-blocks и срезы по presets.

Что менять где (practical map)

Задача	Куда идти
Изменить дашборд	`app/Filament/Pages/MotivDashboard.php` + `app/Filament/Widgets/Motiv/*` + `app/Services/MotivCommandCenterService.php`
Изменить импорт	`app/Filament/Imports/` + header actions в `Resources//Pages`
Изменить экспорт	`app/Filament/Exports/*` + ExportAction в нужном Resource
Добавить поле в сущность	migration → model fillable/casts → resource form/table/filters → dashboard integration (если нужно)
Изменить status mapping	`app/Support/MotivUi.php` + resource options/filters + service rules
Изменить docs center	`resources/views/docs/*` + `routes/web.php` (без смены URL)
Изменить API layer	`routes/api.php` + `app/Http/Controllers/Api/V1/` + `app/Http/Requests/Api/V1/` + `app/Http/Resources/Api/V1/*`
Операционный просмотр API логов	`app/Filament/Resources/ApiRequestLogs/*` + `app/Http/Controllers/Api/V1/AdminApiLogController.php`

Критичные зоны (осторожно)

Не ломать без проверки:

Filament `/admin` resources и их route generation.
Import/export инфраструктуру (таблицы imports, failed_import_rows, exports).
Ownership/status сигнализацию в dashboard service layer.
Notes/Audit traits и relation managers (shared behavior).
Документированные URL: /docs/business, /docs/project, /docs/api, /docs/strategies, /docs/msp.

Соглашения по проекту

Бизнес-логика сигналов и агрегатов — в services/support, а не в Blade.
Resource actions должны быть operational: либо рабочие, либо скрытые.
Новые сущности, требующие traceability, подключаются к notes/audit слою.
Изменения статусов всегда согласуются с `MotivUi` и ресурсными фильтрами.

Назначение раздела MSP

MSP docs — внутренний operations/runbook hub: окружения, доступы, релизы и восстановление сервиса.

Раздел для platform/ops и тех, кто дежурит по инцидентам.

Environments

Среда	Назначение
local	Разработка и отладка через Laragon.
development	Интеграционные проверки функций.
staging	Проверка релиз-кандидатов перед production.
production	Рабочее окружение команды.

Access / permissions

Доступы выдаются по заявке owner/ops manager.
Секреты не хранятся в репозитории и личных чатах.
Revocation выполняется при смене роли/уходе сотрудника.

API setup / auth model

API auth основан на Laravel Sanctum токенах: выдача/ревокация через /api/v1/auth/*.
Ability checks: middleware в app/Http/Middleware/EnsureTokenAbility.php.
Policy checks: role-aware policy слой в app/Policies/* (включая ApiRequestLogPolicy).
API request audit: app/Http/Middleware/LogApiRequest.php + таблица api_request_logs.

Local bootstrap: после php artisan migrate --seed создаётся dev admin test@example.com. Пароль по умолчанию admin12345, можно переопределить через MOTIV_DEV_ADMIN_PASSWORD.

Кто видит API logs: только admin/manager с активным статусом и корректной ability (для API endpoint: logs:read).

Deploy / release process

Pre-check: миграции, health endpoint, import/export infra.
Deploy: код + зависимости + migrate.
Post-check: /admin, /docs, dashboard, import/export smoke test.
Rollback: откат релиза и фиксация инцидента в runbook.

Runbooks

Админка не открывается

Проверить APP_URL, auth, DB connection, логи и route cache.

Миграция не применилась

Проверить блокировки, batch status, повторить migrate --force.

Импорт падает

Проверить таблицы imports/failed_import_rows, mapping и validation errors.

Экспорт падает

Проверить таблицу exports, storage link, права на диск.

Нет свежих кликов

Проверить импортный пайплайн, period presets и source data feed.

Broken ownership links

Проверить null owner/company/strategy через Requires Attention.

Monitoring / health checks

/up должен быть доступен.
Проверка доступности `/admin` и `MotivDashboard`.
Ошибки из логов по import/export и DB connectivity.

Incident handling

Инцидент: недоступность админки, массовый import/export fail, потеря свежих данных.
Уведомляются: owner, ops manager, backend responsible.
После устранения — короткий postmortem и action items.

Backup / recovery principles

Бэкапы базы должны быть регулярными и проверяемыми на восстановление.
Recovery-план должен включать DB restore + health verification + dashboard smoke test.