bff dev upgrde

api/proto/billing/documents/v1/documents.proto

@@ -0,0 +1,101 @@
+syntax = "proto3";
+
+package billing.documents.v1;
+
+option go_package = "github.com/tech/sendico/pkg/proto/billing/documents/v1;documentsv1";
+
+
+// ---------------------------
+// ENUMS
+// ---------------------------
+
+// DocumentType defines supported accounting document kinds.
+enum DocumentType {
+  DOCUMENT_TYPE_UNSPECIFIED = 0;
+
+  // Invoice issued for the payment
+  DOCUMENT_TYPE_INVOICE     = 1;
+
+  // Service acceptance act (common in EU/RU accounting)
+  DOCUMENT_TYPE_ACT         = 2;
+
+  // Simple receipt confirmation
+  DOCUMENT_TYPE_RECEIPT     = 3;
+}
+
+
+// ---------------------------
+// SERVICE
+// ---------------------------
+
+// DocumentService provides document metadata for payment lists
+// and lazy document generation on demand.
+service DocumentService {
+
+  // BatchResolveDocuments is used by BFF when rendering
+  // a page of payments. This prevents N+1 calls by resolving
+  // document metadata for many payments in a single request.
+  rpc BatchResolveDocuments(BatchResolveDocumentsRequest)
+      returns (BatchResolveDocumentsResponse);
+
+  // GetDocument returns the actual PDF file.
+  // If the document was not generated before, the service
+  // generates it lazily, stores it, and returns it.
+  rpc GetDocument(GetDocumentRequest)
+      returns (GetDocumentResponse);
+}
+
+
+// ---------------------------
+// BATCH RESOLVE (for payment tables)
+// ---------------------------
+
+// BatchResolveDocumentsRequest contains a list of payment references
+// for which document availability should be resolved.
+message BatchResolveDocumentsRequest {
+  repeated string payment_refs = 1;
+}
+
+// DocumentMeta describes document availability for a single payment.
+message DocumentMeta {
+  // Payment reference
+  string payment_ref = 1;
+
+  // Document types that are applicable for this payment
+  // based on business rules and payment snapshot.
+  repeated DocumentType available_types = 2;
+
+  // Document types that were already generated and stored.
+  // Other available types will be generated lazily when requested.
+  repeated DocumentType ready_types = 3;
+}
+
+// BatchResolveDocumentsResponse returns metadata for all requested payments.
+message BatchResolveDocumentsResponse {
+  repeated DocumentMeta items = 1;
+}
+
+
+// ---------------------------
+// GET DOCUMENT (lazy generation)
+// ---------------------------
+
+// GetDocumentRequest requests a specific document for a payment.
+message GetDocumentRequest {
+  string payment_ref = 1;
+
+  // Type of document to retrieve (invoice, act, receipt, etc.)
+  DocumentType type  = 2;
+}
+
+// GetDocumentResponse returns the generated PDF content.
+message GetDocumentResponse {
+  // Raw PDF bytes
+  bytes  content   = 1;
+
+  // Suggested filename for download (e.g. invoice_123.pdf)
+  string filename  = 2;
+
+  // MIME type, typically "application/pdf"
+  string mime_type = 3;
+}