From 39bc8e5d8b2ee9bb12b710cb20481f46f3fbf640 Mon Sep 17 00:00:00 2001
From: andynnnfw <and345melo@gmail.com>
Date: Thu, 8 Oct 2026 21:05:20 -0300
Subject: [PATCH 1/3] feat(db): prazo de validade dos pontos por loja
 (migration 011)

- database/migrations/011_validade_pontos.sql: coluna points_expiry_months (padrao 12 meses) e tipo expire no points_log

- database/schema.sql: mesma mudanca no estado final e registro da 011 em schema_migrations

- docs/db/schema-explanation.md: documenta o prazo, o calculo do vencimento e o tipo expire

- src/Models/MerchantModel.php: findById traz o prazo e updatePointsExpiry grava

- src/Controllers/MerchantController.php: lista de prazos aceitos e acao de salvar a validade

- views/merchant/points-rule.php: card Validade dos pontos com o select de prazo

- views/partials/flash.php: mensagens validade_invalida e validade_salva, e o campo que o erro aponta

- tests/Feature/PointsExpiryConfigTest.php: testes do padrao de 12 meses, troca, desligar, valor invalido e isolamento entre lojas
---
 database/migrations/011_validade_pontos.sql | 16 ++++
 database/schema.sql                         | 12 ++-
 docs/db/schema-explanation.md               |  6 +-
 src/Controllers/MerchantController.php      | 25 +++++-
 src/Models/MerchantModel.php                |  8 +-
 tests/Feature/PointsExpiryConfigTest.php    | 93 +++++++++++++++++++++
 views/merchant/points-rule.php              | 31 +++++++
 views/partials/flash.php                    |  3 +
 8 files changed, 187 insertions(+), 7 deletions(-)
 create mode 100644 database/migrations/011_validade_pontos.sql
 create mode 100644 tests/Feature/PointsExpiryConfigTest.php

diff --git a/database/migrations/011_validade_pontos.sql b/database/migrations/011_validade_pontos.sql
new file mode 100644
index 0000000..feef960
--- /dev/null
+++ b/database/migrations/011_validade_pontos.sql
@@ -0,0 +1,16 @@
+-- fidelityx - migration 011 (validade dos pontos, task 31)
+-- para bancos criados antes desta versao do schema.sql. rodar uma unica vez:
+--   php bin/migrate.php
+-- (ou, a mao: mysql -u root -p fidelityx < database/migrations/011_validade_pontos.sql)
+
+USE fidelityx;
+
+-- prazo de validade por loja: o saldo do cliente vence depois de points_expiry_months meses sem
+-- nenhuma movimentacao naquela loja (loyalty_cards.last_use_at). NULL = os pontos nao vencem.
+-- o padrao e 12 meses, e as lojas que ja existem tambem comecam com ele.
+ALTER TABLE merchants
+  ADD COLUMN points_expiry_months TINYINT UNSIGNED NULL DEFAULT 12 AFTER points_rule_cents;
+
+-- o vencimento vira uma linha propria no historico ('expire'), como o resgate e o estorno
+ALTER TABLE points_log
+  MODIFY type ENUM('earn', 'redeem', 'reversal', 'expire') NOT NULL;
diff --git a/database/schema.sql b/database/schema.sql
index 20309b9..c0cd3f4 100644
--- a/database/schema.sql
+++ b/database/schema.sql
@@ -27,6 +27,9 @@ CREATE TABLE IF NOT EXISTS merchants (
   -- regra de pontos pelo valor da compra: a cada points_rule_cents centavos, 1 ponto (arredonda pra baixo).
   -- NULL = sem regra (o lojista digita os pontos direto)
   points_rule_cents INT UNSIGNED NULL,
+  -- validade dos pontos: o saldo vence depois deste tanto de meses sem movimentacao do cliente na loja
+  -- (loyalty_cards.last_use_at). NULL = os pontos nao vencem
+  points_expiry_months TINYINT UNSIGNED NULL DEFAULT 12,
   status ENUM('active', 'inactive') NOT NULL DEFAULT 'active',
 
   -- para futuras implementações (NULL)
@@ -82,8 +85,10 @@ CREATE TABLE IF NOT EXISTS loyalty_cards (
   current_points INT NOT NULL DEFAULT 0,
   total_accumulated INT NOT NULL DEFAULT 0,
 
-  -- para futuras implementações (NULL)
+  -- ultima movimentacao (ganho, resgate ou estorno). e daqui que conta a validade dos pontos:
+  -- vencimento = last_use_at + merchants.points_expiry_months (calculado na hora, nao fica gravado)
   last_use_at TIMESTAMP NULL,
+  -- sem uso: a data de vencimento e calculada (acima), pra nao ficar errada quando a loja muda o prazo
   expiration_date TIMESTAMP NULL,
 
   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -133,7 +138,7 @@ CREATE TABLE IF NOT EXISTS points_log (
   id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
 
   card_id BIGINT UNSIGNED NOT NULL,
-  type ENUM('earn', 'redeem', 'reversal') NOT NULL, -- reversal = estorno de um earn ou de um redeem
+  type ENUM('earn', 'redeem', 'reversal', 'expire') NOT NULL, -- reversal = estorno de um earn ou de um redeem, expire = saldo vencido
   quantity INT NOT NULL,
   description VARCHAR(255) NOT NULL,
   reward_id BIGINT UNSIGNED NULL, -- preenchido quando type = 'redeem'
@@ -267,4 +272,5 @@ INSERT IGNORE INTO schema_migrations (version) VALUES
   ('007_customers_so_telefone'),
   ('008_password_resets'),
   ('009_email_verifications'),
-  ('010_admins');
+  ('010_admins'),
+  ('011_validade_pontos');
diff --git a/docs/db/schema-explanation.md b/docs/db/schema-explanation.md
index 3b4a7d6..bf8d096 100644
--- a/docs/db/schema-explanation.md
+++ b/docs/db/schema-explanation.md
@@ -24,6 +24,7 @@ merchants 1───N loyalty_cards N───1 customers
 | Coluna | Observação |
 |---|---|
 | `points_rule_cents` | Regra de pontos pelo valor da compra: a cada tantos centavos, 1 ponto (sempre arredonda para baixo, `Money::pointsFor`). `NULL` = sem regra, o lojista digita os pontos. |
+| `points_expiry_months` | Validade dos pontos (task 31): o saldo do cliente vence depois deste tanto de meses sem movimentação na loja, contados de `loyalty_cards.last_use_at`. Padrão 12; `NULL` = os pontos não vencem. O lojista escolhe na tela Regra de pontos, entre os prazos de `MerchantController::EXPIRY_MONTHS_OPTIONS`. |
 | `public_code` | `UNIQUE`, 8 caracteres. Código público da loja: vai no QR do cartaz e identifica a loja na consulta de saldo. Gerado no cadastro (`App\Support\PublicCode`). |
 | `email`, `cpf`, `cnpj` | `UNIQUE`. Só um dos dois documentos é preenchido, apenas com números. |
 | `password_hash` | BCRYPT (`password_hash`). |
@@ -48,7 +49,8 @@ O cliente é **só o telefone** (task 11, ADR 002). As colunas `cpf`, `email`, `
 | `anonymized_at` | Exclusão a pedido do cliente: o cartão perde nome, telefone, consentimento e saldo e fica só para os relatórios. |
 | `current_points` | Saldo disponível. Aumenta ao ganhar pontos e diminui ao resgatar. |
 | `total_accumulated` | Tudo que o cliente já ganhou nesta loja. Só aumenta. |
-| `last_use_at` | Última movimentação. |
+| `last_use_at` | Última movimentação (ganho, resgate ou estorno). É daqui que conta a validade dos pontos: vencimento = `last_use_at` + `merchants.points_expiry_months`. |
+| `expiration_date` | Sem uso. A data de vencimento é calculada na hora (linha acima) em vez de gravada, para não ficar errada quando a loja muda o prazo. |
 
 ### `rewards` — catálogo de prêmios (novo no MVP)
 | Coluna | Observação |
@@ -60,7 +62,7 @@ O cliente é **só o telefone** (task 11, ADR 002). As colunas `cpf`, `email`, `
 ### `points_log` — histórico
 | Coluna | Observação |
 |---|---|
-| `type` | `earn` (ganho), `redeem` (resgate) ou `reversal` (estorno de um ganho ou de um resgate, task 44). `quantity` é sempre positivo: o sinal vem do tipo (o estorno de resgate devolve pontos). |
+| `type` | `earn` (ganho), `redeem` (resgate), `reversal` (estorno de um ganho ou de um resgate, task 44) ou `expire` (saldo vencido por falta de movimentação, task 31). `quantity` é sempre positivo: o sinal vem do tipo (o estorno de resgate devolve pontos). |
 | `reward_id` | Preenchido em resgates. Vira `NULL` se o prêmio for apagado. |
 | `reverses_id` | Preenchido em estornos (`reversal`): o ganho ou resgate estornado. `UNIQUE`, então cada movimentação é estornada no máximo uma vez. |
 | `ip_address` | IP de quem fez a operação (o do cliente, mesmo atrás de proxy confiável: `TRUSTED_PROXIES`). |
diff --git a/src/Controllers/MerchantController.php b/src/Controllers/MerchantController.php
index 8ceb1a7..d83d6a6 100644
--- a/src/Controllers/MerchantController.php
+++ b/src/Controllers/MerchantController.php
@@ -54,6 +54,8 @@ class MerchantController {
     private const UNDO_BANNER_SECONDS = 120;
     private const RECENT_CUSTOMERS = 5;
     private const MAX_POINTS_RULE_CENTS = 100000000;
+    // prazos de validade dos pontos que a loja pode escolher, em meses sem movimentacao (task 31)
+    public const EXPIRY_MONTHS_OPTIONS = [3, 6, 12, 18, 24, 36];
     private const MAX_LOGIN_FAILURES = 5;         // mesmo e-mail + mesmo ip
     private const MAX_LOGIN_FAILURES_PER_IP = 20; // mesmo ip, somando todas as contas
     private const LOGIN_WINDOW_SECONDS = 900;
@@ -244,12 +246,33 @@ public function renderPointsRule() {
             return;
         }
 
-        View::render('merchant/points-rule', ['ruleCents' => $this->pointsRule()]);
+        View::render('merchant/points-rule', [
+            'ruleCents'     => $this->pointsRule(),
+            'expiryMonths'  => $this->pointsExpiryMonths(),
+            'expiryOptions' => self::EXPIRY_MONTHS_OPTIONS,
+        ]);
+    }
+
+    // validade dos pontos da loja logada, em meses sem movimentacao (null = nao vencem). so depois do authGuard.
+    private function pointsExpiryMonths(): ?int {
+        $months = $this->merchant['points_expiry_months'] ?? null;
+        return $months === null ? null : (int)$months;
     }
 
     private function handlePointsRule(int $merchantId) {
         Csrf::verify();
 
+        // validade dos pontos (task 31): um dos prazos da lista, ou "never" pra desligar o vencimento
+        if (($_POST['action'] ?? '') === 'expiry') {
+            $choice = (string)($_POST['expiry_months'] ?? '');
+            if ($choice !== 'never' && !in_array($choice, array_map('strval', self::EXPIRY_MONTHS_OPTIONS), true)) {
+                redirect('merchant/points-rule', ['error' => 'validade_invalida']);
+            }
+
+            $this->merchantModel->updatePointsExpiry($merchantId, $choice === 'never' ? null : (int)$choice);
+            redirect('merchant/points-rule', ['success' => 'validade_salva']);
+        }
+
         if (($_POST['action'] ?? '') === 'clear') {
             $this->merchantModel->updatePointsRule($merchantId, null);
             redirect('merchant/points-rule', ['success' => 'regra_removida']);
diff --git a/src/Models/MerchantModel.php b/src/Models/MerchantModel.php
index 04dfd15..f41d682 100644
--- a/src/Models/MerchantModel.php
+++ b/src/Models/MerchantModel.php
@@ -42,7 +42,7 @@ public function findByEmail($email){
     // dados que o authGuard confere a cada requisicao (o hash da senha serve pra derrubar
     // as sessoes antigas quando a senha e trocada, ver SessionGuard::passwordSignature)
     public function findById($merchantId) {
-        $stmt = $this->db->prepare('SELECT id, owner_name, store_name, email, email_verified_at, status, points_rule_cents, password_hash FROM merchants WHERE id = :id');
+        $stmt = $this->db->prepare('SELECT id, owner_name, store_name, email, email_verified_at, status, points_rule_cents, points_expiry_months, password_hash FROM merchants WHERE id = :id');
         $stmt->execute([':id' => $merchantId]);
 
         return $stmt->fetch(\PDO::FETCH_ASSOC);
@@ -54,6 +54,12 @@ public function updatePointsRule($merchantId, ?int $ruleCents): void {
         $stmt->execute([':rule' => $ruleCents, ':id' => $merchantId]);
     }
 
+    // validade dos pontos em meses sem movimentacao; null = os pontos da loja nao vencem
+    public function updatePointsExpiry($merchantId, ?int $months): void {
+        $stmt = $this->db->prepare('UPDATE merchants SET points_expiry_months = :months WHERE id = :id');
+        $stmt->execute([':months' => $months, ':id' => $merchantId]);
+    }
+
     // dados exibidos na tela de perfil; false se a conta nao existir
     public function findProfile($merchantId) {
         $stmt = $this->db->prepare(
diff --git a/tests/Feature/PointsExpiryConfigTest.php b/tests/Feature/PointsExpiryConfigTest.php
new file mode 100644
index 0000000..61d4654
--- /dev/null
+++ b/tests/Feature/PointsExpiryConfigTest.php
@@ -0,0 +1,93 @@
+<?php
+
+namespace Tests\Feature;
+
+use Tests\Support\HttpTestCase;
+
+// task 31: prazo de validade dos pontos, configurado por loja na tela Regra de pontos
+final class PointsExpiryConfigTest extends HttpTestCase {
+    private const SCREEN = 'merchant/points-rule';
+
+    private function months(int $merchant) {
+        return $this->scalar('SELECT points_expiry_months FROM merchants WHERE id = ?', [$merchant]);
+    }
+
+    private function save(string $choice): ?string {
+        return $this->post(self::SCREEN, ['action' => 'expiry', 'expiry_months' => $choice], true, self::SCREEN)[1];
+    }
+
+    public function testLojaNovaComecaComDozeMeses(): void {
+        $merchant = $this->createMerchant('loja@teste.test');
+        $this->loginAs('loja@teste.test');
+
+        $this->assertSame(12, (int)$this->months($merchant));
+        $this->get(self::SCREEN);
+        $this->assertStringContainsString('Validade atual: <strong>12 meses</strong>', $this->lastBody);
+        $this->assertStringContainsString('<option value="12" selected>', $this->lastBody);
+    }
+
+    public function testLojaTrocaOPrazoEDesligaOVencimento(): void {
+        $merchant = $this->createMerchant('loja@teste.test');
+        $this->loginAs('loja@teste.test');
+
+        $this->assertSame(self::SCREEN . '&success=validade_salva', $this->save('6'));
+        $this->assertSame(6, (int)$this->months($merchant));
+
+        $this->assertSame(self::SCREEN . '&success=validade_salva', $this->save('never'));
+        $this->assertNull($this->months($merchant));
+
+        $this->get(self::SCREEN);
+        $this->assertStringContainsString('os pontos não vencem', $this->lastBody);
+        $this->assertStringContainsString('<option value="never" selected>', $this->lastBody);
+    }
+
+    public function testPrazoForaDaListaERecusado(): void {
+        $merchant = $this->createMerchant('loja@teste.test');
+        $this->loginAs('loja@teste.test');
+
+        foreach (['0', '5', '-12', '999', 'abc', '', '12.5'] as $choice) {
+            $this->assertSame(self::SCREEN . '&error=validade_invalida', $this->save($choice), $choice);
+        }
+        $this->assertSame(12, (int)$this->months($merchant));
+
+        $this->get(self::SCREEN . '&error=validade_invalida');
+        // a mensagem aponta o campo: o forms.js marca e poe o foco nele
+        $this->assertStringContainsString('data-fields="expiry_months"', $this->lastBody);
+    }
+
+    public function testSalvarAValidadeNaoMexeNaRegraDePontos(): void {
+        $merchant = $this->createMerchant('loja@teste.test');
+        $this->db->exec("UPDATE merchants SET points_rule_cents = 500 WHERE id = $merchant");
+        $this->loginAs('loja@teste.test');
+
+        $this->save('24');
+        $this->assertSame(500, (int)$this->scalar('SELECT points_rule_cents FROM merchants WHERE id = ?', [$merchant]));
+    }
+
+    public function testPrazoDeUmaLojaNaoMudaODaOutra(): void {
+        $lojaA = $this->createMerchant('a@teste.test');
+        $lojaB = $this->createMerchant('b@teste.test');
+        $this->loginAs('b@teste.test');
+
+        $this->save('3');
+        $this->assertSame(12, (int)$this->months($lojaA));
+        $this->assertSame(3, (int)$this->months($lojaB));
+    }
+
+    public function testSemLoginNaoSalva(): void {
+        $merchant = $this->createMerchant('loja@teste.test');
+
+        [, $location] = $this->post(self::SCREEN, ['action' => 'expiry', 'expiry_months' => '3'], false);
+        $this->assertSame('merchant/login&error=sessao_expirada', $location);
+        $this->assertSame(12, (int)$this->months($merchant));
+    }
+
+    // a migration e o schema.sql precisam chegar no mesmo lugar: historico aceita o tipo 'expire'
+    public function testHistoricoAceitaOTipoExpire(): void {
+        $type = $this->scalar(
+            "SELECT column_type FROM information_schema.columns
+             WHERE table_schema = DATABASE() AND table_name = 'points_log' AND column_name = 'type'"
+        );
+        $this->assertStringContainsString("'expire'", (string)$type);
+    }
+}
diff --git a/views/merchant/points-rule.php b/views/merchant/points-rule.php
index 2d4cf89..74e86a2 100644
--- a/views/merchant/points-rule.php
+++ b/views/merchant/points-rule.php
@@ -34,4 +34,35 @@
     <?php endif; ?>
 </section>
 
+<section class="card">
+    <h2>Validade dos pontos</h2>
+    <p class="muted rule-help">O saldo do cliente vence quando ele fica esse tempo sem nenhuma movimentação na sua loja (ganhar, resgatar ou estornar pontos). Cada movimentação renova o prazo do saldo inteiro.</p>
+
+    <p class="rule-current">
+        <?php if ($expiryMonths): ?>
+            Validade atual: <strong><?= (int)$expiryMonths ?> meses</strong> sem movimentação.
+        <?php else: ?>
+            Validade atual: <strong>os pontos não vencem</strong>.
+        <?php endif; ?>
+    </p>
+
+    <form action="<?= e(url('merchant/points-rule')) ?>" method="POST">
+        <?= Csrf::field() ?>
+        <input type="hidden" name="action" value="expiry">
+
+        <div class="form-group">
+            <label for="expiry_months">Os pontos vencem depois de quanto tempo sem movimentação?</label>
+            <select name="expiry_months" id="expiry_months" required>
+                <?php foreach ($expiryOptions as $months): ?>
+                    <option value="<?= (int)$months ?>"<?= $expiryMonths === $months ? ' selected' : '' ?>><?= (int)$months ?> meses</option>
+                <?php endforeach; ?>
+                <option value="never"<?= $expiryMonths === null ? ' selected' : '' ?>>Não vencem</option>
+            </select>
+            <p class="muted rule-example">A mudança vale para todos os clientes da loja, inclusive para o saldo que eles já têm.</p>
+        </div>
+
+        <button type="submit" class="btn-primary btn-inline">Salvar validade</button>
+    </form>
+</section>
+
 <?php require __DIR__ . '/../partials/merchant-footer.php'; ?>
diff --git a/views/partials/flash.php b/views/partials/flash.php
index 034b6fb..51dde36 100644
--- a/views/partials/flash.php
+++ b/views/partials/flash.php
@@ -33,6 +33,7 @@
         'confirmacao_obrigatoria' => 'Marque a confirmação de que o cliente pediu a exclusão.',
         'estorno_invalido'      => 'Lançamento não encontrado para este cliente.',
         'regra_invalida'        => 'Informe um valor de R$ 0,01 a R$ 1.000.000,00.',
+        'validade_invalida'     => 'Escolha um dos prazos de validade da lista.',
         'valor_invalido'        => 'Informe o valor da compra, ex.: 12,90.',
         'valor_pontos_demais'   => 'Essa compra daria mais de 10.000 pontos, o limite por lançamento. Confira o valor ou divida em mais de um lançamento.',
         'valor_sem_pontos'      => 'O valor da compra não chega a 1 ponto pela regra da loja.',
@@ -69,6 +70,7 @@
         'resgate_estornado'    => 'Resgate estornado. Os pontos voltaram ao saldo.',
         'regra_salva'       => 'Regra de pontos salva.',
         'regra_removida'    => 'Regra de pontos removida.',
+        'validade_salva'    => 'Validade dos pontos salva.',
         'perfil_atualizado' => 'Dados da loja atualizados.',
         'reset_enviado'     => 'Se o e-mail for de uma loja cadastrada, enviamos um link para criar uma nova senha. Ele vale por 1 hora.',
         'senha_redefinida'  => 'Senha nova criada. Entre com ela.',
@@ -96,6 +98,7 @@
     'valor_sem_pontos'          => ['amount'],
     'valor_pontos_demais'       => ['amount'],
     'regra_invalida'            => ['rule'],
+    'validade_invalida'         => ['expiry_months'],
     'telefone_novo_invalido'    => ['new_phone'],
     'telefone_igual'            => ['new_phone'],
     'telefone_ja_cliente'       => ['new_phone'],

From 2e86f46f80726667732fd90496c44518e9dc06a7 Mon Sep 17 00:00:00 2001
From: andynnnfw <and345melo@gmail.com>
Date: Thu, 8 Oct 2026 21:11:05 -0300
Subject: [PATCH 2/3] feat(pontos): rotina que vence o saldo parado e registra
 no points_log

- src/Models/LoyaltyCardModel.php: metodos expire, expireIdle e countExpirable, com trava do cartao e registro expire na mesma transacao

- bin/expire-points.php: script da rotina, com --dry-run que so mostra o que venceria

- src/Support/helpers.php: tipo expire aparece como Venceu no extrato e nos relatorios

- public/css/app.css: selo badge-expire com as cores de erro da paleta

- docs/operacao.md: secao Vencimento dos pontos com o comando e como agendar

- CLAUDE.md: comando novo e a regra de validade no modelo de dados

- tests/Integration/PointsExpiryTest.php: testes da rotina (prazo por loja, renovacao, loja inativa, lotes, sem vencer em dobro)

- tests/Unit/HelpersTest.php: teste do rotulo e selo do vencimento
---
 CLAUDE.md                              |   4 +-
 bin/expire-points.php                  |  54 +++++++++
 docs/operacao.md                       |  28 +++++
 public/css/app.css                     |   6 +
 src/Models/LoyaltyCardModel.php        |  84 ++++++++++++++
 src/Support/helpers.php                |   1 +
 tests/Integration/PointsExpiryTest.php | 148 +++++++++++++++++++++++++
 tests/Unit/HelpersTest.php             |   4 +
 8 files changed, 328 insertions(+), 1 deletion(-)
 create mode 100644 bin/expire-points.php
 create mode 100644 tests/Integration/PointsExpiryTest.php

diff --git a/CLAUDE.md b/CLAUDE.md
index 1599541..018d360 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,6 +26,7 @@ tsc                                    # compila src/ts -> public/js (tsconfig.j
 php bin/migrate.php                    # roda as migrations pendentes (status | baseline NNN)
 php bin/backup.php                     # backup do banco (mysqldump .sql.gz em BACKUP_DIR)
 php bin/create-admin.php email "Nome"  # cria um administrador (senha pela entrada padrão)
+php bin/expire-points.php              # vence o saldo parado alem do prazo de cada loja (--dry-run so mostra)
 docker compose up -d --build           # aplicacao + mysql em docker (docs/operacao.md)
 ```
 
@@ -67,7 +68,8 @@ Banco: `mysql -u root -p < database/schema.sql` em instalação nova. Banco já
 - `customers` é **só o telefone**, global e único (só dígitos, 10–11, via `PhoneValidator::sanitize`); o mesmo cliente pode ter cartão em várias lojas.
 - `loyalty_cards` = par (merchant, customer) único. Guarda o que o cliente deu **a esta loja** (`customer_name`, `consent_at`, `consent_version`), o saldo (`current_points`, `total_accumulated`) e `anonymized_at`. `findOrCreate` usa `ON DUPLICATE KEY UPDATE id = LAST_INSERT_ID(id)` e nunca troca nome nem consentimento de cartão existente.
 - **LGPD (regra da task 11, `docs/adr/002-lgpd-dados-por-loja.md`)**: nenhuma tela de uma loja mostra dado vindo de outra. Telefone sem cartão nesta loja vai sempre para o cadastro rápido, seja novo ou de outra loja: nunca crie caminho que diferencie os dois. Consentimento é gravado no cadastro com `Privacy::VERSION` (mudou o texto de `views/privacy.php` de forma relevante, troque a versão). Exclusão = `LoyaltyCardModel::anonymize` (cartão fica só para os relatórios, telefone some quando não há mais cartão).
-- `points_log` é o histórico (`earn`/`redeem`/`reversal`, `reward_id` nos resgates, `reverses_id` nos estornos). Toda mudança de saldo passa por `LoyaltyCardModel::addPoints` / `redeem` / `reverse`, que atualizam o cartão e gravam o log na mesma transação; `redeem` usa `SELECT ... FOR UPDATE` para impedir gasto duplo. Não altere saldo fora desses métodos.
+- `points_log` é o histórico (`earn`/`redeem`/`reversal`/`expire`, `reward_id` nos resgates, `reverses_id` nos estornos). Toda mudança de saldo passa por `LoyaltyCardModel::addPoints` / `redeem` / `reverse`, que atualizam o cartão e gravam o log na mesma transação; `redeem` usa `SELECT ... FOR UPDATE` para impedir gasto duplo. Não altere saldo fora desses métodos.
+- **Validade dos pontos (task 31)**: cada loja tem `merchants.points_expiry_months` (padrão 12, `NULL` = não vence, escolhido na tela Regra de pontos). O saldo inteiro vence depois desse tempo sem movimentação, contado de `loyalty_cards.last_use_at`; a data não é gravada, é sempre calculada. Quem vence é `LoyaltyCardModel::expire` / `expireIdle` (linha `expire` no `points_log`), chamado pelo `bin/expire-points.php`, que precisa estar agendado (`docs/operacao.md`).
 - `merchants` guarda CPF **ou** CNPJ (normalizados por `DocumentValidator::normalize`, UNIQUE). O CNPJ pode ser alfanumérico (letras maiúsculas nas 12 primeiras posições, task 57). Validação só por dígito verificador, sem API externa (ver `docs/adr/001-documents-validation.md`).
 
 **Área pública** — a home (`HomeController`, view `views/home.php`, `public/css/home.css`) apresenta o produto e leva ao cadastro; lojista logado vai direto ao painel. `customer/balance&loja=CODIGO` consulta o saldo pelo telefone sem login, **só na loja do código** (`merchants.public_code`, impresso no cartaz e embutido no QR), com limite por IP (5/min → 429) e exibindo só o primeiro nome do cartão daquela loja. Sem código válido, a página pede o código (nunca lista lojas). `privacy` é a política de privacidade (rascunho pendente de revisão jurídica).
diff --git a/bin/expire-points.php b/bin/expire-points.php
new file mode 100644
index 0000000..cfa9b89
--- /dev/null
+++ b/bin/expire-points.php
@@ -0,0 +1,54 @@
+<?php
+// vence o saldo de pontos parado alem do prazo de cada loja (merchants.points_expiry_months, task 31).
+//
+//   php bin/expire-points.php             vence os saldos e registra cada um no historico (points_log 'expire')
+//   php bin/expire-points.php --dry-run   so mostra quantos cartoes e pontos venceriam, sem alterar nada
+//
+// agendar uma vez por dia (cron, agendador de tarefas). pode rodar quantas vezes quiser: saldo ja vencido
+// nao vence de novo. sai com codigo 1 se falhar, pra o agendador avisar. ver docs/operacao.md.
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use App\Database;
+use App\Models\LoyaltyCardModel;
+use App\Support\Env;
+use App\Support\ErrorLog;
+
+if (PHP_SAPI !== 'cli') {
+    exit(1);
+}
+
+Env::load(dirname(__DIR__));
+date_default_timezone_set(app_timezone());
+$logToFile = ErrorLog::useFile(Env::get('LOG_FILE'));
+
+$option = $argv[1] ?? '';
+
+try {
+    if ($option !== '' && $option !== '--dry-run') {
+        throw new RuntimeException("opcao desconhecida: $option (use sem nada ou com --dry-run)");
+    }
+    if (Env::missing() !== []) {
+        throw new RuntimeException('variaveis obrigatorias sem valor: ' . implode(', ', Env::missing()));
+    }
+
+    $cards = new LoyaltyCardModel(Database::connect());
+
+    if ($option === '--dry-run') {
+        $preview = $cards->countExpirable();
+        printf("venceriam agora: %d cartao(oes), %d ponto(s). nada foi alterado.\n", $preview['cards'], $preview['points']);
+        exit(0);
+    }
+
+    $result = $cards->expireIdle();
+    echo $result['cards'] === 0
+        ? "nada a vencer.\n"
+        : sprintf("%d cartao(oes) com saldo vencido, %d ponto(s) no total.\n", $result['cards'], $result['points']);
+} catch (Throwable $e) {
+    // vai pro terminal e, se houver LOG_FILE, pro log de erros (o agendador nem sempre guarda a saida)
+    fwrite(STDERR, 'erro ao vencer pontos: ' . $e->getMessage() . "\n");
+    if ($logToFile) {
+        error_log('[expire-points] ' . $e->getMessage());
+    }
+    exit(1);
+}
diff --git a/docs/operacao.md b/docs/operacao.md
index 19a656c..85a1b21 100644
--- a/docs/operacao.md
+++ b/docs/operacao.md
@@ -135,6 +135,34 @@ gunzip -c fidelityx-20261005-030000.sql.gz | docker compose exec -T db sh -c 'my
 
 A restauração **substitui** as tabelas do banco de destino pelo conteúdo do backup. Depois dela, rode `php bin/migrate.php` (o backup pode ser anterior à última migration).
 
+## Vencimento dos pontos
+
+Cada loja tem um prazo de validade (`merchants.points_expiry_months`, padrão 12 meses; o lojista muda ou desliga na tela Regra de pontos). O saldo de um cliente vence quando ele fica esse tempo sem nenhuma movimentação naquela loja. Quem tira os pontos vencidos do saldo é este comando:
+
+```bash
+php bin/expire-points.php             # vence os saldos parados
+php bin/expire-points.php --dry-run   # só mostra quantos cartões e pontos venceriam, sem alterar nada
+```
+
+Cada saldo vencido vira uma linha `expire` no histórico (`points_log`), que aparece no extrato do cliente e nos relatórios da loja. Rodar de novo não vence nada em dobro. Lojas inativas e cartões anonimizados ficam de fora. Em caso de falha o comando sai com código 1.
+
+**Sem o agendamento nada vence**: a data aparece para o cliente, mas o saldo continua lá. Agende uma vez por dia, como o backup:
+
+```
+# cron no servidor (4h da manhã), com Docker
+0 4 * * * cd /caminho/do/fidelityx && docker compose exec -T app php bin/expire-points.php >> /var/log/fidelityx-expire.log 2>&1
+
+# cron sem Docker
+0 4 * * * cd /caminho/do/fidelityx && php bin/expire-points.php >> /var/log/fidelityx-expire.log 2>&1
+```
+
+No Windows (XAMPP), use o Agendador de Tarefas chamando `C:\xampp\php\php.exe bin\expire-points.php` na pasta do projeto.
+
+Cuidados:
+
+- O vencimento não tem "desfazer". Antes da primeira execução em um banco com dados reais, rode com `--dry-run` e faça um backup.
+- Se a loja diminuir o prazo, os saldos que já passam do prazo novo vencem na próxima execução.
+
 ## Registro de erros
 
 - Exceção não tratada e erro fatal viram uma linha no log e a página 500. A página mostra um código curto (ex.: `ab12cd34`) e a mesma sequência aparece na linha do log: quando um lojista relatar o erro, procure por ela.
diff --git a/public/css/app.css b/public/css/app.css
index 8319378..1b843e4 100644
--- a/public/css/app.css
+++ b/public/css/app.css
@@ -286,6 +286,12 @@ th.num {
     color: var(--warning-text);
 }
 
+/* pontos vencidos por falta de movimentacao */
+.badge-expire {
+    background: var(--error-soft);
+    color: var(--error-text);
+}
+
 .btn-secondary {
     min-height: 44px;
     background: transparent;
diff --git a/src/Models/LoyaltyCardModel.php b/src/Models/LoyaltyCardModel.php
index be5d0e6..5474ddd 100644
--- a/src/Models/LoyaltyCardModel.php
+++ b/src/Models/LoyaltyCardModel.php
@@ -180,6 +180,90 @@ public function redeem($cardId, $reward) {
         }
     }
 
+    // validade dos pontos (task 31): saldo parado alem do prazo da loja (merchants.points_expiry_months).
+    // o prazo conta da ultima movimentacao do cartao (cartao sem nenhuma conta da criacao). ficam de fora:
+    // cartao sem saldo ou anonimizado, loja sem prazo (pontos nao vencem) e loja inativa (saldo congelado).
+    private const EXPIRABLE = "lc.current_points > 0 AND lc.anonymized_at IS NULL
+                               AND m.status = 'active' AND m.points_expiry_months IS NOT NULL
+                               AND COALESCE(lc.last_use_at, lc.created_at) <= NOW() - INTERVAL m.points_expiry_months MONTH";
+
+    // quantos cartoes e quantos pontos venceriam agora (so consulta, nao altera nada)
+    public function countExpirable(): array {
+        $row = $this->db->query(
+            'SELECT COUNT(*) AS cards, COALESCE(SUM(lc.current_points), 0) AS points
+             FROM loyalty_cards lc JOIN merchants m ON m.id = lc.merchant_id
+             WHERE ' . self::EXPIRABLE
+        )->fetch(\PDO::FETCH_ASSOC);
+
+        return ['cards' => (int)$row['cards'], 'points' => (int)$row['points']];
+    }
+
+    // vence o saldo de um cartao: zera os pontos e registra um 'expire' no historico (tudo ou nada).
+    // confere a regra de novo com o cartao travado: se o cliente movimentou (ou a loja mudou o prazo)
+    // entre a busca e este momento, nada vence. devolve quantos pontos venceram (0 = nada a vencer).
+    // o total acumulado e a data da ultima movimentacao ficam como estavam: vencer nao e movimentacao do cliente.
+    public function expire($cardId): int {
+        $this->db->beginTransaction();
+        try {
+            // trava o cartao: lancamento ou resgate ao mesmo tempo espera o commit e ja ve o saldo certo
+            $stmt = $this->db->prepare('SELECT current_points FROM loyalty_cards WHERE id = :id FOR UPDATE');
+            $stmt->execute([':id' => $cardId]);
+            $points = (int)$stmt->fetchColumn();
+
+            $stmt = $this->db->prepare(
+                'SELECT m.points_expiry_months
+                 FROM loyalty_cards lc JOIN merchants m ON m.id = lc.merchant_id
+                 WHERE lc.id = :id AND ' . self::EXPIRABLE
+            );
+            $stmt->execute([':id' => $cardId]);
+            $months = $stmt->fetchColumn();
+
+            if ($months === false) {
+                $this->db->rollBack();
+                return 0;
+            }
+
+            $this->db->prepare('UPDATE loyalty_cards SET current_points = 0 WHERE id = :id')
+                ->execute([':id' => $cardId]);
+
+            $description = 'Pontos vencidos: ' . (int)$months . ' meses sem movimentação';
+            $this->log($cardId, 'expire', $points, $description, null);
+
+            $this->db->commit();
+            return $points;
+        } catch (\Throwable $e) {
+            $this->db->rollBack();
+            throw $e;
+        }
+    }
+
+    // rotina do bin/expire-points.php: vence todos os saldos parados, um cartao por transacao
+    // (uma falha no meio nao desfaz os que ja venceram, e nenhuma trava fica aberta por muito tempo).
+    // devolve ['cards' => cartoes vencidos, 'points' => pontos vencidos]. rodar de novo nao vence nada em dobro.
+    public function expireIdle(int $batchSize = 200): array {
+        $total = ['cards' => 0, 'points' => 0];
+
+        do {
+            $ids = $this->db->query(
+                'SELECT lc.id FROM loyalty_cards lc JOIN merchants m ON m.id = lc.merchant_id
+                 WHERE ' . self::EXPIRABLE . ' ORDER BY lc.id LIMIT ' . (int)$batchSize
+            )->fetchAll(\PDO::FETCH_COLUMN);
+
+            $expiredInBatch = 0;
+            foreach ($ids as $cardId) {
+                $points = $this->expire($cardId);
+                if ($points > 0) {
+                    $expiredInBatch++;
+                    $total['cards']++;
+                    $total['points'] += $points;
+                }
+            }
+            // lote cheio = pode haver mais; lote sem nenhum vencimento = os que sobraram deixaram de valer, para
+        } while (count($ids) === $batchSize && $expiredInBatch > 0);
+
+        return $total;
+    }
+
     // filtro de busca por nome ou telefone. so numero (com ou sem mascara) busca no telefone;
     // qualquer outra coisa busca no nome. % e _ do que foi digitado valem como letra, nao como coringa.
     private function searchClause(string $search): array {
diff --git a/src/Support/helpers.php b/src/Support/helpers.php
index 6443594..101346c 100644
--- a/src/Support/helpers.php
+++ b/src/Support/helpers.php
@@ -66,6 +66,7 @@ function log_type_view(string $type, ?string $reversedType = null): array {
         $type === 'redeem' => ['Resgatou', 'badge-redeem', '−'],
         $type === 'reversal' && $reversedType === 'redeem' => ['Estorno de resgate', 'badge-reversal', '+'],
         $type === 'reversal' => ['Estorno', 'badge-reversal', '−'],
+        $type === 'expire' => ['Venceu', 'badge-expire', '−'],
         default            => [$type, '', ''],
     };
 }
diff --git a/tests/Integration/PointsExpiryTest.php b/tests/Integration/PointsExpiryTest.php
new file mode 100644
index 0000000..a242e69
--- /dev/null
+++ b/tests/Integration/PointsExpiryTest.php
@@ -0,0 +1,148 @@
+<?php
+
+namespace Tests\Integration;
+
+use App\Models\LoyaltyCardModel;
+use Tests\Support\DatabaseTestCase;
+
+// task 31: saldo parado alem do prazo da loja vence e fica registrado no historico
+final class PointsExpiryTest extends DatabaseTestCase {
+    private LoyaltyCardModel $cards;
+    private int $merchant;
+    private int $card;
+
+    protected function setUp(): void {
+        parent::setUp();
+        $this->cards = new LoyaltyCardModel($this->db);
+        $this->merchant = $this->createMerchant(); // nasce com 12 meses de validade
+        $this->card = $this->createCard($this->merchant, 'Bia', '11922220002');
+    }
+
+    // lanca pontos e empurra a ultima movimentacao do cartao pra $months meses atras
+    private function idleCard(int $card, int $points, int $months): void {
+        $this->cards->addPoints($card, $points, 'Compra');
+        $this->db->exec("UPDATE loyalty_cards SET last_use_at = NOW() - INTERVAL $months MONTH WHERE id = $card");
+    }
+
+    private function balance(int $card): int {
+        return (int)$this->scalar('SELECT current_points FROM loyalty_cards WHERE id = ?', [$card]);
+    }
+
+    public function testSaldoParadoAlemDoPrazoVenceEFicaNoHistorico(): void {
+        $this->idleCard($this->card, 80, 13);
+        $before = $this->db->query("SELECT last_use_at, total_accumulated FROM loyalty_cards WHERE id = {$this->card}")->fetch();
+
+        $this->assertSame(['cards' => 1, 'points' => 80], $this->cards->countExpirable());
+        $this->assertSame(['cards' => 1, 'points' => 80], $this->cards->expireIdle());
+
+        $this->assertSame(0, $this->balance($this->card));
+        $log = $this->db->query("SELECT quantity, description, reward_id, reverses_id FROM points_log WHERE type = 'expire'")->fetch();
+        $this->assertSame(80, (int)$log['quantity']);
+        $this->assertSame('Pontos vencidos: 12 meses sem movimentação', $log['description']);
+        $this->assertNull($log['reward_id']);
+        $this->assertNull($log['reverses_id']);
+
+        // vencer nao e movimentacao do cliente: total acumulado e ultima movimentacao ficam como estavam
+        $after = $this->db->query("SELECT last_use_at, total_accumulated FROM loyalty_cards WHERE id = {$this->card}")->fetch();
+        $this->assertSame($before, $after);
+    }
+
+    public function testDentroDoPrazoNaoVence(): void {
+        $this->idleCard($this->card, 80, 11);
+
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(80, $this->balance($this->card));
+        $this->assertSame(0, (int)$this->scalar("SELECT COUNT(*) FROM points_log WHERE type = 'expire'"));
+    }
+
+    public function testRodarDeNovoNaoVenceEmDobro(): void {
+        $this->idleCard($this->card, 80, 13);
+
+        $this->cards->expireIdle();
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(1, (int)$this->scalar("SELECT COUNT(*) FROM points_log WHERE type = 'expire'"));
+    }
+
+    public function testMovimentacaoNovaRenovaOPrazoDoSaldoInteiro(): void {
+        $this->idleCard($this->card, 80, 13);
+        $this->cards->addPoints($this->card, 5, 'Compra'); // cliente voltou antes da rotina rodar
+
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(85, $this->balance($this->card));
+    }
+
+    public function testCadaLojaTemOSeuPrazo(): void {
+        $lojaCurta = $this->createMerchant('curta@teste.test');
+        $this->db->exec("UPDATE merchants SET points_expiry_months = 3 WHERE id = $lojaCurta");
+        $cardCurta = $this->createCard($lojaCurta, 'Bia', '11922220002');
+
+        // o mesmo cliente, 4 meses parado nas duas lojas: so vence na de 3 meses
+        $this->idleCard($this->card, 50, 4);
+        $this->idleCard($cardCurta, 30, 4);
+
+        $this->assertSame(['cards' => 1, 'points' => 30], $this->cards->expireIdle());
+        $this->assertSame(50, $this->balance($this->card));
+        $this->assertSame(0, $this->balance($cardCurta));
+        $this->assertSame(
+            'Pontos vencidos: 3 meses sem movimentação',
+            $this->scalar("SELECT description FROM points_log WHERE type = 'expire'")
+        );
+    }
+
+    public function testLojaSemPrazoNaoVenceNunca(): void {
+        $this->db->exec("UPDATE merchants SET points_expiry_months = NULL WHERE id = {$this->merchant}");
+        $this->idleCard($this->card, 80, 60);
+
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(80, $this->balance($this->card));
+    }
+
+    public function testLojaInativaFicaComOSaldoCongelado(): void {
+        $this->db->exec("UPDATE merchants SET status = 'inactive' WHERE id = {$this->merchant}");
+        $this->idleCard($this->card, 80, 13);
+
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(80, $this->balance($this->card));
+    }
+
+    public function testCartaoSemSaldoOuAnonimizadoFicaDeFora(): void {
+        // sem saldo: nada a vencer, e nao gera linha de 0 pontos no historico
+        $this->db->exec("UPDATE loyalty_cards SET last_use_at = NOW() - INTERVAL 13 MONTH WHERE id = {$this->card}");
+
+        $outro = $this->createCard($this->merchant, 'Caio', '11933330003');
+        $this->idleCard($outro, 40, 13);
+        $this->cards->anonymize($outro, $this->merchant);
+
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+        $this->assertSame(0, (int)$this->scalar("SELECT COUNT(*) FROM points_log WHERE type = 'expire'"));
+    }
+
+    // a rotina confere a regra de novo com o cartao travado: chamar direto num cartao em dia nao vence nada
+    public function testExpireDeUmCartaoEmDiaNaoFazNada(): void {
+        $this->idleCard($this->card, 80, 2);
+
+        $this->assertSame(0, $this->cards->expire($this->card));
+        $this->assertSame(80, $this->balance($this->card));
+    }
+
+    public function testVenceVariosCartoesEmLotes(): void {
+        $this->idleCard($this->card, 10, 13);
+        foreach (['11933330003', '11944440004', '11955550005', '11966660006'] as $i => $phone) {
+            $this->idleCard($this->createCard($this->merchant, "Cliente $i", $phone), 10, 13);
+        }
+
+        // lote de 2: precisa de mais de uma volta pra vencer os 5
+        $this->assertSame(['cards' => 5, 'points' => 50], $this->cards->expireIdle(2));
+        $this->assertSame(0, (int)$this->scalar('SELECT COALESCE(SUM(current_points), 0) FROM loyalty_cards'));
+    }
+
+    // depois de vencer, o cliente volta a acumular normalmente
+    public function testClienteAcumulaDeNovoDepoisDoVencimento(): void {
+        $this->idleCard($this->card, 80, 13);
+        $this->cards->expireIdle();
+
+        $this->cards->addPoints($this->card, 15, 'Compra');
+        $this->assertSame(15, $this->balance($this->card));
+        $this->assertSame(['cards' => 0, 'points' => 0], $this->cards->expireIdle());
+    }
+}
diff --git a/tests/Unit/HelpersTest.php b/tests/Unit/HelpersTest.php
index 234e2e1..e87efb9 100644
--- a/tests/Unit/HelpersTest.php
+++ b/tests/Unit/HelpersTest.php
@@ -15,4 +15,8 @@ public function testFormatDocument(): void {
         $this->assertSame('123', format_document('123'), 'tamanho desconhecido sai so com os digitos');
         $this->assertSame('', format_document(null));
     }
+
+    public function testVencimentoTemRotuloESeloProprioNoExtrato(): void {
+        $this->assertSame(['Venceu', 'badge-expire', '−'], log_type_view('expire'));
+    }
 }

From 55ea68c10c2bf80eae7731e80830e59271844014 Mon Sep 17 00:00:00 2001
From: andynnnfw <and345melo@gmail.com>
Date: Thu, 8 Oct 2026 21:16:56 -0300
Subject: [PATCH 3/3] feat(cliente): data de vencimento na consulta e na tela
 do cliente

- src/Models/LoyaltyCardModel.php: findByMerchantAndPhone devolve expires_at (ultima movimentacao mais o prazo da loja)

- src/Support/helpers.php: funcao format_date para mostrar so o dia

- views/partials/points-expiry.php: linha com a validade do saldo, ou aviso de vencido

- views/customer/balance.php: consulta publica mostra ate quando os pontos valem

- views/merchant/customer.php: tela do cliente no painel mostra a mesma data

- public/css/components.css: classe points-expiry

- CLAUDE.md: documenta o format_date e de onde vem a data de vencimento

- tests/Feature/PointsExpiryScreenTest.php: testes das duas telas (prazo da loja, sem data, vencido, isolamento entre lojas)

- tests/Unit/HelpersTest.php: teste do format_date
---
 CLAUDE.md                                |   4 +-
 public/css/components.css                |   7 ++
 src/Models/LoyaltyCardModel.php          |   8 +-
 src/Support/helpers.php                  |   5 +
 tests/Feature/PointsExpiryScreenTest.php | 124 +++++++++++++++++++++++
 tests/Unit/HelpersTest.php               |   5 +
 views/customer/balance.php               |   1 +
 views/merchant/customer.php              |   1 +
 views/partials/points-expiry.php         |  16 +++
 9 files changed, 168 insertions(+), 3 deletions(-)
 create mode 100644 tests/Feature/PointsExpiryScreenTest.php
 create mode 100644 views/partials/points-expiry.php

diff --git a/CLAUDE.md b/CLAUDE.md
index 018d360..4edd49a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,7 +46,7 @@ Banco: `mysql -u root -p < database/schema.sql` em instalação nova. Banco já
 
 **Post/Redirect/Get com códigos de flash** — handlers terminam com `redirect('rota', ['error' => 'codigo'])` ou `['success' => 'codigo']` (`redirect()` tem tipo `never`, faz `exit`). `views/partials/flash.php` traduz o código via um mapa fixo; **código novo precisa ser adicionado nesse mapa**, senão nada aparece. Nunca exibir o valor cru da query string.
 
-**Views** — PHP puro em `views/`, recebem variáveis via `extract()` do `View::render($view, $data)`. Toda saída passa por `e()`. Links e actions usam `url('rota', [...])`; formulários POST incluem `<?= Csrf::field() ?>`. Páginas do painel incluem `partials/merchant-header.php` / `merchant-footer.php` (definir `$title` antes). Helpers globais (`e`, `redirect`, `url`, `format_phone`, `format_document`, `format_datetime`) ficam em `src/Support/helpers.php`, carregado pelo autoload `files` do Composer.
+**Views** — PHP puro em `views/`, recebem variáveis via `extract()` do `View::render($view, $data)`. Toda saída passa por `e()`. Links e actions usam `url('rota', [...])`; formulários POST incluem `<?= Csrf::field() ?>`. Páginas do painel incluem `partials/merchant-header.php` / `merchant-footer.php` (definir `$title` antes). Helpers globais (`e`, `redirect`, `url`, `format_phone`, `format_document`, `format_datetime`, `format_date`) ficam em `src/Support/helpers.php`, carregado pelo autoload `files` do Composer.
 
 **Fuso horário** — `app_timezone()` (`APP_TIMEZONE` do `.env`, padrão `America/Sao_Paulo`) é aplicado no PHP pelo `index.php` e pelo `tests/bootstrap.php`, e o `Database` faz `SET time_zone` com o mesmo offset em toda conexão. Não dependa do fuso do `php.ini` nem do servidor MySQL.
 
@@ -69,7 +69,7 @@ Banco: `mysql -u root -p < database/schema.sql` em instalação nova. Banco já
 - `loyalty_cards` = par (merchant, customer) único. Guarda o que o cliente deu **a esta loja** (`customer_name`, `consent_at`, `consent_version`), o saldo (`current_points`, `total_accumulated`) e `anonymized_at`. `findOrCreate` usa `ON DUPLICATE KEY UPDATE id = LAST_INSERT_ID(id)` e nunca troca nome nem consentimento de cartão existente.
 - **LGPD (regra da task 11, `docs/adr/002-lgpd-dados-por-loja.md`)**: nenhuma tela de uma loja mostra dado vindo de outra. Telefone sem cartão nesta loja vai sempre para o cadastro rápido, seja novo ou de outra loja: nunca crie caminho que diferencie os dois. Consentimento é gravado no cadastro com `Privacy::VERSION` (mudou o texto de `views/privacy.php` de forma relevante, troque a versão). Exclusão = `LoyaltyCardModel::anonymize` (cartão fica só para os relatórios, telefone some quando não há mais cartão).
 - `points_log` é o histórico (`earn`/`redeem`/`reversal`/`expire`, `reward_id` nos resgates, `reverses_id` nos estornos). Toda mudança de saldo passa por `LoyaltyCardModel::addPoints` / `redeem` / `reverse`, que atualizam o cartão e gravam o log na mesma transação; `redeem` usa `SELECT ... FOR UPDATE` para impedir gasto duplo. Não altere saldo fora desses métodos.
-- **Validade dos pontos (task 31)**: cada loja tem `merchants.points_expiry_months` (padrão 12, `NULL` = não vence, escolhido na tela Regra de pontos). O saldo inteiro vence depois desse tempo sem movimentação, contado de `loyalty_cards.last_use_at`; a data não é gravada, é sempre calculada. Quem vence é `LoyaltyCardModel::expire` / `expireIdle` (linha `expire` no `points_log`), chamado pelo `bin/expire-points.php`, que precisa estar agendado (`docs/operacao.md`).
+- **Validade dos pontos (task 31)**: cada loja tem `merchants.points_expiry_months` (padrão 12, `NULL` = não vence, escolhido na tela Regra de pontos). O saldo inteiro vence depois desse tempo sem movimentação, contado de `loyalty_cards.last_use_at`; a data não é gravada, é sempre calculada. Quem vence é `LoyaltyCardModel::expire` / `expireIdle` (linha `expire` no `points_log`), chamado pelo `bin/expire-points.php`, que precisa estar agendado (`docs/operacao.md`). A data aparece para o cliente e para o lojista pelo `views/partials/points-expiry.php`, a partir do `expires_at` de `findByMerchantAndPhone`.
 - `merchants` guarda CPF **ou** CNPJ (normalizados por `DocumentValidator::normalize`, UNIQUE). O CNPJ pode ser alfanumérico (letras maiúsculas nas 12 primeiras posições, task 57). Validação só por dígito verificador, sem API externa (ver `docs/adr/001-documents-validation.md`).
 
 **Área pública** — a home (`HomeController`, view `views/home.php`, `public/css/home.css`) apresenta o produto e leva ao cadastro; lojista logado vai direto ao painel. `customer/balance&loja=CODIGO` consulta o saldo pelo telefone sem login, **só na loja do código** (`merchants.public_code`, impresso no cartaz e embutido no QR), com limite por IP (5/min → 429) e exibindo só o primeiro nome do cartão daquela loja. Sem código válido, a página pede o código (nunca lista lojas). `privacy` é a política de privacidade (rascunho pendente de revisão jurídica).
diff --git a/public/css/components.css b/public/css/components.css
index 7dcd7fc..02cedc2 100644
--- a/public/css/components.css
+++ b/public/css/components.css
@@ -171,6 +171,13 @@
     color: var(--warning-text);
 }
 
+/* validade do saldo (partials/points-expiry.php): linha pequena embaixo dos pontos,
+   na consulta publica e na tela do cliente no painel */
+.points-expiry {
+    font-size: 0.85rem;
+    margin-top: 0.4rem;
+}
+
 /* acessibilidade (task 18) ------------------------------------------------ */
 
 /* foco do teclado sempre visivel (inputs e selects ja tem o anel em :focus) */
diff --git a/src/Models/LoyaltyCardModel.php b/src/Models/LoyaltyCardModel.php
index 5474ddd..7dee4fb 100644
--- a/src/Models/LoyaltyCardModel.php
+++ b/src/Models/LoyaltyCardModel.php
@@ -33,10 +33,16 @@ public function findOrCreate($merchantId, $customerId, ?string $customerName = n
     }
 
     // cartao do cliente (pelo telefone) nesta loja. cartao anonimizado nao tem mais telefone, entao nao aparece.
+    // expires_at: quando o saldo vence pela validade da loja (ultima movimentacao + prazo, a mesma conta
+    // do EXPIRABLE la embaixo). NULL quando nao ha o que vencer: sem saldo ou loja sem prazo.
     public function findByMerchantAndPhone($merchantId, $phone) {
-        $sql = 'SELECT lc.id, lc.current_points, lc.total_accumulated, lc.customer_name, lc.consent_at, lc.consent_version, c.phone
+        $sql = 'SELECT lc.id, lc.current_points, lc.total_accumulated, lc.customer_name, lc.consent_at, lc.consent_version, c.phone,
+                       CASE WHEN lc.current_points > 0 AND m.points_expiry_months IS NOT NULL
+                            THEN COALESCE(lc.last_use_at, lc.created_at) + INTERVAL m.points_expiry_months MONTH
+                       END AS expires_at
                 FROM loyalty_cards lc
                 JOIN customers c ON c.id = lc.customer_id
+                JOIN merchants m ON m.id = lc.merchant_id
                 WHERE lc.merchant_id = :merchant_id AND c.phone = :phone';
         $stmt = $this->db->prepare($sql);
         $stmt->execute([
diff --git a/src/Support/helpers.php b/src/Support/helpers.php
index 101346c..2db08b9 100644
--- a/src/Support/helpers.php
+++ b/src/Support/helpers.php
@@ -53,6 +53,11 @@ function format_datetime($value): string {
     return $value ? date('d/m/Y H:i', strtotime($value)) : '—';
 }
 
+// timestamp do banco -> "30/09/2026" (so o dia, ex.: vencimento dos pontos)
+function format_date($value): string {
+    return $value ? date('d/m/Y', strtotime($value)) : '—';
+}
+
 // monta a url de uma rota interna, pra usar em links e actions de form
 function url(string $route, array $params = []): string {
     return '/index.php?' . http_build_query(array_merge(['url' => $route], $params));
diff --git a/tests/Feature/PointsExpiryScreenTest.php b/tests/Feature/PointsExpiryScreenTest.php
new file mode 100644
index 0000000..49213f3
--- /dev/null
+++ b/tests/Feature/PointsExpiryScreenTest.php
@@ -0,0 +1,124 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\LoyaltyCardModel;
+use Tests\Support\HttpTestCase;
+
+// task 31: a data de vencimento do saldo aparece na consulta publica e na tela do cliente no painel
+final class PointsExpiryScreenTest extends HttpTestCase {
+    private const PHONE = '11922220002';
+
+    private function setUpCard(int $points, string $email = 'loja@teste.test'): array {
+        $merchant = $this->createMerchant($email);
+        $card = $this->createCard($merchant, 'Bia Souza', self::PHONE);
+        if ($points > 0) {
+            (new LoyaltyCardModel($this->db))->addPoints($card, $points, 'Compra');
+        }
+        return [$merchant, $card];
+    }
+
+    // a data esperada sai da mesma conta do banco: ultima movimentacao + prazo da loja
+    private function expectedDate(int $card, int $months): string {
+        return (string)$this->scalar(
+            "SELECT DATE_FORMAT(last_use_at + INTERVAL $months MONTH, '%d/%m/%Y') FROM loyalty_cards WHERE id = ?",
+            [$card]
+        );
+    }
+
+    private function publicBalance(int $merchant): void {
+        $code = $this->publicCode($merchant);
+        $this->post('customer/balance', ['phone' => self::PHONE, 'loja' => $code], true, 'customer/balance&loja=' . $code);
+    }
+
+    public function testConsultaPublicaMostraAteQuandoOsPontosValem(): void {
+        [$merchant, $card] = $this->setUpCard(30);
+
+        $this->publicBalance($merchant);
+        $this->assertStringContainsString(
+            'Pontos válidos até <strong>' . $this->expectedDate($card, 12) . '</strong>',
+            $this->lastBody
+        );
+    }
+
+    public function testTelaDoLojistaMostraAMesmaData(): void {
+        [, $card] = $this->setUpCard(30);
+        $this->loginAs('loja@teste.test');
+
+        $this->get('merchant/customer&phone=' . self::PHONE);
+        $this->assertStringContainsString(
+            'Pontos válidos até <strong>' . $this->expectedDate($card, 12) . '</strong>',
+            $this->lastBody
+        );
+    }
+
+    public function testDataSegueOPrazoDaLoja(): void {
+        [$merchant, $card] = $this->setUpCard(30);
+        $this->db->exec("UPDATE merchants SET points_expiry_months = 3 WHERE id = $merchant");
+
+        $this->publicBalance($merchant);
+        $this->assertStringContainsString('<strong>' . $this->expectedDate($card, 3) . '</strong>', $this->lastBody);
+    }
+
+    public function testLojaEmQueOsPontosNaoVencemNaoMostraData(): void {
+        [$merchant] = $this->setUpCard(30);
+        $this->db->exec("UPDATE merchants SET points_expiry_months = NULL WHERE id = $merchant");
+
+        $this->publicBalance($merchant);
+        $this->assertStringContainsString('30 pts', $this->lastBody);
+        $this->assertStringNotContainsString('points-expiry', $this->lastBody);
+    }
+
+    public function testSemSaldoNaoMostraData(): void {
+        [$merchant] = $this->setUpCard(0);
+
+        $this->publicBalance($merchant);
+        $this->assertStringNotContainsString('points-expiry', $this->lastBody);
+
+        $this->loginAs('loja@teste.test');
+        $this->get('merchant/customer&phone=' . self::PHONE);
+        $this->assertStringNotContainsString('points-expiry', $this->lastBody);
+    }
+
+    // prazo ja passou e a rotina ainda nao rodou: a tela avisa que venceu em vez de prometer uma data no passado
+    public function testSaldoQueJaPassouDoPrazoApareceComoVencido(): void {
+        [$merchant, $card] = $this->setUpCard(30);
+        $this->db->exec("UPDATE loyalty_cards SET last_use_at = NOW() - INTERVAL 13 MONTH WHERE id = $card");
+
+        $this->publicBalance($merchant);
+        $this->assertStringContainsString(
+            'Pontos vencidos em <strong>' . $this->expectedDate($card, 12) . '</strong>',
+            $this->lastBody
+        );
+        $this->assertStringNotContainsString('Pontos válidos até', $this->lastBody);
+    }
+
+    // depois que a rotina vence o saldo, a data some (nao ha mais o que vencer) e o extrato mostra o vencimento
+    public function testDepoisDeVencerADataSomeEOExtratoMostraOVencimento(): void {
+        [, $card] = $this->setUpCard(30);
+        $this->db->exec("UPDATE loyalty_cards SET last_use_at = NOW() - INTERVAL 13 MONTH WHERE id = $card");
+        (new LoyaltyCardModel($this->db))->expireIdle();
+        $this->loginAs('loja@teste.test');
+
+        $this->get('merchant/customer&phone=' . self::PHONE);
+        $this->assertStringContainsString('balance-value">0<', $this->lastBody);
+        $this->assertStringNotContainsString('points-expiry', $this->lastBody);
+
+        $this->get('merchant/statement&phone=' . self::PHONE);
+        $this->assertStringContainsString('badge-expire', $this->lastBody);
+        $this->assertStringContainsString('Venceu', $this->lastBody);
+        $this->assertStringContainsString('Pontos vencidos: 12 meses sem movimentação', $this->lastBody);
+    }
+
+    // LGPD: a data e so desta loja; o prazo de outra loja em que o cliente tambem compra nao aparece aqui
+    public function testDataDeUmaLojaNaoVazaParaOutra(): void {
+        [$lojaA, $cardA] = $this->setUpCard(30, 'a@teste.test');
+        [$lojaB, $cardB] = $this->setUpCard(50, 'b@teste.test');
+        $this->db->exec("UPDATE merchants SET points_expiry_months = 3 WHERE id = $lojaB");
+        $this->db->exec("UPDATE loyalty_cards SET last_use_at = NOW() - INTERVAL 1 MONTH WHERE id = $cardB");
+
+        $this->publicBalance($lojaA);
+        $this->assertStringContainsString('<strong>' . $this->expectedDate($cardA, 12) . '</strong>', $this->lastBody);
+        $this->assertStringNotContainsString($this->expectedDate($cardB, 3), $this->lastBody);
+    }
+}
diff --git a/tests/Unit/HelpersTest.php b/tests/Unit/HelpersTest.php
index e87efb9..2f67c8b 100644
--- a/tests/Unit/HelpersTest.php
+++ b/tests/Unit/HelpersTest.php
@@ -16,6 +16,11 @@ public function testFormatDocument(): void {
         $this->assertSame('', format_document(null));
     }
 
+    public function testFormatDateMostraSoODia(): void {
+        $this->assertSame('08/10/2027', format_date('2027-10-08 21:15:00'));
+        $this->assertSame('—', format_date(null));
+    }
+
     public function testVencimentoTemRotuloESeloProprioNoExtrato(): void {
         $this->assertSame(['Venceu', 'badge-expire', '−'], log_type_view('expire'));
     }
diff --git a/views/customer/balance.php b/views/customer/balance.php
index a7e699f..07c3d75 100644
--- a/views/customer/balance.php
+++ b/views/customer/balance.php
@@ -70,6 +70,7 @@
                             <strong><?= number_format((int)$card['current_points'], 0, ',', '.') ?> pts</strong>
                         </div>
 
+                        <?php require __DIR__ . '/../partials/points-expiry.php'; ?>
                         <?php require __DIR__ . '/../partials/reward-progress.php'; ?>
 
                         <?php if ($rewards): ?>
diff --git a/views/merchant/customer.php b/views/merchant/customer.php
index c5fcbdc..190d077 100644
--- a/views/merchant/customer.php
+++ b/views/merchant/customer.php
@@ -8,6 +8,7 @@
         <div class="customer-name"><?= e($card['customer_name']) ?></div>
         <div class="muted"><?= e(format_phone($card['phone'])) ?></div>
         <a href="<?= e(url('merchant/statement', ['phone' => $card['phone']])) ?>" class="customer-statement-link">Ver extrato</a>
+        <?php require __DIR__ . '/../partials/points-expiry.php'; ?>
     </div>
     <div class="customer-balance">
         <span class="customer-balance-value"><?= number_format((int)$card['current_points'], 0, ',', '.') ?></span>
diff --git a/views/partials/points-expiry.php b/views/partials/points-expiry.php
new file mode 100644
index 0000000..98113c7
--- /dev/null
+++ b/views/partials/points-expiry.php
@@ -0,0 +1,16 @@
+<?php
+// validade do saldo (task 31). espera $card com expires_at (LoyaltyCardModel::findByMerchantAndPhone).
+// sem data nao mostra nada: cartao sem saldo ou loja em que os pontos nao vencem.
+if (empty($card['expires_at'])) {
+    return;
+}
+// data ja passada: o saldo venceu e sai na proxima rodada do bin/expire-points.php
+$pointsExpired = strtotime($card['expires_at']) <= time();
+?>
+<p class="muted points-expiry">
+    <?php if ($pointsExpired): ?>
+        Pontos vencidos em <strong><?= e(format_date($card['expires_at'])) ?></strong> por falta de movimentação.
+    <?php else: ?>
+        Pontos válidos até <strong><?= e(format_date($card['expires_at'])) ?></strong>. Cada compra ou resgate renova o prazo.
+    <?php endif; ?>
+</p>