zou 0.20.82__py3-none-any.whl → 0.20.84__py3-none-any.whl

zou/app/blueprints/crud/person.py

@@ -31,6 +31,190 @@ class PersonsResource(BaseModelsResource):
     def __init__(self):
         BaseModelsResource.__init__(self, Person)
 
+    @jwt_required()
+    def get(self):
+        """
+        Get persons
+        ---
+        tags:
+          - Crud
+        description: Retrieve all persons. Supports filtering via query
+          parameters and pagination. Admin users can include password
+          hashes. Non-admin users only see minimal information.
+        parameters:
+          - in: query
+            name: page
+            required: false
+            schema:
+              type: integer
+            example: 1
+            description: Page number for pagination
+          - in: query
+            name: limit
+            required: false
+            schema:
+              type: integer
+            example: 50
+            description: Number of results per page
+          - in: query
+            name: relations
+            required: false
+            schema:
+              type: boolean
+            default: false
+            example: false
+            description: Whether to include relations
+          - in: query
+            name: with_pass_hash
+            required: false
+            schema:
+              type: boolean
+            default: false
+            example: false
+            description: Include password hash (admin only)
+        responses:
+            200:
+              description: Persons retrieved successfully
+              content:
+                application/json:
+                  schema:
+                    oneOf:
+                      - type: array
+                        items:
+                          type: object
+                      - type: object
+                        properties:
+                          data:
+                            type: array
+                            items:
+                              type: object
+                            example: []
+                          total:
+                            type: integer
+                            example: 100
+                          nb_pages:
+                            type: integer
+                            example: 2
+                          limit:
+                            type: integer
+                            example: 50
+                          offset:
+                            type: integer
+                            example: 0
+                          page:
+                            type: integer
+                            example: 1
+            400:
+              description: Invalid filter format or query error
+        """
+        return super().get()
+
+    @jwt_required()
+    def post(self):
+        """
+        Create person
+        ---
+        tags:
+          - Crud
+        description: Create a new person with data provided in the
+          request body. JSON format is expected. Requires admin
+          permissions. Validates role, contract_type, two_factor_authentication,
+          email, and expiration_date. Checks user limit for active non-bot users.
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - first_name
+                  - last_name
+                  - email
+                properties:
+                  first_name:
+                    type: string
+                    example: John
+                  last_name:
+                    type: string
+                    example: Doe
+                  email:
+                    type: string
+                    format: email
+                    example: john.doe@example.com
+                  password:
+                    type: string
+                    example: securepassword123
+                  role:
+                    type: string
+                    example: user
+                  active:
+                    type: boolean
+                    default: true
+                    example: true
+                  contract_type:
+                    type: string
+                    example: permanent
+                  two_factor_authentication:
+                    type: string
+                    example: none
+                  expiration_date:
+                    type: string
+                    format: date
+                    example: "2025-12-31"
+                  is_bot:
+                    type: boolean
+                    default: false
+                    example: false
+        responses:
+            201:
+              description: Person created successfully
+              content:
+                application/json:
+                  schema:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      first_name:
+                        type: string
+                        example: John
+                      last_name:
+                        type: string
+                        example: Doe
+                      email:
+                        type: string
+                        format: email
+                        example: john.doe@example.com
+                      role:
+                        type: string
+                        example: user
+                      active:
+                        type: boolean
+                        example: true
+                      contract_type:
+                        type: string
+                        example: permanent
+                      two_factor_authentication:
+                        type: string
+                        example: none
+                      access_token:
+                        type: string
+                        example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
+                      created_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+                      updated_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+            400:
+              description: Invalid data format or validation error or user limit reached
+        """
+        return super().post()
+
     def all_entries(self, query=None, relations=False):
         if query is None:
             query = self.model.query
@@ -138,6 +322,202 @@ class PersonResource(BaseModelResource, ArgsMixin):
     def check_read_permissions(self, instance):
         return True
 
+    @jwt_required()
+    def get(self, instance_id):
+        """
+        Get person
+        ---
+        tags:
+          - Crud
+        description: Retrieve a person by their ID and return it as a
+          JSON object. Supports including relations. Managers see safe
+          serialization, others see minimal information.
+        parameters:
+          - in: path
+            name: instance_id
+            required: true
+            schema:
+              type: string
+              format: uuid
+            example: a24a6ea4-ce75-4665-a070-57453082c25
+          - in: query
+            name: relations
+            required: false
+            schema:
+              type: boolean
+            default: true
+            example: true
+            description: Whether to include relations
+        responses:
+            200:
+              description: Person retrieved successfully
+              content:
+                application/json:
+                  schema:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      first_name:
+                        type: string
+                        example: John
+                      last_name:
+                        type: string
+                        example: Doe
+                      email:
+                        type: string
+                        format: email
+                        example: john.doe@example.com
+                      role:
+                        type: string
+                        example: user
+                      active:
+                        type: boolean
+                        example: true
+                      contract_type:
+                        type: string
+                        example: permanent
+                      two_factor_authentication:
+                        type: string
+                        example: none
+                      departments:
+                        type: array
+                        items:
+                          type: string
+                          format: uuid
+                        example: []
+                      created_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+                      updated_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+            400:
+              description: Invalid ID format or query error
+        """
+        return super().get(instance_id)
+
+    @jwt_required()
+    def put(self, instance_id):
+        """
+        Update person
+        ---
+        tags:
+          - Crud
+        description: Update a person with data provided in the request
+          body. JSON format is expected. Users can only update themselves
+          unless they have admin permissions. Non-admins cannot change
+          certain protected fields. Validates role, contract_type,
+          two_factor_authentication, email, and expiration_date. Checks
+          user limit when activating non-bot users. Protected accounts
+          have restrictions.
+        parameters:
+          - in: path
+            name: instance_id
+            required: true
+            schema:
+              type: string
+              format: uuid
+            example: a24a6ea4-ce75-4665-a070-57453082c25
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  first_name:
+                    type: string
+                    example: Jane
+                  last_name:
+                    type: string
+                    example: Smith
+                  email:
+                    type: string
+                    format: email
+                    example: jane.smith@example.com
+                  password:
+                    type: string
+                    example: newsecurepassword123
+                  role:
+                    type: string
+                    example: manager
+                    description: Admin only
+                  active:
+                    type: boolean
+                    example: true
+                    description: Admin only
+                  contract_type:
+                    type: string
+                    example: freelance
+                  two_factor_authentication:
+                    type: string
+                    example: totp
+                  expiration_date:
+                    type: string
+                    format: date
+                    example: "2025-12-31"
+                    description: Person or admin only
+        responses:
+            200:
+              description: Person updated successfully
+              content:
+                application/json:
+                  schema:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      first_name:
+                        type: string
+                        example: Jane
+                      last_name:
+                        type: string
+                        example: Smith
+                      email:
+                        type: string
+                        format: email
+                        example: jane.smith@example.com
+                      role:
+                        type: string
+                        example: manager
+                      active:
+                        type: boolean
+                        example: true
+                      contract_type:
+                        type: string
+                        example: freelance
+                      two_factor_authentication:
+                        type: string
+                        example: totp
+                      departments:
+                        type: array
+                        items:
+                          type: string
+                          format: uuid
+                        example: []
+                      access_token:
+                        type: string
+                        example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
+                      created_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+                      updated_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T11:00:00Z"
+            400:
+              description: Invalid data format or validation error or user limit reached or protected account restriction
+        """
+        return super().put(instance_id)
+
     def check_update_permissions(self, instance_dict, data):
         if instance_dict["id"] != persons_service.get_current_user()["id"]:
             permissions.check_admin_permissions()
@@ -259,8 +639,33 @@ class PersonResource(BaseModelResource, ArgsMixin):
     @jwt_required()
     def delete(self, instance_id):
         """
-        Delete a person corresponding at given ID and return it as a JSON
-        object.
+        Delete person
+        ---
+        tags:
+          - Crud
+        description: Delete a person by their ID. Returns empty response
+          on success. Cannot delete yourself.
+        parameters:
+          - in: path
+            name: instance_id
+            required: true
+            schema:
+              type: string
+              format: uuid
+            example: a24a6ea4-ce75-4665-a070-57453082c25
+          - in: query
+            name: force
+            required: false
+            schema:
+              type: boolean
+            default: false
+            example: false
+            description: Force deletion even if person has associated data
+        responses:
+            204:
+              description: Person deleted successfully
+            400:
+              description: Cannot delete person or integrity error
         """
         force = self.get_force()
         person = self.get_model_or_404(instance_id)