Ты в роли профессионального backend разработчика с навыками в проектировании и системной…
- User
Ты в роли профессионального backend разработчика с навыками в проектировании и системной аналитике. Твоя задача составить документ для реализации API сервиса MSM по описанию ниже. В документе должно бтыь минимум кода.
# Техническое задание на разработку системы для хранения информации о поверках средств измерений ## 1. Общее описание и цели проекта ### 1.1. Цель проекта Разработка системы для автоматизации процессов регистрации, учета и хранения информации о поверках средств измерений (СИ), выпущенных предприятием, с возможностью интеграции с ФГИС "АРШИН" и внутренней PDM-системой. ### 1.2. Назначение системы - Автоматизация работы с заявками на поверку средств измерений - Регистрация и хранение данных о проведенных поверках - Отслеживание статусов поверок - Взаимодействие с ФГИС "АРШИН" для выгрузки результатов поверок - Исключение ошибок при внесении данных о поверках - Сбор и хранение информации об эталонных средствах измерений ### 1.3. Пользователи системы - Администратор – полный доступ ко всем функциям системы - Метролог/поверитель – проведение поверок, создание заявок, доступ только к своим данным ## 2. Функциональные требования ### 2.1. Управление средствами измерений (СИ) - Регистрация СИ, получаемых из PDM-системы - Хранение информации о СИ (тип, серийный номер, модификация и т.д.) - Отслеживание статуса СИ (новое, в поверке, поверено, забраковано) - Отображение истории поверок для каждого СИ - Отображение информации об актуальной поверке СИ ### 2.2. Управление заявками на поверку - Создание заявок на поверку СИ - Отслеживание статуса заявок - Регистрация входного контроля СИ - Планирование даты проведения поверки - Указание адреса доставки/отправки - Выделение заявок с приближающимися дедлайнами ### 2.3. Проведение поверок - Регистрация результатов поверок для различных типов СИ - Фиксация использованных эталонных средств измерений - Запись условий проведения поверки (температура, давление, влажность) - Регистрация положительных и отрицательных результатов - Фиксация специфичных для LPIT параметров поверки: - Номинальная нагрузка - Калибровочные коэффициенты по току и напряжению - Фазовые коэффициенты - Результаты тестов (HV-тест, изоляция, ток, напряжение) ### 2.4. Управление эталонными средствами измерений - Регистрация эталонных СИ с указанием их типа - Отслеживание сроков действия поверок эталонных СИ - Указание области применимости эталонов (для каких типов СИ подходят) - Хранение информации о поверках эталонных СИ ### 2.5. Интеграция с ФГИС "АРШИН" - Формирование данных для выгрузки в АРШИН - Генерация XML-файлов по установленному формату - Выгрузка данных о поверках через API АРШИН - Получение данных из АРШИН (номера документов поверки и т.д.) - Отслеживание статуса выгрузки в АРШИН - Фиксация номера и даты документа поверки из АРШИН ### 2.6. Отчетность - Формирование отчетов о проведенных поверках - Статистика по типам СИ и результатам поверок - Выгрузка данных в форматах XML, Excel - Отчеты по плановым и выполненным поверкам ## 3. Нефункциональные требования ### 3.1. Производительность - Система должна поддерживать одновременную работу необходимого количества пользователей - Время отклика системы при выполнении основных операций не должно превышать 2 секунды - Система должна обеспечивать обработку пиковых нагрузок в период массовых поверок ### 3.2. Масштабируемость - Архитектура должна предусматривать возможность горизонтального масштабирования - Система должна поддерживать добавление новых типов СИ (например, PSU) без изменения архитектуры ### 3.3. Надежность - Обеспечение отказоустойчивости при сбоях внешних систем - Механизм восстановления прерванных операций - Регулярное резервное копирование данных ### 3.4. Безопасность - Аутентификация пользователей через Keycloak - Разграничение прав доступа по ролям - Аудит действий пользователей с фиксацией ключевых операций - Защита от основных типов атак (XSS, CSRF, SQL Injection) - Шифрование чувствительных данных ### 3.5. Технологический стек - Backend: Python, FastAPI, SQLAlchemy 2.0 - База данных: PostgreSQL - Асинхронная обработка запросов - Интеграция с шиной данных/очередью сообщений для получения данных из PDM ## 4. Модель данных ### 4.1. Основные сущности #### 4.1.1. MeasurementInstrumentType (Тип средства измерения) - id - первичный ключ - mi_type_number - номер из государственного реестра средств измерений - mi_type_name - наименование типа - doc_title - методика поверки #### 4.1.2. MeasurementInstrument (Средство измерения) - id - первичный ключ - entity_type_id - тип измерительного устройства (LPIT, PSU и т.д.) - pdm_id - идентификатор в PDM-системе - mi_type_id - тип средства измерения - verif_res_id - актуальная проведенная поверка #### 4.1.3. ReferenceInstrument (Эталонное средство измерения) - id - первичный ключ - suitable_type_id - тип СИ, для которого подходит эталон - mi_type_id - тип эталонного средства измерения - verification_num - номер поверки - verification_date - дата поверки - verification_valid_date - дата окончания действия поверки #### 4.1.4. VerificationResult (Результат поверки) - id - первичный ключ - prev_id - ссылка на предыдущую поверку - verification_num - номер поверки - verification_date - дата поверки - verification_valid_date - дата до которой действительна поверка - sign_pass - наличие знака поверки в паспорте - sign_mi - наличие знака поверки на СИ - mi_owner_id - владелец СИ - metrologist_id - метролог, проводивший поверку - verification_type_id - тип поверки - test_bench_id - испытательный стенд - mi_reference_id - использованное эталонное СИ - arshin_uploaded - статус выгрузки в АРШИН - arshin_upload_date - дата выгрузки в АРШИН - arshin_document_number - номер документа в АРШИН #### 4.1.5. LpitVerificationRecord (Запись о поверке LPIT) - id - первичный ключ - rated_burden_cv - номинальная нагрузка - acf_current - калибровочный коэффициент по току - pcf_current - фазовый коэффициент по току - acf_voltage - калибровочный коэффициент по напряжению - pcf_voltage - фазовый коэффициент по напряжению - result_hv_test - результат HV-теста - result_insulation_test - результат теста изоляции - current_tests - значения проведенных испытаний по току - voltage_tests - значения проведенных испытаний по напряжению - result_current_tests - результат испытаний по току - result_voltage_tests - результат испытаний по напряжению - temperature - температура при проведении - pressure - давление при проведении - humidity - влажность при проведении #### 4.1.6. Metrologist (Метролог) - id - первичный ключ - sign_cipher - условный шифр знака поверки - lastname - фамилия - firstname - имя - snils - СНИЛС #### 4.1.7. VerificationType (Тип поверки) - name - наименование (Первичная, Очередная, Внеочередная) #### 4.1.8. TestBench (Испытательный стенд) - id - первичный ключ - name - наименование - serial_number - серийный номер #### 4.1.9. MIAcceptance (Заявка на поверку) - id - первичный ключ - mi_instance_id - средство измерения - acceptance_number - номер заявки - acceptance_date - дата заявки - pass_entry_control - пройден ли входной контроль - transfer_date - дата передачи/отправки - shipping_address - адрес доставки #### 4.1.10. User (Пользователь) - id - первичный ключ - username - имя пользователя - email - электронная почта - role - роль (администратор, метролог) - keycloak_id - идентификатор пользователя в Keycloak #### 4.1.11. AuditLog (Журнал аудита) - id - первичный ключ - user_id - пользователь, выполнивший действие - action_type - тип действия - entity_type - тип сущности - entity_id - идентификатор сущности - timestamp - время действия - details - детали действия (JSON) ## 5. Бизнес-процессы ### 5.1. Регистрация нового СИ 1. Создание записи о СИ в PDM-системе 2. Передача данных через шину данных/очередь сообщений в MSM 3. Создание записи о новом СИ в MSM 4. Уведомление о создании нового СИ ### 5.2. Создание заявки на поверку 1. Выбор СИ из списка 2. Ввод данных заявки (номер, дата, адрес доставки) 3. Отметка о прохождении входного контроля 4. Сохранение заявки ### 5.3. Проведение поверки 1. Выбор заявки на поверку 2. Выбор эталонных СИ и испытательного стенда 3. Проведение измерений и испытаний 4. Ввод результатов поверки 5. Установка статуса поверки (пройдена/не пройдена) 6. Сохранение результатов поверки 7. Обновление статуса СИ ### 5.4. Выгрузка данных в АРШИН 1. Выбор поверок для выгрузки 2. Формирование XML-файла 3. Отправка данных в АРШИН через API 4. Получение подтверждения и номера документа 5. Обновление статуса выгрузки 6. Сохранение номера документа из АРШИН ### 5.5. Обработка данных из АРШИН 1. Получение данных из АРШИН 2. Сопоставление с существующими записями 3. Обновление информации о поверках ## 6. Интеграции с внешними системами ### 6.1. Интеграция с PDM - Получение данных о новых СИ через шину данных/очередь сообщений - Обработка сообщений о создании новых СИ - Запрос дополнительных данных через API PDM при необходимости ## 7. Безопасность и разграничение доступа ### 7.1. Роли и права доступа - **Администратор**: - Полный доступ ко всем функциям системы - Управление пользователями - Редактирование справочников - Просмотр и редактирование всех данных - Выгрузка данных в АРШИН - **Метролог**: - Создание заявок на поверку - Проведение поверок - Просмотр и редактирование только своих поверок - Просмотр справочников - Невозможность редактирования данных других метрологов ### 7.2. Аутентификация и авторизация - Интеграция с Keycloak для управления пользователями - Проверка прав доступа на уровне API - Защита от несанкционированного доступа ## 10. Архитектурные решения ### 10.1. Общая архитектура - Многослойная архитектура с выделением слоев: - Слой доступа к данным - Слой бизнес-логики - Слой API - Слой интеграции с внешними системами ### 10.2. Обработка сообщений - Использование шины данных/очереди сообщений для интеграции с PDM - Асинхронная обработка сообщений - Механизмы повторных попыток при сбоях ### 10.3. API - RESTful API для взаимодействия с клиентами - Документированный API с использованием OpenAPI - Версионирование API для обеспечения обратной совместимости ## 13. Терминология - **ФГИС "АРШИН"** - федеральная государственная информационная система для учёта и хранения сведений о результатах поверки средств измерений - **PDM** - система управления данными о продукции - **LPIT** - измерительный трансформатор - **PSU** - блок питания (будущий тип СИ) - **Метролог** - специалист, проводящий поверку средств измерений - **СИ** - средство измерения - **Поверка** - совокупность операций по определению метрологических характеристик средства измерений - **Эталон** - эталонное средство измерения, используемое при поверке - Assistant
Документ по реализации API сервиса MSM (Measurement and Storage Management)
1. Введение
1.1. Цель документа
Этот документ предназначен для описания архитектуры, дизайна и реализации API сервиса MSM (система для хранения информации о поверках средств измерений). Он основан на предоставленном техническом задании (ТЗ) и охватывает ключевые аспекты проектирования backend-части системы. Документ фокусируется на системной аналитике, архитектурных решениях и интеграциях, минимизируя использование кода. Он предназначен для backend-разработчиков, системных аналитиков и заинтересованных сторон для обеспечения согласованной реализации.
1.2. Обзор системы
Система MSM предназначена для автоматизации процессов регистрации, учета и хранения данных о поверках средств измерений (СИ), с интеграцией с ФГИС "АРШИН" и внутренней PDM-системой. API-сервис будет реализован на основе многослойной архитектуры, используя стек технологий: Python, FastAPI для API, SQLAlchemy 2.0 для ORM и PostgreSQL в качестве базы данных. Основные цели включают обеспечение производительности, безопасности и масштабируемости, как указано в нефункциональных требованиях ТЗ.
1.3. Предполагаемые читатели
- Backend-разработчики: Для реализации API и бизнес-логики.
- Системные аналитики: Для понимания взаимодействия компонентов.
- Администраторы: Для настройки и мониторинга системы.
2. Архитектурные решения
2.1. Общая архитектура
Система будет построена по многослойной архитектуре, как описано в разделе 10.1 ТЗ:
- Слой доступа к данным: Включает взаимодействие с PostgreSQL через SQLAlchemy. Все операции с данными (CRUD) будут абстрагированы для обеспечения изоляции от бизнес-логики.
- Слой бизнес-логики: Реализует правила и процессы, такие как валидация данных, расчет статусов поверок и обработка бизнес-процессов (например, регистрация СИ или выгрузка в АРШИН). Этот слой будет использовать сервисы для оркестрации операций.
- Слой API: RESTful API на базе FastAPI, обеспечивающий взаимодействие с клиентами. API будет документировано с использованием OpenAPI для автоматической генерации спецификации.
- Слой интеграции: Обеспечивает асинхронное взаимодействие с внешними системами, такими как PDM (через шину данных/очередь сообщений) и ФГИС "АРШИН" (через API). Для асинхронной обработки будут использованы очереди сообщений.
Эта архитектура обеспечивает разделение обязанностей, что способствует масштабируемости и удобству тестирования.
2.2. Масштабируемость и производительность
- Горизонтальное масштабирование: Архитектура предусматривает развертывание нескольких экземпляров API-сервера за балансировщиком нагрузки. База данных может быть масштабирована с использованием репликации или шардинга PostgreSQL.
- Обработка пиковых нагрузок: Система будет использовать асинхронную обработку запросов для поддержки одновременной работы пользователей. Время отклика не должно превышать 2 секунды, как указано в разделе 3.1 ТЗ, что достигается оптимизацией запросов и кэшированием часто запрашиваемых данных.
- Добавление новых типов СИ: Дизайн будет модульным, позволяя расширять модель данных (например, для типов как PSU) без изменения основной архитектуры, путем добавления новых сущностей или полей.
2.3. Обработка сообщений и асинхронные операции
На основе раздела 10.2 ТЗ, интеграция с PDM будет реализована через шину данных или очередь сообщений (например, RabbitMQ или Kafka). Асинхронные задачи, такие как обработка входящих сообщений о новых СИ или выгрузка в АРШИН, будут управляться с механизмами повторных попыток для обеспечения надежности.
3. Модель данных
3.1. Обзор
Модель данных основана на разделе 4 ТЗ и будет реализована с использованием SQLAlchemy. Она включает основные сущности, такие как MeasurementInstrument, VerificationResult и другие, для хранения информации о СИ, поверках и заявках. Связи между сущностями (например, MeasurementInstrument связан с VerificationResult через verif_res_id) обеспечат целостность данных.
3.2. Ключевые принципы
- Нормализация: Данные будут нормализованы для минимизации избыточности, с использованием внешних ключей для связей.
- Расширение: Для специфичных типов СИ (например, LPIT) будут использованы связанные таблицы, такие как LpitVerificationRecord, для хранения дополнительных атрибутов.
- Аудит: Все изменения будут логироваться в таблице AuditLog для обеспечения traceability, как указано в разделе 7 ТЗ.
4. Дизайн API
4.1. Общие принципы
API будет RESTful, с версионированием (например, /v1/endpoint), как описано в разделе 10.3 ТЗ. Каждый endpoint будет поддерживать стандартные HTTP-методы (GET, POST, PUT, DELETE) и возвращать JSON-ответы. Авторизация будет реализована через Keycloak, с проверкой ролей на уровне endpoint.
4.2. Endpoints по функциональным требованиям
Ниже приведено описание ключевых endpoints, сгруппированных по разделам ТЗ. Для каждого указаны метод, путь, параметры и ожидаемые ответы. Это не код, а текстовое описание.
4.2.1. Управление средствами измерений (Раздел 2.1 ТЗ)
- GET /v1/measurement-instruments: Получение списка СИ. Параметры: фильтры по типу, статусу, pdm_id. Ответ: список объектов с атрибутами id, entity_type_id, mi_type_id, статусом и историей поверок.
- POST /v1/measurement-instruments: Регистрация нового СИ (из PDM). Параметры: данные из очереди сообщений (pdm_id, mi_type_id и т.д.). Ответ: Созданный объект СИ с назначенным id.
- GET /v1/measurement-instruments/{id}/history: Получение истории поверок для конкретного СИ. Параметры: id СИ. Ответ: Список связанных VerificationResult.
- PUT /v1/measurement-instruments/{id}: Обновление статуса СИ (например, "в поверке"). Доступно только для администраторов.
4.2.2. Управление заявками на поверку (Раздел 2.2 ТЗ)
- POST /v1/verification-requests: Создание заявки. Параметры: mi_instance_id, acceptance_date, shipping_address, pass_entry_control. Ответ: Созданная заявка с id.
- GET /v1/verification-requests: Получение списка заявок. Параметры: фильтры по статусу, дедлайнам. Ответ: Список заявок с деталями.
- PUT /v1/verification-requests/{id}: Обновление заявки (например, отметка о прохождении входного контроля). Доступно для метрологов.
4.2.3. Проведение поверок (Раздел 2.3 ТЗ)
- POST /v1/verification-results: Регистрация результатов поверки. Параметры: данные о СИ, эталонах, условиях (температура, давление), специфичные для LPIT (номинальная нагрузка, коэффициенты). Ответ: Созданный VerificationResult с id.
- GET /v1/verification-results/{id}: Получение деталей поверки. Параметры: id. Ответ: Объект с результатами, включая связанные записи (например, LpitVerificationRecord).
4.2.4. Управление эталонными средствами (Раздел 2.4 ТЗ)
- POST /v1/reference-instruments: Регистрация эталонного СИ. Параметры: suitable_type_id, mi_type_id, verification_valid_date. Ответ: Созданный объект.
- GET /v1/reference-instruments: Получение списка эталонов с фильтрами по срокам действия.
4.2.5. Интеграция с ФГИС "АРШИН" (Раздел 2.5 ТЗ)
- POST /v1/arshin/export: Формирование и выгрузка данных в АРШИН. Параметры: список id поверок. Процесс: Генерация XML, отправка через API АРШИН, обновление статуса. Ответ: Статус операции и номер документа.
- GET /v1/arshin/status/{id}: Получение статуса выгрузки. Параметры: id поверки. Ответ: Текущий статус и детали.
4.2.6. Отчетность (Раздел 2.6 ТЗ)
- GET /v1/reports/verifications: Генерация отчета о поверках. Параметры: фильтры по типам СИ, датам. Ответ: Данные в формате JSON, с опцией экспорта в XML или Excel через заголовки.
4.3. Обработка ошибок и валидация
Все endpoints будут включать валидацию входных данных (например, проверку наличия обязательных полей). Ошибки будут возвращаться в формате JSON с HTTP-кодами (400 для валидации, 401 для аутентификации).
5. Бизнес-процессы и интеграции
5.1. Поддержка бизнес-процессов
API будет интегрировать процессы из раздела 5 ТЗ:
- Регистрация нового СИ: Асинхронная обработка сообщений из PDM, вызывающая POST /v1/measurement-instruments.
- Создание заявки: Через POST /v1/verification-requests, с уведомлениями для пользователей.
- Проведение поверки: Последовательность вызовов endpoint'ов для выбора заявки, ввода результатов и обновления статусов.
- Выгрузка в АРШИН: Автоматизированный процесс через POST /v1/arshin/export, с отслеживанием в AuditLog.
5.2. Интеграции с внешними системами
- PDM (Раздел 6.1 ТЗ): Получение данных через очередь сообщений. API будет включать endpoint для обработки входящих событий.
- ФГИС "АРШИН": Взаимодействие через внешний API для выгрузки XML и получения подтверждений. Механизмы повторных попыток обеспечат отказоустойчивость.
6. Безопасность
6.1. Аутентификация и авторизация
На основе раздела 7 ТЗ:
- Keycloak: Все запросы будут требовать JWT-токен для аутентификации.
- Разграничение доступа: Endpoint'ы будут проверять роли (администратор или метролог). Например, только администраторы могут вызывать endpoint'ы для управления пользователями.
- Аудит: Каждое действие будет логироваться в AuditLog, включая тип действия и детали.
6.2. Защита
- От атак: Реализация мер против XSS, CSRF и SQL Injection через валидацию входных данных и использование безопасных библиотек.
- Шифрование: Чувствительные данные (например, номера поверок) будут шифроваться в базе данных.
7. Заключение
Этот документ предоставляет всестороннее руководство по реализации API сервиса MSM, основанное на ТЗ. Он охватывает архитектуру, дизайн API, интеграции и безопасность, обеспечивая основу для разработки. Рекомендуется провести ревью с заинтересованными сторонами перед началом реализации для уточнения деталей. В случае изменений в ТЗ, документ должен быть обновлен соответственно.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.