feat(niki): add return awaiting kindbox permission and route (#81)

delivery/http_server/admin/kind_box/get_return_awaiting.go

@@ -0,0 +1,53 @@
+package adminkindboxhandler
+
+import (
+	"net/http"
+
+	param "git.gocasts.ir/ebhomengo/niki/param/admin/kind_box"
+	"git.gocasts.ir/ebhomengo/niki/pkg/claim"
+	httpmsg "git.gocasts.ir/ebhomengo/niki/pkg/http_msg"
+	"github.com/labstack/echo/v4"
+)
+
+// GetAwaitingReturn godoc
+// @Summary      Get a kind box that is awaiting return by agent
+// @Tags         KindBox
+// @Accept       json
+// @Produce      json
+// @Param        id path int true "KindBox ID"
+// @Success      200  {object}  param.ReturnAwaitingGetResponse
+// @Failure      400  {string}  "Bad Request"
+// @Failure      401  {string}  "invalid or expired jwt"
+// @Failure      403  {string}  "user not allowed"
+// @Failure      422  {object}  httpmsg.ErrorResponse
+// @Failure      404  {string}  "record not found"
+// @Failure      500  {string}  "something went wrong"
+// @Security 	 AuthBearerAdmin
+// @Router       /admin/kindboxes/awaiting-return/{id} [get]
+func (h Handler) GetAwaitingReturn(c echo.Context) error {
+	var req param.ReturnAwaitingGetRequest
+	if bErr := c.Bind(&req); bErr != nil {
+		return echo.NewHTTPError(http.StatusBadRequest)
+	}
+
+	claims := claim.GetClaimsFromEchoContext(c)
+	req.AgentID = claims.UserID
+
+	if fieldErrors, err := h.adminKindBoxVld.ValidateGetAwaitingReturnRequest(req); err != nil {
+		msg, code := httpmsg.Error(err)
+
+		return c.JSON(code, httpmsg.ErrorResponse{
+			Message: msg,
+			Errors:  fieldErrors,
+		})
+	}
+
+	resp, sErr := h.adminKindBoxSvc.GetAwaitingReturn(c.Request().Context(), req)
+	if sErr != nil {
+		msg, code := httpmsg.Error(sErr)
+
+		return echo.NewHTTPError(code, msg)
+	}
+
+	return c.JSON(http.StatusOK, resp)
+}

delivery/http_server/admin/kind_box/route.go

@@ -14,4 +14,5 @@ func (h Handler) SetRoutes(e *echo.Echo) {
 	r.GET("/:id", h.Get, middleware.AdminAuthorization(h.adminAuthorizeSvc, entity.AdminKindBoxGetPermission))
 	r.PATCH("/assign-receiver-agent/:id", h.AssignReceiverAgent, middleware.AdminAuthorization(h.adminAuthorizeSvc, entity.AdminKindBoxAssignReceiverAgentPermission))
 	r.GET("", h.GetAll, middleware.AdminAuthorization(h.adminAuthorizeSvc, entity.AdminKindBoxGetAllPermission))
+	r.GET("/awaiting-return/:id", h.GetAwaitingReturn, middleware.AdminAuthorization(h.adminAuthorizeSvc, entity.AdminKindBoxGetAwaitingReturnPermission))
 }

delivery/http_server/middleware/admin_authorization.go

@@ -19,15 +19,11 @@ func AdminAuthorization(service adminauthorizationservice.Service,
 
 			isAllowed, err := service.CheckAccess(claims.UserID, entity.MapToAdminRole(claims.Role), permissions...)
 			if err != nil {
-				return c.JSON(http.StatusInternalServerError, echo.Map{
-					"message": errmsg.ErrorMsgSomethingWentWrong,
-				})
+				return echo.NewHTTPError(http.StatusInternalServerError, errmsg.ErrorMsgSomethingWentWrong)
 			}
 
 			if !isAllowed {
-				return c.JSON(http.StatusForbidden, echo.Map{
-					"message": errmsg.ErrorMsgUserNotAllowed,
-				})
+				return echo.NewHTTPError(http.StatusForbidden, errmsg.ErrorMsgUserNotAllowed)
 			}
 
 			return next(c)

docs/docs.go

@@ -509,6 +509,78 @@ const docTemplate = `{
                 }
             }
         },
+        "/admin/kindboxes/awaiting-return/{id}": {
+            "get": {
+                "security": [
+                    {
+                        "AuthBearerAdmin": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "KindBox"
+                ],
+                "summary": "Get a kind box that is awaiting return by agent",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "KindBox ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/adminkindboxparam.ReturnAwaitingGetResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "401": {
+                        "description": "invalid or expired jwt",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "403": {
+                        "description": "user not allowed",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "record not found",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/httpmsg.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "something went wrong",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
         "/admin/kindboxes/{id}": {
             "get": {
                 "security": [
@@ -1829,6 +1901,59 @@ const docTemplate = `{
                 }
             }
         },
+        "adminkindboxparam.ReturnAwaitingGetResponse": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "integer"
+                },
+                "benefactorID": {
+                    "type": "integer"
+                },
+                "deliverAddressID": {
+                    "type": "integer"
+                },
+                "deliverReferDate": {
+                    "type": "string"
+                },
+                "deliveredAt": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "integer"
+                },
+                "kindBoxReqID": {
+                    "type": "integer"
+                },
+                "kindBoxType": {
+                    "$ref": "#/definitions/entity.KindBoxType"
+                },
+                "receiverAgentID": {
+                    "type": "integer"
+                },
+                "returnAddressID": {
+                    "type": "integer"
+                },
+                "returnReferDate": {
+                    "type": "string"
+                },
+                "returnReferTimeID": {
+                    "type": "integer"
+                },
+                "returnedAt": {
+                    "type": "string"
+                },
+                "senderAgentID": {
+                    "type": "integer"
+                },
+                "serialNumber": {
+                    "type": "string"
+                },
+                "status": {
+                    "$ref": "#/definitions/entity.KindBoxStatus"
+                }
+            }
+        },
         "adminkindboxreqparam.AssignSenderRequest": {
             "type": "object",
             "properties": {
@@ -2738,6 +2863,20 @@ const docTemplate = `{
                 }
             }
         },
+        "httpmsg.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "message": {
+                    "type": "string"
+                }
+            }
+        },
         "param.PaginationResponse": {
             "type": "object",
             "properties": {

docs/swagger.json

@@ -498,6 +498,78 @@
                 }
             }
         },
+        "/admin/kindboxes/awaiting-return/{id}": {
+            "get": {
+                "security": [
+                    {
+                        "AuthBearerAdmin": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "KindBox"
+                ],
+                "summary": "Get a kind box that is awaiting return by agent",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "KindBox ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/adminkindboxparam.ReturnAwaitingGetResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "401": {
+                        "description": "invalid or expired jwt",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "403": {
+                        "description": "user not allowed",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "record not found",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/httpmsg.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "something went wrong",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
         "/admin/kindboxes/{id}": {
             "get": {
                 "security": [
@@ -1818,6 +1890,59 @@
                 }
             }
         },
+        "adminkindboxparam.ReturnAwaitingGetResponse": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "integer"
+                },
+                "benefactorID": {
+                    "type": "integer"
+                },
+                "deliverAddressID": {
+                    "type": "integer"
+                },
+                "deliverReferDate": {
+                    "type": "string"
+                },
+                "deliveredAt": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "integer"
+                },
+                "kindBoxReqID": {
+                    "type": "integer"
+                },
+                "kindBoxType": {
+                    "$ref": "#/definitions/entity.KindBoxType"
+                },
+                "receiverAgentID": {
+                    "type": "integer"
+                },
+                "returnAddressID": {
+                    "type": "integer"
+                },
+                "returnReferDate": {
+                    "type": "string"
+                },
+                "returnReferTimeID": {
+                    "type": "integer"
+                },
+                "returnedAt": {
+                    "type": "string"
+                },
+                "senderAgentID": {
+                    "type": "integer"
+                },
+                "serialNumber": {
+                    "type": "string"
+                },
+                "status": {
+                    "$ref": "#/definitions/entity.KindBoxStatus"
+                }
+            }
+        },
         "adminkindboxreqparam.AssignSenderRequest": {
             "type": "object",
             "properties": {
@@ -2727,6 +2852,20 @@
                 }
             }
         },
+        "httpmsg.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "message": {
+                    "type": "string"
+                }
+            }
+        },
         "param.PaginationResponse": {
             "type": "object",
             "properties": {

docs/swagger.yaml

@@ -121,6 +121,41 @@ definitions:
       status:
         $ref: '#/definitions/entity.KindBoxStatus'
     type: object
+  adminkindboxparam.ReturnAwaitingGetResponse:
+    properties:
+      amount:
+        type: integer
+      benefactorID:
+        type: integer
+      deliverAddressID:
+        type: integer
+      deliverReferDate:
+        type: string
+      deliveredAt:
+        type: string
+      id:
+        type: integer
+      kindBoxReqID:
+        type: integer
+      kindBoxType:
+        $ref: '#/definitions/entity.KindBoxType'
+      receiverAgentID:
+        type: integer
+      returnAddressID:
+        type: integer
+      returnReferDate:
+        type: string
+      returnReferTimeID:
+        type: integer
+      returnedAt:
+        type: string
+      senderAgentID:
+        type: integer
+      serialNumber:
+        type: string
+      status:
+        $ref: '#/definitions/entity.KindBoxStatus'
+    type: object
   adminkindboxreqparam.AssignSenderRequest:
     properties:
       sender_agent_id:
@@ -727,6 +762,15 @@ definitions:
       name:
         type: string
     type: object
+  httpmsg.ErrorResponse:
+    properties:
+      errors:
+        additionalProperties:
+          type: string
+        type: object
+      message:
+        type: string
+    type: object
   param.PaginationResponse:
     properties:
       page_number:
@@ -1095,6 +1139,52 @@ paths:
       summary: Admin assign receiver agent to kindbox
       tags:
       - KindBox
+  /admin/kindboxes/awaiting-return/{id}:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: KindBox ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/adminkindboxparam.ReturnAwaitingGetResponse'
+        "400":
+          description: Bad Request
+          schema:
+            type: string
+        "401":
+          description: invalid or expired jwt
+          schema:
+            type: string
+        "403":
+          description: user not allowed
+          schema:
+            type: string
+        "404":
+          description: record not found
+          schema:
+            type: string
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/httpmsg.ErrorResponse'
+        "500":
+          description: something went wrong
+          schema:
+            type: string
+      security:
+      - AuthBearerAdmin: []
+      summary: Get a kind box that is awaiting return by agent
+      tags:
+      - KindBox
   /admin/kindboxreqs:
     get:
       consumes:

entity/admin_permission.go

@@ -16,4 +16,5 @@ const (
 	AdminKindBoxAssignReceiverAgentPermission    = AdminPermission("kindbox-assign_receiver_agent")
 	AdminKindBoxGetAllPermission                 = AdminPermission("kindbox-getall")
 	AdminKindBoxReqUpdatePermission              = AdminPermission("kindboxreq-update")
+	AdminKindBoxGetAwaitingReturnPermission      = AdminPermission("kindbox-get_awaiting_return")
 )

param/admin/kind_box/get_return_awaiting.go

@@ -0,0 +1,12 @@
+package adminkindboxparam
+
+import "git.gocasts.ir/ebhomengo/niki/entity"
+
+type ReturnAwaitingGetRequest struct {
+	KindBoxID uint `param:"id"`
+	AgentID   uint
+}
+
+type ReturnAwaitingGetResponse struct {
+	entity.KindBox
+}

pkg/http_msg/err_response.go

@@ -0,0 +1,6 @@
+package httpmsg
+
+type ErrorResponse struct {
+	Message string            `json:"message"`
+	Errors  map[string]string `json:"errors"`
+}

repository/mysql/dbconfig.yml

@@ -1,5 +1,5 @@
 production:
   dialect: mysql
-  datasource: niki:nikiappt0lk2o20(localhost:3306)/niki_db?parseTime=true
+  datasource: niki:nikiappt0lk2o20@(localhost:3306)/niki_db?parseTime=true
   dir: repository/mysql/migration
   table: gorp_migrations

repository/mysql/kind_box/get_return_awaiting.go

@@ -0,0 +1,30 @@
+package mysqlkindbox
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"git.gocasts.ir/ebhomengo/niki/entity"
+	errmsg "git.gocasts.ir/ebhomengo/niki/pkg/err_msg"
+	richerror "git.gocasts.ir/ebhomengo/niki/pkg/rich_error"
+)
+
+func (d DB) GetAwaitingReturnByAgent(ctx context.Context, kindBoxID uint, agentID uint) (entity.KindBox, error) {
+	const op = "mysqlkindbox.GetAwaitingReturnByAgent"
+
+	query := `SELECT * FROM kind_boxes WHERE id = ? AND receiver_agent_id = ? AND status = ? AND deleted_at IS NULL `
+	row := d.conn.Conn().QueryRowContext(ctx, query, kindBoxID, agentID, entity.KindBoxAssignedReceiverAgentStatus.String())
+	k, err := scanKindBox(row)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+
+			return entity.KindBox{}, richerror.New(op).WithErr(err).
+				WithMessage(errmsg.ErrorMsgNotFound).WithKind(richerror.KindNotFound)
+		}
+
+		return entity.KindBox{}, richerror.New(op).WithErr(err).
+			WithMessage(errmsg.ErrorMsgCantScanQueryResult).WithKind(richerror.KindUnexpected)
+	}
+
+	return k, nil
+}

repository/mysql/migration/1708712564_alter_admin_access_controls_table_permission_enum_field.sql

@@ -13,7 +13,8 @@ ALTER TABLE `admin_access_controls` MODIFY COLUMN `permission`
         'kindboxreq-add',
         'kindbox-assign_receiver_agent',
         'kindbox-getall',
-        'kindboxreq-update'
+        'kindboxreq-update',
+        'kindbox-get_awaiting_return'
     ) NOT NULL;
     
 -- +migrate Down

service/admin/kind_box/get_return_awaiting.go

@@ -0,0 +1,20 @@
+package adminkindboxservice
+
+import (
+	"context"
+	param "git.gocasts.ir/ebhomengo/niki/param/admin/kind_box"
+)
+
+func (s Service) GetAwaitingReturn(ctx context.Context, req param.ReturnAwaitingGetRequest) (param.ReturnAwaitingGetResponse, error) {
+	const op = "adminkindboxservice.GetAwaitingReturn"
+
+	kindBox, err := s.repo.GetAwaitingReturnByAgent(ctx, req.KindBoxID, req.AgentID)
+	if err != nil {
+
+		return param.ReturnAwaitingGetResponse{}, err
+	}
+
+	return param.ReturnAwaitingGetResponse{
+		KindBox: kindBox,
+	}, nil
+}

service/admin/kind_box/service.go

@@ -13,6 +13,7 @@ type Repository interface {
 	GetKindBox(ctx context.Context, kindBoxID uint) (entity.KindBox, error)
 	AssignReceiverAgent(ctx context.Context, kindBox entity.KindBox) error
 	GetAllKindBox(ctx context.Context, filter params.FilterRequest, pagination params.PaginationRequest, sort params.SortRequest) ([]entity.KindBox, uint, error)
+	GetAwaitingReturnByAgent(ctx context.Context, kindBoxID uint, agentID uint) (entity.KindBox, error)
 }
 
 type Service struct {

validator/admin/kind_box/get_return_awaiting.go

@@ -0,0 +1,36 @@
+package adminkindboxvalidator
+
+import (
+	"errors"
+	param "git.gocasts.ir/ebhomengo/niki/param/admin/kind_box"
+	errmsg "git.gocasts.ir/ebhomengo/niki/pkg/err_msg"
+	richerror "git.gocasts.ir/ebhomengo/niki/pkg/rich_error"
+	validation "github.com/go-ozzo/ozzo-validation/v4"
+)
+
+func (v Validator) ValidateGetAwaitingReturnRequest(req param.ReturnAwaitingGetRequest) (map[string]string, error) {
+	const op = "adminkindboxvalidator.ValidateGetAwaitingReturnRequest"
+
+	if err := validation.ValidateStruct(&req,
+		validation.Field(&req.KindBoxID, validation.Required),
+	); err != nil {
+		fieldErrors := make(map[string]string)
+
+		var errV validation.Errors
+		if errors.As(err, &errV) {
+			for key, value := range errV {
+				if value != nil {
+					fieldErrors[key] = value.Error()
+				}
+			}
+		}
+
+		return fieldErrors, richerror.New(op).
+			WithMessage(errmsg.ErrorMsgInvalidInput).
+			WithKind(richerror.KindInvalid).
+			WithMeta(map[string]interface{}{"req": req}).
+			WithErr(err)
+	}
+
+	return map[string]string{}, nil
+}