From 3830144269d1e9950832355646e7b7ef215f2153 Mon Sep 17 00:00:00 2001 From: emelinda Date: Thu, 20 Aug 2026 18:39:24 +0300 Subject: [PATCH] Expand architecture documentation: add detailed descriptions for `ams-sync` and `resources` components, update their Archimate models, and correct inter-service relationships. --- docs/architecture/app-docs.md | 16 ++++++++++ docs/architecture/app-summaries.md | 8 +++++ .../architecture/example-technology.archimate | 30 +++++++++---------- docs/architecture/example-technology.xml | 30 +++++++++---------- docs/architecture/preview.html | 2 +- 5 files changed, 55 insertions(+), 31 deletions(-) diff --git a/docs/architecture/app-docs.md b/docs/architecture/app-docs.md index fa5c044..6881bb7 100644 --- a/docs/architecture/app-docs.md +++ b/docs/architecture/app-docs.md @@ -6,6 +6,14 @@ Конкретные домены заменены на `<домен>` — файл коммитится в репозиторий и не должен содержать данных инсталляции. +## ams-sync + +Репозитории: platform/ams-sync — синхронизация учётных записей с внешним провайдером идентификации; рядом лежит platform/ams без активности с апреля 2025. Стек: Python, чистая архитектура (`cmd` → `internal/app` → `controller` → `usecase` → `adapter`/`repository`), kafka-python (`KafkaConsumer`), requests с ретраями, PyJWT, pydantic-settings; адаптеры к Zitadel Management API v1 и к generic/sarex-backend как провайдеру аутентификации. + +Компонент переносит учётные записи из Django-монолита во внешний провайдер идентификации: пользователь, заведённый или изменённый в платформе, автоматически появляется и обновляется в AMS (Access Management Service) вместе с профилем, e-mail, принадлежностью организации и метаданными, на которых затем строится авторизация в доменных сервисах. Работает в двух режимах — постоянный сервис, читающий Kafka-топик `ams-sync` и обрабатывающий события по одному, и консольный режим массовой миграции пользователей и компаний, использовавшийся при первичном переезде на Zitadel. + +Технически организация в Zitadel выбирается по конфигурации хоста, импорт идёт через `/management/v1/users/human/_import` для одиночных пользователей и `/admin/v1/import` для батчей, следом устанавливаются метаданные учётной записи. Отсутствующие имя и фамилия подставляются заглушками, то есть компонент рассчитан на импорт неполных легаси-данных. Проверка живости — TCP, HTTP-эндпоинтов сервис не публикует и входящих вызовов от других компонентов не принимает; этим объясняется его отсутствие в графе межсервисных вызовов, выведенном из манифестов. + ## attachments Репозитории: pdm/attachments — REST-сервис хранения и выдачи файловых вложений. Стек: Python, FastAPI, Pydantic, PostgreSQL (psycopg2 + пул соединений, сырой SQL), SQLAlchemy/Alembic для схемы и миграций, S3 через boto3 (presigned URL), OpenTelemetry, JSON-логирование. @@ -240,6 +248,14 @@ cde-api построен на чистой архитектуре с явным Технически это микрофронтенд-модуль, экспортируемый в host-приложение со своим провайдером и MobX-стором и порталами для встраивания панелей, общающийся по HTTP через общий `httpService` с сервисом issues. На стороне бэкенда работают модели замечания, его изменений, типа, статусов и их связей, прав на переход и на тип, вложений, комментариев и записей атрибутов. Права строятся на JWT и наборе разрешений просмотра, редактирования, администрирования и надзора, дополнительно уточняемых на уровне типа замечания и сервисных аккаунтов. Атрибуты вынесены в собственную EAV-модель, синхронизируемую с внешним сервисом EAV миграцией первичного импорта и management-командой. Асинхронная часть — Celery-задачи уведомлений, синхронизации с OLAP-сервисом, публикации событий в Kafka и фоновой генерации больших экспортов с сохранением файлов в S3. При переносе компонента в модель ArchiMate стоит явно зафиксировать, что «remarks» и «issues» — это один бэкенд и два имени, иначе связи между элементами получатся дублирующими. +## resources + +Репозитории: platform/sarex-resources — бэкенд реестра ресурсов; planning/resources-frontend — интерфейс. Стек: Python, Django 4.1–5.1 + DRF, django-filter, model_utils, PostgreSQL с расширением ltree и PostGIS, requests + pydantic для HTTP-клиента к сервису пользователей, админка Django. + +Компонент ведёт единый реестр ресурсов платформы — иерархию объектов строительства (проект, объект, участок и далее вниз по дереву) с типами, географическим положением, кодами и правами доступа. Идентификатор ресурса (`resource_id`, `public_id`) служит сквозным ключом проекта во всех остальных сервисах, а сам реестр — общей точкой проверки прав: к нему привязываются права пользователей и сервисных аккаунтов, права на уровне компании, фотографии, состав проектной команды, график работ по проекту и идентификаторы виджетов планирования. По графу вызовов контура к нему обращаются documentations, flows, issues, pm, processing, rfi и transmittal; по коду компонентных репозиториев — также inspections, contracts, prescriptions и projects. + +Технически дерево хранится в PostgreSQL с расширением ltree: в проекте есть собственное приложение `apps.ltree` с полем `LTreeField` и lookup'ами для запросов по поддереву, а координаты объекта ведутся через `django.contrib.gis` поверх PostGIS. Мультиарендность обеспечивается hash-индексами по `tenant_id` и сервисному аккаунту, у моделей — мягкое удаление и таймстампы через миксины. API опубликован в двух версиях (`urls.py` и `urls_v2.py` с расширенным `ResourceExpandedViewSet`). Брокеров сообщений в коде нет: интеграция со смежными сервисами только синхронная, по HTTP. + ## reviews Репозитории: proc/reviews-frontend — микрофронтенд рабочего места согласующего; proc/flows-backend — бэкенд маршрутов согласования; proc/flows-frontend — UI конструктора маршрутов; proc/export-reviews — сервис экспорта отчётов по согласованиям. Отдельного репозитория `reviews-backend` не существует. Стек: фронтенд — TypeScript, React, MobX, rsbuild + Module Federation, внутренний `sdk-js`, Helm; бэкенд — см. компонент flows (FastAPI, SQLAlchemy, PostgreSQL, Kafka через FastStream, Celery, sqladmin). diff --git a/docs/architecture/app-summaries.md b/docs/architecture/app-summaries.md index 43f7a08..66cd5c1 100644 --- a/docs/architecture/app-summaries.md +++ b/docs/architecture/app-summaries.md @@ -4,6 +4,10 @@ Заголовок второго уровня — имя каталога в `apps/` либо идентификатор элемента для компонентов, которых в `apps/` нет. Порядок соответствует дереву на схеме. +## ams-sync + +Односторонняя синхронизация учётных записей из ядра платформы во внешний провайдер идентификации: созданный или изменённый пользователь вместе с профилем, принадлежностью организации и метаданными появляется в Zitadel, где на этих данных строится авторизация доменных сервисов. Работает консьюмером Kafka-топика, отдельный консольный режим использовался для первичной массовой миграции пользователей и компаний. Входящих вызовов не принимает. + ## attachments Универсальное хранилище файловых вложений к любым сущностям платформы: файл кладётся в S3, метаданные — в PostgreSQL, привязка полиморфная («имя модели + идентификатор экземпляра»). Скачивание идёт по временным подписанным ссылкам напрямую из объектного хранилища. @@ -116,6 +120,10 @@ Пользовательский модуль работы с замечаниями (UI): пин на чертеже, в ячейке XLSX или на задаче графика, описание, срок, ответственные, вложения и пометки поверх листа, табличное и списочное представления, фильтры, массовое редактирование и экспорт. Собственный бэкенд архивирован — модуль работает поверх issues. +## resources + +Единый реестр ресурсов платформы — иерархия объектов строительства (проект, объект, участок и ниже) с типами, географическим положением, кодами и правами доступа. Идентификатор ресурса служит сквозным ключом проекта во всех остальных сервисах, а сам реестр — общей точкой проверки прав, поэтому это один из самых востребованных компонентов контура. Интеграция только синхронная, по HTTP. + ## reviews Рабочее место согласующего: очередь задач с приоритетами и сроками, просмотр документа, пометки и замечания, заполнение чек-листов и вынесение решения (согласовано / с замечаниями / отклонено). Ключевой этап между выпуском версии документа и выдачей её «в производство работ»; бэкенд общий с flows. diff --git a/docs/architecture/example-technology.archimate b/docs/architecture/example-technology.archimate index c875c4c..dc3635e 100644 --- a/docs/architecture/example-technology.archimate +++ b/docs/architecture/example-technology.archimate @@ -5,7 +5,7 @@ - apps/ams-sync/<contour>/ + Односторонняя синхронизация учётных записей из ядра платформы во внешний провайдер идентификации: созданный или изменённый пользователь вместе с профилем, принадлежностью организации и метаданными появляется в Zitadel, где на этих данных строится авторизация доменных сервисов. Работает консьюмером Kafka-топика, отдельный консольный режим использовался для первичной массовой миграции пользователей и компаний. Входящих вызовов не принимает. Универсальное хранилище файловых вложений к любым сущностям платформы: файл кладётся в S3, метаданные — в PostgreSQL, привязка полиморфная («имя модели + идентификатор экземпляра»). Скачивание идёт по временным подписанным ссылкам напрямую из объектного хранилища. @@ -92,7 +92,7 @@ Пользовательский модуль работы с замечаниями (UI): пин на чертеже, в ячейке XLSX или на задаче графика, описание, срок, ответственные, вложения и пометки поверх листа, табличное и списочное представления, фильтры, массовое редактирование и экспорт. Собственный бэкенд архивирован — модуль работает поверх issues. - apps/resources/<contour>/ + Единый реестр ресурсов платформы — иерархия объектов строительства (проект, объект, участок и ниже) с типами, географическим положением, кодами и правами доступа. Идентификатор ресурса служит сквозным ключом проекта во всех остальных сервисах, а сам реестр — общей точкой проверки прав, поэтому это один из самых востребованных компонентов контура. Интеграция только синхронная, по HTTP. Рабочее место согласующего: очередь задач с приоритетами и сроками, просмотр документа, пометки и замечания, заполнение чек-листов и вынесение решения (согласовано / с замечаниями / отклонено). Ключевой этап между выпуском версии документа и выдачей её «в производство работ»; бэкенд общий с flows. @@ -898,47 +898,47 @@ - + - + - + - + - + - + - + + + + + + - + - - - - - diff --git a/docs/architecture/example-technology.xml b/docs/architecture/example-technology.xml index 377147d..13bc498 100644 --- a/docs/architecture/example-technology.xml +++ b/docs/architecture/example-technology.xml @@ -7,7 +7,7 @@ ams-sync - apps/ams-sync/<contour>/ + Односторонняя синхронизация учётных записей из ядра платформы во внешний провайдер идентификации: созданный или изменённый пользователь вместе с профилем, принадлежностью организации и метаданными появляется в Zitadel, где на этих данных строится авторизация доменных сервисов. Работает консьюмером Kafka-топика, отдельный консольный режим использовался для первичной массовой миграции пользователей и компаний. Входящих вызовов не принимает. attachments @@ -123,7 +123,7 @@ resources - apps/resources/<contour>/ + Единый реестр ресурсов платформы — иерархия объектов строительства (проект, объект, участок и ниже) с типами, географическим положением, кодами и правами доступа. Идентификатор ресурса служит сквозным ключом проекта во всех остальных сервисах, а сам реестр — общей точкой проверки прав, поэтому это один из самых востребованных компонентов контура. Интеграция только синхронная, по HTTP. reviews @@ -795,34 +795,34 @@ - - + + - + - + - + - + - + - + - - - - - + + + + + diff --git a/docs/architecture/preview.html b/docs/architecture/preview.html index 1b57086..d79701a 100644 --- a/docs/architecture/preview.html +++ b/docs/architecture/preview.html @@ -52,7 +52,7 @@ -documentationsdjangoflowsprocessingeavissuesresourcespm

A2. Зависят от: django

К django обращаются 18 сервисов.

+documentationsdjangoflowsprocessingeavresourcesissuespm

A2. Зависят от: django

К django обращаются 18 сервисов.