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);

  // Permanently lock a balanced journal. This is an explicit action; becoming
  // balanced never locks a journal automatically.
  rpc LockJournal(LockJournalRequest) returns (Journal);

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

  // Search profile journals by user-facing name while retaining journal ids
  // as the stable relationship keys.
  rpc SearchJournals(SearchJournalsRequest) returns (SearchJournalsResponse);

  // 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);
}

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;

  // Required and unique within the profile when creating. Must be empty when
  // appending to an existing journal selected by journal_id.
  string journal_name = 6;
}

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

message LockJournalRequest {
  string profile_name = 1;
  int64 journal_id = 2;
}

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 SearchJournalsRequest {
  string profile_name = 1;

  // Case-insensitive literal substring. Empty returns all profile journals.
  string name_query = 2;

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

  // Opaque cursor returned by the previous response.
  string page_token = 4;
}

message JournalSummary {
  int64 journal_id = 1;
  string journal_name = 2;
  string currency = 3;
  string description = 4;
  string total_debit = 5;
  string total_credit = 6;
  string balance = 7;
  int64 active_line_count = 8;
  bool locked = 9;
  string created_at = 10;
}

message SearchJournalsResponse {
  repeated JournalSummary journals = 1;
  int64 total_count = 2;
  string next_page_token = 3;
}

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;
  string journal_name = 11;
}

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;
  bool locked = 10;
  string locked_at = 11;
  string locked_by_user_id = 12;
  string journal_name = 13;
}