Skip to main content

ADOLF CFO — Раздел 1: Архитектура

Проект: Финансовый учёт и управленческая аналитика
Модуль: CFO
Версия: 1.0
Дата: Январь 2026

1.1 Назначение модуля

CFO — модуль автоматизированного управленческого учёта, формирования P&L-отчётов и финансовой аналитики для e-commerce бизнеса на маркетплейсах.

Основные функции

ФункцияОписание
Data IngestionЕжедневный сбор данных из API маркетплейсов и файлов
Cost MappingСопоставление продаж с себестоимостью по Barcode/SKU
P&L CalculationРасчёт маржинальности по всем срезам
ABC AnalysisКлассификация SKU по вкладу в прибыль
AI InsightsФормирование выводов и рекомендаций
Custom ReportsГенерация отчётов по запросу пользователя
AlertingУведомления об убыточных SKU и аномалиях

Целевые пользователи

РольДоступФункции
SeniorОграниченныйP&L по категориям/брендам/МП, ABC-анализ
DirectorПолныйВсе отчёты + P&L по SKU + кастомные отчёты
AdministratorПолный + настройкиВсё + настройка порогов и расписания

1.2 Границы модуля

Входит в модуль CFO

КомпонентОписание
Marketplace AdaptersПолучение финансовых данных через API WB, Ozon, YM
File ParsersПарсинг Excel-отчётов из ЛК маркетплейсов
Cost MapperСопоставление продаж с себестоимостью из 1С
P&L CalculatorРасчёт маржинальности по всем срезам
ABC AnalyzerКлассификация SKU (A, B, C, D)
AI Insights GeneratorФормирование выводов (Claude Opus 4.5)
Report BuilderГенерация отчётов по запросу
Alert EngineОбнаружение аномалий и убыточных SKU
REST APIEndpoints для управления модулем
Open WebUI PipelineИнтерфейс @Adolf_CFO
Celery TasksФоновые задачи импорта и расчёта

Не входит в модуль CFO

КомпонентГде реализованоТип взаимодействия
Авторизация пользователейADOLF Core (Middleware)Используется готовая
Обработка файлов 1СADOLF Core (ETL)Файлы из /data/inbox
Хранение первичкиADOLF KnowledgeИндексация через ETL
Хранение пользователейADOLF Core (PostgreSQL)Чтение таблицы users
Система уведомленийADOLF Core (Notifications)Event Bus
Генерация текста (LLM)OpenAI APIAPI-вызовы

Функционал v2.0 (не входит в MVP)

КомпонентОписание
1C IntegrationПрямое подключение к 1С через API
Extended CostsУчёт ФОТ, упаковки, доставки до МП
ForecastingПрогнозирование маржинальности
BudgetingПлан-факт анализ
DashboardsВизуальные графики и диаграммы
BI ExportИнтеграция с Power BI / Tableau

1.3 Архитектура модуля

1.3.1 Общая схема

1.3.2 Схема потока данных

1.3.3 Компонентная диаграмма


1.4 Зависимости от ADOLF Core

1.4.1 Middleware (FastAPI)

Используемые возможности:
ВозможностьПрименение в CFO
АвторизацияПроверка role IN (senior, director, admin)
ИдентификацияПолучение user_id, brand_id из сессии
РоутингРегистрация endpoints /api/v1/cfo/*
ФильтрацияОграничение данных по роли
АудитЛогирование действий в audit_log
Разграничение доступа:
# Проверка доступа к CFO
ALLOWED_ROLES = ["senior", "director", "admin"]

# Функции с ограниченным доступом (только Director+)
DIRECTOR_ONLY_FUNCTIONS = [
    "pnl_by_sku",
    "consolidated_pnl", 
    "sku_cost_price",
    "custom_reports"
]

def check_cfo_access(user: User, function: str) -> bool:
    if user.role not in ALLOWED_ROLES:
        return False
    
    if function in DIRECTOR_ONLY_FUNCTIONS:
        return user.role in ["director", "admin"]
    
    return True

1.4.2 ETL

Обрабатываемые файлы:
Тип файлаИсточникОбработка
Excel отчёты МП/data/inbox/cfo/marketplace/Парсинг → cfo_transactions
Себестоимость 1С/data/inbox/cfo/costs/Парсинг → cfo_cost_prices
Первичка/data/inbox/cfo/primary/OCR → Knowledge Base
Структура папок:
/data/inbox/cfo/
├── marketplace/          # Excel-отчёты из ЛК маркетплейсов
│   ├── wb/
│   ├── ozon/
│   └── ym/
├── costs/                # Выгрузки себестоимости из 1С
└── primary/              # Бухгалтерская первичка

1.4.3 PostgreSQL

Используемые таблицы:
ТаблицаНазначение
usersРоль пользователя, проверка доступа
cfo_transactionsФинансовые транзакции с маркетплейсов
cfo_cost_pricesСправочник себестоимости (Barcode → COGS)
cfo_pnl_dailyЕжедневный P&L по SKU
cfo_pnl_aggregatedАгрегированный P&L по периодам
cfo_abc_resultsРезультаты ABC-анализа
cfo_alertsИстория алертов
cfo_reportsСохранённые отчёты
cfo_settingsНастройки модуля (пороги, расписание)
audit_logЛоги всех действий

1.4.4 Celery

Фоновые задачи:
ЗадачаОписаниеРасписание
cfo.import_wb_financeИмпорт данных WildberriesЕжедневно 06:00
cfo.import_ozon_financeИмпорт данных OzonЕжедневно 06:10
cfo.import_ym_financeИмпорт данных Яндекс.МаркетЕжедневно 06:20
cfo.process_excel_reportsОбработка Excel из ETLЕжедневно 06:30
cfo.process_cost_pricesОбработка себестоимостиЕженедельно (Пн 07:00)
cfo.calculate_daily_pnlРасчёт дневного P&LЕжедневно 07:00
cfo.run_abc_analysisABC-анализЕженедельно (Пн 08:00)
cfo.check_alertsПроверка алертовЕжедневно 08:00
cfo.cleanup_old_dataОчистка старых данныхЕжемесячно

1.4.5 Notifications

События для уведомлений:
СобытиеУровеньПолучателиОписание
cfo.sku_negative_marginwarningSenior, DirectorSKU с отрицательной маржой (класс D)
cfo.margin_below_thresholdwarningSenior, DirectorМаржа ниже порога
cfo.data_importedinfoAdminЕжедневный импорт завершён
cfo.import_errorcriticalAdminОшибка импорта данных
cfo.anomaly_detectedwarningAdminАномалия в данных

1.5 Зависимости от других модулей

1.5.1 ADOLF Knowledge

Назначение: Хранение и поиск бухгалтерской первички. Используемые данные:
Тип документаПримерПрименение
НакладныеТОРГ-12Подтверждение закупочной цены
Счета-фактурыОт поставщиковДетализация расходов
АктыАкты выполненных работУчёт услуг
API-вызов:
async def search_primary_docs(
    query: str,
    doc_type: str,
    date_from: date,
    date_to: date
) -> List[Document]:
    """Поиск первичных документов в Knowledge Base."""
    response = await knowledge_api.search(
        query=query,
        filters={
            "category": "finance",
            "doc_type": doc_type,
            "date_range": [date_from, date_to]
        }
    )
    return response.results

1.5.2 Другие модули

МодульВзаимодействие
WatcherНе используется в MVP
ReputationНе используется
Content FactoryНе используется
MarketingВ v2.0: данные о расходах на рекламу
ScoutВ v2.0: данные для unit-экономики

1.6 Внешние интеграции

1.6.1 API маркетплейсов (финансовые данные)

Сводка API:
МаркетплейсEndpointДанныеRate Limit
WildberriesGET /api/v1/supplier/reportDetailByPeriodПродажи, комиссии, логистика1 req/min
OzonPOST /v3/finance/transaction/listТранзакции, удержания60 req/min
Яндекс.МаркетGET /reports/financesФинансовый отчёт10 req/min

1.6.2 AI-сервисы

СервисМодельНазначение
OpenAIClaude Opus 4.5AI-инсайты, кастомные отчёты
Timeweb AIGPT-5 miniПарсинг Excel, OCR первички

1.7 Компоненты модуля

1.7.1 Data Ingestion

Назначение: Сбор финансовых данных из всех источников.

1.7.2 Cost Mapper

Назначение: Сопоставление продаж с себестоимостью. Алгоритм маппинга: Приоритет маппинга:
ПриоритетКлючОписание
1BarcodeТочное соответствие штрихкода
2SKU (артикул)Артикул продавца
3nm_id + sizeНоменклатура МП + размер

1.7.3 P&L Calculator

Назначение: Расчёт маржинальности по всем срезам. Формула расчёта:
Revenue = Sale Price (после скидок)

Expenses:
  - COGS (себестоимость)
  - Commission (комиссия МП)
  - Logistics (логистика до покупателя)
  - Return Logistics (обратная логистика)
  - Storage (хранение)
  - Advertising (реклама)

Gross Profit = Revenue - COGS
Net Profit = Revenue - All Expenses
Margin % = Net Profit / Revenue * 100
Срезы агрегации:
СрезКлюч группировкиПример
По SKUskuOM-12345
По категорииcategoryПлатья
По брендуbrand_idohana_market
По маркетплейсуmarketplacewb
По периодуdate2026-01-15

1.7.4 ABC Analyzer

Назначение: Классификация SKU по вкладу в прибыль. Алгоритм: Пороги классификации:
КлассНакопительная доля прибылиХарактеристика
A0% — 80%Ключевые SKU
B80% — 95%Средние SKU
C95% — 100%Аутсайдеры (прибыльные)
DОтрицательная прибыльУбыточные

1.7.5 AI Insights Generator

Назначение: Формирование текстовых выводов и рекомендаций. Входные данные для AI:
ДанныеОписание
P&L summaryСводка по выручке, расходам, прибыли
ABC distributionРаспределение SKU по классам
Top/Bottom performersЛучшие и худшие SKU
AnomaliesВыявленные аномалии
TrendsДинамика показателей
Промпт для Claude Opus 4.5:
Ты финансовый аналитик e-commerce компании.

Проанализируй финансовые данные и сформируй выводы:

Данные:
{pnl_summary}
{abc_distribution}
{top_performers}
{bottom_performers}
{anomalies}

Требования к ответу:
1. Краткое резюме (2-3 предложения)
2. Ключевые проблемы (если есть)
3. Конкретные рекомендации по убыточным SKU
4. Возможности для роста маржи

Формат: структурированный текст на русском языке.
Тон: деловой, конкретный, с цифрами.

1.7.6 Report Builder

Назначение: Генерация отчётов по запросу пользователя. Типы отчётов:
ТипОписаниеДоступ
pnl_by_skuP&L по каждому SKUDirector+
pnl_by_categoryP&L по категориямSenior+
pnl_by_brandP&L по брендамSenior+
pnl_by_marketplaceP&L по маркетплейсамSenior+
pnl_consolidatedКонсолидированный P&LDirector+
abc_reportABC-анализSenior+
loss_makersУбыточные SKU (класс D)Senior+
customКастомный отчётDirector+

1.7.7 Alert Engine

Назначение: Обнаружение проблем и отправка уведомлений. Правила алертов:
ПравилоУсловиеУровень
Убыточный SKUmargin < 0warning
Низкая маржаmargin < thresholdwarning
Аномалия выручкиrevenue_change > 20%warning
Аномалия расходовexpense_change > 20%warning
Ошибка маппингаunmapped_count > 10warning

1.8 Настройки модуля

1.8.1 Environment Variables

ПеременнаяОписаниеПример
WB_API_KEYAPI-ключ Wildberriesxxx...
OZON_CLIENT_IDClient ID Ozon123456
OZON_API_KEYAPI-ключ Ozonxxx...
YM_OAUTH_TOKENOAuth-токен Яндекс.Маркетxxx...
YM_CAMPAIGN_IDID кампании Яндекс.Маркет789012
CLAUDE_API_KEYAPI-ключ Claudesk-...
CFO_MARGIN_THRESHOLDПорог маржи для алерта (%)10
CFO_ANOMALY_THRESHOLDПорог аномалии (%)20

1.8.2 Настройки в БД (cfo_settings)

КлючТипОписаниеЗначение по умолчанию
margin_thresholdfloatПорог маржи для алерта10.0
anomaly_thresholdfloatПорог отклонения для аномалии20.0
abc_thresholdsjsonПороги ABC-классов{"a": 80, "b": 95}
import_schedulejsonРасписание импорта{"time": "06:00"}
retention_daysintСрок хранения детальных данных365

1.9 Технические ограничения

ПараметрОграничение
Период запроса API (WB)Максимум 30 дней
Период запроса API (Ozon)Максимум 3 месяца
Размер Excel-файлаДо 50 МБ
Время расчёта P&L< 5 минут (полный пересчёт)
Время генерации AI-инсайтов< 30 секунд
Хранение детальных транзакций12 месяцев
Хранение агрегатовБессрочно

1.10 Безопасность

Защита финансовых данных

МераРеализация
Доступ по ролямMiddleware проверяет role IN (senior, director, admin)
Фильтрация по брендуSenior видит только свой бренд
АудитВсе действия логируются в audit_log
ШифрованиеAPI-ключи в environment variables
RetentionАвтоочистка детальных данных старше 12 месяцев

Документ подготовлен: Январь 2026
Версия: 1.0
Статус: Черновик