Feat: Complete Link Module Implementation, Integration Tests & OpenAPI Documentation

[MathCunha16]

Summary

This Pull Request completes the end-to-end implementation of the Link domain module for the Go backend.

It includes:

• Complete LinkUseCase implementation and validation
• REST HTTP Handler improvements
• Route mapping fixes
• Comprehensive Unit and Integration Test coverage
• OpenAPI 3.0 documentation

---

✨ Key Changes

⚙️ 1. Use Case Layer (internal/usecase/)

link_usecase.go

• Verified and validated the existing business logic.
• Ensured alignment with the project's domain architecture.

Unit Tests (link_usecase_test.go)

Added 13 unit tests covering:

• Create
• GetByID
• GetAllByProjectID
• Update
• Delete

Coverage includes:

• Successful operations
• Project not found
• Link not found
• Error paths using testify mocks

---

🌐 2. Web Layer (internal/adapter/in/web/)

link_handler.go

Implemented several handler improvements:

• Added missing return statements in error branches to prevent duplicated HTTP responses.

• Fixed missing return after UUID parsing failures.

• Standardized context usage with:

  c.Request.Context()

• Added internal error logging with log.Printf.

router.go

Added the missing route:

DELETE /api/v1/projects/:project_id/links/:link_id

under mapLinkRoutes.

---

🧪 3. Integration Testing

Updated test_helper_test.go to wire:

• Link repository
• Link use case
• Link handler

into the shared SetupTestApp.

HTTP Integration Tests (link_handler_test.go)

Added 27 integration tests using Gin and an in-memory SQLite database (:memory:).

Coverage includes:

• Successful creation with Location header validation
• Retrieval by ID
• Paginated project listing
• Tenant/project isolation
• Partial updates (PATCH)
• Deletion with persistence validation
• Invalid UUIDs
• Invalid URL format
• Missing required fields
• Title minimum length validation
• Page size validation (size > 100)
• Unauthorized requests (401)
• Not found responses (404) for projects and links

---

📚 4. OpenAPI 3.0 Documentation

Updated docs/openapi.yaml with:

Schemas

• Link
• CreateLinkCommand
• UpdateLinkCommand
• LinkPage

Endpoints

Documented all Link endpoints:

• POST
• GET
• PATCH
• DELETE

under:

/projects/{project_id}/links
/projects/{project_id}/links/{link_id}

---

🧪 Test Execution

Run the full test suite:

cd backend-go
go test ./... -v

Run only the Link use case tests:

go test ./internal/usecase/... -v -run TestLink

Run only the Link handler integration tests:

go test ./internal/adapter/in/web/handler/... -v -run TestLinkHandler

Summary by CodeRabbit

• Novos Recursos

  • Adicionado o gerenciamento de links associados a projetos.
  • É possível criar, listar, consultar, atualizar e excluir links.
  • A listagem oferece paginação e validação de dados, URLs e identificadores.
  • Links são protegidos por autenticação e permanecem isolados entre projetos.

• Documentação

  • Adicionada documentação da API, incluindo exemplos, respostas de erro e códigos HTTP.

• Testes

  • Incluídos testes para operações de links, autenticação, validações, paginação e cenários de erro.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: d80faf59-e9b3-4b1e-8009-2acd25029534

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

backend-go/internal/adapter/in/web/handler/link_handler_test.go (2)

139-149: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Adicione um teste de isolamento entre dois projetos existentes.

Os subtestes usam o UUID zero como projeto inexistente, o que retorna 404 já na verificação ensureProjectExists. O predicado project_id do repositório não é exercitado nesse caminho. O escopo por projeto é a mudança central de FindByIDAndProjectID e DeleteByIDAndProjectID. Crie dois projetos válidos e acesse um link do projeto A pela rota do projeto B. O resultado esperado é 404 em GET, PATCH e DELETE.

♻️ Teste proposto

t.Run("Get failure - link belongs to another project", func(t *testing.T) {
	respOther := app.DoRequest(t, http.MethodPost, "/api/v1/projects", []byte(`{"name":"Other Project"}`), true)
	require.Equal(t, http.StatusCreated, respOther.StatusCode)
	var otherProject map[string]interface{}
	require.NoError(t, json.NewDecoder(respOther.Body).Decode(&otherProject))
	otherProjectID := otherProject["id"].(string)

	urlGet := fmt.Sprintf("/api/v1/projects/%s/links/%s", otherProjectID, linkID)
	resp := app.DoRequest(t, http.MethodGet, urlGet, nil, true)
	assert.Equal(t, http.StatusNotFound, resp.StatusCode)
})

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend-go/internal/adapter/in/web/handler/link_handler_test.go` around lines
139 - 149, Add isolation coverage to the link handler tests by creating a second
valid project and requesting the existing link from that project’s route. In the
relevant test setup, exercise GET, PATCH, and DELETE with the other project ID
while retaining the link’s original project ownership, and assert each returns
404; use the created project’s ID rather than an all-zero UUID so
FindByIDAndProjectID and DeleteByIDAndProjectID are tested.

---

110-124: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use require nas etapas de preparação dos testes.

O erro do decode é descartado e o valor é convertido com createdProject["id"].(string). Se a criação do projeto ou do link falhar, a conversão gera panic e a causa real não aparece. TestLinkHandler_Create já aplica require nas linhas 20-24. Aplique o mesmo padrão nas preparações de TestLinkHandler_Get, TestLinkHandler_GetAll, TestLinkHandler_Update e TestLinkHandler_Delete.

♻️ Refatoração proposta

 	projectBody := []byte(`{"name":"Parent Project"}`)
 	respProject := app.DoRequest(t, http.MethodPost, "/api/v1/projects", projectBody, true)
+	require.Equal(t, http.StatusCreated, respProject.StatusCode)
 	var createdProject map[string]interface{}
-	_ = json.NewDecoder(respProject.Body).Decode(&createdProject)
+	require.NoError(t, json.NewDecoder(respProject.Body).Decode(&createdProject))
 	projectID := createdProject["id"].(string)
 
 	linkBody := []byte(`{
 		"title": "Seeded Link",
 		"url": "https://example.com"
 	}`)
 	urlCreate := fmt.Sprintf("/api/v1/projects/%s/links", projectID)
 	respLink := app.DoRequest(t, http.MethodPost, urlCreate, linkBody, true)
+	require.Equal(t, http.StatusCreated, respLink.StatusCode)
 	var createdLink map[string]interface{}
-	_ = json.NewDecoder(respLink.Body).Decode(&createdLink)
+	require.NoError(t, json.NewDecoder(respLink.Body).Decode(&createdLink))
 	linkID := createdLink["id"].(string)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend-go/internal/adapter/in/web/handler/link_handler_test.go` around lines
110 - 124, Atualize a preparação dos testes TestLinkHandler_Get,
TestLinkHandler_GetAll, TestLinkHandler_Update e TestLinkHandler_Delete para
usar require em cada etapa de criação do projeto e do link: valide as respostas,
verifique os erros de json.Decoder.Decode e confirme a presença e o tipo dos
campos id antes de utilizá-los. Siga o padrão já aplicado em
TestLinkHandler_Create, evitando descartar erros ou causar panic nas conversões.

backend-go/internal/usecase/link_usecase_test.go (1)

314-367: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Adicione testes para falhas do repositório.

Os 13 testes cobrem sucesso, projeto inexistente e link inexistente. Nenhum teste cobre o retorno de erro do repositório. Nesses caminhos, o caso de uso encapsula o erro com fmt.Errorf("...: %w", err) e o handler responde 500. Um teste por operação confirma que o erro é propagado e que não é convertido em ErrLinkNotFound.

♻️ Exemplo de teste para erro na exclusão

func TestLinkUseCase_Delete_RepositoryError(t *testing.T) {
	mockLinkRepo := new(MockLinkRepository)
	mockProjectRepo := new(MockProjectRepository)
	uc := usecase.NewLinkUseCase(mockLinkRepo, mockProjectRepo)
	ctx := context.Background()

	projectID := uuid.New()
	linkID := uuid.New()
	repoErr := errors.New("db failure")

	mockProjectRepo.On("ExistsByID", ctx, projectID).Return(true, nil)
	mockLinkRepo.On("DeleteByIDAndProjectID", ctx, projectID, linkID).Return(false, repoErr)

	err := uc.Delete(ctx, projectID, linkID)

	assert.ErrorIs(t, err, repoErr)
	assert.NotErrorIs(t, err, usecase.ErrLinkNotFound)
	mockLinkRepo.AssertExpectations(t)
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend-go/internal/usecase/link_usecase_test.go` around lines 314 - 367,
Adicione testes para erros de repositório em cada operação do LinkUseCase
coberta pelo arquivo, incluindo Delete, configurando os mocks para retornar um
erro sentinel. Verifique que o erro original é propagado com assert.ErrorIs e
que não é convertido em ErrLinkNotFound ou outros erros de ausência; mantenha as
expectativas dos repositórios validadas.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend-go/docs/openapi.yaml`:
- Around line 415-432: Atualize o schema UpdateLinkCommand removendo nullable:
true de title, url e description, pois campos ausentes já representam “não
alterar” e valores null não produzem alteração na implementação. Preserve os
demais tipos, formatos, limites e exemplos existentes.

---

Nitpick comments:
In `@backend-go/internal/adapter/in/web/handler/link_handler_test.go`:
- Around line 139-149: Add isolation coverage to the link handler tests by
creating a second valid project and requesting the existing link from that
project’s route. In the relevant test setup, exercise GET, PATCH, and DELETE
with the other project ID while retaining the link’s original project ownership,
and assert each returns 404; use the created project’s ID rather than an
all-zero UUID so FindByIDAndProjectID and DeleteByIDAndProjectID are tested.
- Around line 110-124: Atualize a preparação dos testes TestLinkHandler_Get,
TestLinkHandler_GetAll, TestLinkHandler_Update e TestLinkHandler_Delete para
usar require em cada etapa de criação do projeto e do link: valide as respostas,
verifique os erros de json.Decoder.Decode e confirme a presença e o tipo dos
campos id antes de utilizá-los. Siga o padrão já aplicado em
TestLinkHandler_Create, evitando descartar erros ou causar panic nas conversões.

In `@backend-go/internal/usecase/link_usecase_test.go`:
- Around line 314-367: Adicione testes para erros de repositório em cada
operação do LinkUseCase coberta pelo arquivo, incluindo Delete, configurando os
mocks para retornar um erro sentinel. Verifique que o erro original é propagado
com assert.ErrorIs e que não é convertido em ErrLinkNotFound ou outros erros de
ausência; mantenha as expectativas dos repositórios validadas.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 8b101241-f3e7-4f71-83cd-d8a1de45347b

📥 Commits

Reviewing files that changed from the base of the PR and between 786bdfd and 88522dc.

📒 Files selected for processing (10)

• backend-go/cmd/api/main.go
• backend-go/docs/openapi.yaml
• backend-go/internal/adapter/in/web/handler/link_handler.go
• backend-go/internal/adapter/in/web/handler/link_handler_test.go
• backend-go/internal/adapter/in/web/handler/test_helper_test.go
• backend-go/internal/adapter/in/web/router.go
• backend-go/internal/adapter/out/persistence/link_repository.go
• backend-go/internal/domain/port/link_repository.go
• backend-go/internal/usecase/link_usecase.go
• backend-go/internal/usecase/link_usecase_test.go