Feat/define user generated content data

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Upcoming
 
+- **feat**: Added a comprehensive **Community & Engagement System**. This major feature introduces the foundational data models, fixtures and tests for user reactions, comments, a multi-entity reporting system, and a smart app review funnel. The entire system is remotely configurable via a new unified `CommunityConfig` model and extends `UserLimitsConfig` to support role-based limits for comments and reports.
+- **BREAKING** refactor!: Overhauled data models and configuration to align with the new identity pivot toward news aggregator. This major refactor introduces a more scalable remote configuration structure, standardizes enums and models for broader use (e.g., `FeedItem` settings), and simplifies ad, notification, and headline data structures for improved clarity and maintainability.
 - **feat**: Introduce data models to support a filter-based push notification system. This includes `SavedHeadlineFilter`, `SavedSourceFilter`, and related configuration models, providing the architectural foundation for clients to implement notification subscriptions.
 - **BREAKING** refactor!: Rework `UserPreferenceConfig` to support the new notification system with a more scalable, role-based map structure for all user limits.
 - **test**: Add comprehensive unit tests for all new and refactored models.

README.md

@@ -66,6 +66,27 @@ Provides data structures for persisting all user-specific configurations, from a
 
 </details>
 
+<details>
+<summary><strong>💬 Community & Engagement System</strong></summary>
+
+---
+
+### 💬 Reactions, Comments & Reporting
+
+Provides a complete suite of models for building a rich community interaction layer. This includes individualized reactions, a robust commenting system with a built-in moderation workflow, and a flexible reporting system for headlines, sources, and comments.
+
+> **Your Advantage:** Foster a vibrant and safe user community, maintain high content quality through effective moderation, and gather direct user feedback on your content.
+
+---
+
+### ⭐ Smart App Review Funnel
+
+Implements the data structures for a strategic, two-layer review funnel. This system intelligently prompts engaged users for public reviews while channeling critical feedback from dissatisfied users into private channels.
+
+> **Your Advantage:** Maximize positive app store ratings and improve your app's reputation by proactively managing user feedback and preventing negative public reviews.
+
+</details>
+
 <details>
 <summary><strong>🔔 Notification & Alerting System</strong></summary>
 

lib/src/enums/comment_report_reason.dart

@@ -0,0 +1,19 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template comment_report_reason}
+/// Defines the specific reasons a user can provide for reporting a comment.
+/// {@endtemplate}
+@JsonEnum()
+enum CommentReportReason {
+  /// The comment is unsolicited advertising or promotion.
+  @JsonValue('spamOrAdvertising')
+  spamOrAdvertising,
+
+  /// The comment contains abusive language, personal attacks, or bullying.
+  @JsonValue('harassmentOrBullying')
+  harassmentOrBullying,
+
+  /// The comment targets certain groups with hateful language.
+  @JsonValue('hateSpeech')
+  hateSpeech,
+}

lib/src/enums/comment_status.dart

@@ -0,0 +1,27 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template comment_status}
+/// Defines the lifecycle status of a user-submitted comment.
+/// {@endtemplate}
+@JsonEnum()
+enum CommentStatus {
+  /// The comment has been submitted and is awaiting moderation.
+  @JsonValue('pendingReview')
+  pendingReview,
+
+  /// The comment has been approved by a moderator and is publicly visible.
+  @JsonValue('approved')
+  approved,
+
+  /// The comment has been rejected by a moderator and is not visible.
+  @JsonValue('rejected')
+  rejected,
+
+  /// The comment has been automatically flagged by an AI moderation service.
+  @JsonValue('flaggedByAI')
+  flaggedByAI,
+
+  /// The comment has been hidden by the user who posted it.
+  @JsonValue('hiddenByUser')
+  hiddenByUser,
+}

lib/src/enums/engageable_type.dart

@@ -0,0 +1,12 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template engageable_type}
+/// Defines the types of entities that can be engaged with (reacted to or
+/// commented on).
+/// {@endtemplate}
+@JsonEnum()
+enum EngageableType {
+  /// The engagement is for a news headline.
+  @JsonValue('headline')
+  headline,
+}

lib/src/enums/engagement_mode.dart

@@ -0,0 +1,15 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template engagement_mode}
+/// Defines the engagement features available to users.
+/// {@endtemplate}
+@JsonEnum()
+enum EngagementMode {
+  /// Users can only react to headlines.
+  @JsonValue('reactionsOnly')
+  reactionsOnly,
+
+  /// Users can both react and comment on headlines.
+  @JsonValue('reactionsAndComments')
+  reactionsAndComments,
+}

lib/src/enums/enums.dart

@@ -6,16 +6,25 @@ export 'app_font_weight.dart';
 export 'app_text_scale_factor.dart';
 export 'app_user_role.dart';
 export 'banner_ad_shape.dart';
+export 'comment_report_reason.dart';
+export 'comment_status.dart';
 export 'content_status.dart';
 export 'content_type.dart';
 export 'dashboard_user_role.dart';
 export 'device_platform.dart';
+export 'engageable_type.dart';
+export 'engagement_mode.dart';
 export 'feed_decorator_category.dart';
 export 'feed_decorator_type.dart';
 export 'feed_item_click_behavior.dart';
 export 'feed_item_density.dart';
 export 'feed_item_image_style.dart';
+export 'headline_report_reason.dart';
 export 'push_notification_provider.dart';
 export 'push_notification_subscription_delivery_type.dart';
+export 'reaction_type.dart';
+export 'report_status.dart';
+export 'reportable_entity.dart';
 export 'sort_order.dart';
+export 'source_report_reason.dart';
 export 'source_type.dart';

lib/src/enums/headline_report_reason.dart

@@ -0,0 +1,32 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template headline_report_reason}
+/// Defines the specific reasons a user can provide for reporting a headline.
+/// {@endtemplate}
+@JsonEnum()
+enum HeadlineReportReason {
+  /// The content is factually incorrect or considered fake news.
+  @JsonValue('misinformationOrFakeNews')
+  misinformationOrFakeNews,
+
+  /// The headline is clickbait or does not reflect the article's content.
+  @JsonValue('clickbaitTitle')
+  clickbaitTitle,
+
+  /// The content contains hate speech, graphic violence, or other inappropriate
+  /// material.
+  @JsonValue('offensiveOrHateSpeech')
+  offensiveOrHateSpeech,
+
+  /// The link leads to advertising, phishing, or fraudulent content.
+  @JsonValue('spamOrScam')
+  spamOrScam,
+
+  /// The article URL does not work.
+  @JsonValue('brokenLink')
+  brokenLink,
+
+  /// The content requires a subscription that was not disclosed.
+  @JsonValue('paywalled')
+  paywalled,
+}

lib/src/enums/reaction_type.dart

@@ -0,0 +1,38 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template reaction_type}
+/// Defines the types of reactions a user can have to a headline.
+/// {@endtemplate}
+@JsonEnum()
+enum ReactionType {
+  /// Represents a "like" or "thumbs up" reaction.
+  /// General positive approval.
+  @JsonValue('like')
+  like,
+
+  /// Represents an "insightful" or "lightbulb" reaction.
+  /// Signals the article provided new information or a valuable perspective.
+  @JsonValue('insightful')
+  insightful,
+
+  /// Represents an "amusing" or "funny" reaction.
+  /// For lighthearted or humorous content.
+  @JsonValue('amusing')
+  amusing,
+
+  /// Represents a "sad" reaction.
+  /// For news that evokes empathy or sadness.
+  @JsonValue('sad')
+  sad,
+
+  /// Represents an "angry" or "outrageous" reaction.
+  /// For news that provokes a strong negative emotional response.
+  @JsonValue('angry')
+  angry,
+
+  /// Represents a "skeptical" or "questionable" reaction.
+  /// Signals that the user questions the validity, bias, or sourcing of the
+  /// article without formally reporting it.
+  @JsonValue('skeptical')
+  skeptical,
+}

lib/src/enums/report_status.dart

@@ -0,0 +1,19 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template report_status}
+/// Defines the moderation workflow status for a user-submitted report.
+/// {@endtemplate}
+@JsonEnum()
+enum ReportStatus {
+  /// The report has been submitted by a user and is awaiting review.
+  @JsonValue('submitted')
+  submitted,
+
+  /// A moderator is actively reviewing the report.
+  @JsonValue('inReview')
+  inReview,
+
+  /// The report has been reviewed and a decision has been made.
+  @JsonValue('resolved')
+  resolved,
+}

lib/src/enums/reportable_entity.dart

@@ -0,0 +1,22 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template reportable_entity}
+/// Defines the types of entities that can be reported by users.
+///
+/// This enum acts as a discriminator in the `Report` model to identify
+/// what kind of content the report refers to.
+/// {@endtemplate}
+@JsonEnum()
+enum ReportableEntity {
+  /// The report is for a news headline.
+  @JsonValue('headline')
+  headline,
+
+  /// The report is for a news source.
+  @JsonValue('source')
+  source,
+
+  /// The report is for a user-submitted comment.
+  @JsonValue('comment')
+  comment,
+}

lib/src/enums/source_report_reason.dart

@@ -0,0 +1,30 @@
+import 'package:json_annotation/json_annotation.dart';
+
+/// {@template source_report_reason}
+/// Defines the specific reasons a user can provide for reporting a news source.
+///
+/// These reasons are designed to be actionable and can provide data to
+/// influence other systems, like an automated content scraper's scoring.
+/// {@endtemplate}
+@JsonEnum()
+enum SourceReportReason {
+  /// The source consistently produces poor, biased, or unreliable content.
+  @JsonValue('lowQualityJournalism')
+  lowQualityJournalism,
+
+  /// The source's website is unusable due to excessive ads or popups.
+  @JsonValue('highAdDensity')
+  highAdDensity,
+
+  /// The source often requires a subscription to view content.
+  @JsonValue('frequentPaywalls')
+  frequentPaywalls,
+
+  /// The source is pretending to be another entity.
+  @JsonValue('impersonation')
+  impersonation,
+
+  /// The source has a pattern of publishing fake news or misinformation.
+  @JsonValue('spreadsMisinformation')
+  spreadsMisinformation,
+}