komp_ac/common/proto/accounting.proto

syntax = "proto3";
package komp_ac.accounting;

// Mutable informational journals. A journal may contain only debits, only
// credits, or any non-zero balance. Balance is reported but never enforced.
service Accounting {
  // Create a journal with its first lines when journal_id is absent, or append
  // all supplied lines atomically when journal_id identifies an existing one.
  rpc PostJournal(PostJournalRequest) returns (Journal);

  // Return journal lines and credits-minus-debits informational balance.
  rpc GetJournal(GetJournalRequest) returns (Journal);

  // Return the profile-wide count of balanced and unbalanced journals.
  rpc GetAccountingStatus(GetAccountingStatusRequest) returns (AccountingStatus);

  // Return an oldest-first, paginated queue of unbalanced journals.
  rpc ListUnbalancedJournals(ListUnbalancedJournalsRequest)
      returns (ListUnbalancedJournalsResponse);

  // Soft-delete one line while retaining it for audit display.
  rpc SoftDeleteJournalLine(SoftDeleteJournalLineRequest) returns (Journal);
}

// Tables with an active posting script accept journal_id as a reserved key in
// PostTableDataRequest.data. It selects the journal receiving generated lines
// and is removed before the source row is validated or stored.

enum JournalSide {
  JOURNAL_SIDE_UNSPECIFIED = 0;
  JOURNAL_SIDE_DEBIT = 1;
  JOURNAL_SIDE_CREDIT = 2;
}

message PostJournalRequest {
  string profile_name = 1;

  // Absent creates a new journal. Present must identify an existing journal;
  // an unknown id is never treated as a request to create one.
  optional int64 journal_id = 2;

  // Required when creating. When appending, empty uses the journal currency;
  // a supplied value must match it exactly.
  string currency = 3;

  // Applied when creating and required to be empty when appending.
  string description = 4;

  // At least one line is required. The lines are inserted atomically and the
  // journal is allowed to remain unbalanced.
  repeated JournalLineInput lines = 5;
}

message JournalLineInput {
  JournalSide side = 1;
  string account_code = 2;
  string amount = 3;
  string description = 4;
}

message GetJournalRequest {
  string profile_name = 1;
  int64 journal_id = 2;

  // False by default. True is reserved for a future Casbin permission granted
  // only to superadmin and is rejected until that permission is implemented.
  bool include_deleted = 3;
}

message GetAccountingStatusRequest {
  string profile_name = 1;
}

message AccountingStatus {
  bool all_journals_balanced = 1;
  int64 journal_count = 2;
  int64 balanced_journal_count = 3;
  int64 unbalanced_journal_count = 4;
  string calculated_at = 5;
}

message ListUnbalancedJournalsRequest {
  string profile_name = 1;

  // Zero uses 50. The maximum is 500.
  int32 page_size = 2;

  // Opaque cursor returned by the previous response. Empty starts at the
  // oldest unbalanced journal.
  string page_token = 3;

  // Optional ISO 4217 currency filter. Empty includes every currency.
  string currency = 4;
}

message UnbalancedJournalSummary {
  int64 journal_id = 1;
  string description = 2;
  string currency = 3;
  string total_debit = 4;
  string total_credit = 5;

  // Signed credits-minus-debits difference.
  string balance = 6;

  // Side and positive amount needed to make the journal balance zero.
  JournalSide missing_side = 7;
  string missing_amount = 8;
  int64 active_line_count = 9;
  string created_at = 10;
}

message ListUnbalancedJournalsResponse {
  repeated UnbalancedJournalSummary journals = 1;
  int64 total_unbalanced_count = 2;
  string next_page_token = 3;
}

message SoftDeleteJournalLineRequest {
  string profile_name = 1;
  int64 journal_id = 2;
  int64 journal_line_id = 3;
}

message JournalLine {
  int64 id = 1;
  int32 line_number = 2;
  JournalSide side = 3;
  string account_code = 4;
  string amount = 5;
  string description = 6;
  bool deleted = 7;
  string created_at = 8;
  string deleted_at = 9;
  string source_table_name = 10;
  int64 source_record_id = 11;
  int64 source_row_revision = 12;
  int64 posting_script_id = 13;
}

message Journal {
  int64 id = 1;
  string profile_name = 2;
  string currency = 3;
  string description = 4;
  string created_at = 5;
  repeated JournalLine lines = 6;
  string total_debit = 7;
  string total_credit = 8;
  // Informational difference calculated as credits minus debits.
  string balance = 9;
}