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
    {
        foreach (ColumnCommentsCatalog::toSqlStatements() as $sql) {
            $this->addSql($sql);
        }
    }

    public function down(Schema $schema): void
    {
        foreach (ColumnCommentsCatalog::comments() as $table => $entries) {
            $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).'"',
                ));
            }
        }
    }
}