// Copyright 2024 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 how parts in the parts list are matched against parts 
 * in the AVL or Part Library.
 */
enum MatchingMode {
  Both	= 0;		// Matches both part number and manufacturer.
  Part	= 1;		// Matches part number only.
}

/**
 * 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;
  string ccaName      = 2;
  MatchingMode matching       = 3;
  DuplicationMode duplication = 4;
  AVLPartNum avlPartNum       = 5;
  AVLDescription avlDesc      = 6;
}

message UpdatePartsListFromAVLResponse {
  ReturnCode returnCode = 1;
  int32 numPartsUpdated = 2;
  repeated string updateErrors = 3;
}

/**
 * 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;		// Name of the CCA.
    message Part {
      string refDes		= 1;	// Reference Designator for the part.
      string partNumber	= 2;	// Part number.
    }
    repeated Part parts	= 2;
  }
  repeated CCA ccas			= 2;
}

/**
 * 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;	// Ref Des 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;
}

/**
 * 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 {
  string project				= 1;	// Sherlock project name.
  string ccaName				= 2;	// The CCA name.
  string refDes					= 3;	// A comma separated list of ref des 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 {
  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;	// RefDes for the corresponding part.
  }
  repeated LocationData locationData = 2;
}

/**
 * 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.
}

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.
  rpc getPartLocation(GetPartLocationRequest) returns (GetPartLocationResponse);

  // Export the net list to a file.
  rpc exportNetList(ExportNetListRequest) returns (ReturnCode);
}
