Add UserMediaList entity, migrations, and GraphQL mutations

[vitorhugo-java]

This pull request introduces several new features and improvements related to user media libraries, custom status management, and error handling in the API. The most significant changes include new controllers for managing user media lists and custom statuses, enhancements to error handling with new exception types and standardized codes, and the introduction of new models and enums for media categories and statuses.

API and Controller Additions:

• Added UserMediaListController to handle querying, adding, updating, and removing media in a user's library, including privacy checks and support for various filters.
• Added UserStatusController to allow users to create, update, delete, and list their custom media tracking statuses.

Error Handling Improvements:

• Introduced new exception classes: AccessDeniedException, NotFoundException, and MediaAlreadyInLibraryException for more specific error reporting. [1] [2] [3]
• Updated GenericExceptionResolver to map these exceptions to standardized error codes (3403 for access denied, 3404 for not found, 2005 for media already in library) and included them in the documentation and error mapping logic. [1] [2] [3] [4]

Model and Enum Enhancements:

• Added CategoryType and StatusType enums for stronger typing of media categories and statuses. [1] [2]
• Updated MediaCategoryModel to use the new CategoryType enum instead of a string for the category name. [1] [2]
• Introduced MediaStatusModel entity for representing media production statuses, linked to MediaModel. [1] [2]
• Added UserCustomStatusModel entity for user-defined tracking statuses.

Minor Adjustments:

• Updated MovieAPIImpl and TvSeriesApiImpl to account for the new mediaStatus field in MediaModel. [1] [2]

These changes collectively enhance the flexibility and robustness of the user media library and status management features, while improving API error consistency and data modeling.

---

References:

• [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18]

[github-actions]

Qodana for JVM

5 new problems were found

Inspection name	Severity	Problems
Constant values	🔶 Warning	3
Unnecessary 'null' check before method call	🔶 Warning	1
Unused assignment	🔶 Warning	1

View the detailed Qodana report

To be able to view the detailed Qodana report, you can either:

• Register at Qodana Cloud and configure the action
• Use GitHub Code Scanning with Qodana
• Host Qodana report at GitHub Pages
• Inspect and use qodana.sarif.json (see the Qodana SARIF format for details)

To get *.log files or any other Qodana artifacts, run the action with upload-result option set to true,
so that the action will upload the files as the job artifacts:

      - name: 'Qodana Scan'
        uses: JetBrains/qodana-action@v2025.3.2
        with:
          upload-result: true

Contact Qodana team

Contact us at qodana-support@jetbrains.com

• Or via our issue tracker: https://jb.gg/qodana-issue
• Or share your feedback: https://jb.gg/qodana-discussions

[Copilot]

Pull request overview

This PR adds first-class support for user media libraries and user-defined tracking statuses across the persistence layer (Flyway + JPA), service/controller layer, and the GraphQL schema, along with new repository and GraphQL tests.

Changes:

• Introduces user_media_list + user_custom_statuses tables and expands them with planning date, custom-status linking, and privacy/notes fields.
• Adds new JPA models/repositories/services/controllers for UserMediaList and UserCustomStatus, and extends Media with a mediaStatus relation.
• Expands the GraphQL schema with new types, queries, and mutations and adds corresponding GraphQL/repository tests.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/test/java/com/espacogeek/geek/services/MediaServicePersistenceIntegrationTest.java	Updates category handling in persistence test to use CategoryType.
src/test/java/com/espacogeek/geek/repositories/UserMediaListRepositoryTest.java	Adds JPA repository tests for UserMediaListModel (UUID + unique constraint).
src/test/java/com/espacogeek/geek/query/userstatus/UserStatusQueryTest.java	Adds GraphQL query tests for custom statuses.
src/test/java/com/espacogeek/geek/query/usermedialist/UserMediaLibraryQueryTest.java	Adds GraphQL query tests for user media library + privacy + filters.
src/test/java/com/espacogeek/geek/mutation/userstatus/UserStatusMutationTest.java	Adds GraphQL mutation tests for create/update/delete custom statuses.
src/test/java/com/espacogeek/geek/mutation/usermedialist/UserMediaListMutationTest.java	Adds GraphQL mutation tests for add/remove/upsert library entries.
src/main/resources/graphql/query.graphqls	Adds findUserMediaLibrary and getUserCustomStatuses queries.
src/main/resources/graphql/mutation.graphqls	Adds library and custom-status mutations.
src/main/resources/graphql/entity/UserStatus.graphqls	Adds UserStatus GraphQL type.
src/main/resources/graphql/entity/UserMediaList.graphqls	Adds UserMediaList GraphQL type and UpdateUserMediaInput input.
src/main/resources/graphql/entity/user.graphqls	Exposes privateList on User.
src/main/resources/graphql/entity/StatusType.graphqls	Adds StatusType GraphQL enum for tracking status.
src/main/resources/graphql/entity/MediaStatus.graphqls	Adds MediaStatus GraphQL type.
src/main/resources/graphql/entity/Media.graphqls	Exposes mediaStatus on Media.
src/main/resources/db/migration/V20__create_user_media_list_table.sql	Creates user_media_list table (UUID PK + unique constraint).
src/main/resources/db/migration/V21__add_media_status.sql	Adds media_status table and medias.status_id FK; normalizes category strings.
src/main/resources/db/migration/V22__change_media_status_id_to_int.sql	Changes media_status.id + FK types from BIGINT to INT.
src/main/resources/db/migration/V23__add_private_list_to_users.sql	Adds users.private_list.
src/main/resources/db/migration/V24__update_status_types_and_add_date_planned.sql	Adds date_planned, migrates status strings, creates user_custom_statuses.
src/main/resources/db/migration/V25__add_custom_status_to_user_media_list.sql	Adds custom_status_id FK to user_media_list.
src/main/resources/db/migration/V26__add_rewatch_count_is_private_personal_notes.sql	Adds rewatch_count, is_private, personal_notes to user_media_list.
src/main/java/com/espacogeek/geek/types/UpdateUserMediaInput.java	Adds Java DTO backing the GraphQL upsert input.
src/main/java/com/espacogeek/geek/services/UserMediaListService.java	Adds service interface for library management + filtered queries.
src/main/java/com/espacogeek/geek/services/UserCustomStatusService.java	Adds service interface for custom status labels.
src/main/java/com/espacogeek/geek/services/MediaStatusService.java	Adds service interface for media statuses.
src/main/java/com/espacogeek/geek/services/impl/UserMediaListServiceImpl.java	Implements add/remove/upsert + filter delegation for user library entries.
src/main/java/com/espacogeek/geek/services/impl/UserCustomStatusServiceImpl.java	Implements CRUD for user custom status labels with validation.
src/main/java/com/espacogeek/geek/services/impl/MediaStatusServiceImpl.java	Implements MediaStatusService.
src/main/java/com/espacogeek/geek/repositories/UserMediaListRepository.java	Adds repository with a JPQL filter query + upsert helpers.
src/main/java/com/espacogeek/geek/repositories/UserLibraryRepository.java	Adds missing @Repository annotation.
src/main/java/com/espacogeek/geek/repositories/UserCustomStatusRepository.java	Adds repository for custom status CRUD scoped by userId.
src/main/java/com/espacogeek/geek/repositories/MediaStatusRepository.java	Adds repository for MediaStatusModel.
src/main/java/com/espacogeek/geek/models/UserModel.java	Adds privateList column mapping.
src/main/java/com/espacogeek/geek/models/UserMediaListModel.java	Adds UserMediaListModel entity (UUID PK + new columns).
src/main/java/com/espacogeek/geek/models/UserCustomStatusModel.java	Adds UserCustomStatusModel entity.
src/main/java/com/espacogeek/geek/models/StatusType.java	Adds Java enum for tracking statuses.
src/main/java/com/espacogeek/geek/models/MediaStatusModel.java	Adds MediaStatusModel entity.
src/main/java/com/espacogeek/geek/models/MediaModel.java	Adds mediaStatus relation to MediaModel.
src/main/java/com/espacogeek/geek/models/MediaCategoryModel.java	Converts category column to CategoryType enum.
src/main/java/com/espacogeek/geek/models/CategoryType.java	Adds Java enum for media categories.
src/main/java/com/espacogeek/geek/exception/resolver/GenericExceptionResolver.java	Maps new exceptions to standardized error codes.
src/main/java/com/espacogeek/geek/exception/NotFoundException.java	Adds domain exception for 3404.
src/main/java/com/espacogeek/geek/exception/MediaAlreadyInLibraryException.java	Adds domain exception for 2005.
src/main/java/com/espacogeek/geek/exception/AccessDeniedException.java	Adds domain exception for 3403.
src/main/java/com/espacogeek/geek/data/api/impl/TvSeriesApiImpl.java	Updates MediaModel construction to include mediaStatus placeholder.
src/main/java/com/espacogeek/geek/data/api/impl/MovieAPIImpl.java	Updates MediaModel construction to include mediaStatus placeholder.
src/main/java/com/espacogeek/geek/controllers/UserStatusController.java	Adds GraphQL controller for custom statuses.
src/main/java/com/espacogeek/geek/controllers/UserMediaListController.java	Adds GraphQL controller for library query + mutations + privacy checks.
README.md	Documents new standardized error codes/exceptions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Invalid categoryName is treated as an internal error: throwing GenericException here will be mapped to errorCode 5000. Since this is client input validation, it should throw InputValidationException (errorCode 2004) with a helpful message, consistent with GenericExceptionResolver's mapping.

[Copilot]

MediaCategoryModel was changed from a String typeCategory to CategoryType name, but the GraphQL schema still exposes MediaCategory.typeCategory. With the current model, typeCategory will resolve to null (no getTypeCategory()), breaking existing GraphQL clients. Either update the GraphQL schema field to match the new property, or add a compatibility getter/setter (getTypeCategory delegating to the enum) so the existing schema continues to work.

[Copilot]

rewatch_count and is_private are added as NOT NULL with defaults in V26, but the entity fields allow null and have no default initialization. Hibernate inserts often include null values explicitly, which can violate the DB constraint at runtime when an entry is persisted without these fields set. Initialize defaults in the entity (e.g., rewatchCount = 0, isPrivate = false) and/or enforce non-null via @Column(nullable = false) / @PrePersist to align with the migration.

Suggested change

	@Column(name = "rewatch_count", columnDefinition = "INT DEFAULT 0")
	private Integer rewatchCount;
	@Column(name = "is_private", columnDefinition = "TINYINT(1) DEFAULT 0")
	private Boolean isPrivate;
	@Column(name = "rewatch_count", nullable = false, columnDefinition = "INT DEFAULT 0")
	private Integer rewatchCount = 0;
	@Column(name = "is_private", nullable = false, columnDefinition = "TINYINT(1) DEFAULT 0")
	private Boolean isPrivate = false;

[Copilot]

@OneToMany(mappedBy = "mediaStatus") combined with @Transient means this association is not mapped/persisted at all, which is confusing and likely not what you want. Either remove @Transient (and, if needed, handle serialization recursion via Jackson annotations) or remove the relationship annotation entirely.

[Copilot]

addMedia() uses an exists-check followed by an insert. With the unique constraint on (user_id, media_id), concurrent requests can still race and trigger a DB unique-constraint violation, which will currently surface as a database error (5001) instead of the intended 2005. Consider relying on the unique constraint and catching DataIntegrityViolationException (or re-checking on failure) to consistently translate it to MediaAlreadyInLibraryException.

[Copilot]

upsertUserMedia() does a read-then-insert when no existing entry is found. Under concurrent requests for the same (userId, mediaId), this can race and hit the unique constraint, surfacing as a DB error (5001). Consider handling DataIntegrityViolationException on save() (e.g., retry by loading the existing row and applying updates) so the operation is robust under concurrency.