@mamindom/contracts 1.0.143 → 1.0.145

package/proto/notification.proto

@@ -3,8 +3,6 @@ syntax = "proto3";
 package notification.v1;
 
 
-// Admin API для керування шаблонами нотифікацій, Telegram-чатами,
-// надсилання test-пакета, перегляду логів.
 
 service NotificationTemplateService {
   rpc ListTemplates       (ListTemplatesRequest)       returns (ListTemplatesResponse);
@@ -16,41 +14,38 @@ service NotificationTemplateService {
   rpc RestoreVersion      (RestoreVersionRequest)      returns (TemplateResponse);
   rpc RenderPreview       (RenderPreviewRequest)       returns (RenderPreviewResponse);
   rpc SendTest            (SendTestRequest)            returns (SendTestResponse);
-  // Реальна відправка клієнту з адмінки — або по шаблону, або ad-hoc body.
+
   rpc SendToCustomer      (SendToCustomerRequest)      returns (SendToCustomerResponse);
 }
 
-// SendToCustomer — викликається з gateway після того, як клієнтський контакт
-// (email/phone) вже резолвнений і опційно згенерований персональний купон.
+
 message SendToCustomerRequest {
-  // userId з auth-service — пишемо в NotificationLog.user_id для зведень.
+  
   string user_id = 1;
   NotificationChannel channel = 2;
 
-  // Recipient — email або phone, заздалегідь визначені gateway з акаунта.
+  
   string recipient = 3;
 
-  // Шлях 1: templateId — рендеримо існуючий шаблон з variables.
+ 
   optional string template_id = 4;
 
-  // Шлях 2: ad-hoc контент. Якщо template_id порожній — використовуємо ці поля.
-  // body_html — для EMAIL (буде обгорнутий брендингом).
-  // body_text — для SMS (plain text) або текстова версія email.
+ 
   optional string custom_subject = 5;
   optional string custom_body_html = 6;
   optional string custom_body_text = 7;
 
-  // JSON з placeholders для Handlebars: { "coupon_code": "...", ... }
+ 
   string variables_json = 8;
 
-  // Locale для пошуку версії шаблону + надсилання branding-обгортки.
+  
   optional NotificationLocale locale = 9;
 }
 
 message SendToCustomerResponse {
   bool ok = 1;
   string error_message = 2;
-  // id запису в NotificationLog (для трекінгу в /notifications/logs).
+ 
   string log_id = 3;
 }
 
@@ -65,7 +60,7 @@ service TelegramChatsService {
   rpc TestSendTelegram (TestSendTelegramRequest) returns (TestSendTelegramResponse);
 }
 
-// Маркетингові кампанії: створення, запуск, статистика.
+
 service CampaignsService {
   rpc ListCampaigns    (ListCampaignsRequest)    returns (ListCampaignsResponse);
   rpc GetCampaign      (GetCampaignRequest)      returns (CampaignResponse);
@@ -74,12 +69,11 @@ service CampaignsService {
   rpc DeleteCampaign   (DeleteCampaignRequest)   returns (DeleteCampaignResponse);
   rpc StartCampaign    (StartCampaignRequest)    returns (CampaignResponse);
   rpc CancelCampaign   (CancelCampaignRequest)   returns (CampaignResponse);
-  // Превью сегменту — повертає кількість + перші N клієнтів, БЕЗ створення кампанії.
+  
   rpc PreviewSegment   (PreviewSegmentRequest)   returns (PreviewSegmentResponse);
-  // Список отримувачів конкретної кампанії з їхніми статусами.
+  
   rpc ListRecipients   (ListRecipientsRequest)   returns (ListRecipientsResponse);
-  // Викликається з gateway після того, як сегмент резолвнено клієнтами —
-  // передається список {userId, recipient}, нотифікація розкладає у чергу.
+  
   rpc EnqueueRecipients(EnqueueRecipientsRequest) returns (EnqueueRecipientsResponse);
 }
 
@@ -90,12 +84,9 @@ message EnqueueRecipientsRequest {
 
 message CampaignResolvedRecipient {
   string user_id = 1;
-  string recipient = 2; // email або phone
-  // true → у клієнта promotions=false. dispatcher позначить SKIPPED_OPT_OUT
-  // якщо respect_opt_out=true для кампанії.
+  string recipient = 2; 
   bool opt_out = 3;
-  // Унікальний код, згенерований gateway через CouponsService.CreateCoupon.
-  // Підставляється у шаблон як {{coupon_code}}.
+
   optional string coupon_code = 4;
 }
 
@@ -128,7 +119,7 @@ message DeleteCampaignResponse {
 
 message StartCampaignRequest {
   string id = 1;
-  // ISO date; якщо порожньо → запустити одразу.
+  
   optional string scheduled_at = 2;
 }
 
@@ -143,9 +134,9 @@ message CreateCampaignRequest {
   optional string custom_subject = 4;
   optional string custom_body_html = 5;
   optional string custom_body_text = 6;
-  // JSON segment spec.
+  
   string segment_json = 7;
-  // JSON coupon spec — null/empty для кампаній без купонів.
+ 
   optional string coupon_spec_json = 8;
   bool respect_opt_out = 9;
   optional NotificationLocale locale = 10;
@@ -154,7 +145,7 @@ message CreateCampaignRequest {
 
 message UpdateCampaignRequest {
   string id = 1;
-  // Можна оновлювати тільки DRAFT — гілки нижче опційні.
+
   optional string name = 2;
   optional NotificationChannel channel = 3;
   optional string template_id = 4;
@@ -210,12 +201,12 @@ enum CampaignStatusEnum {
 
 message PreviewSegmentRequest {
   string segment_json = 1;
-  NotificationChannel channel = 2; // потрібно для перевірки наявності email/phone
+  NotificationChannel channel = 2; 
 }
 
 message PreviewSegmentResponse {
   int32 total_count = 1;
-  // Перші 10 для UI; решта — за необхідності окремим запитом.
+  
   repeated PreviewSegmentSample sample = 2;
 }
 
@@ -261,7 +252,7 @@ enum CampaignRecipientStatusEnum {
   RECIPIENT_SKIPPED_NO_CONTACT = 5;
 }
 
-// Брендинг email-шаблонів — singleton редагується адміном.
+
 service BrandingService {
   rpc GetBranding    (BrandingEmpty)         returns (BrandingProfile);
   rpc UpdateBranding (UpdateBrandingRequest) returns (BrandingProfile);
@@ -269,8 +260,7 @@ service BrandingService {
 
 message BrandingEmpty {}
 
-// Поля що поверталися з resolved-merge (DB ∪ env). Порожні рядки означають
-// "взяти fallback з env" при наступному GET.
+
 message BrandingProfile {
   string logo_url      = 1;
   string brand_name    = 2;
@@ -279,18 +269,17 @@ message BrandingProfile {
   string footer_html   = 5;
   int64  updated_at    = 6;
   string updated_by    = 7;
-  // resolved: остаточні значення, що використовуються wrapper'ом
-  // (DB override → env fallback). Для UI щоб показати "поточне значення".
+
   string resolved_logo_url      = 8;
   string resolved_brand_name    = 9;
   string resolved_brand_url     = 10;
   string resolved_support_email = 11;
-  // Кастомний HTML-хедер (замість дефолтного логотип-блоку). Порожньо → default.
+
   string header_html            = 12;
 }
 
 message UpdateBrandingRequest {
-  // optional: відсутність → не оновлювати; порожній рядок → скинути до NULL у БД.
+  
   optional string logo_url      = 1;
   optional string brand_name    = 2;
   optional string brand_url     = 3;
@@ -354,12 +343,11 @@ message NotificationTemplate {
   NotificationCategory category = 5;
   string title = 6;
   string subject = 7;
-  // JSON-stringified Tiptap content (передаємо як string щоб не
-  // використовувати proto google.protobuf.Struct).
+  
   string content_json = 8;
   string body_html = 9;
   string body_text = 10;
-  // JSON array of variable names (для autocomplete).
+  
   string variables_json = 11;
   bool is_active = 12;
   int32 version = 13;
@@ -374,7 +362,6 @@ message TemplateResponse {
 }
 
 
-// ─── List ────────────────────────────────────────────────────────────
 
 message ListTemplatesRequest {
   optional NotificationChannel channel = 1;
@@ -388,14 +375,12 @@ message ListTemplatesResponse {
 }
 
 
-// ─── Get ─────────────────────────────────────────────────────────────
 
 message GetTemplateRequest {
   string id = 1;
 }
 
 
-// ─── Upsert (create new) ─────────────────────────────────────────────
 
 message UpsertTemplateRequest {
   string key = 1;
@@ -412,7 +397,6 @@ message UpsertTemplateRequest {
 }
 
 
-// ─── Update by id (з versioning) ─────────────────────────────────────
 
 message UpdateTemplateRequest {
   string id = 1;
@@ -423,12 +407,11 @@ message UpdateTemplateRequest {
   string body_text = 6;
   optional string variables_json = 7;
   optional bool is_active = 8;
-  // Admin id для audit (хто змінив).
+  
   optional string actor_id = 9;
 }
 
 
-// ─── Toggle (вмикання/вимикання) ────────────────────────────────────
 
 message ToggleTemplateRequest {
   string id = 1;
@@ -436,7 +419,6 @@ message ToggleTemplateRequest {
 }
 
 
-// ─── Versions ────────────────────────────────────────────────────────
 
 message NotificationTemplateVersion {
   string id = 1;
@@ -466,15 +448,13 @@ message RestoreVersionRequest {
 }
 
 
-// ─── Preview ────────────────────────────────────────────────────────
 
 message RenderPreviewRequest {
   string body_html = 1;
-  // JSON-stringified variables { "order.number": "MD-2026-0001", ... }
+  
   string variables_json = 2;
   optional string subject = 3;
-  // JSON-stringified branding override (header/footer/logo/brand…) для live-
-  // превʼю незбережених змін на сторінці брендингу. Порожньо → беремо з БД.
+  
   optional string branding_json = 4;
 }
 
@@ -484,13 +464,12 @@ message RenderPreviewResponse {
 }
 
 
-// ─── Test send ───────────────────────────────────────────────────────
 
 message SendTestRequest {
   string template_id = 1;
-  // email або phone (залежно від channel).
+
   string recipient = 2;
-  // JSON-stringified test variables.
+
   string variables_json = 3;
 }
 
@@ -500,7 +479,6 @@ message SendTestResponse {
 }
 
 
-// ─── Logs ────────────────────────────────────────────────────────────
 
 message NotificationLog {
   string id = 1;
@@ -539,7 +517,6 @@ message ListLogsResponse {
 }
 
 
-// ─── Telegram chats ──────────────────────────────────────────────────
 
 message TelegramChat {
   string id = 1;

package/proto/order.proto

@@ -14,8 +14,7 @@ service OrderService {
   rpc UpdateStatus(UpdateStatusRequest) returns (OrderResponse);
   rpc CancelOrder(CancelOrderRequest) returns (OrderResponse);
 
-  // Archive (soft delete) — встановлює archived_at. Замовлення зникає
-  // з дефолтного списку, але доступне через ?archived=true.
+  
   rpc ArchiveOrder(ArchiveOrderRequest) returns (OrderResponse);
   rpc UnarchiveOrder(UnarchiveOrderRequest) returns (OrderResponse);
 
@@ -31,7 +30,7 @@ service OrderService {
 
   rpc ListHistory(ListHistoryRequest) returns (ListHistoryResponse);
 
-  // CRM-агрегація для експорту клієнтів — повертає count/sum/last для кожного userId.
+
   rpc AggregateByCustomers(AggregateByCustomersRequest) returns (AggregateByCustomersResponse);
 }
 
@@ -42,9 +41,9 @@ message AggregateByCustomersRequest {
 message CustomerOrderAggregate {
   string user_id = 1;
   int32 orders_count = 2;
-  // Decimal у вигляді рядка ('1234.56') — щоб не втратити точність на gRPC border.
+ 
   string total_sum = 3;
-  // ISO-рядок, відсутній якщо клієнт ще не робив замовлень.
+  
   optional string last_order_at = 4;
 }
 
@@ -52,12 +51,6 @@ message AggregateByCustomersResponse {
   repeated CustomerOrderAggregate items = 1;
 }
 
-// ─── Enums (string у proto3, для зворотної сумісності) ─────────
-
-// Статуси: new, processing, confirmed, no_answer, packing,
-//          shipped, delivered, completed, cancelled, returned
-
-// ─── Domain types ──────────────────────────────────────────────
 
 message OrderItem {
   string id            = 1;
@@ -95,8 +88,7 @@ message OrderDelivery {
   string tracking_url    = 10;
   string estimated_date  = 11;
   string shipment_status = 12;
-  // Адмін-облік: область/регіон з City.region від delivery-service.
-  // Старі замовлення можуть мати порожнє значення.
+  
   string region          = 13;
 }
 
@@ -111,8 +103,7 @@ message OrderPayment {
   int64  captured_at          = 8;
   int64  cancelled_at         = 9;
   int64  refunded_at          = 10;
-  // Денормалізовано з payment-service для відображення в адмінці
-  // без додаткового gRPC дзвінка. Оновлюється з payment-events listener.
+ 
   double captured_amount      = 11;
   double refunded_amount      = 12;
 }
@@ -187,15 +178,13 @@ message Order {
   int64  created_at = 20;
   int64  updated_at = 21;
 
-  // Внутрішні нотатки менеджерів (видимі тільки в адмінці).
-  // Сортуються від новіших до старіших — server-side.
+  
   repeated OrderNote notes = 22;
 
-  // 0 = не в архіві; інакше timestamp коли архівовано.
+  
   int64  archived_at = 23;
 }
 
-// ─── Requests ──────────────────────────────────────────────────
 
 message CreateOrderRequest {
   string idempotency_key = 1;
@@ -251,8 +240,7 @@ message ListOrdersRequest {
   double total_to   = 13;
   string sort_by = 14;
   string sort_dir = 15;
-  // 0 = тільки активні (default), 1 = тільки архівні, 2 = всі.
-  // Менеджер бачить тільки свої через manager_id (вище).
+  
   int32  archived_filter = 16;
 }
 

package/proto/page.proto

@@ -31,9 +31,7 @@ message PageResponse {
 
   map<string, string> title = 4;
 
-  // PageBlock[] serialized as JSON-string. ts-proto without oneofs
-  // turns discriminated unions into a soup of optional fields; keep
-  // the typed union on the gateway side via zod instead.
+ 
   string blocks_json = 5;
 
   optional string cover_image    = 6;

package/proto/payment.proto

@@ -3,35 +3,30 @@ syntax = "proto3";
 package payment.v1;
 
 service PaymentService {
-  // CreateInvoice — провайдер створює інвойс у режимі hold (2-stage).
+ 
   rpc CreateInvoice(CreateInvoiceRequest) returns (PaymentResponse);
 
   rpc GetPayment(GetPaymentRequest) returns (PaymentResponse);
   rpc GetPaymentByOrder(GetPaymentByOrderRequest) returns (PaymentResponse);
   rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
 
-  // Capture — фіксація списання раніше зарезервованих коштів.
+  
   rpc Capture(CaptureRequest) returns (PaymentResponse);
-  // Cancel — повне скасування hold (без списання).
+  
   rpc Cancel(CancelRequest) returns (PaymentResponse);
-  // Refund — повернення вже captured коштів (повне або часткове).
+
   rpc Refund(RefundRequest) returns (PaymentResponse);
 
-  // SyncStatus — підтягує актуальний статус від провайдера (manual reconciliation).
+  
   rpc SyncStatus(SyncStatusRequest) returns (PaymentResponse);
 
-  // RegenerateInvoice — створює новий invoice у провайдера для існуючого Payment.
-  // Використовується коли paymentUrl застарів (TTL у Mono ≈ 24г) або клієнт
-  // загубив SMS — менеджер ділиться новим лінком через адмін UI.
+  
   rpc RegenerateInvoice(RegenerateInvoiceRequest) returns (PaymentResponse);
 
   rpc ListProviders(ListProvidersRequest) returns (ListProvidersResponse);
   rpc ToggleProvider(ToggleProviderRequest) returns (ToggleProviderResponse);
 }
 
-// ─── Domain ────────────────────────────────────────────────────
-
-// status: pending | hold | captured | cancelled | refunded | partially_refunded | failed
 
 message Payment {
   string id                  = 1;
@@ -62,7 +57,6 @@ message PaymentProviderInfo {
   string description  = 5;
 }
 
-// ─── Requests ──────────────────────────────────────────────────
 
 message CreateInvoiceRequest {
   string order_id        = 1;
@@ -111,7 +105,7 @@ message ListPaymentsResponse {
 
 message CaptureRequest {
   string id      = 1;
-  double amount  = 2; // 0 → captures full amount
+  double amount  = 2; 
   string actor_id = 3;
 }
 
@@ -123,7 +117,7 @@ message CancelRequest {
 
 message RefundRequest {
   string id       = 1;
-  double amount   = 2; // 0 → full refund of captured
+  double amount   = 2; 
   string reason   = 3;
   string actor_id = 4;
 }

package/proto/pickup.proto

@@ -5,14 +5,14 @@ package catalog.v1;
 import "common.proto";
 
 service PickupPointService {
-  // Pickup points CRUD
+  
   rpc GetPickupPoints (GetPickupPointsRequest) returns (GetPickupPointsResponse);
   rpc GetPickupPoint  (GetPickupPointRequest)  returns (PickupPointResponse);
   rpc CreatePickupPoint (CreatePickupPointRequest) returns (PickupPointResponse);
   rpc UpdatePickupPoint (UpdatePickupPointRequest) returns (PickupPointResponse);
   rpc DeletePickupPoint (DeletePickupPointRequest) returns (DeleteResponse);
 
-  // Stock per pickup point
+  
   rpc GetPickupStock      (GetPickupStockRequest)      returns (GetPickupStockResponse);
   rpc SetPickupStock      (SetPickupStockRequest)      returns (PickupStockItemResponse);
   rpc AdjustPickupStock   (AdjustPickupStockRequest)   returns (PickupStockItemResponse);
@@ -20,7 +20,6 @@ service PickupPointService {
   rpc BulkSyncFromOnec    (BulkSyncFromOnecRequest)    returns (SuccessResponse);
 }
 
-// ── Pickup Point ──────────────────────────────────────────────
 
 message PickupPointResponse {
   string  id       = 1;
@@ -32,7 +31,7 @@ message PickupPointResponse {
   optional double lng      = 7;
   bool    is_active = 8;
   optional string code_1c  = 9;
-  optional string schedule = 10; // JSON-encoded WeekSchedule
+  optional string schedule = 10; 
 }
 
 message GetPickupPointsRequest {
@@ -77,14 +76,13 @@ message DeletePickupPointRequest {
   string id = 1;
 }
 
-// ── Pickup Stock ──────────────────────────────────────────────
 
 message PickupStockItemResponse {
   string  pickup_point_id = 1;
   string  product_id      = 2;
   optional string variant_id = 3;
   int32   qty             = 4;
-  string  source          = 5;  // "MANUAL" | "SYNC_1C"
+  string  source          = 5;  
   string  updated_at      = 6;
   optional string pickup_point_name = 7;
 }
@@ -104,21 +102,21 @@ message SetPickupStockRequest {
   string  product_id      = 2;
   optional string variant_id = 3;
   int32   qty             = 4;
-  optional string source  = 5;  // default MANUAL
+  optional string source  = 5;  
 }
 
 message AdjustPickupStockRequest {
   string  pickup_point_id = 1;
   string  product_id      = 2;
   optional string variant_id = 3;
-  int32   delta           = 4;  // positive = add, negative = subtract
+  int32   delta           = 4;  
 }
 
 message BulkSetPickupStockRequest {
   repeated SetPickupStockRequest items = 1;
 }
 
-// Масова синхронізація з 1С: масив рядків вигляду "code1c:productGuid1c:variantGuid1c?:qty"
+
 message BulkSyncFromOnecRequest {
   repeated OnecStockEntry entries = 1;
 }