@mamindom/contracts 1.0.129 → 1.0.131

package/dist/proto/notification.proto

@@ -16,6 +16,42 @@ 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;
 }
 
 service NotificationLogsService {
@@ -29,6 +65,202 @@ service TelegramChatsService {
   rpc TestSendTelegram (TestSendTelegramRequest) returns (TestSendTelegramResponse);
 }
 
+// Маркетингові кампанії: створення, запуск, статистика.
+service CampaignsService {
+  rpc ListCampaigns    (ListCampaignsRequest)    returns (ListCampaignsResponse);
+  rpc GetCampaign      (GetCampaignRequest)      returns (CampaignResponse);
+  rpc CreateCampaign   (CreateCampaignRequest)   returns (CampaignResponse);
+  rpc UpdateCampaign   (UpdateCampaignRequest)   returns (CampaignResponse);
+  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);
+}
+
+message EnqueueRecipientsRequest {
+  string campaign_id = 1;
+  repeated CampaignResolvedRecipient recipients = 2;
+}
+
+message CampaignResolvedRecipient {
+  string user_id = 1;
+  string recipient = 2; // email або phone
+  // true → у клієнта promotions=false. dispatcher позначить SKIPPED_OPT_OUT
+  // якщо respect_opt_out=true для кампанії.
+  bool opt_out = 3;
+  // Унікальний код, згенерований gateway через CouponsService.CreateCoupon.
+  // Підставляється у шаблон як {{coupon_code}}.
+  optional string coupon_code = 4;
+}
+
+message EnqueueRecipientsResponse {
+  int32 enqueued = 1;
+}
+
+message ListCampaignsRequest {
+  optional CampaignStatusEnum status = 1;
+  optional int32 page = 2;
+  optional int32 limit = 3;
+}
+
+message ListCampaignsResponse {
+  repeated Campaign items = 1;
+  int32 total = 2;
+}
+
+message GetCampaignRequest {
+  string id = 1;
+}
+
+message DeleteCampaignRequest {
+  string id = 1;
+}
+
+message DeleteCampaignResponse {
+  bool ok = 1;
+}
+
+message StartCampaignRequest {
+  string id = 1;
+  // ISO date; якщо порожньо → запустити одразу.
+  optional string scheduled_at = 2;
+}
+
+message CancelCampaignRequest {
+  string id = 1;
+}
+
+message CreateCampaignRequest {
+  string name = 1;
+  NotificationChannel channel = 2;
+  optional string template_id = 3;
+  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;
+  string created_by_id = 11;
+}
+
+message UpdateCampaignRequest {
+  string id = 1;
+  // Можна оновлювати тільки DRAFT — гілки нижче опційні.
+  optional string name = 2;
+  optional NotificationChannel channel = 3;
+  optional string template_id = 4;
+  optional string custom_subject = 5;
+  optional string custom_body_html = 6;
+  optional string custom_body_text = 7;
+  optional string segment_json = 8;
+  optional string coupon_spec_json = 9;
+  optional bool respect_opt_out = 10;
+  optional NotificationLocale locale = 11;
+}
+
+message CampaignResponse {
+  bool ok = 1;
+  string error_message = 2;
+  Campaign campaign = 3;
+}
+
+message Campaign {
+  string id = 1;
+  string name = 2;
+  NotificationChannel channel = 3;
+  optional string template_id = 4;
+  optional string custom_subject = 5;
+  optional string custom_body_html = 6;
+  optional string custom_body_text = 7;
+  NotificationLocale locale = 8;
+  string segment_json = 9;
+  optional string coupon_spec_json = 10;
+  bool respect_opt_out = 11;
+  CampaignStatusEnum status = 12;
+  optional string scheduled_at = 13;
+  optional string started_at = 14;
+  optional string completed_at = 15;
+  int32 total_recipients = 16;
+  int32 sent_count = 17;
+  int32 failed_count = 18;
+  int32 skipped_opt_out_count = 19;
+  string created_by_id = 20;
+  string created_at = 21;
+  string updated_at = 22;
+}
+
+enum CampaignStatusEnum {
+  CAMPAIGN_STATUS_UNSPECIFIED = 0;
+  DRAFT = 1;
+  SCHEDULED = 2;
+  RUNNING = 3;
+  COMPLETED = 4;
+  CANCELLED = 5;
+  CAMPAIGN_FAILED = 6;
+}
+
+message PreviewSegmentRequest {
+  string segment_json = 1;
+  NotificationChannel channel = 2; // потрібно для перевірки наявності email/phone
+}
+
+message PreviewSegmentResponse {
+  int32 total_count = 1;
+  // Перші 10 для UI; решта — за необхідності окремим запитом.
+  repeated PreviewSegmentSample sample = 2;
+}
+
+message PreviewSegmentSample {
+  string user_id = 1;
+  string first_name = 2;
+  string last_name = 3;
+  string email = 4;
+  string phone = 5;
+}
+
+message ListRecipientsRequest {
+  string campaign_id = 1;
+  optional CampaignRecipientStatusEnum status = 2;
+  optional int32 page = 3;
+  optional int32 limit = 4;
+}
+
+message ListRecipientsResponse {
+  repeated CampaignRecipient items = 1;
+  int32 total = 2;
+}
+
+message CampaignRecipient {
+  string id = 1;
+  string campaign_id = 2;
+  string user_id = 3;
+  string recipient = 4;
+  CampaignRecipientStatusEnum status = 5;
+  optional string coupon_code = 6;
+  optional string notification_log_id = 7;
+  optional string error_message = 8;
+  optional string sent_at = 9;
+  string created_at = 10;
+}
+
+enum CampaignRecipientStatusEnum {
+  CAMPAIGN_RECIPIENT_UNSPECIFIED = 0;
+  RECIPIENT_PENDING = 1;
+  RECIPIENT_SENT = 2;
+  RECIPIENT_FAILED = 3;
+  RECIPIENT_SKIPPED_OPT_OUT = 4;
+  RECIPIENT_SKIPPED_NO_CONTACT = 5;
+}
+
 // Брендинг email-шаблонів — singleton редагується адміном.
 service BrandingService {
   rpc GetBranding    (BrandingEmpty)         returns (BrandingProfile);
@@ -53,6 +285,8 @@ message BrandingProfile {
   string resolved_brand_name    = 9;
   string resolved_brand_url     = 10;
   string resolved_support_email = 11;
+  // Кастомний HTML-хедер (замість дефолтного логотип-блоку). Порожньо → default.
+  string header_html            = 12;
 }
 
 message UpdateBrandingRequest {
@@ -63,6 +297,7 @@ message UpdateBrandingRequest {
   optional string support_email = 4;
   optional string footer_html   = 5;
   string actor_id               = 6;
+  optional string header_html   = 7;
 }
 
 
@@ -238,6 +473,9 @@ message RenderPreviewRequest {
   // 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;
 }
 
 message RenderPreviewResponse {

package/dist/proto/order.proto

@@ -25,6 +25,26 @@ service OrderService {
   rpc ReorderOrder(ReorderOrderRequest) returns (ReorderResponse);
 
   rpc ListHistory(ListHistoryRequest) returns (ListHistoryResponse);
+
+  // CRM-агрегація для експорту клієнтів — повертає count/sum/last для кожного userId.
+  rpc AggregateByCustomers(AggregateByCustomersRequest) returns (AggregateByCustomersResponse);
+}
+
+message AggregateByCustomersRequest {
+  repeated string user_ids = 1;
+}
+
+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;
+}
+
+message AggregateByCustomersResponse {
+  repeated CustomerOrderAggregate items = 1;
 }
 
 // ─── Enums (string у proto3, для зворотної сумісності) ─────────

package/dist/proto/users.proto

@@ -47,6 +47,9 @@ service UsersService {
   rpc RemoveCartItem(RemoveCartItemRequest) returns (GetCartResponse);
   rpc ClearCart(ClearCartRequest) returns (ClearCartResponse);
   rpc SyncCart(SyncCartRequest) returns (GetCartResponse);
+
+  // Admin CRM — редагування клієнта менеджером (customers.edit на gateway).
+  rpc AdminUpdateCustomer(AdminUpdateCustomerRequest) returns (AdminUpdateCustomerResponse);
 }
 
 message GetMeRequest {
@@ -87,6 +90,19 @@ message User {
   int32 bonuses = 4;
   optional string email = 5;
   optional string phone = 6;
+  optional string internal_note = 7;
+}
+
+message AdminUpdateCustomerRequest {
+  string id = 1;
+  optional string first_name = 2;
+  optional string last_name = 3;
+  // internal_note редагується тут окремо, бо це CRM-поле — не видиме клієнту.
+  optional string internal_note = 4;
+}
+
+message AdminUpdateCustomerResponse {
+  User user = 1;
 }
 
 message NotificationSettings {

package/events/orders/order-cancelled.interface.ts

@@ -8,7 +8,6 @@ export interface OrderCancelledEvent {
 	releaseStock: boolean
 	cancelledAt: number
 
-	// Опціональний customer-snapshot для нотифікацій.
 	userId?: string
 	customer?: {
 		firstName: string

package/events/orders/order-status-changed.interface.ts

@@ -8,8 +8,6 @@ export interface OrderStatusChangedEvent {
 	actorName?: string
 	changedAt: number
 
-	// Опціональний customer-snapshot для нотифікацій (щоб
-	// notification-service не робив додатковий lookup в order-service).
 	userId?: string
 	customer?: {
 		firstName: string
@@ -18,7 +16,6 @@ export interface OrderStatusChangedEvent {
 		phone: string
 	}
 
-	// На переходах у shipped — ТТН + tracking URL.
 	trackingNumber?: string
 	trackingUrl?: string
 }

package/events/stock/stock-confirm-requested.interface.ts

@@ -1,5 +1,3 @@
-// Подія від order-service: замовлення переходить у packing → catalog
-// списує резерв у реальний OUTGOING рух (підтверджує продаж).
 export interface StockConfirmRequestedEvent {
 	orderId: string
 	orderNumber: string

package/events/stock/stock-release-requested.interface.ts

@@ -1,5 +1,3 @@
-// Подія від order-service: cancel/відмова → catalog скасовує всі резерви
-// замовлення (по reference_type='order', reference_id=orderId).
 export interface StockReleaseRequestedEvent {
 	orderId: string
 	orderNumber: string

package/events/stock/stock-reserve-failed.interface.ts

@@ -1,5 +1,3 @@
-// Подія від catalog-service: catalog НЕ зміг зарезервувати (insufficient
-// stock, product disappeared). Order-service кенселить замовлення з reason.
 export interface StockReserveFailedEvent {
 	orderId: string
 	orderNumber: string

package/events/stock/stock-reserve-requested.interface.ts

@@ -1,9 +1,3 @@
-// Подія від order-service: catalog має зарезервувати stock для замовлення.
-// Catalog сам обирає warehouse(и) (auto-pick first-available, greedy
-// fill через product_warehouses ORDER BY created_at).
-//
-// TTL у мс — після його закінчення UnpaidOrdersCron у order-service
-// автоматично скасує замовлення → catalog отримає stock.release_requested.
 export interface StockReserveRequestedEvent {
 	orderId: string
 	orderNumber: string

package/events/stock/stock-reserved.interface.ts

@@ -1,5 +1,3 @@
-// Подія від catalog-service: успішний резерв → order-service зберігає
-// reservationId/reservedUntil у OrderItem (для admin UI і traceability).
 export interface StockReservedEvent {
 	orderId: string
 	orderNumber: string