Онбординг: Nimbus — биллинговая система ЖКХ

Документ для Junior-разработчика (в т.ч. с использованием AI-инструментов). Содержит общую суть проекта, стек, жёсткие архитектурные правила и структуру репозитория.

1. Суть проекта и стек

Nimbus — облачная платформа для автоматизации управления жилищно-коммунальным хозяйством (ЖКХ). Целевая аудитория: управляющие компании (УК), ТСЖ, ЖСК.

Основные возможности (целевые):

Управление организациями, домами, помещениями, лицевыми счетами, собственниками
Учёт услуг ЖКХ, тарифов, нормативах, счётчиков (ИПУ/ОДПУ) и показаний
Начисления по правилам Постановления Правительства № 354 (расчёт коммунальных услуг)
Платежи, долги, пени
Отчётность, интеграции (в т.ч. ГИС ЖКХ)

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

Слой	Технологии
Backend	Go 1.22+, Gin, GORM, PostgreSQL, Redis, JWT, Zap
Сервисы	Микросервисы: `auth-service`, `core-service`, `billing-service`
Frontend	React, TypeScript, Vite, MUI v7, React Router v7, Recharts
DevOps	Docker, Docker Compose, Caddy, Prometheus, Grafana

Базы данных (отдельная БД на сервис):

nimbus_auth — пользователи, роли, сессии (auth-service)
nimbus_core — организации, дома, помещения, ЛС, услуги, справочники (core-service)
nimbus_billing — начисления, счета, задания расчёта (billing-service)

Порты сервисов: Auth 8001, Core 8002, Billing 8003.

2. Жёсткие архитектурные правила

Эти правила нельзя нарушать даже при подсказках AI. Они касаются финансовой и нормативной корректности.

2.1 Учёт и балансы (Ledger / двойная запись)

Никогда не использовать UPDATE для изменения балансов лицевых счетов.
Баланс (долг/переплата) — производная величина. Менять её можно только через двойную запись (будущая модель JournalEntry: дебет/кредит).
Текущая реализация: в коде Ledger ещё нет; в документации (docs/architecture/billing_core_architecture.md, Инструкции/DEBT_AND_PENALTY_ARCHITECTURE.md) описаны принципы и модели AccountBalance, DebtItem, JournalEntry (будущее).
История начислений и показаний неизменяема.
Не редактировать и не удалять фактические начисления и показания. Допускаются только корректирующие проводки (в рамках Ledger), а не правка старых записей.
Аудит: у всех значимых сущностей должны быть created_at, updated_at; для финансовых операций — кто и когда внёс изменение.

2.2 Постановление № 354 (ПП 354)

Логика расчёта по ПП 354 неприкосновенна.
Формулы расчёта коммунальных услуг (по счётчикам, нормативам, ОДН, отопление, ГВС и т.д.) заданы законодательством. Их нельзя упрощать или менять «для удобства».
Где живёт ПП 354 в коде:
- core-service: internal/models/utility_service.go — CalculationFormulaCode (например pp354_formula_1, pp354_formula_1_or_4), UtilityServiceFormulaFlags; миграции/сиды в internal/database/migrate_utility_services.go.
- frontend: форма и отображение услуг ЖКХ с кодами формул ПП 354 (например frontend/src/crud-dashboard/components/utility-service/).
Не трогать без явного ТЗ:
- Формулы и коды расчёта в utility_service.go и в сидах.
- Ядро движка начислений в billing-service (когда оно будет реализовано).
  Допустимые задачи: CRUD по справочникам, UI для выбора формулы без изменения самой логики расчёта.

2.3 Микросервисы и данные

core-service — источник правды по организациям, домам, помещениям, лицевым счетам, услугам, тарифам, счётчикам, справочникам.
Billing использует их по ID (например personalAccountId, houseServiceId), не дублирует мастер-данные.
billing-service — только начисления, счета, задания расчёта, позже — Ledger/проводки. Не хранит копии справочников для расчёта; запрашивает или получает события из core.
Не дублировать бизнес-логику расчёта между сервисами. Расчёт по ПП 354 — в одном месте (billing / будущий расчётный движок).

2.4 Безопасность и API

Все state-changing операции защищаются CSRF (в core-service используется csrfMiddleware).
Чувствительные данные (платежи, персональные данные) не логировать в открытом виде.
Внешние вызовы (например DaData) — через backend-прокси, не с фронтенда с секретами.

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

nimbus/
├── frontend/                    # React SPA (Vite, TypeScript, MUI)
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── api.ts               # API-клиент к backend
│   │   ├── contexts/            # Auth и др. контексты
│   │   ├── crud-dashboard/      # CRUD-интерфейсы (организации, дома, ЛС, услуги и т.д.)
│   │   │   ├── components/      # Компоненты по сущностям (organization, house, room, owner, billing…)
│   │   │   ├── data/            # API-слой для CRUD (organizations, houses, personal-accounts…)
│   │   │   └── hooks/
│   │   ├── dashboard/          # Основной дашборд приложения, страницы, меню
│   │   ├── sign-in/
│   │   ├── shared-theme/
│   │   └── utils/
│   └── package.json
│
├── services/                    # Микросервисы (Go)
│   ├── auth-service/            # Аутентификация, авторизация, пользователи, роли
│   │   ├── cmd/server/main.go
│   │   └── internal/            # config, database, handlers, models, logger, metrics
│   ├── core-service/            # Организации, дома, помещения, ЛС, услуги, справочники, тестовые данные
│   │   ├── cmd/server/main.go
│   │   ├── internal/
│   │   │   ├── handlers/        # REST API (organizations, houses, rooms, meters, utility_services…)
│   │   │   ├── models/         # Модели (в т.ч. UtilityService с формулами ПП 354)
│   │   │   ├── database/       # migrate.go, seed_*, миграции
│   │   │   └── ...
│   │   └── migrations/          # SQL-миграции (например 001_room_owners.sql)
│   └── billing-service/         # Начисления, счета, задания расчёта (движок в разработке)
│       ├── cmd/server/main.go
│       └── internal/            # handlers, models (Bill, Charge, CalculationJob), database, storage (S3)
│
├── docs/                        # Документация (см. docs/index.md)
│   ├── architecture/            # Архитектура биллинга, пеней и т.д.
│   ├── business/                # Стейкхолдеры, дорожная карта, стратегия
│   ├── guides/                  # Онбординг, задачи Junior, версионирование
│   ├── prompts/                 # Эталонные промпты для Cursor/AI
│   └── index.md                 # Навигация по документации
├── Инструкции/                  # Внутренние инструкции, анализ ПП 354, долги/пени, ГИС ЖКХ
├── scripts/                     # Скрипты (seed, генерация тестовых данных, dev)
├── deploy/                      # Caddy, конфигурация развёртывания
├── monitoring/                  # Prometheus, Grafana
├── docker-compose.yml           # Монолит/основной вариант
├── docker-compose.microservices.yml
├── Makefile
└── README.md

Важно: в корне нет папки backend/ — весь backend разнесён по services/*. В README.md может упоминаться старый layout; ориентироваться на структуру выше.

Запуск для разработки:

Микросервисы: ./scripts/dev-start.sh или docker-compose -f docker-compose.microservices.yml up -d
Frontend: cd frontend && npm install && npm run dev (порт 5173, прокси к API)
Подробнее: README.md, services/README.md, Инструкции/DEV_QUICK_START.md

4. Полезные ссылки внутри репозитория

Документ	Назначение
README.md	Обзор продукта, быстрый старт, переменные окружения
docs/architecture/billing_core_architecture.md	Ядро биллинга: ЛС, связи, Golden Test, двойная запись
Инструкции/DEBT_AND_PENALTY_ARCHITECTURE.md	Долг, пени, ставки, модели (AccountBalance, DebtItem и др.)
services/README.md	Порты, БД, статус микросервисов
docs/business/roadmap_3m.md	Дорожная карта на 3 месяца
junior_tasks.md	Рекомендованные задачи для Junior без изменения ядра расчётов

При использовании AI (например Cursor) всегда проверяй, что предложенные изменения не нарушают разделы 2.1–2.4. В сомнительных случаях — уточнять у Tech Lead / CTO.

Онбординг: Nimbus — биллинговая система ЖКХ ​

1. Суть проекта и стек ​

2. Жёсткие архитектурные правила ​

2.1 Учёт и балансы (Ledger / двойная запись) ​

2.2 Постановление № 354 (ПП 354) ​

2.3 Микросервисы и данные ​

2.4 Безопасность и API ​

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

4. Полезные ссылки внутри репозитория ​