Архитектура

Это описание текущей backend-архитектуры CRM RMS: где живет бизнес-логика, как регистрируются API, как обновляются контракты и как документация должна оставаться синхронной с кодом.

---

Общая схема

Проект — Go-монолит с доменной модульностью:

• HTTP API: Gin, базовый префикс /api/v1;
• backend: internal/modules/*;
• сборка приложения и DI: internal/app;
• общие HTTP helpers: internal/transport;
• авторизация и проектные секции: internal/authorization;
• БД: PostgreSQL + SQL migrations;
• документы API: OpenAPI/Scalar, генерируются из backend metadata;
• концептуальная документация: VitePress в docs/.

HTTP request
    ↓
Gin router / middleware
    ↓
transport_http.go
    ↓
service.go
    ↓
repository_pg.go
    ↓
PostgreSQL

---

Слойность модуля

Типовой доменный модуль устроен так:

Файл	Ответственность
model.go	Доменные структуры, enum’ы, фильтры
status.go	Матрицы статусов, если lifecycle сложный
transport_http.go	HTTP routes, request DTO, binding, response shape
service.go	Бизнес-правила, валидация, workflow, интеграции
repository_pg.go	SQL и транзакционные операции PostgreSQL
*_test.go	Unit/transport/repository tests

Правило: handler не должен содержать бизнес-решение, repository не должен знать про UI-сценарий, service не должен паниковать и обязан явно возвращать ошибки.

---

Регистрация API

Все основные HTTP-модули подключаются в internal/app/app.go к группе:

api := r.Group("/api/v1")

Затем модуль получает middleware:

• auth middleware;
• permission middleware;
• иногда проектный access checker или секционный checker.

Примеры доменных групп:

• /projects, /tasks, /project-team, /team-requests;
• /equipment, /equipment-requests, /logistics, /suppliers, /locations;
• /finance, /projects/:id/budget;
• /accounts, /payments, /counterparties, /reports/...;
• /contracts, /payroll, /compensation-profiles;
• /files, /documents, /document-templates;
• /chats, /notifications, /users, /rbac, /org.

---

Контракты и документация API

OpenAPI/Scalar не пишется вручную. Артефакты строятся из backend metadata:

• internal/contractspec/spec.go;
• internal/contractspec/route_discovery.go;
• cmd/generate_contracts;
• cmd/generate_endpoints.

Основные артефакты:

• docs/assets/data/openapi.json;
• docs/public/openapi.json;
• docs/assets/data/endpoints.json;
• docs/assets/data/contracts.json;
• docs/assets/downloads/postman_collection.json;
• docs/assets/downloads/insomnia_collection.json.

Если меняется API, права, DTO или список маршрутов, нужно запускать:

go run ./cmd/generate_contracts
go run ./cmd/generate_endpoints

Если генераторы недоступны локально, обновляется source metadata и явно фиксируется, что артефакты нужно регенерировать в окружении с Go.

---

Доступы

Система использует несколько уровней доступа:

1. JWT auth (Authorization: Bearer <token>).
2. RBAC permissions через роли и персональные overrides.
3. Casbin/domain checks для отделов и объектов.
4. Project section checks для финансов, документов, файлов, логистики.
5. Доменная проверка в service: например, участник задачи, менеджер проекта, руководитель отдела.

admin — технический обход. director и system.global_read дают глобальный read, но не write-обход.

Подробнее — Security & RBAC.

---

Интеграции между модулями

Модули связаны через интерфейсы, адаптеры и сервисы в internal/app:

• логистика создает задачи логисту и финансисту через app adapters;
• командировки создают попутные задачи;
• задачи создают auto time entries при pause/finish;
• документы читают project/company/finance/requisites data;
• notifications adapters подписаны на task, chat, team request и project spec события;
• budget читает finance cost items, а не доменные таблицы напрямую.

Это сохраняет границы модулей: доменный сервис зависит от интерфейса, а конкретная сборка зависимостей находится в internal/app.

---

Правило изменения

Если меняется бизнес-поведение

Обновите соответствующую концепцию под docs/concepts/*.

Если меняется API

Обновите source metadata и сгенерированные OpenAPI/endpoints artifacts.

Если меняется БД

Добавьте migration. Изменение схемы без миграции считается незавершенным.

Если меняется доступ

Обновите docs/concepts/security-rbac.md и, если нужно, docs/rbac_matrix.md.

---

Практический ориентир

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

• сначала объяснить процесс простыми словами;
• затем показать реальные backend слои и endpoint-ы;
• перечислить статусы и важные бизнес-правила;
• отдельно описать frontend-поведение;
• не дублировать полную OpenAPI-схему, если она уже есть в Scalar.