// Copyright 2023-2025 ANSYS, Inc. Unauthorized use, distribution, or duplication is prohibited.
syntax = "proto3";

import "ansys/api/sherlock/v0/SherlockCommonService.proto";

option java_package = "sherlock.grpc";
option java_outer_classname = "SherlockPartsServiceProto";

/**
 * Request to list the available parts libraries.
 */
message ListPartsLibrariesRequest {
}

/**
 * Determines what happens when there are duplicate matches for parts in the part list
 * against parts in the AVL or Part Library.
 */
enum DuplicationMode {
  First	= 0;					// Uses first matched when there is duplication.
  Error	= 1;					// Generates an error when there is duplication.
  Ignore = 2;					// Ignore the matches when there is duplication.
}

/**
 * Determines what fields in the part list will get updated by the AVL.
 */
enum AVLPartNum {
  AssignInternalPartNum = 0;      // Assign internal part number.
  AssignVendorAndPartNum = 1;     // Assign vendor & part number.
  DoNotChangeVendorOrPartNum = 2; // Do not change vendor / part number.
}

/**
 * Determines if the part description in the parts list 
 * will be updated by the AVL.
 */
enum AVLDescription {
  AssignApprovedDescription = 0;  // Assign approved description.
  DoNotChangeDescription = 1;     // Do not change description.
}

/**
 * Represents a list of available parts libraries.
 */
message ListPartsLibrariesResponse {
  ReturnCode returnCode			= 1;	// Status code of response.
  repeated string partLibrary	= 2;	// Parts library name.
}

/**
 * Request to update a parts list based on matching and duplication preferences provided.
 */
message UpdatePartsListRequest {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
  string partLibrary			= 3;	// Parts library name.
  
  MatchingMode matching			= 4;	// Designates the matching mode for updates.
  
  DuplicationMode duplication 	= 5;	// Designates how to handle duplications during update.
}

/**
 * Contains the status of the update as well as all of the update error messages.
 */
message UpdatePartsListResponse {
  ReturnCode returnCode 		= 1;	// Status code of response.
  repeated string updateError	= 2;	// Parts update error messages.
}

/**
 * Request to update the parts list from AVL.
 */
message UpdatePartsListFromAVLRequest {
  string project      = 1;          // Sherlock project name.
  string ccaName      = 2;          // The CCA name.
  MatchingMode matching       = 3;  // How sherlock matches parts in the AVL
  DuplicationMode duplication = 4;  // How sherlock handles duplicate parts found.
  AVLPartNum avlPartNum       = 5;  // Update part number and vendor/manufacturer or part number only.
  AVLDescription avlDesc      = 6;  // Update description or not.
}

message UpdatePartsListFromAVLResponse {
  ReturnCode returnCode = 1;        // Status code of response.
  int32 numPartsUpdated = 2;        // Number of parts updated in the parts list.
  repeated string updateErrors = 3; // Specific errors that occured during update.
}

/**
 * Request to get a list of parts not updated from the Sherlock Part Library.
 */
message ListPartsNotUpdatedRequest {
  string project		= 1;	// Sherlock project name.
}

/**
 * Represents a list of parts not updated from the Sherlock Part Library.
 */
message ListPartsNotUpdatedResponse {
  ReturnCode returnCode = 1;	// Status code of response.
  message CCA {
    string ccaName      = 1;	// The CCA name.
    message Part {
      string refDes     = 1;	// Reference designator for the part.
      string partNumber = 2;	// Part number.
    }
    repeated Part parts = 2;    // List of Parts not updated for a CCA.
  }
  repeated CCA ccas     = 2;    // List of CCAs containing Parts not updated.
}

/**
 * Request to enable Lead Modeling for all non LEADLESS parts leads.
 */
message UpdateLeadModelingRequest {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
}

/**
 * Request to export the parts list for all parts for a project CCA.
 */
message ExportPartsListRequest {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
  string exportFile		 		= 3;	// Full file path to the export parts list .csv file.
}

/**
 * Request to import a parts list for a project CCA.
 */
message ImportPartsListRequest {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
  string importFile		 		= 3;	// Full file path to the parts list .csv file.
  bool importAsUserSrc			= 4;	// If true, set the data source of the properties to "User". Otherwise, set the data source to the name of the importFile.
}

/**
 * Request to set a part's location.
 */
message UpdatePartsLocationsRequest {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
  message PartLocation {
    string refDes			= 1;	// Reference designator of the part.
    string x				= 2;	// Location of the part along the X axis.
    string y				= 3;	// Location of the part along the Y axis.
    string rotation			= 4;	// Rotation of the part on the board in degrees.
    string locationUnits	= 5;	// Unit of length for the part location. Supported values are IN, MM, M, MIL, MICRON, and NM.
    string boardSide		= 6;	// Side of board on which the component exists. Supported values are TOP and BOTTOM.
    string mirrored			= 7;	// Indicates if the component is mirrored across the Y-axis. Supported values are Y, and N.
  }
  repeated PartLocation partLoc	= 3;  // List of part locations to be updated for a specified project and CCA.
}

/**
 * Contains the status of the parts locations update as well as all the update error messages.
 */
message UpdatePartsLocationsResponse {
  ReturnCode returnCode 		= 1;	// Status code of response.
  repeated string updateError	= 2;	// Parts locations update error messages.
}

/**
 * Request to update one or more parts' locations using a CSV file.
 */
message UpdatePartsLocationsByFileRequest {
  string project					= 1;	// Sherlock project name.
  string ccaName					= 2;	// The CCA name.
  string numericFormat				= 3;	// Numeric format for the file. If not provided, it will default to "English (United States)".
  string filePath					= 4;	// File that contains the components and location properties.
}

/**
 * Contains the status of the parts locations update as well as all the update error messages.
 */
message UpdatePartsLocationsByFileResponse {
  ReturnCode returnCode 		= 1;	// Status code of response.
  repeated string updateError	= 2;	// Parts locations update error messages.
}

/**
 * Request to list valid location units.
 */
message GetPartLocationUnitsRequest {
}

/**
 * Represents a list of valid location units.
 */
message GetPartLocationUnitsResponse {
  ReturnCode returnCode 	= 1;	// Status code of response.
  repeated string units		= 2;	// Location units.
}

/**
 * Request to list valid board sides.
 */
message GetBoardSidesRequest {
}

/**
 * Represents a list of valid board sides.
 */
message GetBoardSidesResponse {
  ReturnCode returnCode 		= 1;	// Status code of response.
  repeated string boardSides 	= 2;	// Board sides.
}

/**
 * Request to get a part's location.
 */
message GetPartLocationRequest {
  option deprecated = true; // Signifies this message is being deprecated as of 25R2.
  string project       = 1; // Sherlock project name.
  string ccaName       = 2; // The CCA name.
  string refDes        = 3; // A comma separated list of reference designators for a list of parts, or a Ref Des for one part.
  string locationUnits = 4; // Unit of length for the part location. Supported values are IN, MM, M, MIL, MICRON, and NM.
}

/**
 * Represents one or multiple parts' location properties.
 */
message GetPartLocationResponse {
  option deprecated                  = true; // Signifies this message is being deprecated as of 25R2.
  ReturnCode returnCode              = 1;    // Status code of response.
  message LocationData {
    double x                = 1;      // Location of the part along the X axis.
    double y                = 2;      // Location of the part along the Y axis.
    double rotation         = 3;      // Rotation of the part on the board in degrees.
    string locationUnits    = 4;      // Unit of length for the part location.
    string boardSide        = 5;      // Side of board on which the component exists.
    bool mirrored           = 6;      // Indicates if the component is mirrored across the Y-axis.
    string refDes           = 7;      // Ref Des for the corresponding part.
  }
  repeated LocationData locationData = 2;    // List of location data for a part or list of parts in a specified project and CCA.
}

/**
 * Request to get the properties for a list of parts.
 */
message GetPartsListPropertiesRequest {
  string project         = 1; // Sherlock project name.
  string ccaName         = 2; // The CCA name.
  repeated string refDes = 3; // The reference designator for each part to get properties for. If not included, get properties for all parts in the CCA.
}

/**
 * Represents the properties for a part.
 */
message GetPartsListPropertiesResponse {
  ReturnCode returnCode        = 1;         // Status code of response.
  string refDes                = 2;         // The reference designator of the part.
  message Property {
    string name  = 1; // Name of the property.
    string value = 2; // Value of the property.
  }
  repeated Property properties = 3;         // All properties applicable to the part.
}

/**
 * Request to update one or more properties of one or more parts in a parts list.
 */
message UpdatePartsListPropertiesRequest {
  string project                         = 1; // Sherlock project name.
  string ccaName                         = 2; // The CCA name for which part properties will be updated.         
  message PartProperties {
    repeated string refDes       = 1; // The reference designator for each part to be updated. If not included, update properties for all parts in the CCA.
    message Property {
      string name  = 1; // Name of property to be updated.
      string value = 2; // Value to be applied to the chosen part property.
    }
    repeated Property properties = 2; // Part properties to be updated.  
  }
  repeated PartProperties partProperties = 3; // List of parts with properties to be updated.
}

/**
 * Contains the status of the parts properties update as well as all the update error messages.
 */
message UpdatePartsListPropertiesResponse {
  ReturnCode returnCode                   = 1; // Status code of response.
  message PartPropertyError {
    optional string refDes = 1; // The reference designator of the part. Not set for invalid property name errors.
    string message         = 2; // Error message when updating the part.
  }
  repeated PartPropertyError updateErrors = 2; // Part property update errors.
}

/**
 * Contains the options needed to export a net list to a delimited output file (csv but can have delimiters other than a comma).
 */
message ExportNetListRequest {
  string project = 1; // Sherlock project name.
  string ccaName = 2; // The CCA name. 
  string outputFilePath = 3; // Full path of the file where the table will be written.
  bool overwriteExisting = 4; // Flag to determine if existing files should be overwritten if they match the outputFilePath. False by default.
  TableDelimiter colDelimiter = 5; // Enum that specifies supported delimiter character to be used. Set to COMMA by default. Not applicable to Excel files like xls, xlsx.
  bool utf8Enabled = 6; // Flag that specifies if UTF-8 will be used. False by default. Not applicable to Excel files like xls, xlsx.
}

/**
 * Request to update one or more pad properties of one or more parts in a parts list.
 */
 message UpdatePadPropertiesRequest {
  string project         = 1; // Sherlock project name.
  string ccaName         = 2; // The CCA name for which pad properties will be updated.         
  repeated string refDes = 3; // The reference designator of the associated part to be updated.
}

/**
 * Contains the status of the pad properties update as well as all the update error messages.
 */
message UpdatePadPropertiesResponse {
  ReturnCode returnCode	 = 1;	// Status code of response.
  string refDes          = 2; // The reference designator of the associated part.
}

/**
 * Request to delete parts from the parts list for a given project's CCA.
 */
message DeletePartsFromPartsListRequest {
  string project         = 1; // Sherlock project name.
  string ccaName         = 2; // The CCA name for which parts will be deleted.         
  repeated string refDes = 3; // The reference designator of the associated part to be deleted.
}

/**
 * Contains the status of the delete parts operation as well as all the delete error messages.
 */
message DeletePartsFromPartsListResponse {
  ReturnCode returnCode	 = 1;	// Status code of response.
  string refDes          = 2; // The reference designator of the associated part.
}

/**
 * Defines the supported AVL (Approved Vendor List) import modes.
 */
 enum AVLImportType {
  Replace = 0; // Replace Existing AVL By File Contents.
  Update  = 1; // Add New Parts & Update Existing Parts.
  Add     = 2; // Add New Parts Only.
}

/**
 * Request to import parts into the AVL (Approved Vendor List).
 */
message ImportPartsToAVLRequest {
  string importFile         = 1; // Full file path to the AVL file.
  AVLImportType importType  = 2; // Import mode to use for AVL data.
}

service SherlockPartsService {

  // List the available parts libraries.
  rpc listPartsLibraries(ListPartsLibrariesRequest) returns (ListPartsLibrariesResponse);

  // Update the parts list for a project's CCA.
  rpc updatePartsList(UpdatePartsListRequest) returns (UpdatePartsListResponse);

  // Update the parts list from the AVL.
  rpc updatePartsListFromAVL(UpdatePartsListFromAVLRequest) returns (UpdatePartsListFromAVLResponse);
  
  // Update the values of given parts.
  rpc updatePartsListProperties(UpdatePartsListPropertiesRequest) returns (UpdatePartsListPropertiesResponse);
  
  // List the parts that have not been updated from the Sherlock Part Library.
  rpc listPartsNotUpdated(ListPartsNotUpdatedRequest) returns (ListPartsNotUpdatedResponse);
  
  // Enable lead modeling for all non LEADLESS parts leads in a project's CCA.
  rpc updateLeadModeling(UpdateLeadModelingRequest) returns (ReturnCode);
  
  // Export parts list for all parts given a project's CCA.
  rpc exportPartsList(ExportPartsListRequest) returns (ReturnCode);
  
  // Import a parts list for a given a project's CCA.
  rpc importPartsList(ImportPartsListRequest) returns (ReturnCode);

  // Update one or more parts' locations.
  rpc updatePartsLocations(UpdatePartsLocationsRequest) returns (UpdatePartsLocationsResponse);

  // Update one or more parts' locations using a CSV file.
  rpc updatePartsLocationsByFile(UpdatePartsLocationsByFileRequest) returns (UpdatePartsLocationsByFileResponse);
    
  // Get a list of valid part location units.
  rpc getPartLocationUnits(GetPartLocationUnitsRequest) returns (GetPartLocationUnitsResponse);
  
  // Get a list of valid board side values.
  rpc getBoardSides(GetBoardSidesRequest) returns (GetBoardSidesResponse);
  
  // Get the location properties for a part. This is deprecated as of 25R2.
  rpc getPartLocation(GetPartLocationRequest) returns (GetPartLocationResponse) {
    option deprecated = true;
  }

  // Get the properties for a list of parts
  rpc getPartsListProperties(GetPartsListPropertiesRequest) returns (stream GetPartsListPropertiesResponse);
  
  // Export the net list to a file
  rpc exportNetList(ExportNetListRequest) returns (ReturnCode);

  // Updates the pad properties for one or more parts for a given project's CCA.
  rpc updatePadProperties(UpdatePadPropertiesRequest) returns (stream UpdatePadPropertiesResponse);

  // Delete parts from the parts list for a given project's CCA.
  rpc deletePartsFromPartsList(DeletePartsFromPartsListRequest) returns (stream DeletePartsFromPartsListResponse);

  // Import a support file containing parts to be added to the Approved Vendor List (AVL).
  rpc importPartsToAVL(ImportPartsToAVLRequest) returns (ReturnCode);
}
