Starseed/migrations/Version20260528120000.php

<?php

declare(strict_types=1);

namespace DoctrineMigrations;

use App\Shared\Infrastructure\Database\ColumnCommentsCatalog;
use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * ERP-67 — Retrofit `COMMENT ON COLUMN` / `COMMENT ON TABLE` sur toutes les
 * tables metier existantes.
 *
 * Postgres stocke la description dans `pg_description`. Les outils d'admin
 * (DBeaver, DataGrip, pgAdmin) l'affichent automatiquement, ce qui evite de
 * remonter au code Doctrine pour comprendre la semantique d'une colonne.
 *
 * Source unique : `ColumnCommentsCatalog::comments()`. Le meme catalogue est
 * rejoue par `app:apply-column-comments` apres `doctrine:schema:update --force`
 * en environnement de test (Doctrine ORM ne conservant pas les commentaires
 * absents du mapping PHP).
 *
 * Convention :
 * - Description en francais, ≤ 200 caracteres.
 * - Semantique du champ + contraintes / lien RG si pertinent.
 *
 * Migration placee au namespace racine `DoctrineMigrations` (regle ABSOLUE
 * Starseed n°11) car elle touche plusieurs modules. Les futures migrations
 * applicatives devront poser leur propre `COMMENT ON COLUMN` au moment de
 * creer leurs colonnes (cf. regle ABSOLUE n°12 + .claude/rules/backend.md).
 */
final class Version20260528120000 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'ERP-67 : retrofit COMMENT ON COLUMN/TABLE sur toutes les tables metier existantes.';
    }

    public function up(Schema $schema): void
    {
        // Ne commente que les tables deja presentes a ce stade de la chaine de
        // migrations. Les modules crees plus tard (ex: M1 Commercial, 06-01)
        // figurent desormais dans le catalogue partage mais leurs tables
        // n'existent pas encore ici : elles posent leurs propres COMMENT dans
        // leur migration dediee (regle ABSOLUE n°12). Garde-fou indispensable,
        // sinon l'ajout d'un module au catalogue casse ce retrofit avec un
        // "relation X does not exist".
        $existingTables = array_values(array_filter(
            array_keys(ColumnCommentsCatalog::comments()),
            static fn (string $table): bool => $schema->hasTable($table),
        ));

        foreach (ColumnCommentsCatalog::toSqlStatements($existingTables) as $sql) {
            $this->addSql($sql);
        }
    }

    public function down(Schema $schema): void
    {
        foreach (ColumnCommentsCatalog::comments() as $table => $entries) {
            // Symetrie avec up() : on n'efface que les commentaires des tables
            // presentes (les tables des modules ulterieurs sont gerees par leur
            // propre migration).
            if (!$schema->hasTable($table)) {
                continue;
            }

            $quotedTable = '"'.str_replace('"', '""', $table).'"';
            foreach ($entries as $column => $_) {
                if ('_table' === $column) {
                    $this->addSql(sprintf('COMMENT ON TABLE %s IS NULL', $quotedTable));

                    continue;
                }

                $this->addSql(sprintf(
                    'COMMENT ON COLUMN %s.%s IS NULL',
                    $quotedTable,
                    '"'.str_replace('"', '""', $column).'"',
                ));
            }
        }
    }
}