Техническая спецификация системы

складского учёта для буровой

компании

1. Введение

Данный документ описывает детальную техническую спецификацию для

разработки системы складского учёта, предназначенной для буровой компании,
оперирующей на 5-6 участках в одной стране. Система призвана
автоматизировать процессы отслеживания движения грузов, обеспечить
прозрачность операций, повысить эффективность управления запасами и
предоставить инструменты для аналитики и отчётности.

2. Обзор требований

Система должна соответствовать следующим основным требованиям:

Отслеживание статусов грузов:

Заказан

В пути на склад

На складе [Город, №]

В пути на участок [Участок]

На участке

Передан бригаде [Бригада]

Списан

Обязательная регистрация и перемещение по штрихкодам.

Поддержка аудита, истории действий, прав доступа.

Удобная админ-панель, быстрый и понятный UI.

 Возможность развёртывания через Docker и масштабирования (вплоть
до международного уровня).

Логирование, резервное копирование, отчёты, экспорт, API-доступ.

Мобильные приложения для iOS и Android с функционалом сканера

(React Native).

Интеграция с 1С (MVP) и будущая интеграция с GPS-системами.

Возможность перенаправления грузов между складами и участками.

Гибкая система локализации (языки, валюты) через конфигурацию.

Безопасность уровня Tier-3.

Этапность развития проекта от MVP до продакшена, включая

интерактивные карты складов в будущем.

3. Оценка объёма данных

Для буровой компании, работающей на 5-6 участках, можно предположить

следующий примерный объём данных:

Количество номенклатурных позиций (SKU): 5,000 - 10,000 уникальных

позиций (запчасти, инструменты, расходные материалы).

Количество единиц хранения (товаров на складе/участке): 50,000 -

100,000 единиц одновременно.

Количество транзакций в день: 500 - 1,000 операций (приёмка, отгрузка,

перемещение, списание).

Количество пользователей: 20-50 активных пользователей (складские

работники, менеджеры, бригадиры).

Эти цифры являются оценочными и могут быть скорректированы по мере

уточнения бизнес-процессов. Система должна быть спроектирована с учётом
возможности роста этих показателей в 5-10 раз для обеспечения
масштабируемости.
4. Архитектура системы

Система будет построена на микросервисной архитектуре, что обеспечит

высокую масштабируемость, отказоустойчивость, гибкость в разработке и
развёртывании. Каждый микросервис будет отвечать за определённый набор
бизнес-функций и взаимодействовать с другими сервисами через легковесные
API (REST/gRPC).

4.1. Высокоуровневая архитектура

Система будет состоять из следующих основных компонентов:

Gateway/API Gateway: Единая точка входа для всех клиентских приложений

(веб, мобильные). Отвечает за маршрутизацию запросов, аутентификацию,
балансировку нагрузки и кэширование. Пример: Nginx, Kong, Ocelot.

Микросервисы: Набор независимых сервисов, каждый из которых

реализует определённую бизнес-логику. Примеры:
Service Inventory : Управление номенклатурой, характеристиками
товаров, штрихкодами.

Service Warehouse : Управление складами, ячейками, остатками,

перемещениями внутри склада.

Service Logistics : Управление статусами грузов, маршрутами,

перемещениями между складами/участками.

Service UserManagement : Управление пользователями, ролями,

правами доступа.

Service Reporting : Генерация отчётов, экспорт данных.

Service Integration : Взаимодействие с внешними системами (1С,

GPS).

Базы данных: Каждый микросервис будет иметь свою собственную базу

данных (Database per Service pattern), что повышает автономность и
гибкость в выборе технологий хранения данных. Предпочтение будет
отдаваться реляционным СУБД для большинства сервисов, но возможны
NoSQL решения для специфических задач (например, для логирования или
кэширования).
 Брокер сообщений (Message Broker): Для асинхронного взаимодействия
между микросервисами и обеспечения надёжной доставки событий.
Пример: Apache Kafka, RabbitMQ.

Система кэширования (Caching System): Для ускорения доступа к часто

используемым данным и снижения нагрузки на базы данных. Пример: Redis,
Memcached.

Система логирования и мониторинга (Logging & Monitoring):

Централизованный сбор логов и метрик для отслеживания состояния
системы, выявления проблем и анализа производительности. Пример: ELK
Stack (Elasticsearch, Logstash, Kibana), Prometheus + Grafana.

CI/CD Pipeline: Автоматизация процессов сборки, тестирования и

развёртывания. Пример: GitLab CI/CD, Jenkins.

4.2. Взаимодействие компонентов

Взаимодействие между микросервисами будет осуществляться

преимущественно через RESTful API для синхронных операций и через брокер
сообщений для асинхронных событий. API Gateway будет выступать в роли
фасада для всех внешних запросов.

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

Выбор технологического стека обусловлен требованиями к масштабируемости,

производительности, безопасности, удобству разработки и поддержки, а также
наличием квалифицированных специалистов на рынке.
5.1. Backend

Язык программирования: Python 3.x

Обоснование: Python является одним из самых популярных языков
для разработки бэкенда, обладает богатой экосистемой библиотек,
высокой скоростью разработки и отличной поддержкой
микросервисной архитектуры. Он также хорошо подходит для задач,
связанных с обработкой данных и интеграциями.

Фреймворк: FastAPI
Обоснование: FastAPI — это современный, высокопроизводительный
веб-фреймворк для создания API на Python, основанный на
стандартных типах Python. Он обеспечивает автоматическую
генерацию интерактивной документации (Swagger UI), валидацию
данных, асинхронность (ASGI) и отличную производительность,
сравнимую с Go и [Link].

База данных: PostgreSQL

Обоснование: PostgreSQL — мощная, надёжная, объектно-
реляционная система управления базами данных с открытым
исходным кодом. Она поддерживает сложные запросы, транзакции,
репликацию, обладает высокой степенью соответствия стандартам
SQL и отлично подходит для хранения структурированных данных,
включая информацию о товарах, складах, пользователях и
транзакциях. Её расширяемость позволяет легко добавлять новые
типы данных и функции.

ORM: SQLAlchemy (с Alembic для миграций)

Обоснование: SQLAlchemy — это мощный и гибкий ORM для Python,
который предоставляет полный набор инструментов для работы с
базами данных. Alembic обеспечивает удобное управление
миграциями схемы базы данных.

Брокер сообщений: RabbitMQ

Обоснование: RabbitMQ — надёжный и широко используемый брокер
сообщений, поддерживающий различные протоколы обмена
сообщениями. Он идеально подходит для асинхронного
взаимодействия между микросервисами, обеспечения надёжной
доставки событий и обработки фоновых задач.
 Кэширование: Redis
Обоснование: Redis — высокопроизводительное хранилище данных в
памяти, используемое как кэш, брокер сообщений и база данных.
Идеально подходит для хранения сессий, часто запрашиваемых
данных и очередей задач.

5.2. Frontend (Web)

Фреймворк: [Link]
Обоснование: [Link] — популярная JavaScript-библиотека для
создания пользовательских интерфейсов. Обеспечивает высокую
производительность, модульность, компонентный подход к
разработке и большое сообщество. Подходит для создания сложных и
интерактивных админ-панелей.

Язык: TypeScript
Обоснование: TypeScript — надмножество JavaScript, добавляющее
статическую типизацию. Это повышает надёжность кода, упрощает
его поддержку и улучшает процесс разработки, особенно в больших
проектах.

Управление состоянием: Redux Toolkit / React Query

Обоснование: Redux Toolkit упрощает работу с Redux, а React Query
предоставляет мощные инструменты для управления состоянием
сервера и кэширования данных.

UI-библиотека: Ant Design / Material-UI

Обоснование: Готовые компоненты UI ускоряют разработку и
обеспечивают консистентный, современный внешний вид.

5.3. Mobile (iOS/Android)

Фреймворк: React Native

Обоснование: React Native позволяет разрабатывать
кроссплатформенные мобильные приложения, используя тот же стек
технологий (React, JavaScript/TypeScript), что и для веб-версии. Это
значительно сокращает время и стоимость разработки, а также
упрощает поддержку. React Native имеет хорошие возможности для
 работы с нативными модулями, что важно для интеграции со
сканерами штрихкодов.

5.4. DevOps & Инфраструктура

Контейнеризация: Docker
Обоснование: Docker обеспечивает изоляцию приложений и их
зависимостей, упрощает развёртывание и обеспечивает
консистентность среды между разработкой, тестированием и
продакшеном.

Оркестрация контейнеров: Kubernetes (K8s)

Обоснование: Kubernetes — стандарт де-факто для оркестрации
контейнеров. Он обеспечивает автоматическое развёртывание,
масштабирование, управление и мониторинг контейнеризированных
приложений, что критически важно для высоконагруженных и
отказоустойчивых систем.

CI/CD: GitLab CI/CD / Jenkins

Обоснование: Автоматизация процессов сборки, тестирования и
развёртывания. GitLab CI/CD интегрирован с системой контроля
версий, Jenkins — гибкое и мощное решение.

Мониторинг: Prometheus + Grafana

Обоснование: Prometheus для сбора метрик, Grafana для
визуализации. Позволяют отслеживать состояние системы в реальном
времени, выявлять узкие места и оперативно реагировать на
инциденты.

Логирование: ELK Stack (Elasticsearch, Logstash, Kibana)

Обоснование: Централизованный сбор, хранение, индексация и
анализ логов со всех компонентов системы. Позволяет быстро
находить и устранять проблемы.

Система контроля версий: Git (GitLab / GitHub / Bitbucket)

Обоснование: Стандарт индустрии для совместной разработки и
управления версиями кода.
5.5. Инструменты для разработки

IDE: VS Code / PyCharm

Управление зависимостями (Python): Poetry / Pipenv

Управление зависимостями (JavaScript/TypeScript): Yarn / npm

6. API-контракты и структура данных

API будет разработан по принципам RESTful, обеспечивая чёткое и

предсказуемое взаимодействие между клиентскими приложениями и
микросервисами. Для описания API будет использоваться OpenAPI Specification
(Swagger).

6.1. Общие принципы API

Версионирование: API будет версионироваться (например, /api/v1/ ) для

обеспечения обратной совместимости.

Аутентификация и Авторизация: Использование JWT (JSON Web Tokens)

для аутентификации и RBAC (Role-Based Access Control) для авторизации.

Формат данных: JSON для обмена данными.

Обработка ошибок: Стандартизированные коды HTTP-статусов и формат

сообщений об ошибках.

6.2. Структура данных (примеры)

Ниже представлены примеры ключевых сущностей и их атрибутов. Полная схема

будет разработана на этапе детального проектирования базы данных.

6.2.1. Item (Номенклатурная позиция)

Представляет собой уникальный тип товара или материала.

 from pydantic import BaseModel, Field
from typing import Optional, List

class ItemBase(BaseModel):
name: str = Field(..., example="Буровое долото 123мм")
description: Optional[str] = Field(None, example="Долото для бурения
твёрдых пород")
sku: str = Field(..., example="BTD-123-XYZ", description="Stock Keeping
Unit - уникальный идентификатор номенклатуры")
unit_of_measure: str = Field(..., example="шт", description="Единица
измерения (шт, м, кг)")
barcode_prefix: Optional[str] = Field(None, example="4607000",
description="Префикс для генерации штрихкодов")
is_consumable: bool = Field(False, description="Является ли расходным
материалом")

class ItemCreate(ItemBase):
pass

class Item(ItemBase):
id: int

class Config:
from_attributes = True

6.2.2. Warehouse (Склад)

Представляет собой физический склад или место хранения.

from pydantic import BaseModel, Field

from typing import Optional

class WarehouseBase(BaseModel):
name: str = Field(..., example="Склад №1, г. Усинск")
location: str = Field(..., example="Усинск, ул. Промышленная, 10")
city: str = Field(..., example="Усинск")
warehouse_number: Optional[str] = Field(None, example="1")
is_active: bool = Field(True)

class WarehouseCreate(WarehouseBase):
pass

class Warehouse(WarehouseBase):
id: int

class Config:
from_attributes = True

6.2.3. Site (Участок)

Представляет собой буровой участок.

 from pydantic import BaseModel, Field
from typing import Optional

class SiteBase(BaseModel):
name: str = Field(..., example="Участок 'Северный'")
location: str = Field(..., example="Коми, Усинский район, месторождение
'Северное'")
is_active: bool = Field(True)

class SiteCreate(SiteBase):
pass

class Site(SiteBase):
id: int

class Config:
from_attributes = True

6.2.4. Brigade (Бригада)

Представляет собой буровую бригаду.

from pydantic import BaseModel, Field

from typing import Optional

class BrigadeBase(BaseModel):
name: str = Field(..., example="Бригада №5")
site_id: int = Field(..., description="ID участка, к которому прикреплена
бригада")
foreman_name: Optional[str] = Field(None, example="Иванов И.И.")
is_active: bool = Field(True)

class BrigadeCreate(BrigadeBase):
pass

class Brigade(BrigadeBase):
id: int

class Config:
from_attributes = True

6.2.5. CargoUnit (Единица груза)

Представляет собой конкретную физическую единицу товара, отслеживаемую

по штрихкоду.
 from pydantic import BaseModel, Field
from typing import Optional, Dict, Any
from datetime import datetime

class CargoUnitBase(BaseModel):
item_id: int = Field(..., description="ID номенклатурной позиции")
barcode: str = Field(..., example="4607000123456789",
description="Уникальный штрихкод единицы груза")
current_status: str = Field(..., example="На складе", description="Текущий
статус груза")
current_location_type: str = Field(..., example="warehouse",
description="Тип текущей локации (warehouse, site, brigade)")
current_location_id: int = Field(..., description="ID текущей локации
(склад, участок, бригада)")
quantity: float = Field(1.0, description="Количество (для неделимых единиц
1.0, для весовых - фактический вес)")
additional_info: Optional[Dict[str, Any]] = Field(None,
description="Дополнительная информация в формате JSON")

class CargoUnitCreate(CargoUnitBase):
pass

class CargoUnit(CargoUnitBase):
id: int
created_at: datetime
updated_at: datetime

class Config:
from_attributes = True

6.2.6. CargoStatusHistory (История статусов груза)

Запись о каждом изменении статуса груза.

from pydantic import BaseModel, Field

from datetime import datetime
from typing import Optional

class CargoStatusHistoryBase(BaseModel):
cargo_unit_id: int
old_status: Optional[str]
new_status: str
timestamp: datetime
user_id: int
location_type: Optional[str]
location_id: Optional[int]
comment: Optional[str]

class CargoStatusHistoryCreate(CargoStatusHistoryBase):
pass

class CargoStatusHistory(CargoStatusHistoryBase):
id: int

class Config:
from_attributes = True
6.3. API Endpoints (примеры)

Ниже представлены примеры RESTful API endpoints для Service Logistics и

Inventory . Полный список будет включать все CRUD операции для каждой
сущности и специфические операции.

6.3.1. Service Inventory API

POST /api/v1/items/
Описание: Создать новую номенклатурную позицию.

Request Body: ItemCreate

Response: Item

GET /api/v1/items/{item_id}
Описание: Получить информацию о номенклатурной позиции по ID.

Response: Item

GET /api/v1/items/
Описание: Получить список всех номенклатурных позиций (с
пагинацией, фильтрацией).

Response: List[Item]

6.3.2. Service Logistics API

POST /api/v1/cargo-units/receive/
Описание: Приёмка груза на склад (статус 'В пути на склад' -> 'На
складе').

Request Body: json { "barcode": "4607000123456789", "item_id": 1,

"warehouse_id": 1, "user_id": 101, "quantity": 1.0 }

Response: CargoUnit

POST /api/v1/cargo-units/transfer/
Описание: Перемещение груза между локациями (склад -> участок,
участок -> склад, склад -> склад, участок -> участок).

Request Body: json { "barcode": "4607000123456789",

"from_location_type": "warehouse", "from_location_id": 1,
 "to_location_type": "site", "to_location_id": 5, "user_id": 101,
"comment": "Перемещение на участок 'Северный'" }

Response: CargoUnit (с обновлённым статусом и локацией)

POST /api/v1/cargo-units/assign-to-brigade/
Описание: Передача груза бригаде (статус 'На участке' -> 'Передан
бригаде').

Request Body: json { "barcode": "4607000123456789", "brigade_id":

2, "user_id": 101 }

Response: CargoUnit

POST /api/v1/cargo-units/dispose/
Описание: Списание груза (статус 'Списан').

Request Body: json { "barcode": "4607000123456789", "user_id":

101, "reason": "Поломка", "comment": "Долото сломано в процессе
бурения" }

Response: CargoUnit

GET /api/v1/cargo-units/{barcode}
Описание: Получить информацию о единице груза по штрихкоду,
включая текущий статус и историю.

Response: CargoUnit (с вложенной историей статусов)

GET /api/v1/cargo-units/history/{cargo_unit_id}
Описание: Получить полную историю статусов для конкретной
единицы груза.

Response: List[CargoStatusHistory]

6.4. Логика статусов и переходов

Система будет строго контролировать переходы между статусами грузов.

Каждый переход будет инициироваться определённым действием пользователя
или системы и сопровождаться записью в историю CargoStatusHistory .

Определённые статусы грузов:

 1. Заказан: Начальный статус. Груз заказан, но ещё не отправлен или не
принят.

2. В пути на склад: Груз отправлен поставщиком и находится в процессе

доставки на центральный или региональный склад.

3. На складе [Город, №]: Груз принят на определённый склад и доступен для

дальнейших операций.

4. В пути на участок [Участок]: Груз отправлен со склада на конкретный

буровой участок.

5. На участке: Груз прибыл на буровой участок и находится на его

территории.

6. Передан бригаде [Бригада]: Груз передан конкретной буровой бригаде

для использования.

7. Списан: Груз выведен из оборота (использован, утерян, сломан и т.д.).

Примеры допустимых переходов:

Заказан -> В пути на склад (Действие: Отправка поставщиком)

В пути на склад -> На складе (Действие: Приёмка на склад)

На складе -> В пути на участок (Действие: Отгрузка на участок)

В пути на участок -> На участке (Действие: Приёмка на участке)

На участке -> Передан бригаде (Действие: Передача бригаде)

На складе -> Списан (Действие: Списание со склада)

На участке -> Списан (Действие: Списание с участка)

Передан бригаде -> Списан (Действие: Списание бригадой)

Перенаправление грузов:

Система будет поддерживать гибкое перенаправление грузов между любыми

локациями (склады, участки). Это будет реализовано через универсальную
операцию transfer , которая будет обновлять current_location_type ,
current_location_id и статус груза, при необходимости, с записью в историю.

Например: * На складе [Склад А] -> В пути на склад [Склад Б] -> На складе

[Склад Б] * На участке [Участок А] -> В пути на участок [Участок Б] -> На
участке [Участок Б] * На складе [Склад А] -> В пути на участок [Участок Б]
-> На участке [Участок Б]

Каждый такой переход будет требовать подтверждения приёмки на новой

локации, чтобы обеспечить целостность данных и прозрачность движения
грузов.

7. Проектирование пользовательских интерфейсов

и UX

Проектирование пользовательских интерфейсов (UI) и пользовательского опыта

(UX) будет ориентировано на максимальное удобство, скорость работы и
интуитивность, учитывая специфику работы на буровых участках и складах.
Будут разработаны веб-интерфейс для десктопных устройств и нативные
мобильные приложения для iOS и Android.

7.1. Основные пользовательские сценарии

Система будет поддерживать следующие ключевые пользовательские сценарии:

Приёмка груза: Сканирование штрихкода при поступлении груза на склад/

участок, автоматическое обновление статуса и местоположения.

Отгрузка/Перемещение груза: Сканирование штрихкода при отгрузке со

склада/участка, указание целевой локации, обновление статуса.

Передача груза бригаде: Сканирование штрихкода, выбор бригады,

подтверждение передачи.

Списание груза: Сканирование штрихкода, указание причины списания,

подтверждение.

Поиск и просмотр информации о грузе: Поиск по штрихкоду,

наименованию, статусу, локации; просмотр текущего статуса, истории
перемещений, характеристик.

Управление номенклатурой: Добавление, редактирование, удаление

номенклатурных позиций.

Управление складами/участками/бригадами: Добавление,

редактирование, просмотр информации о локациях.
 Управление пользователями и ролями: Создание, редактирование
пользователей, назначение ролей и прав доступа.

Формирование отчётов: Генерация отчётов по движению грузов, остаткам,

списаниям.

Инвентаризация: Проведение инвентаризации на складах/участках с

использованием сканеров.

7.2. Админ-панель и Веб-интерфейс

Веб-интерфейс будет представлять собой единую админ-панель, доступную

через браузер. Она будет оптимизирована для работы на десктопных
устройствах и обеспечит полный функционал управления системой.

Дашборд: Обзор ключевых показателей (количество грузов в пути, на

складах, списанных; последние операции; уведомления).

Разделы:
Грузы: Поиск, просмотр, редактирование информации о грузах,
история статусов, операции перемещения/списания.

Номенклатура: Управление справочником товаров.

Склады/Участки/Бригады: Управление локациями.

Пользователи и Роли: Управление доступом.

Отчёты: Инструменты для формирования и экспорта отчётов.

Настройки: Управление системными параметрами, включая

локализацию (языки, валюты).

Поиск и фильтрация: Мощные инструменты поиска и фильтрации данных

по всем ключевым параметрам.

Экспорт данных: Возможность экспорта данных в распространённые

форматы (CSV, Excel, PDF).

7.3. Мобильные приложения (iOS/Android)

Мобильные приложения будут разработаны на React Native и ориентированы на

сотрудников, работающих непосредственно с грузами на складах и участках.
Основной акцент будет сделан на скорость и удобство выполнения операций со
штрихкодами.
 Функционал сканера штрихкодов: Интеграция с камерой устройства для
быстрого и надёжного сканирования штрихкодов. Возможность
подключения внешних Bluetooth-сканеров.

Ключевые операции:
Приёмка: Сканирование, ввод количества (если применимо), выбор
локации, подтверждение.

Отгрузка/Перемещение: Сканирование, выбор целевой локации,

подтверждение.

Передача бригаде: Сканирование, выбор бригады, подтверждение.

Списание: Сканирование, выбор причины, подтверждение.

Просмотр информации о грузе: Сканирование штрихкода для

быстрого получения текущего статуса и основной информации.

Офлайн-режим (MVP+): Возможность выполнения некоторых операций в

условиях отсутствия стабильного интернет-соединения с последующей
синхронизацией данных.

Уведомления: Push-уведомления о важных событиях (например,

поступление груза, изменение статуса).

7.4. UX Принципы

Минимализм и чистота интерфейса: Избегание избыточных элементов,

фокусировка на ключевой информации.

Интуитивность: Простые и понятные рабочие процессы, минимизация

количества кликов.

Скорость: Оптимизация загрузки страниц, быстрый отклик на действия

пользователя.

Обратная связь: Чёткие сообщения об успешном выполнении операций,

ошибках, статусе загрузки.

Доступность: Учёт различных размеров экранов, контрастности, удобства

использования для людей с ограниченными возможностями (по
возможности).

Консистентность: Единый стиль и поведение элементов по всей системе

(веб и мобильные).
7.5. Этапы развития UI/UX (от MVP до продакшена)

MVP (Minimum Viable Product):

Базовый веб-интерфейс для управления номенклатурой, складами,
пользователями.

Мобильное приложение с основным функционалом сканирования для

приёмки, отгрузки, передачи бригаде и списания.

Просмотр текущего статуса груза.

Базовые отчёты.

Фаза 2 (Расширение функционала):

Полная история операций по грузам в веб-интерфейсе.

Расширенные фильтры и поиск.

Интеграция с 1С для обмена данными о номенклатуре и транзакциях.

Уведомления в мобильном приложении.

Офлайн-режим для мобильных приложений.

Фаза 3 (Оптимизация и новые возможности):

Интерактивные карты складов: Визуализация расположения грузов
на складе, маршрутов перемещения. Возможность кликать на ячейки/
зоны для просмотра содержимого. (Требует дополнительного
проектирования структуры данных для хранения топологии склада).

Интеграция с GPS-системами для отслеживания грузов в пути.

Предиктивная аналитика (например, прогнозирование потребности в

определённых материалах).

Расширенные возможности кастомизации отчётов.

Дашборды с более глубокой аналитикой.

8. Безопасность и контроль доступа

Безопасность системы является одним из критически важных аспектов,

особенно учитывая чувствительность данных о движении материальных
ценностей. Система будет соответствовать уровню безопасности Tier-3, что
подразумевает комплексный подход к защите данных на всех уровнях.
8.1. Принципы безопасности Tier-3

Tier-3 безопасность включает в себя:

Защита на уровне сети: Использование VPN для доступа к внутренним

ресурсам, фаерволы, сегментация сети, защита от DDoS-атак.

Защита на уровне приложений: Валидация входных данных, защита от

SQL-инъекций, XSS, CSRF, безопасная обработка сессий, минимизация
привилегий.

Защита на уровне данных: Шифрование данных при хранении (at rest) и

при передаче (in transit), регулярное резервное копирование и
восстановление, контроль доступа к базам данных.

Управление идентификацией и доступом (IAM): Строгая политика

управления пользователями, ролями и правами доступа.

Аудит и логирование: Детальное логирование всех значимых событий и

действий пользователей для последующего аудита и анализа инцидентов.

Регулярные аудиты безопасности и тестирование на проникновение

(пентесты).

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

Система будет использовать ролевую модель контроля доступа (RBAC), где

каждому пользователю назначается одна или несколько ролей, а каждая роль
имеет определённый набор разрешений. Это обеспечивает гибкость и
детализацию в управлении доступом.

Примеры ролей:

Администратор системы: Полный доступ ко всем функциям системы,

включая управление пользователями, ролями, системными настройками.

Менеджер склада: Доступ к операциям на складе (приёмка, отгрузка,

перемещение внутри склада, инвентаризация), просмотр номенклатуры и
отчётов по складу.

Работник склада: Выполнение операций со штрихкодами (приёмка,

отгрузка, перемещение) на закреплённом складе.
 Менеджер участка: Доступ к операциям на участке (приёмка, передача
бригаде, списание), просмотр номенклатуры и отчётов по участку.

Бригадир: Доступ к операциям по передаче/списанию грузов для своей

бригады, просмотр информации о грузах, переданных бригаде.

Бухгалтер/Финансист: Доступ к отчётам и экспорту данных для целей

учёта.

Гость/Просмотр: Только просмотр информации о грузах и отчётов без

возможности изменения данных.

Примеры разрешений (Permissions):

item:create , item:read , item:update , item:delete

warehouse:create , warehouse:read , warehouse:update , warehouse:delete

cargo_unit:receive , cargo_unit:transfer ,
cargo_unit:assign_to_brigade , cargo_unit:dispose , cargo_unit:read

user:create , user:read , user:update , user:delete

report:generate , report:export

audit_log:read

Каждая роль будет иметь определённый набор этих разрешений. Например,

Работник склада будет иметь cargo_unit:receive , cargo_unit:transfer ,
cargo_unit:read для своего склада.

8.3. Аутентификация и Авторизация

Аутентификация: Будет реализована с использованием JWT (JSON Web

Tokens). Пользователи будут аутентифицироваться, предоставляя свои
учётные данные (логин/пароль), после чего сервер выдаст JWT. Этот токен
будет использоваться для всех последующих запросов к API.
Парольная политика: Строгие требования к сложности паролей,
регулярная смена паролей, блокировка учётной записи после
нескольких неудачных попыток входа.

Двухфакторная аутентификация (2FA): Рекомендуется внедрение

2FA для повышения безопасности, особенно для административных
ролей.
 Авторизация: Каждый запрос к API будет проходить проверку авторизации
на основе JWT. Токен будет содержать информацию о ролях пользователя,
и микросервисы будут проверять наличие необходимых разрешений для
выполнения запрошенной операции.

8.4. Защита данных

Шифрование данных:
Данные в покое (Data at Rest): Все конфиденциальные данные в базах
данных (например, пароли пользователей) будут храниться в
зашифрованном виде (хеширование с солью). Рекомендуется
использовать шифрование на уровне дисков или файловой системы
для баз данных.

Данные в движении (Data in Transit): Все коммуникации между

клиентскими приложениями и API Gateway, а также между
микросервисами (если они находятся в разных сегментах сети), будут
осуществляться по защищённым протоколам (HTTPS/TLS).

Резервное копирование и восстановление: Регулярное автоматическое

резервное копирование всех баз данных и конфигурационных файлов.
Разработка и тестирование планов восстановления данных (Disaster
Recovery Plan).

Аудит и логирование: Все действия пользователей, изменения данных,

попытки входа в систему, ошибки и предупреждения будут логироваться.
Логи будут централизованно собираться и храниться в защищённом
хранилище с ограниченным доступом. Это позволит проводить аудит,
расследовать инциденты и отслеживать подозрительную активность.

8.5. Безопасность мобильных приложений

Защита API-ключей и токенов: Не хранить чувствительные данные

непосредственно в коде приложения. Использовать безопасные
хранилища (например, Keychain для iOS, Keystore для Android).

Защита от реверс-инжиниринга: Обфускация кода, использование техник

защиты от отладки.

Безопасное сетевое взаимодействие: Использование HTTPS/TLS для всех

коммуникаций с бэкендом.
 Валидация сертификатов: Проверка подлинности SSL-сертификатов
сервера для предотвращения атак типа Man-in-the-Middle.

9. Инфраструктура и DevOps стратегия

Эффективное развёртывание, управление и масштабирование системы требуют

надёжной инфраструктуры и продуманной DevOps стратегии. Мы будем
использовать современные подходы, основанные на контейнеризации и
оркестрации, для обеспечения высокой доступности, отказоустойчивости и
простоты эксплуатации.

9.1. Инфраструктура развёртывания

Контейнеризация с Docker: Все компоненты системы (микросервисы, базы

данных, брокеры сообщений и т.д.) будут упакованы в Docker-контейнеры.
Это обеспечивает изоляцию, переносимость и консистентность среды
между различными этапами разработки и продакшена.

Оркестрация с Kubernetes (K8s): Kubernetes будет использоваться для

автоматического развёртывания, масштабирования, управления и
мониторинга контейнеризированных приложений. Ключевые
преимущества использования K8s:
Автоматическое масштабирование: Горизонтальное
масштабирование микросервисов в зависимости от нагрузки.

Самовосстановление: Автоматический перезапуск упавших

контейнеров, перенос их на здоровые узлы.

Управление конфигурацией: Централизованное управление

конфигурационными файлами и секретами.

Обнаружение сервисов и балансировка нагрузки: Автоматическое

обнаружение и маршрутизация трафика между экземплярами
сервисов.

Обновления без простоя: Возможность обновлять приложения без

прерывания работы сервиса (rolling updates).

Облачная платформа (рекомендация): Для обеспечения глобального

масштабирования и высокой доступности рекомендуется использовать
облачные провайдеры, такие как Google Cloud Platform (GCP), Amazon Web
 Services (AWS) или Microsoft Azure. Они предоставляют управляемые
сервисы Kubernetes (GKE, EKS, AKS), что значительно упрощает управление
инфраструктурой.

9.2. CI/CD Pipeline

Будет реализован полностью автоматизированный конвейер непрерывной

интеграции и непрерывной доставки (CI/CD) для ускорения цикла разработки,
повышения качества кода и минимизации ошибок при развёртывании.

Инструмент: GitLab CI/CD (или Jenkins, GitHub Actions).

Этапы CI/CD:
1. Code Commit: Разработчики коммитят код в систему контроля версий
(Git).

2. Build: Автоматическая сборка кода, компиляция (если применимо),

сборка Docker-образов для каждого микросервиса.

3. Test: Запуск автоматических тестов (юнит-тесты, интеграционные

тесты, функциональные тесты, тесты безопасности).

4. Container Registry: Сохранение собранных Docker-образов в

приватном реестре контейнеров (например, Docker Hub, Google
Container Registry, AWS ECR).

5. Deploy to Staging: Автоматическое развёртывание новой версии

приложения в тестовой (staging) среде для ручного тестирования и
приёмочных испытаний.

6. Manual Approval: После успешного тестирования на staging, ручное

подтверждение для развёртывания в продакшене.

7. Deploy to Production: Развёртывание новой версии в продакшен-

среде с использованием стратегий Rolling Update или Blue/Green
Deployment для минимизации простоя.

9.3. Мониторинг и Логирование

Централизованное логирование: Все логи со всех микросервисов и

компонентов инфраструктуры будут собираться в централизованную
систему (ELK Stack: Elasticsearch для хранения и индексации, Logstash для
 сбора и обработки, Kibana для визуализации и анализа). Это позволит
быстро находить и устранять проблемы, а также проводить аудит.

Мониторинг производительности и состояния: Prometheus будет

собирать метрики со всех компонентов системы (использование CPU,
памяти, диска, сетевой трафик, количество запросов к API, задержки,
ошибки). Grafana будет использоваться для визуализации этих метрик,
создания дашбордов и настройки алертов. Будут настроены оповещения о
критических событиях (например, падение сервиса, превышение
пороговых значений).

Трассировка запросов (Distributed Tracing): Для микросервисной

архитектуры критически важна возможность отслеживать путь запроса
через несколько сервисов. Рекомендуется использовать OpenTelemetry или
Jaeger для сбора и визуализации трассировок.

9.4. Резервное копирование и восстановление (Backup & Disaster

Recovery)

Резервное копирование баз данных: Ежедневное автоматическое

резервное копирование всех баз данных с хранением копий в
географически распределённых хранилищах (например, S3-совместимые
хранилища). Будут использоваться инкрементальные и полные бэкапы.

Резервное копирование конфигураций: Все конфигурационные файлы

Kubernetes, Docker Compose, а также конфигурации приложений будут
храниться в системе контроля версий (Git) и регулярно бэкапироваться.

План восстановления после сбоев (Disaster Recovery Plan): Будет

разработан и регулярно тестироваться план действий на случай серьёзных
сбоев (например, отказ целого дата-центра). План будет включать
процедуры восстановления данных, развёртывания инфраструктуры и
приложений из резервных копий.

9.5. Масштабирование до международного уровня

Архитектура, основанная на микросервисах и Kubernetes, изначально

спроектирована для горизонтального масштабирования. Для международного
уровня будут учтены следующие аспекты:
 Географически распределённые кластеры Kubernetes: Развёртывание
кластеров в разных регионах мира для снижения задержек для
пользователей и повышения отказоустойчивости.

CDN (Content Delivery Network): Использование CDN для кэширования

статического контента (изображения, CSS, JS) ближе к конечным
пользователям.

Глобальная балансировка нагрузки: Использование глобальных

балансировщиков нагрузки для маршрутизации трафика к ближайшему
или наименее загруженному региону.

Локализация: Система будет поддерживать многоязычность и

мультивалютность через конфигурационные файлы и базу данных. Это
позволит быстро добавлять новые языки и валюты без изменения кода
приложения.
Пример структуры для локализации: json { "languages": [
{"code": "ru", "name": "Русский"}, {"code": "en", "name":
"English"}, {"code": "zh", "name": "中文"} ], "currencies": [
{"code": "RUB", "symbol": "₽", "name": "Российский рубль"},
{"code": "USD", "symbol": "$", "name": "Доллар США"}, {"code":
"EUR", "symbol": "€", "name": "Евро"} ], "translations": { "ru":
{ "item_name": "Наименование товара", "status_ordered": "Заказан"
}, "en": { "item_name": "Item Name", "status_ordered": "Ordered"
} } }

Реализация на уровне фронтенда (i18n библиотеки) и бэкенда

(хранение переводов в базе данных или конфигурационных файлах).

10. Примеры кода и технических решений

В этом разделе представлены примеры реализации ключевых аспектов системы,

таких как логика обработки статусов грузов и их перенаправления, а также
интеграция со сканерами штрихкодов.
10.1. Логика обработки статусов и перенаправления (Backend -
Python/FastAPI)

Пример реализации логики смены статуса и перемещения груза в Logistics

Service . Используется паттерн State Machine для управления переходами
статусов.
 from fastapi import APIRouter, Depends, HTTPException, status
from [Link] import Session
from datetime import datetime
from typing import Optional

from [Link] import get_db # Предполагается, что есть модуль для работы с
БД
from [Link] import CargoUnit, CargoStatusHistory, Item, Warehouse, Site,
Brigade # Модели данных
from [Link] import CargoUnitCreate, CargoUnitUpdateStatus,
CargoUnitTransfer, CargoUnitAssignBrigade, CargoUnitDispose # Схемы Pydantic

router = APIRouter()

# Определение допустимых переходов статусов

STATUS_TRANSITIONS = {
"Заказан": ["В пути на склад"],
"В пути на склад": ["На складе"],
"На складе": ["В пути на участок", "Списан", "В пути на склад"], # "В пути
на склад" для перенаправления
"В пути на участок": ["На участке"],
"На участке": ["Передан бригаде", "Списан", "В пути на участок"], # "В пути
на участок" для перенаправления
"Передан бригаде": ["Списан"],
"Списан": [] # Конечный статус
}

# Вспомогательная функция для создания записи в истории статусов

def create_status_history(db: Session, cargo_unit_id: int, old_status:
Optional[str], new_status: str, user_id: int, location_type: Optional[str] =
None, location_id: Optional[int] = None, comment: Optional[str] = None):
db_history = CargoStatusHistory(
cargo_unit_id=cargo_unit_id,
old_status=old_status,
new_status=new_status,
timestamp=[Link](),
user_id=user_id,
location_type=location_type,
location_id=location_id,
comment=comment
)
[Link](db_history)
[Link]()
[Link](db_history)
return db_history

@[Link]("/cargo-units/receive", response_model=CargoUnit)
def receive_cargo_unit(
data: CargoUnitCreate,
db: Session = Depends(get_db)
):
db_cargo_unit = [Link](CargoUnit).filter([Link] ==
[Link]).first()

if db_cargo_unit:
# Если груз уже существует, обновляем его статус
if data.current_status not in
STATUS_TRANSITIONS.get(db_cargo_unit.current_status, []):
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail=f"Недопустимый переход статуса из '{db_cargo_unit.current_status}' в
'{data.current_status}'")
 old_status = db_cargo_unit.current_status
db_cargo_unit.current_status = data.current_status
db_cargo_unit.current_location_type = data.current_location_type
db_cargo_unit.current_location_id = data.current_location_id
db_cargo_unit.quantity = [Link]
db_cargo_unit.updated_at = [Link]()
[Link]()
[Link](db_cargo_unit)
create_status_history(db, db_cargo_unit.id, old_status,
db_cargo_unit.current_status, data.user_id, data.current_location_type,
data.current_location_id, "Приёмка груза")
else:
# Если груз новый, создаем его
if data.current_status not in ["Заказан", "В пути на склад", "На
складе"]:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail=f"Недопустимый начальный статус '{data.current_status}' для нового
груза")

db_cargo_unit = CargoUnit(**data.model_dump())
[Link](db_cargo_unit)
[Link]()
[Link](db_cargo_unit)
create_status_history(db, db_cargo_unit.id, None,
db_cargo_unit.current_status, data.user_id, data.current_location_type,
data.current_location_id, "Первичная приёмка/создание груза")

return db_cargo_unit

@[Link]("/cargo-units/transfer", response_model=CargoUnit)
def transfer_cargo_unit(
data: CargoUnitTransfer,
db: Session = Depends(get_db)
):
db_cargo_unit = [Link](CargoUnit).filter([Link] ==
[Link]).first()
if not db_cargo_unit:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Груз
не найден")

old_status = db_cargo_unit.current_status
old_location_type = db_cargo_unit.current_location_type
old_location_id = db_cargo_unit.current_location_id

# Проверка допустимости перехода статуса для перенаправления

if data.to_location_type == "warehouse":
new_status = "В пути на склад"
elif data.to_location_type == "site":
new_status = "В пути на участок"
else:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail="Недопустимый тип целевой локации для перенаправления")

if new_status not in STATUS_TRANSITIONS.get(db_cargo_unit.current_status,

[]):
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail=f"Недопустимый переход статуса из '{db_cargo_unit.current_status}' в
'{new_status}' для перенаправления")

db_cargo_unit.current_status = new_status
db_cargo_unit.current_location_type = data.to_location_type
 db_cargo_unit.current_location_id = data.to_location_id
db_cargo_unit.updated_at = [Link]()
[Link]()
[Link](db_cargo_unit)

create_status_history(db, db_cargo_unit.id, old_status,

db_cargo_unit.current_status, data.user_id, old_location_type, old_location_id,
f"Начало перенаправления в {data.to_location_type} ID {data.to_location_id}")

return db_cargo_unit

@[Link]("/cargo-units/assign-to-brigade", response_model=CargoUnit)
def assign_cargo_to_brigade(
data: CargoUnitAssignBrigade,
db: Session = Depends(get_db)
):
db_cargo_unit = [Link](CargoUnit).filter([Link] ==
[Link]).first()
if not db_cargo_unit:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Груз
не найден")

if db_cargo_unit.current_status != "На участке":

raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail="Груз должен быть на участке для передачи бригаде")

old_status = db_cargo_unit.current_status
db_cargo_unit.current_status = "Передан бригаде"
db_cargo_unit.current_location_type = "brigade"
db_cargo_unit.current_location_id = data.brigade_id
db_cargo_unit.updated_at = [Link]()
[Link]()
[Link](db_cargo_unit)

create_status_history(db, db_cargo_unit.id, old_status,

db_cargo_unit.current_status, data.user_id, "brigade", data.brigade_id,
"Передан бригаде")

return db_cargo_unit

@[Link]("/cargo-units/dispose", response_model=CargoUnit)
def dispose_cargo_unit(
data: CargoUnitDispose,
db: Session = Depends(get_db)
):
db_cargo_unit = [Link](CargoUnit).filter([Link] ==
[Link]).first()
if not db_cargo_unit:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Груз
не найден")

if db_cargo_unit.current_status == "Списан":
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
detail="Груз уже списан")

old_status = db_cargo_unit.current_status
db_cargo_unit.current_status = "Списан"
db_cargo_unit.updated_at = [Link]()
[Link]()
[Link](db_cargo_unit)

create_status_history(db, db_cargo_unit.id, old_status,

 db_cargo_unit.current_status, data.user_id,
db_cargo_unit.current_location_type, db_cargo_unit.current_location_id,
[Link] + ": " + [Link])

return db_cargo_unit

# Пример получения информации о грузе

@[Link]("/cargo-units/{barcode}", response_model=CargoUnit)
def get_cargo_unit_by_barcode(
barcode: str,
db: Session = Depends(get_db)
):
db_cargo_unit = [Link](CargoUnit).filter([Link] ==
barcode).first()
if not db_cargo_unit:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Груз
не найден")
return db_cargo_unit

# Пример получения истории статусов

@[Link]("/cargo-units/history/{cargo_unit_id}",
response_model=list[CargoStatusHistory])
def get_cargo_unit_history(
cargo_unit_id: int,
db: Session = Depends(get_db)
):
history =
[Link](CargoStatusHistory).filter(CargoStatusHistory.cargo_unit_id ==
cargo_unit_id).order_by([Link]).all()
return history

10.2. Интеграция со сканерами штрихкодов (Frontend - React

Native)

Пример компонента React Native для сканирования штрихкодов с

использованием библиотеки react-native-camera (или аналогичной) и
отправки данных на бэкенд.
 import React, { useState, useEffect } from 'react';
import { View, Text, StyleSheet, Button, Alert } from 'react-native';
import { Camera } from 'react-native-camera';
import axios from 'axios'; // Для HTTP-запросов

const BarcodeScannerScreen = ({ navigation, route }) => {

const [scanning, setScanning] = useState(false);
const [cameraPermission, setCameraPermission] = useState(null);

useEffect(() => {
(async () => {
const { status } = await [Link]();
setCameraPermission(status === 'granted');
})();
}, []);

const handleBarcodeScanned = async ({ data }) => {

if (scanning) return; // Избегаем повторного сканирования

setScanning(true);
[Link]('Штрихкод отсканирован', `Данные: ${data}`, [
{ text: 'OK', onPress: () => setScanning(false) },
]);

try {
// Пример отправки данных на бэкенд
const response = await [Link]('YOUR_BACKEND_API_URL/api/v1/cargo-
units/receive', {
barcode: data,
item_id: 1, // Пример: нужно будет получить из базы или выбрать
warehouse_id: 1, // Пример: нужно будет получить из базы или выбрать
user_id: 101, // Пример: получить из контекста пользователя
current_status: 'На складе', // Пример: зависит от операции
current_location_type: 'warehouse',
current_location_id: 1,
quantity: 1.0
});
[Link]('Успешно отправлено на сервер:', [Link]);
[Link]('Успех', 'Груз успешно обработан!');
} catch (error) {
[Link]('Ошибка при отправке на сервер:', [Link] ?
[Link] : [Link]);
[Link]('Ошибка', 'Не удалось обработать груз. Попробуйте снова.');
} finally {
setScanning(false);
}
};

if (cameraPermission === null) {

return <Text>Запрос разрешения на камеру...</Text>;
}
if (cameraPermission === false) {
return <Text>Нет доступа к камере</Text>;
}

return (
<View style={[Link]}>
<Camera
style={[Link]}
onBarcodeScanned={scanning ? undefined : handleBarcodeScanned}
captureAudio={false}
 />
<View style={[Link]}>
<Text style={[Link]}>Наведите камеру на штрихкод</Text>
<View style={[Link]} />
</View>
</View>
);
};

const styles = [Link]({

container: {
flex: 1,
flexDirection: 'column',
backgroundColor: 'black',
},
overlay: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
scanText: {
fontSize: 20,
color: 'white',
marginBottom: 20,
},
rectangle: {
height: 250,
width: 250,
borderWidth: 2,
borderColor: 'white',
borderRadius: 10,
},
});

export default BarcodeScannerScreen;

Примечание: Для реального приложения потребуется более сложная логика

обработки ошибок, выбор операции (приёмка, отгрузка и т.д.) перед
сканированием, а также интеграция с состоянием приложения для получения
user_id , item_id , warehouse_id и других параметров.

11. Заключение

Данная техническая спецификация представляет собой всеобъемлющий план

по разработке современной, масштабируемой и безопасной системы складского
учёта для буровой компании. Предложенная микросервисная архитектура,
выбранный технологический стек и продуманная DevOps стратегия обеспечат
надёжную основу для успешной реализации проекта.

Система будет способна эффективно отслеживать движение грузов,

поддерживать строгий аудит операций, предоставлять удобные инструменты
для пользователей на всех уровнях и масштабироваться в соответствии с
растущими потребностями бизнеса, вплоть до международного уровня. Особое
внимание уделено безопасности данных и гибкости в интеграции с
существующими и будущими системами.

Реализация данного проекта позволит значительно повысить эффективность

управления материальными ресурсами, снизить операционные издержки и
обеспечить прозрачность всех складских операций, что является критически
важным для успешной деятельности буровой компании.