Feat: Complete Tag & ItemTag Module Implementation

[MathCunha16]

Summary

This Pull Request introduces the complete Tag and ItemTag management modules for the Go backend, porting and enhancing the tag functionality from the original backend.

It includes:

• Complete domain modeling
• SQLite persistence layer
• Business logic and use cases
• Centralized DTO architecture
• REST API handlers
• Comprehensive Unit and Integration Test coverage
• OpenAPI 3.0 documentation

---

✨ Key Changes

🏗️ 1. Centralized DTO Architecture (internal/dto/)

Centralized all Command and View DTOs into the internal/dto package:

• tag_dto.go
• snippet_dto.go
• link_dto.go
• problem_dto.go
• project_dto.go

TagSummary

Introduced a lightweight DTO containing:

• id
• name
• color

Used in:

• SnippetView
• LinkView
• ProblemView
• ProblemSummary

to avoid overfetching during item retrieval.

Tag

Added the full Tag DTO containing:

• id
• projectId
• name
• color
• createdAt
• updatedAt

Used for Tag CRUD operations.

---

⚙️ 2. Domain & Persistence (internal/domain/, internal/adapter/out/persistence/)

Added new domain models:

• Tag
• ItemTag

Introduced the ItemType enum:

• SNIPPET
• NOTE
• LINK
• PROBLEM
• CREDENTIAL

Created repository ports:

• TagRepository
• ItemTagRepository

Implemented SQLite persistence using jmoiron/sqlx with:

• Transaction safety
• Batch querying support

---

🧠 3. Use Cases (internal/usecase/)

TagUseCase

Implemented:

• Create
• GetByID
• GetAllByProjectID
• SearchByName
• Update
• Delete

Features include:

• Project isolation
• Duplicate tag name validation per project (400 Bad Request)

ItemTagUseCase

Implemented:

• AssociateTagToItem
• DisassociateTagFromItem

Validates ownership of both the target item and tag before creating associations.

Automatic Tag Loading

Updated:

• SnippetUseCase
• LinkUseCase
• ProblemUseCase

to automatically attach []TagSummary to:

• GetByID
• Update
• GetAllByProjectID

responses.

Cascading Cleanup

When a Snippet, Link, or Problem is deleted, all associated tag relationships are automatically removed using RemoveAllTagsFromItem.

---

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

TagHandler

Added endpoints for:

• Tag CRUD
• Name search

GET /projects/:project_id/tags/search?tag_name=

ItemTagHandler

Added endpoints for:

• Associating tags (PUT)
• Removing associations (DELETE)

Router

Updated router.go to ensure literal routes (such as /search) take precedence over wildcard routes (/:tag_id).

---

📚 5. OpenAPI 3.0 Documentation

Updated docs/openapi.yaml with:

Schemas

• Tag
• TagSummary
• CreateTagCommand
• UpdateTagCommand
• ItemType

Updated existing schemas:

• Snippet
• Link
• Problem
• ProblemSummary

to include:

tags: []TagSummary

Documented all Tag and ItemTag endpoints.

---

🌐 New API Endpoints

Method	Endpoint	Description
POST	/api/v1/projects/:project_id/tags	Create a new tag
GET	/api/v1/projects/:project_id/tags	List all project tags
GET	/api/v1/projects/:project_id/tags/search	Search tags by name (?tag_name=)
GET	/api/v1/projects/:project_id/tags/:tag_id	Get a tag by ID
PATCH	/api/v1/projects/:project_id/tags/:tag_id	Update a tag
DELETE	/api/v1/projects/:project_id/tags/:tag_id	Delete a tag
PUT	/api/v1/projects/:project_id/items/:item_type/:item_id/tags/:tag_id	Associate a tag with an item
DELETE	/api/v1/projects/:project_id/items/:item_type/:item_id/tags/:tag_id	Remove a tag association

---

🧪 Testing & Verification

Unit Tests

Updated:

• tag_usecase_test.go
• snippet_usecase_test.go
• link_usecase_test.go
• problem_usecase_test.go

Integration Tests

Added:

• tag_handler_test.go (28 test cases)
• item_tag_handler_test.go (16 test cases)

Test Results

Run the complete test suite:

go test -count=1 ./...

Result:

PASS
All packages compiled successfully.
100% of the test suite passed in 0.44s.

Summary by CodeRabbit

• Novos Recursos
  • Adicionado gerenciamento completo de tags por projeto: criação, consulta, listagem, busca, atualização e exclusão.
  • Tags podem ser associadas ou removidas de snippets, links e problemas.
  • Snippets, links e problemas agora exibem suas tags nas respostas da API.
• Documentação
  • Atualizada a especificação da API e a documentação de arquitetura e autenticação.
• Testes
  • Incluídos testes para gerenciamento, associação e validação de tags.

[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: 0c4771f6-6f3a-4ebc-b924-e16b0ec036c4

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: 13

🧹 Nitpick comments (7)

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

417-427: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Torne explícita a expectativa do comentário.

O comentário da linha 419 afirma que ExistsByNameAndProjectID não deve ser chamado. Nenhuma assertiva verifica isso. Adicione mockTagRepo.AssertNotCalled para que o teste falhe se a comparação sem diferenciação de maiúsculas for removida.

💚 Refactor proposto

 		assert.NoError(t, err)
 		assert.NotNil(t, result)
 		assert.Equal(t, "GOLANG", result.Name)
+		mockTagRepo.AssertNotCalled(t, "ExistsByNameAndProjectID", ctx, "GOLANG", projectID)

🤖 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/tag_usecase_test.go` around lines 417 - 427, Make
the test explicitly verify the case-insensitive rename behavior by asserting
mockTagRepo.AssertNotCalled for ExistsByNameAndProjectID after uc.Update
completes. Keep the existing success and result assertions unchanged.

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

76-78: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Renomeie DisassembleTagFromItem na porta.

O nome do método da porta usa "Disassemble", que significa desmontar. A operação desassocia a tag do item. O use case, o handler e a documentação usam "Disassociate". Renomeie o método da porta para DisassociateTagFromItem e atualize o adapter e o mock em backend-go/internal/usecase/item_tag_usecase_test.go (linha 25).

Remova também a linha vazia 77 antes do fechamento da função.

🤖 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/item_tag_usecase.go` around lines 76 - 78, Rename
the port method DisassembleTagFromItem to DisassociateTagFromItem and update all
corresponding adapter and mock implementations, including the mock in
item_tag_usecase_test.go, while preserving the existing use-case behavior.
Remove the extra blank line before the function’s closing brace.

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

43-46: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Considere 409 para nome de tag duplicado.

ErrTagAlreadyExists indica conflito com um recurso existente, não payload malformado. http.StatusConflict descreve melhor a situação e permite ao cliente distinguir falha de validação de colisão de nome. Se você adotar 409, atualize também as respostas documentadas nas linhas 2005 e 2217 de backend-go/docs/openapi.yaml.

Also applies to: 156-159

🤖 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/tag_handler.go` around lines 43 -
46, Atualize o tratamento de ErrTagAlreadyExists no handler de tags para
retornar http.StatusConflict (409) em vez de http.StatusBadRequest, preservando
a mensagem de erro existente. Ajuste também as respostas documentadas
correspondentes no OpenAPI para refletir o status 409.

---

101-104: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remova a verificação inalcançável.

TagUseCase.GetByID retorna ErrTagNotFound quando a tag não existe. Nunca retorna (nil, nil). O bloco das linhas 101-104 é código morto, já coberto pelo tratamento da linha 92.

♻️ Refactor proposto

-	if tag == nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": "Tag not found"})
-		return
-	}
-
 	c.JSON(http.StatusOK, tag)

🤖 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/tag_handler.go` around lines 101 -
104, Remova a verificação e o bloco de resposta para tag == nil no handler que
chama TagUseCase.GetByID, pois esse caso já é tratado pelo erro ErrTagNotFound.
Preserve o tratamento de erro existente e o fluxo de sucesso para tags válidas.

backend-go/internal/domain/port/tag_repository.go (1)

12-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Padronize a ordem dos parâmetros UUID na interface.

FindByIDAndProjectID e DeleteByIDAndProjectID recebem (projectID, id). ExistsByIDAndProjectID recebe (id, projectID). Os dois parâmetros são uuid.UUID, portanto uma troca de argumentos não gera erro de compilação e produz consulta silenciosamente errada. Use a mesma ordem em todos os métodos.

♻️ Refactor proposto

-	ExistsByIDAndProjectID(ctx context.Context, id uuid.UUID, projectID uuid.UUID) (bool, error)
+	ExistsByIDAndProjectID(ctx context.Context, projectID, id uuid.UUID) (bool, error)

Ajuste também o adapter em backend-go/internal/adapter/out/persistence/tag_repository.go, o mock em backend-go/internal/usecase/tag_usecase_test.go e as chamadas em backend-go/internal/usecase/item_tag_usecase.go.

🤖 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/domain/port/tag_repository.go` around lines 12 - 17,
Padronize ExistsByIDAndProjectID para receber UUIDs na ordem (projectID, id),
alinhando-o a FindByIDAndProjectID e DeleteByIDAndProjectID. Atualize a
implementação do adapter TagRepository, o mock em TagUsecaseTest e as chamadas
em ItemTagUsecase para preservar essa ordem em toda a cadeia.

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

39-57: 🗄️ Data Integrity & Integration | 🔵 Trivial

Considere um índice único para garantir a unicidade do nome.

A verificação com ExistsByNameAndProjectID e o Save posterior não são atômicos. Duas requisições concorrentes com o mesmo nome podem criar tags duplicadas no mesmo projeto. Adicione um índice único em (project_id, lower(name)) na migração de tags e mapeie a violação de restrição para ErrTagAlreadyExists.

🤖 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/tag_usecase.go` around lines 39 - 57, A unicidade
de tags ainda depende de uma verificação e gravação não atômicas. Adicione, na
migração da tabela tags, um índice único para (project_id, lower(name));
atualize o fluxo de criação em torno de ExistsByNameAndProjectID e Save para
capturar a violação dessa restrição e retorná-la como ErrTagAlreadyExists,
preservando o tratamento existente para outros erros.

backend-go/internal/adapter/out/persistence/tag_repository.go (1)

35-46: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Padronize o encapsulamento do erro.

Este método retorna err sem contexto. FindAllByProjectID, SearchByNameAndProjectID e DeleteByIDAndProjectID no mesmo arquivo usam fmt.Errorf com mensagem. Os adapters de snippet, link e problem também encapsulam o erro neste método.

♻️ Refactor proposto

-		return nil, err
+		return nil, fmt.Errorf("error trying to find tag: %w", err)

🤖 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/out/persistence/tag_repository.go` around lines
35 - 46, Atualize FindByIDAndProjectID para encapsular o erro retornado por
r.db.GetContext com fmt.Errorf e uma mensagem contextual, seguindo o padrão de
FindAllByProjectID, SearchByNameAndProjectID, DeleteByIDAndProjectID e dos
demais adapters. Preserve o tratamento de sql.ErrNoRows retornando nil, nil.

🤖 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 657-665: Restrinja o enum ItemType em OpenAPI aos tipos realmente
suportados por itemRepos: SNIPPET, LINK e PROBLEM. Atualize também as descrições
das rotas referidas para remover NOTE e CREDENTIAL ou indicar explicitamente que
ambos retornam 400 por ErrUnsupportedItemType, mantendo a documentação
consistente com validateItemOwnership.

In `@backend-go/internal/adapter/in/web/handler/item_tag_handler_test.go`:
- Around line 18-35: The HTTP response bodies returned by DoRequest remain open
in both test suites. In
backend-go/internal/adapter/in/web/handler/item_tag_handler_test.go:18-35, add
deferred resp.Body.Close() calls after every response, including responses in
subtests; apply the same cleanup to every response and flow in
backend-go/internal/adapter/in/web/handler/tag_handler_test.go:19-25.

In `@backend-go/internal/adapter/in/web/handler/tag_handler.go`:
- Line 54: Substitua as respostas diretas de model.Tag nos handlers de tag por
um DTO TagView definido em internal/dto/tag_dto.go. Adicione o mapeamento do
modelo para TagView e use-o em todos os pontos indicados do handler antes de
chamar c.JSON, preservando o contrato documentado no OpenAPI e evitando expor
novos campos do domínio.

In `@backend-go/internal/dto/tag_dto.go`:
- Line 20: Altere a validação do campo Name em UpdateTagCommand para usar min=2,
alinhando-a com CreateTagCommand e rejeitando nomes de um caractere. Atualize
também a propriedade correspondente de name em backend-go/docs/openapi.yaml para
minLength: 2.
- Around line 11-15: Atualize CreateTagCommand para tornar Color opcional,
usando um ponteiro com validação hexcolor que permita valor ausente. Ajuste
TagUsecase.Create para propagar nil como NULL e preservar o valor quando
informado, em vez de sempre criar um ponteiro para string vazia.

In `@backend-go/internal/usecase/item_tag_usecase.go`:
- Around line 122-135: Atualize validateItemsOwnership para validar cada ID
solicitado por pertencimento em existingIDs, usando uma estrutura de consulta
adequada, em vez de comparar len(existingIDs) com len(itemIDs). Preserve
ErrItemNotFound quando qualquer ID não existir e aceite IDs repetidos quando o
item correspondente existir.

In `@backend-go/internal/usecase/snippet_usecase.go`:
- Around line 159-162: Atualize os fluxos de exclusão dos métodos de use case
que removem snippets em backend-go/internal/usecase/snippet_usecase.go:159-162,
links em backend-go/internal/usecase/link_usecase.go:155-158 e problemas em
backend-go/internal/usecase/problem_usecase.go:201-204 para executar a exclusão
do item e a chamada correspondente a RemoveAllTagsFromItem na mesma transação,
confirmando a transação apenas quando ambas forem concluídas e revertendo-a em
qualquer falha.

In `@backend-go/internal/usecase/tag_usecase.go`:
- Around line 38-45: Validate sanitizedName after strings.TrimSpace in both the
create and update use cases, returning a shared ErrInvalidTagName when it is
empty before checking or persisting the tag. Declare ErrInvalidTagName with the
existing errors and map it to HTTP 400 in TagHandler.Create and
TagHandler.Update.

In `@docs/architecture/tags.md`:
- Line 57: Specify the fenced code block language as text for the route and flow
examples in the tags documentation, including the blocks at the referenced
locations, to satisfy markdownlint MD040.
- Around line 57-64: Update the supported item-type documentation near the tag
endpoints to list only SNIPPET, LINK, and PROBLEM, matching the types registered
by ItemTagUseCase. Remove NOTE and CREDENTIAL from the documented domain
constants, and add them only after their repositories are registered in
NewItemTagUseCase.

In `@docs/security/local-development-tokens.md`:
- Around line 7-10: Revise the `/api/v1/*` authentication documentation so
`dev-token` is not presented as process authentication: either describe it
explicitly as a convenience value without isolation guarantees, or document a
per-process randomly generated token and how the authorized client receives it.
- Around line 17-24: Adicione o identificador de linguagem text ou markdown ao
fence do bloco cercado na documentação, atualizando a abertura de ``` para
```text ou ```markdown e preservando o conteúdo da tabela.
- Around line 18-23: Corrija a resolução do token em main.go para que o fallback
dev-token ocorra somente quando APP_ENV=dev; em produção, exija
DEVAULTY_INTERNAL_TOKEN e retorne 401 Unauthorized quando ausente ou inválido.
Atualize a tabela de documentação para remover as referências não implementadas
a UUID gerado em memória e argumentos de linha de comando, mantendo apenas
comportamentos realmente suportados.

---

Nitpick comments:
In `@backend-go/internal/adapter/in/web/handler/tag_handler.go`:
- Around line 43-46: Atualize o tratamento de ErrTagAlreadyExists no handler de
tags para retornar http.StatusConflict (409) em vez de http.StatusBadRequest,
preservando a mensagem de erro existente. Ajuste também as respostas
documentadas correspondentes no OpenAPI para refletir o status 409.
- Around line 101-104: Remova a verificação e o bloco de resposta para tag ==
nil no handler que chama TagUseCase.GetByID, pois esse caso já é tratado pelo
erro ErrTagNotFound. Preserve o tratamento de erro existente e o fluxo de
sucesso para tags válidas.

In `@backend-go/internal/adapter/out/persistence/tag_repository.go`:
- Around line 35-46: Atualize FindByIDAndProjectID para encapsular o erro
retornado por r.db.GetContext com fmt.Errorf e uma mensagem contextual, seguindo
o padrão de FindAllByProjectID, SearchByNameAndProjectID, DeleteByIDAndProjectID
e dos demais adapters. Preserve o tratamento de sql.ErrNoRows retornando nil,
nil.

In `@backend-go/internal/domain/port/tag_repository.go`:
- Around line 12-17: Padronize ExistsByIDAndProjectID para receber UUIDs na
ordem (projectID, id), alinhando-o a FindByIDAndProjectID e
DeleteByIDAndProjectID. Atualize a implementação do adapter TagRepository, o
mock em TagUsecaseTest e as chamadas em ItemTagUsecase para preservar essa ordem
em toda a cadeia.

In `@backend-go/internal/usecase/item_tag_usecase.go`:
- Around line 76-78: Rename the port method DisassembleTagFromItem to
DisassociateTagFromItem and update all corresponding adapter and mock
implementations, including the mock in item_tag_usecase_test.go, while
preserving the existing use-case behavior. Remove the extra blank line before
the function’s closing brace.

In `@backend-go/internal/usecase/tag_usecase_test.go`:
- Around line 417-427: Make the test explicitly verify the case-insensitive
rename behavior by asserting mockTagRepo.AssertNotCalled for
ExistsByNameAndProjectID after uc.Update completes. Keep the existing success
and result assertions unchanged.

In `@backend-go/internal/usecase/tag_usecase.go`:
- Around line 39-57: A unicidade de tags ainda depende de uma verificação e
gravação não atômicas. Adicione, na migração da tabela tags, um índice único
para (project_id, lower(name)); atualize o fluxo de criação em torno de
ExistsByNameAndProjectID e Save para capturar a violação dessa restrição e
retorná-la como ErrTagAlreadyExists, preservando o tratamento existente para
outros erros.

🪄 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: 9ea7bf4b-7197-4380-94f6-77dc4061bb3e

📥 Commits

Reviewing files that changed from the base of the PR and between 4f79bae and 5a4f3a4.

📒 Files selected for processing (33)

• backend-go/cmd/api/main.go
• backend-go/docs/openapi.yaml
• backend-go/internal/adapter/in/web/handler/item_tag_handler.go
• backend-go/internal/adapter/in/web/handler/item_tag_handler_test.go
• backend-go/internal/adapter/in/web/handler/link_handler.go
• backend-go/internal/adapter/in/web/handler/problem_handler.go
• backend-go/internal/adapter/in/web/handler/project_handler.go
• backend-go/internal/adapter/in/web/handler/snippet_handler.go
• backend-go/internal/adapter/in/web/handler/tag_handler.go
• backend-go/internal/adapter/in/web/handler/tag_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/tag_repository.go
• backend-go/internal/domain/port/tag_repository.go
• backend-go/internal/dto/link_dto.go
• backend-go/internal/dto/problem_dto.go
• backend-go/internal/dto/project_dto.go
• backend-go/internal/dto/snippet_dto.go
• backend-go/internal/dto/tag_dto.go
• backend-go/internal/usecase/item_tag_usecase.go
• backend-go/internal/usecase/item_tag_usecase_test.go
• backend-go/internal/usecase/link_usecase.go
• backend-go/internal/usecase/link_usecase_test.go
• backend-go/internal/usecase/problem_usecase.go
• backend-go/internal/usecase/problem_usecase_test.go
• backend-go/internal/usecase/project_usecase.go
• backend-go/internal/usecase/project_usecase_test.go
• backend-go/internal/usecase/snippet_usecase.go
• backend-go/internal/usecase/snippet_usecase_test.go
• backend-go/internal/usecase/tag_usecase.go
• backend-go/internal/usecase/tag_usecase_test.go
• docs/architecture/tags.md
• docs/security/local-development-tokens.md