Skip to content
BranchesTags

Repository files navigation

Русский · English

Store Order Management System

Внутренняя retail-платформа для управления заказами, запасами и аналитикой

Продажи · Пополнение · Перемещения · Запасы · Аналитика · FastAPI · React · PostgreSQL

FastAPI Python React TypeScript Vite PostgreSQL SQLAlchemy Recharts

Обзор

Store Order Management System (OMS) — full-stack приложение для внутренних retail-операций. Оно предоставляет менеджерам магазинов, сотрудникам складов и operations/admin-пользователям единое рабочее пространство для работы с заказами, запасами, локациями, товарами и операционной аналитикой.

Это не клиентский интернет-магазин. Продукт сосредоточен на контролируемых workflow заказов, видимости запасов, отслеживаемом движении товаров и управленческой отчётности по магазинам и складам.

Контекст проекта и мой вклад

Этот репозиторий — завершённый университетский командный проект, разработанный в Innopolis University. Он представлен как snapshot реализованного командой MVP вместе с инженерной документацией, подтверждениями качества и историей сдачи проекта по курсу.

Мой основной вклад был сосредоточен на домене Orders: routers, schemas, services и repositories, workflows создания заказов, контролируемые backend-переходы статусов, комментарии, история, обработка отклонений и отмен, а также связанная транзакционная business logic. Полное приложение отражает работу всей проектной команды.

Что демонстрирует проект

  • Слоистый FastAPI backend с чёткими границами между HTTP, business logic и persistence.
  • REST-контракты на основе Pydantic schemas, SQLAlchemy models и TypeScript types.
  • Транзакционные workflows, согласующие состояние заказов, резервы запасов и stock movements.
  • React/TypeScript operations-интерфейс для ежедневных процессов и аналитических представлений.
  • PostgreSQL domain modelling для заказов, inventory, locations, workflow transitions и permissions.
  • Автоматизированные backend/frontend проверки, coverage thresholds и сохранённые delivery evidence.

Скриншоты

Операционный dashboard OMS
Операционный dashboard 		Запасы магазина
Запасы магазина
История inventory-транзакций
Inventory-транзакции 		Retail-аналитика
Аналитика

Архитектура

Решение построено как modular monolith backend с отдельным браузерным frontend. React-приложение взаимодействует с FastAPI через JSON REST API; FastAPI координирует бизнес-правила и сохраняет состояние в PostgreSQL в схеме oms_schema.

flowchart LR
    U[Менеджеры магазинов<br/>Сотрудники складов<br/>Operations/admin] --> F[React + TypeScript + Vite]
    F -->|REST / JSON| R

    subgraph B[FastAPI modular monolith]
        R[Routers] --> S[Services]
        S --> P[Repositories]
        SC[Schemas] -. typed API structures .-> R
        M[SQLAlchemy models] -. persistence mappings .-> P
    end

    P --> D[(PostgreSQL<br/>oms_schema)]
Loading

Путь backend-запроса — router → service → repository → PostgreSQL. Routers публикуют HTTP-контракты, services отвечают за validation и координацию транзакций, repositories изолируют доступ к базе данных, schemas задают typed API payloads, а models отображают persistent entities. Подробные static, dynamic и deployment views находятся в документации по архитектуре.

Основные области продукта

Область Операционный охват
Orders Заказы продаж, пополнения и перемещения с workflow, контролируемыми backend-логикой
Inventory Запасы магазинов и складов, резервы, доступность и движения
Transactions Отслеживаемая история inventory-транзакций магазинов и складов и экспорт
Catalogue Управление товарами, поиск по SKU/EAN/названию и импорт из spreadsheet
Locations Создание, редактирование и detail views магазинов и складов
Dashboard Операционные сводки, индикаторы заказов и low-stock visibility
Analytics Executive KPI, sales timelines, анализ товаров, доступность и inventory value

Возможности продукта

  • Создание и отслеживание sales, replenishment и store-to-store transfer orders.
  • Проверка допустимых переходов статусов заказов на backend вместо зависимости от frontend-правил.
  • Сохранение order items, истории статусов, комментариев и общих заметок.
  • Фиксация причин отклонения и результатов отмены.
  • Резервирование запасов при создании заказа и согласование количества при completion, dispatch или cancellation.
  • Отслеживание фактического, зарезервированного и доступного количества для inventory магазинов и складов.
  • Запись входящих и исходящих inventory movements со ссылками на orders.
  • Поиск и управление товарами; импорт товарных данных из проверенного spreadsheet-шаблона.
  • Управление магазинами, складами и доступностью товаров для конкретного магазина.
  • Просмотр executive KPI, sales summaries и timelines, top items, inventory availability и inventory value.

Технологический стек

Слой Технологии
Backend Python 3.14+, FastAPI, SQLAlchemy, Uvicorn
Database PostgreSQL, psycopg2, SQL schema и seed scripts
Frontend React, TypeScript, Vite
Analytics and UI Recharts, date-fns, Lucide React, React DayPicker
Data import Pandas, OpenPyXL, FastAPI multipart uploads
API REST, JSON, FastAPI OpenAPI/Swagger
Testing and quality unittest, Coverage.py, Vitest, ESLint, Prettier, Ruff
Documentation Markdown, PlantUML, ADRs, GitLab Pages

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

.
├── MVP-v2/
│   ├── backend/
│   │   ├── app/                 # FastAPI application and layered domain modules
│   │   ├── database/            # PostgreSQL schema and demo seed data
│   │   ├── scripts/             # Quality and coverage verification utilities
│   │   └── tests/               # Backend unit and integration tests
│   └── frontend/
│       ├── src/                 # React pages, components, API clients and analytics
│       └── public/              # Frontend static assets
├── docs/                        # Architecture, quality, process and release documents
├── reports/                     # Weekly delivery reports and product screenshots
├── OMS_v4_unified_orders_schema.sql
└── demo_data.sql

Быстрый старт

Требования

  • Python 3.14+
  • Node.js 22+ и npm
  • PostgreSQL

1. Подготовка PostgreSQL

Создайте или выберите PostgreSQL database, затем примените поддерживаемую схему:

psql -U postgres -d postgres -f MVP-v2/backend/database/schema/OMS_v4_unified_orders_schema.sql

Приложение использует PostgreSQL schema oms_schema. После схемы при необходимости можно загрузить demo data:

psql -U postgres -d postgres -f MVP-v2/backend/database/seeds/demo_data.sql

Demo seed устанавливает search_path в oms_schema, сохраняет существующие записи, выполняет upsert товаров по SKU и защищает demo orders/transactions от повторной вставки. Эти же SQL-файлы можно открыть и выполнить в DataGrip.

2. Настройка и запуск backend

cd MVP-v2/backend
cp app/.env.example app/.env

Обновите app/.env, указав параметры подключения к PostgreSQL. DATABASE_URL должен использовать SQLAlchemy PostgreSQL URL в формате postgresql+psycopg2://USER:PASSWORD@HOST:PORT/DATABASE.

Создайте окружение, установите runtime dependencies и запустите FastAPI:

python3 -m venv .venv
.venv/bin/python -m pip install fastapi openpyxl pandas psycopg2-binary python-dotenv python-multipart sqlalchemy uvicorn
.venv/bin/python -m compileall app
.venv/bin/python -m unittest discover -s tests
.venv/bin/python -m uvicorn app.main:app --reload

API запускается на http://127.0.0.1:8000; интерактивная Swagger-документация доступна на http://127.0.0.1:8000/docs.

3. Запуск frontend

Во втором терминале:

cd MVP-v2/frontend
npm ci
npm run build
npm run dev

Frontend запускается на http://127.0.0.1:5173. Установите VITE_API_BASE_URL, если backend размещён не по локальному адресу по умолчанию.

Тестирование и качество

Backend verification использует Python unittest, Coverage.py и Ruff; frontend verification — Vitest, ESLint, Prettier и TypeScript/Vite production build. Сохранённая конфигурация GitLab CI также проверяет Markdown links и выполняет проверку репозитория на случайно добавленные чувствительные данные.

# Backend
cd MVP-v2/backend
.venv/bin/ruff check app tests scripts
.venv/bin/ruff format --check tests scripts
.venv/bin/python -m compileall app
.venv/bin/python -m coverage run --source=app -m unittest discover -s tests
.venv/bin/python -m coverage report --fail-under=30

# Frontend
cd ../frontend
npm run lint
npm run format:check
npm run test:coverage
npm run build

CI фиксирует 45 backend tests, целевые suites для quality requirements, frontend unit tests и 30% coverage thresholds для поддерживаемых critical modules. Полное определение quality gates см. в стратегии тестирования и подтверждениях.

Документация

Инженерная документация

Подтверждения delivery и release

Исторические подтверждения проекта остаются доступны в исходных ресурсах GitLab, включая v3.0.0 release, final verification pipeline и hosted documentation.

Статус

Репозиторий представляет завершённый MVP и университетский командный проект с реализованным full-stack приложением, автоматизированными quality gates, architecture records, release notes и сохранёнными delivery evidence для review.

Ранее существовал внутренний deployment в сети Innopolis University. Это не публичный live demo, поэтому доступность вне университетской сети не гарантируется. Точный исторический адрес сохранён в английской версии README вместе с исходной технической формулировкой.

Почему проект важен для review

Проект демонстрирует практическую работу с FastAPI backend architecture, REST API design, SQLAlchemy/PostgreSQL persistence, транзакционными order workflows и state transitions, согласованностью inventory, интеграцией React/TypeScript, аналитикой, автоматизированным тестированием, quality gates, архитектурной документацией и командной разработкой ПО.

About

Full-stack retail order management system with FastAPI, React, TypeScript and PostgreSQL for sales, replenishment, transfers, inventory tracking and analytics.

Topics

analyticsfastapifull-stackinventory-managementinventory-trackingorder-managementpostgresqlpythonreactrechartsreplenishmentrest-apiretail-operationssqlalchemytypescriptvitevitestwarehouse-management

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages