// todo generate the protobuf code here
// delete the templates code start

syntax = "proto3";

package api.serverNameExample.v1;

import "validate/validate.proto";
import "api/types/types.proto";
import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "tagger/tagger.proto";

option go_package = "github.com/go-dev-frame/sponge/api/serverNameExample/v1;v1";

// Default settings for generating *.swagger.json documents. For reference, see: https://bit.ly/4dE5jj7
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  host: "localhost:8080"
  base_path: ""
  info: {
    title: "serverNameExample api docs";
    version: "v1.0.0";
  }
  schemes: HTTP;
  schemes: HTTPS;
  consumes: "application/json";
  produces: "application/json";
  security_definitions: {
    security: {
      key: "BearerAuth";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "Authorization";
        description: "Type Bearer your-jwt-token to Value";
      }
    }
  }
};

service userExample {
  // Create a new userExample
  rpc Create(CreateUserExampleRequest) returns (CreateUserExampleReply) {
    option (google.api.http) = {
      post: "/api/v1/userExample"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Create a new userExample";
      description: "Creates a new userExample entity using the provided data in the request body.";
    };
  }

  // Delete a userExample by id
  rpc DeleteByID(DeleteUserExampleByIDRequest) returns (DeleteUserExampleByIDReply) {
    option (google.api.http) = {
      delete: "/api/v1/userExample/{id}"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Delete a userExample by id";
      description: "Deletes a existing userExample identified by the given id in the path.";
      //security: {
      //  security_requirement: {
      //    key: "BearerAuth";
      //    value: {}
      //  }
      //}
    };
  }

  // Update a userExample by id
  rpc UpdateByID(UpdateUserExampleByIDRequest) returns (UpdateUserExampleByIDReply) {
    option (google.api.http) = {
      put: "/api/v1/userExample/{id}"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Update a userExample by id";
      description: "Updates the specified userExample with new data provided in the request body. The target is identified by id in the path.";
      //security: {
      //  security_requirement: {
      //    key: "BearerAuth";
      //    value: {}
      //  }
      //}
    };
  }

  // Get a userExample by id
  rpc GetByID(GetUserExampleByIDRequest) returns (GetUserExampleByIDReply) {
    option (google.api.http) = {
      get: "/api/v1/userExample/{id}"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Get a userExample by id";
      description: "Gets detailed information of a userExample specified by the given id in the path.";
      //security: {
      //  security_requirement: {
      //    key: "BearerAuth";
      //    value: {}
      //  }
      //}
    };
  }

  // get a list of userExamples by custom conditions
  rpc List(ListUserExampleRequest) returns (ListUserExampleReply) {
    option (google.api.http) = {
      post: "/api/v1/userExample/list"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "get a list of userExamples by custom conditions";
      description: "Returns a paginated list of userExamples filtered by specified query parameters. The request supports pagination (page number, page size) and filtering conditions.";
      //security: {
      //  security_requirement: {
      //    key: "BearerAuth";
      //    value: {}
      //  }
      //}
    };
  }
}


/*
Notes for defining message fields:
    1. Suggest using camel case style naming for message field names, such as firstName, lastName, etc.
    2. If the message field name ending in 'id', it is recommended to use xxxID naming format, such as userID, orderID, etc.
    3. Add validate rules https://github.com/envoyproxy/protoc-gen-validate#constraint-rules, such as:
        uint64 id = 1 [(validate.rules).uint64.gte  = 1];

If used to generate code that supports the HTTP protocol, notes for defining message fields:
    1. If the route contains the path parameter, such as /api/v1/userExample/{id}, the defined
        message must contain the name of the path parameter and the name should be added
        with a new tag, such as int64 id = 1 [(tagger.tags) = "uri:\"id\""];
    2. If the request url is followed by a query parameter, such as /api/v1/getUserExample?name=Tom,
        a form tag must be added when defining the query parameter in the message, such as:
        string name = 1 [(tagger.tags) = "form:\"name\""].
    3. When the message fields use snake_case naming (e.g., order_id), the generated swagger.json file
        will use camelCase (e.g., orderId) instead of the expected snake_case. This behavior aligns with
        the JSON tag names used by gRPC, but it can cause the Gin framework to fail to correctly bind and
        retrieve parameter values. There are two ways to resolve this issue:
            (1) Explicitly specify the JSON tag name using the json_name option, such as:
                 string order_id = 1 [json_name = "order_id"];
            (2) If you want to switch to camelCase naming and update the JSON tag name accordingly, such as:
                 string order_id = 1 [json_name = "orderID", (tagger.tags) = "json:\"orderID\""];
*/


enum GenderType {
  UNKNOWN = 0;
  MALE = 1;
  FEMALE = 2;
};

message CreateUserExampleRequest {
  string name = 1 [(validate.rules).string.min_len  = 2];         // name
  string email = 2 [(validate.rules).string.email = true];          // email
  string password = 3 [(validate.rules).string.min_len = 10];   // password
  string phone = 4 [(validate.rules).string = {pattern: "^1[3456789]\\d{9}$"}];    // phone number
  string avatar = 5 [(validate.rules).string.uri = true];       // avatar
  int32  age = 6 [(validate.rules).int32  = {gte:0, lte: 120}];    // age
  GenderType  gender = 7 [(validate.rules).enum.defined_only = true];  // gender, 1:Male, 2:Female, other values:unknown
}

message CreateUserExampleReply {
  uint64   id = 1;
}

message DeleteUserExampleByIDRequest {
  uint64   id = 1 [(validate.rules).uint64.gte  = 1, (tagger.tags) = "uri:\"id\"" ];
}

message DeleteUserExampleByIDReply {

}

message UpdateUserExampleByIDRequest {
  uint64   id = 1 [(validate.rules).uint64.gte  = 1 , (tagger.tags) = "uri:\"id\"" ];
  string name = 2;         // name
  string email = 3;         // email
  string password = 4;   // password
  string phone = 5;          // phone number
  string avatar = 6;         // avatar
  int32  age = 7;             // age
  GenderType  gender = 8;        // gender, 1:Male, 2:Female, other values:unknown
  int32  status = 9;         // account status
  int64  loginAt = 10;     // login timestamp
}

message UpdateUserExampleByIDReply {

}

message UserExample {
  uint64   id = 1;
  string name = 2;          // name
  string email = 3;          // email
  string phone = 4;           // phone number
  string avatar = 5;           // avatar
  int32  age = 6;               // age
  GenderType  gender = 7; // gender, 1:Male, 2:Female, other values:unknown
  int32  status = 8;           // account status
  int64  loginAt = 9;        // login timestamp
  string createdAt = 10;   // creation time
  string updatedAt = 11;  // update time
}

message GetUserExampleByIDRequest {
  uint64   id = 1 [(validate.rules).uint64.gte  = 1, (tagger.tags) = "uri:\"id\"" ];
}

message GetUserExampleByIDReply {
  UserExample userExample = 1;
}

message ListUserExampleRequest {
  api.types.Params params = 1 [(validate.rules).message.required = true];
}

message ListUserExampleReply {
  int64 total = 1;
  repeated UserExample userExamples = 2;
}

// delete the templates code end