@ssoeasy-dev/proto 1.1.1-beta.1 → 1.1.1-beta.10

package/README.md

@@ -1,228 +1,171 @@
-# SSO Easy - Protocol Buffers
+# SSO Easy — Protocol Buffers
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Централизованный репозиторий Protocol Buffers контрактов для SSO Easy микросервисной архитектуры.
 
-## 📦 Установка
+## Пространства имён
 
-### Go
+| Пакет          | Сервисы                                         | Потребители                 |
+| -------------- | ----------------------------------------------- | --------------------------- |
+| `auth.v1`      | AuthService, VerificationService                | `auth.api`, `auth.svc`      |
+| `companies.v1` | CompanyService, EmployeeService, ServiceService | `auth.api`, `companies.svc` |
+| `common.v1`    | Общие типы (StatusResponse и др.)               | все сервисы                 |
 
-```bash
-go get github.com/ssoeasy-dev/proto@latest
-```
-
-Или конкретная версия:
+## Структура проекта
 
-```bash
-go get github.com/ssoeasy-dev/proto@v1.0.0
 ```
-
-### NPM
-
-```bash
-npm install @ssoeasy-dev/proto
+.
+├── proto/                   # Исходные .proto файлы
+│   ├── auth/v1/             # AuthService, VerificationService
+│   ├── companies/v1/        # CompanyService, EmployeeService, ServiceService
+│   └── common/v1/           # Общие типы
+├── gen/go/                  # Сгенерированный Go код (коммитится)
+│   ├── auth/v1/
+│   ├── companies/v1/
+│   └── common/v1/
+├── gen/ts/                  # Сгенерированный TypeScript код (коммитится)
+│   ├── index.ts
+│   ├── index.auth.ts
+│   ├── index.companies.ts
+│   └── index.common.ts
+├── buf.yaml
+├── buf.gen.yaml             # Генерация Go кода
+├── buf.gen.ts.yaml          # Генерация TypeScript кода
+├── go.mod
+├── package.json
+├── Makefile
+├── workflow.md              # Процесс работы с изменениями и релизами
+└── README.md
 ```
 
-Или конкретная версия:
+## Использование в сервисах
 
-```bash
-npm install @ssoeasy-dev/proto@1.0.0
-```
+### `auth.svc` и `companies.svc` (Go)
 
-Для pre-release версий (beta, rc):
+Подключение в `go.mod`:
 
-```bash
-npm install @ssoeasy-dev/proto@1.0.0-beta.1
+```go
+require github.com/ssoeasy-dev/proto v1.1.1
 ```
 
-## 🚀 Использование
-
-### Импорт в Go проект
+Импорт в коде:
 
 ```go
-package main
-
 import (
-    pb "github.com/ssoeasy-dev/proto/gen/go/companies/v1"
-    "google.golang.org/grpc"
+    authpb    "github.com/ssoeasy-dev/proto/gen/go/auth/v1"
+    companiespb "github.com/ssoeasy-dev/proto/gen/go/companies/v1"
+    commonpb  "github.com/ssoeasy-dev/proto/gen/go/common/v1"
 )
-
-func main() {
-    conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
-    defer conn.Close()
-    
-    client := pb.NewCompanyServiceClient(conn)
-    // Используйте client...
-}
 ```
 
-### Импорт в TypeScript/JavaScript проект
-
-```typescript
-import { CompanyServiceClient } from '@ssoeasy-dev/proto/companies';
-import { CredentialServiceClient } from '@ssoeasy-dev/proto/auth';
-import { EmployeeAttributeServiceClient } from '@ssoeasy-dev/proto/abac';
+Обновление до последней версии:
 
-// Используйте клиенты...
+```bash
+go get github.com/ssoeasy-dev/proto@latest
+go mod tidy
 ```
 
-## 🛠️ Разработка
-
-### Требования
-
-- Go 1.24+
-- Node.js 20+ (для TypeScript генерации и npm публикации)
-- pnpm (для управления npm зависимостями)
-- [Buf CLI](https://buf.build/docs/installation)
+### `auth.api` (TypeScript / NestJS)
 
-### Установка Buf
+Подключение в `package.json`:
 
-```bash
-# macOS
-brew install bufbuild/buf/buf
-
-# Linux
-curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-$(uname -s)-$(uname -m)" \
-  -o "/usr/local/bin/buf"
-chmod +x /usr/local/bin/buf
-
-# Или через Go
-make install-tools
+```json
+"dependencies": {
+  "@ssoeasy-dev/proto": "1.1.1"
+}
 ```
 
-### Команды
+Импорт в коде:
 
-```bash
-make help              # Показать все команды
-make generate          # Сгенерировать весь код (Go + TypeScript)
-make generate-go       # Сгенерировать только Go код
-make generate-ts       # Сгенерировать только TypeScript код
-make lint              # Проверить proto файлы на ошибки
-make format            # Отформатировать proto файлы
-make breaking          # Проверить breaking changes
-make clean             # Очистить сгенерированные файлы
-make tag VERSION=v1.0.0  # Создать git тег для релиза
-make sync-version      # Синхронизировать версию package.json с git тегом
-make publish-npm       # Опубликовать npm пакет (автоматически синхронизирует версию)
-```
+```typescript
+// gRPC клиенты для auth.svc
+import {
+  AuthServiceClient,
+  VerificationServiceClient,
+} from "@ssoeasy-dev/proto/auth";
 
-### Структура проекта
+// gRPC клиенты для companies.svc
+import {
+  CompanyServiceClient,
+  ServiceServiceClient,
+} from "@ssoeasy-dev/proto/companies";
 
-```
-.
-├── proto/                          # Исходные .proto файлы
-│   ├── common/v1/                 # Общие типы
-│   ├── <group>/<version>/         # Протофайлы
-│   └── gateway/v1/                # Gateway
-├── gen/go/                        # ✅ Сгенерированный Go код (коммитится!)
-│   ├── common/v1/
-│   ├── <group>/<version>/
-│   └── gateway/v1/
-├── gen/ts/                        # ✅ Сгенерированный TypeScript код (коммитится!)
-│   ├── common/v1/
-│   ├── <group>/<version>/
-│   └── index.ts
-├── scripts/                       # Скрипты для автоматизации
-│   └── sync-version.sh           # Скрипт синхронизации версии
-├── buf.yaml                       # Конфигурация Buf
-├── buf.gen.yaml                   # Генерация Go кода
-├── buf.gen.ts.yaml                # Генерация TypeScript кода
-├── go.mod                         # Go модуль
-├── package.json                   # NPM пакет конфигурация
-├── Makefile                       # Команды разработки
-└── README.md
+// Общие типы
+import { StatusResponse } from "@ssoeasy-dev/proto/common";
 ```
 
-## 📝 Workflow изменений
+Подключение gRPC-клиентов через NestJS ClientsModule — см. `src/infra/grpc/grpc.module.ts` в `auth.api`.
 
-### 1. Изменение proto файлов
+Обновление:
 
 ```bash
-# Отредактировать proto файл
-vim proto/companies/v1/company.proto
+pnpm add @ssoeasy-dev/proto@latest
+```
 
-# Проверить стиль
-make lint
+## Разработка
 
-# Отформатировать
-make format
+### Требования
 
-# Проверить breaking changes
-make breaking
-```
+- Go 1.24+
+- Node.js 20+
+- pnpm
+- [Buf CLI](https://buf.build/docs/installation)
 
-### 2. Генерация кода
+### Установка инструментов
 
 ```bash
-# Сгенерировать весь код (Go + TypeScript)
-make generate
-
-# Или отдельно
-make generate-go   # Только Go
-make generate-ts   # Только TypeScript
-
-# Проверить что все работает
-go mod tidy
-pnpm install
+make install-tools
 ```
 
-### 3. Коммит и релиз
+### Команды
 
 ```bash
-# Закоммитить изменения (proto + gen/)
-git add proto/ gen/
-git commit -m "feat: add new field to Company"
-git push origin main
-
-# Создать релиз (создаст git тег)
-make tag VERSION=v1.1.0
-
-# GitHub Actions автоматически:
-# - Создаст GitHub Release
-# - Опубликует npm пакет с версией из тега
-# - Go модуль будет доступен через git тег
+make generate     # Сгенерировать весь код (Go + TypeScript)
+make generate-go  # Только Go
+make generate-ts  # Только TypeScript
+make lint         # Проверить proto файлы
+make format       # Отформатировать proto файлы
+make breaking     # Проверить breaking changes относительно main
+make clean        # Очистить gen/
 ```
 
-**Важно:** Версия npm пакета автоматически синхронизируется с git тегом при публикации через GitHub Actions. Версия в `package.json` обновляется автоматически из git тега (без префикса `v`).
-
-## 🔄 Обновление зависимости в проектах
-
-### Go проекты
+### Добавление нового proto файла
 
 ```bash
-# В вашем микросервисе
-cd <Микросервис>
+# 1. Создать файл в нужном пространстве имён
+vim proto/auth/v1/my_service.proto
 
-# Обновить до последней версии
-go get github.com/ssoeasy-dev/proto@latest
+# 2. Проверить и отформатировать
+make format && make lint
 
-# Или до конкретной версии
-go get github.com/ssoeasy-dev/proto@v1.2.0
+# 3. Сгенерировать код
+make generate
 
-go mod tidy
+# 4. Закоммитить proto и сгенерированный код вместе
+git add proto/ gen/
+git commit -m "feat: add MyService"
 ```
 
-### TypeScript/JavaScript проекты
+> **Важно:** всегда коммитьте `proto/` и `gen/` вместе. CI проверяет их синхронизацию.
 
-```bash
-# Обновить до последней версии
-npm install @ssoeasy-dev/proto@latest
-# или
-pnpm add @ssoeasy-dev/proto@latest
+## Релизы
 
-# Или до конкретной версии
-npm install @ssoeasy-dev/proto@1.2.0
+Подробный процесс — в [workflow.md](./workflow.md). Кратко:
 
-# Для pre-release версий
-npm install @ssoeasy-dev/proto@1.2.0-beta.1
-```
+| Событие                              | Результат                                                              |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| Открытие / обновление PR в `develop` | dev версия `v1.1.1-dev-{branch}.N`                                     |
+| Закрытие PR в `develop`              | dev версия удаляется                                                   |
+| Мерж в `develop`                     | beta версия `v1.1.1-beta.N`                                            |
+| Мерж в `main`                        | production версия из `package.json`, публикация в npm с тегом `latest` |
 
-## 📄 Лицензия
+## Лицензия
 
-MIT License - см. [LICENSE](LICENSE) файл.
+MIT — см. [LICENSE](LICENSE).
 
-## 📞 Контакты
+## Контакты
 
+- Email: morewiktor@yandex.ru
+- Telegram: [@MoreWiktor](https://t.me/MoreWiktor)
 - GitHub: [@MoreWiktor](https://github.com/MoreWiktor)
-- Проект: [https://github.com/ssoeasy-dev/proto](https://github.com/ssoeasy-dev/proto)