@ticket_for_cinema/contracts 1.0.0

package/gen/auth.ts

@@ -0,0 +1,50 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v1.181.2
+//   protoc               v3.21.12
+// source: auth.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "auth.v1";
+
+/** указываем версию протобуфера */
+
+export interface SendOtpRequest {
+  /** менять номер нельзя, чтоб не было рассинхронизации данных */
+  identifier: string;
+  type: string;
+}
+
+export interface SendOtpResponse {
+  ok: boolean;
+}
+
+export const AUTH_V1_PACKAGE_NAME = "auth.v1";
+
+export interface AuthServiceClient {
+  sendOtp(request: SendOtpRequest): Observable<SendOtpResponse>;
+}
+
+export interface AuthServiceController {
+  sendOtp(request: SendOtpRequest): Promise<SendOtpResponse> | Observable<SendOtpResponse> | SendOtpResponse;
+}
+
+export function AuthServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["sendOtp"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("AuthService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("AuthService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const AUTH_SERVICE_NAME = "AuthService";

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ticket_for_cinema/contracts",
+  "version": "1.0.0",
+  "description": "Contracts for microservices",
+  "scripts": {
+    "generate": "protoc -I ./proto ./proto/*.proto --ts_proto_out=./gen --ts_proto_opt=nestJs=true,package=omit"
+  },
+  "files": [
+    "proto",
+    "gen"
+  ],
+  "dependencies": {
+    "@nestjs/microservices": "^11.1.11",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "ts-proto": "^1.176.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/proto/auth.proto

@@ -0,0 +1,17 @@
+syntax = "proto3"; // указываем версию протобуфера
+
+package auth.v1; // указываем пакет тут указываем доменную область
+
+service AuthService {
+    rpc SendOtp (SendOtpRequest) returns (SendOtpResponse);
+
+}
+
+message SendOtpRequest {
+  string identifier = 1; // менять номер нельзя, чтоб не было рассинхронизации данных
+  string type = 2;
+}
+
+message SendOtpResponse {
+  bool ok = 1;
+}

package/proto/redme.md

@@ -0,0 +1,521 @@
+# Конспект по Protocol Buffers (proto файлам) для gRPC
+
+## Что такое .proto файл?
+
+`.proto` файл - это файл описания данных и сервисов для gRPC. Он определяет:
+
+- **Структуру сообщений** (какие данные передаются)
+- **Сервисы и методы** (какие операции можно выполнять)
+- **Типы данных** (какие типы полей используются)
+
+Из `.proto` файла генерируется код на разных языках программирования (TypeScript, Go, Python и т.д.)
+
+---
+
+## Базовая структура .proto файла
+
+```protobuf
+syntax = "proto3";                    // Версия Protocol Buffers (всегда используй proto3)
+
+package auth.v1;                      // Пакет - организация кода (как namespace)
+
+// Сообщение (структура данных)
+message SendOtpRequest {
+  string identifier = 1;              // Поле: тип название = номер
+  string type = 2;
+}
+
+// Сервис (набор методов)
+service AuthService {
+  rpc SendOtp(SendOtpRequest) returns (SendOtpResponse);  // Метод
+}
+```
+
+---
+
+## 1. Синтаксис и пакет
+
+### `syntax = "proto3"`
+
+- Указывает версию Protocol Buffers
+- Всегда используй `proto3` (самая новая версия)
+
+### `package auth.v1`
+
+- Организует код в пространство имен
+- Помогает избежать конфликтов имен
+- Формат: `название.версия` (например, `auth.v1`, `user.v2`)
+
+---
+
+## 2. Сообщения (Messages)
+
+Сообщения - это структуры данных (как классы или интерфейсы)
+
+```protobuf
+message User {
+  string name = 1;      // Поле 1: имя пользователя
+  int32 age = 2;        // Поле 2: возраст
+  bool is_active = 3;   // Поле 3: активен ли
+}
+```
+
+### Важно про номера полей:
+
+- Каждое поле имеет **уникальный номер** (1, 2, 3...)
+- Номера **нельзя менять** после релиза (иначе сломается совместимость)
+- Номера 1-15 занимают 1 байт (используй для частых полей)
+- Номера 16-2047 занимают 2 байта
+
+---
+
+## 3. Типы данных
+
+### Скалярные типы (простые):
+
+| Proto тип | Описание                          | Пример           |
+| --------- | --------------------------------- | ---------------- |
+| `string`  | Строка                            | `"Привет"`       |
+| `int32`   | Целое число 32-бит                | `42`             |
+| `int64`   | Целое число 64-бит                | `1234567890`     |
+| `uint32`  | Беззнаковое целое 32-бит          | `100`            |
+| `uint64`  | Беззнаковое целое 64-бит          | `9999`           |
+| `bool`    | Булево значение                   | `true` / `false` |
+| `float`   | Число с плавающей точкой          | `3.14`           |
+| `double`  | Число с плавающей точкой (точнее) | `3.14159265`     |
+| `bytes`   | Бинарные данные                   | `[0x01, 0x02]`   |
+
+### Пример:
+
+```protobuf
+message Product {
+  string name = 1;           // "iPhone"
+  double price = 2;          // 999.99
+  int32 quantity = 3;        // 10
+  bool in_stock = 4;         // true
+  bytes image = 5;           // бинарные данные картинки
+}
+```
+
+---
+
+## 4. Повторяющиеся поля (массивы)
+
+Используй `repeated` для массивов:
+
+```protobuf
+message ShoppingCart {
+  repeated string items = 1;        // Массив строк: ["яблоко", "банан"]
+  repeated int32 quantities = 2;    // Массив чисел: [5, 3]
+}
+```
+
+---
+
+## 5. Вложенные сообщения
+
+Можно использовать одно сообщение внутри другого:
+
+```protobuf
+message Address {
+  string city = 1;
+  string street = 2;
+}
+
+message User {
+  string name = 1;
+  Address address = 2;      // Вложенное сообщение
+}
+```
+
+---
+
+## 6. Enum (перечисления)
+
+Для фиксированного набора значений:
+
+```protobuf
+enum Status {
+  STATUS_UNSPECIFIED = 0;   // Всегда начинай с 0 и _UNSPECIFIED
+  STATUS_PENDING = 1;
+  STATUS_APPROVED = 2;
+  STATUS_REJECTED = 3;
+}
+
+message Order {
+  string id = 1;
+  Status status = 2;        // Использование enum
+}
+```
+
+**Важно:** Первое значение enum всегда должно быть `0` и называться `НАЗВАНИЕ_UNSPECIFIED`
+
+---
+
+## 7. Опциональные поля
+
+В proto3 все поля опциональны по умолчанию. Если поле не задано, оно имеет значение по умолчанию:
+
+- `string` → `""`
+- `int32` → `0`
+- `bool` → `false`
+
+Если нужно явно указать, что поле опционально:
+
+```protobuf
+message User {
+  string name = 1;
+  optional string nickname = 2;  // Может быть null
+}
+```
+
+---
+
+## 8. Сервисы (Services)
+
+Сервис - это набор RPC методов (удаленных вызовов)
+
+```protobuf
+service UserService {
+  // Простой вызов: один запрос → один ответ
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+
+  // Server streaming: один запрос → много ответов
+  rpc ListUsers(ListUsersRequest) returns (stream User);
+
+  // Client streaming: много запросов → один ответ
+  rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse);
+
+  // Bidirectional streaming: много запросов ↔ много ответов
+  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
+}
+```
+
+### Типы методов:
+
+1. **Unary (обычный)** - один запрос, один ответ
+
+   ```protobuf
+   rpc SendOtp(SendOtpRequest) returns (SendOtpResponse);
+   ```
+
+2. **Server streaming** - один запрос, много ответов (стрим)
+
+   ```protobuf
+   rpc WatchOrders(WatchRequest) returns (stream Order);
+   ```
+
+3. **Client streaming** - много запросов (стрим), один ответ
+
+   ```protobuf
+   rpc UploadFile(stream FileChunk) returns (UploadResponse);
+   ```
+
+4. **Bidirectional streaming** - стрим в обе стороны
+   ```protobuf
+   rpc Chat(stream Message) returns (stream Message);
+   ```
+
+---
+
+## 9. Импорты
+
+Можно импортировать другие .proto файлы:
+
+```protobuf
+import "google/protobuf/timestamp.proto";
+import "common/types.proto";
+
+message Post {
+  string title = 1;
+  google.protobuf.Timestamp created_at = 2;  // Использование импортированного типа
+}
+```
+
+---
+
+## 10. Комментарии
+
+```protobuf
+// Однострочный комментарий
+
+/*
+  Многострочный
+  комментарий
+*/
+
+message User {
+  string name = 1;  // Комментарий к полю
+}
+```
+
+---
+
+## 11. Полный пример .proto файла
+
+```protobuf
+syntax = "proto3";
+
+package shop.v1;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/any.proto";
+
+// Перечисление статусов заказа
+enum OrderStatus {
+  ORDER_STATUS_UNSPECIFIED = 0;
+  ORDER_STATUS_PENDING = 1;
+  ORDER_STATUS_PAID = 2;
+  ORDER_STATUS_SHIPPED = 3;
+  ORDER_STATUS_DELIVERED = 4;
+}
+
+// Сообщение: товар
+message Product {
+  string id = 1;
+  string name = 2;
+  double price = 3;
+  int32 stock = 4;
+  google.protobuf.Timestamp created_at = 5; // время создания, но перед этим импортировать google.protobuf.Timestamp
+  google.protobuf.Duration duration = 6; // длительность, но перед этим импортировать google.protobuf.Duration
+  google.protobuf.Struct metadata = 7; // метаданные (структура json внутри протобуфера), но перед этим импортировать google.protobuf.Struct
+}
+
+// Сообщение: заказ
+message Order {
+  string id = 1;
+  string user_id = 2;
+  repeated Product products = 3;    // Массив товаров
+  OrderStatus status = 4;           // Статус из enum
+  double total_price = 5;
+}
+
+// Запрос на создание заказа
+message CreateOrderRequest {
+  string user_id = 1;
+  repeated string product_ids = 2;
+}
+
+// Ответ на создание заказа
+message CreateOrderResponse {
+  Order order = 1;
+  bool success = 2;
+  string message = 3;
+}
+
+// Сервис для работы с заказами
+service OrderService {
+  // Создать заказ
+  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
+
+  // Получить заказ по ID
+  rpc GetOrder(GetOrderRequest) returns (Order);
+
+  // Получить список всех заказов (стрим)
+  rpc ListOrders(ListOrdersRequest) returns (stream Order);
+}
+```
+
+---
+
+## 12. Лучшие практики
+
+### ✅ Делай так:
+
+- Всегда используй `syntax = "proto3"`
+- Называй пакеты в формате `название.v1`, `название.v2`
+- Первое значение enum всегда `0` и `_UNSPECIFIED`
+- Используй `snake_case` для полей: `user_name`, `created_at`
+- Используй `PascalCase` для сообщений: `UserProfile`, `CreateOrderRequest`
+- Добавляй комментарии к сложным полям
+
+### ❌ Не делай так:
+
+- Не меняй номера полей после релиза
+- Не удаляй поля (помечай как `reserved` если нужно)
+- Не используй `required` (в proto3 его нет)
+- Не используй одинаковые номера для разных полей
+
+---
+
+## 13. Зарезервированные поля
+
+Если нужно удалить поле, но сохранить его номер:
+
+```protobuf
+message User {
+  reserved 2, 5 to 10;              // Зарезервированные номера
+  reserved "old_field", "deleted";  // Зарезервированные имена
+
+  string name = 1;
+  int32 age = 3;
+  // Поле 2 удалено, но номер зарезервирован
+}
+```
+
+---
+
+## 14. Как использовать .proto файлы
+
+1. **Создай .proto файл** с описанием данных и сервисов
+2. **Сгенерируй код** с помощью компилятора `protoc`:
+   ```bash
+   protoc --go_out=. --go-grpc_out=. auth.proto
+   ```
+3. **Используй сгенерированный код** в своем приложении
+
+---
+
+## Резюме
+
+- `.proto` файл описывает структуру данных и API для gRPC
+- **Messages** - структуры данных (как классы)
+- **Services** - наборы методов (API)
+- **Типы данных**: `string`, `int32`, `bool`, `repeated` и др.
+- **Enum** - перечисления фиксированных значений
+- **Номера полей** - уникальные и неизменяемые
+- **4 типа RPC**: unary, server streaming, client streaming, bidirectional
+
+---
+
+## 15. Команда генерации TypeScript кода
+
+### Команда:
+
+```bash
+protoc -I ./proto ./proto/*.proto --ts_proto_out=./gen --ts_proto_opt=nestJs=true,package=omit
+```
+
+### Разбор команды по частям:
+
+| Параметр               | Описание                           | Пример                            |
+| ---------------------- | ---------------------------------- | --------------------------------- |
+| `protoc`               | Компилятор Protocol Buffers        | Основная программа                |
+| `-I ./proto`           | Папка с .proto файлами (include)   | Ищет файлы в папке `./proto`      |
+| `./proto/*.proto`      | Все .proto файлы для обработки     | `auth.proto`, `user.proto` и т.д. |
+| `--ts_proto_out=./gen` | Выходная папка для TypeScript кода | Генерирует файлы в папке `./gen`  |
+| `--ts_proto_opt=...`   | Опции генерации                    | Настройки формата кода            |
+
+### Опции генерации:
+
+| Опция          | Что делает                          | Пример                                             |
+| -------------- | ----------------------------------- | -------------------------------------------------- |
+| `nestJs=true`  | Генерирует код совместимый с NestJS | Декораторы `@GrpcMethod()`                         |
+| `package=omit` | Пропускает префикс пакета в именах  | Вместо `auth.v1.SendOtpRequest` → `SendOtpRequest` |
+
+### Что генерируется:
+
+Из файла `auth.proto`:
+
+```protobuf
+service AuthService {
+  rpc SendOtp (SendOtpRequest) returns (SendOtpResponse);
+}
+
+message SendOtpRequest {
+  string identifier = 1;
+  string type = 2;
+}
+
+message SendOtpResponse {
+  bool ok = 1;
+}
+```
+
+Генерируется `gen/auth.ts`:
+
+```typescript
+// Интерфейсы для сообщений
+export interface SendOtpRequest {
+  identifier: string;
+  type: string;
+}
+
+export interface SendOtpResponse {
+  ok: boolean;
+}
+
+// Клиент и контроллер для NestJS
+export interface AuthServiceClient {
+  sendOtp(request: SendOtpRequest): Observable<SendOtpResponse>;
+}
+
+export interface AuthServiceController {
+  sendOtp(
+    request: SendOtpRequest
+  ): Promise<SendOtpResponse> | Observable<SendOtpResponse> | SendOtpResponse;
+}
+```
+
+### Пример использования в NestJS:
+
+**Контроллер:**
+
+```typescript
+@Controller()
+export class AuthController implements AuthServiceController {
+  @GrpcMethod("SendOtp")
+  async sendOtp(request: SendOtpRequest): Promise<SendOtpResponse> {
+    return { ok: true };
+  }
+}
+```
+
+**Клиент:**
+
+```typescript
+@Injectable()
+export class AuthClient {
+  constructor(@Inject("AUTH_SERVICE") private client: ClientGrpc) {}
+
+  sendOtp(request: SendOtpRequest): Observable<SendOtpResponse> {
+    return this.client
+      .getService<AuthServiceClient>("AuthService")
+      .sendOtp(request);
+  }
+}
+```
+
+---
+
+## 16. Установка необходимых инструментов
+
+### 1. Protocol Buffers компилятор:
+
+```bash
+# Установить protoc (добавить в PATH)
+# Скачать с: https://github.com/protocolbuffers/protobuf/releases
+# Или через пакетный менеджер
+```
+
+### 2. TypeScript плагин:
+
+```bash
+npm install -g ts-proto
+# или локально
+npm install -D ts-proto
+```
+
+### 3. Проверка установки:
+
+```bash
+protoc --version          # Проверка protoc
+protoc-gen-ts_proto --version  # Проверка плагина
+```
+
+---
+
+## 17. Полный процесс работы с .proto файлами
+
+1. **Создать .proto файл** с описанием сервисов и сообщений
+2. **Установить инструменты** (`protoc` и `ts-proto`)
+3. **Сгенерировать TypeScript код** с помощью команды
+4. **Использовать сгенерированные интерфейсы** в NestJS приложении
+5. **Реализовать контроллеры** и клиенты на основе сгенерированного кода
+
+---
+
+Это основа для работы с gRPC! 🚀