controllers: add comments/doc to donation-related code

app/controller/admin.php

@@ -35,6 +35,7 @@ class Admin extends Controller
             100 => "Récurrent non validé",
             101 => "Récurrent validé",
             102 => "Récurrent remis",
+            //! 103 => "Refusé"
         ));
 
         $f3->set('CT_STATUTS', array(
@@ -1428,6 +1429,7 @@ class Admin extends Controller
                 if ($identifier && $transaction && $effect && $amount && $statut == false) {
                     continue;
                 }
+                //! "Refusé" status seems not be present in csv, is this really used?
                 if ($statut == 'Refusé' and !$testing) {
                     $db->query("UPDATE dons SET status = 103 WHERE id='".$transaction."'");
                     continue;
@@ -1438,6 +1440,8 @@ class Admin extends Controller
                     $total ++;
                     $email = '';
                     $time_struct = strptime($effect, "%d/%m/%Y %H:%M:%S");
+                    //! XXX WHY? month + 1 can make sense, but hour (always 00) + 1 or year (2020) + 1900 does not
+                    //! what is the rationale, is this the next due date?
                     $new_effect = strftime("%Y-%m-%d %H:%M:%S", mktime(
                         $time_struct['tm_hour']+1,
                         $time_struct['tm_min'],
@@ -1479,6 +1483,7 @@ class Admin extends Controller
                                 $email = $user_field . "@example.org";
                                 $pseudo = $user_field;
                             }
+                            //! hash seems to identify one email at one time
                             $hash = hash('sha256', date("%Y-%m-%d %H:%i:%d").$email);
                             if (!$testing) {
                                 $log->write('Insert user: email "'.$email.'" pseudo "'.$pseudo.'" identifier "'.$identifier.'"');
@@ -1495,6 +1500,7 @@ class Admin extends Controller
                         $email = $email['email'];
                         // On stocke l'email pour comptabiliser les dons
                     }
+                    //! Counting email duplicates
                     if (array_key_exists($email, $emails)) {
                         $emails[$email] ++;
                     } else {
@@ -1503,6 +1509,7 @@ class Admin extends Controller
                     // On a besoin de l'utilisateur
                     $user = $f3->get('container')['user_finder']->findByEmail($email);
                     // Récupération de l'id du bon abonnement
+                    //! look for a validated donation, see if the recurrent donation is already scheduled
                     $stmt = $db->query("SELECT d.id AS id
                         FROM dons d
                             JOIN users u ON u.id = d.user_id
@@ -1512,10 +1519,13 @@ class Admin extends Controller
                     $result = $stmt->fetch(\PDO::FETCH_ASSOC);
                     if (!$result) {
                         if ($testing) {
+                            //! XXX WTF random transaction id!
                             $cumul = rand(50000, 70000);
                         } else {
                             // don non trouvé en statut 101. On le crée (la banque à raison)
                             // statut = cumul
+                            //! FIXME bad naming cumul for transactions
+                            //! It means that don.cumul is the id of parent transaction with 101 status
                             $f3->get('container')['command_handler']
                                 ->handle(new DonationCreateCommand(
                                     $user['id'],
@@ -1541,6 +1551,7 @@ class Admin extends Controller
                                 AND d.datec='".$new_effect."'
                                 AND d.cumul=".$cumul."
                             ");
+                    //! Does not sound like a good idea to match on a creation date...
                     if ($result) {
                         $combien = $result->fetch();
                         if ($combien[0]==0) {
@@ -1578,10 +1589,10 @@ class Admin extends Controller
             }
             fclose($handle);
         }
-        $datas['update'] = $update;
-        $datas['total'] = $total;
-        $datas['comptabilise'] = $comptabilise;
-        $datas['sans_cumul'] = $sans_cumul;
+        $datas['total'] = $total; //! all recurrent transactions (validées + remisées)
+        $datas['update'] = $update; //! recurrent transactions remisées just added
+        $datas['comptabilise'] = $comptabilise; //! recurrent transactions remisées already added
+        $datas['sans_cumul'] = $sans_cumul; //! empty
         return $datas;
     }
 

app/controller/bank.php

@@ -155,6 +155,7 @@ class Bank extends Controller
 
         $user = $f3->get('container')['user_finder']->findById($don['user_id']);
         $cb_log->write("Utilisation d'un utilisateur existant");
+        //! FIXME What if user not found? Must check it
         // Ajout du nouveau don au cumul actuel
         if ($status!=101) {
             $cb_log->write("Ajout de ".$don['somme']);

app/controller/campaign.php

@@ -162,7 +162,7 @@ class Campaign extends Controller
             "vads_action_mode" => "INTERACTIVE",
             "vads_ctx_mode" => CTX_MODE,
             // Autres codes possibles (page 16)
-            "vads_trans_id" => str_repeat("0", 6-strlen($id)).$id,
+            "vads_trans_id" => str_repeat("0", 6-strlen($id)).$id, // fill left zeros to have length 6
             "vads_version" => "V2",
             // Champs facultatifs
             "vads_language" => $f3->get('lang'),