Обзор микросервисов

Nimbus — это облачная SaaS‑платформа для автоматизации управления ЖКХ, построенная как набор Go‑микросервисов с чётким разделением ответственности.

• nimbus_auth (auth-service)
  Отвечает за аутентификацию и авторизацию:

  • управление пользователями и ролями (УК, оператор, бухгалтер, администратор);
  • выдача и проверка JWT‑токенов;
  • единая точка проверки прав для всех бэкендов.

• nimbus_core (core-service)
  Доменно‑справочный и операционный контур:

  • организации, дома, помещения (Room/House), собственники (Owner);
  • лицевые счета (PersonalAccount) и базовые параметры (площади, категории, льготы);
  • справочники для форм UI (виды помещений, типы счётчиков, формы собственности и т.д.);
  • API для CRUD‑операций в админке и подготовка данных для биллинга.

• nimbus_billing (billing-service)
  Расчётное ядро и финансовый контур:

  • услуги дома (HouseService), тарифы и нормативы;
  • расчёт начислений (Charge) по ПП 354;
  • ставки пеней (PenaltyRate) и ежедневный пересчёт пеней;
  • журнал проводок Ledger (ledger_entries) и кэш балансов (account_balances);
  • технические задачи: синхронизация ключевой ставки ЦБ, массовое применение расчётных циклов (BillingCycle).

• Bank Integrator
  Финансовый хаб для обмена с банками:

  • приём и разбор банковских выписок/реестров в текстовом формате 1С (клиент‑банк);
  • унифицированный парсер, который превращает строки выписок в внутренние события «платёж по ЛС»;
  • API‑клиенты к банкам для прямой интеграции (polling/webhook) и получения статусов платежей;
  • запись результатов в billing-service (создание платежей и Ledger‑проводок) по безопасному внутреннему API.

• GIS Integration Gateway
  Compliance‑модуль для двустороннего обмена с ГИС ЖКХ:

  • выгрузка в ГИС ЖКХ данных по домам, ЛС, начислениям, показаниям и услугам с учётом настроек в nimbus_core;
  • загрузка оплат, статусов обработок и связанных справочников из ГИС ЖКХ;
  • нормализация/валидация данных и прокси‑слой между внутренней моделью Nimbus и внешними XML/JSON‑форматами.

Справочники и объекты, к которым обращается UI (дома, помещения, ЛС, услуги), лежат в nimbus_core. Вся сложная финансовая логика (начисления, пени, Ledger) сконцентрирована в nimbus_billing. Авторизация и сессии вынесены в nimbus_auth.

Последовательность: от создания ЛС до первого начисления

Ниже показан упрощённый путь запроса: от пользователя в веб‑интерфейсе до появления первой записи в Ledger и учёта банковского платежа.

Где «живут» справочники и расчётное ядро

• Справочники и «паспортная» часть данных:

  • nimbus_core хранит структуру жилищного фонда (Organization, House, Room, Owner, PersonalAccount) и доменные справочники;
  • эти данные используются как источники истины для UI и для расчётного ядра.

• Расчётное ядро и финансы:

  • nimbus_billing не дублирует доменную модель, а ссылается на ЛС и услуги через идентификаторы;
  • все движения по долгам проходят через LedgerEntry (иммутабельный журнал проводок);
  • AccountBalance выступает оптимизированным представлением текущего состояния по ЛС и всегда может быть восстановлен из Ledger.

Такое разделение позволяет:

• эволюционировать доменную модель (core-service) без риска сломать финансовый контур;
• независимо масштабировать billing-service под тяжёлые расчётные задачи;
• подвести под Ledger жёсткие аудит‑требования (неизменяемая история, только INSERT).