#2192 - Account quality score

Author: FaustoJohn

Core/AccountQuality/Controller.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\AccountQuality\ResponseBuilders\GetAccountQualityScoreResponseBuilder;
+use Minds\Core\AccountQuality\Validators\GetAccountQualityScoreRequestValidator;
+use Minds\Exceptions\UserErrorException;
+use Psr\Http\Message\ServerRequestInterface;
+use Zend\Diactoros\Response\JsonResponse;
+
+/**
+ * The controller for the Account Quality module
+ */
+class Controller
+{
+    public function __construct(
+        private ?ManagerInterface $manager = null
+    ) {
+        $this->manager = $this->manager ?? new Manager();
+    }
+
+    /**
+     * Http route: api/v3/account-quality/:targetUserGuid
+     * @param ServerRequestInterface $request
+     * @return JsonResponse
+     * @throws UserErrorException
+     */
+    public function getAccountQualityScore(ServerRequestInterface $request): JsonResponse
+    {
+        $parameters = $request->getAttributes()["parameters"];
+        $requestValidator = new GetAccountQualityScoreRequestValidator();
+
+        $responseBuilder = new GetAccountQualityScoreResponseBuilder();
+
+        if (!$requestValidator->validate($parameters)) {
+            return $responseBuilder->buildBadRequestResponse($requestValidator->getErrors());
+        }
+
+        $results = $this->manager->getAccountQualityScore($parameters['targetUserGuid']);
+
+        return $responseBuilder->buildSuccessfulResponse($results);
+    }
+}

Core/AccountQuality/Manager.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\AccountQuality\Models\UserQualityScore;
+
+/**
+ * Responsible for the business logic in order to retrieve the relevant details required to the controller
+ */
+class Manager implements ManagerInterface
+{
+    public function __construct(
+        private ?RepositoryInterface $repository = null
+    ) {
+        $this->repository = $this->repository ?? new Repository();
+    }
+
+    /**
+     * Retrieves the account quality score based on the userId provided
+     * @param string $userId
+     * @return UserQualityScore
+     */
+    public function getAccountQualityScore(string $userId): UserQualityScore
+    {
+        return $this->repository->getAccountQualityScore($userId);
+    }
+}

Core/AccountQuality/ManagerInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\AccountQuality\Models\UserQualityScore;
+
+interface ManagerInterface
+{
+    /**
+     * Retrieves the account quality score based on the userId provided
+     * @param string $userId
+     * @return UserQualityScore
+     */
+    public function getAccountQualityScore(string $userId): UserQualityScore;
+}

Core/AccountQuality/Models/UserQualityScore.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Minds\Core\AccountQuality\Models;
+
+use Minds\Core\Config\Config;
+use Minds\Core\Di\Di;
+use Minds\Traits\MagicAttributes;
+
+/**
+ * Entity representing the user quality score.
+ * @method float|null getScore()
+ * @method self setScore(float $score)
+ * @method string getCategory()
+ * @method self setCategory(string $category)
+ */
+class UserQualityScore
+{
+    use MagicAttributes;
+    
+    private ?float $score = null;
+    private string $category = "";
+
+    public function __construct(
+        private ?Config $config = null
+    ) {
+        $this->config ??= Di::_()->get("Config");
+    }
+
+    /**
+     * Checks if the score is below the risk threshold of being considered a spam account
+     * @return bool
+     */
+    public function isBelowSpamRiskThreshold(): bool
+    {
+        return is_numeric($this->score) && $this->score < $this->config->get("user_quality_score")['belowSpamRiskThreshold'];
+    }
+}

Core/AccountQuality/Module.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Interfaces\ModuleInterface;
+
+class Module implements ModuleInterface
+{
+    public array $submodules = [];
+
+    public function onInit()
+    {
+        (new Provider())->register();
+        (new Routes())->register();
+    }
+}

Core/AccountQuality/Provider.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\Di\Provider as DiProvider;
+
+class Provider extends DiProvider
+{
+    public function register(): void
+    {
+        $this->di->bind('AccountQuality\Manager', function ($di) {
+            return new Manager();
+        });
+        $this->di->bind('AccountQuality\Controller', function ($di) {
+            return new Controller();
+        });
+    }
+}

Core/AccountQuality/Repository.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\AccountQuality\Models\UserQualityScore;
+use Minds\Core\Data\Cassandra\Client as CassandraClient;
+use Minds\Core\Data\Cassandra\Prepared\Custom as CustomQuery;
+use Minds\Core\Di\Di;
+
+/**
+ * Responsible to fetch the data from the relevant data sources
+ */
+class Repository implements RepositoryInterface
+{
+    private const TABLE_NAME = "user_quality_scores";
+
+    public function __construct(
+        private ?CassandraClient $cassandraClient = null
+    ) {
+        $this->cassandraClient = $this->cassandraClient ?? Di::_()->get('Database\Cassandra\Cql');
+    }
+
+    /**
+     * Retrieves the account quality score based on the userId provided
+     * @param string $userId
+     * @return UserQualityScore
+     */
+    public function getAccountQualityScore(string $userId): UserQualityScore
+    {
+        $statement = "SELECT score, category
+            FROM
+                " . self::TABLE_NAME . "
+            WHERE
+                user_id = ?
+            LIMIT 1";
+
+        $query = $this->prepareQuery($statement, [$userId]);
+
+        $results = $this->cassandraClient->request($query);
+        $entry = $results->first();
+        return (new UserQualityScore())
+                ->setScore((float)$entry["score"])
+                ->setCategory($entry["category"]);
+    }
+
+    /**
+     * Returns a Cassandra prepared statement using the query and values provided
+     * @param string $statement
+     * @param array $values The values for the parameters in the query statement
+     * @return CustomQuery
+     */
+    private function prepareQuery(string $statement, array $values): CustomQuery
+    {
+        $query = new CustomQuery();
+        $query->query($statement, $values);
+
+        return $query;
+    }
+}

Core/AccountQuality/RepositoryInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\AccountQuality\Models\UserQualityScore;
+
+interface RepositoryInterface
+{
+    /**
+     * Retrieves the account quality score based on the userId provided
+     * @param string $userId
+     * @return UserQualityScore
+     */
+    public function getAccountQualityScore(string $userId): UserQualityScore;
+}

Core/AccountQuality/ResponseBuilders/GetAccountQualityScoreResponseBuilder.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Minds\Core\AccountQuality\ResponseBuilders;
+
+use Minds\Core\AccountQuality\Models\UserQualityScore;
+use Minds\Entities\ValidationErrorCollection;
+use Minds\Exceptions\UserErrorException;
+use Zend\Diactoros\Response\JsonResponse;
+
+/**
+ * Builds the relevant responses for GET api/v3/account-quality/:targetUserId
+ */
+class GetAccountQualityScoreResponseBuilder
+{
+    /**
+     * Builds the successful response object for the request
+     * @param UserQualityScore $response
+     * @return JsonResponse
+     */
+    public function buildSuccessfulResponse(UserQualityScore $response): JsonResponse
+    {
+        return new JsonResponse([
+            'status' => 'success',
+            'results' => [
+                'score' => abs($response->getScore() - 1)
+            ]
+        ]);
+    }
+
+    /**
+     * @param ValidationErrorCollection $errors
+     * @return JsonResponse
+     * @throws UserErrorException
+     */
+    public function buildBadRequestResponse(ValidationErrorCollection $errors): JsonResponse
+    {
+        throw new UserErrorException(
+            "Some validation errors have been found with the request.",
+            400,
+            $errors
+        );
+    }
+}

Core/AccountQuality/Routes.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Minds\Core\AccountQuality;
+
+use Minds\Core\Di\Ref;
+use Minds\Core\Router\Middleware\AdminMiddleware;
+use Minds\Core\Router\ModuleRoutes;
+use Minds\Core\Router\Route;
+
+class Routes extends ModuleRoutes
+{
+    public function register(): void
+    {
+        $this->route
+            ->withPrefix('api/v3/account-quality')
+            ->do(function (Route $route) {
+                // Temporarily accessible only to Admins
+                $route
+                    ->withMiddleware([
+                        AdminMiddleware::class
+                    ])
+                    ->do(function (Route $route) {
+                        $route->get(
+                            '',
+                            Ref::_('AccountQuality\Controller', 'getAccountQualityScores')
+                        );
+                        $route->get(
+                            ':targetUserGuid',
+                            Ref::_('AccountQuality\Controller', 'getAccountQualityScore')
+                        );
+                    });
+            });
+    }
+}

Core/AccountQuality/Validators/GetAccountQualityScoreRequestValidator.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Minds\Core\AccountQuality\Validators;
+
+use Minds\Entities\ValidationError;
+use Minds\Entities\ValidationErrorCollection;
+use Minds\Helpers\UserValidator;
+use Minds\Interfaces\ValidatorInterface;
+
+/**
+ * Responsible to run validation of the GET /api/v3/account-quality request
+ */
+class GetAccountQualityScoreRequestValidator implements ValidatorInterface
+{
+    private ?ValidationErrorCollection $errors;
+
+    private function reset(): void
+    {
+        $this->errors = new ValidationErrorCollection();
+    }
+
+    public function validate(array $dataToValidate): bool
+    {
+        $this->reset();
+
+        if (empty($dataToValidate['targetUserGuid'])) {
+            $this->errors->add(new ValidationError("targetUserId", "The user guid must be provided."));
+        }
+
+        if (!UserValidator::isValidUserId($dataToValidate['targetUserGuid'])) {
+            $this->errors->add(new ValidationError("targetUserId", "The user guid must be a valid user id."));
+        }
+
+        return $this->errors->count() == 0;
+    }
+
+    public function getErrors(): ?ValidationErrorCollection
+    {
+        return $this->errors;
+    }
+}

Core/Minds.php

@@ -62,6 +62,7 @@ class Minds extends base
         Votes\Module::class,
         Helpdesk\Zendesk\Module::class,
         SocialCompass\Module::class,
+        AccountQuality\Module::class,
         Recommendations\Module::class
     ];
 

Core/Provisioner/Provisioners/cassandra-provision.cql

@@ -1717,3 +1717,12 @@ CREATE TABLE minds.social_compass_answers (
     current_value int,
     PRIMARY KEY (user_guid, question_id)
 );
+
+CREATE TABLE minds.user_quality_scores
+(
+    user_id   text,
+    timestamp timestamp,
+    category  text,
+    score     float,
+    PRIMARY KEY (user_id, timestamp)
+) WITH CLUSTERING ORDER BY (timestamp DESC);

Helpers/UserValidator.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Minds\Helpers;
+
+/**
+ * User validation helper methods
+ */
+class UserValidator
+{
+    public static function isValidUserId(string $userId): bool
+    {
+        return is_numeric($userId);
+    }
+}