feat: news resources

Author: TechAbraao

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help venv install start create-database
+.PHONY: help venv install start tests create-database
 
 VENV_DIR = .venv
 VENV_PYTHON = $(VENV_DIR)/bin/python
@@ -11,6 +11,7 @@ help:
 	@echo " * venv             -> Creates virtual environment (.venv)"
 	@echo " * install          -> Installs dependencies from src/requirements.txt"
 	@echo " * start            -> Starts the REST API (Python/Flask)"
+	@echo " * tests            -> Run all tests (PyTest)"
 	@echo " * create-database  -> Initializes the database"
 	@echo ""
 
@@ -23,5 +24,8 @@ install:
 start:
 	cd src && ../$(VENV_FLASK) run
 
+tests:
+	$(VENV_PYTHON) -m pytest
+
 create-database:
 	PYTHONPATH=src $(VENV_PYTHON) -c "from app.settings.database.init_db import init_db; init_db()"

README.md

@@ -119,6 +119,7 @@ git push origin main
 | PUT | `/api/cards/<card_id>` | Update a specific card |
 | DELETE | `/api/cards/<card_id>` | Remove card |
 
+
 - Example Payload for Cards
 
 ```json
@@ -151,4 +152,42 @@ All API responses follow the following pattern:
 ```
 > **Notes:**
 > - The `error` field contains the error object or list of errors.
-> - The `message` field describes the result of the operation or the reason for the error.
+> - The `message` field describes the result of the operation or the reason for the error.
+
+## Project Progress
+
+### Decks API
+- [ ] List all decks (GET /api/decks)
+- [ ] Create a new deck (POST /api/decks)
+  - [ ] Validate title is required and not empty
+  - [ ] Validate tags are list of strings (optional)
+  - [ ] Validate description max length 500 chars
+- [ ] Get deck details (GET /api/decks/<id>)
+  - [ ] Validate UUID format for `<id>`
+- [ ] Update deck information (PUT /api/decks/<id>)
+  - [ ] Validate fields if present (partial update)
+  - [ ] Validate title uniqueness (optional)
+- [ ] Delete a deck (DELETE /api/decks/<id>)
+  - [ ] Validate UUID format for `<id>`
+
+### Cards API
+- [ ] Add card to deck (POST /api/decks/<deck_id>/cards)
+  - [ ] Validate question is required and not empty
+  - [ ] Validate answer is required
+  - [ ] Validate tags are list of strings (optional)
+  - [ ] Validate deck_id is valid UUID and exists
+- [ ] Search all cards in a deck (GET /api/decks/<deck_id>/cards)
+  - [ ] Validate UUID format for `<deck_id>`
+- [ ] Search for random card (GET /api/decks/<deck_id>/cards/random)
+  - [ ] Validate UUID format for `<deck_id>`
+- [ ] Search specific card (GET /api/cards/<card_id>)
+  - [ ] Validate UUID format for `<card_id>`
+- [ ] Update card (PUT /api/cards/<card_id>)
+  - [ ] Validate fields if present
+  - [ ] Validate question uniqueness (optional)
+- [ ] Remove card (DELETE /api/cards/<card_id>)
+  - [ ] Validate UUID format for `<card_id>`
+
+### Testing
+- [ ] Unit tests for Decks endpoints
+- [ ] Unit tests for Cards endpoints

pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+markers =
+    unit: Testes de unidade — verificam funções ou classes isoladas, sem dependências externas.
+    integration: Testes de integração — validam a interação entre múltiplos componentes ou camadas do sistema.
+    controllers: Testes de controller — asseguram o formato e as chaves presentes no payload das respostas da API.
+    services: Testes de serviço — confirmam se os campos retornados têm os tipos de dados esperados.

src/app/blueprints/api/cards.py

@@ -16,7 +16,7 @@ def get_cards_by_deck(deck_uuid):
 def get_random_card(deck_uuid): pass
 
 @cards.route('/cards/<string:card_uuid>', methods=['GET'])
-def get_cards(deck_uuid): pass    
+def get_cards(card_uuid): return controller.searching_specific_card(card_uuid)
 
 @cards.route('/cards/<string:card_uuid>', methods=['PUT'])
 def update_card(deck_uuid): pass

src/app/blueprints/api/decks.py

@@ -2,31 +2,23 @@
 from src.app.controllers.decks_controller import DecksController
 from src.app.schemas.decks_schema import request_decks_schema, request_deck_id_schema
 from src.app.services.decks_services import decks_services
-from ..constants.routes import DECKS as routes
+from ..constants.routes import DECKS as r
 
 decks = Blueprint('decks', __name__)
-controller = DecksController(
-    request_validator=request_decks_schema, 
-    deck_services=decks_services,
-    id_validator=request_deck_id_schema
-)
-routes = routes.get("get_all_decks")
-@decks.route(routes.get("URI"), methods=[routes.get("method")])
-def get_all_decks(): 
-    return controller.get_all_decks()
+controller = DecksController(request_validator=request_decks_schema, deck_services=decks_services,id_validator=request_deck_id_schema)
 
-@decks.route(routes.get("URI"), methods=[routes.get("method")])
-def create_deck(): 
-    return controller.create_deck(request.get_json())
 
-@decks.route(routes.get("URI"), methods=[routes.get("method")])
-def get_deck(deck_id): 
-    return controller.get_deck_by_id(deck_id)
+@decks.route(r.get("get_all_decks").get("URI"), methods=[r.get("get_all_decks").get("method")])
+def get_all_decks(): return controller.get_all_decks()
 
-@decks.route(routes.get("URI"), methods=[routes.get("method")])
-def update_deck(deck_id): 
-    return controller.change_existing_deck(request.get_json(), deck_id)
+@decks.route(r.get("create_deck").get("URI"), methods=[r.get("create_deck").get("method")])
+def create_deck(): return controller.create_deck(request.get_json())
 
-@decks.route(routes.get("URI"), methods=[routes.get("method")])
-def delete_deck(deck_id): 
-    return controller.delete_existing_deck(deck_id)
+@decks.route(r.get("get_deck").get("URI"), methods=[r.get("get_deck").get("method")])
+def get_deck(deck_id): return controller.get_deck_by_id(deck_id)
+
+@decks.route(r.get("update_deck").get("URI"), methods=[r.get("update_deck").get("method")])
+def update_deck(deck_id): return controller.change_existing_deck(request.get_json(), deck_id)
+
+@decks.route(r.get("delete_deck").get("URI"), methods=[r.get("delete_deck").get("method")])
+def delete_deck(deck_id): return controller.delete_existing_deck(deck_id)

src/app/controllers/cards_controller.py

@@ -1,10 +1,11 @@
 from src.app.utils.responses.response import APIResponse
-from werkzeug.exceptions import BadRequest
+from werkzeug.exceptions import BadRequest, NotFound
 from src.app.utils.mocks.decks_mocks import mocks_responses_decks as mock
 from src.app.services.cards_services import CardsService
 from src.app.validators.cards_validator import CardsValidator
 from src.app.schemas.decks_schema import request_deck_id_schema
 
+
 class CardsController:
     def __init__(self):
         self.service = CardsService()
@@ -18,11 +19,23 @@ def get_cards_by_deck(self, id):
                 error="Formato do UUID não é válido.",
                 status_code=BadRequest.code
             )
+        
+        verify_id_exists = self.service.verify_deck_id_exists(uuid_value)
+        if not verify_id_exists:
+            return APIResponse.error(
+                message="Deck não encontrado.",
+                error="ID inexistente na base de dados.",
+                status_code=NotFound.code
+                )
 
-        cards = self.service.get_cards_by_deck_id(uuid_value)
+        cards, deck_name = self.service.get_cards_by_deck_id(uuid_value)
+        
         return APIResponse.success(
-            message="Cards encontrados com sucesso.",
-            data=cards,
+            message=f"Cards encontrados com sucesso.",
+            data={
+                    "deckName": deck_name,
+                    "cards": cards,
+                },
             status_code=200
         )       
 
@@ -42,4 +55,27 @@ def post_cards_by_deck(self, id, body):
             status_code=201,
             data=card_added.to_dict()
         )
-  
+    
+    def searching_specific_card(self, id):
+        is_uuid, uuid_value = self.validator.check_uuid(id)
+        if not is_uuid:
+            return APIResponse.error(
+                message="UUID Inválido.",
+                error="Formato do UUID não é válido.",
+                status_code=BadRequest.code
+            )
+        verify_id_exists = self.service.verify_card_id_exists(id)
+        if not verify_id_exists:
+            return APIResponse.error(
+                message="ID inexistente na base de dados.",
+                status_code=NotFound.code,
+                error="Nenhum dado encontrado."
+            )
+            
+        card = self.service.get_card_by_id(uuid_value)
+        
+        return APIResponse.success(
+            message="Detalhes do card encontrado com sucesso.",
+            status_code=200,
+            data=card,
+        )

src/app/services/cards_services.py

@@ -34,14 +34,31 @@ def post_cards_by_deck_id(self, uuid, body):
       self.session.refresh(new_card)
       return new_card
 
-      
    @handle_db_errors
    def get_cards_by_deck_id(self, uuid):
       deck = self.session.query(Deck).options(
          joinedload(Deck.cards)
       ).filter(Deck.id == uuid).first()
-
       if not deck:
+         return None, None
+      deck_infos = deck.to_dict()
+      return deck_infos.get("cards"), deck_infos.get("title")
+   
+   @handle_db_errors
+   def verify_card_id_exists(self, id):
+      result = self.session.query(Cards).filter(Cards.id == id).first()
+      if not result:
+         return False
+      return True
+      
+   @handle_db_errors
+   def verify_deck_id_exists(self, id):
+    result = self.session.query(Deck).filter(Deck.id == id).first()
+    return bool(result)   
+      
+   @handle_db_errors
+   def get_card_by_id(self, card_id):
+      finding_card = self.session.query(Cards).filter(Cards.id == card_id).first()
+      if not finding_card:
          return None
-
-      return deck.to_dict().get("cards")
+      return finding_card.to_dict()