syntax = "proto3";

package nexuscrm.runtime.v1;

import "common/v1/common.proto";

option go_package = "github.com/pingcap-inc/nexuscrm-contract/wire-go/gen/runtime/v1;runtimev1";

// ApprovalService is one coarse, neutral lifecycle surface served on the
// existing private Platform gRPC endpoint. Product wrappers and status
// vocabulary remain L1-owned.
service ApprovalService {
  rpc ExecuteApproval(ExecuteApprovalRequest) returns (ExecuteApprovalResponse);
  rpc ReadApproval(ReadApprovalRequest) returns (ReadApprovalResponse);
}

enum ApprovalOperation {
  APPROVAL_OPERATION_UNSPECIFIED = 0;
  APPROVAL_OPERATION_SUBMIT = 1;
  APPROVAL_OPERATION_APPROVE = 2;
  APPROVAL_OPERATION_REJECT = 3;
  APPROVAL_OPERATION_RECALL = 4;
  APPROVAL_OPERATION_REASSIGN = 5;
}

enum ApprovalInstanceState {
  APPROVAL_INSTANCE_STATE_UNSPECIFIED = 0;
  APPROVAL_INSTANCE_STATE_PENDING = 1;
  APPROVAL_INSTANCE_STATE_APPROVED = 2;
  APPROVAL_INSTANCE_STATE_REJECTED = 3;
  APPROVAL_INSTANCE_STATE_WITHDRAWN = 4;
}

enum ApprovalActionFailureKind {
  APPROVAL_ACTION_FAILURE_KIND_UNSPECIFIED = 0;
  APPROVAL_ACTION_FAILURE_KIND_ALERT = 1;
  APPROVAL_ACTION_FAILURE_KIND_FLOW = 2;
  APPROVAL_ACTION_FAILURE_KIND_UNSUPPORTED = 3;
}

enum ApprovalActionFailureReason {
  APPROVAL_ACTION_FAILURE_REASON_UNSPECIFIED = 0;
  APPROVAL_ACTION_FAILURE_REASON_UNAVAILABLE = 1;
  APPROVAL_ACTION_FAILURE_REASON_INVALID_BINDING = 2;
  APPROVAL_ACTION_FAILURE_REASON_UNSAFE_DEFINITION = 3;
  APPROVAL_ACTION_FAILURE_REASON_EXECUTION_FAILED = 4;
  APPROVAL_ACTION_FAILURE_REASON_UNSUPPORTED_ACTION = 5;
}

message ExecuteApprovalRequest {
  ApprovalOperation operation = 1;
  string idempotency_key = 2;
  string object_id = 3;
  string target_record_id = 4;
  string work_item_id = 5;
  string comments = 6;
  string next_actor_id = 7;
  bool skip_entry_criteria = 8;
  optional uint64 min_catalog_revision = 9;
}

message ApprovalWorkItemAssignment {
  string work_item_id = 1;
  string actor_id = 2;
}

message ApprovalActionFailure {
  string action_ref = 1;
  ApprovalActionFailureKind kind = 2;
  ApprovalActionFailureReason reason = 3;
}

enum ApprovalSubmitRejectionReason {
  APPROVAL_SUBMIT_REJECTION_REASON_UNSPECIFIED = 0;
  APPROVAL_SUBMIT_REJECTION_REASON_NO_ACTIVE_PROCESS = 1;
  APPROVAL_SUBMIT_REJECTION_REASON_ENTRY_CRITERIA_NOT_MET = 2;
  APPROVAL_SUBMIT_REJECTION_REASON_RECORD_VALIDATION_FAILED = 3;
}

// ApprovalValidationIssue carries only metadata-authored, caller-visible rule
// details. Runtime must never construct these fields from arbitrary error text.
message ApprovalValidationIssue {
  string rule_name = 1;
  string field = 2;
  string message = 3;
}

message ApprovalSubmitRejection {
  ApprovalSubmitRejectionReason reason = 1;
  repeated ApprovalValidationIssue validation_issues = 2;
}

message ExecuteApprovalResponse {
  string execution_id = 1;
  string instance_id = 2;
  string target_record_id = 3;
  string source_work_item_id = 4;
  ApprovalInstanceState state = 5;
  repeated ApprovalWorkItemAssignment pending_work_items = 6;
  repeated ApprovalActionFailure action_failures = 7;
  nexuscrm.common.v1.ConsistencyReceipts receipts = 8;
  // Trusted principal that authorized this execution. Optional for N-1
  // Runtime responses; never supplied by the caller as an actor selector.
  string acting_principal_id = 9;
  // Present only when Submit was evaluated without creating an instance.
  ApprovalSubmitRejection submit_rejection = 10;
}

enum ApprovalReadKind {
  APPROVAL_READ_KIND_UNSPECIFIED = 0;
  APPROVAL_READ_KIND_PENDING_FOR_CALLER = 1;
  APPROVAL_READ_KIND_LATEST_FOR_RECORD = 2;
  APPROVAL_READ_KIND_STEP_DISPLAY_FOR_RECORD = 3;
}

message ReadApprovalRequest {
  ApprovalReadKind kind = 1;
  string target_record_id = 2;
  optional uint64 min_catalog_revision = 3;
}

message ApprovalPendingItem {
  string work_item_id = 1;
  string instance_id = 2;
  string definition_id = 3;
  string target_record_id = 4;
  string object_id = 5;
  string submitted_by_id = 6;
  string submitted_by_name = 7;
  string submitted_at = 8;
  string actor_id = 9;
  string original_actor_id = 10;
  string comments = 11;
  string record_name = 12;
}

message ApprovalPendingWorkItem {
  string work_item_id = 1;
  string actor_id = 2;
  string actor_name = 3;
  string original_actor_id = 4;
  string original_actor_name = 5;
}

message ApprovalInstanceSummary {
  string instance_id = 1;
  string definition_id = 2;
  string target_record_id = 3;
  ApprovalInstanceState state = 4;
  string submitted_by_id = 5;
  string submitted_by_name = 6;
  string created_at = 7;
  string completed_at = 8;
  repeated ApprovalPendingWorkItem pending_work_items = 9;
}

enum ApprovalStepNoMatchBehavior {
  APPROVAL_STEP_NO_MATCH_BEHAVIOR_UNSPECIFIED = 0;
  APPROVAL_STEP_NO_MATCH_BEHAVIOR_NEXT_STEP = 1;
  APPROVAL_STEP_NO_MATCH_BEHAVIOR_APPROVE = 2;
  APPROVAL_STEP_NO_MATCH_BEHAVIOR_REJECT = 3;
}

message ApprovalStepDisplay {
  string step_id = 1;
  uint32 step_order = 2;
  string step_name = 3;
  string step_label = 4;
  bool has_criteria = 5;
  ApprovalStepNoMatchBehavior no_match_behavior = 6;
}

message ReadApprovalResponse {
  repeated ApprovalPendingItem pending = 1;
  ApprovalInstanceSummary latest = 2;
  repeated ApprovalStepDisplay steps = 3;
  nexuscrm.common.v1.ConsistencyReceipts receipts = 4;
}