fix: the page's centred blocks keep their full width in the column layout

Making the body a column to keep the footer at the bottom shrank every
block centred with auto margins (the account area, and two of the Site's
sections) to the width of its content. They take the full width again, up
to their max-width, exactly as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.env.example

@@ -14,12 +14,34 @@ S3_APP_USER=dtf_app
 S3_APP_PASSWORD=local-app-storage-only
 S3_BUCKET=dtf-local-artwork
 S3_PUBLIC_ENDPOINT=http://localhost:9000
-OPERATOR_USER=operator
+OPERATOR_EMAIL=operator@example.test
 OPERATOR_PASSWORD=local-operator-only
 APP_ENV=local
 PAYMENT_ADAPTER=fake
 FREIGHT_ADAPTER=fake
 TINY_ADAPTER=fake
+# Sandbox only (see docs/LOCAL_SETUP.md, "Provider sandboxes"):
+# PAYMENT_ADAPTER=mercadopago
+# MP_ACCESS_TOKEN=TEST-...
+# MP_WEBHOOK_SECRET=...
+# MP_NOTIFICATION_URL=https://<public tunnel>/api/payments/webhook
+# Tiny API v3: client ID/secret come from the "Aplicativo" created in Tiny
+# (Configurações > Geral > Aplicativos); the redirect URI registered there
+# must be exactly TINY_REDIRECT_URI. Product ids are the Tiny products each
+# Site product becomes. Tiny has no sandbox: orders created are real.
+# TINY_CLIENT_ID=...
+# TINY_CLIENT_SECRET=...
+# TINY_REDIRECT_URI=http://localhost:8081/api/operator/tiny/callback
+# TINY_PRODUCT_TEXTIL_FOLHA=...
+# TINY_PRODUCT_TEXTIL_AVULSA=...
+# TINY_PRODUCT_UV_FOLHA=...
+# TINY_PRODUCT_UV_AVULSA=...
+# TINY_ADAPTER=tiny      # only once connected and tested: creates real orders
+# Jadlog price quotes go in jadlog.env, not here (see app/jadlog_probe.py):
+# JADLOG_TOKEN=...
+# JADLOG_CNPJ=...          # the "Usuário" Jadlog issued, the CNPJ that contracts freight
+# JADLOG_CONTA=...         # conta corrente
+# JADLOG_CONTRATO=         # only if Jadlog issued a contract number
 WHATSAPP_ADAPTER=fake
 STORAGE_ADAPTER=s3-local
 MOCK_FREIGHT_CENTS=1500

.env.exemplo

@@ -1,27 +0,0 @@
-# HISTORICAL PROTOTYPE ONLY. Do not use for the local stack; use .env.example.
-# ---- portal (nuvem) ----
-DATABASE_URL=postgresql+psycopg://dtf:senha@localhost/dtf
-S3_ENDPOINT=https://<conta>.r2.cloudflarestorage.com
-S3_BUCKET=dtf-artes
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-BASE_PORTAL=https://arte.dropstaratacado.com.br
-BASE_KANBAN=http://servidor:8080
-WEBHOOK_TOKEN=troque-isto
-AGENTE_TOKEN=troque-isto-tambem
-AGENTE_WEBHOOK=http://ip-da-fabrica:8080/api/agente/acordar
-
-# ---- Tiny ----
-TINY_CLIENT_ID=
-TINY_CLIENT_SECRET=
-TINY_TOKEN_URL=
-TINY_BASE=https://api.tiny.com.br/public-api/v3
-
-# ---- WhatsApp ----
-WHATS_PROVEDOR=meta
-WHATS_TOKEN=
-WHATS_NUMERO_ID=
-
-# ---- fábrica ----
-PASTA_DTF=\\servidor\DTF
-KANBAN_DB=C:\dtf\kanban.db

.gitea/workflows/deploy.yml

@@ -16,20 +16,158 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
       - name: Run fast regression checks
         run: |
-          python3 -m py_compile local/*.py deploy/*.py
+          python3 -m py_compile app/*.py app/**/*.py ops/*.py deploy/*.py
           python3 -m unittest \
-            local.test_dependency_lock \
-            local.test_staging_readiness \
+            tests.test_dependency_lock \
+            tests.test_staging_readiness \
             deploy.test_production_preflight \
-            local.test_pricing -v
-          sh -n local/lock_dependencies.sh
+            tests.test_pricing \
+            tests.test_secrets -v
+          sh -n infra/lock_dependencies.sh
 
-  publish-and-deploy:
-    name: Publish images and notify Portainer
+  integration:
+    name: Integration suite on a real stack
     needs: validate
-    if: gitea.event_name == 'push' && gitea.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     timeout-minutes: 45
+    env:
+      # The runner shares the host's Docker daemon, so every published port is
+      # taken on the machine itself. Known occupants of that host:
+      #   8000, 9443  Portainer (the Edge tunnel and its UI)
+      #   18080/18081 the production dtf-cloud stack (docker-compose.yml defaults)
+      #   9000/9001   MinIO defaults elsewhere
+      # This block avoids all of them. Ephemeral ports are not an option: the
+      # published port is baked into PUBLIC_ORIGIN, ALLOWED_ORIGINS and the CSP
+      # when the containers start, so it has to be known beforehand.
+      SITE_PORT: "28080"
+      KANBAN_PORT: "28081"
+      API_PORT: "28000"
+      STORAGE_PORT: "29000"
+      STORAGE_CONSOLE_PORT: "29001"
+      # Presigned URLs are signed against this endpoint, so it must be reachable
+      # by whoever follows them. The suites run inside the network, so it has to
+      # be the service name, not a published port on the host.
+      S3_PUBLIC_ENDPOINT: http://storage:9000
+      PUBLIC_ORIGIN: http://site
+      ALLOWED_HOSTS: localhost,127.0.0.1,site,kanban
+      ALLOWED_ORIGINS: http://site,http://kanban,http://localhost:28080,http://localhost:28081
+      COMPOSE: docker compose -f compose.local.yaml
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      # py_compile cannot see an unresolved name, and the four unit tests above
+      # never start the application. A missing import in local/auth.py therefore
+      # reached production and returned 500 on every session, login and
+      # registration. These suites exercise the running stack and would have
+      # failed on it immediately.
+      - name: Start the stack
+        run: |
+          $COMPOSE up --build -d --wait --wait-timeout 600
+          $COMPOSE ps
+
+      # Run inside the stack's own network. The runner is itself a container, so
+      # ports published on the host's loopback are in a different namespace and
+      # unreachable from here. SITE_HOST_HEADER keeps the Host the gateway and
+      # TrustedHostMiddleware expect, so the configuration under test is the same
+      # one a developer exercises on localhost.
+      - name: API and workflow regressions
+        run: |
+          for suite in smoke_test workflow_test security_test scanning_test payment_test quote_pagination_test print_file_test; do
+            echo "--- $suite"
+            $COMPOSE exec -T \
+              -e SITE_BASE_URL=http://site \
+              -e SITE_HOST_HEADER=localhost \
+              api python -m "tests.$suite"
+          done
+
+      # Need Pillow and httpx, which only the application image has. The raster
+      # check needs PyMuPDF as well and skips here; run it locally when changing
+      # the generator's geometry. The provider suites use a fake transport: they
+      # prove the documented contract, not the integration.
+      - name: Print-file geometry and provider adapters
+        run: $COMPOSE exec -T api python -m unittest tests.test_printfile tests.test_mercadopago tests.test_tiny tests.test_jadlog tests.test_quote_review tests.test_large_files tests.test_grade_check -v
+
+      - name: Runtime and retention regressions
+        run: |
+          $COMPOSE exec -T api python -m tests.retention_test
+          $COMPOSE exec -T api python -m tests.runtime_security_test
+          $COMPOSE exec -T api python -m tests.tiny_oauth_test
+          $COMPOSE exec -T backup python -m tests.backup_test
+
+      # Run Chrome on the Compose network. It must resolve the same storage:9000
+      # hostname used in presigned URLs, and absence of Chrome must fail CI.
+      - name: Browser regressions
+        run: |
+          $COMPOSE build browser-tests
+          $COMPOSE run --rm --no-deps browser-tests sh -ec \
+            'node tests/artwork_browser_test.mjs && node tests/browser_test.mjs'
+
+      - name: Diagnostics on failure
+        if: failure()
+        run: |
+          $COMPOSE ps || true
+          $COMPOSE logs --tail 200 api worker backup site kanban || true
+
+      - name: Tear down
+        if: always()
+        run: $COMPOSE down -v || true
+
+  scan:
+    name: Secret scan and release gate
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      TRIVY_IMAGE: ${{ vars.TRIVY_IMAGE }}
+      ENFORCE_PRODUCTION_PREFLIGHT: ${{ vars.ENFORCE_PRODUCTION_PREFLIGHT }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      # Blocking. A credential committed by accident must never reach the
+      # registry or the deployed stack, and the repository is clean today, so
+      # this gate costs nothing until it is actually needed.
+      - name: Secret scan
+        run: |
+          image="${TRIVY_IMAGE:-aquasec/trivy:0.58.1}"
+          docker run --rm -v "$PWD:/src:ro" "$image" \
+            fs --scanners secret --exit-code 1 --severity HIGH,CRITICAL \
+            --no-progress /src
+
+      # Advisory while the provider adapters are fake. This is the only copy of
+      # the gate: set ENFORCE_PRODUCTION_PREFLIGHT=true and a blocked preflight
+      # fails this job, which stops images from being published.
+      - name: Production source preflight
+        run: |
+          set +e
+          python3 deploy/production_preflight.py --source-only
+          verdict=$?
+          set -e
+          if [ "$verdict" -eq 0 ]; then
+            echo "Source preflight passes."
+            exit 0
+          fi
+          if [ "${ENFORCE_PRODUCTION_PREFLIGHT:-false}" = "true" ]; then
+            echo "::error::Source preflight blocked the release."
+            exit "$verdict"
+          fi
+          echo "::warning::Source preflight reports blockers (advisory; set ENFORCE_PRODUCTION_PREFLIGHT=true to gate)."
+
+  # Every push to main that passes validation, the integration suite and the
+  # scans publishes images. Production changes only when someone pulls and
+  # redeploys the stack in Portainer; a manual run of this workflow also calls
+  # the Portainer webhook when one is configured.
+  publish-and-deploy:
+    name: Publish images
+    needs: [validate, integration, scan]
+    if: gitea.ref == 'refs/heads/main' && (gitea.event_name == 'push' || gitea.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      TRIVY_IMAGE: ${{ vars.TRIVY_IMAGE }}
+      PYTHON_BASE_IMAGE: ${{ vars.PYTHON_BASE_IMAGE }}
+      NGINX_BASE_IMAGE: ${{ vars.NGINX_BASE_IMAGE }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
@@ -42,28 +180,90 @@ jobs:
           test -n "$REGISTRY_TOKEN"
           echo "$REGISTRY_TOKEN" | docker login gitea.blyzer.com.br \
             --username "$REGISTRY_USERNAME" --password-stdin
-      - name: Build and publish API
+      - name: Build API
         run: |
           image="gitea.blyzer.com.br/blyzer/dtf-api"
-          docker build --pull --file deploy/Dockerfile.api \
+          # The Dockerfiles pin digests themselves; these variables let a base be
+          # moved forward without editing the repository. --pull is intentionally
+          # absent: a digest already names one immutable image.
+          set --
+          [ -n "$PYTHON_BASE_IMAGE" ] && set -- --build-arg PYTHON_BASE_IMAGE="$PYTHON_BASE_IMAGE"
+          docker build --file deploy/Dockerfile.api "$@" \
             --build-arg VCS_REF="${{ gitea.sha }}" \
             --tag "$image:latest" --tag "$image:${{ gitea.sha }}" .
-          docker push "$image:latest"
-          docker push "$image:${{ gitea.sha }}"
-      - name: Build and publish web
+      - name: Build web
         run: |
           image="gitea.blyzer.com.br/blyzer/dtf-web"
-          docker build --pull --file deploy/Dockerfile.web \
+          set --
+          [ -n "$PYTHON_BASE_IMAGE" ] && set -- --build-arg PYTHON_BASE_IMAGE="$PYTHON_BASE_IMAGE"
+          [ -n "$NGINX_BASE_IMAGE" ] && set -- "$@" --build-arg NGINX_BASE_IMAGE="$NGINX_BASE_IMAGE"
+          docker build --file deploy/Dockerfile.web "$@" \
             --build-arg VCS_REF="${{ gitea.sha }}" \
             --tag "$image:latest" --tag "$image:${{ gitea.sha }}" .
-          docker push "$image:latest"
-          docker push "$image:${{ gitea.sha }}"
+      # CRITICAL blocks, HIGH is reported. Both images carry zero CRITICAL after
+      # the base pinning and OS upgrades, so this gate holds the line already
+      # reached. The remaining HIGH findings have no upstream fix, so failing on
+      # them would stop releases without making anything safer.
+      - name: Image vulnerabilities
+        run: |
+          image="${TRIVY_IMAGE:-aquasec/trivy:0.58.1}"
+          # One database download for the four scans, kept in a volume between
+          # runs and retried: a failed download from the mirror used to fail
+          # the gate as if a CRITICAL vulnerability had been found.
+          trivy() { docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+            -v dtf-trivy-cache:/root/.cache/trivy "$image" "$@"; }
+          for attempt in 1 2 3; do
+            trivy image --download-db-only --no-progress && break
+            if [ "$attempt" -eq 3 ]; then
+              echo "::error::The vulnerability database could not be downloaded; the release images were not scanned."
+              exit 1
+            fi
+            echo "Database download failed (attempt $attempt); retrying in 30 s."
+            sleep 30
+          done
+          # Findings exit 5; any other failure means the scan did not run.
+          found=0; broken=0
+          for target in \
+              "gitea.blyzer.com.br/blyzer/dtf-api:${{ gitea.sha }}" \
+              "gitea.blyzer.com.br/blyzer/dtf-web:${{ gitea.sha }}"; do
+            echo "--- $target (HIGH, reported)"
+            trivy image --skip-db-update --image-src docker --scanners vuln --severity HIGH --no-progress \
+              --format table --exit-code 0 "$target" ||
+              echo "::warning::Could not scan $target for HIGH findings"
+            echo "--- $target (CRITICAL, blocking)"
+            set +e
+            trivy image --skip-db-update --image-src docker --scanners vuln --severity CRITICAL --no-progress \
+              --format table --exit-code 5 "$target"
+            verdict=$?
+            set -e
+            if [ "$verdict" -eq 5 ]; then found=1
+            elif [ "$verdict" -ne 0 ]; then broken=1; echo "::error::The CRITICAL scan of $target did not run (exit $verdict)."
+            fi
+          done
+          if [ "$found" -ne 0 ]; then
+            echo "::error::A CRITICAL vulnerability was found in a release image."
+            exit 1
+          fi
+          if [ "$broken" -ne 0 ]; then
+            echo "::error::A release image could not be scanned; nothing is published unscanned."
+            exit 1
+          fi
+
+      - name: Publish validated images
+        run: |
+          for name in dtf-api dtf-web; do
+            image="gitea.blyzer.com.br/blyzer/$name"
+            docker push "$image:${{ gitea.sha }}"
+            docker push "$image:latest"
+          done
+
       - name: Trigger Portainer redeployment
+        if: gitea.event_name == 'workflow_dispatch'
         env:
           PORTAINER_WEBHOOK: ${{ secrets.PORTAINER_WEBHOOK }}
         run: |
           if [ -z "$PORTAINER_WEBHOOK" ]; then
-            echo "PORTAINER_WEBHOOK is not configured; images were published but deployment was skipped."
+            echo "No PORTAINER_WEBHOOK configured; redeploy the stack in Portainer."
             exit 0
           fi
           curl --fail --silent --show-error --max-time 30 --request POST "$PORTAINER_WEBHOOK"

.gitignore

@@ -35,8 +35,12 @@ deploy/portainer.env
 output/local/
 output/security/
 
-# Keep the roadmap generator, not its extracted text or render-review scratch.
-tmp/*
-!tmp/pdfs/
-tmp/pdfs/*
-!tmp/pdfs/generate_dtf_report.py
+# Scratch only. The roadmap generator moved to tools/, the PDFs to docs/.
+tmp/
+
+# Client deliverables and scratch inputs live here but are not the repository's
+# to version: they are produced for a specific week, or dropped in to test with.
+Relatorio-*.docx
+Relatorio-*.pdf
+imagem-teste.*
+output/documents/

PORTAINER.md

@@ -1,121 +0,0 @@
-# Portainer deployment
-
-DTF follows the same operating model as Graphs and ComporHUB: Gitea builds
-prebuilt images, pushes them to the Gitea registry, and calls one Portainer
-webhook. Portainer owns and redeploys one Docker Swarm stack named `dtf-cloud`.
-
-The production stack is `deploy/stack.yaml`. It contains Site, Kanban, API,
-worker, PostgreSQL, ClamAV, and a one-time database initializer. Production uses
-Cloudflare R2, so MinIO is not part of this stack.
-
-## 1. Gitea configuration
-
-The single workflow is `.gitea/workflows/deploy.yml`. Pull requests run static
-validation. A push to `main` runs the full isolated test suite, builds and scans
-the production images, publishes both `latest` and the full commit SHA, then
-calls Portainer.
-
-Repository variables:
-
-- `REGISTRY_HOST` — normally `gitea.blyzer.com.br`.
-- `REGISTRY_OWNER` — normally `blyzer`.
-- `PYTHON_BASE_IMAGE`, `NGINX_BASE_IMAGE`, `TRIVY_IMAGE` — approved immutable
-  `@sha256:` image references.
-
-Repository secrets:
-
-- `REGISTRY_USERNAME` and `REGISTRY_TOKEN` — package write credentials.
-- `PORTAINER_WEBHOOK` — webhook generated by the `dtf-cloud` Portainer stack.
-
-The webhook is called only after tests and HIGH/CRITICAL secret,
-misconfiguration, and image gates pass. The current local-only application
-fails the source preflight intentionally, so it cannot publish yet.
-
-## 2. One-time Portainer resources
-
-Use a Docker Swarm environment. Create a dedicated production PostgreSQL volume
-and set its name as `POSTGRES_VOLUME`. Label its Swarm node
-`dtf_database=true`. Do not reuse the localhost Compose volume.
-
-Create each application credential under **Secrets**. Use versioned names such
-as `dtf_prod_database_url_v1`, then place only those names in the corresponding
-`*_SECRET` stack variables. The stack expects distinct secrets for:
-
-- runtime and administrator database URLs;
-- database administrator and application-role passwords;
-- R2 access key and secret key;
-- operator password;
-- Mercado Pago token and webhook secret;
-- Tiny/Olist token;
-- WhatsApp token.
-
-Credential values must never be entered into Git, `portainer.env`, or Gitea
-workflow variables.
-
-## 3. Create the stack once
-
-In Portainer select **Stacks → Add stack → Git repository**:
-
-- Name: `dtf-cloud`
-- Repository: this Gitea repository
-- Reference: `main`
-- Compose path: `deploy/stack.yaml`
-- Registry: the private `gitea.blyzer.com.br` registry
-- Re-pull image: enabled
-- Automatic update: webhook
-
-Load a completed copy of `deploy/portainer.env.example` as the stack's
-non-secret environment variables. Do not load the example unchanged: `TBD` and
-zero digests are deliberate blockers. Keep `IMAGE_TAG=latest` for normal
-webhook deployments.
-
-Before entering those values in Portainer, validate the completed ignored file:
-
-```bash
-set -a
-. deploy/portainer.env
-set +a
-python3 deploy/production_preflight.py
-```
-
-The public reverse proxy should send the Site hostname to `SITE_PORT` and the
-Kanban hostname to `KANBAN_PORT`. `/api/` and `/portal.html` are served through
-the Site gateway. Preserve the original Host header. Do not expose PostgreSQL,
-API, worker, or ClamAV. Restrict the
-two published web ports at the host firewall so only the reverse proxy can use
-them, and terminate HTTPS at the proxy.
-
-The `db-init` service completing and stopping is expected. The other six
-services must be healthy. A failed `db-init` task or an unhealthy service blocks
-acceptance.
-
-## 4. Normal deployment
-
-Push to `main`. Gitea validates, tests, scans, publishes these images, and calls
-the webhook:
-
-```text
-gitea.blyzer.com.br/blyzer/dtf-api:latest
-gitea.blyzer.com.br/blyzer/dtf-api:<full-commit-sha>
-gitea.blyzer.com.br/blyzer/dtf-web:latest
-gitea.blyzer.com.br/blyzer/dtf-web:<full-commit-sha>
-```
-
-In Portainer, verify the new image digests, service health, `db-init` result, and
-the public `/health` endpoints. Back up PostgreSQL and R2 before changes that
-affect stored data or retention.
-
-## 5. Rollback
-
-In the Portainer stack variables, change `IMAGE_TAG` from `latest` to the full
-SHA of the last known-good Gitea commit and redeploy. This rolls back Site, API,
-Kanban, and worker code; it does not undo database migrations or restore data.
-After recovery and a corrected release, return `IMAGE_TAG` to `latest`.
-
-## Current blocker
-
-This is the final deployment shape, but it is not authorized for production
-today. Production adapters, Docker-secret file loading, provider sandbox tests,
-current clean base images, approved inputs, and a production restore rehearsal
-are still required. Do not bypass `deploy/production_preflight.py` or the Gitea
-scan gates to make a deployment run.

README.md

@@ -1,12 +1,12 @@
 # Sistema DTF 24h — Altus Group
 
-> **Active local milestone (2026-09-11):** Read [CONTEXT.md](CONTEXT.md) first.
-> Start with `docker compose up --build`, then open the [Site](http://localhost:8080)
+> **Active local milestone (2026-09-23):** Read [docs/CONTEXT.md](docs/CONTEXT.md) first.
+> Start with `docker compose -f compose.local.yaml up --build`, then open the [Site](http://localhost:8080)
 > and [Kanban](http://localhost:8081). Optional configuration: copy `.env.example`
-> to `.env`. Follow [LOCAL_SETUP.md](LOCAL_SETUP.md) for the complete test flow,
+> to `.env`. Follow [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md) for the complete test flow,
 > local login, health checks, and troubleshooting. See
-> [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) for scope and reuse decisions.
-> Production delivery uses one Portainer stack; see [PORTAINER.md](PORTAINER.md).
+> [IMPLEMENTATION_REPORT.md](docs/historico/IMPLEMENTATION_REPORT.md) for scope and reuse decisions.
+> Production delivery uses one Portainer stack; see [docs/PORTAINER.md](docs/PORTAINER.md).
 > Everything below is preserved historical prototype documentation, not the active
 > setup or delivery specification. Do not run its production integrations or agent.
 
@@ -14,6 +14,16 @@
 > a arquitetura, o código e o que ainda depende de resposta.
 > Base: conversas de 29 e 30/08/2026 com Marcus.
 
+
+> **2026-09-21.** Everything below this line is the original prototype
+> documentation. The code it describes (`portal/`, `kanban/`, `agente/`, the root
+> `schema.sql`, `.env.exemplo`) no longer exists, and the model it describes is
+> not the one implemented. Kept for the business reasoning in it — the capacity
+> figures, the cost argument, the meeting decisions. For how the system actually
+> works read [docs/CONTEXT.md](docs/CONTEXT.md); for what is outstanding read
+> [docs/ROADMAP.md](docs/ROADMAP.md); for the original documents see
+> [docs/historico/](docs/historico/README.md).
+
 ---
 
 ## Por que este projeto existe
@@ -418,7 +428,7 @@ depende de a pasta de rede funcionar.
 ```bash
 apt install -y python3.12-venv libvips-tools postgresql nginx certbot
 python3 -m venv /opt/dtf/venv && source /opt/dtf/venv/bin/activate
-pip install -r requirements.txt
+pip install fastapi uvicorn sqlmodel 'psycopg[binary]' boto3 httpx  # prototype only; no longer tracked
 cp .env.exemplo .env    # preencher
 cd portal && uvicorn main:app --host 0.0.0.0 --port 8000
 ```

agente/agente.py

@@ -1,141 +0,0 @@
-"""
-Agente da fábrica — traz a arte aprovada do portal para o servidor local.
-
-Roda como serviço:
-  Windows: nssm install DtfAgente "C:\\Python312\\python.exe" "C:\\dtf\\agente.py"
-  Linux:   systemd (ver dtf-agente.service no repositório)
-
-Duas fontes de trabalho:
-  - webhook do portal (chega na hora)
-  - polling a cada 60 s (rede de segurança se o webhook falhar)
-
-Se a internet cair, o agente para e o portal continua recebendo.
-Quando voltar, ele baixa o acumulado. Nada se perde.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import logging
-import os
-import sqlite3
-import time
-from datetime import datetime
-from pathlib import Path
-
-import httpx
-
-PORTAL = os.environ["BASE_PORTAL"]
-TOKEN = os.environ["AGENTE_TOKEN"]
-RAIZ = Path(os.environ.get("PASTA_DTF", r"\\servidor\DTF"))
-BANCO = Path(os.environ.get("KANBAN_DB", r"C:\dtf\kanban.db"))
-INTERVALO = 60
-HEARTBEAT = 300
-
-PASTA_ENTRADA = RAIZ / "00_ARTE_RECEBIDA"
-
-logging.basicConfig(
-    filename=RAIZ / "_log" / "agente.log",
-    level=logging.INFO,
-    format="%(asctime)s %(levelname)s %(message)s",
-)
-log = logging.getLogger("agente")
-
-
-def sha256(caminho: Path) -> str:
-    h = hashlib.sha256()
-    with open(caminho, "rb") as f:
-        for bloco in iter(lambda: f.read(1 << 20), b""):
-            h.update(bloco)
-    return h.hexdigest()
-
-
-def registrar_no_kanban(arte: dict, arquivos: list[Path]) -> None:
-    """Insere o card. Idempotente: a chave é o arte_id, não o nome do arquivo."""
-    con = sqlite3.connect(BANCO)
-    try:
-        con.execute("""
-            CREATE TABLE IF NOT EXISTS card(
-                arte_id INTEGER PRIMARY KEY,
-                pedido TEXT, cliente TEXT, metros REAL,
-                coluna TEXT DEFAULT 'rec', desde TEXT,
-                maquina TEXT, partes INTEGER
-            )""")
-        con.execute("""
-            INSERT OR IGNORE INTO card(arte_id,pedido,cliente,metros,desde,partes)
-            VALUES (?,?,?,?,?,?)""",
-            (arte["arte_id"], arte["pedido"], arte["cliente"],
-             arte["metros"], datetime.now().isoformat(timespec="seconds"),
-             len(arquivos)))
-        con.commit()
-    finally:
-        con.close()
-
-
-def baixar(cliente: httpx.Client, arte: dict) -> bool:
-    PASTA_ENTRADA.mkdir(parents=True, exist_ok=True)
-    salvos: list[Path] = []
-
-    for parte in arte["partes"]:
-        destino = PASTA_ENTRADA / f"{arte['pedido']}_{parte['nome']}"
-        if destino.exists():
-            salvos.append(destino)
-            continue
-        tmp = destino.with_suffix(".parcial")
-        with cliente.stream("GET", parte["url"]) as r:
-            r.raise_for_status()
-            with open(tmp, "wb") as f:
-                for bloco in r.iter_bytes(1 << 20):
-                    f.write(bloco)
-        tmp.rename(destino)          # só aparece na pasta quando está completo
-        salvos.append(destino)
-        log.info("baixado %s (%s) sha=%s", destino.name,
-                 f"{parte['metros']:.2f} m", sha256(destino)[:12])
-
-    registrar_no_kanban(arte, salvos)
-    cliente.post(f"{PORTAL}/api/artes/{arte['arte_id']}/baixada",
-                 headers={"x-token": TOKEN}, timeout=15)
-    return True
-
-
-def ciclo(cliente: httpx.Client) -> int:
-    r = cliente.get(f"{PORTAL}/api/artes", headers={"x-token": TOKEN}, timeout=30)
-    r.raise_for_status()
-    artes = r.json()
-    for arte in artes:
-        try:
-            baixar(cliente, arte)
-        except Exception as e:
-            log.error("falha na arte %s: %s", arte["arte_id"], e)
-    return len(artes)
-
-
-def main() -> None:
-    log.info("agente iniciado · portal=%s · pasta=%s", PORTAL, RAIZ)
-    ultimo_hb = 0.0
-    with httpx.Client(follow_redirects=True) as cliente:
-        while True:
-            try:
-                n = ciclo(cliente)
-                if n:
-                    log.info("%d arte(s) processada(s)", n)
-            except httpx.HTTPError as e:
-                # internet caiu: não é erro fatal, o portal segue recebendo
-                log.warning("sem conexão com o portal: %s", e)
-            except Exception as e:
-                log.exception("erro inesperado: %s", e)
-
-            agora = time.time()
-            if agora - ultimo_hb > HEARTBEAT:
-                try:
-                    cliente.post(f"{PORTAL}/api/agente/heartbeat",
-                                 headers={"x-token": TOKEN}, timeout=10)
-                    ultimo_hb = agora
-                except Exception:
-                    pass   # sem sinal por 15 min, o portal alerta o TI
-
-            time.sleep(INTERVALO)
-
-
-if __name__ == "__main__":
-    main()

agente/dtf-agente.service

@@ -1,14 +0,0 @@
-[Unit]
-Description=Agente DTF - baixa artes do portal
-After=network-online.target
-
-[Service]
-Type=simple
-User=dtf
-EnvironmentFile=/etc/dtf/.env
-ExecStart=/usr/bin/python3 /opt/dtf/agente.py
-Restart=always
-RestartSec=15
-
-[Install]
-WantedBy=multi-user.target

app/adapters.py

@@ -1,6 +1,9 @@
 """Local-only composition root. No production provider implementations/imports."""
+import hashlib
+import hmac
+import json
 import os
-from typing import Protocol
+from typing import Mapping, NamedTuple, Protocol
 from urllib.parse import urlparse
 import boto3
 from botocore.config import Config
@@ -14,9 +17,33 @@ def require_runtime():
     checkout until their audited implementations are added.
     """
     environment = os.environ.get('APP_ENV', 'local')
-    for name in ('PAYMENT', 'FREIGHT', 'TINY', 'WHATSAPP'):
-        if os.environ.get(f'{name}_ADAPTER') != 'fake':
-            raise RuntimeError(f'{name} must use the currently supported fake adapter')
+    if os.environ.get('WHATSAPP_ADAPTER') != 'fake':
+        raise RuntimeError('WHATSAPP must use the currently supported fake adapter')
+    freight = os.environ.get('FREIGHT_ADAPTER')
+    if freight == 'jadlog':
+        from .jadlog import required_settings as jadlog_settings
+        for name in jadlog_settings():
+            if not os.environ.get(name):
+                raise RuntimeError(f'{name} is required for the Jadlog adapter')
+    elif freight != 'fake':
+        raise RuntimeError('FREIGHT must use the fake or jadlog adapter')
+    tiny = os.environ.get('TINY_ADAPTER')
+    if tiny == 'tiny':
+        from .tiny import required_settings
+        for name in required_settings():
+            if not os.environ.get(name):
+                raise RuntimeError(f'{name} is required for the Tiny adapter')
+    elif tiny != 'fake':
+        raise RuntimeError('TINY must use the fake or tiny adapter')
+    # Mercado Pago is selectable only with its credentials present; it has not
+    # yet passed the sandbox flows, so production preflight still blocks it.
+    payment = os.environ.get('PAYMENT_ADAPTER')
+    if payment == 'mercadopago':
+        for name in ('MP_ACCESS_TOKEN', 'MP_WEBHOOK_SECRET'):
+            if not os.environ.get(name):
+                raise RuntimeError(f'{name} is required for the Mercado Pago adapter')
+    elif payment != 'fake':
+        raise RuntimeError('PAYMENT must use the fake or mercadopago adapter')
     if environment == 'local':
         if os.environ.get('STORAGE_ADAPTER') != 's3-local':
             raise RuntimeError('Local runtime requires local S3 storage')
@@ -41,19 +68,99 @@ def require_runtime():
 # Compatibility alias for local-only callers outside the active runtime.
 require_local = require_runtime
 
+class PaymentEvent(NamedTuple):
+    """One provider notification, normalised.
+
+    `event_id` identifies the delivery and makes it idempotent. `reference` is
+    our quote id, echoed back by the provider. `amount_cents` is what the
+    provider says was actually paid, which the service compares against the
+    approved total before it will create an order.
+    """
+    event_id: str
+    reference: str
+    status: str          # 'approved' | 'rejected' | 'pending' | 'refunded'
+    amount_cents: int | None
+    raw: dict
+
+
 class PaymentAdapter(Protocol):
-    def pay(self, quote_id: str, total_cents: int) -> dict: ...
+    def create(self, quote_id: str, total_cents: int, customer: dict, method: dict | None = None) -> dict:
+        """Start a payment. Must be idempotent on quote_id: a retry after a
+        timeout has to return the existing payment, never charge twice."""
+
+    def verify(self, headers: Mapping[str, str], body: bytes, query: Mapping[str, str] | None = None) -> bool:
+        """Whether this delivery genuinely came from the provider."""
+
+    def parse(self, body: bytes, query: Mapping[str, str] | None = None) -> PaymentEvent | None:
+        """Normalise a verified delivery, or None if it is not about a payment."""
+
 
 class FakePayment:
+    """Local stand-in with a real signature scheme, so the webhook path is
+    exercised end to end rather than waiting for a provider account.
+
+    Signs the body with HMAC-SHA256 under PAYMENT_WEBHOOK_SECRET. A real adapter
+    replaces verify() and parse() with the provider's own scheme; nothing else in
+    the service changes.
+    """
+
+    name = 'fake'
+    header = 'x-payment-signature'
+
+    def _secret(self) -> bytes | None:
+        secret = os.environ.get('PAYMENT_WEBHOOK_SECRET', '')
+        return secret.encode() if secret else None
+
+    def create(self, quote_id: str, total_cents: int, customer: dict, method: dict | None = None) -> dict:
+        kind = (method or {}).get('type', 'pix')
+        if kind == 'pix':
+            from datetime import datetime, timedelta, timezone
+            expires = (datetime.now(timezone.utc) + timedelta(minutes=30)).isoformat(timespec='milliseconds')
+            return {'provider': 'fake', 'id': f"local-{quote_id}-pix-{(method or {}).get('attempt', 1)}",
+                    'status': 'pending', 'total_cents': total_cents, 'expires_at': expires}
+        return {'provider': 'fake', 'id': f'local-{quote_id}-{kind}',
+                'status': 'pending', 'total_cents': total_cents}
+
+    def sign(self, body: bytes) -> str:
+        secret = self._secret()
+        if secret is None:
+            raise RuntimeError('PAYMENT_WEBHOOK_SECRET is not configured')
+        return hmac.new(secret, body, hashlib.sha256).hexdigest()
+
+    def verify(self, headers, body: bytes, query=None) -> bool:
+        # No configured secret means nothing can be verified, so nothing is
+        # accepted. A guessable default would let anyone forge an approval and
+        # create an order that was never paid for.
+        if self._secret() is None:
+            return False
+        supplied = headers.get(self.header) or headers.get(self.header.title()) or ''
+        return hmac.compare_digest(supplied, self.sign(body))
+
+    def parse(self, body: bytes, query=None):
+        try:
+            data = json.loads(body)
+        except ValueError:
+            return None
+        if not isinstance(data, dict) or 'event_id' not in data:
+            return None
+        return PaymentEvent(event_id=str(data['event_id']),
+                            reference=str(data.get('reference', '')),
+                            status=str(data.get('status', 'pending')),
+                            amount_cents=data.get('amount_cents'),
+                            raw=data)
+
+    # The local development checkout still needs a direct "it is paid" path.
     def pay(self, quote_id: str, total_cents: int) -> dict:
         return {'provider': 'fake', 'id': f'local-{quote_id}',
                 'status': 'paid', 'total_cents': total_cents}
 
 class FreightAdapter(Protocol):
-    def quote(self, service: str, postal_code: str) -> dict: ...
+    def quote(self, service: str, postal_code: str, metres=None, declared_cents: int = 0) -> dict: ...
 
 class FakeFreight:
-    def quote(self, service: str, postal_code: str) -> dict:
+    name = 'fake'
+
+    def quote(self, service: str, postal_code: str, metres=None, declared_cents: int = 0) -> dict:
         if service == 'pickup':
             return {'provider': 'fake', 'service': 'pickup', 'total_cents': 0, 'postal_code': ''}
         if service != 'mock-standard' or len(postal_code) != 8 or not postal_code.isascii() or not postal_code.isdigit():
@@ -84,6 +191,8 @@ class ObjectStorage(Protocol):
     def complete(self, key: str, upload_id: str, parts: list): ...
     def size(self, key: str) -> int: ...
     def download(self, key: str, name: str) -> str: ...
+    def fetch(self, key: str, path: str): ...
+    def store(self, key: str, path: str, content_type: str): ...
     def health(self): ...
     def discard(self, key: str, upload_id: str, complete: bool): ...
 
@@ -132,6 +241,14 @@ class LocalS3Storage:
     def size(self, key):
         return self.client.head_object(Bucket=self.bucket, Key=key)['ContentLength']
 
+    def fetch(self, key, path):
+        """Copy a stored object to a local file (the worker's scratch space)."""
+        self.client.download_file(self.bucket, key, path)
+
+    def store(self, key, path, content_type):
+        """Upload a file the service generated itself, such as a print file."""
+        self.client.upload_file(path, self.bucket, key, ExtraArgs={'ContentType': content_type})
+
     def download(self, key, name):
         from urllib.parse import quote
         return self.public.generate_presigned_url('get_object', Params={

app/api/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP routers, one per resource. They import from local.runtime, never
+from each other or from local.app."""

app/api/artwork.py

@@ -0,0 +1,53 @@
+"""Operator artwork handling: final files, and the uploads that carry them.
+
+These reuse the customer upload routes with the operator's derived identity, so
+one transport serves both and there is only one place where parts are signed.
+"""
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ..core import db
+from ..artwork import submit_files
+from ..core.auth import operator
+from ..core.models import ArtworkSubmission, UploadStart
+from ..runtime import file_rows, operator_identity
+from .uploads import begin_upload, cancel_upload, complete_upload, part_url, upload_status
+
+router = APIRouter()
+
+@router.post('/api/operator/orders/{oid}/uploads')
+def begin_final(oid: UUID, body: UploadStart, user=Depends(operator)):
+    with db.connect() as c:
+        row = c.execute('SELECT state FROM dtf_local.orders WHERE id=%s', (oid,)).fetchone()
+        if not row: raise HTTPException(404, 'Order not found')
+        if row['state'] not in ('rec','tra','cor'): raise HTTPException(409, 'Order is not in artwork review')
+    return begin_upload(body, session_id=operator_identity(user))
+
+@router.get('/api/operator/uploads/{uid}')
+def final_status(uid: UUID, user=Depends(operator)):
+    return upload_status(uid,session_id=operator_identity(user))
+
+@router.post('/api/operator/uploads/{uid}/parts/{number}')
+def final_part(uid: UUID, number: int, user=Depends(operator)):
+    return part_url(uid,number,session_id=operator_identity(user))
+
+@router.post('/api/operator/uploads/{uid}/complete')
+def final_complete(uid: UUID, user=Depends(operator)):
+    return complete_upload(uid,session_id=operator_identity(user))
+
+@router.delete('/api/operator/uploads/{uid}')
+def final_cancel(uid: UUID, user=Depends(operator)):
+    return cancel_upload(uid,session_id=operator_identity(user))
+
+@router.get('/api/operator/orders/{oid}/files')
+def operator_files(oid: UUID, user=Depends(operator)):
+    with db.connect() as c:
+        return file_rows(c,oid)
+
+@router.post('/api/operator/orders/{oid}/final-files')
+def final_files(oid: UUID, body: ArtworkSubmission, user=Depends(operator)):
+    with db.connect() as c:
+        order = c.execute('SELECT * FROM dtf_local.orders WHERE id=%s FOR UPDATE', (oid,)).fetchone()
+        if not order: raise HTTPException(404, 'Order not found')
+        return submit_files(c,order,body,operator_identity(user),'final',user)

app/api/customer.py

@@ -0,0 +1,224 @@
+"""Customer accounts, their orders, and the corrections they submit."""
+from datetime import datetime, timedelta, timezone
+from uuid import UUID, uuid4
+
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from psycopg.errors import UniqueViolation
+from psycopg.types.json import Jsonb
+
+from ..core import db
+from ..artwork import submit_files
+from ..core.auth import (DUMMY_PASSWORD_HASH, audit, client_ip, new_session, owner,
+                    login_failed, password_hash, password_matches, session_row, throttle, transfer_guest)
+from ..core.models import ArtworkSubmission, EmailChange, Login, PasswordChange, ProfileUpdate, Register
+from ..runtime import STATES, file_rows, owned_order, storage
+from ..scanning import require_clean
+
+router = APIRouter()
+
+
+def current(request):
+    try: return session_row(request)
+    except HTTPException: return None
+
+
+@router.post('/api/account/register')
+def register(body: Register, request: Request, response: Response):
+    email = body.customer.mail.strip().lower()
+    throttle(email, request)
+    # Registration attempts keep counting against the email, as before.
+    login_failed(email)
+    previous = current(request)
+    encoded = password_hash(body.password)
+    identity = uuid4()
+    profile = body.customer.model_dump()
+    profile['mail'] = email
+    try:
+        with db.connect() as c:
+            if previous and c.execute('SELECT id FROM dtf_local.accounts WHERE id=%s', (previous['owner'],)).fetchone():
+                raise HTTPException(409, 'Sign out before registering another account')
+            c.execute('INSERT INTO dtf_local.accounts(id,email,password_hash,profile) VALUES(%s,%s,%s,%s)', (identity,email,encoded,Jsonb(profile)))
+            if previous: transfer_guest(c, previous, identity)
+            new_session(c, response, identity)
+    except UniqueViolation:
+        raise HTTPException(409, 'An account already exists; sign in')
+    audit('account_registered', account=str(identity))
+    return {'customer': profile}
+
+@router.post('/api/account/login')
+def login(body: Login, request: Request, response: Response):
+    email = body.email.strip().lower()
+    throttle(email, request)
+    with db.connect() as c:
+        account = c.execute('SELECT * FROM dtf_local.accounts WHERE email=%s', (email,)).fetchone()
+    # Comparable password work even when the email is absent.
+    stored = account['password_hash'] if account else DUMMY_PASSWORD_HASH
+    matches = password_matches(body.password, stored)
+    if not account or not matches:
+        login_failed(email)
+        audit('customer_login_failed', ip=client_ip(request))
+        raise HTTPException(401, 'E-mail ou senha inválidos.')
+    previous = current(request)
+    with db.connect() as c:
+        if not stored.startswith('scrypt-v2$'):
+            c.execute('UPDATE dtf_local.accounts SET password_hash=%s WHERE id=%s', (password_hash(body.password),account['id']))
+        if previous:
+            transfer_guest(c, previous, account['id'])
+            c.execute('DELETE FROM dtf_local.sessions WHERE id=%s', (previous['id'],))
+        new_session(c, response, account['id'])
+    audit('customer_login_success', account=str(account['id']))
+    return {'customer': account['profile']}
+
+@router.post('/api/account/logout')
+def logout(request: Request, response: Response):
+    previous = current(request)
+    if previous:
+        with db.connect() as c:
+            c.execute('DELETE FROM dtf_local.sessions WHERE id=%s', (previous['id'],))
+    response.delete_cookie('dtf_session', httponly=True, samesite='strict')
+    response.headers['Clear-Site-Data'] = '"storage"'
+    audit('customer_logout')
+    return {'ok': True}
+
+@router.get('/api/account/me')
+def me(identity=Depends(owner)):
+    with db.connect() as c:
+        row = c.execute('SELECT profile FROM dtf_local.accounts WHERE id=%s', (identity,)).fetchone()
+    return {'customer': row['profile'] if row else None}
+
+def account_row(c, identity, lock=False):
+    row = c.execute('SELECT * FROM dtf_local.accounts WHERE id=%s' + (' FOR UPDATE' if lock else ''), (identity,)).fetchone()
+    if not row:
+        raise HTTPException(401, 'Entre na sua conta.')
+    return row
+
+@router.post('/api/account/profile')
+def update_profile(body: ProfileUpdate, identity=Depends(owner)):
+    """WhatsApp and the saved delivery address. The CNPJ is the account's and
+    does not change; the e-mail is the login and changes on its own route."""
+    with db.connect() as c:
+        row = account_row(c, identity, lock=True)
+        profile = {**row['profile'], 'zap': body.zap,
+                   'address': body.address.model_dump() if body.address else None}
+        c.execute('UPDATE dtf_local.accounts SET profile=%s WHERE id=%s', (Jsonb(profile), identity))
+    audit('account_profile_updated', account=str(identity))
+    return {'customer': profile}
+
+@router.post('/api/account/email')
+def change_email(body: EmailChange, request: Request, identity=Depends(owner)):
+    with db.connect() as c:
+        row = account_row(c, identity)
+    throttle(row['email'], request)
+    if not password_matches(body.password, row['password_hash']):
+        login_failed(row['email'])
+        raise HTTPException(401, 'Senha incorreta.')
+    profile = {**row['profile'], 'mail': body.email}
+    try:
+        with db.connect() as c:
+            c.execute('UPDATE dtf_local.accounts SET email=%s, profile=%s WHERE id=%s', (body.email, Jsonb(profile), identity))
+    except UniqueViolation:
+        raise HTTPException(409, 'Este e-mail já é de outra conta.')
+    audit('account_email_changed', account=str(identity))
+    return {'customer': profile}
+
+@router.post('/api/account/password')
+def change_password(body: PasswordChange, request: Request, identity=Depends(owner)):
+    with db.connect() as c:
+        row = account_row(c, identity)
+    throttle(row['email'], request)
+    if not password_matches(body.current, row['password_hash']):
+        login_failed(row['email'])
+        raise HTTPException(401, 'Senha atual incorreta.')
+    session = current(request)
+    with db.connect() as c:
+        c.execute('UPDATE dtf_local.accounts SET password_hash=%s WHERE id=%s', (password_hash(body.new), identity))
+        # Other devices signed in with the old password are signed out.
+        c.execute('DELETE FROM dtf_local.sessions WHERE owner=%s AND id<>%s', (identity, session['id']))
+    audit('account_password_changed', account=str(identity))
+    return {'ok': True}
+
+# The order list's groups, as the customer filters them.
+GROUPS = {'pay': 'Aguardando pagamento', 'prod': 'Em produção', 'cor': 'Correção', 'fin': 'Finalizados'}
+ENTRIES = '''WITH live_quote AS (
+    -- The cart waiting for payment: the newest unpaid quote whose files still
+    -- exist. An older one was replaced when the cart changed, and one whose
+    -- files are gone can no longer be paid.
+    SELECT q.id, q.created_at, q.approved FROM dtf_local.quotes q
+    LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+    WHERE q.owner=%(me)s AND o.id IS NULL
+      AND NOT EXISTS (SELECT 1 FROM jsonb_array_elements(q.draft->'items') i
+          CROSS JOIN LATERAL jsonb_array_elements_text(i->'uploads') u(uid)
+          JOIN dtf_local.uploads up ON up.id=u.uid::uuid
+          WHERE up.purged_at IS NOT NULL OR up.expires_at<=now())
+    ORDER BY q.created_at DESC LIMIT 1
+), entries AS (
+    SELECT 'order' AS kind, o.id, o.number, o.state,
+           CASE WHEN o.state='fin' THEN 'fin' WHEN o.state='cor' THEN 'cor' ELSE 'prod' END AS grp,
+           (o.snapshot->>'total_cents')::bigint AS total_cents, o.created_at, o.snapshot->'items' AS items
+    FROM dtf_local.orders o WHERE o.owner=%(me)s
+    UNION ALL
+    SELECT 'quote', q.id, NULL, CASE WHEN q.approved IS NULL THEN 'review' ELSE 'pay' END, 'pay',
+           (q.approved->>'total_cents')::bigint, q.created_at, COALESCE(q.approved->'items','[]'::jsonb)
+    FROM live_quote q
+)'''
+
+@router.get('/api/customer/orders')
+def orders(identity=Depends(owner), status: Literal['all','pay','prod','cor','fin'] = 'all',
+           number: int | None = Query(None, ge=1), days: int = Query(0, ge=0, le=3650),
+           page: int = Query(1, ge=1, le=10000), size: int = Query(10, ge=1, le=50)):
+    """The customer's orders and the cart waiting for payment, newest first,
+    filtered and a page at a time, with how many there are in each group."""
+    params = {'me': identity, 'grp': None if status == 'all' else status, 'number': number,
+              'since': datetime.now(timezone.utc) - timedelta(days=days) if days else None,
+              'size': size, 'offset': (page - 1) * size}
+    where = '''WHERE (%(grp)s::text IS NULL OR grp=%(grp)s) AND (%(number)s::int IS NULL OR number=%(number)s)
+               AND (%(since)s::timestamptz IS NULL OR created_at>=%(since)s)'''
+    with db.connect() as c:
+        counts = {r['grp']: r['n'] for r in c.execute(ENTRIES + ' SELECT grp, count(*) AS n FROM entries GROUP BY grp', params).fetchall()}
+        total = c.execute(ENTRIES + ' SELECT count(*) AS n FROM entries ' + where, params).fetchone()['n']
+        rows = c.execute(ENTRIES + ' SELECT * FROM entries ' + where +
+                         ' ORDER BY created_at DESC LIMIT %(size)s OFFSET %(offset)s', params).fetchall()
+        items = []
+        for r in rows:
+            entry = {'kind': r['kind'], 'id': r['id'], 'number': r['number'], 'state': r['state'],
+                     'group': r['grp'], 'total_cents': r['total_cents'], 'created_at': r['created_at'],
+                     'items': [{'mode': i['mode'], 'billed_metres': i.get('billed_metres')} for i in r['items']]}
+            if r['kind'] == 'quote':
+                # A PIX code still open is paid on its own page.
+                pix = c.execute('''SELECT 1 FROM dtf_local.payment_intents WHERE quote_id=%s AND method='pix'
+                    AND status='pending' AND COALESCE((response->>'expires_at')::timestamptz > now(), false)''',
+                                (r['id'],)).fetchone()
+                entry['pay_with'] = 'pix' if pix else 'page'
+            items.append(entry)
+    return {'items': items, 'total': total, 'page': page, 'size': size,
+            'counts': {g: counts.get(g, 0) for g in GROUPS}, 'groups': GROUPS, 'states': STATES}
+
+@router.get('/api/customer/orders/{oid}')
+def detail(oid: UUID, identity=Depends(owner)):
+    with db.connect() as c:
+        row = owned_order(c, oid, identity)
+        # A move back undoes an operator's mistake and its reason is internal;
+        # only a correction's reason is written for the customer.
+        history = c.execute('''SELECT from_state,to_state,CASE WHEN to_state='cor' THEN reason ELSE '' END AS reason,
+            created_at FROM dtf_local.movements WHERE order_id=%s AND NOT back ORDER BY id''', (oid,)).fetchall()
+        return {'id': row['id'], 'number': row['number'], 'state': row['state'], 'version': row['version'],
+                'created_at': row['created_at'], 'snapshot': row['snapshot'], 'history': history,
+                'files': file_rows(c,oid)}
+
+@router.post('/api/customer/orders/{oid}/corrections')
+def correction(oid: UUID, body: ArtworkSubmission, identity=Depends(owner)):
+    with db.connect() as c:
+        order = owned_order(c, oid, identity, lock=True)
+        return submit_files(c,order,body,identity,'correction','customer')
+
+@router.get('/api/customer/orders/{oid}/files/{fid}/download')
+def customer_download(oid: UUID, fid: UUID, identity=Depends(owner)):
+    with db.connect() as c:
+        owned_order(c,oid,identity)
+        row = c.execute('SELECT u.* FROM dtf_local.order_files f JOIN dtf_local.uploads u ON u.id=f.upload_id WHERE f.id=%s AND f.order_id=%s AND f.active', (fid,oid)).fetchone()
+        if not row: raise HTTPException(404, 'Active file not found')
+        if row['expires_at'] <= datetime.now(timezone.utc): raise HTTPException(410, 'File expired')
+        require_clean(row)
+    return {'url':storage.download(row['object_key'],row['name']), 'name':row['name']}

app/api/health.py

@@ -0,0 +1,72 @@
+"""Health, session bootstrap, freight quoting and the address of a CEP."""
+import os
+import re
+
+import httpx
+from fastapi import APIRouter, HTTPException, Request, Response
+
+from ..core import db
+from ..core.auth import client_ip, owner, new_session, rate_limit
+from ..core.limits import upload_limit_bytes
+from ..core.models import FreightEstimate
+from ..runtime import (ENVIRONMENT, GUEST_SESSION_LIMIT, PART_BYTES, freight, payment,
+                       require_delivery_available, storage)
+
+router = APIRouter()
+
+@router.get('/health')
+@router.get('/api/health')
+def health():
+    try:
+        with db.connect() as c:
+            c.execute('SELECT 1')
+        storage.health()
+    except Exception:
+        raise HTTPException(503, 'Database or storage unavailable')
+    return {'status': 'ok', 'environment': ENVIRONMENT,
+            'storage': 'minio' if ENVIRONMENT == 'local' else 'r2', 'integrations': 'fake'}
+
+@router.get('/api/session')
+def session(request: Request, response: Response):
+    try:
+        session_id = owner(request)
+    except HTTPException:
+        # Per source, not per deployment: keyed on the environment name this was a
+        # single global bucket, so ~8 new visitors a minute exhausted it site-wide.
+        rate_limit('guest-sessions', client_ip(request), GUEST_SESSION_LIMIT, 900)
+        with db.connect() as c:
+            session_id = new_session(c, response)
+    return {'environment': ENVIRONMENT, 'cart_scope': str(session_id), 'part_bytes': PART_BYTES,
+            'max_upload_bytes': upload_limit_bytes(), 'payment_provider': payment.name,
+            # Public by design: Mercado Pago's card form needs it in the browser.
+            'payment_public_key': os.environ.get('MP_PUBLIC_KEY', '') if payment.name == 'mercadopago' else '',
+            # The delivery service the cart quotes, or none: pickup only.
+            'freight_service': 'jadlog' if freight.name == 'jadlog' else 'mock-standard' if ENVIRONMENT == 'local' else None}
+
+@router.post('/api/freight')
+def quote_freight(body: FreightEstimate):
+    require_delivery_available(body.service)
+    try:
+        return freight.quote(body.service, body.postal_code, body.metres, body.declared_cents)
+    except ValueError as exc:
+        raise HTTPException(422, str(exc))
+
+# The address of a CEP, so the cart fills it in. Looked up here rather than in
+# the browser, which keeps the Site's CSP to its own origin.
+VIACEP = 'https://viacep.com.br/ws/{}/json/'
+CEP_LIMIT = 120
+
+@router.get('/api/cep/{cep}')
+def cep_address(cep: str, request: Request):
+    if not re.fullmatch(r'[0-9]{8}', cep):
+        raise HTTPException(422, 'CEP must have eight digits')
+    rate_limit('cep-lookup', client_ip(request), CEP_LIMIT, 900)
+    try:
+        response = httpx.get(VIACEP.format(cep), timeout=5)
+        data = response.json() if response.status_code == 200 else {}
+    except (httpx.HTTPError, ValueError):
+        raise HTTPException(503, 'Consulta de CEP indisponível')
+    if not data or data.get('erro'):
+        raise HTTPException(404, 'CEP não encontrado')
+    return {'street': data.get('logradouro') or '', 'district': data.get('bairro') or '',
+            'city': data.get('localidade') or '', 'state': data.get('uf') or ''}

app/api/operator.py

@@ -0,0 +1,393 @@
+"""Kanban: sign-in, the board, commercial review and card movement."""
+import hashlib
+import os
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Literal
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from fastapi.responses import RedirectResponse
+
+from ..core import db
+from ..core.auth import (COOKIE_SECURE, DUMMY_PASSWORD_HASH, audit, client_ip, operator,
+                    login_failed, password_matches, throttle)
+from ..core.models import Move, OperatorLogin, Resolution, Review
+from ..printjobs import queue as queue_print_files
+from .. import payments, quote_review
+from .. import tiny
+from ..runtime import (BACK, BOARD_FINISHED_LIMIT, BOARD_QUOTE_LIMIT, ENVIRONMENT, STATES, TRANSITIONS, payment,
+                       enqueue, freight, quote_view, storage)
+from ..scanning import require_clean
+
+router = APIRouter()
+
+@router.post('/api/operator/login')
+def operator_login(body: OperatorLogin, request: Request, response: Response):
+    email = body.email
+    throttle('operator:'+email, request)
+    with db.connect() as c:
+        account = c.execute('SELECT * FROM dtf_local.operators WHERE email=%s', (email,)).fetchone()
+        if not c.execute('SELECT 1 FROM dtf_local.operators WHERE active LIMIT 1').fetchone():
+            raise HTTPException(503, 'Nenhuma conta de operador configurada.')
+    # Comparable password work whether or not the account exists or is active.
+    stored = account['password_hash'] if account else DUMMY_PASSWORD_HASH
+    matches = password_matches(body.password, stored)
+    if not account or not account['active'] or not matches:
+        login_failed('operator:'+email)
+        audit('operator_login_failed', ip=client_ip(request), operator=email)
+        raise HTTPException(401, 'E-mail ou senha inválidos.')
+    token = secrets.token_urlsafe(32)
+    with db.connect() as c:
+        previous = hashlib.sha256(request.cookies.get('dtf_operator','').encode()).hexdigest()
+        c.execute('DELETE FROM dtf_local.operator_sessions WHERE token_hash=%s', (previous,))
+        c.execute('INSERT INTO dtf_local.operator_sessions(token_hash,username) VALUES(%s,%s)',
+                  (hashlib.sha256(token.encode()).hexdigest(), email))
+        c.execute('UPDATE dtf_local.operators SET last_login_at=now() WHERE id=%s', (account['id'],))
+    response.set_cookie('dtf_operator', token, httponly=True, secure=COOKIE_SECURE,
+                        samesite='strict', path='/api/operator', max_age=28800)
+    audit('operator_login_success', operator=email)
+    return {'ok': True}
+
+@router.post('/api/operator/logout')
+def operator_logout(request: Request, response: Response):
+    with db.connect() as c:
+        digest = hashlib.sha256(request.cookies.get('dtf_operator','').encode()).hexdigest()
+        c.execute('DELETE FROM dtf_local.operator_sessions WHERE token_hash=%s', (digest,))
+    response.delete_cookie('dtf_operator', path='/api/operator', httponly=True,
+                           secure=COOKIE_SECURE, samesite='strict')
+    audit('operator_logout')
+    return {'ok': True}
+
+def freight_status():
+    """What delivery the Site offers, and the package rule it prices with."""
+    if freight.name != 'jadlog':
+        return {'provider': freight.name}
+    return {'provider': 'jadlog', 'base_kg': str(freight.base_kg), 'per_metre_kg': str(freight.per_metre_kg),
+            'production_days': freight.production_days}
+
+
+def backup_status(c):
+    """The latest database backup and the latest run, which may have failed."""
+    ok = c.execute('''SELECT finished_at,bytes FROM dtf_local.backups WHERE status='ok'
+        ORDER BY finished_at DESC LIMIT 1''').fetchone()
+    last = c.execute('SELECT finished_at,status,detail FROM dtf_local.backups ORDER BY finished_at DESC LIMIT 1').fetchone()
+    return {'last_ok': ok['finished_at'].isoformat() if ok else None, 'bytes': ok['bytes'] if ok else None,
+            'failed': last['detail'] if last and last['status'] == 'failed' else None,
+            'failed_at': last['finished_at'].isoformat() if last and last['status'] == 'failed' else None}
+
+
+@router.get('/api/operator/board')
+def board(user=Depends(operator)):
+    with db.connect() as c:
+        # Everything still in progress, however old: an operator must never lose a
+        # card they can act on. Finished orders are terminal and only accumulate,
+        # so the board carries a recent window of them and reports the true total.
+        active = c.execute("SELECT * FROM dtf_local.orders WHERE state<>'fin' ORDER BY created_at").fetchall()
+        finished = c.execute("SELECT * FROM dtf_local.orders WHERE state='fin' ORDER BY created_at DESC LIMIT %s",
+                             (BOARD_FINISHED_LIMIT,)).fetchall()
+        finished_total = c.execute("SELECT count(*) AS n FROM dtf_local.orders WHERE state='fin'").fetchone()['n']
+        pending = c.execute('''SELECT q.* FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND q.approved IS NULL
+            ORDER BY q.created_at DESC,q.id DESC LIMIT %s''', (BOARD_QUOTE_LIMIT,)).fetchall()
+        approved = c.execute('''SELECT q.* FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND q.approved IS NOT NULL
+            ORDER BY q.created_at DESC,q.id DESC LIMIT 20''').fetchall()
+        pending_total = c.execute('''SELECT count(*) AS n FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND q.approved IS NULL''').fetchone()['n']
+        approved_total = c.execute('''SELECT count(*) AS n FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND q.approved IS NOT NULL''').fetchone()['n']
+        orders = with_print_files(c, active + list(reversed(finished)))
+        # A paid notification that did not become an order is money received
+        # for nothing the factory will make. The board carries the count; the
+        # Pagamentos tab pages through them until someone records a resolution.
+        issues_total = c.execute('''SELECT count(*) AS n FROM dtf_local.payment_events
+            WHERE (outcome LIKE 'refused%' OR outcome LIKE 'attention%') AND resolved_at IS NULL''').fetchone()['n']
+        backup = backup_status(c)
+        return {'states': STATES, 'transitions': TRANSITIONS, 'back': BACK,
+                'orders': orders, 'payment_issues_total': issues_total, 'tiny': tiny_status(), 'operator': user,
+                'providers': {'payment': payment.name, 'freight': freight_status(), 'backup': backup}, 'environment': ENVIRONMENT,
+                'finished_shown': len(finished), 'finished_total': finished_total,
+                'quotes': [quote_view(c, q) for q in pending + approved],
+                'pending_total': pending_total, 'approved_total': approved_total}
+
+
+def with_print_files(c, orders):
+    generated = c.execute('''SELECT p.order_id,p.item_index,p.status,p.upload_id,p.detail,u.name
+        FROM dtf_local.print_files p LEFT JOIN dtf_local.uploads u ON u.id=p.upload_id
+        WHERE p.order_id=ANY(%s) ORDER BY p.item_index''', ([o['id'] for o in orders],)).fetchall()
+    for order in orders:
+        order['print_files'] = [row for row in generated if row['order_id'] == order['id']]
+    return orders
+
+
+def cursor_pair(first, second):
+    if (first is None) != (second is None):
+        raise HTTPException(422, 'Both cursor fields are required')
+    return first is not None
+
+
+@router.get('/api/operator/orders/finished')
+def finished_page(before_created_at: datetime | None = None, before_id: UUID | None = None,
+                  limit: int = Query(default=50, ge=1, le=100), user=Depends(operator)):
+    """Older finished orders, newest first, beyond the board's recent window."""
+    paged = cursor_pair(before_created_at, before_id)
+    with db.connect() as c:
+        rows = c.execute('''SELECT * FROM dtf_local.orders WHERE state='fin'
+            ''' + ('AND (created_at,id)<(%s,%s) ' if paged else '') + '''
+            ORDER BY created_at DESC,id DESC LIMIT %s''',
+            ((before_created_at, before_id) if paged else ()) + (limit + 1,)).fetchall()
+        return {'orders': with_print_files(c, rows[:limit]), 'has_more': len(rows) > limit}
+
+
+@router.get('/api/operator/payment-events')
+def payment_events(state: Literal['open','resolved','all'] = 'open',
+                   offset: int = Query(default=0, ge=0),
+                   limit: int = Query(default=20, ge=1, le=100), user=Depends(operator)):
+    """Payments that needed a person, newest first: open ones to act on, resolved ones as history."""
+    where = {'open': 'AND resolved_at IS NULL', 'resolved': 'AND resolved_at IS NOT NULL', 'all': ''}[state]
+    with db.connect() as c:
+        rows = c.execute('''SELECT id,provider,event_id,reference,status,amount_cents,received_at,outcome,
+              resolved_at,resolved_by,resolution
+            FROM dtf_local.payment_events WHERE (outcome LIKE 'refused%%' OR outcome LIKE 'attention%%') ''' + where + '''
+            ORDER BY received_at DESC,id DESC LIMIT %s OFFSET %s''', (limit, offset)).fetchall()
+        total = c.execute('''SELECT count(*) AS n FROM dtf_local.payment_events
+            WHERE (outcome LIKE 'refused%' OR outcome LIKE 'attention%') ''' + where).fetchone()['n']
+        return {'issues': rows, 'total': total}
+
+
+@router.get('/api/operator/events')
+def events(provider: Literal['tiny','whatsapp'] | None = None,
+           status: Literal['delivered','queued','failing'] | None = None,
+           event: Literal['payment_approved','production_started','correction_needed','ready'] | None = None,
+           order: int | None = Query(default=None, ge=1), offset: int = Query(default=0, ge=0),
+           limit: int = Query(default=20, ge=1, le=100), user=Depends(operator)):
+    """The integration send log, newest first, filtered, by page with a total."""
+    clauses, params = [], []
+    if provider:
+        clauses.append('provider=%s'); params.append(provider)
+    if status == 'delivered':
+        clauses.append('delivered_at IS NOT NULL')
+    elif status == 'queued':
+        clauses.append('delivered_at IS NULL AND last_error IS NULL')
+    elif status == 'failing':
+        clauses.append('delivered_at IS NULL AND last_error IS NOT NULL')
+    if event:
+        clauses.append("payload->>'event'=%s"); params.append(event)
+    if order:
+        clauses.append("payload->>'number'=%s"); params.append(str(order))
+    where = ('WHERE ' + ' AND '.join(clauses)) if clauses else ''
+    with db.connect() as c:
+        rows = c.execute(f'SELECT * FROM dtf_local.outbox {where} ORDER BY id DESC LIMIT %s OFFSET %s',
+                         (*params, limit, offset)).fetchall()
+        total = c.execute(f'SELECT count(*) AS n FROM dtf_local.outbox {where}', params).fetchone()['n']
+        return {'events': rows, 'total': total}
+
+@router.get('/api/operator/quotes')
+def quote_page(kind: Literal['pending','approved'], before_created_at: datetime | None = None,
+               before_id: UUID | None = None, offset: int = Query(default=0, ge=0),
+               limit: int = Query(default=50, ge=1, le=100), user=Depends(operator)):
+    """Unpaid quotes, newest first: by cursor, or by page (offset) with a total."""
+    if (before_created_at is None) != (before_id is None):
+        raise HTTPException(422, 'Both quote cursor fields are required')
+    approved_filter = 'q.approved IS NULL' if kind == 'pending' else 'q.approved IS NOT NULL'
+    cursor = 'AND (q.created_at,q.id)<(%s,%s)' if before_created_at else ''
+    skip = 0 if before_created_at else offset
+    params = ((before_created_at,before_id) if before_created_at else ()) + (limit+1, skip)
+    with db.connect() as c:
+        rows = c.execute(f'''SELECT q.* FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND {approved_filter} {cursor}
+            ORDER BY q.created_at DESC,q.id DESC LIMIT %s OFFSET %s''', params).fetchall()
+        total = c.execute(f'''SELECT count(*) AS n FROM dtf_local.quotes q
+            LEFT JOIN dtf_local.orders o ON o.quote_id=q.id
+            WHERE o.id IS NULL AND {approved_filter}''').fetchone()['n']
+        return {'quotes':[quote_view(c,row) for row in rows[:limit]],
+                'has_more':len(rows)>limit, 'total': total}
+
+@router.post('/api/operator/quotes/{uid}/approve')
+def approve(uid: UUID, body: Review, user=Depends(operator)):
+    with db.connect() as c:
+        row = c.execute('SELECT * FROM dtf_local.quotes WHERE id=%s FOR UPDATE', (uid,)).fetchone()
+        if not row:
+            raise HTTPException(404, 'Quote not found')
+        return quote_review.approve(c, row, body.items, user)
+
+@router.post('/api/operator/quotes/{uid}/test-order')
+def test_order(uid: UUID, user=Depends(operator)):
+    """An order for an approved quote without payment, to try the Kanban,
+    files and print flow in production. Marked TEST on the board, never sent
+    to Tiny or WhatsApp, and audited."""
+    with db.connect() as c:
+        try:
+            quote = payments.approved_quote(c, uid)
+        except payments.PaymentRefused as refusal:
+            raise HTTPException(404 if 'not found' in str(refusal) else 409, str(refusal))
+        receipt = {'provider': payments.TEST_PROVIDER, 'id': f'teste-{uid}', 'status': 'paid',
+                   'total_cents': quote['approved']['total_cents'], 'operator': user}
+        order, created = payments.create_order(c, quote, receipt)
+    if created:
+        audit('test_order_created', order=str(order['id']), operator=user)
+    return order
+
+
+@router.post('/api/operator/orders/{uid}/move')
+def move(uid: UUID, body: Move, user=Depends(operator)):
+    with db.connect() as c:
+        row = c.execute('SELECT * FROM dtf_local.orders WHERE id=%s FOR UPDATE', (uid,)).fetchone()
+        if not row:
+            raise HTTPException(404, 'Order not found')
+        if body.version != row['version']:
+            raise HTTPException(409, 'O pedido mudou. Clique em Atualizar.')
+        if body.state == row['state']:
+            return row
+        back = BACK.get(row['state']) == body.state
+        if body.state not in TRANSITIONS[row['state']] and not back:
+            raise HTTPException(409, f"Não dá para ir de {STATES[row['state']]} para {STATES[body.state]}.")
+        if body.state == 'cor' and not body.reason.strip():
+            raise HTTPException(422, 'Informe o motivo da correção.')
+        if back and not body.reason.strip():
+            raise HTTPException(422, 'Informe por que o pedido está voltando de etapa.')
+        if body.state in ('fil','imp'):
+            coverage = c.execute('SELECT DISTINCT f.item_index FROM dtf_local.order_files f JOIN dtf_local.uploads u ON u.id=f.upload_id WHERE f.order_id=%s AND f.kind=\'final\' AND f.active AND u.expires_at>now() AND u.purged_at IS NULL AND u.scan_state=\'clean\'', (uid,)).fetchall()
+            if {r['item_index'] for r in coverage} != set(range(len(row['snapshot']['items']))):
+                raise HTTPException(409, 'Aprove os arquivos finais de todos os itens antes de colocar na fila.')
+        if body.state == 'cor':
+            c.execute("UPDATE dtf_local.order_files SET active=false WHERE order_id=%s AND kind='final'", (uid,))
+        c.execute('INSERT INTO dtf_local.movements(order_id,from_state,to_state,operator,reason,back) VALUES(%s,%s,%s,%s,%s,%s)',
+                  (uid,row['state'],body.state,user,body.reason,back))
+        changed = c.execute('UPDATE dtf_local.orders SET state=%s, version=version+1, updated_at=now() WHERE id=%s RETURNING *', (body.state,uid)).fetchone()
+        events = {'imp':'production_started','cor':'correction_needed','fin':'ready'}
+        if body.state in events and not back and not payments.is_test(row):
+            # "Production started" and "ready" reach the customer once per order,
+            # even if a mistaken move is undone and made again. Each correction
+            # is a new request, so it keeps one message per movement.
+            once = body.state in ('imp','fin')
+            event = {'order_id':str(uid), 'number':row['number'], 'event':events[body.state], 'reason':body.reason,
+                     'customer_path': f'/portal.html?order={uid}'}
+            # Tiny needs the order (customer, pickup or delivery) and, once the
+            # sale reached it, its id, to set the situação without a search.
+            sale = c.execute("SELECT receipt FROM dtf_local.outbox WHERE event_key=%s AND delivered_at IS NOT NULL",
+                             (f'{uid}:paid:tiny',)).fetchone()
+            tiny = {**event, 'order': row['snapshot'], 'tiny_id': ((sale or {}).get('receipt') or {}).get('tiny_id')}
+            for provider, payload in (('tiny', tiny), ('whatsapp', event)):
+                key = f'{uid}:{events[body.state]}:{provider}' if once else f'{uid}:{changed["version"]}:{provider}'
+                enqueue(c, key, provider, payload)
+    return changed
+
+@router.post('/api/operator/orders/{uid}/print-files')
+def regenerate(uid: UUID, user=Depends(operator)):
+    """Queue generation again for items that failed or went to manual preparation,
+    and for orders paid before the generator existed."""
+    with db.connect() as c:
+        row = c.execute('SELECT id,snapshot,state FROM dtf_local.orders WHERE id=%s FOR UPDATE', (uid,)).fetchone()
+        if not row:
+            raise HTTPException(404, 'Order not found')
+        if row['state'] not in ('rec','tra'):
+            raise HTTPException(409, 'Print files are generated only before the order is queued')
+        if c.execute("SELECT 1 FROM dtf_local.order_files WHERE order_id=%s AND kind='correction' LIMIT 1", (uid,)).fetchone():
+            raise HTTPException(409, 'A customer correction replaced the original artwork; prepare the final file by hand')
+        queue_print_files(c, uid, len(row['snapshot']['items']), only_missing=True)
+        audit('print_file_requeued', order=str(uid), operator=user)
+        return c.execute('SELECT * FROM dtf_local.print_files WHERE order_id=%s ORDER BY item_index', (uid,)).fetchall()
+
+@router.post('/api/operator/payment-events/{uid}/resolve')
+def resolve_payment(uid: UUID, body: Resolution, user=Depends(operator)):
+    with db.connect() as c:
+        row = c.execute('''UPDATE dtf_local.payment_events SET resolved_at=now(), resolved_by=%s, resolution=%s
+            WHERE id=%s AND (outcome LIKE 'refused%%' OR outcome LIKE 'attention%%') AND resolved_at IS NULL RETURNING id''',
+            (user, body.note, uid)).fetchone()
+        if not row:
+            raise HTTPException(404, 'No open payment issue with this id')
+    audit('payment_issue_resolved', payment_event=str(uid), operator=user)
+    return {'ok': True}
+
+def tiny_status():
+    if not tiny.configured():
+        return {'configured': False}
+    return {'configured': True, 'orders_enabled': os.environ.get('TINY_ADAPTER') == 'tiny',
+            **tiny.TinyAuth().status()}
+
+@router.post('/api/operator/tiny/connect')
+def tiny_connect(user=Depends(operator)):
+    """Start the one-time authorisation of this system in the client's Tiny."""
+    if not tiny.configured():
+        raise HTTPException(503, 'Tiny application is not configured')
+    audit('tiny_connect_started', operator=user)
+    return {'url': tiny.TinyAuth().authorize_url(user)}
+
+@router.post('/api/operator/tiny/test')
+def tiny_test(user=Depends(operator)):
+    """Read one order and one contact from Tiny. Creates nothing."""
+    if not tiny.configured():
+        raise HTTPException(503, 'Tiny application is not configured')
+    try:
+        results = tiny.check()
+    except tiny.TinyNotConnected as exc:
+        raise HTTPException(409, str(exc))
+    audit('tiny_tested', operator=user, ok=all(v == 'ok' for v in results.values()))
+    return {'ok': all(v == 'ok' for v in results.values()), 'results': results}
+
+@router.post('/api/operator/mercadopago/check')
+def mercadopago_check(user=Depends(operator)):
+    """The Mercado Pago account behind the configured token; reads only."""
+    if payment.name != 'mercadopago':
+        raise HTTPException(409, 'Mercado Pago não está configurado')
+    from ..mercadopago_probe import check
+    audit('mercadopago_check', operator=user)
+    result = check(payment.access_token)
+    # Whether Mercado Pago's notifications reach this server and pass the
+    # signature: every accepted one is recorded, a refused one is audited.
+    with db.connect() as c:
+        received = c.execute('''SELECT count(*) AS n, max(received_at) AS last FROM dtf_local.payment_events
+            WHERE provider='mercadopago' AND received_at > now()-interval '24 hours' ''').fetchone()
+        last = c.execute('''SELECT received_at,status,outcome FROM dtf_local.payment_events
+            WHERE provider='mercadopago' ORDER BY received_at DESC LIMIT 1''').fetchone()
+        refused = c.execute('''SELECT count(*) AS n FROM dtf_local.security_events
+            WHERE event='payment_webhook_rejected' AND created_at > now()-interval '24 hours' ''').fetchone()
+    result['webhooks'] = {'accepted_24h': received['n'], 'refused_24h': refused['n'], 'last': last}
+    return result
+
+
+@router.get('/api/operator/tiny/callback')
+def tiny_callback(code: str = Query('', max_length=4096), state: str = Query('', max_length=128),
+                  error: str = Query('', max_length=128)):
+    """Tiny's redirect back. Cross-site, so the operator cookie is absent: the
+    single-use state an operator created is what authorises it. Tiny reports a
+    refusal (the operator declined, or offline access is not allowed for this
+    application) with `error` instead of a code."""
+    if not tiny.configured():
+        raise HTTPException(503, 'Tiny application is not configured')
+    try:
+        if error == 'invalid_scope':
+            retry = tiny.TinyAuth().without_offline(state)
+            audit('tiny_offline_refused')
+            return RedirectResponse(retry, status_code=303)
+        if error or not code:
+            raise tiny.TinyError(f'Tiny returned {error or "no code"}')
+        who = tiny.TinyAuth().complete(code, state)
+    except tiny.TinyError:
+        audit('tiny_connect_failed')
+        return RedirectResponse('/?tiny=failed', status_code=303)
+    audit('tiny_connected', operator=who)
+    return RedirectResponse('/?tiny=connected', status_code=303)
+
+@router.get('/api/operator/orders/{uid}/history')
+def history(uid: UUID, user=Depends(operator)):
+    with db.connect() as c:
+        return c.execute('SELECT * FROM dtf_local.movements WHERE order_id=%s ORDER BY id', (uid,)).fetchall()
+
+@router.get('/api/operator/uploads/{uid}/download')
+def download(uid: UUID, user=Depends(operator)):
+    with db.connect() as c:
+        row = c.execute('SELECT * FROM dtf_local.uploads WHERE id=%s AND complete', (uid,)).fetchone()
+        if not row:
+            raise HTTPException(404, 'Completed upload not found')
+        if row['expires_at'] <= datetime.now(timezone.utc):
+            raise HTTPException(410, 'Artwork retention expired')
+        require_clean(row)
+    return {'name':row['name'], 'url':storage.download(row['object_key'],row['name']), 'expires_in':300}

app/api/orders.py

@@ -0,0 +1,38 @@
+"""Local development checkout.
+
+The real path is the provider webhook. This exists so the local stack can reach
+a paid order without a provider account, and it goes through the same service so
+the two cannot drift apart.
+"""
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from .. import payments
+from ..core import db
+from ..core.auth import owner
+from ..core.models import Pay
+from ..runtime import ENVIRONMENT, payment
+
+router = APIRouter()
+
+
+@router.post('/api/orders/dev-paid')
+def dev_paid(body: Pay, session_id=Depends(owner)):
+    if ENVIRONMENT != 'local':
+        raise HTTPException(503, 'Checkout is not configured yet')
+    with db.connect() as c:
+        try:
+            quote = payments.approved_quote(c, body.quote_id, session_id)
+        except payments.PaymentRefused as refusal:
+            # The quote may already be paid; that is not a refusal.
+            existing = c.execute('SELECT * FROM dtf_local.orders WHERE quote_id=%s AND owner=%s',
+                                 (body.quote_id, session_id)).fetchone()
+            if existing:
+                return existing
+            raise HTTPException(404 if 'not found' in str(refusal) else 409, str(refusal))
+        # The charge happens inside the transaction that persists the order, so a
+        # failure to record it cannot leave a customer charged without an order.
+        receipt = payment.pay(str(body.quote_id), quote['approved']['total_cents'])
+        order, _ = payments.create_order(c, quote, receipt)
+    return order

app/api/payments.py

@@ -0,0 +1,147 @@
+"""The provider's callback.
+
+Unauthenticated by necessity — a payment provider has no session — so the
+signature is the only thing standing between this endpoint and an attacker
+creating orders. It is verified before the body is parsed, let alone acted on,
+and an unverified delivery is recorded and refused rather than retried.
+"""
+from uuid import uuid4
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request
+from psycopg.types.json import Jsonb
+
+from .. import payments
+from ..core import db
+from ..core.auth import audit, client_ip, owner, rate_limit
+from ..core.models import PaymentIntent
+from ..runtime import payment
+
+router = APIRouter()
+
+# Generous: a provider legitimately retries, and a signature check is cheap.
+# This exists so an unsigned flood cannot keep the database busy.
+WEBHOOK_LIMIT = 600
+# How long a card waiting for the bank's confirmation holds off a new attempt.
+CHALLENGE_MINUTES = 10
+
+
+@router.post('/api/payments/webhook')
+async def webhook(request: Request):
+    rate_limit('payment-webhook', client_ip(request), WEBHOOK_LIMIT, 900)
+    body = await request.body()
+
+    query = dict(request.query_params)
+    if not payment.verify(request.headers, body, query):
+        audit('payment_webhook_rejected', ip=client_ip(request), reason='signature')
+        raise HTTPException(403, 'Invalid signature')
+
+    event = payment.parse(body, query)
+    if event is None:
+        # Verified, so genuinely from the provider, but not about a payment.
+        # Acknowledge it: refusing would make the provider retry for ever.
+        return {'status': 'ignored'}
+
+    with db.connect() as c:
+        stored = payments.record(c, event_provider(), event)
+        if stored is None:
+            # Already delivered. Acknowledge without acting again.
+            return {'status': 'duplicate'}
+        outcome = payments.apply(c, event)
+        c.execute('UPDATE dtf_local.payment_events SET processed_at=now(), outcome=%s WHERE id=%s',
+                  (outcome, stored['id']))
+
+    # audit()'s own first parameter is named `event`, so the id goes under another key.
+    audit('payment_webhook_applied', payment_event=event.event_id,
+          status=event.status, outcome=outcome)
+    return {'status': 'applied', 'outcome': outcome}
+
+
+def event_provider():
+    return payment.name
+
+
+def provider_reason(response):
+    """A short, loggable reason from a refused provider call."""
+    try:
+        data = response.json()
+    except ValueError:
+        return f'HTTP {response.status_code}'
+    causes = '; '.join(f"{c.get('code')}: {c.get('description')}" for c in data.get('cause') or []
+                       if isinstance(c, dict))
+    return (causes or data.get('message') or data.get('error') or f'HTTP {response.status_code}')[:300]
+
+
+@router.post('/api/payments/intent')
+def intent(body: PaymentIntent, session_id=Depends(owner)):
+    """Start paying an approved quote: a PIX code, or a card token from the
+    provider's own form. Asking twice for the same method returns the same
+    payment; a quote already paid returns 409."""
+    rate_limit('payment-intent', str(session_id), 30, 900)
+    with db.connect() as c:
+        try:
+            quote = payments.approved_quote(c, body.quote_id, session_id)
+        except payments.PaymentRefused as refusal:
+            raise HTTPException(404 if 'not found' in str(refusal) else 409, str(refusal))
+        if c.execute('SELECT 1 FROM dtf_local.orders WHERE quote_id=%s', (body.quote_id,)).fetchone():
+            raise HTTPException(409, 'Quote is already paid')
+        # Never charge for files that are gone: an unpaid cart's files are
+        # removed after a while. A payment under way keeps them a day longer,
+        # time enough for the provider's notice to become the order.
+        uploads = payments.quote_uploads(quote['approved'])
+        live = c.execute('''SELECT count(*) AS n FROM dtf_local.uploads WHERE id=ANY(%s)
+            AND purged_at IS NULL AND expires_at>now()''', (uploads,)).fetchone()['n']
+        if live != len(set(uploads)):
+            raise HTTPException(410, 'Os arquivos deste pedido expiraram porque ele não foi pago a tempo. '
+                                     'Monte o pedido de novo para pagar.')
+        payments.hold_uploads(c, uploads, '1 day')
+        # Never a second charge: an approved payment is waiting for its
+        # notification to become the order, and a card in review may still be.
+        # A card waiting for the bank's confirmation (3-D Secure) blocks only
+        # for CHALLENGE_MINUTES: a customer who gave up on it must still be able
+        # to pay, and an unanswered challenge is not charged.
+        if c.execute('''SELECT 1 FROM dtf_local.payment_intents WHERE quote_id=%s
+            AND (status='approved' OR (method='card' AND status='pending'
+                 AND NOT (jsonb_typeof(response->'challenge')='object'
+                          AND created_at < now() - make_interval(mins => %s))))''',
+                     (body.quote_id, CHALLENGE_MINUTES)).fetchone():
+            raise HTTPException(409, 'A payment for this quote is already approved or in review')
+        method = body.method.model_dump()
+        if body.method.type == 'pix':
+            # One open PIX per quote: the same code until it expires, and a new
+            # one only after that, when the old code can no longer be paid.
+            # Serialised per quote, so two clicks never open two codes.
+            c.execute('SELECT pg_advisory_xact_lock(hashtext(%s))', ('pix:'+str(body.quote_id),))
+            existing = c.execute('''SELECT *, COALESCE((response->>'expires_at')::timestamptz <= now(), false) AS expired
+                FROM dtf_local.payment_intents WHERE quote_id=%s AND method='pix'
+                AND status='pending' ORDER BY created_at DESC LIMIT 1''', (body.quote_id,)).fetchone()
+            if existing and not existing['expired']:
+                return existing['response']
+            if existing:
+                c.execute("UPDATE dtf_local.payment_intents SET status='expired', updated_at=now() WHERE id=%s",
+                          (existing['id'],))
+            method['attempt'] = c.execute('''SELECT count(*) AS n FROM dtf_local.payment_intents
+                WHERE quote_id=%s AND method='pix' ''', (body.quote_id,)).fetchone()['n'] + 1
+        try:
+            created = payment.create(str(body.quote_id), quote['approved']['total_cents'],
+                                     quote['approved']['customer'], method)
+        except ValueError as exc:
+            raise HTTPException(422, str(exc))
+        except httpx.HTTPStatusError as exc:
+            # Mercado Pago's own reason (status, message and cause codes) goes to
+            # the log; it never contains card data, only what was refused.
+            reason = provider_reason(exc.response)
+            audit('payment_intent_refused', quote=str(body.quote_id), method=body.method.type,
+                  status=exc.response.status_code, reason=reason)
+            if exc.response.status_code < 500:
+                raise HTTPException(422, f'O Mercado Pago recusou o pagamento: {reason}')
+            raise HTTPException(502, 'Payment provider unavailable; try again')
+        except Exception as exc:
+            audit('payment_intent_failed', quote=str(body.quote_id), error=type(exc).__name__)
+            raise HTTPException(502, 'Payment provider unavailable; try again')
+        c.execute('''INSERT INTO dtf_local.payment_intents(id,quote_id,provider,provider_payment_id,method,
+              status,amount_cents,response) VALUES(%s,%s,%s,%s,%s,%s,%s,%s)
+            ON CONFLICT(provider,provider_payment_id) DO NOTHING''',
+                  (uuid4(), body.quote_id, payment.name, created['id'], body.method.type,
+                   created['status'], quote['approved']['total_cents'], Jsonb(created)))
+    return created

app/api/quotes.py

@@ -0,0 +1,72 @@
+"""Quotes: the customer's cart, approved at once when it can be (app/quote_review.py)."""
+import hashlib
+import json
+from decimal import Decimal
+from uuid import UUID, uuid4
+
+from fastapi import APIRouter, Depends, HTTPException
+from psycopg.types.json import Jsonb
+
+from .. import payments
+from ..core import db
+from ..core.auth import owner
+from ..core.models import QuoteRequest
+from ..core.pricing import price
+from .. import quote_review
+from ..grade_check import Files, mismatch
+from ..runtime import freight, quote_view, require_delivery_available, storage, upload_row
+from ..scanning import require_clean
+
+router = APIRouter()
+
+@router.post('/api/quotes')
+def create_quote(body: QuoteRequest, session_id=Depends(owner)):
+    for item in body.items:
+        if abs(item.metres*100-item.production.height_cm) > Decimal('0.02'):
+            raise HTTPException(422, 'Quoted metres do not match the submitted layout height')
+    require_delivery_available(body.freight.service)
+    draft = body.model_dump(mode='json', exclude={'request_key'})
+    digest = hashlib.sha256(json.dumps(draft, sort_keys=True).encode()).hexdigest()
+    reason = quote_review.review_reason(draft)
+    if reason is not None:
+        # Waits for review: check the delivery now, priced at approval.
+        try:
+            priced = [price(item.mode, str(item.metres), item.grade) for item in body.items]
+            freight.quote(body.freight.service, body.freight.postal_code,
+                          sum(Decimal(i['billed_metres']) for i in priced), sum(i['total_cents'] for i in priced))
+        except ValueError as exc:
+            raise HTTPException(422, str(exc))
+    with db.connect() as c:
+        rows = {}
+        for item in body.items:
+            for uid in item.uploads:
+                row = upload_row(c, uid, session_id)
+                if not row['complete']:
+                    raise HTTPException(409, 'Complete every upload before requesting a quote')
+                require_clean(row)
+                rows[str(uid)] = row
+        # The grade sets the price and came from the browser: before a cart is
+        # approved at checkout, the server works it out from the files.
+        note = mismatch(Files(storage), draft['items'], rows) if reason is None else None
+        reason = reason or note
+        uid = uuid4()
+        c.execute('INSERT INTO dtf_local.quotes(id,owner,request_key,request_hash,draft,review_note) VALUES(%s,%s,%s,%s,%s,%s) ON CONFLICT(owner,request_key) DO NOTHING',
+                  (uid, session_id, body.request_key, digest, Jsonb(draft), note))
+        row = c.execute('SELECT * FROM dtf_local.quotes WHERE owner=%s AND request_key=%s FOR UPDATE', (session_id, body.request_key)).fetchone()
+        if row['request_hash'] != digest:
+            raise HTTPException(409, 'Request key already used for a different cart')
+        if row['id'] == uid and reason is None:
+            quote_review.approve(c, row, body.items, quote_review.AUTO)
+            return {'id': row['id'], 'status': 'approved'}
+        if row['id'] == uid:
+            # An operator reviews it first; the files wait for that review.
+            payments.hold_uploads(c, payments.quote_uploads(draft), payments.REVIEW_HOLD)
+    return {'id': row['id'], 'status': 'approved' if row['approved'] else 'pending_review'}
+
+@router.get('/api/quotes/{uid}')
+def get_quote(uid: UUID, session_id=Depends(owner)):
+    with db.connect() as c:
+        row = c.execute('SELECT * FROM dtf_local.quotes WHERE id=%s AND owner=%s', (uid,session_id)).fetchone()
+        if not row:
+            raise HTTPException(404, 'Quote not found')
+        return quote_view(c, row)

app/api/uploads.py

@@ -0,0 +1,106 @@
+"""Customer uploads: reservation, signed parts, completion.
+
+The operator artwork routes reuse these functions directly with a different
+identity, which is why they are plain functions with a session_id argument.
+"""
+import math
+import os
+from uuid import UUID, uuid4
+
+from botocore.exceptions import ClientError
+from fastapi import APIRouter, Depends, HTTPException
+
+from ..core import db
+from ..core.auth import audit, owner, rate_limit
+from ..core.limits import upload_limit_bytes
+from ..core.models import UploadStart
+from ..payments import UNPAID_HOLD
+from ..runtime import PART_BYTES, storage, upload_row
+
+router = APIRouter()
+
+@router.post('/api/uploads')
+def begin_upload(body: UploadStart, session_id=Depends(owner)):
+    if body.size > upload_limit_bytes():
+        raise HTTPException(413, 'File exceeds the malware scan limit; select a smaller file')
+    uid = uuid4()
+    key = f'originals/{uid}'
+    rate_limit('upload-start', str(session_id), 60, 900)
+    with db.connect() as c:
+        # Serialize reservations across API processes, including changing guest IDs.
+        c.execute('SELECT pg_advisory_xact_lock(804208)')
+        usage = c.execute('''SELECT COALESCE(sum(size),0) AS total,
+            COALESCE(sum(size) FILTER(WHERE owner=%s),0) AS owned,
+            count(*) FILTER(WHERE owner=%s AND NOT complete) AS pending
+            FROM dtf_local.uploads WHERE purged_at IS NULL''',
+            (session_id,session_id)).fetchone()
+        if (usage['total']+body.size > int(os.environ.get('STORAGE_QUOTA_BYTES','53687091200')) or
+            usage['owned']+body.size > int(os.environ.get('OWNER_UPLOAD_QUOTA_BYTES','10737418240')) or
+            usage['pending'] >= int(os.environ.get('MAX_PENDING_UPLOADS','10'))):
+            audit('upload_quota_rejected')
+            raise HTTPException(429, 'Limite de armazenamento ou de envios pendentes atingido. Tente de novo mais tarde.')
+        multipart = storage.begin(key)
+        c.execute('''INSERT INTO dtf_local.uploads(id,owner,name,size,object_key,multipart_id,expires_at)
+            VALUES(%s,%s,%s,%s,%s,%s,now()+interval '1 hour')''',
+                  (uid, session_id, body.name, body.size, key, multipart))
+    return {'id': uid, 'part_bytes': PART_BYTES}
+
+@router.get('/api/uploads/{uid}')
+def upload_status(uid: UUID, session_id=Depends(owner)):
+    with db.connect() as c:
+        row = upload_row(c, uid, session_id)
+    parts = [] if row['complete'] else storage.parts(row['object_key'], row['multipart_id'])
+    return {'id': uid, 'complete': row['complete'], 'part_bytes': PART_BYTES,
+            'scan_state':row['scan_state'], 'scan_reason':row['scan_reason'],
+            'parts': [p['PartNumber'] for p in parts]}
+
+@router.post('/api/uploads/{uid}/parts/{part}')
+def part_url(uid: UUID, part: int, session_id=Depends(owner)):
+    with db.connect() as c:
+        row = upload_row(c, uid, session_id)
+        if row['complete'] or not 1 <= part <= math.ceil(row['size'] / PART_BYTES):
+            raise HTTPException(409, 'Invalid part or completed upload')
+        # The reservation lease is an hour; a multi-GB upload on a slow line
+        # takes longer, so each part it asks for keeps it alive.
+        c.execute("UPDATE dtf_local.uploads SET expires_at=GREATEST(expires_at,now()+interval '1 hour') WHERE id=%s", (uid,))
+    size = min(PART_BYTES, row['size']-(part-1)*PART_BYTES)
+    return {'url': storage.part_url(row['object_key'], row['multipart_id'], part, size)}
+
+@router.post('/api/uploads/{uid}/complete')
+def complete_upload(uid: UUID, session_id=Depends(owner)):
+    with db.connect() as c:
+        row = upload_row(c, uid, session_id, lock=True)
+        if row['complete']:
+            return {'id': uid, 'complete': True}
+        try:
+            existing_size = storage.size(row['object_key'])
+        except ClientError as exc:
+            if exc.response['ResponseMetadata']['HTTPStatusCode'] != 404:
+                raise
+            existing_size = None
+        if existing_size is None:
+            parts = storage.parts(row['object_key'], row['multipart_id'])
+            expected = math.ceil(row['size'] / PART_BYTES)
+            if [p['PartNumber'] for p in parts] != list(range(1, expected+1)) or any(
+                p['Size'] != min(PART_BYTES, row['size'] - i*PART_BYTES) for i,p in enumerate(parts)):
+                raise HTTPException(409, 'Parts are missing or their sizes do not match')
+            storage.complete(row['object_key'], row['multipart_id'], parts)
+            existing_size = storage.size(row['object_key'])
+        if existing_size != row['size']:
+            raise HTTPException(409, 'Stored size differs from declared size')
+        # Held while the cart is unpaid: an abandoned cart's files go after
+        # UNPAID_HOLD; a paid order keeps them for its 30 days (app/payments.py).
+        c.execute('UPDATE dtf_local.uploads SET complete=true,expires_at=now()+%s::interval WHERE id=%s',
+                  (UNPAID_HOLD, uid))
+    return {'id': uid, 'complete': True}
+
+@router.delete('/api/uploads/{uid}')
+def cancel_upload(uid: UUID, session_id=Depends(owner)):
+    with db.connect() as c:
+        row=upload_row(c,uid,session_id,lock=True)
+        if row['complete']:
+            raise HTTPException(409, 'Completed upload cannot be cancelled')
+        storage.discard(row['object_key'],row['multipart_id'],False)
+        c.execute('UPDATE dtf_local.uploads SET purged_at=now() WHERE id=%s',(uid,))
+    audit('upload_cancelled', upload=str(uid))
+    return {'id':uid,'cancelled':True}

app/app.py

@@ -0,0 +1,48 @@
+"""The DTF Portal/API service: assembly only.
+
+Configuration and shared helpers are in local.runtime; every route lives in a
+router under local.api. This module creates the application, applies the
+cross-cutting middleware, and includes them.
+"""
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from .core import db
+from .core.auth import audit, client_ip
+from .runtime import ALLOWED_HOSTS, ALLOWED_ORIGINS, storage
+from .api import artwork, customer, health, operator, orders, payments, quotes, uploads
+
+
+@asynccontextmanager
+async def lifespan(app):
+    with db.connect() as c:
+        c.execute('SELECT 1 FROM dtf_local.operator_sessions LIMIT 1')
+    storage.health()
+    yield
+
+
+app = FastAPI(title='DTF Portal/API', lifespan=lifespan, docs_url=None, redoc_url=None)
+app.add_middleware(TrustedHostMiddleware, allowed_hosts=ALLOWED_HOSTS)
+
+@app.middleware('http')
+async def safe_headers(request, call_next):
+    if request.method not in ('GET','HEAD','OPTIONS'):
+        origin = request.headers.get('origin')
+        if request.headers.get('sec-fetch-site') == 'cross-site' or (origin and origin not in ALLOWED_ORIGINS):
+            audit('cross_origin_rejected', ip=client_ip(request))
+            return JSONResponse({'detail':'Cross-origin request rejected'}, status_code=403)
+    response = await call_next(request)
+    if response.status_code in (401,403,429) or response.status_code>=500:
+        audit('http_security_event', method=request.method, status=response.status_code, ip=client_ip(request))
+    response.headers['Cache-Control'] = 'no-store'
+    response.headers['X-Content-Type-Options'] = 'nosniff'
+    response.headers['Referrer-Policy'] = 'no-referrer'
+    return response
+
+
+# Order is not significant: no two routers declare the same path.
+for module in (health, uploads, quotes, orders, payments, operator, customer, artwork):
+    app.include_router(module.router)

app/artwork.py

@@ -0,0 +1,79 @@
+"""Attaching artwork to an order: the rules shared by customers and operators.
+
+A customer submits a correction and an operator submits the final set; both go
+through the same checks, so the rule about what may be attached, when, and what
+it does to retention lives in one place.
+"""
+from datetime import datetime, timedelta, timezone
+from uuid import UUID, uuid4
+
+from fastapi import HTTPException
+
+from .runtime import upload_row
+from .scanning import require_clean
+
+
+def generated_owner(c, order, ref, kind):
+    """The owner to look a generated print file up under, or None if it is not one.
+
+    A generated file may be approved as the final for the item it was made
+    from, and only while that item still has its original artwork: after a
+    customer correction it reproduces a layout nobody wants printed.
+    """
+    generated = c.execute('''SELECT item_index FROM dtf_local.print_files
+        WHERE order_id=%s AND upload_id=%s AND status='ready' ''', (order['id'], ref.upload_id)).fetchone()
+    if not generated:
+        return None
+    if kind != 'final' or generated['item_index'] != ref.item_index:
+        raise HTTPException(422, 'A generated print file can only be the final file of its own item')
+    if c.execute("SELECT 1 FROM dtf_local.order_files WHERE order_id=%s AND kind='correction' LIMIT 1",
+                 (order['id'],)).fetchone():
+        raise HTTPException(409, 'A customer correction replaced the artwork this file was generated from')
+    # A large sheet's print file is its original, owned by the customer.
+    return c.execute('SELECT owner FROM dtf_local.uploads WHERE id=%s', (ref.upload_id,)).fetchone()['owner']
+
+def submit_files(c, order, body, identity, kind, actor):
+    if order['version'] != body.version:
+        raise HTTPException(409, 'Order changed. Refresh before submitting files.')
+    if kind == 'final' and order['state'] not in ('rec','tra','cor'):
+        raise HTTPException(409, 'Final files can only change during artwork review')
+    if kind == 'correction' and order['state'] != 'cor':
+        raise HTTPException(409, 'This order is not awaiting artwork correction')
+    if len({f.upload_id for f in body.files}) != len(body.files):
+        raise HTTPException(422, 'Each uploaded file must appear once')
+    count = len(order['snapshot']['items'])
+    if any(f.item_index >= count for f in body.files):
+        raise HTTPException(422, 'Invalid order item')
+    if kind == 'final' and {f.item_index for f in body.files} != set(range(count)):
+        raise HTTPException(422, 'Final-file set must cover every order item')
+    original_ids = [UUID(uid) for item in order['snapshot']['items'] for uid in item['uploads']]
+    first = c.execute('SELECT min(created_at) AS first FROM dtf_local.uploads WHERE id=ANY(%s)', (original_ids,)).fetchone()['first']
+    expiry = first + timedelta(days=30)
+    if expiry <= datetime.now(timezone.utc):
+        raise HTTPException(410, 'Order artwork retention has expired')
+    for ref in body.files:
+        upload = upload_row(c, ref.upload_id, generated_owner(c, order, ref, kind) or identity, lock=True)
+        if not upload['complete']:
+            raise HTTPException(409, 'Complete all uploads first')
+        require_clean(upload)
+        if c.execute('SELECT id FROM dtf_local.order_files WHERE upload_id=%s', (ref.upload_id,)).fetchone():
+            raise HTTPException(409, 'File is already attached. Upload a new revision.')
+    # A new customer correction supersedes every final prepared from earlier
+    # artwork, including finals uploaded while this order was in correction.
+    if kind == 'correction':
+        c.execute("UPDATE dtf_local.order_files SET active=false WHERE order_id=%s AND kind IN ('correction','final')", (order['id'],))
+    else:
+        c.execute('UPDATE dtf_local.order_files SET active=false WHERE order_id=%s AND kind=%s', (order['id'],kind))
+    for ref in body.files:
+        c.execute('INSERT INTO dtf_local.order_files(id,order_id,upload_id,item_index,kind,note,created_by) VALUES(%s,%s,%s,%s,%s,%s,%s)',
+                  (uuid4(),order['id'],ref.upload_id,ref.item_index,kind,body.note,actor))
+        # The order's window, whatever the upload's own hold was.
+        c.execute('UPDATE dtf_local.uploads SET expires_at=%s WHERE id=%s', (expiry,ref.upload_id))
+    c.execute('UPDATE dtf_local.orders SET version=version+1,updated_at=now() WHERE id=%s', (order['id'],))
+    if kind == 'final':
+        # Artwork approval, not commercial quote approval, starts original cleanup.
+        # An original approved as its own print file is kept as the final.
+        finals = [ref.upload_id for ref in body.files]
+        c.execute("UPDATE dtf_local.uploads SET expires_at=LEAST(expires_at,now()+interval '7 days') WHERE id=ANY(%s) AND NOT id=ANY(%s)",
+                  (original_ids, finals))
+    return {'ok': True, 'version': order['version']+1, 'expires_at': expiry}

app/bootstrap.py

@@ -0,0 +1,58 @@
+"""One-shot schema/role setup. Only this job receives database admin credentials."""
+import os
+from pathlib import Path
+from urllib.parse import urlparse
+import psycopg
+from psycopg import sql
+from .core.secrets import load as load_secret_files
+from .operators import seed_from_environment
+
+
+def admin_connect():
+    if os.environ.get('DATABASE_ADMIN_HOST'):
+        return psycopg.connect(
+            host=os.environ['DATABASE_ADMIN_HOST'],
+            dbname=os.environ['DATABASE_ADMIN_NAME'],
+            user=os.environ['DATABASE_ADMIN_USER'],
+            password=os.environ['DATABASE_ADMIN_PASSWORD'],
+        )
+    return psycopg.connect(os.environ['DATABASE_ADMIN_URL'])
+
+
+def admin_password():
+    if os.environ.get('DATABASE_ADMIN_HOST'):
+        return os.environ.get('DATABASE_ADMIN_PASSWORD')
+    url = os.environ.get('DATABASE_ADMIN_URL', '')
+    return urlparse(url).password
+
+
+def main():
+    load_secret_files()
+    role = os.environ['APP_DB_USER']
+    password = os.environ['APP_DB_PASSWORD']
+    if password == admin_password():
+        raise RuntimeError('Application and database administrator passwords must differ')
+    with admin_connect() as c:
+        admin, database = c.execute('SELECT current_user,current_database()').fetchone()
+        if role == admin:
+            raise RuntimeError('Application and database administrator must differ')
+        if not c.execute('SELECT 1 FROM pg_roles WHERE rolname=%s', (role,)).fetchone():
+            c.execute(sql.SQL('CREATE ROLE {} LOGIN').format(sql.Identifier(role)))
+        c.execute(sql.SQL('ALTER ROLE {} NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS PASSWORD {}').format(
+            sql.Identifier(role), sql.Literal(password)))
+        c.execute(Path(__file__).with_name('schema.sql').read_text())
+        c.execute(sql.SQL('REVOKE CREATE ON SCHEMA public FROM PUBLIC'))
+        c.execute(sql.SQL('GRANT CONNECT ON DATABASE {} TO {}').format(sql.Identifier(database),sql.Identifier(role)))
+        c.execute(sql.SQL('GRANT USAGE ON SCHEMA dtf_local TO {}').format(sql.Identifier(role)))
+        c.execute(sql.SQL('GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA dtf_local TO {}').format(sql.Identifier(role)))
+        c.execute(sql.SQL('GRANT USAGE,SELECT ON ALL SEQUENCES IN SCHEMA dtf_local TO {}').format(sql.Identifier(role)))
+        # Turn the configured credential into a real account so an existing
+        # deployment keeps logging in exactly as before. Inserts only when that
+        # email is absent, so a password changed with local.operators is never
+        # reverted by a stale environment variable on the next deploy.
+        seeded = seed_from_environment(c)
+    print('Local schema migrated; runtime role has DML only.')
+    if seeded:
+        print(f'Seeded operator account {seeded} from OPERATOR_EMAIL.')
+
+if __name__ == '__main__': main()

app/core/__init__.py

@@ -0,0 +1 @@
+"""Shared foundations: identity, database, models, prices, secret loading."""

app/core/auth.py

@@ -1,11 +1,28 @@
 """Local customer passwords and revocable database sessions. No email service."""
 import hashlib
+import os
 import secrets
 import logging
 import json
 from uuid import UUID, uuid4
 from fastapi import HTTPException, Request
-from .db import connect
+from ..core.db import connect
+
+COOKIE_SECURE = os.environ.get('COOKIE_SECURE', 'false').lower() == 'true'
+
+def client_ip(request: Request):
+    """The requester's address, for rate-limit buckets and security events.
+
+    The API is only reachable through the web gateway, which replaces
+    X-Forwarded-For with the peer address it observed, so the header carries
+    exactly one value the client could not choose. Without this every request
+    looks like the gateway, which collapses per-source limits into one global
+    bucket and strips the address from the audit trail.
+    """
+    forwarded = request.headers.get('x-forwarded-for', '').split(',')[0].strip()
+    if forwarded:
+        return forwarded[:64]
+    return request.client.host if request.client else 'unknown'
 
 def password_hash(password, salt=None):
     salt = salt or secrets.token_hex(16)
@@ -28,7 +45,7 @@ def session_row(request):
     try:
         sid = UUID(request.cookies.get('dtf_session', ''))
     except ValueError:
-        raise HTTPException(401, 'Start a local session first')
+        raise HTTPException(401, 'Sessão não iniciada. Recarregue a página.')
     with connect() as c:
         row = c.execute('SELECT * FROM dtf_local.sessions WHERE id=%s AND expires_at>now()', (sid,)).fetchone()
     if not row:
@@ -42,8 +59,7 @@ def new_session(c, response, identity=None):
     sid = uuid4()
     identity = identity or uuid4()
     c.execute('INSERT INTO dtf_local.sessions(id,owner) VALUES(%s,%s)', (sid,identity))
-    response.set_cookie('dtf_session', str(sid), httponly=True,
-                        secure=os.environ.get('COOKIE_SECURE', 'false').lower() == 'true',
+    response.set_cookie('dtf_session', str(sid), httponly=True, secure=COOKIE_SECURE,
                         samesite='strict', max_age=86400*7)
     return identity
 
@@ -76,20 +92,35 @@ def rate_limit(scope, identity, limit, seconds=900):
           RETURNING attempts""", (key,seconds,seconds)).fetchone()
     if row['attempts'] > limit:
         audit('rate_limit', scope=scope)
-        raise HTTPException(429, 'Too many requests. Try again later.', headers={'Retry-After':str(seconds)})
+        raise HTTPException(429, 'Muitas tentativas. Tente de novo mais tarde.', headers={'Retry-After':str(seconds)})
+
+ACCOUNT_FAILURES = 10
 
 def throttle(email, request):
     # Independent account and source buckets prevent bypass by rotating emails.
-    rate_limit('auth-source', request.client.host if request.client else 'local', 60)
-    rate_limit('auth-account', email, 10)
+    # Every attempt counts against the source. Only failures count against the
+    # account: guessing a password is what the account bucket stops, and
+    # counting successful sign-ins too let ordinary use lock an operator out.
+    rate_limit('auth-source', client_ip(request), 60)
+    key = hashlib.sha256(('auth-account|'+email).encode()).hexdigest()
+    with connect() as c:
+        row = c.execute("""SELECT attempts FROM dtf_local.login_attempts
+            WHERE key=%s AND started_at >= now()-interval '900 seconds'""", (key,)).fetchone()
+    if row and row['attempts'] >= ACCOUNT_FAILURES:
+        audit('rate_limit', scope='auth-account')
+        raise HTTPException(429, 'Muitas tentativas. Tente de novo mais tarde.', headers={'Retry-After': '900'})
+
+def login_failed(email):
+    """Count a failed sign-in (or registration attempt) against the account."""
+    rate_limit('auth-account', email, 1_000_000)
 
 def operator(request: Request):
     token = request.cookies.get('dtf_operator', '')
     if not token or len(token)>128:
-        raise HTTPException(401, 'Sign in to the local Kanban')
+        raise HTTPException(401, 'Entre no Kanban.')
     digest = hashlib.sha256(token.encode()).hexdigest()
     with connect() as c:
         row = c.execute('SELECT username FROM dtf_local.operator_sessions WHERE token_hash=%s AND expires_at>now()', (digest,)).fetchone()
     if not row:
-        raise HTTPException(401, 'Operator session expired')
+        raise HTTPException(401, 'Sua sessão expirou. Entre de novo.')
     return row['username']

app/core/db.py

@@ -0,0 +1,23 @@
+import os
+from pathlib import Path
+import psycopg
+from psycopg.rows import dict_row
+
+def connect():
+    # Production passes credentials as discrete libpq fields.  This avoids
+    # treating characters in a generated password as URL syntax.  Local and
+    # test environments retain DATABASE_URL compatibility.
+    if os.environ.get('DATABASE_HOST'):
+        return psycopg.connect(
+            host=os.environ['DATABASE_HOST'],
+            dbname=os.environ['DATABASE_NAME'],
+            user=os.environ['DATABASE_USER'],
+            password=os.environ['DATABASE_PASSWORD'],
+            row_factory=dict_row,
+        )
+    return psycopg.connect(os.environ['DATABASE_URL'], row_factory=dict_row)
+
+def initialize():
+    with connect() as c:
+        # The schema lives at the package root, one level up from core/.
+        c.execute((Path(__file__).resolve().parent.parent / 'schema.sql').read_text())

app/core/limits.py

@@ -0,0 +1,13 @@
+"""Limits shared by upload admission and the malware scanner."""
+import os
+
+CLAMAV_STREAM_MAX_BYTES = 2000 * 1024 * 1024  # infra/clamd.conf StreamMaxLength
+
+
+def scan_limit_bytes():
+    """The largest file ClamAV scans; above it the format check releases it."""
+    return min(CLAMAV_STREAM_MAX_BYTES, int(os.environ.get('SCAN_MAX_BYTES', str(CLAMAV_STREAM_MAX_BYTES))))
+
+
+def upload_limit_bytes():
+    return int(os.environ.get('MAX_UPLOAD_BYTES', '5368709120'))

app/core/models.py

@@ -0,0 +1,274 @@
+import re
+from decimal import Decimal
+from typing import Literal
+from uuid import UUID
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra='forbid', allow_inf_nan=False)
+
+class Customer(StrictModel):
+    cnpj: str
+    zap: str
+    mail: str = Field(max_length=254)
+
+    @field_validator('cnpj')
+    @classmethod
+    def cnpj_valid(cls, value):
+        digits = re.sub(r'\D', '', value)
+        if len(digits) != 14 or len(set(digits)) == 1 or not digits.isascii():
+            raise ValueError('Invalid CNPJ')
+        def check(base, weights):
+            rem = sum(int(n) * w for n,w in zip(base, weights)) % 11
+            return 0 if rem < 2 else 11-rem
+        if check(digits[:12], [5,4,3,2,9,8,7,6,5,4,3,2]) != int(digits[12]) or check(digits[:13], [6,5,4,3,2,9,8,7,6,5,4,3,2]) != int(digits[13]):
+            raise ValueError('Invalid CNPJ')
+        return digits
+
+    @field_validator('zap')
+    @classmethod
+    def phone_valid(cls, value):
+        digits = re.sub(r'\D', '', value)
+        if len(digits) not in (10,11) or not digits.isascii():
+            raise ValueError('Invalid phone')
+        return digits
+
+    @field_validator('mail')
+    @classmethod
+    def email_valid(cls, value):
+        if not re.fullmatch(r'[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}', value.strip()):
+            raise ValueError('Invalid email')
+        return value.strip()
+
+class Freight(StrictModel):
+    service: Literal['pickup','mock-standard','jadlog'] = 'pickup'
+    postal_code: str = Field(default='', max_length=8)
+
+class FreightEstimate(Freight):
+    """The cart's estimate. The charged freight is quoted again by the server
+    from the approved items, never from these numbers."""
+    metres: Decimal | None = Field(default=None, gt=0, le=12000)
+    declared_cents: int = Field(default=0, ge=0, le=100_000_000, strict=True)
+
+UF = Literal['AC','AL','AP','AM','BA','CE','DF','ES','GO','MA','MT','MS','MG','PA','PB',
+             'PR','PE','PI','RJ','RN','RS','RO','RR','SC','SP','SE','TO']
+
+class Destination(StrictModel):
+    """Where a shipped order goes. A CEP alone quotes freight; it does not deliver."""
+    recipient: str = Field(min_length=2, max_length=120)
+    street: str = Field(min_length=2, max_length=160)
+    number: str = Field(min_length=1, max_length=20)
+    complement: str = Field(default='', max_length=80)
+    district: str = Field(min_length=2, max_length=80)
+    city: str = Field(min_length=2, max_length=80)
+    state: UF
+    postal_code: str = Field(pattern=r'^[0-9]{8}$')
+
+    @field_validator('recipient', 'street', 'number', 'complement', 'district', 'city', mode='before')
+    @classmethod
+    def trimmed(cls, value):
+        if isinstance(value, str):
+            value = ' '.join(value.split())
+            if any(ord(ch) < 32 for ch in value):
+                raise ValueError('Invalid characters')
+        return value
+
+class UploadStart(StrictModel):
+    name: str = Field(min_length=1, max_length=200, pattern=r'^[^/\\\x00-\x1f]+$')
+    size: int = Field(gt=0, strict=True)
+
+    @field_validator('name')
+    @classmethod
+    def artwork_extension(cls, value):
+        # Union of existing Site product formats; this is NOT malware/pre-flight validation.
+        if not re.search(r'\.(png|jpe?g|webp|tiff?|pdf|psd|psb|ai|cdr)$', value, re.I):
+            raise ValueError('Unsupported artwork file extension')
+        return value
+
+class ProductionSource(StrictModel):
+    upload_id: UUID
+    kind: Literal['sheet', 'artwork']
+    width_cm: Decimal = Field(gt=0, le=57)
+    length_cm: Decimal = Field(gt=0, le=6000)
+    copies: int = Field(ge=1, le=200, strict=True)
+    rotation_degrees: Literal[0, 90] = 0
+    mirrored: bool = False
+    measurement: Literal['file', 'customer']
+
+class ProductionPlacement(StrictModel):
+    source_index: int = Field(ge=0, le=19, strict=True)
+    copy_index: int = Field(ge=0, le=199, strict=True)
+    x_cm: Decimal = Field(ge=0, le=57)
+    y_cm: Decimal = Field(ge=0, le=1200000)
+    width_cm: Decimal = Field(gt=0, le=57)
+    length_cm: Decimal = Field(gt=0, le=6000)
+    rotation_degrees: Literal[0, 90, 180, 270]
+    mirrored: bool
+
+class ProductionSpec(StrictModel):
+    version: Literal[2]
+    film_width_cm: Decimal
+    height_cm: Decimal = Field(gt=0, le=1200000)
+    sources: list[ProductionSource] = Field(min_length=1, max_length=20)
+    placements: list[ProductionPlacement] = Field(min_length=1, max_length=4000)
+
+class Item(StrictModel):
+    mode: Literal['file','avulsa','uvfile','uv']
+    metres: Decimal = Field(gt=0, le=12000)
+    grade: int = Field(ge=0, le=100, strict=True)
+    uploads: list[UUID] = Field(min_length=1, max_length=20)
+    production: ProductionSpec
+    quality_status: Literal['ok', 'warning', 'unverified']
+    quality_acknowledged: bool
+
+    @model_validator(mode='after')
+    def production_matches_uploads(self):
+        if [source.upload_id for source in self.production.sources] != self.uploads:
+            raise ValueError('Production sources must match uploaded files in order')
+        is_sheet = self.mode in ('file', 'uvfile')
+        film_width = Decimal('28.5') if self.mode in ('uvfile', 'uv') else Decimal('57')
+        if self.production.film_width_cm != film_width:
+            raise ValueError('Production film width does not match the product')
+        for source in self.production.sources:
+            if (source.kind == 'sheet') != is_sheet or source.width_cm > film_width:
+                raise ValueError('Production source does not fit the selected product')
+            if is_sheet and (source.rotation_degrees or source.mirrored):
+                raise ValueError('Finished sheets cannot be rotated or mirrored by the layout')
+        expected={(index,copy) for index,source in enumerate(self.production.sources)
+                  for copy in range(source.copies)}
+        placed=set()
+        tolerance=Decimal('0.02')
+        for placement in self.production.placements:
+            key=(placement.source_index,placement.copy_index)
+            if key not in expected or key in placed:
+                raise ValueError('Production placement has a missing or duplicate source copy')
+            placed.add(key)
+            source=self.production.sources[placement.source_index]
+            auto_rotation=(placement.rotation_degrees-source.rotation_degrees)%360
+            if auto_rotation not in (0,90) or placement.mirrored != source.mirrored:
+                raise ValueError('Production placement changes the source transform')
+            width,length=(source.width_cm,source.length_cm) if auto_rotation==0 else (source.length_cm,source.width_cm)
+            if abs(placement.width_cm-width)>tolerance or abs(placement.length_cm-length)>tolerance:
+                raise ValueError('Production placement changes the source size')
+            if placement.x_cm+placement.width_cm>film_width+tolerance or placement.y_cm+placement.length_cm>self.production.height_cm+tolerance:
+                raise ValueError('Production placement is outside the film')
+            if is_sheet and (placement.x_cm or auto_rotation):
+                raise ValueError('Finished sheets must retain their original orientation')
+        if placed != expected:
+            raise ValueError('Production layout does not cover every source copy')
+        if self.quality_status == 'warning' and not self.quality_acknowledged:
+            raise ValueError('Resolution warning must be acknowledged')
+        return self
+
+class QuoteRequest(StrictModel):
+    request_key: UUID
+    customer: Customer
+    items: list[Item] = Field(min_length=1, max_length=30)
+    freight: Freight
+    destination: Destination | None = None
+
+    @model_validator(mode='after')
+    def destination_matches_freight(self):
+        if self.freight.service == 'pickup':
+            if self.destination is not None:
+                raise ValueError('Pickup orders do not take a delivery address')
+        elif self.destination is None:
+            raise ValueError('Delivery requires the full address')
+        elif self.destination.postal_code != self.freight.postal_code:
+            raise ValueError('The delivery address CEP must be the CEP freight was quoted for')
+        return self
+
+class Review(StrictModel):
+    items: list[Item] = Field(min_length=1, max_length=30)
+
+class Pay(StrictModel):
+    quote_id: UUID
+
+class PaymentMethod(StrictModel):
+    type: Literal['pix', 'card']
+    # Card fields come from the provider's own form, which tokenises the card
+    # in the browser; the number never reaches this server.
+    token: str | None = Field(default=None, max_length=200)
+    payment_method_id: str | None = Field(default=None, max_length=40, pattern=r'^[a-z_]+$')
+    installments: int = Field(default=1, ge=1, le=12, strict=True)
+    issuer_id: str | None = Field(default=None, max_length=40)
+    # The cardholder's document from the card form: for a card, the payer is
+    # the cardholder, not necessarily the company on the invoice.
+    payer_document_type: Literal['CPF', 'CNPJ'] | None = None
+    payer_document: str | None = Field(default=None, pattern=r'^[0-9]{11,14}$')
+
+    @model_validator(mode='after')
+    def card_needs_token(self):
+        if self.type == 'card' and not (self.token and self.payment_method_id):
+            raise ValueError('Card payment requires the provider token and method')
+        return self
+
+class PaymentIntent(StrictModel):
+    quote_id: UUID
+    method: PaymentMethod
+
+class Move(StrictModel):
+    state: Literal['rec','tra','fil','imp','cor','fin']
+    version: int = Field(ge=0)
+    reason: str = Field(default='', max_length=1000)
+
+class Resolution(StrictModel):
+    note: str = Field(min_length=3, max_length=1000)
+
+class Register(StrictModel):
+    customer: Customer
+    password: str = Field(min_length=12, max_length=128)
+
+class ProfileUpdate(StrictModel):
+    """What a customer may change about their account; the CNPJ is not among it."""
+    zap: str
+    address: Destination | None = None
+
+    @field_validator('zap')
+    @classmethod
+    def phone_valid(cls, value):
+        digits = re.sub(r'\D', '', value)
+        if len(digits) not in (10,11) or not digits.isascii():
+            raise ValueError('Invalid phone')
+        return digits
+
+class EmailChange(StrictModel):
+    email: str = Field(max_length=254)
+    password: str = Field(min_length=1, max_length=128)
+
+    @field_validator('email')
+    @classmethod
+    def email_valid(cls, value):
+        value = value.strip().lower()
+        if not re.fullmatch(r'[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}', value):
+            raise ValueError('Invalid email')
+        return value
+
+class PasswordChange(StrictModel):
+    current: str = Field(min_length=1, max_length=128)
+    new: str = Field(min_length=12, max_length=128)
+
+class Login(StrictModel):
+    email: str = Field(min_length=3, max_length=254)
+    password: str = Field(min_length=1, max_length=128)
+
+class OperatorLogin(StrictModel):
+    email: str = Field(min_length=3, max_length=254)
+    password: str = Field(min_length=1, max_length=128)
+
+    @field_validator('email')
+    @classmethod
+    def operator_email_valid(cls, value):
+        value = value.strip().lower()
+        if not re.fullmatch(r'[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}', value):
+            raise ValueError('Invalid email')
+        return value
+
+class FileReference(StrictModel):
+    upload_id: UUID
+    item_index: int = Field(ge=0, strict=True)
+
+class ArtworkSubmission(StrictModel):
+    version: int = Field(ge=0, strict=True)
+    files: list[FileReference] = Field(min_length=1, max_length=60)
+    note: str = Field(min_length=1, max_length=1000)

app/core/secrets.py

@@ -0,0 +1,76 @@
+"""Resolve Docker secret files into the environment before configuration is read.
+
+Swarm mounts each secret as a file and the stack passes its path as `<NAME>_FILE`.
+The deployed `docker-compose.yml` passes credentials as plain environment
+variables, so this module is inert there. It exists so a stack can supply them as
+Docker secrets instead without any code change; see `docs/ROADMAP.md` 2.12.
+
+Call `load()` in every entrypoint before any configuration is read.
+
+Note for readers: this module is `local.secrets`. Python 3 resolves `import
+secrets` elsewhere in the package to the standard library, not to this file.
+"""
+import os
+
+# The settings a stack may supply as secret files. Any other `*_FILE` variable is
+# resolved the same way; this list documents the contract and is what the release
+# gate checks against.
+SECRET_FILE_SETTINGS = (
+    'DATABASE_URL',
+    'DATABASE_ADMIN_URL',
+    'DATABASE_PASSWORD',
+    'DATABASE_ADMIN_PASSWORD',
+    'APP_DB_PASSWORD',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'OPERATOR_PASSWORD',
+    'PAYMENT_TOKEN',
+    'PAYMENT_WEBHOOK_SECRET',
+    'TINY_TOKEN',
+    'WHATSAPP_TOKEN',
+)
+
+SUFFIX = '_FILE'
+
+
+def read_secret(path):
+    """One secret's value, without the newline an editor or `docker secret` adds.
+
+    Only a single trailing newline is removed: everything else is part of the
+    value, because a generated password may legitimately end in whitespace.
+    """
+    with open(path, 'r', encoding='utf-8') as handle:
+        value = handle.read()
+    if value.endswith('\r\n'):
+        return value[:-2]
+    if value.endswith('\n'):
+        return value[:-1]
+    return value
+
+
+def load(environ=None):
+    """Replace every `<NAME>_FILE` path with `<NAME>` holding the file's contents.
+
+    Fails closed. An unreadable secret, an empty one, or a name supplied both
+    directly and as a file is a configuration error, and starting anyway would
+    mean running with a credential nobody intended. Never logs a value.
+    """
+    environ = os.environ if environ is None else environ
+    resolved = []
+    for key in sorted(k for k in environ if k.endswith(SUFFIX) and len(k) > len(SUFFIX)):
+        name = key[:-len(SUFFIX)]
+        path = environ[key].strip()
+        if not path:
+            raise RuntimeError(f'{key} is set but empty; point it at a secret file')
+        if environ.get(name):
+            raise RuntimeError(
+                f'{name} and {key} are both set; supply the value or the file, not both')
+        try:
+            value = read_secret(path)
+        except OSError as exc:
+            raise RuntimeError(f'{key} could not be read: {exc.strerror}') from None
+        if not value:
+            raise RuntimeError(f'{key} points at an empty secret file')
+        environ[name] = value
+        resolved.append(name)
+    return resolved

app/grade_check.py

@@ -0,0 +1,189 @@
+"""The grade (the resolution discount) recomputed from the uploaded files.
+
+The Site grades the art in the customer's browser and sends the grade with the
+cart, and the price depends on it. A customer who edits the page could claim a
+better grade, so before a cart is approved at checkout the server reads the
+files it already has and works the grade out again, by the Site's own rules:
+
+- a finished sheet: its pixel width over the sheet width is its DPI, and the
+  item's grade comes from the worst sheet (web/site-quality.js);
+- artworks: each one's DPI along the width it is printed at, rotation
+  included; the item's grade is the average of the artworks' grades;
+- a PDF: the area-weighted DPI of the images drawn on its page, 300 when it
+  is only vectors (web/site-pdf.js, dpiDasImagens and resumoDpi).
+
+Images are measured from their first bytes, never decoded. A PDF is opened
+only up to PDF_MAX_BYTES, the size the Site itself analyses. A grade that
+cannot be recomputed is None; the caller decides what that means.
+"""
+import math
+import os
+import struct
+import tempfile
+
+DPI_IDEAL = 300
+# The Site analyses PDFs up to 150 MB (GRANDE_BYTES); above that it does not
+# grade them, so neither does this.
+PDF_MAX_BYTES = 150 * 1048576
+HEAD_BYTES = 1048576
+# Rounding in the browser and here can differ by a point on the same file.
+TOLERANCE = 2
+
+
+def js_round(value):
+    """Math.round, which rounds halves up; Python's round() does not."""
+    return math.floor(value + 0.5)
+
+
+def grade_of(dpi):
+    return max(6, min(100, js_round(dpi / DPI_IDEAL * 100)))
+
+
+def image_size(head):
+    """(width, height) in pixels from a PNG, JPEG or WebP's first bytes."""
+    if head[:8] == b'\x89PNG\r\n\x1a\n' and head[12:16] == b'IHDR':
+        return struct.unpack('>II', head[16:24])
+    if head[:2] == b'\xff\xd8':
+        i = 2
+        while i + 9 < len(head):
+            if head[i] != 0xFF:
+                i += 1
+                continue
+            marker = head[i + 1]
+            if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7 or marker == 0xFF:
+                i += 1 if marker == 0xFF else 2
+                continue
+            length = struct.unpack('>H', head[i + 2:i + 4])[0]
+            if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+                h, w = struct.unpack('>HH', head[i + 5:i + 9])
+                return w, h
+            i += 2 + length
+        return None
+    if head[:4] == b'RIFF' and head[8:12] == b'WEBP':
+        chunk = head[12:16]
+        if chunk == b'VP8X':
+            return (int.from_bytes(head[24:27], 'little') + 1, int.from_bytes(head[27:30], 'little') + 1)
+        if chunk == b'VP8L' and head[20] == 0x2F:
+            bits = int.from_bytes(head[21:25], 'little')
+            return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+        if chunk == b'VP8 ' and head[23:26] == b'\x9d\x01\x2a':
+            w, h = struct.unpack('<HH', head[26:30])
+            return w & 0x3FFF, h & 0x3FFF
+    return None
+
+
+def _multiply(a, b):
+    return [a[0] * b[0] + a[2] * b[1], a[1] * b[0] + a[3] * b[1],
+            a[0] * b[2] + a[2] * b[3], a[1] * b[2] + a[3] * b[3],
+            a[0] * b[4] + a[2] * b[5] + a[4], a[1] * b[4] + a[3] * b[5] + a[5]]
+
+
+def pdf_dpi(path):
+    """The page's area-weighted image DPI, 300 for vectors only, None if the
+    file is not a one-page PDF this can read."""
+    import pikepdf
+    try:
+        with pikepdf.open(path) as pdf:
+            if len(pdf.pages) != 1:
+                return None
+            page = pdf.pages[0]
+            unit = float(page.obj.get('/UserUnit', 1))
+            found = []
+
+            def walk(resources, instructions, ctm, depth):
+                stack = []
+                xobjects = resources.get('/XObject', {}) if resources is not None else {}
+                for operands, operator in instructions:
+                    op = str(operator)
+                    if op == 'q':
+                        stack.append(ctm)
+                    elif op == 'Q':
+                        ctm = stack.pop() if stack else [1, 0, 0, 1, 0, 0]
+                    elif op == 'cm':
+                        ctm = _multiply(ctm, [float(v) for v in operands])
+                    elif op == 'Do' and operands:
+                        xobject = xobjects.get(str(operands[0]))
+                        if xobject is None:
+                            continue
+                        subtype = xobject.get('/Subtype')
+                        if subtype == '/Image':
+                            width_pt = math.hypot(ctm[0], ctm[1])
+                            if width_pt >= 1:
+                                found.append((int(xobject.get('/Width', 0)) / (width_pt * unit / 72),
+                                              abs(ctm[0] * ctm[3] - ctm[1] * ctm[2])))
+                        elif subtype == '/Form' and depth < 8:
+                            matrix = [float(v) for v in xobject.get('/Matrix', [1, 0, 0, 1, 0, 0])]
+                            walk(xobject.get('/Resources', resources),
+                                 pikepdf.parse_content_stream(xobject), _multiply(ctm, matrix), depth + 1)
+
+            walk(page.obj.get('/Resources'), pikepdf.parse_content_stream(page), [1, 0, 0, 1, 0, 0], 0)
+    except Exception:
+        return None
+    found = [(dpi, area) for dpi, area in found if dpi > 0]
+    if not found:
+        return DPI_IDEAL
+    total = sum(area for _, area in found) or 1
+    return js_round(sum(dpi * area for dpi, area in found) / total)
+
+
+class Files:
+    """The uploaded files, read from storage as little as needed."""
+
+    def __init__(self, storage):
+        self.storage = storage
+
+    def head(self, row):
+        return self.storage.client.get_object(Bucket=self.storage.bucket, Key=row['object_key'],
+                                              Range=f'bytes=0-{HEAD_BYTES - 1}')['Body'].read()
+
+    def pdf_dpi(self, row):
+        if row['size'] > PDF_MAX_BYTES:
+            return None
+        with tempfile.NamedTemporaryFile(suffix='.pdf') as handle:
+            self.storage.client.download_fileobj(self.storage.bucket, row['object_key'], handle)
+            handle.flush()
+            return pdf_dpi(handle.name)
+
+
+def source_dpi(files, row, source):
+    """One source's DPI across the width it is printed at, or None."""
+    name = row['name'].lower()
+    width_in = float(source['width_cm']) / 2.54
+    if name.endswith('.pdf'):
+        return files.pdf_dpi(row) if source['kind'] == 'sheet' else None
+    if not name.endswith(('.png', '.jpg', '.jpeg', '.webp')):
+        return None
+    size = image_size(files.head(row))
+    if not size or not all(size):
+        return None
+    across = size[1] if source['rotation_degrees'] in (90, 270) else size[0]
+    return across / width_in
+
+
+def item_grade(files, item, rows):
+    """The grade the Site gives this item, recomputed; None if it cannot be."""
+    sources = item['production']['sources']
+    dpis = []
+    for source in sources:
+        row = rows.get(str(source['upload_id']))
+        dpi = source_dpi(files, row, source) if row else None
+        if dpi is None:
+            return None
+        dpis.append(dpi)
+    if all(source['kind'] == 'sheet' for source in sources):
+        # A sheet's DPI is shown and compared as a whole number.
+        return grade_of(min(js_round(d) for d in dpis))
+    return js_round(sum(grade_of(d) for d in dpis) / len(dpis))
+
+
+def mismatch(files, items, rows):
+    """Why a cart's grades cannot be approved at checkout, or None."""
+    for item in items:
+        if item['grade'] == 0:
+            continue                      # full price: nothing to verify
+        verified = item_grade(files, item, rows)
+        if verified is None:
+            return 'Nota não conferida no servidor'
+        if item['grade'] > verified + TOLERANCE:
+            return f"Nota {item['grade']} maior que a do arquivo ({verified})"
+    return None

app/jadlog.py

@@ -0,0 +1,119 @@
+"""Jadlog freight quotes (Embarcador API, "Simulador de Frete").
+
+Written from Jadlog's API manual v2.3 (August 2025) and exercised only
+against a fake HTTP transport until app.jadlog_probe has run on the client's
+account. A quote is read-only: it creates no shipment and costs nothing, so
+unlike Tiny it can be tried on the real account as often as needed.
+
+The client's contract: origin CEP 14402-310, service .PACKAGE (modalidade 3),
+home delivery. Jadlog prices by weight in kg and expects the larger of the
+real and the cubed weight. The package weight comes from the client (a base
+plus a weight per billed metre) and has no default: FREIGHT_ADAPTER=jadlog
+refuses to start without it, so a guessed weight never prices a customer's
+freight.
+"""
+import os
+from decimal import ROUND_HALF_UP, Decimal
+
+import httpx
+
+QUOTE_URL = 'https://www.jadlog.com.br/embarcador/api/frete/valor'
+PACKAGE = 3
+ORIGIN = '14402310'
+SERVICE = 'jadlog'
+WEIGHT_SETTINGS = ('JADLOG_PESO_BASE_KG', 'JADLOG_PESO_POR_METRO_KG')
+
+
+class JadlogError(Exception):
+    pass
+
+
+def digits(value):
+    return ''.join(ch for ch in str(value or '') if ch.isdigit())
+
+
+class JadlogQuotes:
+    def __init__(self, token=None, cnpj=None, conta=None, contrato=None, origin=None,
+                 modalidade=None, transport=None):
+        self.token = (token or os.environ.get('JADLOG_TOKEN', '')).strip()
+        self.cnpj = digits(cnpj or os.environ.get('JADLOG_CNPJ'))
+        # Sent as configured: Jadlog issues it as 000000-0 and documents six
+        # characters, so which form it accepts is only known on the account.
+        self.conta = (conta if conta is not None else os.environ.get('JADLOG_CONTA', '')).strip()
+        # Only when Jadlog issued one; the manual says to send null otherwise.
+        self.contrato = (contrato if contrato is not None else os.environ.get('JADLOG_CONTRATO', '')).strip() or None
+        self.origin = digits(origin or os.environ.get('JADLOG_ORIGEM_CEP') or ORIGIN)
+        self.modalidade = int(modalidade or os.environ.get('JADLOG_MODALIDADE') or PACKAGE)
+        if not self.token or len(self.cnpj) != 14:
+            raise RuntimeError('Jadlog needs JADLOG_TOKEN and a 14-digit JADLOG_CNPJ')
+        self.http = httpx.Client(timeout=20, transport=transport)
+
+    def item(self, postal_code, weight_kg, declared_cents):
+        return {'cepori': self.origin, 'cepdes': digits(postal_code), 'frap': 'N',
+                'peso': float(weight_kg), 'cnpj': self.cnpj, 'conta': self.conta,
+                'contrato': self.contrato, 'modalidade': self.modalidade,
+                'tpentrega': 'D', 'tpseguro': 'N',
+                'vldeclarado': declared_cents / 100, 'vlcoleta': 0}
+
+    def quote(self, postal_code, weight_kg, declared_cents):
+        """Price in centavos and delivery days for one package to one CEP."""
+        response = self.http.post(QUOTE_URL, json={'frete': [self.item(postal_code, weight_kg, declared_cents)]},
+                                  headers={'Authorization': self.token})
+        if response.status_code == 401:
+            raise JadlogError('Jadlog refused the token (HTTP 401)')
+        try:
+            data = response.json()
+        except ValueError:
+            raise JadlogError(f'HTTP {response.status_code}: the response is not JSON') from None
+        items = data.get('frete') or []
+        # The manual names the group "erro" in its tables and "error" in its
+        # examples, at the top level and per item.
+        problem = data.get('error') or data.get('erro')
+        if not problem and items:
+            problem = items[0].get('erro') or items[0].get('error')
+        if problem:
+            raise JadlogError(problem.get('descricao') or str(problem) if isinstance(problem, dict) else str(problem))
+        if response.status_code >= 400 or not items or items[0].get('vltotal') is None:
+            raise JadlogError(f'HTTP {response.status_code}: no freight value in the response')
+        total = Decimal(str(items[0]['vltotal']))
+        return {'total_cents': int((total * 100).quantize(Decimal('1'), ROUND_HALF_UP)),
+                'days': items[0].get('prazo'), 'raw': items[0]}
+
+
+def required_settings():
+    return ('JADLOG_TOKEN', 'JADLOG_CNPJ') + WEIGHT_SETTINGS
+
+
+class JadlogFreight:
+    """The Site's delivery option: Jadlog's price for the order's package."""
+    name = 'jadlog'
+
+    def __init__(self, quotes=None):
+        self.quotes = quotes or JadlogQuotes()
+        self.base_kg = Decimal(os.environ['JADLOG_PESO_BASE_KG'])
+        self.per_metre_kg = Decimal(os.environ['JADLOG_PESO_POR_METRO_KG'])
+        # Jadlog's time counts from collection; the order is printed first.
+        self.production_days = int(os.environ.get('FREIGHT_PRODUCTION_DAYS') or 0)
+        if self.base_kg < 0 or self.per_metre_kg <= 0 or self.production_days < 0:
+            raise RuntimeError('Jadlog package weight and production days must be positive')
+
+    def weight_kg(self, metres):
+        return (self.base_kg + self.per_metre_kg * Decimal(str(metres))).quantize(Decimal('0.001'))
+
+    def quote(self, service, postal_code, metres=None, declared_cents=0):
+        if service == 'pickup':
+            return {'provider': self.name, 'service': 'pickup', 'total_cents': 0, 'postal_code': ''}
+        if service != SERVICE or len(postal_code) != 8 or not postal_code.isascii() or not postal_code.isdigit():
+            raise ValueError('Select pickup or Jadlog delivery with an eight-digit CEP')
+        if metres is None or Decimal(str(metres)) <= 0:
+            raise ValueError('The order length is required to quote freight')
+        weight = self.weight_kg(metres)
+        try:
+            result = self.quotes.quote(postal_code, weight, int(declared_cents))
+        except (JadlogError, httpx.HTTPError) as error:
+            raise ValueError(f'Não foi possível cotar o frete na Jadlog agora: {error}') from None
+        days = result['days']
+        return {'provider': self.name, 'service': SERVICE, 'postal_code': postal_code,
+                'total_cents': result['total_cents'], 'weight_kg': str(weight),
+                'days': None if days is None else int(days) + self.production_days,
+                'description': 'Jadlog .PACKAGE'}

app/jadlog_probe.py

@@ -0,0 +1,80 @@
+"""Read-only price check against the client's real Jadlog account, run by hand.
+A quote creates no shipment and costs nothing.
+
+    python -m app.jadlog_probe [--cep 01310100 ...] [--peso 0.5 ...] [--valor 100]
+
+Without --cep and --peso it prices a few test weights to a few regions. It
+answers whether the token, CNPJ and account are accepted, whether a contract
+number is required (Jadlog names it in the error), and what the contract
+prices and delivery times are. The first failure stops the run: an account
+problem would repeat on every line.
+
+In production, from the worker's console (Portainer > Containers > worker >
+Console), with JADLOG_TOKEN, JADLOG_CNPJ and JADLOG_CONTA in the stack:
+
+    python -m app.jadlog_probe
+
+Locally, with the credentials in jadlog.env (ignored by git):
+
+    docker compose -f compose.local.yaml -f compose.providers.yaml run --rm --no-deps --build \\
+        --env-from-file jadlog.env worker python -m app.jadlog_probe
+"""
+import argparse
+import sys
+from decimal import Decimal
+
+from .core.secrets import load as load_secret_files
+from .jadlog import JadlogError, JadlogQuotes
+
+DESTINATIONS = {'14402310': 'Franca (origem)', '01310100': 'São Paulo', '20040002': 'Rio de Janeiro',
+                '80010000': 'Curitiba', '50030230': 'Recife', '69005010': 'Manaus'}
+WEIGHTS = ['0.3', '0.5', '1', '2', '5']
+
+
+def money(cents):
+    return f'R$ {cents / 100:.2f}'.replace('.', ',')
+
+
+def run(quotes, ceps, weights, declared_cents, out):
+    header = quotes.token
+    for weight in weights:
+        for cep in ceps:
+            try:
+                result = quotes.quote(cep, Decimal(weight), declared_cents)
+            except JadlogError as error:
+                # The manual shows the header as the bare token; some accounts
+                # are issued one that expects the Bearer scheme.
+                if '401' in str(error) and not header.lower().startswith('bearer '):
+                    quotes.token = 'Bearer ' + header
+                    header = quotes.token
+                    try:
+                        result = quotes.quote(cep, Decimal(weight), declared_cents)
+                    except JadlogError as retry:
+                        out(f'ERRO {cep} {weight} kg: {retry} (also with "Bearer ")')
+                        return 1
+                    out('Note: the token only works with the "Bearer " prefix.')
+                else:
+                    out(f'ERRO {cep} {weight} kg: {error}')
+                    return 1
+            days = result['days']
+            out(f"{weight} kg\t{cep}\t{DESTINATIONS.get(cep, '')}\t{money(result['total_cents'])}\t"
+                f"{days if days is not None else '?'} dia(s)")
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='python -m app.jadlog_probe')
+    parser.add_argument('--cep', action='append', help='destination CEP (repeatable)')
+    parser.add_argument('--peso', action='append', help='weight in kg (repeatable)')
+    parser.add_argument('--valor', default='100', help='declared value in reais (default 100)')
+    args = parser.parse_args(argv)
+    load_secret_files()
+    quotes = JadlogQuotes()
+    declared = int(Decimal(args.valor) * 100)
+    print(f'Origem {quotes.origin}, modalidade {quotes.modalidade}, contrato {quotes.contrato or "-"}, '
+          f'valor declarado {money(declared)}')
+    return run(quotes, args.cep or list(DESTINATIONS), args.peso or WEIGHTS, declared, print)
+
+
+if __name__ == '__main__':
+    sys.exit(main())

app/mercadopago.py

@@ -0,0 +1,196 @@
+"""Mercado Pago: payment creation, webhook verification and status lookup.
+
+Written from the public API documentation and exercised only against a fake
+HTTP transport. It is not a verified integration until it has passed the
+sandbox flows in docs/PRODUCTION_INPUTS.md with the client's own account;
+until then the runtime refuses to select it without explicit credentials.
+
+The notification is only a pointer. Its body says "payment 123 changed" and
+nothing about amount or status, so nothing in it is trusted beyond the id:
+the payment is fetched from the API with our access token, and that response
+is what the order service compares against the approved quote.
+
+Signature (x-signature: "ts=<unix>,v1=<hex>"): HMAC-SHA256, keyed with the
+webhook secret from the integration panel, over the manifest
+"id:<data.id>;request-id:<x-request-id>;ts:<ts>;", where data.id comes from
+the notification URL's query string (lower-cased when alphanumeric). A part
+whose value is absent from the notification is left out of the manifest.
+"""
+import hashlib
+import hmac
+import json
+import os
+import time
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal, InvalidOperation
+from typing import Mapping
+
+import httpx
+
+from .adapters import PaymentEvent
+
+API = 'https://api.mercadopago.com'
+# How old a signed timestamp may be. Mercado Pago retries a failed delivery
+# every 15 minutes, re-signing each attempt, so a replayed old one is refused.
+MAX_SIGNATURE_AGE = 30 * 60
+STATUSES = {'approved': 'approved', 'pending': 'pending', 'in_process': 'pending',
+            'authorized': 'pending', 'in_mediation': 'pending', 'rejected': 'rejected',
+            'cancelled': 'cancelled', 'refunded': 'refunded', 'charged_back': 'refunded'}
+# A PIX code stops working after this; Mercado Pago then cancels the payment.
+PIX_MINUTES = 30
+BRASILIA = timezone(timedelta(hours=-3))
+
+
+class MercadoPagoPayment:
+    name = 'mercadopago'
+
+    def __init__(self, access_token=None, webhook_secret=None, notification_url=None,
+                 transport=None, clock=time.time):
+        self.access_token = access_token or os.environ.get('MP_ACCESS_TOKEN', '')
+        self.webhook_secret = (webhook_secret or os.environ.get('MP_WEBHOOK_SECRET', '')).encode()
+        self.notification_url = notification_url or os.environ.get('MP_NOTIFICATION_URL', '')
+        if not self.access_token or not self.webhook_secret:
+            raise RuntimeError('Mercado Pago needs MP_ACCESS_TOKEN and MP_WEBHOOK_SECRET')
+        self.http = httpx.Client(base_url=API, transport=transport, timeout=15,
+                                 headers={'Authorization': f'Bearer {self.access_token}'})
+        self.clock = clock
+
+    # Payments ------------------------------------------------------------
+
+    def create(self, quote_id: str, total_cents: int, customer: dict, method: dict | None = None) -> dict:
+        """Create a payment for an approved quote.
+
+        The quote id is the idempotency key, so a retry after a timeout returns
+        the payment already created rather than charging again. `method` is
+        {'type': 'pix'} or {'type': 'card', 'token', 'payment_method_id',
+        'installments', 'issuer_id'} from Mercado Pago's card form: card data is
+        tokenised in the customer's browser and never reaches this server.
+        """
+        method = method or {'type': 'pix'}
+        body = {'transaction_amount': float(Decimal(total_cents) / 100),
+                'description': f'DTF - cotação {quote_id[:8]}',
+                'external_reference': quote_id,
+                'payer': {'email': customer['mail'],
+                          'identification': {'type': 'CNPJ', 'number': customer['cnpj']}}}
+        if self.notification_url:
+            body['notification_url'] = self.notification_url
+        expires_at = None
+        if method['type'] == 'pix':
+            body['payment_method_id'] = 'pix'
+            expires_at = (datetime.now(BRASILIA) + timedelta(minutes=PIX_MINUTES)).isoformat(timespec='milliseconds')
+            body['date_of_expiration'] = expires_at
+        elif method['type'] == 'card':
+            body.update(token=method['token'], payment_method_id=method['payment_method_id'],
+                        installments=int(method.get('installments', 1)))
+            # 3-D Secure (the bank's confirmation) only for debit, which needs
+            # it; asking it of every card was refused as a rule (10113).
+            if method['payment_method_id'].startswith('deb'):
+                body['three_d_secure_mode'] = 'optional'
+            if method.get('payer_document_type') and method.get('payer_document'):
+                body['payer']['identification'] = {'type': method['payer_document_type'],
+                                                   'number': method['payer_document']}
+            # No issuer_id: Mercado Pago takes the issuer from the card number.
+            # The form's suggestion was refused for its own test cards
+            # (10111, "the issuer does not have the BIN configured").
+        else:
+            raise ValueError('Unsupported payment method')
+        # A PIX retry must return the same code; a new one, after the last
+        # expired, is the next attempt. A card retry after a decline is a new
+        # attempt with a new token, so the token is part of the key; the intent
+        # route refuses new attempts once one is approved or in review.
+        key = f"dtf-quote-{quote_id}-pix-{int(method.get('attempt', 1))}" if method['type'] == 'pix' else \
+            f"dtf-quote-{quote_id}-card-{hashlib.sha256(method['token'].encode()).hexdigest()[:24]}"
+        response = self.http.post('/v1/payments', json=body, headers={'X-Idempotency-Key': key})
+        response.raise_for_status()
+        payment = response.json()
+        transaction = (payment.get('point_of_interaction') or {}).get('transaction_data') or {}
+        # A payment waiting for 3-D Secure carries the bank's challenge page,
+        # which the Site shows in a frame by posting `creq` to that address.
+        three_ds = payment.get('three_ds_info') or {}
+        challenge = ({'url': three_ds['external_resource_url'], 'creq': three_ds['creq']}
+                     if payment.get('status_detail') == 'pending_challenge'
+                     and three_ds.get('external_resource_url') and three_ds.get('creq') else None)
+        return {'provider': self.name, 'id': str(payment['id']),
+                'status': STATUSES.get(payment.get('status'), 'pending'),
+                'status_detail': payment.get('status_detail'),
+                'total_cents': total_cents,
+                'pix_qr_code': transaction.get('qr_code'),
+                'pix_qr_code_base64': transaction.get('qr_code_base64'),
+                'ticket_url': transaction.get('ticket_url'),
+                'expires_at': payment.get('date_of_expiration') or expires_at,
+                'challenge': challenge}
+
+    def lookup(self, payment_id: str) -> dict:
+        response = self.http.get(f'/v1/payments/{payment_id}')
+        response.raise_for_status()
+        return response.json()
+
+    # Webhooks ------------------------------------------------------------
+
+    def verify(self, headers: Mapping[str, str], body: bytes, query: Mapping[str, str] | None = None) -> bool:
+        signature = headers.get('x-signature') or ''
+        parts = dict(part.strip().split('=', 1) for part in signature.split(',') if '=' in part)
+        ts, supplied = parts.get('ts', ''), parts.get('v1', '')
+        if not ts.isdigit() or not supplied:
+            return False
+        if abs(self.clock() - int(ts[:10])) > MAX_SIGNATURE_AGE:
+            return False
+        data_id = (query or {}).get('data.id', '')
+        if data_id.isalnum():
+            data_id = data_id.lower()
+        manifest = ''
+        if data_id:
+            manifest += f'id:{data_id};'
+        request_id = headers.get('x-request-id') or ''
+        if request_id:
+            manifest += f'request-id:{request_id};'
+        manifest += f'ts:{ts};'
+        expected = hmac.new(self.webhook_secret, manifest.encode(), hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, supplied.lower())
+
+    def parse(self, body: bytes, query: Mapping[str, str] | None = None) -> PaymentEvent | None:
+        try:
+            data = json.loads(body)
+        except ValueError:
+            return None
+        if not isinstance(data, dict) or data.get('type') != 'payment':
+            return None
+        payment_id = str((query or {}).get('data.id') or (data.get('data') or {}).get('id') or '')
+        if not payment_id.isdigit():
+            return None
+        try:
+            payment = self.lookup(payment_id)
+        except httpx.HTTPStatusError as error:
+            # Signed by Mercado Pago but about no payment of ours, such as the
+            # panel's "Simular notificação". Anything else is raised so that a
+            # real notification is retried.
+            if error.response.status_code == 404:
+                return None
+            raise
+        return event_from_payment(payment, notification_id=str(data.get('id', '')))
+
+
+def event_from_payment(payment: dict, notification_id: str = '') -> PaymentEvent:
+    """Normalise a payment fetched from the API. Amount is None unless it is BRL
+    and a whole number of centavos, so a foreign or malformed amount is refused."""
+    amount = None
+    if payment.get('currency_id') == 'BRL':
+        try:
+            cents = Decimal(str(payment.get('transaction_amount'))) * 100
+            if cents == cents.to_integral_value():
+                amount = int(cents)
+        except (InvalidOperation, TypeError, ValueError):
+            amount = None
+    status = STATUSES.get(payment.get('status'), 'pending')
+    # One event per payment state: a notification id alone would let the same
+    # approval be applied twice under two notifications, and would collapse a
+    # later refund into the earlier approval.
+    event_id = f"{payment.get('id')}:{payment.get('status')}"
+    return PaymentEvent(event_id=event_id, reference=str(payment.get('external_reference') or ''),
+                        status=status, amount_cents=amount,
+                        raw={'provider': 'mercadopago', 'payment_id': str(payment.get('id')),
+                             'status': payment.get('status'), 'status_detail': payment.get('status_detail'),
+                             'currency_id': payment.get('currency_id'),
+                             'transaction_amount': payment.get('transaction_amount'),
+                             'date_approved': payment.get('date_approved'),
+                             'notification_id': notification_id})

app/mercadopago_probe.py

@@ -0,0 +1,65 @@
+"""Read-only look at the Mercado Pago account behind MP_ACCESS_TOKEN.
+
+    python -m app.mercadopago_probe [--bin 503143] [--valor 50]
+
+Run from the api container's console (Portainer > Containers > api >
+Console), or with "Verificar conta" on the Kanban's Integrations tab. It creates nothing and charges nothing: it asks Mercado Pago which
+account the token belongs to, which card methods the account accepts, and how
+it classifies a card number's first digits (type, issuer, instalments). That
+is what payment errors such as 10111 (issuer) and 10113 (method excluded by a
+rule) depend on.
+"""
+import argparse
+import os
+import sys
+
+import httpx
+
+from .core.secrets import load as load_secret_files
+
+API = 'https://api.mercadopago.com'
+
+
+def check(token, bin_='548083', amount='50', transport=None):
+    """The account, its card methods and how a card's first digits are read."""
+    http = httpx.Client(base_url=API, timeout=15, transport=transport,
+                        headers={'Authorization': f'Bearer {token}'})
+    result = {'token': 'test' if token.startswith('TEST-') else 'production'}
+    me = http.get('/users/me')
+    if me.status_code == 200:
+        user = me.json()
+        tags = user.get('tags') or []
+        result['account'] = {'id': user.get('id'), 'nickname': user.get('nickname'),
+                             'site': user.get('site_id'), 'test_user': 'test_user' in tags, 'tags': tags}
+    else:
+        result['account'] = {'error': f'HTTP {me.status_code}'}
+    methods = http.get('/v1/payment_methods')
+    result['cards'] = ([{'id': m.get('id'), 'type': m.get('payment_type_id'), 'status': m.get('status')}
+                        for m in methods.json() if m.get('payment_type_id') in ('credit_card', 'debit_card')]
+                       if methods.status_code == 200 else {'error': f'HTTP {methods.status_code}'})
+    options = http.get('/v1/payment_methods/installments', params={'bin': bin_, 'amount': amount})
+    result['bin'] = ([{'method': o.get('payment_method_id'), 'type': o.get('payment_type_id'),
+                       'issuer': (o.get('issuer') or {}).get('name'),
+                       'installments': [c.get('installments') for c in o.get('payer_costs') or []]}
+                      for o in options.json()]
+                     if options.status_code == 200 else {'error': f'HTTP {options.status_code} {options.text[:200]}'})
+    return result
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='python -m app.mercadopago_probe')
+    parser.add_argument('--bin', default='548083', help="the card's first six digits")
+    parser.add_argument('--valor', default='50', help='amount in reais for the instalment lookup')
+    args = parser.parse_args(argv)
+    load_secret_files()
+    token = os.environ.get('MP_ACCESS_TOKEN', '')
+    if not token:
+        print('MP_ACCESS_TOKEN is not set in this container.')
+        return 1
+    import json
+    print(json.dumps(check(token, args.bin, args.valor), indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

app/operators.py

@@ -0,0 +1,130 @@
+"""Kanban operator accounts.
+
+One shared login meant every card movement was attributed to the same name, so
+the movement history could not answer who did what. Accounts live in the
+database; `OPERATOR_EMAIL` and `OPERATOR_PASSWORD` seed the first one so an
+existing deployment keeps working unchanged.
+
+Administered from the API container, the same way the schema is:
+
+    python -m local.operators list
+    python -m local.operators add maria@example.com --name "Maria"
+    python -m local.operators password maria@example.com
+    python -m local.operators disable maria@example.com
+    python -m local.operators enable maria@example.com
+
+Passwords are read from the terminal, never from an argument, so they do not
+reach shell history or the process list.
+"""
+import getpass
+import os
+import sys
+from uuid import uuid4
+
+from .core.auth import password_hash
+from .core.db import connect
+
+MIN_PASSWORD = 12
+
+
+def seed_from_environment(cursor):
+    """Make the configured credential a real account, once.
+
+    Only inserts when that email is absent, so a password changed here is never
+    reverted by a stale environment variable on the next deploy.
+    """
+    email = os.environ.get('OPERATOR_EMAIL', '').strip().lower()
+    password = os.environ.get('OPERATOR_PASSWORD', '')
+    if not email or not password:
+        return None
+    existing = cursor.execute(
+        'SELECT id FROM dtf_local.operators WHERE email=%s', (email,)).fetchone()
+    if existing:
+        return None
+    cursor.execute(
+        'INSERT INTO dtf_local.operators(id,email,name,password_hash) VALUES(%s,%s,%s,%s)',
+        (uuid4(), email, 'Operador', password_hash(password)))
+    return email
+
+
+def _ask_password(email):
+    first = getpass.getpass(f'New password for {email}: ')
+    if len(first) < MIN_PASSWORD:
+        raise SystemExit(f'Password must be at least {MIN_PASSWORD} characters.')
+    if first != getpass.getpass('Repeat: '):
+        raise SystemExit('Passwords did not match.')
+    return first
+
+
+def add(email, name=''):
+    email = email.strip().lower()
+    with connect() as c:
+        if c.execute('SELECT id FROM dtf_local.operators WHERE email=%s', (email,)).fetchone():
+            raise SystemExit(f'{email} already exists. Use "password" or "enable".')
+        c.execute('INSERT INTO dtf_local.operators(id,email,name,password_hash) VALUES(%s,%s,%s,%s)',
+                  (uuid4(), email, name, password_hash(_ask_password(email))))
+    print(f'Added {email}.')
+
+
+def password(email):
+    email = email.strip().lower()
+    with connect() as c:
+        if not c.execute('SELECT id FROM dtf_local.operators WHERE email=%s', (email,)).fetchone():
+            raise SystemExit(f'{email} does not exist.')
+        c.execute('UPDATE dtf_local.operators SET password_hash=%s WHERE email=%s',
+                  (password_hash(_ask_password(email)), email))
+    print(f'Password changed for {email}. Existing sessions stay valid until they expire;'
+          ' run "disable" first if the account is compromised.')
+
+
+def set_active(email, active):
+    email = email.strip().lower()
+    with connect() as c:
+        updated = c.execute(
+            'UPDATE dtf_local.operators SET active=%s WHERE email=%s RETURNING email',
+            (active, email)).fetchone()
+        if not updated:
+            raise SystemExit(f'{email} does not exist.')
+        if not active:
+            # Revoke immediately: disabling must end access now, not in eight hours.
+            c.execute('DELETE FROM dtf_local.operator_sessions WHERE username=%s', (email,))
+    print(f'{email} {"enabled" if active else "disabled; open sessions revoked"}.')
+
+
+def listing():
+    with connect() as c:
+        rows = c.execute('''SELECT email,name,active,last_login_at FROM dtf_local.operators
+                            ORDER BY email''').fetchall()
+    if not rows:
+        print('No operator accounts. Set OPERATOR_EMAIL and OPERATOR_PASSWORD and run'
+              ' "python -m local.bootstrap", or add one here.')
+        return
+    for row in rows:
+        seen = row['last_login_at'].strftime('%Y-%m-%d %H:%M') if row['last_login_at'] else 'never'
+        state = 'active ' if row['active'] else 'DISABLED'
+        print(f"{state}  {row['email']:<34} {row['name'][:20]:<20} last login {seen}")
+
+
+def main(argv):
+    if not argv:
+        raise SystemExit(__doc__)
+    command, rest = argv[0], argv[1:]
+    if command == 'list':
+        return listing()
+    if not rest:
+        raise SystemExit(f'usage: python -m local.operators {command} <email>')
+    email = rest[0]
+    if command == 'add':
+        name = rest[rest.index('--name') + 1] if '--name' in rest else ''
+        return add(email, name)
+    if command == 'password':
+        return password(email)
+    if command == 'disable':
+        return set_active(email, False)
+    if command == 'enable':
+        return set_active(email, True)
+    raise SystemExit(__doc__)
+
+
+if __name__ == '__main__':
+    main(sys.argv[1:])

app/payments.py

@@ -0,0 +1,158 @@
+"""Turning a payment into an order, once.
+
+A provider may deliver the same notification several times, out of order, or
+long after the fact. None of that may produce a second order, a second charge,
+or a second WhatsApp message. Every delivery is recorded under the provider's
+own event id and applied inside one transaction, so a duplicate is a no-op and a
+crash mid-way is retried rather than half-applied.
+
+Order creation lives here rather than in a route because two paths reach it: the
+webhook, and the local development checkout. They must agree.
+"""
+from datetime import datetime, timedelta, timezone
+from uuid import UUID, uuid4
+
+from psycopg.types.json import Jsonb
+
+from .core.auth import audit
+from .printjobs import queue as queue_print_files
+from .runtime import enqueue, upload_row
+from .scanning import require_clean
+
+QUOTE_VALID_HOURS = 24
+
+
+class PaymentRefused(Exception):
+    """The payment cannot become an order, with a reason worth recording."""
+
+
+def approved_quote(c, quote_id, owner=None):
+    """The reviewed quote behind a payment, or a refusal explaining why not."""
+    sql = 'SELECT * FROM dtf_local.quotes WHERE id=%s' + (' AND owner=%s' if owner else '')
+    row = c.execute(sql + ' FOR UPDATE', (quote_id, owner) if owner else (quote_id,)).fetchone()
+    if not row:
+        raise PaymentRefused('quote not found')
+    if not row['approved']:
+        raise PaymentRefused('quote was never reviewed')
+    if any(item.get('production', {}).get('version') != 2 for item in row['approved']['items']):
+        raise PaymentRefused('quote uses an obsolete production layout; request a new quote')
+    if row['approved_at'] < datetime.now(timezone.utc) - timedelta(hours=QUOTE_VALID_HOURS):
+        raise PaymentRefused('quote expired before payment')
+    return row
+
+
+TEST_PROVIDER = 'teste'
+
+
+def is_test(order):
+    """An operator's test order: it goes through production and notifies no one."""
+    return (order.get('payment') or {}).get('provider') == TEST_PROVIDER
+
+
+# How long a file is kept while nothing has been paid for it. A cart's files
+# are uploaded before payment, so the price and the security check are done on
+# the file itself; a cart that is never paid must not keep them for 30 days.
+UNPAID_HOLD = '2 days'
+# A quote waiting for an operator's review keeps its files this long.
+REVIEW_HOLD = '7 days'
+# Once paid, the order keeps its originals for this long from the upload.
+ORDER_RETENTION = '30 days'
+
+
+def quote_uploads(quote_or_draft):
+    return [uid for item in quote_or_draft['items'] for uid in item['uploads']]
+
+
+def hold_uploads(c, upload_ids, interval):
+    """Keep these files at least `interval` from now; never shortens a hold."""
+    c.execute('''UPDATE dtf_local.uploads SET expires_at=GREATEST(expires_at, now()+%s::interval)
+        WHERE id=ANY(%s) AND purged_at IS NULL''', (interval, [str(u) for u in upload_ids]))
+
+
+def create_order(c, quote, payment):
+    """Create the order for a reviewed quote, or return the one already there.
+
+    Returns (order, created). The caller decides what to do about a duplicate;
+    the important part is that asking twice cannot produce two orders, because
+    orders.quote_id is unique and this runs inside the caller's transaction.
+    """
+    existing = c.execute('SELECT * FROM dtf_local.orders WHERE quote_id=%s', (quote['id'],)).fetchone()
+    if existing:
+        return existing, False
+
+    approved = quote['approved']
+    for item in approved['items']:
+        for upload_id in item['uploads']:
+            require_clean(upload_row(c, UUID(upload_id), quote['owner']))
+
+    order = c.execute(
+        'INSERT INTO dtf_local.orders(id,quote_id,owner,snapshot,payment) VALUES(%s,%s,%s,%s,%s) RETURNING *',
+        (uuid4(), quote['id'], quote['owner'], Jsonb(approved), Jsonb(payment))).fetchone()
+    # Paid: the files are kept for the order's retention, counted from upload.
+    c.execute('''UPDATE dtf_local.uploads SET expires_at=GREATEST(expires_at, created_at+%s::interval)
+        WHERE id=ANY(%s) AND purged_at IS NULL''', (ORDER_RETENTION, quote_uploads(approved)))
+    queue_print_files(c, order['id'], len(approved['items']))
+    if is_test(order):
+        return order, True
+    for provider in ('tiny', 'whatsapp'):
+        enqueue(c, f"{order['id']}:paid:{provider}", provider,
+                {'order_id': str(order['id']), 'number': order['number'],
+                 'event': 'payment_approved', 'order': approved})
+    return order, True
+
+
+def record(c, provider, event):
+    """Store a delivery. Returns None if this exact event was already seen."""
+    inserted = c.execute(
+        '''INSERT INTO dtf_local.payment_events(id,provider,event_id,reference,status,amount_cents,payload)
+           VALUES(%s,%s,%s,%s,%s,%s,%s) ON CONFLICT(provider,event_id) DO NOTHING RETURNING *''',
+        (uuid4(), provider, event.event_id, event.reference, event.status,
+         event.amount_cents, Jsonb(event.raw))).fetchone()
+    return inserted
+
+
+def apply(c, event):
+    """Act on a payment notification. Returns the outcome recorded against it.
+
+    Outcomes starting 'refused' (money arrived, no order) or 'attention' (an
+    order exists but its payment was reversed) stay on the Kanban until an
+    operator records a resolution.
+    """
+    provider_id = event.raw.get('payment_id')
+    if provider_id:
+        c.execute('''UPDATE dtf_local.payment_intents SET status=%s, updated_at=now()
+            WHERE provider_payment_id=%s''', (event.status, provider_id))
+    if event.status in ('refunded', 'cancelled'):
+        try:
+            order = c.execute('SELECT number FROM dtf_local.orders WHERE quote_id=%s',
+                              (UUID(event.reference),)).fetchone()
+        except (ValueError, AttributeError):
+            order = None
+        if order:
+            audit('payment_reversed', order=order['number'], status=event.status)
+            return f"attention: payment {event.status} for order {order['number']}"
+    if event.status != 'approved':
+        return f'ignored: {event.status}'
+
+    try:
+        quote_id = UUID(event.reference)
+    except (ValueError, AttributeError):
+        return 'refused: reference is not a quote id'
+
+    try:
+        quote = approved_quote(c, quote_id)
+    except PaymentRefused as refusal:
+        return f'refused: {refusal}'
+
+    # The provider is the authority on what was paid, and the reviewed quote is
+    # the authority on what was owed. If they disagree, no order is created:
+    # underpayment would ship artwork that was not paid for, and overpayment
+    # means something is wrong that a person should look at.
+    expected = quote['approved']['total_cents']
+    if type(event.amount_cents) is not int or event.amount_cents != expected:
+        audit('payment_amount_mismatch', quote=str(quote_id),
+              expected_cents=expected, paid_cents=event.amount_cents)
+        return f'refused: paid {event.amount_cents} but quote total is {expected}'
+
+    order, created = create_order(c, quote, {'provider': event.raw.get('provider', 'webhook'), **event.raw})
+    return f"order {order['number']}" + ('' if created else ' (already existed)')

app/printfile.py

@@ -0,0 +1,489 @@
+"""The print file: the reviewed layout, reproduced exactly, at the film's size.
+
+The customer is quoted on a layout the Site computes: each copy of each artwork
+at a width, rotation, mirror and position on the film. Production spec v2 keeps
+that layout through the approved order. This module turns it into one PDF per
+order item, with a page exactly as wide as the film and as long as the layout,
+so the operator imports what the customer approved instead of rebuilding it.
+
+Each source image is embedded once, at its original resolution, and every copy
+is a placement of it. Nothing is resampled: a 300 DPI artwork is still 300 DPI
+in the file, a JPEG keeps its original bytes, and transparency survives as a
+soft mask. The output is therefore about the size of the artwork, not of a
+57 cm x 20 m raster, and it never needs that raster in memory.
+
+Raster sources are JPEG, PNG, WebP and TIFF. A single-page PDF is placed as a
+vector form, never rasterised. Anything else (PSD, AI, CDR, multi-page or
+protected PDFs), or a file whose proportions do not match the size it was
+quoted at, is refused with a reason, and the operator prepares that item by
+hand exactly as before.
+"""
+import math
+import os
+import tempfile
+import zlib
+from decimal import Decimal
+
+from PIL import Image, ImageOps
+
+PT_PER_CM = 72 / 2.54
+# Acrobat's page limit. Longer layouts scale user space with /UserUnit (PDF 1.6)
+# rather than cutting the film into pages a RIP might print with gaps.
+MAX_PAGE_PT = 14400
+# How far a file's proportions may drift from the quoted size before the item
+# is refused: rounding in the Site keeps real files well inside this.
+ASPECT_TOLERANCE = 0.01
+# The quote may round up (10 cm steps, 1 m minimum) but never down.
+HEIGHT_TOLERANCE_CM = Decimal('0.05')
+SUPPORTED_FORMATS = {'JPEG', 'PNG', 'WEBP', 'TIFF'}
+STRIP_ROWS = 256
+# Decoding holds the whole image in memory (about 4 bytes a pixel). 57 cm x 3 m
+# at 300 DPI is 239 Mpx; above this the item goes to the operator instead.
+MAX_DECODED_PIXELS = int(os.environ.get('PRINT_MAX_PIXELS', '250000000'))
+# Pillow's own bomb guard would refuse a genuine long sheet before we can
+# decide; the explicit limit above is the one that applies.
+Image.MAX_IMAGE_PIXELS = None
+
+
+class Unsupported(Exception):
+    """This item cannot be generated automatically. The reason is shown to the
+    operator on the Kanban, so it is written in Portuguese."""
+
+
+class Name(str):
+    pass
+
+
+class Ref(int):
+    pass
+
+
+def serialize(value):
+    if isinstance(value, Ref):
+        return b'%d 0 R' % value
+    if isinstance(value, Name):
+        return b'/' + value.encode('ascii')
+    if isinstance(value, bool):
+        return b'true' if value else b'false'
+    if isinstance(value, int):
+        return b'%d' % value
+    if isinstance(value, (float, Decimal)):
+        text = f'{float(value):.4f}'.rstrip('0').rstrip('.')
+        return (text if text not in ('', '-0') else '0').encode('ascii')
+    if isinstance(value, dict):
+        return b'<<' + b''.join(b'/' + k.encode('ascii') + b' ' + serialize(v)
+                                for k, v in value.items()) + b'>>'
+    if isinstance(value, (list, tuple)):
+        return b'[' + b' '.join(serialize(v) for v in value) + b']'
+    if isinstance(value, str):
+        escaped = value.replace('\\', '\\\\').replace('(', '\\(').replace(')', '\\)')
+        return b'(' + escaped.encode('latin-1', 'replace') + b')'
+    raise TypeError(f'Cannot serialize {type(value).__name__}')
+
+
+class PdfWriter:
+    """A sequential PDF writer: objects go straight to the file, streams included.
+
+    Stream lengths are indirect objects written after the data, so an image is
+    compressed strip by strip into the output without being held in memory.
+    """
+
+    def __init__(self, fp):
+        self.fp = fp
+        self.offsets = {}
+        self.next_id = 1
+        self.write(b'%PDF-1.6\n%\xe2\xe3\xcf\xd3\n')
+
+    def write(self, data):
+        self.fp.write(data)
+
+    def tell(self):
+        return self.fp.tell()
+
+    def alloc(self):
+        ref = Ref(self.next_id)
+        self.next_id += 1
+        return ref
+
+    def obj(self, value, ref=None):
+        ref = ref or self.alloc()
+        self.offsets[ref] = self.tell()
+        self.write(b'%d 0 obj\n' % ref + serialize(value) + b'\nendobj\n')
+        return ref
+
+    def stream(self, dictionary, chunks, ref=None):
+        """Write a stream from an iterable of already-encoded byte chunks."""
+        ref = ref or self.alloc()
+        length = self.alloc()
+        self.offsets[ref] = self.tell()
+        self.write(b'%d 0 obj\n' % ref + serialize({**dictionary, 'Length': length}) + b'\nstream\n')
+        start = self.tell()
+        for chunk in chunks:
+            self.write(chunk)
+        size = self.tell() - start
+        self.write(b'\nendstream\nendobj\n')
+        self.obj(size, length)
+        return ref
+
+    def finish(self, root, info):
+        xref = self.tell()
+        count = self.next_id
+        self.write(b'xref\n0 %d\n0000000000 65535 f \n' % count)
+        for ref in range(1, count):
+            self.write(b'%010d 00000 n \n' % self.offsets[ref])
+        self.write(b'trailer\n' + serialize({'Size': count, 'Root': root, 'Info': info}) +
+                   b'\nstartxref\n%d\n%%%%EOF\n' % xref)
+
+
+def deflate(pieces):
+    compressor = zlib.compressobj(6)
+    for piece in pieces:
+        out = compressor.compress(piece)
+        if out:
+            yield out
+    yield compressor.flush()
+
+
+class SourceImage:
+    """One customer file, opened for reading pixels and measured as the browser sees it."""
+
+    def __init__(self, path, name):
+        self.path = path
+        self.name = name
+        try:
+            self.image = Image.open(path)
+            self.format = self.image.format
+        except Image.DecompressionBombError as exc:
+            raise Unsupported(f'"{name}" é grande demais para gerar automaticamente') from exc
+        except Exception as exc:
+            raise Unsupported(f'"{name}" não é uma imagem que o gerador consiga ler') from exc
+        if self.format not in SUPPORTED_FORMATS:
+            raise Unsupported(f'"{name}" está em {self.format or "formato desconhecido"}; '
+                              'só JPEG, PNG, WebP, TIFF e PDF são gerados automaticamente')
+        if getattr(self.image, 'n_frames', 1) > 1 and self.format != 'TIFF':
+            raise Unsupported(f'"{name}" é animado ou tem vários quadros')
+        # Browsers draw a photo upright according to its EXIF orientation, and
+        # the Site measured it that way, so the print must too.
+        try:
+            self.orientation = self.image.getexif().get(0x0112, 1)
+        except Exception:
+            self.orientation = 1
+        width, height = self.image.size
+        self.size = (height, width) if self.orientation in (5, 6, 7, 8) else (width, height)
+
+    def passthrough(self):
+        """Whether the original JPEG bytes can go into the PDF unchanged."""
+        return (self.format == 'JPEG' and self.orientation == 1 and
+                self.image.mode in ('L', 'RGB', 'CMYK'))
+
+    def embed(self, pdf):
+        """Write this image (and its alpha) as XObjects; returns the image reference."""
+        if self.passthrough():
+            return self._embed_jpeg(pdf)
+        width, height = self.image.size
+        if width * height > MAX_DECODED_PIXELS:
+            raise Unsupported(f'"{self.name}" tem {width} × {height} px, mais do que o '
+                              'gerador processa; prepare este item à mão')
+        return self._embed_pixels(pdf)
+
+    def _colorspace(self, pdf, mode):
+        components = {'L': 1, 'RGB': 3, 'CMYK': 4}[mode]
+        device = Name({'L': 'DeviceGray', 'RGB': 'DeviceRGB', 'CMYK': 'DeviceCMYK'}[mode])
+        profile = self.image.info.get('icc_profile')
+        if not profile:
+            return device
+        icc = pdf.stream({'N': components, 'Alternate': device, 'Filter': Name('FlateDecode')},
+                         deflate([profile]))
+        return [Name('ICCBased'), icc]
+
+    def _embed_jpeg(self, pdf):
+        image = self.image
+        extra = {}
+        if image.mode == 'CMYK' and 'adobe' in image.info:
+            # Adobe writes CMYK JPEGs inverted; PDF readers expect the Decode flip.
+            extra['Decode'] = [1, 0, 1, 0, 1, 0, 1, 0]
+
+        def chunks():
+            with open(self.path, 'rb') as source:
+                while block := source.read(1 << 20):
+                    yield block
+        return pdf.stream({'Type': Name('XObject'), 'Subtype': Name('Image'),
+                           'Width': image.width, 'Height': image.height,
+                           'ColorSpace': self._colorspace(pdf, image.mode),
+                           'BitsPerComponent': 8, 'Filter': Name('DCTDecode'), **extra},
+                          chunks())
+
+    def _upright(self):
+        image = self.image
+        image.load()
+        if self.orientation != 1:
+            image = ImageOps.exif_transpose(image)
+        return image
+
+    def _embed_pixels(self, pdf):
+        image = self._upright()
+        mode = image.mode
+        has_alpha = mode in ('RGBA', 'LA', 'PA', 'RGBa', 'La') or (
+            mode == 'P' and 'transparency' in image.info) or (
+            mode in ('L', 'RGB') and 'transparency' in image.info)
+        if mode in ('I;16', 'I;16B', 'I;16L', 'I'):
+            image = image.convert('I').point(lambda value: value * (1 / 257)).convert('L')
+            mode = 'L'
+        if mode == 'CMYK':
+            color_mode = 'CMYK'
+        elif mode in ('1', 'L', 'LA', 'La'):
+            color_mode = 'L'
+        elif mode in ('P', 'PA', 'RGB', 'RGBA', 'RGBa'):
+            color_mode = 'RGB'
+        else:
+            raise Unsupported(f'"{self.name}" usa o modo de cor {mode}, que não é gerado automaticamente')
+        if has_alpha:
+            image = image.convert('RGBA' if color_mode == 'RGB' else 'LA')
+        width, height = image.size
+
+        def strips(convert):
+            for top in range(0, height, STRIP_ROWS):
+                yield convert(image.crop((0, top, width, min(height, top + STRIP_ROWS)))).tobytes()
+
+        smask = None
+        if has_alpha:
+            smask = pdf.stream({'Type': Name('XObject'), 'Subtype': Name('Image'),
+                                'Width': width, 'Height': height,
+                                'ColorSpace': Name('DeviceGray'), 'BitsPerComponent': 8,
+                                'Filter': Name('FlateDecode')},
+                               deflate(strips(lambda strip: strip.getchannel('A'))))
+        colorspace = self._colorspace(pdf, color_mode)
+        dictionary = {'Type': Name('XObject'), 'Subtype': Name('Image'),
+                      'Width': width, 'Height': height, 'ColorSpace': colorspace,
+                      'BitsPerComponent': 8, 'Filter': Name('FlateDecode')}
+        if smask:
+            dictionary['SMask'] = smask
+        return pdf.stream(dictionary, deflate(strips(lambda strip: strip.convert(color_mode))))
+
+    def close(self):
+        self.image.close()
+
+
+def placement_matrix(placement, page_height_pt):
+    """Map the image's unit square onto its box on the film.
+
+    Matches the Site's canvas: the artwork is mirrored first, then turned
+    clockwise about the centre of its box, and the turned image fills the box.
+    """
+    x = float(placement['x_cm']) * PT_PER_CM
+    top = page_height_pt - float(placement['y_cm']) * PT_PER_CM
+    w = float(placement['width_cm']) * PT_PER_CM
+    h = float(placement['length_cm']) * PT_PER_CM
+    rotation = placement['rotation_degrees'] % 360
+    mirrored = placement['mirrored']
+
+    def to_page(u, v):
+        # Unit square (v up) -> image frame (s right, t down).
+        s, t = u, 1 - v
+        if mirrored:
+            s = 1 - s
+        s, t = {0: (s, t), 90: (1 - t, s), 180: (1 - s, 1 - t), 270: (t, 1 - s)}[rotation]
+        return x + s * w, top - t * h
+
+    ox, oy = to_page(0, 0)
+    ax, ay = to_page(1, 0)
+    cx, cy = to_page(0, 1)
+    return [ax - ox, ay - oy, cx - ox, cy - oy, ox, oy]
+
+
+class PdfPage:
+    """One page of a customer PDF, placed as a vector form: nothing is rasterised.
+
+    The box and orientation are the ones the Site measured with pdf.js: the
+    CropBox (which pikepdf uses for the form's BBox), turned by the page's
+    /Rotate, inherited or not.
+    """
+
+    def __init__(self, path, name):
+        import pikepdf
+        self.name = name
+        try:
+            self.pdf = pikepdf.open(path)
+        except pikepdf.PasswordError as exc:
+            raise Unsupported(f'"{name}" está protegido por senha') from exc
+        except Exception as exc:
+            raise Unsupported(f'"{name}" não é um PDF que o gerador consiga ler') from exc
+        try:
+            pages = len(self.pdf.pages)
+            if pages != 1:
+                raise Unsupported(f'"{name}" tem {pages} páginas; só PDFs de uma página são gerados automaticamente')
+            self.page = self.pdf.pages[0]
+            self.rotation = int(self.page.rotation) % 360
+            if self.rotation not in (0, 90, 180, 270):
+                raise Unsupported(f'"{name}" tem uma rotação de página não suportada')
+            box = [float(v) for v in self.page.cropbox]
+        except Unsupported:
+            self.pdf.close()
+            raise
+        except Exception as exc:
+            self.pdf.close()
+            raise Unsupported(f'"{name}" tem uma página que o gerador não consegue ler') from exc
+        self.x0, self.y0 = min(box[0], box[2]), min(box[1], box[3])
+        self.w, self.h = abs(box[2] - box[0]), abs(box[3] - box[1])
+        if self.w <= 0 or self.h <= 0:
+            self.pdf.close()
+            raise Unsupported(f'"{name}" tem uma página vazia')
+        # As displayed, which is what the proportions are checked against.
+        self.size = (self.h, self.w) if self.rotation in (90, 270) else (self.w, self.h)
+
+    def normalise(self):
+        """Matrix from the page's box, as displayed, onto the unit square."""
+        a, d = 1 / self.w, 1 / self.h
+        scale = [a, 0, 0, d, -self.x0 * a, -self.y0 * d]
+        turn = {0: [1, 0, 0, 1, 0, 0], 90: [0, -1, 1, 0, 0, 1],
+                180: [-1, 0, 0, -1, 1, 1], 270: [0, 1, -1, 0, 1, 0]}[self.rotation]
+        return multiply(scale, turn)
+
+    def form(self, target):
+        """The page as a form XObject copied into the target document."""
+        form = self.page.as_form_xobject(handle_transformations=False)
+        group = self.page.obj.get('/Group')
+        if group is not None and '/Group' not in form:
+            form.Group = group
+        return target.copy_foreign(form)
+
+    def close(self):
+        self.pdf.close()
+
+
+def multiply(first, then):
+    """PDF matrices: a point transformed by `first`, then by `then`."""
+    a1, b1, c1, d1, e1, f1 = first
+    a2, b2, c2, d2, e2, f2 = then
+    return [a1 * a2 + b1 * c2, a1 * b2 + b1 * d2, c1 * a2 + d1 * c2, c1 * b2 + d1 * d2,
+            e1 * a2 + f1 * c2 + e2, e1 * b2 + f1 * d2 + f2]
+
+
+def open_source(path, name):
+    with open(path, 'rb') as handle:
+        head = handle.read(1024)
+    if b'%PDF-' in head:
+        return PdfPage(path, name)
+    return SourceImage(path, name)
+
+
+def check_layout(item, sizes, vector=()):
+    """Refuse a layout the file cannot reproduce faithfully. Returns the lowest
+    DPI of the raster sources (vector pages have none)."""
+    production = item['production']
+    height = Decimal(str(production['height_cm']))
+    billed = Decimal(str(item['billed_metres'])) * 100
+    if height > billed + HEIGHT_TOLERANCE_CM:
+        raise Unsupported(f'a montagem tem {height} cm, mas só {billed} cm foram cobrados')
+    lowest = None
+    for placement in production['placements']:
+        width_px, height_px = sizes[placement['source_index']]
+        if placement['rotation_degrees'] % 180 == 90:
+            width_px, height_px = height_px, width_px
+        width_cm = float(placement['width_cm'])
+        length_cm = float(placement['length_cm'])
+        drift = abs((width_px / height_px) / (width_cm / length_cm) - 1)
+        if drift > ASPECT_TOLERANCE:
+            source = production['sources'][placement['source_index']]
+            raise Unsupported(f'o arquivo {placement["source_index"] + 1} tem proporções diferentes '
+                              f'das cotadas ({source["width_cm"]} × {source["length_cm"]} cm)')
+        if placement['source_index'] in vector:
+            continue
+        dpi = width_px / (width_cm / 2.54)
+        lowest = dpi if lowest is None else min(lowest, dpi)
+    return lowest
+
+
+def render(item, files, out, title):
+    """Write the PDF for one approved order item.
+
+    `files` maps each source index to (local path, original name). Returns the
+    evidence the Kanban shows: page size, what was billed, and the lowest DPI.
+
+    Raster sources are written by the streaming writer above. PDF sources are
+    then added as vector forms by a second pass through pikepdf, so a sheet
+    exported as PDF keeps its vectors, fonts and transparency.
+    """
+    production = item['production']
+    if production.get('version') != 2:
+        raise Unsupported('o item usa uma montagem antiga')
+    sources = []
+    try:
+        for index in range(len(production['sources'])):
+            path, name = files[index]
+            sources.append(open_source(path, name))
+        vector = {index for index, source in enumerate(sources) if isinstance(source, PdfPage)}
+        lowest_dpi = check_layout(item, [source.size for source in sources], vector)
+
+        width_pt = float(production['film_width_cm']) * PT_PER_CM
+        height_pt = float(production['height_cm']) * PT_PER_CM
+        unit = max(1, math.ceil(max(width_pt, height_pt) / MAX_PAGE_PT))
+
+        first = tempfile.TemporaryFile() if vector else out
+        try:
+            write_rasters(production, sources, first, title, width_pt, height_pt, unit)
+            if vector:
+                first.seek(0)
+                add_vector_pages(production, sources, first, out, height_pt)
+        finally:
+            if vector:
+                first.close()
+    finally:
+        for source in sources:
+            source.close()
+    return {'film_width_cm': str(production['film_width_cm']),
+            'height_cm': str(production['height_cm']),
+            'billed_metres': str(item['billed_metres']),
+            'placements': len(production['placements']),
+            'sources': len(sources),
+            'vector_sources': len(vector),
+            'min_dpi': round(lowest_dpi) if lowest_dpi else None,
+            'user_unit': unit}
+
+
+def write_rasters(production, sources, out, title, width_pt, height_pt, unit):
+    pdf = PdfWriter(out)
+    images = {index: source.embed(pdf) for index, source in enumerate(sources)
+              if isinstance(source, SourceImage)}
+    # The user-space scale is not wrapped in q/Q, so it also applies to the
+    # vector placements appended by the second pass.
+    commands = [b'%s 0 0 %s 0 0 cm\n' % (serialize(1 / unit), serialize(1 / unit))] if unit > 1 else []
+    for placement in production['placements']:
+        if placement['source_index'] not in images:
+            continue
+        matrix = placement_matrix(placement, height_pt)
+        commands.append(b'q ' + b' '.join(serialize(v) for v in matrix) +
+                        b' cm /Im%d Do Q\n' % placement['source_index'])
+    content = pdf.stream({'Filter': Name('FlateDecode')}, deflate(commands))
+    pages = pdf.alloc()
+    page_box = [0, 0, width_pt / unit, height_pt / unit]
+    page = {'Type': Name('Page'), 'Parent': pages, 'MediaBox': page_box, 'TrimBox': page_box,
+            'Resources': {'XObject': {f'Im{index}': ref for index, ref in images.items()}},
+            'Contents': content}
+    if unit > 1:
+        page['UserUnit'] = unit
+    page_ref = pdf.obj(page)
+    pdf.obj({'Type': Name('Pages'), 'Kids': [page_ref], 'Count': 1}, pages)
+    root = pdf.obj({'Type': Name('Catalog'), 'Pages': pages})
+    info = pdf.obj({'Title': title, 'Producer': 'DTF System print-file generator'})
+    pdf.finish(root, info)
+
+
+def add_vector_pages(production, sources, first, out, height_pt):
+    import pikepdf
+    with pikepdf.open(first) as document:
+        page = document.pages[0]
+        xobjects = page.obj.Resources.XObject
+        for index, source in enumerate(sources):
+            if isinstance(source, PdfPage):
+                xobjects[f'/Pdf{index}'] = source.form(document)
+        commands = []
+        for placement in production['placements']:
+            source = sources[placement['source_index']]
+            if not isinstance(source, PdfPage):
+                continue
+            matrix = multiply(source.normalise(), placement_matrix(placement, height_pt))
+            commands.append(b'q ' + b' '.join(serialize(v) for v in matrix) +
+                            b' cm /Pdf%d Do Q\n' % placement['source_index'])
+        page.contents_add(pikepdf.Stream(document, b''.join(commands)), prepend=False)
+        document.save(out, min_version='1.6')

app/printjobs.py

@@ -0,0 +1,180 @@
+"""Generating print files in the background, one order item at a time.
+
+A paid order queues one job per item. The worker claims a job, commits the
+claim, and renders outside any transaction, so a long render never holds a row
+lock or a database connection. A claim older than CLAIM_TIMEOUT is assumed to
+belong to a worker that died and is taken again.
+
+The result is an ordinary upload row owned by an identity derived from the
+order, already marked clean: its only inputs are artwork that passed the
+malware scan, and the bytes are written here. The operator still decides
+whether it becomes the final file; generation never approves anything.
+
+Sheets of several GB are the normal order, and decoding one would take more
+memory than the worker has. A source above LARGE_SOURCE_BYTES is never
+opened: a finished sheet placed whole on the film is already its own print
+file, so the original becomes the print file; any other layout is prepared
+by hand from the original.
+"""
+import logging
+import os
+import tempfile
+import time
+from datetime import timedelta
+from uuid import NAMESPACE_URL, UUID, uuid4, uuid5
+
+from psycopg.types.json import Jsonb
+
+from .core.auth import audit
+from .core.db import connect
+from .printfile import Unsupported, render
+
+CLAIM_TIMEOUT = timedelta(minutes=15)
+MAX_ATTEMPTS = 3
+LARGE_SOURCE_BYTES = int(os.environ.get('PRINT_DECODE_MAX_BYTES', str(300 * 1024 * 1024)))
+# Formats the operator can import as they are.
+PRINTABLE_ORIGINAL = ('.png', '.jpg', '.jpeg', '.tif', '.tiff', '.pdf')
+
+
+def generated_identity(order_id):
+    return uuid5(NAMESPACE_URL, f'dtf-print-file:{order_id}')
+
+
+def queue(c, order_id, items, only_missing=False):
+    """Queue (or re-queue) generation for every item of an order."""
+    for index in range(items):
+        if only_missing:
+            c.execute('''INSERT INTO dtf_local.print_files(id,order_id,item_index) VALUES(%s,%s,%s)
+                ON CONFLICT(order_id,item_index) DO UPDATE SET status='pending', attempts=0,
+                  claimed_at=NULL, finished_at=NULL, detail='{}'
+                WHERE dtf_local.print_files.status IN ('failed','manual')''',
+                      (uuid4(), order_id, index))
+        else:
+            c.execute('''INSERT INTO dtf_local.print_files(id,order_id,item_index) VALUES(%s,%s,%s)
+                ON CONFLICT(order_id,item_index) DO NOTHING''', (uuid4(), order_id, index))
+
+
+def claim(c):
+    return c.execute('''SELECT p.*, o.snapshot, o.number FROM dtf_local.print_files p
+        JOIN dtf_local.orders o ON o.id=p.order_id
+        WHERE p.status='pending' OR (p.status='rendering' AND p.claimed_at < now()-%s)
+        ORDER BY p.created_at FOR UPDATE OF p SKIP LOCKED LIMIT 1''', (CLAIM_TIMEOUT,)).fetchone()
+
+
+def render_one(storage):
+    with connect() as c:
+        job = claim(c)
+        if not job:
+            return False
+        c.execute('''UPDATE dtf_local.print_files SET status='rendering', claimed_at=now(),
+            attempts=attempts+1 WHERE id=%s''', (job['id'],))
+        item = job['snapshot']['items'][job['item_index']]
+        uploads = c.execute('''SELECT id,name,size,object_key,scan_state,purged_at,expires_at,
+            (expires_at<=now()) AS expired FROM dtf_local.uploads WHERE id=ANY(%s)''',
+            ([UUID(u) for u in item['uploads']],)).fetchall()
+        # Every generated file shares its order's artwork retention deadline.
+        expiry = c.execute('SELECT min(created_at)+interval \'30 days\' AS e FROM dtf_local.uploads WHERE id=ANY(%s)',
+                           ([UUID(u) for u in item['uploads']],)).fetchone()['e']
+    by_id = {str(row['id']): row for row in uploads}
+    if any(row['size'] > LARGE_SOURCE_BYTES for row in uploads):
+        original = whole_sheet(item, by_id)
+        if original:
+            with connect() as c:
+                c.execute('''UPDATE dtf_local.print_files SET status='ready', upload_id=%s, detail=%s,
+                    finished_at=now(), claimed_at=NULL WHERE id=%s''',
+                          (original['id'], Jsonb({'source': 'original', 'name': original['name']}), job['id']))
+            audit('print_file_original', order=str(job['order_id']), item=job['item_index'])
+        else:
+            finish(job, 'manual', {'reason': f'arquivo acima de {LARGE_SOURCE_BYTES // 1048576} MB: '
+                                             'monte a folha a partir do original'})
+            audit('print_file_manual', order=str(job['order_id']), item=job['item_index'])
+        return True
+    try:
+        result = produce(storage, job, item, by_id)
+    except Unsupported as reason:
+        finish(job, 'manual', {'reason': str(reason)})
+        audit('print_file_manual', order=str(job['order_id']), item=job['item_index'])
+        return True
+    except Exception as exc:
+        logging.exception('Print file generation failed')
+        final = job['attempts'] + 1 >= MAX_ATTEMPTS
+        finish(job, 'failed' if final else 'pending', {'error': type(exc).__name__})
+        return True
+    path, name, size, detail = result
+    try:
+        uid = uuid4()
+        key = f'originals/{uid}'
+        storage.store(key, path, 'application/pdf')
+    finally:
+        os.unlink(path)
+    with connect() as c:
+        c.execute('''INSERT INTO dtf_local.uploads(id,owner,name,size,object_key,multipart_id,complete,
+              expires_at,scan_state,scan_reason,scanned_at)
+            VALUES(%s,%s,%s,%s,%s,'',true,%s,'clean','generated from scanned artwork',now())''',
+                  (uid, generated_identity(job['order_id']), name, size, key, expiry))
+        c.execute('''UPDATE dtf_local.print_files SET status='ready', upload_id=%s, detail=%s,
+            finished_at=now() WHERE id=%s''', (uid, Jsonb(detail), job['id']))
+    audit('print_file_ready', order=str(job['order_id']), item=job['item_index'])
+    return True
+
+
+def whole_sheet(item, uploads):
+    """The original, when the item is one finished sheet placed whole, once,
+    unrotated and unmirrored, across the film: then it is the print file."""
+    spec = item.get('production') or {}
+    sources, placements = spec.get('sources') or [], spec.get('placements') or []
+    if len(item['uploads']) != 1 or len(sources) != 1 or len(placements) != 1:
+        return None
+    source, place = sources[0], placements[0]
+    row = uploads.get(item['uploads'][0])
+    if (not row or row['scan_state'] != 'clean' or row['purged_at'] or row['expired']
+            or source.get('kind') != 'sheet' or int(source.get('copies', 1)) != 1
+            or not row['name'].lower().endswith(PRINTABLE_ORIGINAL)):
+        return None
+    if (float(place['x_cm']) != 0 or float(place['y_cm']) != 0 or int(place['rotation_degrees']) != 0
+            or place['mirrored'] or abs(float(source['width_cm']) - float(spec['film_width_cm'])) > 0.5):
+        return None
+    return row
+
+
+def produce(storage, job, item, uploads):
+    """Fetch the item's artwork and render it. Returns (pdf path, name, size, evidence)."""
+    for upload_id in item['uploads']:
+        row = uploads.get(upload_id)
+        if not row or row['scan_state'] != 'clean':
+            raise Unsupported('um arquivo original está ausente ou não foi liberado pelo antivírus')
+        if row['purged_at'] or row['expired']:
+            raise Unsupported('um arquivo original passou do prazo de guarda')
+    number = job['number']
+    name = f'pedido-{number}-item-{job["item_index"] + 1}.pdf'
+    with tempfile.TemporaryDirectory(prefix='print-') as scratch:
+        files = {}
+        for index, upload_id in enumerate(item['uploads']):
+            local = os.path.join(scratch, f'source-{index}')
+            storage.fetch(uploads[upload_id]['object_key'], local)
+            files[index] = (local, uploads[upload_id]['name'])
+        handle, output = tempfile.mkstemp(prefix='print-', suffix='.pdf')
+        try:
+            with os.fdopen(handle, 'wb') as out:
+                detail = render(item, files, out, f'Pedido {number} - item {job["item_index"] + 1}')
+        except BaseException:
+            os.unlink(output)
+            raise
+    return output, name, os.path.getsize(output), detail
+
+
+def finish(job, status, detail):
+    with connect() as c:
+        c.execute('''UPDATE dtf_local.print_files SET status=%s, detail=%s,
+            finished_at=CASE WHEN %s='pending' THEN NULL ELSE now() END,
+            claimed_at=NULL WHERE id=%s''', (status, Jsonb(detail), status, job['id']))
+
+
+def render_loop(storage):
+    while True:
+        try:
+            if render_one(storage):
+                continue
+        except Exception:
+            logging.exception('Print render worker tick failed')
+        time.sleep(2)

app/quote_review.py

@@ -0,0 +1,89 @@
+"""Quote approval: automatic at checkout, by an operator for the exceptions.
+
+A quote the customer can pay is priced here from the server's own ladders,
+whether an operator approved it on the Kanban or the Site approved it the
+moment it was created. The Site is a shop: a customer who can price the order
+should be able to pay for it straight away, at any hour, so only orders a
+person must look at before charging wait for the Kanban (review_reason).
+
+The grade (and so the discount) is worked out in the customer's browser and
+checked against the files before an automatic approval (app/grade_check.py);
+a grade the files do not support waits for review. The layout is still the
+browser's (roadmap 3.9): the API checks its geometry. Operators see every
+order's grade and artwork at Arte recebida.
+"""
+import os
+from decimal import Decimal
+
+from fastapi import HTTPException
+from psycopg.types.json import Jsonb
+
+from . import payments
+from .core.pricing import price
+from .runtime import freight, upload_row
+from .scanning import require_clean
+
+AUTO = 'auto'
+
+
+def auto_approve_enabled():
+    return os.environ.get('QUOTE_AUTO_APPROVE', 'true').lower() == 'true'
+
+
+def max_auto_metres():
+    return Decimal(os.environ.get('QUOTE_AUTO_MAX_METRES', '50'))
+
+
+def review_reason(draft):
+    """Why this quote needs a person before it can be paid, or None."""
+    if not auto_approve_enabled():
+        return 'Aprovação automática desligada'
+    total = sum(Decimal(str(item['metres'])) for item in draft['items'])
+    if total > max_auto_metres():
+        return f'Pedido acima de {max_auto_metres():g} m'
+    for item in draft['items']:
+        if item.get('production', {}).get('version') != 2:
+            return 'Montagem antiga'
+        # The Site grades only the art it could analyse; anything else is
+        # priced at the full rate. A discount on it did not come from the Site.
+        if item['quality_status'] == 'unverified' and item['grade'] != 0:
+            return 'Nota informada sem análise da arte'
+    return None
+
+
+def approve(c, row, items, reviewer):
+    """Price the reviewed items and bind them to the quote; returns the approval.
+    `row` must be locked by the caller."""
+    draft = row['draft']
+    if row['approved']:
+        raise HTTPException(409, 'Approved quotes are immutable; request a new quote')
+    if any(item.get('production', {}).get('version') != 2 for item in draft['items']):
+        raise HTTPException(409, 'Quote uses an obsolete production layout; customer must request a new quote')
+    if len(items) != len(draft['items']):
+        raise HTTPException(422, 'Review must cover every item')
+    priced = []
+    for item, original in zip(items, draft['items']):
+        if item.mode != original['mode'] or list(map(str, item.uploads)) != original['uploads']:
+            raise HTTPException(422, 'Product mode and attached files cannot change during review')
+        if item.production.model_dump(mode='json') != original['production'] or item.quality_status != original['quality_status'] or item.quality_acknowledged != original['quality_acknowledged']:
+            raise HTTPException(422, 'Production instructions and customer acknowledgement cannot change during commercial review')
+        for upload_id in item.uploads:
+            require_clean(upload_row(c, upload_id, row['owner']))
+        priced.append({**price(item.mode, str(item.metres), item.grade),
+                       'uploads': original['uploads'], 'production': original['production'],
+                       'quality_status': original['quality_status'],
+                       'quality_acknowledged': original['quality_acknowledged']})
+    metres = sum(Decimal(i['billed_metres']) for i in priced)
+    try:
+        quoted_freight = freight.quote(draft['freight']['service'], draft['freight'].get('postal_code', ''),
+                                       metres, sum(i['total_cents'] for i in priced))
+    except ValueError as exc:
+        raise HTTPException(422, str(exc))
+    approved = {'customer': draft['customer'], 'items': priced, 'freight': quoted_freight,
+                'destination': draft.get('destination'),
+                'total_cents': sum(i['total_cents'] for i in priced) + quoted_freight['total_cents']}
+    c.execute('UPDATE dtf_local.quotes SET approved=%s, reviewed_by=%s, approved_at=now() WHERE id=%s',
+              (Jsonb(approved), reviewer, row['id']))
+    # Approved and payable now: the files wait for the payment, not for ever.
+    payments.hold_uploads(c, payments.quote_uploads(approved), payments.UNPAID_HOLD)
+    return approved

app/runtime.py

@@ -0,0 +1,112 @@
+"""Composition root, and the pieces every router needs.
+
+app.py held the adapters, the configuration, the shared query helpers and all
+nineteen of its routes, so customer.py could not import from it without a cycle
+and was wired instead by passing nine callables into install_routes. Everything
+shared lives here: routers import downwards, never from each other.
+"""
+import os
+from datetime import datetime, timedelta, timezone
+from uuid import uuid5, NAMESPACE_URL
+
+from fastapi import HTTPException
+from psycopg.types.json import Jsonb
+
+from .adapters import FakeFreight, FakePayment, LocalS3Storage, require_runtime
+from .core.secrets import load as load_secret_files
+
+# Secret files must resolve before any configuration below is read.
+load_secret_files()
+require_runtime()
+
+storage = LocalS3Storage()
+if os.environ.get('PAYMENT_ADAPTER') == 'mercadopago':
+    from .mercadopago import MercadoPagoPayment
+    payment = MercadoPagoPayment()
+else:
+    payment = FakePayment()
+if os.environ.get('FREIGHT_ADAPTER') == 'jadlog':
+    from .jadlog import JadlogFreight
+    freight = JadlogFreight()
+else:
+    freight = FakeFreight()
+ENVIRONMENT = os.environ.get('APP_ENV', 'local')
+PUBLIC_ORIGIN = os.environ.get('PUBLIC_ORIGIN', 'http://localhost')
+ALLOWED_HOSTS = [host for host in os.environ.get('ALLOWED_HOSTS', 'localhost,127.0.0.1').split(',') if host]
+ALLOWED_ORIGINS = [origin for origin in os.environ.get('ALLOWED_ORIGINS', PUBLIC_ORIGIN).split(',') if origin]
+# Per source and generous: a browser needs one session and keeps the cookie, but
+# offices and mobile carriers put many real customers behind one address, so a
+# tight per-IP ceiling would lock out the same people the old global one did.
+GUEST_SESSION_LIMIT = int(os.environ.get('GUEST_SESSION_LIMIT', '240'))
+# The board returned every order ever created. Finished ones are terminal, so
+# they were pure growth: at a few hundred a day the response and the page both
+# degrade with no operator benefit.
+BOARD_FINISHED_LIMIT = int(os.environ.get('BOARD_FINISHED_LIMIT', '50'))
+BOARD_QUOTE_LIMIT = int(os.environ.get('BOARD_QUOTE_LIMIT', '100'))
+PART_BYTES = int(os.environ.get('UPLOAD_PART_BYTES', '8388608'))
+if not 5242880 <= PART_BYTES <= 67108864:
+    raise RuntimeError('UPLOAD_PART_BYTES must be between 5 and 64 MiB')
+STATES = {'rec': 'Arte recebida', 'tra': 'Arte tratada', 'fil': 'Fila de impressão',
+          'imp': 'Imprimindo', 'cor': 'Correção', 'fin': 'Finalizado'}
+TRANSITIONS = {'rec': ['tra','cor'], 'tra': ['fil','cor'], 'fil': ['imp','cor'],
+               'imp': ['fin','cor'], 'cor': ['rec','tra'], 'fin': []}
+# Undoing a move made by mistake: one stage back, with an internal reason. It
+# is not a correction: the customer is not told and approved finals stay.
+BACK = {'tra': 'rec', 'fil': 'tra', 'imp': 'fil', 'fin': 'imp'}
+
+
+def require_delivery_available(service):
+    """Outside the local stack, a simulated freight price must never reach a
+    customer: until a real freight provider exists, only pickup is offered."""
+    if service != 'pickup' and ENVIRONMENT != 'local' and getattr(freight, 'name', '') == 'fake':
+        raise HTTPException(503, 'A entrega ainda não está disponível. Escolha a retirada em Franca.')
+
+
+def upload_row(c, upload_id, session_id, lock=False):
+    row = c.execute('SELECT * FROM dtf_local.uploads WHERE id=%s AND owner=%s' +
+                    (' FOR UPDATE' if lock else ''), (upload_id, session_id)).fetchone()
+    if not row:
+        raise HTTPException(404, 'Upload not found')
+    days = 30 if row['complete'] else 1
+    if row['purged_at'] or row['expires_at'] <= datetime.now(timezone.utc) or row['created_at'] < datetime.now(timezone.utc) - timedelta(days=days):
+        raise HTTPException(410, 'Upload expired; select the file again')
+    return row
+
+
+def quote_view(c, row):
+    from .quote_review import review_reason  # it imports this module
+    order = c.execute('SELECT id,number,state FROM dtf_local.orders WHERE quote_id=%s', (row['id'],)).fetchone()
+    # The latest payment attempt, so the payment page can tell a refused card
+    # (the notification updates it) from one still waiting.
+    attempt = c.execute('''SELECT method,status,response->>'status_detail' AS status_detail
+        FROM dtf_local.payment_intents WHERE quote_id=%s ORDER BY created_at DESC LIMIT 1''', (row['id'],)).fetchone()
+    expired = row['approved_at'] and row['approved_at'] < datetime.now(timezone.utc)-timedelta(hours=24)
+    return {'id': row['id'], 'created_at': row['created_at'],
+            'draft': row['draft'], 'approved': row['approved'],
+            'status': 'paid' if order else 'expired' if expired else 'approved' if row['approved'] else 'pending_review',
+            'auto_approved': row.get('reviewed_by') == 'auto',
+            'review_reason': None if row['approved'] else (row.get('review_note') or review_reason(row['draft'])),
+            'payment': attempt,
+            'order': order}
+
+
+def enqueue(c, event_key, provider, payload):
+    c.execute('INSERT INTO dtf_local.outbox(event_key,provider,payload) VALUES(%s,%s,%s) ON CONFLICT(event_key) DO NOTHING',
+              (event_key, provider, Jsonb(payload)))
+
+
+def owned_order(c, oid, identity, lock=False):
+    row = c.execute('SELECT * FROM dtf_local.orders WHERE id=%s AND owner=%s'+(' FOR UPDATE' if lock else ''), (oid,identity)).fetchone()
+    if not row: raise HTTPException(404, 'Order not found')
+    return row
+
+
+def file_rows(c, oid):
+    return c.execute('''SELECT f.id,f.upload_id,f.item_index,f.kind,f.active,f.note,f.created_at,
+        u.name,u.size,u.expires_at,(u.expires_at<=now()) AS expired
+        FROM dtf_local.order_files f JOIN dtf_local.uploads u ON u.id=f.upload_id
+        WHERE order_id=%s ORDER BY f.created_at''', (oid,)).fetchall()
+
+
+def operator_identity(user):
+    return uuid5(NAMESPACE_URL, 'dtf-local-operator:'+user)

app/scanning.py

@@ -1,11 +1,20 @@
-"""Local ClamAV boundary. Unknown/error/over-limit results NEVER release artwork."""
-import os
+"""Releasing artwork: ClamAV up to its size limit, a format check above it.
+
+Unknown or error results NEVER release artwork. ClamAV scans files up to
+scan_limit_bytes() (2 GB). Sheets of several GB are the normal order and
+ClamAV cannot take them, so a larger file is released only if its first bytes
+are those of the format its name claims (a PNG that really is a PNG, not a
+program renamed .png). That is the check the client chose for large files; it
+does not look for malware inside a valid file.
+"""
+import re
 import socket
 import struct
 import time
 from fastapi import HTTPException
-from .auth import audit
-from .db import connect
+from .core.auth import audit
+from .core.db import connect
+from .core.limits import scan_limit_bytes
 
 def require_clean(row):
     if not row['complete'] or row['scan_state'] != 'clean':
@@ -30,10 +39,9 @@ class ClamAV:
         return self.command(b'VERSION').decode('utf-8','replace')
 
     def scan(self, stream, size):
-        if size > min(134217728, int(os.environ.get('SCAN_MAX_BYTES','134217728'))):
-            return 'rejected', 'File exceeds the malware scan limit'
         with socket.create_connection(('scanner',3310),timeout=10) as sock:
-            sock.settimeout(150)
+            # A 2 GB file takes minutes to stream and scan.
+            sock.settimeout(900)
             sock.sendall(b'zINSTREAM\0')
             sent=0
             for chunk in stream.iter_chunks(chunk_size=65536):
@@ -52,6 +60,37 @@ class ClamAV:
             if result.endswith(b' FOUND'):return 'rejected','Malware or unsafe scan condition detected'
             return 'error','Scanner could not verify this file'
 
+# What each accepted extension must start with. AI files are PDF or PostScript;
+# CDR and WebP are RIFF containers with their own form type.
+TIFF = (b'II*\x00', b'MM\x00*', b'II+\x00', b'MM\x00+')
+SIGNATURES = {
+    'png': (b'\x89PNG\r\n\x1a\n',),
+    'jpg': (b'\xff\xd8\xff',), 'jpeg': (b'\xff\xd8\xff',),
+    'tif': TIFF, 'tiff': TIFF,
+    'pdf': (b'%PDF-',), 'ai': (b'%PDF-', b'%!PS'),
+    'psd': (b'8BPS',), 'psb': (b'8BPS',),
+}
+RIFF_FORMS = {'cdr': re.compile(rb'^RIFF....CDR', re.S), 'webp': re.compile(rb'^RIFF....WEBP', re.S)}
+HEAD_BYTES = 64
+
+
+def format_matches(name, head):
+    """Whether a file's first bytes are those of the format its name claims."""
+    ext = name.rsplit('.', 1)[-1].lower() if '.' in name else ''
+    if ext in RIFF_FORMS:
+        return bool(RIFF_FORMS[ext].match(head))
+    return any(head.startswith(sig) for sig in SIGNATURES.get(ext, ()))
+
+
+def check_large(storage, row):
+    """Release decision for a file above the antivirus limit."""
+    head = storage.client.get_object(Bucket=storage.bucket, Key=row['object_key'],
+                                     Range=f'bytes=0-{HEAD_BYTES - 1}')['Body'].read()
+    if format_matches(row['name'], head):
+        return 'clean', 'Acima do limite do antivírus; formato do arquivo conferido'
+    return 'rejected', 'O conteúdo do arquivo não corresponde ao formato do nome'
+
+
 def scan_one(storage, scanner=None):
     scanner=scanner or ClamAV()
     with connect() as c:
@@ -60,9 +99,12 @@ def scan_one(storage, scanner=None):
             ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT 1''').fetchone()
         if not row:return False
         try:
-            stream=storage.client.get_object(Bucket=storage.bucket,Key=row['object_key'])['Body']
-            try:state,reason=scanner.scan(stream,row['size'])
-            finally:stream.close()
+            if row['size'] > scan_limit_bytes():
+                state,reason=check_large(storage,row)
+            else:
+                stream=storage.client.get_object(Bucket=storage.bucket,Key=row['object_key'])['Body']
+                try:state,reason=scanner.scan(stream,row['size'])
+                finally:stream.close()
         except Exception:
             state,reason='error','Malware scanner unavailable; file remains blocked'
         c.execute("""UPDATE dtf_local.uploads SET scan_state=%s,scan_reason=%s,scanned_at=now(),

app/schema.sql

@@ -0,0 +1,207 @@
+-- Separate schema: never imports/migrates the historical schema.sql or SQLite.
+CREATE SCHEMA IF NOT EXISTS dtf_local;
+CREATE TABLE IF NOT EXISTS dtf_local.uploads (
+ id uuid PRIMARY KEY, owner uuid NOT NULL, name text NOT NULL,
+ size bigint NOT NULL, object_key text UNIQUE NOT NULL, multipart_id text NOT NULL,
+ complete boolean NOT NULL DEFAULT false,
+ created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS dtf_local.quotes (
+ id uuid PRIMARY KEY, owner uuid NOT NULL, request_key uuid NOT NULL,
+ request_hash text NOT NULL, draft jsonb NOT NULL, approved jsonb,
+ reviewed_by text, approved_at timestamptz,
+ created_at timestamptz NOT NULL DEFAULT now(), UNIQUE(owner, request_key)
+);
+CREATE TABLE IF NOT EXISTS dtf_local.orders (
+ id uuid PRIMARY KEY, number bigint GENERATED ALWAYS AS IDENTITY UNIQUE,
+ quote_id uuid NOT NULL UNIQUE REFERENCES dtf_local.quotes(id), owner uuid NOT NULL,
+ snapshot jsonb NOT NULL, payment jsonb NOT NULL, state text NOT NULL DEFAULT 'rec',
+ version integer NOT NULL DEFAULT 0, created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS dtf_local.movements (
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+ order_id uuid NOT NULL REFERENCES dtf_local.orders(id),
+ from_state text NOT NULL, to_state text NOT NULL, operator text NOT NULL,
+ reason text NOT NULL, created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS dtf_local.outbox (
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, event_key text NOT NULL UNIQUE,
+ provider text NOT NULL, payload jsonb NOT NULL, attempts integer NOT NULL DEFAULT 0,
+ available_at timestamptz NOT NULL DEFAULT now(), delivered_at timestamptz,
+ last_error text, receipt jsonb
+);
+CREATE TABLE IF NOT EXISTS dtf_local.accounts (
+ id uuid PRIMARY KEY, email text UNIQUE NOT NULL, password_hash text NOT NULL,
+ profile jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS dtf_local.sessions (
+ id uuid PRIMARY KEY, owner uuid NOT NULL,
+ expires_at timestamptz NOT NULL DEFAULT now() + interval '7 days'
+);
+CREATE TABLE IF NOT EXISTS dtf_local.migrations (name text PRIMARY KEY);
+-- Preserve pre-account guest sessions once, without resurrecting logged-out sessions.
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM dtf_local.migrations WHERE name='customer-sessions-v1') THEN
+  INSERT INTO dtf_local.sessions(id,owner)
+   SELECT owner,owner FROM (
+    SELECT owner FROM dtf_local.orders UNION SELECT owner FROM dtf_local.quotes
+    UNION SELECT owner FROM dtf_local.uploads
+   ) legacy ON CONFLICT DO NOTHING;
+  INSERT INTO dtf_local.migrations VALUES('customer-sessions-v1');
+ END IF;
+END $$;
+CREATE TABLE IF NOT EXISTS dtf_local.login_attempts (
+ key text PRIMARY KEY, attempts integer NOT NULL DEFAULT 0,
+ started_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS dtf_local.operator_sessions (
+ token_hash text PRIMARY KEY, username text NOT NULL,
+ expires_at timestamptz NOT NULL DEFAULT now() + interval '8 hours'
+);
+CREATE TABLE IF NOT EXISTS dtf_local.operators (
+ id uuid PRIMARY KEY, email text UNIQUE NOT NULL, name text NOT NULL DEFAULT '',
+ password_hash text NOT NULL, active boolean NOT NULL DEFAULT true,
+ created_at timestamptz NOT NULL DEFAULT now(), last_login_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS dtf_local.payment_events (
+ id uuid PRIMARY KEY, provider text NOT NULL, event_id text NOT NULL,
+ reference text, status text NOT NULL, amount_cents bigint,
+ payload jsonb NOT NULL, received_at timestamptz NOT NULL DEFAULT now(),
+ processed_at timestamptz, outcome text,
+ UNIQUE(provider, event_id)
+);
+CREATE TABLE IF NOT EXISTS dtf_local.security_events (
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+ event text NOT NULL, details jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS expires_at timestamptz;
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS purged_at timestamptz;
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS scan_state text NOT NULL DEFAULT 'pending';
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS scan_reason text;
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS scanned_at timestamptz;
+ALTER TABLE dtf_local.uploads ADD COLUMN IF NOT EXISTS scan_after timestamptz NOT NULL DEFAULT now();
+UPDATE dtf_local.uploads SET expires_at=created_at + interval '30 days' WHERE expires_at IS NULL;
+ALTER TABLE dtf_local.uploads ALTER COLUMN expires_at SET DEFAULT now() + interval '30 days';
+CREATE TABLE IF NOT EXISTS dtf_local.order_files (
+ id uuid PRIMARY KEY, order_id uuid NOT NULL REFERENCES dtf_local.orders(id),
+ upload_id uuid NOT NULL REFERENCES dtf_local.uploads(id), item_index integer NOT NULL,
+ kind text NOT NULL CHECK(kind IN ('final','correction')), active boolean NOT NULL DEFAULT true,
+ note text NOT NULL, created_by text NOT NULL, created_at timestamptz NOT NULL DEFAULT now(),
+ UNIQUE(order_id,upload_id,kind)
+);
+-- A payment started at the provider for an approved quote: which provider
+-- payment belongs to which quote, and its latest known status.
+CREATE TABLE IF NOT EXISTS dtf_local.payment_intents (
+ id uuid PRIMARY KEY, quote_id uuid NOT NULL REFERENCES dtf_local.quotes(id),
+ provider text NOT NULL, provider_payment_id text NOT NULL, method text NOT NULL,
+ status text NOT NULL, amount_cents bigint NOT NULL, response jsonb NOT NULL,
+ created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(),
+ UNIQUE(provider, provider_payment_id)
+);
+-- OAuth connections to providers (Tiny). One row per provider; the refresh
+-- token rotates on use, so it lives here, never in configuration.
+CREATE TABLE IF NOT EXISTS dtf_local.provider_tokens (
+ provider text PRIMARY KEY, access_token text NOT NULL, refresh_token text NOT NULL,
+ access_expires_at timestamptz NOT NULL, refresh_expires_at timestamptz,
+ connected_by text NOT NULL, connected_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now()
+);
+-- Renewal health, cleared by the next successful renewal or connection.
+-- refused_at: the provider rejected the refresh token, so only a new
+-- connection helps. offline: the grant is not bound to a login session.
+ALTER TABLE dtf_local.provider_tokens ADD COLUMN IF NOT EXISTS refresh_failed_at timestamptz;
+ALTER TABLE dtf_local.provider_tokens ADD COLUMN IF NOT EXISTS refresh_error text;
+ALTER TABLE dtf_local.provider_tokens ADD COLUMN IF NOT EXISTS refused_at timestamptz;
+ALTER TABLE dtf_local.provider_tokens ADD COLUMN IF NOT EXISTS offline boolean NOT NULL DEFAULT false;
+-- Single-use states for an operator-started OAuth connection. They protect the
+-- callback, which arrives cross-site without the operator's cookie.
+CREATE TABLE IF NOT EXISTS dtf_local.oauth_states (
+ state text PRIMARY KEY, provider text NOT NULL, operator text NOT NULL,
+ expires_at timestamptz NOT NULL
+);
+-- The print file generated from each paid item's approved layout. One row per
+-- item: the worker claims it, renders, and records either the file or why the
+-- item has to be prepared by hand. Regenerating replaces the row's result.
+CREATE TABLE IF NOT EXISTS dtf_local.print_files (
+ id uuid PRIMARY KEY, order_id uuid NOT NULL REFERENCES dtf_local.orders(id),
+ item_index integer NOT NULL,
+ status text NOT NULL DEFAULT 'pending'
+  CHECK(status IN ('pending','rendering','ready','manual','failed')),
+ upload_id uuid REFERENCES dtf_local.uploads(id), detail jsonb NOT NULL DEFAULT '{}',
+ attempts integer NOT NULL DEFAULT 0, claimed_at timestamptz,
+ created_at timestamptz NOT NULL DEFAULT now(), finished_at timestamptz,
+ UNIQUE(order_id,item_index)
+);
+
+-- Each run of the off-server database backup (ops/db_backup.py), which the
+-- Kanban shows so a backup that stopped working does not go unnoticed.
+CREATE TABLE IF NOT EXISTS dtf_local.backups (
+ id uuid PRIMARY KEY, started_at timestamptz NOT NULL, finished_at timestamptz NOT NULL,
+ status text NOT NULL CHECK(status IN ('ok','failed')), object_key text, bytes bigint, detail text
+);
+CREATE INDEX IF NOT EXISTS backups_finished ON dtf_local.backups(finished_at DESC);
+
+-- Why a quote waits for review, when the reason came from its files (the grade
+-- the server recomputed) and cannot be worked out again from the draft alone.
+ALTER TABLE dtf_local.quotes ADD COLUMN IF NOT EXISTS review_note text;
+
+CREATE INDEX IF NOT EXISTS uploads_owner ON dtf_local.uploads(owner);
+
+-- Indexes follow the queries the application actually issues. Only these; every
+-- extra index is paid for on each write.
+
+-- The customer portal lists a person's orders and open quotes, newest first.
+CREATE INDEX IF NOT EXISTS orders_owner ON dtf_local.orders(owner, created_at DESC);
+CREATE INDEX IF NOT EXISTS quotes_owner ON dtf_local.quotes(owner, created_at DESC);
+
+-- Order detail and the movement history read by order.
+CREATE INDEX IF NOT EXISTS movements_order ON dtf_local.movements(order_id, id);
+CREATE INDEX IF NOT EXISTS order_files_order ON dtf_local.order_files(order_id);
+-- submit_files checks whether an upload is already attached, by upload.
+CREATE INDEX IF NOT EXISTS order_files_upload ON dtf_local.order_files(upload_id);
+
+-- The worker polls this once a second, and the table only grows. Partial, so the
+-- index stays the size of the backlog rather than of all history.
+CREATE INDEX IF NOT EXISTS outbox_pending ON dtf_local.outbox(available_at, id)
+ WHERE delivered_at IS NULL;
+
+-- The scanner and the retention sweep both walk live uploads in arrival order.
+-- now() cannot appear in a partial index predicate, so the time comparisons stay
+-- in the query and the index narrows to rows still worth looking at.
+CREATE INDEX IF NOT EXISTS uploads_live ON dtf_local.uploads(created_at)
+ WHERE purged_at IS NULL;
+
+-- Sign-in transfers and logout delete a person's sessions by owner.
+CREATE INDEX IF NOT EXISTS sessions_owner ON dtf_local.sessions(owner);
+
+-- Disabling an operator revokes their open sessions by name.
+CREATE INDEX IF NOT EXISTS operator_sessions_username ON dtf_local.operator_sessions(username);
+
+-- security_status reads recent events; the worker prunes old ones by age.
+CREATE INDEX IF NOT EXISTS security_events_created ON dtf_local.security_events(created_at);
+
+-- The webhook looks an event up by provider and id on every delivery, and the
+-- unique constraint already indexes that pair. Only the unprocessed sweep needs
+-- its own index, and it stays the size of the backlog.
+CREATE INDEX IF NOT EXISTS payment_events_unprocessed ON dtf_local.payment_events(received_at)
+ WHERE processed_at IS NULL;
+
+-- The render worker polls for unclaimed or abandoned jobs; the order view reads
+-- by order through the unique constraint.
+CREATE INDEX IF NOT EXISTS print_files_open ON dtf_local.print_files(created_at)
+ WHERE status IN ('pending','rendering');
+
+-- A movement that undid an earlier one (a mistaken move), shown as such.
+ALTER TABLE dtf_local.movements ADD COLUMN IF NOT EXISTS back boolean NOT NULL DEFAULT false;
+
+-- The Kanban lists payment events a person must act on (money without an
+-- order, or a reversed payment on an existing order) until resolved.
+ALTER TABLE dtf_local.payment_events ADD COLUMN IF NOT EXISTS resolved_at timestamptz;
+ALTER TABLE dtf_local.payment_events ADD COLUMN IF NOT EXISTS resolved_by text;
+ALTER TABLE dtf_local.payment_events ADD COLUMN IF NOT EXISTS resolution text;
+CREATE INDEX IF NOT EXISTS payment_events_open_issues ON dtf_local.payment_events(received_at)
+ WHERE (outcome LIKE 'refused%' OR outcome LIKE 'attention%') AND resolved_at IS NULL;
+
+-- Payment intents look up by quote (customer retry) and by provider id (webhook).
+CREATE INDEX IF NOT EXISTS payment_intents_quote ON dtf_local.payment_intents(quote_id, created_at DESC);

app/tiny.py

@@ -0,0 +1,444 @@
+"""Tiny/Olist ERP (API v3): create the sales order once a payment is approved.
+
+Written from the public API documentation and exercised only against a fake
+HTTP transport. Tiny has no sandbox: the first real test creates a real order
+in the client's ERP, so test with a marked order and cancel it afterwards.
+
+Authentication is OAuth2 on Tiny's Keycloak. The client creates an
+"Aplicativo" in Tiny (Configurações > Geral > Aplicativos), which yields a
+client ID and secret and registers our callback URL. An operator then clicks
+"Conectar Tiny" on the Kanban once; the tokens are kept in the database and
+the refresh token is rotated on every refresh, under a row lock so two
+workers never spend the same one.
+
+Orders are created by contact and product id: the customer's contact is found
+by CNPJ or created, and each product mode maps to a product that must already
+exist in Tiny (PRODUCT_SETTINGS).
+
+Idempotency: the outbox may deliver the same event more than once. Every order
+carries numeroOrdemCompra = "DTF-<order number>", and before creating one the
+customer's recent orders are searched for that number, so a second delivery
+finds the first order instead of creating another.
+
+Customer notices: the client already sends WhatsApp messages from Tiny's
+order situação (Tiny webhook -> their middleware -> n8n). With
+TINY_STATUS_UPDATES on, a paid order is set to "Aprovada" and a finished
+pickup order to "Pronto para envio", so those notices reach Site customers
+from the same number and templates; the system's own WhatsApp sender stays
+off. Pickup orders carry the client's "retirar pessoalmente" forma de envio.
+"""
+import os
+import secrets
+import time
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+from urllib.parse import urlencode
+
+import httpx
+
+API = 'https://api.tiny.com.br/public-api/v3'
+AUTH = 'https://accounts.tiny.com.br/realms/tiny/protocol/openid-connect'
+# Not TINY_PRODUCT_<MODE>: app/core/secrets.py reads any variable ending in
+# _FILE as a path to a secret file, and one product mode is called "file".
+PRODUCT_SETTINGS = {'file': 'TINY_PRODUCT_TEXTIL_FOLHA', 'avulsa': 'TINY_PRODUCT_TEXTIL_AVULSA',
+                    'uvfile': 'TINY_PRODUCT_UV_FOLHA', 'uv': 'TINY_PRODUCT_UV_AVULSA'}
+PRODUCTS = {'file': 'DTF Têxtil 57 cm · folha montada',
+            'avulsa': 'DTF Têxtil 57 cm · artes avulsas',
+            'uvfile': 'DTF UV 28,5 cm · folha montada',
+            'uv': 'DTF UV 28,5 cm · artes avulsas'}
+# How far back to look for an order a previous delivery may already have made.
+SEARCH_DAYS = 7
+# A "ready" event can come after corrections; it normally knows the Tiny id.
+READY_SEARCH_DAYS = 45
+# Tiny v3 order situações (PUT /pedidos/{id}/situacao).
+ABERTA, APROVADA, PRONTO_ENVIO, ENVIADA, ENTREGUE, CANCELADA, NAO_ENTREGUE = 0, 3, 7, 5, 6, 2, 9
+SITUACOES = {0: 'Aberta', 3: 'Aprovada', 4: 'Preparando envio', 1: 'Faturada', 7: 'Pronto para envio',
+             5: 'Enviada', 6: 'Entregue', 2: 'Cancelada', 8: 'Dados incompletos', 9: 'Não entregue'}
+# The client's customer notices (Tiny webhook -> middleware -> n8n -> WhatsApp)
+# react to these situações. Off until go-live: while n8n still sends the
+# designer message for DTFIMP products on "Aprovado", setting it would reach
+# Site customers.
+STATUS_UPDATES_SETTING = 'TINY_STATUS_UPDATES'
+# The id of the client's custom "retirar pessoalmente" forma de envio (v2 code
+# X), which the pickup notice is keyed on. Find it with the console tool.
+PICKUP_SETTING = 'TINY_FORMA_ENVIO_RETIRADA'
+STATE_MINUTES = 10
+# Renewal runs about every four hours against a one-day refresh token, so
+# less than this left means renewals have been failing for hours.
+EXPIRY_WARNING = timedelta(hours=12)
+# Brazil has had no daylight saving since 2019; the order date is the local day.
+BRASILIA = timezone(timedelta(hours=-3))
+
+
+def local_today():
+    return datetime.now(BRASILIA).date()
+
+
+class TinyError(Exception):
+    pass
+
+
+class TinyNotConnected(TinyError):
+    """No authorised connection yet: an operator must click "Conectar Tiny"."""
+
+
+def purchase_order(number):
+    return f'DTF-{number}'
+
+
+def configured():
+    """Whether the OAuth application is configured (orders may still be fake)."""
+    return all(os.environ.get(name) for name in ('TINY_CLIENT_ID', 'TINY_CLIENT_SECRET', 'TINY_REDIRECT_URI'))
+
+
+def required_settings():
+    return ['TINY_CLIENT_ID', 'TINY_CLIENT_SECRET', 'TINY_REDIRECT_URI'] + list(PRODUCT_SETTINGS.values())
+
+
+def status_updates():
+    return os.environ.get(STATUS_UPDATES_SETTING, '').lower() == 'true'
+
+
+# OAuth -------------------------------------------------------------------
+
+class TinyAuth:
+    """The OAuth application and the stored connection."""
+
+    def __init__(self, connect=None, transport=None, clock=time.time):
+        self.client_id = os.environ.get('TINY_CLIENT_ID', '')
+        self.client_secret = os.environ.get('TINY_CLIENT_SECRET', '')
+        self.redirect_uri = os.environ.get('TINY_REDIRECT_URI', '')
+        if connect is None:
+            from .core.db import connect
+        self.connect = connect
+        self.http = httpx.Client(timeout=20, transport=transport)
+        self.clock = clock
+
+    def authorize_url(self, operator, offline=True):
+        """Start a connection. The state is single-use, short-lived, and only an
+        authenticated operator can create one, which is what protects the
+        callback: Tiny's redirect back is cross-site, so the operator's
+        SameSite=Strict cookie does not travel with it.
+
+        offline_access asks for a grant that is not bound to a login session,
+        so the connection lasts as long as it keeps being renewed. Tiny's
+        documented refresh token otherwise lasts one day."""
+        state = secrets.token_urlsafe(32)
+        with self.connect() as c:
+            c.execute("DELETE FROM dtf_local.oauth_states WHERE expires_at<now()")
+            c.execute('''INSERT INTO dtf_local.oauth_states(state,provider,operator,expires_at)
+                VALUES(%s,'tiny',%s,now()+%s)''', (state, operator, timedelta(minutes=STATE_MINUTES)))
+        return f'{AUTH}/auth?' + urlencode({'response_type': 'code', 'client_id': self.client_id,
+                                            'redirect_uri': self.redirect_uri,
+                                            'scope': 'openid offline_access' if offline else 'openid',
+                                            'state': state})
+
+    def _claim(self, c, state):
+        row = c.execute('''DELETE FROM dtf_local.oauth_states WHERE state=%s AND provider='tiny'
+            AND expires_at>now() RETURNING operator''', (state,)).fetchone()
+        if not row:
+            raise TinyError('Unknown or expired authorisation state')
+        return row['operator']
+
+    def complete(self, code, state):
+        """Exchange the authorisation code; returns the operator who started it."""
+        with self.connect() as c:
+            operator = self._claim(c, state)
+            tokens = self._token({'grant_type': 'authorization_code', 'code': code,
+                                  'redirect_uri': self.redirect_uri})
+            self._store(c, tokens, operator)
+        return operator
+
+    def without_offline(self, state):
+        """Tiny refused the offline_access scope for this application: spend the
+        operator's state and start again with a session-bound grant."""
+        with self.connect() as c:
+            operator = self._claim(c, state)
+        return self.authorize_url(operator, offline=False)
+
+    def status(self):
+        with self.connect() as c:
+            row = c.execute('''SELECT connected_by,connected_at,refresh_expires_at,updated_at,offline,
+                refresh_failed_at,refused_at FROM dtf_local.provider_tokens WHERE provider='tiny' ''').fetchone()
+        if not row:
+            return {'connected': False}
+        now = datetime.now(timezone.utc)
+        expires = row['refresh_expires_at']
+        expired = bool(expires and expires <= now)
+        if row['refused_at']:
+            problem = 'refused'
+        elif expired:
+            problem = 'expired'
+        elif row['refresh_failed_at']:
+            problem = 'renewal-failing'
+        elif expires and expires - now < EXPIRY_WARNING:
+            problem = 'expiring'
+        else:
+            problem = None
+        return {'connected': not expired and not row['refused_at'], 'problem': problem,
+                'connected_by': row['connected_by'], 'connected_at': row['connected_at'],
+                'renewed_at': row['updated_at'], 'expires_at': expires, 'offline': row['offline'],
+                'failed_at': row['refresh_failed_at']}
+
+    def access_token(self):
+        """A valid access token, refreshing (and rotating) under a row lock.
+
+        A failed renewal is recorded after the lock is released, so the Kanban
+        can show it. A refused refresh token is never tried again: only a new
+        connection helps, and retrying it would only repeat the refusal."""
+        with self.connect() as c:
+            row = c.execute('''SELECT * FROM dtf_local.provider_tokens WHERE provider='tiny'
+                FOR UPDATE''').fetchone()
+            if not row:
+                raise TinyNotConnected('Tiny is not connected; use "Conectar Tiny" on the Kanban')
+            now = datetime.now(timezone.utc)
+            if row['access_expires_at'] > now + timedelta(seconds=60):
+                return row['access_token']
+            if row['refused_at']:
+                raise TinyNotConnected('Tiny refused the stored refresh token; connect again on the Kanban')
+            if row['refresh_expires_at'] and row['refresh_expires_at'] <= now:
+                raise TinyNotConnected('The Tiny connection expired; connect again on the Kanban')
+            try:
+                tokens = self._token({'grant_type': 'refresh_token', 'refresh_token': row['refresh_token']})
+            except (TinyError, httpx.HTTPError, ValueError) as exc:
+                failure = exc
+            else:
+                self._store(c, tokens, row['connected_by'], refreshed=True)
+                return tokens['access_token']
+        # Only against the token that failed: another worker may have renewed since.
+        with self.connect() as c:
+            c.execute('''UPDATE dtf_local.provider_tokens SET refresh_failed_at=now(), refresh_error=%s,
+                refused_at=CASE WHEN %s THEN now() ELSE refused_at END
+                WHERE provider='tiny' AND refresh_token=%s''',
+                      (str(failure)[:300] or type(failure).__name__, isinstance(failure, TinyNotConnected),
+                       row['refresh_token']))
+        raise failure
+
+    def _token(self, form):
+        response = self.http.post(f'{AUTH}/token', data={**form, 'client_id': self.client_id,
+                                                         'client_secret': self.client_secret})
+        if response.status_code == 400 and form['grant_type'] == 'refresh_token':
+            raise TinyNotConnected('Tiny refused the stored refresh token; connect again on the Kanban')
+        response.raise_for_status()
+        tokens = response.json()
+        if not tokens.get('access_token') or not tokens.get('refresh_token'):
+            raise TinyError('Tiny token response is missing tokens')
+        return tokens
+
+    def _store(self, c, tokens, operator, refreshed=False):
+        now = datetime.now(timezone.utc)
+        access_expires = now + timedelta(seconds=int(tokens.get('expires_in', 300)))
+        # An offline grant reports refresh_expires_in 0: no fixed end.
+        refresh_in = tokens.get('refresh_expires_in')
+        refresh_expires = now + timedelta(seconds=int(refresh_in)) if refresh_in else None
+        offline = 'offline_access' in str(tokens.get('scope') or '').split()
+        c.execute('''INSERT INTO dtf_local.provider_tokens(provider,access_token,refresh_token,
+              access_expires_at,refresh_expires_at,connected_by,connected_at,updated_at,offline)
+            VALUES('tiny',%s,%s,%s,%s,%s,now(),now(),%s)
+            ON CONFLICT(provider) DO UPDATE SET access_token=EXCLUDED.access_token,
+              refresh_token=EXCLUDED.refresh_token, access_expires_at=EXCLUDED.access_expires_at,
+              refresh_expires_at=EXCLUDED.refresh_expires_at, updated_at=now(), offline=EXCLUDED.offline,
+              refresh_failed_at=NULL, refresh_error=NULL, refused_at=NULL,
+              connected_by=CASE WHEN %s THEN dtf_local.provider_tokens.connected_by ELSE EXCLUDED.connected_by END,
+              connected_at=CASE WHEN %s THEN dtf_local.provider_tokens.connected_at ELSE now() END''',
+                  (tokens['access_token'], tokens['refresh_token'], access_expires, refresh_expires,
+                   operator, offline, refreshed, refreshed))
+
+
+# Orders ------------------------------------------------------------------
+
+def money(cents):
+    return float(Decimal(cents) / 100)
+
+
+def contact_payload(order):
+    customer = order['customer']
+    destination = order.get('destination')
+    contact = {'nome': (destination or {}).get('recipient') or customer['mail'],
+               'tipoPessoa': 'J', 'cpfCnpj': customer['cnpj'], 'email': customer['mail'],
+               'celular': customer['zap'], 'situacao': 'A'}
+    if destination:
+        contact['endereco'] = address(destination)
+    return contact
+
+
+def address(destination):
+    return {'endereco': destination['street'], 'numero': destination['number'],
+            'complemento': destination.get('complement', ''), 'bairro': destination['district'],
+            'municipio': destination['city'], 'cep': destination['postal_code'],
+            'uf': destination['state'], 'pais': 'Brasil'}
+
+
+def order_payload(payload, contact_id, today=None):
+    """The v3 'pedido' for a paid order's approved snapshot."""
+    order = payload['order']
+    items = []
+    for item in order['items']:
+        setting = PRODUCT_SETTINGS[item['mode']]
+        product = os.environ.get(setting, '')
+        if not product.isdigit():
+            raise TinyError(f'{setting} must be the Tiny product id')
+        items.append({'produto': {'id': int(product)},
+                      'quantidade': float(Decimal(item['billed_metres'])),
+                      'valorUnitario': money(item['unit_cents']),
+                      'infoAdicional': PRODUCTS[item['mode']] + f" · nota {item['grade']}"})
+    freight = order['freight']
+    pickup = freight.get('service') == 'pickup'
+    pedido = {'data': (today or local_today()).isoformat(),
+              'idContato': contact_id,
+              'numeroOrdemCompra': purchase_order(payload['number']),
+              'itens': items,
+              'valorFrete': money(freight['total_cents']),
+              'observacoes': f"Pedido DTF #{payload['number']}" + (' · retirada em Franca' if pickup else ''),
+              'observacoesInternas': f"Site DTF · pago · {payload['order_id']}"}
+    pickup_method = os.environ.get(PICKUP_SETTING, '')
+    if pickup and pickup_method.isdigit():
+        pedido['transportador'] = {'formaEnvio': {'id': int(pickup_method)}}
+    destination = order.get('destination')
+    if destination:
+        pedido['enderecoEntrega'] = {**address(destination), 'enderecoNro': destination['number'],
+                                     'nomeDestinatario': destination['recipient']}
+        del pedido['enderecoEntrega']['numero']
+    ecommerce = os.environ.get('TINY_ECOMMERCE_ID', '')
+    if ecommerce.isdigit():
+        pedido['ecommerce'] = {'id': int(ecommerce), 'numeroPedidoEcommerce': purchase_order(payload['number'])}
+    return pedido
+
+
+def configured_product(orders, mode):
+    """The Tiny product a mode's setting points at, or a reason it cannot be used."""
+    setting = PRODUCT_SETTINGS[mode]
+    value = os.environ.get(setting, '')
+    if not value.isdigit():
+        return None, f'{setting} sem id'
+    found = orders.request('GET', f'/produtos/{value}')
+    if found.get('situacao') != 'A':
+        return found, f"produto {value} não está ativo no Tiny ({found.get('situacao')})"
+    return found, 'ok'
+
+
+def configured_pickup(orders):
+    """The forma de envio the pickup setting points at, or why it cannot be used."""
+    value = os.environ.get(PICKUP_SETTING, '')
+    if not value.isdigit():
+        return None, f'{PICKUP_SETTING} sem id'
+    return orders.request('GET', f'/formas-envio/{value}'), 'ok'
+
+
+def check(auth=None, transport=None, orders=None):
+    """Read-only proof that the connection and permissions work: one order and
+    one contact listed, each configured product found active and the pickup
+    forma de envio found, nothing created. Raises TinyNotConnected when there is no usable connection;
+    otherwise reports each read separately."""
+    orders = orders or TinyOrders(auth=auth or TinyAuth(), transport=transport)
+
+    def listed(path):
+        orders.request('GET', path, params={'limit': 1})
+        return 'ok'
+
+    reads = [('pedidos', lambda: listed('/pedidos')), ('contatos', lambda: listed('/contatos'))]
+    reads += [(PRODUCTS[mode], lambda mode=mode: configured_product(orders, mode)[1]) for mode in PRODUCT_SETTINGS]
+    reads.append(('forma de envio de retirada', lambda: configured_pickup(orders)[1]))
+    results = {}
+    for name, read in reads:
+        try:
+            results[name] = read()
+        except TinyNotConnected:
+            raise
+        except TinyError as exc:
+            results[name] = str(exc)[:200]
+        except httpx.HTTPError:
+            results[name] = 'sem resposta do Tiny'
+    return results
+
+
+class TinyOrders:
+    def __init__(self, auth=None, transport=None, today=None):
+        missing = [name for name in required_settings() if not os.environ.get(name)]
+        if auth is None and missing:
+            raise RuntimeError('Tiny needs ' + ', '.join(missing))
+        self.auth = auth or TinyAuth()
+        self.http = httpx.Client(base_url=API, transport=transport, timeout=30)
+        self.today = today
+
+    def request(self, method, path, **kwargs):
+        headers = {'Authorization': f'Bearer {self.auth.access_token()}'}
+        response = self.http.request(method, path, headers=headers, **kwargs)
+        if response.status_code == 429:
+            raise TinyError('Tiny rate limit reached; the outbox will retry')
+        if response.status_code >= 400:
+            raise TinyError(f'{method} {path}: {response.status_code} {response.text[:300]}')
+        return response.json() if response.content else {}
+
+    def contact(self, order):
+        cnpj = order['customer']['cnpj']
+        found = self.request('GET', '/contatos', params={'cpfCnpj': cnpj, 'limit': 5})
+        for entry in found.get('itens') or []:
+            if ''.join(ch for ch in str(entry.get('cpfCnpj') or '') if ch.isdigit()) == cnpj:
+                return entry['id']
+        return self.request('POST', '/contatos', json=contact_payload(order))['id']
+
+    def find(self, payload, days=SEARCH_DAYS):
+        """An order a previous delivery already created, or None."""
+        wanted = purchase_order(payload['number'])
+        since = ((self.today or local_today()) - timedelta(days=days)).isoformat()
+        found = self.request('GET', '/pedidos', params={'cpfCnpj': payload['order']['customer']['cnpj'],
+                                                        'dataInicial': since, 'limit': 100})
+        for entry in found.get('itens') or []:
+            detail = self.request('GET', f"/pedidos/{entry['id']}")
+            if detail.get('numeroOrdemCompra') == wanted:
+                return detail
+        return None
+
+    def set_situacao(self, tiny_id, situacao):
+        self.request('PUT', f'/pedidos/{tiny_id}/situacao', json={'situacao': situacao})
+
+    def deliver(self, event_key, payload):
+        event = payload.get('event')
+        if event == 'payment_approved':
+            return self.sale(event_key, payload)
+        if event == 'ready' and status_updates():
+            return self.ready(event_key, payload)
+        # Other production events have no Tiny situação and are not written.
+        return {'provider': 'tiny', 'event_key': event_key, 'status': 'not-applicable', 'event': event}
+
+    def sale(self, event_key, payload):
+        """Create the order once; with status updates on, approve it once.
+
+        An order is created "Aberta" and then set to "Aprovada", so a retry
+        after a failure between the two finds it still open and finishes the
+        job, and an order someone has already moved on is left alone."""
+        existing = self.find(payload)
+        if existing:
+            receipt = {'provider': 'tiny', 'event_key': event_key, 'status': 'already-created',
+                       'tiny_id': str(existing.get('id')), 'tiny_number': str(existing.get('numeroPedido'))}
+            tiny_id, situacao = existing.get('id'), existing.get('situacao')
+        else:
+            contact_id = self.contact(payload['order'])
+            created = self.request('POST', '/pedidos', json=order_payload(payload, contact_id, self.today))
+            receipt = {'provider': 'tiny', 'event_key': event_key, 'status': 'created',
+                       'tiny_id': str(created.get('id')), 'tiny_number': str(created.get('numeroPedido'))}
+            tiny_id, situacao = created.get('id'), ABERTA
+        if status_updates() and situacao == ABERTA:
+            self.set_situacao(tiny_id, APROVADA)
+            receipt['situacao'] = SITUACOES[APROVADA]
+        return receipt
+
+    def ready(self, event_key, payload):
+        """A pickup order became ready: "Pronto para envio", which the client's
+        notices turn into the pickup message. Shipped orders get "Enviada"
+        once freight exists (1.2)."""
+        base = {'provider': 'tiny', 'event_key': event_key}
+        order = payload.get('order') or {}
+        if (order.get('freight') or {}).get('service') != 'pickup':
+            return {**base, 'status': 'not-applicable', 'event': 'ready'}
+        tiny_id = payload.get('tiny_id')
+        detail = self.request('GET', f'/pedidos/{tiny_id}') if tiny_id else self.find(payload, READY_SEARCH_DAYS)
+        if not detail:
+            raise TinyError(f"{purchase_order(payload['number'])} is not in Tiny yet; the outbox will retry")
+        base.update(tiny_id=str(detail.get('id')), tiny_number=str(detail.get('numeroPedido')))
+        situacao = detail.get('situacao')
+        if situacao in (PRONTO_ENVIO, ENVIADA, ENTREGUE, CANCELADA, NAO_ENTREGUE):
+            return {**base, 'status': 'status-unchanged', 'situacao': SITUACOES.get(situacao, str(situacao))}
+        self.set_situacao(detail['id'], PRONTO_ENVIO)
+        return {**base, 'status': 'status-updated', 'situacao': SITUACOES[PRONTO_ENVIO]}

app/tiny_probe.py

@@ -0,0 +1,153 @@
+"""Supervised checks against the client's real Tiny, run by hand from a
+container console (docker exec, or Portainer > Containers > worker > Console).
+Tiny has no sandbox, so this is how the adapter is proven on the real account.
+
+    python -m app.tiny_probe produtos [termo]   list active products (read-only)
+    python -m app.tiny_probe formas-envio [termo]  list formas de envio, to find pickup (read-only)
+    python -m app.tiny_probe conferir           connection, the four product ids and pickup (read-only)
+    python -m app.tiny_probe pedido --cnpj ... --email ... --celular ... [--modo file]
+                                                show the test order; --confirmar creates it
+
+The test order goes through TinyOrders.deliver, exactly as the worker sends a
+paid order. The duplicate guard is then proven read-only first (the order must
+be found by its purchase-order number) and only then by a second delivery,
+which must return the existing order. If the search cannot find the order, the
+second delivery is not attempted: it would create a duplicate. Cancel the test
+order in Olist afterwards.
+"""
+import argparse
+import json
+import sys
+import time
+from datetime import datetime
+
+from .core.pricing import TIERS
+from .core.secrets import load as load_secret_files
+from . import tiny
+
+FIND_ATTEMPTS = 4
+FIND_WAIT_SECONDS = 5
+
+
+def test_order(cnpj, email, celular, mode, now=None):
+    number = 'TESTE-' + (now or datetime.now(tiny.BRASILIA)).strftime('%Y%m%d%H%M')
+    unit = TIERS[mode][0][1]
+    return {'order_id': 'teste-integracao', 'number': number, 'event': 'payment_approved',
+            'order': {'customer': {'cnpj': cnpj, 'mail': email, 'zap': celular},
+                      'items': [{'mode': mode, 'grade': 100, 'billed_metres': '1', 'unit_cents': unit}],
+                      'freight': {'service': 'pickup', 'total_cents': 0},
+                      'destination': None, 'total_cents': unit}}
+
+
+def produtos(orders, termo, out):
+    params = {'situacao': 'A', 'limit': 100}
+    if termo:
+        params['nome'] = termo
+    found = orders.request('GET', '/produtos', params=params).get('itens') or []
+    for item in found:
+        preco = (item.get('precos') or {}).get('preco')
+        out(f"{item['id']}\t{item.get('sku') or '-'}\t{item.get('descricao')}\tR$ {preco}")
+    out(f'{len(found)} produto(s) ativo(s)' + (f' com "{termo}"' if termo else '') + '.')
+
+
+def formas_envio(orders, termo, out):
+    params = {'limit': 100}
+    if termo:
+        params['nome'] = termo
+    found = orders.request('GET', '/formas-envio', params=params).get('itens') or []
+    for item in found:
+        out(f"{item.get('id')}\t{item.get('tipo')}\t{item.get('nome')}")
+    out(f'{len(found)} forma(s) de envio' + (f' com "{termo}"' if termo else '') +
+        '. A retirada é a do tipo 6 (Customizado) que a equipe usa para retirar pessoalmente.')
+
+
+def conferir(orders, out):
+    ok = True
+    for mode, setting in tiny.PRODUCT_SETTINGS.items():
+        product, result = tiny.configured_product(orders, mode)
+        ok &= result == 'ok'
+        described = f"{product.get('sku') or '-'} · {product.get('descricao')}" if product else ''
+        out(f'{setting} ({tiny.PRODUCTS[mode]}): {result} {described}'.rstrip())
+    method, result = tiny.configured_pickup(orders)
+    ok &= result == 'ok'
+    out(f"{tiny.PICKUP_SETTING} (retirada): {result} {method.get('nome') if method else ''}".rstrip())
+    out(f"{tiny.STATUS_UPDATES_SETTING}: {'ligado' if tiny.status_updates() else 'desligado'}")
+    for name, result in tiny.check(orders=orders).items():
+        if name in ('pedidos', 'contatos'):
+            ok &= result == 'ok'
+            out(f'{name}: {result}')
+    out('Tudo conferido.' if ok else 'Há pendências acima.')
+    return ok
+
+
+def pedido(orders, payload, confirm, out, wait=time.sleep):
+    cnpj = payload['order']['customer']['cnpj']
+    contacts = orders.request('GET', '/contatos', params={'cpfCnpj': cnpj, 'limit': 5}).get('itens') or []
+    known = [c for c in contacts if ''.join(ch for ch in str(c.get('cpfCnpj') or '') if ch.isdigit()) == cnpj]
+    out(f"Contato {cnpj}: " + (f"já existe no Tiny (id {known[0]['id']})" if known
+                               else 'não existe; será criado com o e-mail como nome'))
+    out('Pedido que será enviado:')
+    out(json.dumps(tiny.order_payload(payload, known[0]['id'] if known else 0), ensure_ascii=False, indent=2))
+    if not confirm:
+        out('Nada foi criado. Repita com --confirmar para criar este pedido no Tiny.')
+        return None
+    first = orders.deliver('teste-integracao', payload)
+    out(f"1º envio: {first['status']} · Tiny id {first['tiny_id']} · nº {first['tiny_number']}")
+    for attempt in range(FIND_ATTEMPTS):
+        found = orders.find(payload)
+        if found:
+            break
+        if attempt < FIND_ATTEMPTS - 1:
+            wait(FIND_WAIT_SECONDS)
+    else:
+        out(f'FALHA: a busca por {tiny.purchase_order(payload["number"])} não encontrou o pedido. '
+            'Um reenvio criaria um duplicado; o 2º envio não foi feito. Cancele o pedido no Olist.')
+        return False
+    second = orders.deliver('teste-integracao', payload)
+    out(f"2º envio: {second['status']} · Tiny id {second['tiny_id']}")
+    passed = second['status'] == 'already-created' and second['tiny_id'] == first['tiny_id']
+    out(('OK: o reenvio encontrou o mesmo pedido.' if passed else 'FALHA: o reenvio não devolveu o mesmo pedido.')
+        + f" Cancele o pedido nº {first['tiny_number']} no Olist.")
+    return passed
+
+
+def main(argv=None, orders=None, out=print):
+    parser = argparse.ArgumentParser(prog='python -m app.tiny_probe')
+    commands = parser.add_subparsers(dest='command', required=True)
+    listing = commands.add_parser('produtos')
+    listing.add_argument('termo', nargs='?', default='')
+    methods = commands.add_parser('formas-envio')
+    methods.add_argument('termo', nargs='?', default='')
+    commands.add_parser('conferir')
+    order = commands.add_parser('pedido')
+    order.add_argument('--cnpj', required=True)
+    order.add_argument('--email', required=True)
+    order.add_argument('--celular', required=True)
+    order.add_argument('--modo', choices=sorted(tiny.PRODUCT_SETTINGS), default='file')
+    order.add_argument('--confirmar', action='store_true')
+    args = parser.parse_args(argv)
+    if orders is None:
+        load_secret_files()
+        orders = tiny.TinyOrders(auth=tiny.TinyAuth())
+    try:
+        if args.command == 'produtos':
+            produtos(orders, args.termo, out)
+            return 0
+        if args.command == 'formas-envio':
+            formas_envio(orders, args.termo, out)
+            return 0
+        if args.command == 'conferir':
+            return 0 if conferir(orders, out) else 1
+        cnpj = ''.join(ch for ch in args.cnpj if ch.isdigit())
+        if len(cnpj) != 14:
+            out('Informe um CNPJ com 14 dígitos.')
+            return 2
+        payload = test_order(cnpj, args.email, args.celular, args.modo)
+        return 0 if pedido(orders, payload, args.confirmar, out) is not False else 1
+    except tiny.TinyError as exc:
+        out(f'Tiny: {exc}')
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

app/worker.py

@@ -1,20 +1,30 @@
 """Transactional outbox worker. Fake receipts persist; no messages leave the stack."""
 import json
 import logging
+import os
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from psycopg.types.json import Jsonb
 from .adapters import FakeTiny, FakeWhatsApp, LocalS3Storage, require_runtime
-from .db import connect
+from .core.secrets import load as load_secret_files
+from .core.db import connect
+from .printjobs import render_loop
 from .scanning import ClamAV, scan_loop
 
+load_secret_files()
 require_runtime()
 adapters = {'tiny': FakeTiny(), 'whatsapp': FakeWhatsApp()}
+# Not yet confirmed against the client's account; see app/tiny.py.
+if os.environ.get('TINY_ADAPTER') == 'tiny':
+    from .tiny import TinyOrders
+    adapters['tiny'] = TinyOrders()
 last_tick = 0.0
 last_cleanup = 0.0
+last_tiny_keepalive = 0.0
 storage = LocalS3Storage()
 scan_thread = None
+render_thread = None
 
 def cleanup():
     """Delete only expired object bytes; retain order/file metadata and history."""
@@ -43,6 +53,27 @@ def tick():
                 c.execute("UPDATE dtf_local.outbox SET attempts=attempts+1, last_error=%s, available_at=now() + %s * interval '1 second' WHERE id=%s", (str(exc),delay,job['id']))
     last_tick = time.monotonic()
 
+def tiny_keepalive():
+    """Keep a connected Tiny authorised even while no orders are sent.
+
+    The refresh token expires unless it is used; access_token() refreshes (and
+    rotates) only when the access token is about to expire, so asking every few
+    minutes renews the connection roughly once per access-token lifetime.
+    """
+    global last_tiny_keepalive
+    if time.monotonic()-last_tiny_keepalive < 600:
+        return
+    last_tiny_keepalive = time.monotonic()
+    from . import tiny
+    if not tiny.configured():
+        return
+    try:
+        tiny.TinyAuth().access_token()
+    except tiny.TinyNotConnected:
+        pass
+    except Exception:
+        logging.exception('Tiny connection refresh failed')
+
 def loop():
     global last_cleanup
     while True:
@@ -51,6 +82,7 @@ def loop():
             if time.monotonic()-last_cleanup > 60:
                 cleanup()
                 last_cleanup = time.monotonic()
+            tiny_keepalive()
         except Exception:
             logging.exception('Local worker tick failed')
         time.sleep(1)
@@ -62,16 +94,20 @@ class Health(BaseHTTPRequestHandler):
             scanner = bool(scan_thread and scan_thread.is_alive() and ClamAV().ping())
         except Exception:
             pass
-        healthy = time.monotonic()-last_tick < 15 and scanner
+        renderer = bool(render_thread and render_thread.is_alive())
+        healthy = time.monotonic()-last_tick < 15 and scanner and renderer
         self.send_response(200 if self.path == '/health' and healthy else 503)
         self.end_headers()
         self.wfile.write(json.dumps({'worker': 'ok' if healthy else 'unavailable',
-                                     'scanner': 'ok' if scanner else 'unavailable'}).encode())
+                                     'scanner': 'ok' if scanner else 'unavailable',
+                                     'print_files': 'ok' if renderer else 'unavailable'}).encode())
     def log_message(self, *args):
         pass
 
 if __name__ == '__main__':
     scan_thread = threading.Thread(target=scan_loop,args=(storage,),daemon=True)
     scan_thread.start()
+    render_thread = threading.Thread(target=render_loop,args=(storage,),daemon=True)
+    render_thread.start()
     threading.Thread(target=loop, daemon=True).start()
     HTTPServer(('0.0.0.0',8002),Health).serve_forever()

compose.local.yaml

@@ -0,0 +1,298 @@
+# Localhost development stack. Builds from source, uses MinIO, fake providers and
+# disposable credentials. `docker-compose.yml` is the production/R2 stack and is
+# NOT usable locally; the two are deliberately separate files.
+#
+#   docker compose -f compose.local.yaml up --build
+#
+# Defaults here mirror `.env.example`; copy it to `.env` only to customise.
+
+x-app: &app
+  build:
+    context: .
+    dockerfile: infra/Dockerfile
+  environment: &environment
+    APP_ENV: local
+    DATABASE_URL: postgresql://${APP_DB_USER:-dtf_app}:${APP_DB_PASSWORD:-local-app-database-only}@db:5432/${POSTGRES_DB:-dtf_local}
+    S3_ENDPOINT: http://storage:9000
+    S3_PUBLIC_ENDPOINT: ${S3_PUBLIC_ENDPOINT:-http://localhost:${STORAGE_PORT:-9000}}
+    S3_BUCKET: ${S3_BUCKET:-dtf-local-artwork}
+    AWS_ACCESS_KEY_ID: ${S3_APP_USER:-dtf_app}
+    AWS_SECRET_ACCESS_KEY: ${S3_APP_PASSWORD:-local-app-storage-only}
+    AWS_DEFAULT_REGION: us-east-1
+    OPERATOR_EMAIL: ${OPERATOR_EMAIL:-operator@example.test}
+    OPERATOR_PASSWORD: ${OPERATOR_PASSWORD:-local-operator-only}
+    # The browser reaches the API through the Site gateway, so the published
+    # Site/Kanban origins must be accepted or every write is rejected 403.
+    PUBLIC_ORIGIN: ${PUBLIC_ORIGIN:-http://localhost:${SITE_PORT:-8080}}
+    ALLOWED_HOSTS: ${ALLOWED_HOSTS:-localhost,127.0.0.1}
+    ALLOWED_ORIGINS: ${ALLOWED_ORIGINS:-http://localhost:${SITE_PORT:-8080},http://localhost:${KANBAN_PORT:-8081},http://127.0.0.1:${SITE_PORT:-8080},http://127.0.0.1:${KANBAN_PORT:-8081}}
+    COOKIE_SECURE: "false"
+    # Sandbox testing only: set PAYMENT_ADAPTER=mercadopago with the MP_* test
+    # credentials, or TINY_ADAPTER=tiny with a TINY_TOKEN, in .env. Never real
+    # production credentials on a developer machine.
+    PAYMENT_ADAPTER: ${PAYMENT_ADAPTER:-fake}
+    PAYMENT_WEBHOOK_SECRET: ${PAYMENT_WEBHOOK_SECRET:-local-webhook-secret}
+    MP_ACCESS_TOKEN: ${MP_ACCESS_TOKEN:-}
+    MP_WEBHOOK_SECRET: ${MP_WEBHOOK_SECRET:-}
+    MP_NOTIFICATION_URL: ${MP_NOTIFICATION_URL:-}
+    MP_PUBLIC_KEY: ${MP_PUBLIC_KEY:-}
+    FREIGHT_ADAPTER: ${FREIGHT_ADAPTER:-fake}
+    JADLOG_TOKEN: ${JADLOG_TOKEN:-}
+    JADLOG_CNPJ: ${JADLOG_CNPJ:-}
+    JADLOG_CONTA: ${JADLOG_CONTA:-}
+    JADLOG_CONTRATO: ${JADLOG_CONTRATO:-}
+    JADLOG_PESO_BASE_KG: ${JADLOG_PESO_BASE_KG:-}
+    JADLOG_PESO_POR_METRO_KG: ${JADLOG_PESO_POR_METRO_KG:-}
+    FREIGHT_PRODUCTION_DAYS: ${FREIGHT_PRODUCTION_DAYS:-0}
+    # Carts the Site priced are approved at checkout; larger ones wait for review.
+    QUOTE_AUTO_APPROVE: ${QUOTE_AUTO_APPROVE:-true}
+    QUOTE_AUTO_MAX_METRES: ${QUOTE_AUTO_MAX_METRES:-50}
+    TINY_ADAPTER: ${TINY_ADAPTER:-fake}
+    TINY_CLIENT_ID: ${TINY_CLIENT_ID:-}
+    TINY_CLIENT_SECRET: ${TINY_CLIENT_SECRET:-}
+    TINY_REDIRECT_URI: ${TINY_REDIRECT_URI:-}
+    TINY_PRODUCT_TEXTIL_FOLHA: ${TINY_PRODUCT_TEXTIL_FOLHA:-}
+    TINY_PRODUCT_TEXTIL_AVULSA: ${TINY_PRODUCT_TEXTIL_AVULSA:-}
+    TINY_PRODUCT_UV_FOLHA: ${TINY_PRODUCT_UV_FOLHA:-}
+    TINY_PRODUCT_UV_AVULSA: ${TINY_PRODUCT_UV_AVULSA:-}
+    TINY_ECOMMERCE_ID: ${TINY_ECOMMERCE_ID:-}
+    WHATSAPP_ADAPTER: fake
+    STORAGE_ADAPTER: s3-local
+    MOCK_FREIGHT_CENTS: ${MOCK_FREIGHT_CENTS:-1500}
+    MAX_UPLOAD_BYTES: ${MAX_UPLOAD_BYTES:-5368709120}
+    UPLOAD_PART_BYTES: ${UPLOAD_PART_BYTES:-8388608}
+    STORAGE_QUOTA_BYTES: ${STORAGE_QUOTA_BYTES:-53687091200}
+    OWNER_UPLOAD_QUOTA_BYTES: ${OWNER_UPLOAD_QUOTA_BYTES:-10737418240}
+    MAX_PENDING_UPLOADS: ${MAX_PENDING_UPLOADS:-10}
+    SCAN_MAX_BYTES: ${SCAN_MAX_BYTES:-2097152000}
+  networks: [local]
+  init: true
+  security_opt: [no-new-privileges:true]
+  cap_drop: [ALL]
+  read_only: true
+  tmpfs: [/tmp]
+  logging:
+    driver: json-file
+    options: {max-size: "10m", max-file: "3"}
+
+services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-dtf_local}
+      POSTGRES_USER: ${POSTGRES_USER:-dtf_local}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-local-database-only}
+    volumes: [postgres-data:/var/lib/postgresql/data]
+    networks: [local]
+    healthcheck:
+      test: [CMD-SHELL, 'pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
+      interval: 5s
+      timeout: 3s
+      retries: 30
+
+  storage:
+    # MinIO stopped publishing public images: since September 2026 both
+    # Docker Hub (minio/minio) and quay.io answer anonymous pulls with 401,
+    # which breaks any machine or runner without a cached copy. Chainguard's
+    # build still pulls anonymously, ships sh and mc (the healthcheck and
+    # storage-init need both) and runs as a non-root user. Pinned by digest
+    # because Chainguard's free tier only publishes :latest. Override
+    # MINIO_IMAGE to use a mirror of your own.
+    image: ${MINIO_IMAGE:-cgr.dev/chainguard/minio@sha256:bd014394a80898e68c149f2311fdf8d5a2c2f3bb2c33b9327ae6d02b4b065ae1}
+    command: server /data --console-address :9001
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-dtf_local}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-local-storage-only}
+    ports:
+      - "127.0.0.1:${STORAGE_PORT:-9000}:9000"
+      - "127.0.0.1:${STORAGE_CONSOLE_PORT:-9001}:9001"
+    volumes: [storage-data:/data]
+    networks: [local, edge]
+    healthcheck:
+      test: [CMD, mc, ready, local]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+
+  db-init:
+    build:
+      context: .
+      dockerfile: infra/Dockerfile
+    command: python -m app.bootstrap
+    environment:
+      # Local only: the app role keeps a password distinct from the administrator.
+      DATABASE_ADMIN_URL: postgresql://${POSTGRES_USER:-dtf_local}:${POSTGRES_PASSWORD:-local-database-only}@db:5432/${POSTGRES_DB:-dtf_local}
+      APP_DB_USER: ${APP_DB_USER:-dtf_app}
+      APP_DB_PASSWORD: ${APP_DB_PASSWORD:-local-app-database-only}
+      # The migration job seeds the first operator account from these, so an
+      # existing deployment keeps its Kanban login after the accounts table
+      # lands. Without them there would be no account at all and login would
+      # fail closed with 503.
+      OPERATOR_EMAIL: ${OPERATOR_EMAIL:-operator@example.test}
+      OPERATOR_PASSWORD: ${OPERATOR_PASSWORD:-local-operator-only}
+    networks: [local]
+    depends_on:
+      db: {condition: service_healthy}
+    restart: on-failure
+
+  storage-init:
+    build:
+      context: .
+      dockerfile: infra/Dockerfile.storage-init
+      args:
+        MINIO_IMAGE: ${MINIO_IMAGE:-cgr.dev/chainguard/minio@sha256:bd014394a80898e68c149f2311fdf8d5a2c2f3bb2c33b9327ae6d02b4b065ae1}
+    entrypoint: [/bin/sh, /init.sh]
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-dtf_local}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-local-storage-only}
+      S3_APP_USER: ${S3_APP_USER:-dtf_app}
+      S3_APP_PASSWORD: ${S3_APP_PASSWORD:-local-app-storage-only}
+      S3_BUCKET: ${S3_BUCKET:-dtf-local-artwork}
+      S3_BACKUP_BUCKET: dtf-local-backups
+      S3_BACKUP_USER: dtf_backup
+      S3_BACKUP_PASSWORD: local-backup-storage-only
+    networks: [local]
+    depends_on:
+      storage: {condition: service_healthy}
+    restart: on-failure
+
+  scanner:
+    # Built, not bind-mounted: see local/Dockerfile.scanner.
+    build:
+      context: .
+      dockerfile: infra/Dockerfile.scanner
+      args:
+        CLAMAV_IMAGE: ${CLAMAV_IMAGE:-clamav/clamav@sha256:9cb27d7660bdf66e9878c832cb433dd8aa152cfbe16f3c2c0084c80b04ae22b4}
+    entrypoint: [clamd, --foreground=true, --config-file=/etc/clamav/clamd.conf]
+    networks: [local]
+    security_opt: [no-new-privileges:true]
+    healthcheck:
+      test: [CMD, clamdscan, --config-file=/etc/clamav/clamd.conf, --ping, "3"]
+      start_period: 60s
+      interval: 10s
+      timeout: 5s
+      retries: 30
+    deploy:
+      resources:
+        limits: {memory: 3G}
+
+  api:
+    <<: *app
+    command: uvicorn app.app:app --host 0.0.0.0 --port 8000 --no-access-log
+    depends_on:
+      db-init: {condition: service_completed_successfully}
+      storage-init: {condition: service_completed_successfully}
+    healthcheck:
+      test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+
+  worker:
+    <<: *app
+    command: python -m app.worker
+    depends_on:
+      api: {condition: service_healthy}
+      scanner: {condition: service_healthy}
+    healthcheck:
+      test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://localhost:8002/health')"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  # The daily database backup, against the local backup bucket. Idle until
+  # BACKUP_AGE_RECIPIENT is set; tests/backup_test.py runs it with a throwaway key.
+  backup:
+    build:
+      context: .
+      dockerfile: infra/Dockerfile
+    command: python -m ops.db_backup serve
+    environment:
+      DATABASE_ADMIN_URL: postgresql://${POSTGRES_USER:-dtf_local}:${POSTGRES_PASSWORD:-local-database-only}@db:5432/${POSTGRES_DB:-dtf_local}
+      BACKUP_S3_ENDPOINT: http://storage:9000
+      BACKUP_BUCKET: dtf-local-backups
+      BACKUP_ACCESS_KEY_ID: dtf_backup
+      BACKUP_SECRET_ACCESS_KEY: local-backup-storage-only
+      BACKUP_REGION: us-east-1
+      BACKUP_AGE_RECIPIENT: ${BACKUP_AGE_RECIPIENT:-}
+    networks: [local]
+    read_only: true
+    tmpfs: [/tmp]
+    depends_on:
+      db-init: {condition: service_completed_successfully}
+      storage-init: {condition: service_completed_successfully}
+
+  site:
+    build:
+      context: .
+      dockerfile: infra/Dockerfile.web
+    environment:
+      S3_PUBLIC_ENDPOINT: ${S3_PUBLIC_ENDPOINT:-http://localhost:${STORAGE_PORT:-9000}}
+      # Empty unless testing Mercado Pago's card form; see docs/LOCAL_SETUP.md.
+      PAYMENT_CSP_SOURCES: ${PAYMENT_CSP_SOURCES:-}
+      PAYMENT_CHALLENGE_SOURCES: ${PAYMENT_CHALLENGE_SOURCES:-}
+    ports:
+      # Published ports are host-wide even bound to loopback, so on a shared
+      # machine any of them can collide with something unrelated. CI overrides
+      # every one; see .gitea/workflows/deploy.yml.
+      - "127.0.0.1:${SITE_PORT:-8080}:80"
+      # Convenience only: the API through its own gateway. No test uses it.
+      - "127.0.0.1:${API_PORT:-8000}:81"
+    networks: [local, edge]
+    depends_on:
+      api: {condition: service_healthy}
+    healthcheck:
+      test: [CMD, wget, -q, -O, /dev/null, http://127.0.0.1/health]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  kanban:
+    build:
+      context: .
+      dockerfile: infra/Dockerfile.web
+    environment:
+      WEB_INDEX: kanban.html
+      S3_PUBLIC_ENDPOINT: ${S3_PUBLIC_ENDPOINT:-http://localhost:${STORAGE_PORT:-9000}}
+      PAYMENT_CSP_SOURCES: ""
+      PAYMENT_CHALLENGE_SOURCES: ""
+    ports: ["127.0.0.1:${KANBAN_PORT:-8081}:80"]
+    networks: [local, edge]
+    depends_on:
+      api: {condition: service_healthy}
+    healthcheck:
+      test: [CMD, wget, -q, -O, /dev/null, http://127.0.0.1/health]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  browser-tests:
+    profiles: [ci]
+    build:
+      context: .
+      dockerfile: infra/Dockerfile.browser-tests
+    environment:
+      CHROME_BIN: /usr/bin/chromium
+      CHROME_NO_SANDBOX: "1"
+      CHROME_TRUST_TEST_ORIGINS: "1"
+      SITE_BROWSER_ORIGIN: http://site
+      KANBAN_BROWSER_ORIGIN: http://kanban
+      OPERATOR_EMAIL: ${OPERATOR_EMAIL:-operator@example.test}
+      OPERATOR_PASSWORD: ${OPERATOR_PASSWORD:-local-operator-only}
+    shm_size: 1gb
+    networks: [local]
+    depends_on:
+      site: {condition: service_healthy}
+      kanban: {condition: service_healthy}
+      storage: {condition: service_healthy}
+    security_opt: [no-new-privileges:true]
+    cap_drop: [ALL]
+
+volumes:
+  postgres-data:
+  storage-data:
+
+networks:
+  local:
+    internal: true
+  edge:

compose.providers.yaml

@@ -0,0 +1,16 @@
+# Provider sandbox testing only: gives the API and worker a route to the
+# internet so they can reach Mercado Pago and Tiny. The default local stack
+# keeps them on an internal network with no external route, which is what
+# every other local run should keep doing.
+#
+#   docker compose -f compose.local.yaml -f compose.providers.yaml up -d --wait
+#
+# Credentials go in .env (see .env.example); never production credentials.
+services:
+  api:
+    networks: [local, provider-egress]
+  worker:
+    networks: [local, provider-egress]
+
+networks:
+  provider-egress: {}

compose.staging.yaml

@@ -7,8 +7,8 @@ services:
   readiness:
     build:
       context: .
-      dockerfile: local/Dockerfile
-    command: python -m local.staging_readiness /config/staging.env
+      dockerfile: infra/Dockerfile
+    command: python -m ops.staging_readiness /config/staging.env
     volumes:
       - ./staging/staging.env:/config/staging.env:ro
     network_mode: none

deploy/Dockerfile.api

@@ -1,5 +1,8 @@
 # syntax=docker/dockerfile:1
-ARG PYTHON_BASE_IMAGE=python:3.12-slim
+# Pinned by digest so a rebuild of the same commit produces the same base.
+# Override with the PYTHON_BASE_IMAGE repository variable to move it forward
+# deliberately, and update this default in the same change.
+ARG PYTHON_BASE_IMAGE=python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9
 FROM ${PYTHON_BASE_IMAGE}
 
 ARG VCS_REF=unknown
@@ -7,12 +10,23 @@ LABEL org.opencontainers.image.title="DTF Portal/API" \
       org.opencontainers.image.revision="$VCS_REF" \
       org.opencontainers.image.source="DTF System repository"
 
+# The base is pinned, so its OS packages are frozen at the digest's build date.
+# Upgrade them here or the image ships known-fixed Debian vulnerabilities, which
+# is what the production image was doing while the local one already did this.
+# pg_dump and age are for the database backup (ops/db_backup.py). Debian 13
+# ships PostgreSQL 17, the server's major version, which pg_dump must match.
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y --no-install-recommends postgresql-client-17 age \
+    && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
-COPY local/requirements.txt local/requirements.lock /app/local/
-RUN python -m pip install --no-cache-dir --require-hashes -r local/requirements.lock
-COPY local /app/local
+COPY infra/requirements.txt infra/requirements.lock /app/infra/
+RUN python -m pip install --no-cache-dir --require-hashes -r infra/requirements.lock
+COPY app /app/app
+COPY ops /app/ops
 RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin dtf
 USER 10001:10001
 ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PYTHONPATH=/app
 EXPOSE 8000
-CMD ["uvicorn", "local.app:app", "--host", "0.0.0.0", "--port", "8000", "--no-access-log"]
+CMD ["uvicorn", "app.app:app", "--host", "0.0.0.0", "--port", "8000", "--no-access-log"]

deploy/Dockerfile.web

@@ -1,23 +1,30 @@
 # syntax=docker/dockerfile:1
-ARG PYTHON_BASE_IMAGE=python:3.12-slim
-ARG NGINX_BASE_IMAGE=nginx:1.28-alpine
+ARG PYTHON_BASE_IMAGE=python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9
+# Both bases are pinned by digest; override with the repository variables to
+# move them forward deliberately.
+# nginx 1.31.6. The 1.28 line pins nginx=1.28.3-r1 in /etc/apk/world, so its five
+# HIGH findings cannot be upgraded in place; 1.29 scans worse. This one is clean.
+ARG NGINX_BASE_IMAGE=nginx:alpine@sha256:62ff2089abf5a9ed33bd232895bef5e22f7bb4b200675cec49a5ebc48e3d4ac8
 FROM ${PYTHON_BASE_IMAGE} AS policy
 WORKDIR /build
-COPY dtf-site.html /build/dtf-site.html
-COPY local /build/local
+COPY web /build/web
+COPY infra /build/infra
 COPY deploy /build/deploy
 ENV NGINX_TEMPLATE=/build/deploy/nginx.conf.template
-RUN python local/compile_web.py
+RUN python infra/compile_web.py
 
 FROM ${NGINX_BASE_IMAGE}
+# Same reason as the API image: a pinned base freezes its packages.
+RUN apk upgrade --no-cache
 ARG VCS_REF=unknown
 LABEL org.opencontainers.image.title="DTF Site and Kanban" \
       org.opencontainers.image.revision="$VCS_REF" \
       org.opencontainers.image.source="DTF System repository"
 ENV WEB_INDEX=index.html PUBLIC_HOST=invalid.example S3_PUBLIC_ENDPOINT=https://invalid.example
 COPY --from=policy /build/default.conf.template /etc/nginx/templates/default.conf.template
-COPY dtf-site.html /usr/share/nginx/html/index.html
-COPY local/static/ /usr/share/nginx/html/
+# The HTML from the policy stage, with every asset address versioned.
+COPY --from=policy /build/web/ /usr/share/nginx/html/
+
 # The official entrypoint renders the server configuration at startup and Nginx
 # writes its PID/cache files.  Keep the service non-root while granting it
 # ownership of only those runtime locations.  This works in Docker Swarm,

deploy/PRODUCTION_CHECKLIST.md

@@ -5,7 +5,7 @@ substitute for `production_preflight.py`, CI, staging acceptance, or change appr
 
 ## Application and external contracts
 
-- [ ] `PRODUCTION_INPUTS.md` has owners, decisions, and evidence for every item.
+- [ ] `docs/PRODUCTION_INPUTS.md` has owners, decisions, and evidence for every item.
 - [ ] Production R2, freight, Mercado Pago, Tiny/Olist, and WhatsApp adapters have
       sandbox contract tests and least-privilege credentials.
 - [ ] Payment webhook authenticity, replay handling, and idempotency are tested.

deploy/README.md

@@ -4,7 +4,7 @@ The DTF application is one Portainer-owned Docker Swarm stack. Gitea builds,
 tests, scans, and publishes the two application images, then calls the stack's
 Portainer webhook. Start with the short operator guide in `../PORTAINER.md`.
 
-- `stack.yaml` — the single Portainer stack.
+- The deployed stack is the repository's `docker-compose.yml`, not a file here.
 - `Dockerfile.api` and `Dockerfile.web` — prebuilt registry images.
 - `portainer.env.example` — non-secret Portainer variables.
 - `production_preflight.py` — fail-closed application/configuration validator.

deploy/nginx.conf.template

@@ -3,6 +3,22 @@ server {
     listen 8080;
     server_name ${PUBLIC_HOST};
     if ($host != ${PUBLIC_HOST}) { return 400; }
+    # Resolve through Docker's embedded DNS at request time.  This prevents
+    # Nginx from exiting during a Swarm rollout when the API task is briefly
+    # unavailable or still creating its database schema.
+    resolver 127.0.0.11 ipv6=off valid=10s;
+    set $api_upstream api:8000;
+
+    # This gateway sits behind the host's reverse proxy, so $remote_addr is that
+    # proxy, not the customer. Recover the real address from the header it sets,
+    # and only when the connection comes from a private network: a request that
+    # reaches the published port directly from the internet is not trusted, so
+    # its X-Forwarded-For is ignored and $remote_addr stays the actual peer.
+    set_real_ip_from 10.0.0.0/8;
+    set_real_ip_from 172.16.0.0/12;
+    set_real_ip_from 192.168.0.0/16;
+    real_ip_header X-Forwarded-For;
+    real_ip_recursive on;
     root /usr/share/nginx/html;
     index ${WEB_INDEX};
 
@@ -11,21 +27,39 @@ server {
     add_header Referrer-Policy no-referrer always;
     add_header X-Frame-Options DENY always;
     add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
-    add_header Content-Security-Policy "default-src 'self'; script-src 'self' @SCRIPT_HASHES@ https://cdnjs.cloudflare.com; script-src-attr 'none'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: blob: https://cdn.vnda.com.br; connect-src 'self' ${S3_PUBLIC_ENDPOINT} https://cdn.vnda.com.br https://cdnjs.cloudflare.com; worker-src 'self' blob: https://cdnjs.cloudflare.com; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self' @SCRIPT_HASHES@ ${PAYMENT_CSP_SOURCES}; script-src-attr 'none'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: blob: https://cdn.vnda.com.br ${PAYMENT_CSP_SOURCES}; connect-src 'self' ${S3_PUBLIC_ENDPOINT} https://cdn.vnda.com.br ${PAYMENT_CSP_SOURCES}; frame-src 'self' ${PAYMENT_CSP_SOURCES} ${PAYMENT_CHALLENGE_SOURCES}; worker-src 'self' blob:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self' ${PAYMENT_CHALLENGE_SOURCES}" always;
 
     location = /health { access_log off; return 200 'ok'; }
     location /api/ {
         limit_req zone=api_limit burst=100 nodelay;
         limit_req_status 429;
-        proxy_pass http://api:8000;
+        proxy_pass http://$api_upstream;
         proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-Host $host;
         proxy_set_header X-Forwarded-Proto https;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        # Overwrite, never append: $proxy_add_x_forwarded_for keeps any header the
+        # client sent, and the leftmost value would then be attacker-controlled.
+        # After real_ip above, $remote_addr is the customer even behind the proxy.
+        proxy_set_header X-Forwarded-For $remote_addr;
         proxy_connect_timeout 5s;
         proxy_read_timeout 30s;
         client_max_body_size 2m;
     }
-    location / { try_files $uri $uri/ =404; }
+    # Always revalidate HTML/JS/CSS after a deployment. Without this, a browser
+    # can pair a new Kanban page with a cached older script after a rollout.
+    # The Site's product pages and cart are addresses of the same page (web/site-pages.js).
+    location ~ ^/(arquivo-por-metro|artes-avulsas|uv-arquivo-por-metro|uv-artes-avulsas|carrinho|pagamento|pagamento/pix)/?$ {
+        expires -1;
+        try_files /index.html =404;
+    }
+    # The customer's area: one page, which shows the right part for each address.
+    location ~ ^/conta(/(entrar|pedidos|dados))?/?$ {
+        expires -1;
+        try_files /portal.html =404;
+    }
+    location / {
+        expires -1;
+        try_files $uri $uri/ =404;
+    }
 }

deploy/portainer.env.example

@@ -24,11 +24,26 @@ POSTGRES_DB=dtf
 POSTGRES_USER=dtf_admin
 APP_DB_USER=dtf_app
 POSTGRES_VOLUME=TBD
-OPERATOR_USER=TBD
+OPERATOR_EMAIL=TBD
 
 PAYMENT_ADAPTER=TBD
+# With PAYMENT_ADAPTER=mercadopago. MP_ACCESS_TOKEN and MP_WEBHOOK_SECRET are
+# secrets: enter them in Portainer only, never in this file.
+MP_NOTIFICATION_URL=https://<SITE_DOMAIN>/api/payments/webhook
+MP_PUBLIC_KEY=
 FREIGHT_ADAPTER=TBD
 TINY_ADAPTER=TBD
+# Tiny API v3 application (Configurações > Geral > Aplicativos in Tiny). The
+# redirect URL registered there must equal TINY_REDIRECT_URI.
+TINY_CLIENT_ID=TBD
+TINY_REDIRECT_URI=https://<KANBAN_DOMAIN>/api/operator/tiny/callback
+TINY_PRODUCT_TEXTIL_FOLHA=TBD
+TINY_PRODUCT_TEXTIL_AVULSA=TBD
+TINY_PRODUCT_UV_FOLHA=TBD
+TINY_PRODUCT_UV_AVULSA=TBD
+TINY_FORMA_ENVIO_RETIRADA=TBD
+# true only at go-live, after the n8n DTFIMP designer branch is removed.
+TINY_STATUS_UPDATES=false
 WHATSAPP_ADAPTER=TBD
 STORAGE_QUOTA_BYTES=TBD
 OWNER_UPLOAD_QUOTA_BYTES=TBD
@@ -36,6 +51,13 @@ MAX_PENDING_UPLOADS=10
 MAX_UPLOAD_BYTES=5368709120
 UPLOAD_PART_BYTES=8388608
 SCAN_MAX_BYTES=134217728
+# Daily encrypted database backup to its own bucket (docs/BACKUP.md).
+BACKUP_S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
+BACKUP_BUCKET=dtf-backups
+BACKUP_ACCESS_KEY_ID=TBD
+BACKUP_SECRET_ACCESS_KEY=TBD
+BACKUP_AGE_RECIPIENT=age1...
+BACKUP_HOUR=3
 
 # Names of external Portainer/Docker Swarm secrets, never their values.
 DATABASE_URL_SECRET=TBD

deploy/production_preflight.py

@@ -17,7 +17,7 @@ REQUIRED = (
     'IMAGE_TAG', 'PUBLIC_ORIGIN', 'PUBLIC_HOST', 'KANBAN_HOST',
     'SITE_PORT', 'KANBAN_PORT',
     'R2_ENDPOINT', 'R2_PUBLIC_ENDPOINT', 'R2_BUCKET',
-    'POSTGRES_DB', 'POSTGRES_USER', 'APP_DB_USER', 'POSTGRES_VOLUME', 'OPERATOR_USER',
+    'POSTGRES_DB', 'POSTGRES_USER', 'APP_DB_USER', 'POSTGRES_VOLUME', 'OPERATOR_EMAIL',
     'STORAGE_QUOTA_BYTES', 'OWNER_UPLOAD_QUOTA_BYTES', 'MAX_UPLOAD_BYTES',
     'UPLOAD_PART_BYTES', 'MAX_PENDING_UPLOADS', 'SCAN_MAX_BYTES',
     'PAYMENT_ADAPTER', 'FREIGHT_ADAPTER', 'TINY_ADAPTER', 'WHATSAPP_ADAPTER',
@@ -33,16 +33,15 @@ IMAGE_REPOSITORY = re.compile(
 DNS = re.compile(r'^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$')
 NAME = re.compile(r'^[a-zA-Z0-9][a-zA-Z0-9_.-]{2,127}$')
 SOURCE_BLOCKERS = {
-    'local/adapters.py': (
-        'This runtime only supports APP_ENV=local',
-        'Only local S3 storage is supported',
-    ),
-    'local/app.py': (
-        "allowed_hosts=['localhost', '127.0.0.1']",
-        "'environment': 'local'",
+    # Markers must name something that is still true, or the gate weakens without
+    # failing. Four entries here described a local-only runtime and stopped
+    # matching when R2 support landed; they were removed rather than left to rot.
+    # What remains is the real blocker: no production payment or messaging adapter
+    # exists, so these lines must change before a release can be meaningful.
+    'app/runtime.py': (
         'payment = FakePayment()',
     ),
-    'local/worker.py': (
+    'app/worker.py': (
         "adapters = {'tiny': FakeTiny(), 'whatsapp': FakeWhatsApp()}",
     ),
 }
@@ -55,12 +54,63 @@ def source_errors(root=ROOT):
         for marker in markers:
             if marker in text:
                 errors.append(f'{relative} remains local-only: {marker}')
-    secrets_module = root / 'local' / 'secrets.py'
-    if not secrets_module.exists() or 'DATABASE_URL_FILE' not in secrets_module.read_text():
-        errors.append('local runtime does not load the production Docker secret *_FILE settings')
+    errors.extend(secret_loading_errors(root))
     return errors
 
 
+def secret_loading_errors(root=ROOT):
+    """Exercise the secret loader instead of grepping it.
+
+    Searching for a string passes as soon as someone writes that string, and
+    fails when a working implementation happens to spell it differently. Load the
+    module and make it resolve a real file.
+    """
+    import importlib.util
+    import tempfile
+
+    module_path = root / 'app' / 'core' / 'secrets.py'
+    if not module_path.exists():
+        return ['local runtime does not load the production Docker secret *_FILE settings']
+    try:
+        spec = importlib.util.spec_from_file_location('_preflight_secrets', module_path)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        return [f'app/core/secrets.py could not be loaded: {exc}']
+
+    stack_names = set()
+    stack = root / 'deploy' / 'stack.yaml'
+    if stack.exists():
+        for line in stack.read_text().splitlines():
+            if '_FILE:' in line:
+                key = line.split(':')[0].strip()
+                # The database image consumes this one; the application does not.
+                if key and key != 'POSTGRES_PASSWORD_FILE':
+                    stack_names.add(key[:-len('_FILE')])
+
+    failures = []
+    with tempfile.TemporaryDirectory() as directory:
+        for name in sorted(stack_names):
+            path = Path(directory) / name
+            path.write_text('resolved-value\n', encoding='utf-8')
+            environ = {f'{name}_FILE': str(path)}
+            try:
+                module.load(environ)
+            except Exception as exc:
+                failures.append(f'{name}_FILE is not resolved by app/core/secrets.py: {exc}')
+                continue
+            if environ.get(name) != 'resolved-value':
+                failures.append(f'{name}_FILE did not produce {name}')
+        # A missing secret must stop the service, never start it unconfigured.
+        try:
+            module.load({'DATABASE_URL_FILE': str(Path(directory) / 'absent')})
+        except Exception:
+            pass
+        else:
+            failures.append('app/core/secrets.py does not fail closed on an unreadable secret')
+    return failures
+
+
 def config_errors(values):
     errors = []
     for name in APPROVALS:
@@ -126,6 +176,8 @@ def config_errors(values):
         errors.append('OWNER_UPLOAD_QUOTA_BYTES cannot exceed STORAGE_QUOTA_BYTES')
     if numeric.get('SCAN_MAX_BYTES', 0) > numeric.get('MAX_UPLOAD_BYTES', 0):
         errors.append('SCAN_MAX_BYTES cannot exceed MAX_UPLOAD_BYTES')
+    if numeric.get('SCAN_MAX_BYTES', 0) > 128 * 1024 * 1024:
+        errors.append('SCAN_MAX_BYTES cannot exceed the configured ClamAV 128 MiB stream limit')
     ports = {}
     for name in ('SITE_PORT', 'KANBAN_PORT'):
         try:

deploy/stack.yaml

@@ -1,309 +0,0 @@
-version: "3.8"
-
-x-app-environment: &app-environment
-  APP_ENV: production
-  DATABASE_URL_FILE: /run/secrets/database_url
-  S3_ENDPOINT: ${R2_ENDPOINT:?set R2_ENDPOINT}
-  S3_PUBLIC_ENDPOINT: ${R2_PUBLIC_ENDPOINT:?set R2_PUBLIC_ENDPOINT}
-  S3_BUCKET: ${R2_BUCKET:?set R2_BUCKET}
-  AWS_ACCESS_KEY_ID_FILE: /run/secrets/r2_access_key_id
-  AWS_SECRET_ACCESS_KEY_FILE: /run/secrets/r2_secret_access_key
-  AWS_DEFAULT_REGION: auto
-  OPERATOR_USER: ${OPERATOR_USER:?set OPERATOR_USER}
-  OPERATOR_PASSWORD_FILE: /run/secrets/operator_password
-  PAYMENT_ADAPTER: ${PAYMENT_ADAPTER:?set PAYMENT_ADAPTER}
-  FREIGHT_ADAPTER: ${FREIGHT_ADAPTER:?set FREIGHT_ADAPTER}
-  TINY_ADAPTER: ${TINY_ADAPTER:?set TINY_ADAPTER}
-  WHATSAPP_ADAPTER: ${WHATSAPP_ADAPTER:?set WHATSAPP_ADAPTER}
-  STORAGE_ADAPTER: s3-r2
-  PAYMENT_TOKEN_FILE: /run/secrets/payment_token
-  PAYMENT_WEBHOOK_SECRET_FILE: /run/secrets/payment_webhook_secret
-  TINY_TOKEN_FILE: /run/secrets/tiny_token
-  WHATSAPP_TOKEN_FILE: /run/secrets/whatsapp_token
-  PUBLIC_ORIGIN: ${PUBLIC_ORIGIN:?set PUBLIC_ORIGIN}
-  PUBLIC_HOST: ${PUBLIC_HOST:?set PUBLIC_HOST}
-  ALLOWED_HOSTS: ${PUBLIC_HOST:?set PUBLIC_HOST},${KANBAN_HOST:?set KANBAN_HOST}
-  ALLOWED_ORIGINS: ${PUBLIC_ORIGIN:?set PUBLIC_ORIGIN},https://${KANBAN_HOST:?set KANBAN_HOST}
-  COOKIE_SECURE: "true"
-  MAX_UPLOAD_BYTES: ${MAX_UPLOAD_BYTES:-5368709120}
-  UPLOAD_PART_BYTES: ${UPLOAD_PART_BYTES:-8388608}
-  STORAGE_QUOTA_BYTES: ${STORAGE_QUOTA_BYTES:?set STORAGE_QUOTA_BYTES}
-  OWNER_UPLOAD_QUOTA_BYTES: ${OWNER_UPLOAD_QUOTA_BYTES:?set OWNER_UPLOAD_QUOTA_BYTES}
-  MAX_PENDING_UPLOADS: ${MAX_PENDING_UPLOADS:-10}
-  SCAN_MAX_BYTES: ${SCAN_MAX_BYTES:-134217728}
-
-x-app-secrets: &app-secrets
-  - database_url
-  - r2_access_key_id
-  - r2_secret_access_key
-  - operator_password
-  - payment_token
-  - payment_webhook_secret
-  - tiny_token
-  - whatsapp_token
-
-x-rolling: &rolling
-  update_config:
-    parallelism: 1
-    delay: 10s
-    order: start-first
-    failure_action: rollback
-    monitor: 45s
-  rollback_config:
-    parallelism: 1
-    delay: 5s
-    order: start-first
-    failure_action: pause
-    monitor: 45s
-  restart_policy:
-    condition: on-failure
-    delay: 5s
-    max_attempts: 5
-    window: 60s
-
-services:
-  db:
-    image: ${POSTGRES_IMAGE:?set POSTGRES_IMAGE}
-    environment:
-      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB}
-      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER}
-      POSTGRES_PASSWORD_FILE: /run/secrets/db_admin_password
-    secrets: [db_admin_password]
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    networks: [backend]
-    healthcheck:
-      test: [CMD-SHELL, 'pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
-      interval: 10s
-      timeout: 5s
-      retries: 12
-      start_period: 20s
-    stop_grace_period: 60s
-    deploy:
-      replicas: 1
-      placement:
-        constraints: [node.labels.dtf_database == true]
-      update_config:
-        parallelism: 1
-        order: stop-first
-        failure_action: rollback
-        monitor: 60s
-      rollback_config:
-        parallelism: 1
-        order: stop-first
-        failure_action: pause
-        monitor: 60s
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-        max_attempts: 5
-        window: 120s
-      resources:
-        limits: {cpus: "2.0", memory: 4G}
-        reservations: {cpus: "0.5", memory: 1G}
-
-  db-init:
-    image: ${API_IMAGE:?set API_IMAGE}:${IMAGE_TAG:-latest}
-    command: python -m local.bootstrap
-    environment:
-      APP_ENV: production
-      DATABASE_ADMIN_URL_FILE: /run/secrets/database_admin_url
-      APP_DB_USER: ${APP_DB_USER:?set APP_DB_USER}
-      APP_DB_PASSWORD_FILE: /run/secrets/app_db_password
-    secrets: [database_admin_url, app_db_password]
-    networks: [backend]
-    deploy:
-      replicas: 1
-      restart_policy: {condition: none}
-      placement:
-        constraints: [node.platform.os == linux]
-      resources:
-        limits: {cpus: "0.5", memory: 512M}
-
-  scanner:
-    image: ${CLAMAV_IMAGE:?set CLAMAV_IMAGE}
-    user: "100:101"
-    entrypoint: [clamd, --foreground=true, --config-file=/etc/clamav/clamd.conf]
-    configs:
-      - source: clamd_config
-        target: /etc/clamav/clamd.conf
-        mode: 0444
-    networks: [backend]
-    read_only: true
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    tmpfs:
-      - /tmp:uid=100,gid=101,mode=0750
-      - /run/clamav:uid=100,gid=101,mode=0750
-      - /var/log/clamav:uid=100,gid=101,mode=0750
-    healthcheck:
-      test: [CMD, clamdscan, --config-file=/etc/clamav/clamd.conf, --ping, "3"]
-      interval: 15s
-      timeout: 5s
-      retries: 20
-      start_period: 90s
-    deploy:
-      replicas: 1
-      restart_policy: {condition: on-failure, delay: 10s}
-      resources:
-        limits: {cpus: "2.0", memory: 3G}
-        reservations: {cpus: "0.5", memory: 1G}
-
-  api:
-    image: ${API_IMAGE:?set API_IMAGE}:${IMAGE_TAG:-latest}
-    environment: *app-environment
-    secrets: *app-secrets
-    networks: [backend, egress]
-    read_only: true
-    tmpfs: [/tmp]
-    init: true
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    healthcheck:
-      test:
-        - CMD-SHELL
-        - >-
-          python -c "import os,urllib.request; r=urllib.request.Request('http://localhost:8000/health',headers={'Host':os.environ['PUBLIC_HOST']}); urllib.request.urlopen(r,timeout=3)"
-      interval: 10s
-      timeout: 5s
-      retries: 12
-      start_period: 30s
-    stop_grace_period: 30s
-    deploy:
-      <<: *rolling
-      replicas: 2
-      resources:
-        limits: {cpus: "1.0", memory: 1G}
-        reservations: {cpus: "0.25", memory: 256M}
-
-  worker:
-    image: ${API_IMAGE:?set API_IMAGE}:${IMAGE_TAG:-latest}
-    command: python -m local.worker
-    environment:
-      <<: *app-environment
-      CLAMD_HOST: scanner
-    secrets: *app-secrets
-    networks: [backend, egress]
-    read_only: true
-    tmpfs: [/tmp]
-    init: true
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    healthcheck:
-      test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://localhost:8002/health',timeout=3)"]
-      interval: 15s
-      timeout: 5s
-      retries: 12
-      start_period: 90s
-    stop_grace_period: 60s
-    deploy:
-      <<: *rolling
-      replicas: 1
-      update_config:
-        parallelism: 1
-        order: stop-first
-        failure_action: rollback
-        monitor: 60s
-      rollback_config:
-        parallelism: 1
-        order: stop-first
-        failure_action: pause
-        monitor: 60s
-      resources:
-        limits: {cpus: "1.5", memory: 2G}
-        reservations: {cpus: "0.25", memory: 512M}
-
-  site:
-    image: ${WEB_IMAGE:?set WEB_IMAGE}:${IMAGE_TAG:-latest}
-    environment:
-      WEB_INDEX: index.html
-      PUBLIC_HOST: ${PUBLIC_HOST:?set PUBLIC_HOST}
-      S3_PUBLIC_ENDPOINT: ${R2_PUBLIC_ENDPOINT:?set R2_PUBLIC_ENDPOINT}
-    networks: [backend]
-    ports:
-      - target: 8080
-        published: ${SITE_PORT:-8080}
-        protocol: tcp
-        mode: ingress
-    read_only: true
-    tmpfs:
-      - /tmp:uid=101,gid=101,mode=0750
-      - /var/cache/nginx:uid=101,gid=101,mode=0750
-      - /var/run:uid=101,gid=101,mode=0750
-      - /etc/nginx/conf.d:uid=101,gid=101,mode=0750
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    healthcheck:
-      test: [CMD-SHELL, 'wget -q --header="Host: $$PUBLIC_HOST" -O /dev/null http://127.0.0.1:8080/health']
-      interval: 10s
-      timeout: 5s
-      retries: 12
-      start_period: 15s
-    deploy:
-      <<: *rolling
-      replicas: 2
-      resources:
-        limits: {cpus: "0.5", memory: 256M}
-        reservations: {cpus: "0.1", memory: 64M}
-
-  kanban:
-    image: ${WEB_IMAGE:?set WEB_IMAGE}:${IMAGE_TAG:-latest}
-    environment:
-      WEB_INDEX: kanban.html
-      PUBLIC_HOST: ${KANBAN_HOST:?set KANBAN_HOST}
-      S3_PUBLIC_ENDPOINT: ${R2_PUBLIC_ENDPOINT:?set R2_PUBLIC_ENDPOINT}
-    networks: [backend]
-    ports:
-      - target: 8080
-        published: ${KANBAN_PORT:-8081}
-        protocol: tcp
-        mode: ingress
-    read_only: true
-    tmpfs:
-      - /tmp:uid=101,gid=101,mode=0750
-      - /var/cache/nginx:uid=101,gid=101,mode=0750
-      - /var/run:uid=101,gid=101,mode=0750
-      - /etc/nginx/conf.d:uid=101,gid=101,mode=0750
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    healthcheck:
-      test: [CMD-SHELL, 'wget -q --header="Host: $$PUBLIC_HOST" -O /dev/null http://127.0.0.1:8080/health']
-      interval: 10s
-      timeout: 5s
-      retries: 12
-      start_period: 15s
-    deploy:
-      <<: *rolling
-      replicas: 1
-      resources:
-        limits: {cpus: "0.5", memory: 256M}
-        reservations: {cpus: "0.1", memory: 64M}
-
-configs:
-  clamd_config:
-    file: ../local/clamd.conf
-
-secrets:
-  database_url: {external: true, name: "${DATABASE_URL_SECRET:?set DATABASE_URL_SECRET}"}
-  database_admin_url: {external: true, name: "${DATABASE_ADMIN_URL_SECRET:?set DATABASE_ADMIN_URL_SECRET}"}
-  db_admin_password: {external: true, name: "${DB_ADMIN_PASSWORD_SECRET:?set DB_ADMIN_PASSWORD_SECRET}"}
-  app_db_password: {external: true, name: "${APP_DB_PASSWORD_SECRET:?set APP_DB_PASSWORD_SECRET}"}
-  r2_access_key_id: {external: true, name: "${R2_ACCESS_KEY_ID_SECRET:?set R2_ACCESS_KEY_ID_SECRET}"}
-  r2_secret_access_key: {external: true, name: "${R2_SECRET_ACCESS_KEY_SECRET:?set R2_SECRET_ACCESS_KEY_SECRET}"}
-  operator_password: {external: true, name: "${OPERATOR_PASSWORD_SECRET:?set OPERATOR_PASSWORD_SECRET}"}
-  payment_token: {external: true, name: "${PAYMENT_TOKEN_SECRET:?set PAYMENT_TOKEN_SECRET}"}
-  payment_webhook_secret: {external: true, name: "${PAYMENT_WEBHOOK_SECRET:?set PAYMENT_WEBHOOK_SECRET}"}
-  tiny_token: {external: true, name: "${TINY_TOKEN_SECRET:?set TINY_TOKEN_SECRET}"}
-  whatsapp_token: {external: true, name: "${WHATSAPP_TOKEN_SECRET:?set WHATSAPP_TOKEN_SECRET}"}
-
-volumes:
-  postgres-data:
-    external: true
-    name: ${POSTGRES_VOLUME:?set POSTGRES_VOLUME}
-
-networks:
-  backend:
-    driver: overlay
-    internal: true
-  egress:
-    driver: overlay

deploy/test_production_preflight.py

@@ -1,8 +1,30 @@
 import unittest
+from pathlib import Path
 
 from .production_preflight import config_errors, source_errors
 
 
+class ReleaseWorkflowTests(unittest.TestCase):
+    def test_only_checked_main_publishes_and_pushes_never_deploy(self):
+        workflow = (Path(__file__).resolve().parents[1] /
+                    '.gitea/workflows/deploy.yml').read_text()
+        checks, release = workflow.split('  publish-and-deploy:\n', 1)
+        # Publishing waits for every check, and only ever happens from main.
+        self.assertIn('needs: [validate, integration, scan]', release)
+        self.assertIn("if: gitea.ref == 'refs/heads/main' && ", release)
+        # The source preflight lives in the scan job and can be made blocking.
+        self.assertIn('python3 deploy/production_preflight.py --source-only', checks)
+        self.assertIn('ENFORCE_PRODUCTION_PREFLIGHT', checks)
+        # Images are scanned before they are pushed, and a push to main only
+        # publishes: redeployment is Portainer's (or a manual run's) decision.
+        scan = release.index('- name: Image vulnerabilities')
+        publish = release.index('- name: Publish validated images')
+        redeploy = release.index('- name: Trigger Portainer redeployment')
+        self.assertLess(scan, publish)
+        self.assertLess(publish, redeploy)
+        self.assertIn("if: gitea.event_name == 'workflow_dispatch'", release[redeploy:])
+
+
 def valid_config():
     digest = '1' * 64
     values = {
@@ -27,7 +49,7 @@ def valid_config():
         'POSTGRES_USER': 'dtf_admin',
         'APP_DB_USER': 'dtf_app',
         'POSTGRES_VOLUME': 'dtf-postgres-data',
-        'OPERATOR_USER': 'dtf-operator',
+        'OPERATOR_EMAIL': 'operador@example.com',
         'STORAGE_QUOTA_BYTES': '53687091200',
         'OWNER_UPLOAD_QUOTA_BYTES': '10737418240',
         'MAX_UPLOAD_BYTES': '5368709120',
@@ -50,6 +72,26 @@ def valid_config():
     return values
 
 
+class SourceMarkerTests(unittest.TestCase):
+    """A marker that stops matching weakens the gate without failing it.
+
+    This is how four markers silently died when the runtime gained R2 support,
+    and how the payment one died again when it moved to runtime.py. Assert that
+    every marker still points at something real.
+    """
+
+    def test_every_marker_is_found_in_its_file(self):
+        from deploy.production_preflight import ROOT, SOURCE_BLOCKERS
+        for relative, markers in SOURCE_BLOCKERS.items():
+            path = ROOT / relative
+            self.assertTrue(path.exists(), f'{relative} no longer exists')
+            text = path.read_text()
+            for marker in markers:
+                self.assertIn(marker, text,
+                              f'{relative} no longer contains {marker!r}: the gate '
+                              'would pass without the condition being resolved')
+
+
 class ProductionPreflightTests(unittest.TestCase):
     def test_structurally_complete_metadata_passes(self):
         self.assertEqual(config_errors(valid_config()), [])
@@ -80,8 +122,8 @@ class ProductionPreflightTests(unittest.TestCase):
 
     def test_fake_checkout_is_explicitly_blocked(self):
         errors = source_errors()
-        self.assertTrue(any('local/app.py remains local-only' in error for error in errors))
-        self.assertTrue(any('local/worker.py remains local-only' in error for error in errors))
+        self.assertTrue(any('app/runtime.py remains local-only' in error for error in errors))
+        self.assertTrue(any('app/worker.py remains local-only' in error for error in errors))
 
     def test_secret_reuse_and_incoherent_limits_are_rejected(self):
         values = valid_config()
@@ -92,6 +134,7 @@ class ProductionPreflightTests(unittest.TestCase):
         self.assertTrue(any('distinct external Swarm secret' in error for error in errors))
         self.assertIn('OWNER_UPLOAD_QUOTA_BYTES cannot exceed STORAGE_QUOTA_BYTES', errors)
         self.assertIn('SCAN_MAX_BYTES cannot exceed MAX_UPLOAD_BYTES', errors)
+        self.assertTrue(any('configured ClamAV 128 MiB stream limit' in error for error in errors))
 
 
 if __name__ == '__main__':

docker-compose.yml

@@ -2,18 +2,77 @@ version: "3.8"
 
 x-app-environment: &app-environment
   APP_ENV: production
-  DATABASE_URL: postgresql://dtf_app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/dtf
+  DATABASE_HOST: db
+  DATABASE_NAME: dtf
+  DATABASE_USER: dtf_app
+  # Must differ from POSTGRES_PASSWORD: the runtime role is DML-only, and reusing
+  # the administrator credential would make that restriction meaningless.
+  DATABASE_PASSWORD: ${APP_DB_PASSWORD:?set APP_DB_PASSWORD}
   S3_ENDPOINT: ${R2_ENDPOINT:?set R2_ENDPOINT}
   S3_PUBLIC_ENDPOINT: ${R2_ENDPOINT:?set R2_ENDPOINT}
   S3_BUCKET: ${R2_BUCKET:?set R2_BUCKET}
   AWS_ACCESS_KEY_ID: ${R2_ACCESS_KEY_ID:?set R2_ACCESS_KEY_ID}
   AWS_SECRET_ACCESS_KEY: ${R2_SECRET_ACCESS_KEY:?set R2_SECRET_ACCESS_KEY}
   AWS_DEFAULT_REGION: auto
-  OPERATOR_USER: operator
+  # Optional at deploy time so a missing Kanban credential cannot make the
+  # entire Swarm stack invalid. The Kanban login endpoint fails closed until
+  # this value is configured.
+  OPERATOR_EMAIL: ${OPERATOR_EMAIL:-}
   OPERATOR_PASSWORD: ${OPERATOR_PASSWORD:?set OPERATOR_PASSWORD}
-  PAYMENT_ADAPTER: fake
-  FREIGHT_ADAPTER: fake
+  # fake until Mercado Pago is configured; mercadopago requires MP_ACCESS_TOKEN
+  # and MP_WEBHOOK_SECRET or the API and worker refuse to start. Test
+  # credentials (TEST-...) until the sandbox flows have passed. The card form
+  # appears only with MP_PUBLIC_KEY, and then needs PAYMENT_CSP_SOURCES too.
+  PAYMENT_ADAPTER: ${PAYMENT_ADAPTER:-fake}
+  MP_ACCESS_TOKEN: ${MP_ACCESS_TOKEN:-}
+  # The "assinatura secreta" from the webhook settings in Mercado Pago.
+  MP_WEBHOOK_SECRET: ${MP_WEBHOOK_SECRET:-}
+  # https://<SITE_DOMAIN>/api/payments/webhook, sent with every payment.
+  MP_NOTIFICATION_URL: ${MP_NOTIFICATION_URL:-}
+  MP_PUBLIC_KEY: ${MP_PUBLIC_KEY:-}
+  # The fake adapter's secret. Optional: without it the webhook verifies
+  # nothing and therefore accepts nothing, which is the correct state until a
+  # provider is connected. Never set it to a value anyone could guess.
+  PAYMENT_WEBHOOK_SECRET: ${PAYMENT_WEBHOOK_SECRET:-}
+  # fake offers pickup only. jadlog prices delivery with Jadlog and needs the
+  # credentials below and the package weight from the client; it refuses to
+  # start without them. The credentials alone are enough for the console
+  # check, python -m app.jadlog_probe, on the worker.
+  FREIGHT_ADAPTER: ${FREIGHT_ADAPTER:-fake}
+  JADLOG_TOKEN: ${JADLOG_TOKEN:-}
+  # The "Usuário" Jadlog issued: the CNPJ that contracts the freight.
+  JADLOG_CNPJ: ${JADLOG_CNPJ:-}
+  JADLOG_CONTA: ${JADLOG_CONTA:-}
+  JADLOG_CONTRATO: ${JADLOG_CONTRATO:-}
+  # Package weight in kg: a base plus each billed metre of film.
+  JADLOG_PESO_BASE_KG: ${JADLOG_PESO_BASE_KG:-}
+  JADLOG_PESO_POR_METRO_KG: ${JADLOG_PESO_POR_METRO_KG:-}
+  # Working days of production added to Jadlog's delivery time.
+  FREIGHT_PRODUCTION_DAYS: ${FREIGHT_PRODUCTION_DAYS:-0}
+  # A cart the Site priced is approved at checkout and can be paid at once;
+  # orders above QUOTE_AUTO_MAX_METRES, or with a grade the Site did not
+  # compute, wait for an operator on the Kanban (app/quote_review.py).
+  QUOTE_AUTO_APPROVE: ${QUOTE_AUTO_APPROVE:-true}
+  QUOTE_AUTO_MAX_METRES: ${QUOTE_AUTO_MAX_METRES:-50}
+  # Order creation in Tiny stays off until it has been tested against the
+  # client's account (Tiny has no sandbox). The application credentials can be
+  # set now: they let an operator connect Tiny from the Kanban, and the worker
+  # keeps that connection alive. Callback: https://<KANBAN_DOMAIN>/api/operator/tiny/callback
   TINY_ADAPTER: fake
+  TINY_CLIENT_ID: ${TINY_CLIENT_ID:-}
+  TINY_CLIENT_SECRET: ${TINY_CLIENT_SECRET:-}
+  TINY_REDIRECT_URI: ${TINY_REDIRECT_URI:-}
+  TINY_PRODUCT_TEXTIL_FOLHA: ${TINY_PRODUCT_TEXTIL_FOLHA:-}
+  TINY_PRODUCT_TEXTIL_AVULSA: ${TINY_PRODUCT_TEXTIL_AVULSA:-}
+  TINY_PRODUCT_UV_FOLHA: ${TINY_PRODUCT_UV_FOLHA:-}
+  TINY_PRODUCT_UV_AVULSA: ${TINY_PRODUCT_UV_AVULSA:-}
+  # The client's "retirar pessoalmente" forma de envio id, on pickup orders.
+  TINY_FORMA_ENVIO_RETIRADA: ${TINY_FORMA_ENVIO_RETIRADA:-}
+  # Sets "Aprovada" on paid orders and "Pronto para envio" on finished pickup
+  # orders, which the client's Tiny -> n8n notices send to customers. Turn on
+  # only together with TINY_ADAPTER=tiny and after n8n stops sending the
+  # designer message for DTFIMP products.
+  TINY_STATUS_UPDATES: ${TINY_STATUS_UPDATES:-false}
   WHATSAPP_ADAPTER: fake
   STORAGE_ADAPTER: s3-r2
   PUBLIC_ORIGIN: https://${SITE_DOMAIN:?set SITE_DOMAIN}
@@ -23,10 +82,13 @@ x-app-environment: &app-environment
   COOKIE_SECURE: "true"
   MAX_UPLOAD_BYTES: "5368709120"
   UPLOAD_PART_BYTES: "8388608"
-  STORAGE_QUOTA_BYTES: "53687091200"
-  OWNER_UPLOAD_QUOTA_BYTES: "10737418240"
+  # Sheets of several GB are the normal order, so room for many of them.
+  STORAGE_QUOTA_BYTES: "${STORAGE_QUOTA_BYTES:-536870912000}"
+  OWNER_UPLOAD_QUOTA_BYTES: "${OWNER_UPLOAD_QUOTA_BYTES:-53687091200}"
   MAX_PENDING_UPLOADS: "10"
-  SCAN_MAX_BYTES: "134217728"
+  # ClamAV scans up to this; larger files (up to MAX_UPLOAD_BYTES) are released
+  # after a file-format check instead (app/scanning.py).
+  SCAN_MAX_BYTES: "2097152000"
 
 services:
   db:
@@ -49,11 +111,20 @@ services:
 
   db-init:
     image: ${API_IMAGE:-gitea.blyzer.com.br/blyzer/dtf-api}:${IMAGE_TAG:-latest}
-    command: python -m local.bootstrap
+    command: python -m app.bootstrap
     environment:
-      DATABASE_ADMIN_URL: postgresql://dtf_admin:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/dtf
+      DATABASE_ADMIN_HOST: db
+      DATABASE_ADMIN_NAME: dtf
+      DATABASE_ADMIN_USER: dtf_admin
+      DATABASE_ADMIN_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
       APP_DB_USER: dtf_app
-      APP_DB_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      APP_DB_PASSWORD: ${APP_DB_PASSWORD:?set APP_DB_PASSWORD}
+      # The migration job seeds the first operator account from these, so an
+      # existing deployment keeps its Kanban login after the accounts table
+      # lands. Without them there would be no account at all and login would
+      # fail closed with 503.
+      OPERATOR_EMAIL: ${OPERATOR_EMAIL:-}
+      OPERATOR_PASSWORD: ${OPERATOR_PASSWORD:?set OPERATOR_PASSWORD}
     networks: [backend]
     deploy:
       replicas: 1
@@ -63,7 +134,7 @@ services:
     image: clamav/clamav@sha256:9cb27d7660bdf66e9878c832cb433dd8aa152cfbe16f3c2c0084c80b04ae22b4
     entrypoint: [clamd, --foreground=true, --config-file=/etc/clamav/clamd.conf]
     configs:
-      - source: clamd_config
+      - source: clamd_config_2gb
         target: /etc/clamav/clamd.conf
         mode: 0444
     networks: [backend]
@@ -97,7 +168,7 @@ services:
 
   worker:
     image: ${API_IMAGE:-gitea.blyzer.com.br/blyzer/dtf-api}:${IMAGE_TAG:-latest}
-    command: python -m local.worker
+    command: python -m app.worker
     environment: *app-environment
     networks: [backend, egress]
     read_only: true
@@ -112,12 +183,47 @@ services:
       replicas: 1
       restart_policy: {condition: on-failure, delay: 5s}
 
+  # Daily encrypted copy of the database to a bucket of its own, off this
+  # server (ops/db_backup.py). Idle until the BACKUP_* settings are set. The
+  # bucket's lifecycle rule removes old copies; this credential never deletes.
+  backup:
+    image: ${API_IMAGE:-gitea.blyzer.com.br/blyzer/dtf-api}:${IMAGE_TAG:-latest}
+    command: python -m ops.db_backup serve
+    environment:
+      DATABASE_ADMIN_HOST: db
+      DATABASE_ADMIN_NAME: dtf
+      DATABASE_ADMIN_USER: dtf_admin
+      DATABASE_ADMIN_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      # The R2 account endpoint (the same as R2_ENDPOINT) and a bucket and API
+      # token for backups only, never the artwork bucket's.
+      BACKUP_S3_ENDPOINT: ${BACKUP_S3_ENDPOINT:-}
+      BACKUP_BUCKET: ${BACKUP_BUCKET:-}
+      BACKUP_ACCESS_KEY_ID: ${BACKUP_ACCESS_KEY_ID:-}
+      BACKUP_SECRET_ACCESS_KEY: ${BACKUP_SECRET_ACCESS_KEY:-}
+      # The public key (age1...). Its private key stays off this server.
+      BACKUP_AGE_RECIPIENT: ${BACKUP_AGE_RECIPIENT:-}
+      # Hour of day in Brasília.
+      BACKUP_HOUR: ${BACKUP_HOUR:-3}
+    networks: [backend, egress]
+    read_only: true
+    tmpfs: [/tmp]
+    deploy:
+      replicas: 1
+      restart_policy: {condition: on-failure, delay: 30s}
+
   site:
     image: ${WEB_IMAGE:-gitea.blyzer.com.br/blyzer/dtf-web}:${IMAGE_TAG:-latest}
     environment:
       WEB_INDEX: index.html
       PUBLIC_HOST: ${SITE_DOMAIN:?set SITE_DOMAIN}
       S3_PUBLIC_ENDPOINT: ${R2_ENDPOINT:?set R2_ENDPOINT}
+      # Mercado Pago's card form loads from these origins; empty keeps the
+      # Site at script-src 'self'. Set together with the Mercado Pago adapter.
+      PAYMENT_CSP_SOURCES: ${PAYMENT_CSP_SOURCES:-}
+      # The bank's confirmation page for debit and other 3-D Secure cards is
+      # on the issuer's own domain, so it cannot be listed: "https:" lets
+      # frames and form posts reach it (never scripts). Empty turns it off.
+      PAYMENT_CHALLENGE_SOURCES: ${PAYMENT_CHALLENGE_SOURCES:-}
     networks: [backend]
     ports:
       - target: 8080
@@ -140,6 +246,8 @@ services:
       WEB_INDEX: kanban.html
       PUBLIC_HOST: ${KANBAN_DOMAIN:?set KANBAN_DOMAIN}
       S3_PUBLIC_ENDPOINT: ${R2_ENDPOINT:?set R2_ENDPOINT}
+      PAYMENT_CSP_SOURCES: ""
+      PAYMENT_CHALLENGE_SOURCES: ""
     networks: [backend]
     ports:
       - target: 8080
@@ -157,8 +265,10 @@ services:
       restart_policy: {condition: on-failure, delay: 5s}
 
 configs:
-  clamd_config:
-    file: ./local/clamd.conf
+  # Renamed whenever infra/clamd.conf changes: Swarm cannot update a deployed
+  # config in place, and a redeploy with new content under the old name fails.
+  clamd_config_2gb:
+    file: ./infra/clamd.conf
 
 volumes:
   postgres-data:

docs/BACKUP.md

@@ -0,0 +1,87 @@
+# Database backup
+
+The `backup` service copies the database off the server once a day
+(`ops/db_backup.py`). It runs `pg_dump`, checks the archive, encrypts it with
+[age](https://age-encryption.org) and uploads it to an R2 bucket used for
+nothing else. Each run is recorded, and the Kanban shows the latest one under
+Integrações → "Backup do banco" ("Em dia", "Verificar" or "Não configurado").
+
+The artwork is not backed up. Originals and print files are temporary (7 to 30
+days) and already stored on R2. The database holds what cannot be recreated:
+orders, customers, quotes, payments, the Tiny connection and the operators.
+
+## Why the backup cannot be read or deleted from the server
+
+- **The server only encrypts.** It holds the public key (`age1…`). The private
+  key, which is the only way to open a backup, stays with the owner.
+- **Its own bucket and token.** The backup token reaches the backup bucket
+  only, and the artwork token cannot reach it.
+- **Nothing is deleted by the job.** The bucket's lifecycle rule removes old
+  copies. The bucket lock keeps anyone, including someone holding the token,
+  from deleting or overwriting a copy before its time.
+
+## Setup (once)
+
+1. **Key pair.** Generate it on your own computer, not on the server:
+
+   ```bash
+   docker run --rm gitea.blyzer.com.br/blyzer/dtf-api:latest age-keygen
+   ```
+
+   Or, with age installed (`sudo pacman -S age`, `apt install age`), just
+   run `age-keygen`.
+
+   Save the whole output (the `AGE-SECRET-KEY-1…` line is the private key) in
+   the password manager. Only the `public key: age1…` value goes to Portainer.
+   Without the private key, no backup can ever be restored.
+2. **Cloudflare R2 → Create bucket.** Use a name such as `dtf-backups`.
+3. **Settings on that bucket:**
+   - Object lifecycle rules: delete objects after 35 days.
+   - Bucket lock rules: retain for 30 days, prefix `db/`.
+4. **R2 → Manage API tokens → Create API token.**
+   - Permission: Object Read & Write.
+   - Scope: the `dtf-backups` bucket only.
+5. **Portainer.** Add these to the stack's environment, then redeploy:
+
+   | Variable | Value |
+   |---|---|
+   | `BACKUP_S3_ENDPOINT` | same as `R2_ENDPOINT` |
+   | `BACKUP_BUCKET` | `dtf-backups` |
+   | `BACKUP_ACCESS_KEY_ID` | the new token's Access Key ID |
+   | `BACKUP_SECRET_ACCESS_KEY` | the new token's Secret Access Key |
+   | `BACKUP_AGE_RECIPIENT` | the public key, `age1…` |
+   | `BACKUP_HOUR` | optional, default `3` (03:00 Brasília) |
+
+The first backup runs as soon as the service starts. After that it runs daily,
+and a failed run is retried an hour later.
+
+## Restore test
+
+Do this after setup, and then once a month. Open the console of the `backup`
+container in Portainer (Containers → `…_backup…` → Console) and run:
+
+```bash
+python -m ops.db_backup list
+python -m ops.db_backup verify --identity -
+```
+
+`--identity -` asks for the private key to be pasted. It is kept only in the
+container's memory while the command runs. `verify` restores the latest backup
+into a scratch database, prints its row counts and drops it. The live database
+is not touched.
+
+## Restoring for real
+
+From the `backup` container's console:
+
+```bash
+python -m ops.db_backup restore db/2026/10/dtf-20261001T060000Z.dump.age --into dtf_restored --identity -
+```
+
+This restores into a new database (or an empty one), never over the running
+one. Then do one of these:
+
+- **Check the restored data**, then point the stack at it.
+- **On a new server**, deploy only the `db` service first. Restore into `dtf`
+  while it is still empty, then deploy the rest. `db-init` then applies the
+  schema and grants on top.

docs/CONTEXT.md

@@ -4,7 +4,7 @@
 
 Read this document before changing code, documentation, architecture, or scope.
 It is the current English source of truth for the project. It supersedes older
-decisions in `README.md`, `ESPECIFICACAO.md`, `schema.sql`, and the existing
+decisions in `README.md`, `docs/historico/ESPECIFICACAO.md`, `schema.sql`, and the existing
 prototype code whenever they conflict.
 
 Update this file whenever the team makes a material product, process, or
@@ -96,6 +96,9 @@ resumes when local access returns.
   Actions workflow tests/scans, publishes `latest` plus commit-SHA application
   images, and calls the Portainer webhook. Activation remains blocked pending
   the production work listed below.
+- **Kanban access:** configure `OPERATOR_EMAIL` and `OPERATOR_PASSWORD` as
+  stack environment variables. If the email is absent, only Kanban login is
+  blocked; the rest of the stack remains available.
 - **Recommended VPS baseline:** 4 vCPU, 16 GB RAM, and 200 GB NVMe. Existing
   VPS capacity may be used if it safely meets or exceeds this baseline.
 - **Backups:** PostgreSQL backups go to R2. Application secrets are never
@@ -138,7 +141,7 @@ taxes, and payment-provider fees before presenting a commercial quote.
 
 ## Commercial rules
 
-The existing rules in `dtf-site.html` are approved as the current source of
+The existing rules in `web/index.html` are approved as the current source of
 truth. Do **not** redesign, simplify, or change prices, discounts, minimums,
 rounding, or product modes without explicit approval.
 
@@ -150,9 +153,17 @@ The browser may display the calculation, but production payment creation must
 recalculate and validate all price, quantity, freight, and discount values on
 the server. Client-provided totals are never authoritative.
 
+Normal JPG/PNG uploads are individual artwork by default, including when uploaded
+from the by-metre panel. They use the existing loose-artwork editor, printed
+width, quantity, and live packing canvas; packed height determines metres.
+Customers uploading an already assembled film-width image must explicitly select
+the ready-sheet option before uploading. PDF and manual-format ready sheets keep
+their existing workflow. These models retain their separate approved price tiers;
+image dimensions alone must never classify a normal artwork as a finished sheet.
+
 ## Freight
 
-The original visual freight flow in `dtf-site.html` was a stub with only pickup
+The original visual freight flow in `web/index.html` was a stub with only pickup
 functional. The localhost bridge now supports pickup and backend fake freight
 quotes; there is still no real carrier quotation or production checkout.
 
@@ -238,7 +249,7 @@ supports subsequent corrections or scoped enhancements.
 
 The current implementation target is localhost before any production connection.
 Use `docker-compose.yml`, `.env.example`, and `LOCAL_SETUP.md`. The runtime is in
-`local/`; historical `portal/`, `kanban/`, `agente/`, and `schema.sql` are preserved
+`app/`; historical `portal/`, `kanban/`, `agente/`, and `schema.sql` are preserved
 as references and are not imported or started by Compose.
 
 - One local `dtf-cloud` Compose project runs seven long-lived services: Site and
@@ -286,23 +297,24 @@ as references and are not imported or started by Compose.
   files can be quoted, commercially approved, paid, downloaded, attached as final
   files, or admitted to the print queue. Rejected/error files remain blocked and
   expire within three days. The isolated scanner uses signatures bundled in its
-  pinned image and has no external network route. The transport accepts files up
-  to 5 GiB, but the local scan/release limit is 128 MiB; larger files remain
-  blocked. This malware gate is not print pre-flight or artwork validation.
+  pinned image and has no external network route. The multipart transport could
+  carry 5 GiB, but API and customer admission stop at the effective 128 MiB
+  scan/release limit by default. Larger files require a new scan/release design.
+  This malware gate is not print pre-flight or artwork validation.
 - A retention worker removes expired object bytes but keeps order/file metadata:
-  incomplete uploads after one day, originals within seven days of manual final
+  incomplete uploads after a one-hour reservation lease, originals within seven days of manual final
   artwork approval, and attached final/correction files within 30 days of the
   order's first upload. Storage lifecycle is also a 30-day backstop.
 - Structured security events are written to logs and PostgreSQL. The local
   `security_status` command summarizes authentication, rate-limit, scan, and
   scanner/signature alerts without exposing secrets. Security regression tests,
   exact-runtime Python dependency auditing, and Trivy image reports live under
-  `local/` and `output/security/`; open findings are documented in
+  `app/` and `output/security/`; open findings are documented in
   `SECURITY_REPORT.md` and are not a production-readiness claim.
 - All direct and transitive Python packages are pinned with artifact hashes in
-  `local/requirements.lock`; the API image build requires those hashes. The lock
+  `infra/requirements.lock`; the API image build requires those hashes. The lock
   is regenerated in a disposable Python 3.12 container by
-  `local/lock_dependencies.sh`. A fresh exact-runtime audit found no known Python
+  `infra/lock_dependencies.sh`. A fresh exact-runtime audit found no known Python
   advisories on 2026-09-15; this does not cover OS/container findings.
 - `compose.staging.yaml` is a separate, network-disabled readiness gate only. It
   validates non-secret staging decisions and rejects placeholders, local endpoints,
@@ -316,7 +328,7 @@ as references and are not imported or started by Compose.
   not been deployed. Its fail-closed preflight intentionally rejects the current
   source until production adapters, Docker-secret file loading, approved inputs,
   restore rehearsal, image scans, and human security approval are complete.
-- `python3 -m local.backup create-and-verify` creates a private, Git-ignored bundle
+- `python3 -m ops.backup create-and-verify` creates a private, Git-ignored bundle
   containing a PostgreSQL dump plus every complete, unexpired object already marked
   `clean`. SHA-256 manifests protect both parts. Verification restores the database
   under a UUID name and the object bytes under a UUID MinIO prefix, hashes the
@@ -329,7 +341,7 @@ as references and are not imported or started by Compose.
   activation remain incomplete. Deployment plumbing exists but cannot pass its
   release gate yet. No factory automation or pre-flight is added.
 
-See `IMPLEMENTATION_REPORT.md` for verification, `PRODUCTION_INPUTS.md` for the
+See `docs/historico/IMPLEMENTATION_REPORT.md` for verification, `PRODUCTION_INPUTS.md` for the
 decisions and evidence required before staging or production connection, and
 `PORTAINER.md` for the production delivery contract.
 The client roadmap promises are unchanged, so its PDF source is not regenerated
@@ -337,17 +349,18 @@ for this local implementation checkpoint.
 
 ### Existing assets
 
-- `dtf-site.html`: rich static front-end prototype. It includes the current
-  commercial rules, client-side artwork analysis, current-session cart, and
-  delivery UI. The localhost checkout bridge connects it to the new local API.
-- `portal/`: early FastAPI prototype for the original Tiny-first, token-link
-  upload flow.
-- `kanban/`: early FastAPI/SQLite Kanban prototype.
-- `agente/`: factory-side agent prototype; out of current MVP scope.
-- `tmp/pdfs/generate_dtf_report.py`: generator for the current client-facing
-  roadmap PDF.
-- `output/pdf/dtf-plano-producao-e-roadmap.pdf`: current generated roadmap.
-- `Reunião iniciada às 2026_09_09 09_39 GMT-03_00 - Anotações do Gemini.pdf`:
+- `web/`: the Site (`index.html`), the Kanban and customer portal pages, and
+  the scripts behind them. `web/site-*.js` holds the Site's behaviour.
+- `docs/historico/`: the original specification, endpoint sketch, task plan and
+  status report. Background only — they describe a model this system does not
+  implement.
+
+The prototypes they describe (`portal/`, `kanban/`, `agente/`, the root
+`schema.sql` and `.env.exemplo`) were removed on 2026-09-21 once nothing
+referenced them; recover from Git history if ever needed.
+- `tools/generate_dtf_report.py`: generator for the client-facing roadmap PDF.
+- `docs/roadmap-cliente.pdf`: the generated roadmap, as last sent.
+- `docs/reuniao-2026-09-09-anotacoes.pdf`:
   meeting notes that established the business direction. Treat it as context;
   the latest decisions in this document define the active scope.
 
@@ -356,12 +369,12 @@ for this local implementation checkpoint.
 - The original Site had no backend payment, freight quote, order persistence,
   authentication, purchase history, or real cart persistence. Local order
   persistence, reviewed quotes, mock freight and fake payment now work through
-  `local/static/checkout.js`. The local customer portal now provides accounts and
+  `web/checkout.js`. The local customer portal now provides accounts and
   order history; cart recovery is browser-local. Production account verification,
   recovery, and cross-device cart editing are still absent.
 - Without the local bridge, the original freight fallback remains a stub.
   Real freight quotation remains unimplemented in all runtimes.
-- The existing `portal/whats.py` and `kanban/whats.py` are duplicated and send
+- The existing the removed prototypes duplicated WhatsApp senders and send
   direct text messages. They are not production-ready notification modules.
 - Older documentation and code describe a Tiny webhook creating an upload link,
   a factory agent, local Kanban, FlexiPRINT automation, 90-day retention, and
@@ -371,8 +384,7 @@ for this local implementation checkpoint.
 
 `context.md` is the compact operating context for agents. The current
 client-facing narrative, diagrams, and formatting live in
-`output/pdf/dtf-plano-producao-e-roadmap.pdf`, generated from
-`tmp/pdfs/generate_dtf_report.py`.
+`docs/roadmap-cliente.pdf`, generated from `tools/generate_dtf_report.py`.
 
 When a decision changes, update both the relevant implementation context here
 and the roadmap source when it changes what the client-facing plan promises.

docs/LOCAL_SETUP.md

@@ -1,6 +1,6 @@
 # DTF local development
 
-Read `CONTEXT.md` first. The current runtime lives in `local/`; older portal,
+Read `CONTEXT.md` first. The service lives in `app/`; older portal,
 Kanban, agent, requirements, and SQL files are historical prototypes.
 
 ## Start
@@ -12,16 +12,19 @@ public container images and Python packages; running integrations are local.
 From this repository directory:
 
 ```bash
-docker compose up --build
+docker compose -f compose.local.yaml up --build
 ```
 
+`docker-compose.yml` is the production/R2 stack and will not start locally; the
+localhost stack is always `compose.local.yaml`.
+
 No `.env` is required: Compose has the same disposable defaults as `.env.example`.
 To customize, copy `.env.example` to `.env` and edit it. Never use real credentials.
 For a detached start with readiness verification:
 
 ```bash
-docker compose up --build -d --wait
-docker compose ps
+docker compose -f compose.local.yaml up --build -d --wait
+docker compose -f compose.local.yaml ps
 ```
 
 | Component | Local URL / port | Purpose |
@@ -39,7 +42,7 @@ docker compose ps
 Use `localhost` consistently; mixing it with `127.0.0.1` creates a different
 browser session. Published ports bind only to `127.0.0.1`.
 
-Kanban default login: `operator` / `local-operator-only`.
+Kanban default login: `operator@example.test` / `local-operator-only`.
 MinIO default login: `dtf_local` / `local-storage-only`.
 These are public, disposable development values, not real credentials.
 Interactive API documentation is disabled; `/docs` and `/redoc` are not local
@@ -48,7 +51,7 @@ operator interfaces.
 ## Browser test order
 
 1. Open the Site. Choose **Arquivo por metro** and the manual/table-price path
-   (CDR/AI/PSD/TIFF). Select `local/fixtures/local-test.cdr`. This is deliberately
+   (CDR/AI/PSD/TIFF). Select `tests/fixtures/local-test.cdr`. This is deliberately
    harmless text for upload testing, not a printable CDR file.
 2. Enter **1.01 metres**. The original calculation bills **1.10 m × R$19.90 =
    R$21.89**, with grade 0 and pickup. You can also use your own non-sensitive
@@ -59,22 +62,35 @@ operator interfaces.
 4. Click the Site checkout button. Files upload directly to MinIO, remain
    quarantined until ClamAV returns `clean`, and then become eligible for a quote.
    The local banner displays a quote ID awaiting commercial review.
-5. Open Kanban and log in. In **Cotações**, download the original if needed,
-   confirm/correct total metres and grade, tick the manual confirmation, and
-   click **Aprovar cotação**. For the fixture keep 1.01 m and grade 0.
-6. Return to the Site, click **Atualizar pedido local**, inspect the authoritative
-   server total, then click **Criar pedido pago local**. No real payment occurs.
-7. Refresh Kanban. The paid order starts in **Arte recebida**. Move it using
-   the buttons or drag and drop to **Arte tratada**. Open **Arquivos de produção**,
-   select the manually prepared final files for every item, enter a review note,
-   tick the confirmation and click **Aprovar arquivos finais**. Use the harmless
-   fixture again only for this local test; no printable file is generated.
-   Continue through **Fila de impressão →
-   Imprimindo → Finalizado**. A move to **Correção** requires a reason; it can
-   return to **Arte recebida** or **Arte tratada**. Finalizado is terminal locally.
-8. Inspect **Histórico** and **Eventos locais de integração**. Worker receipts
-   should say recorded locally. Download links expire after five minutes;
-   request another link from Kanban when needed.
+5. Open Kanban and log in. Open the **Cotações** tab, pick the quote, download
+   the original if needed, confirm/correct metres and grade, tick the
+   confirmation at the bottom and click **Aprovar cotação**. For the fixture
+   keep 1.01 m and grade 0.
+6. Return to the Site and click its checkout action again. Inspect the
+   authoritative server total, then click **Criar pedido de teste**. No real
+   payment occurs.
+7. Click **Atualizar** on the Kanban. The paid order appears in **Arte
+   recebida** on the **Produção** tab. Click its card to open the order panel,
+   then **Mover para Arte tratada** (dragging the card to a column also works).
+   In the panel's **Arquivos finais**, select the manually prepared final file
+   for every item, enter a review note, tick the confirmation and click
+   **Aprovar arquivos finais**. Use the harmless fixture again only for this
+   local test. The text fixture is not an image, so its print file shows
+   **Preparar à mão**; with a PNG, JPEG or PDF artwork the generated file is
+   preselected instead (see "Print files"). Continue with the panel's main
+   button through **Fila de impressão → Imprimindo → Finalizado**. **Pedir
+   correção** asks for the reason the customer will see; from **Correção** the
+   order returns to **Arte recebida** or **Arte tratada**. A move made by
+   mistake is undone with **Voltar para …**: one stage back, with an internal
+   reason recorded in the history. The customer is not notified, approved
+   finals stay, and "produção iniciada"/"pedido pronto" are sent only once per
+   order even if the stage is entered again. Dragging a card only goes forward;
+   the columns it can be dropped on are highlighted.
+8. The panel's **Histórico** lists every move. The **Pagamentos** tab lists
+   payments that need a person; **Integrações** shows the Tiny connection and
+   the send log; with the fake adapters every send reads "Registrado
+   (simulado)". Download links expire after five minutes; click again for a new
+   one. The previous Kanban is kept in git tag `ui-v1`.
 
 The manual quote step is necessary to enforce the backend trust boundary while
 automatic pre-flight is deferred. Browser measurements and grade are proposals.
@@ -131,15 +147,15 @@ Pricing parity requires Python 3.10+ and Node 22+ on the host, no package instal
 python3 -m unittest local.test_pricing -v
 ```
 
-This executes the real pricing constants/functions extracted from `dtf-site.html`
+This executes the real pricing constants/functions extracted from `web/site-config.js`
 and compares all four modes, 101 grades, and 11 lengths (4,444 cases) to backend
 pricing, plus assembly and invalid-input checks.
 
 With the stack healthy, run the integration test (Python standard library only):
 
 ```bash
-python3 -m local.smoke_test
-python3 -m local.workflow_test
+python3 -m tests.smoke_test
+python3 -m tests.workflow_test
 ```
 
 It checks direct two-part upload/resume, missing parts, session isolation,
@@ -155,10 +171,10 @@ Security and malware regressions are separate so an authorized harmless EICAR
 test is unmistakable:
 
 ```bash
-python3 -m local.security_test
-python3 -m local.scanning_test
-docker compose exec -T api python -m local.runtime_security_test
-docker compose exec -T api python -m local.retention_test
+python3 -m tests.security_test
+python3 -m tests.scanning_test
+docker compose -f compose.local.yaml exec -T api python3 -m tests.runtime_security_test
+docker compose -f compose.local.yaml exec -T api python3 -m tests.retention_test
 ```
 
 `local.scanning_test` stores an EICAR fixture as `SECURITY-EICAR.cdr`; ClamAV
@@ -168,7 +184,7 @@ is retained for at most three days, so it temporarily appears in alert summaries
 For an automated real-browser walkthrough, install Chrome and use Node 22+:
 
 ```bash
-node local/browser_test.mjs
+node tests/browser_test.mjs
 ```
 
 Set `CHROME_BIN` if Chrome is not at `/usr/bin/google-chrome-stable`. The test
@@ -179,23 +195,27 @@ test order for inspection. Both integration scripts read `.env` automatically.
 ## Configuration and storage
 
 `.env.example` lists local ports, database/MinIO values, operator login, adapter
-selection, mock freight amount, maximum file size (5 GiB), and multipart size
-(8 MiB by default). The malware scanner releases only files up to 128 MiB by
-default (`SCAN_MAX_BYTES`); larger uploads remain blocked even though the
-multipart transport supports 5 GiB. `S3_ENDPOINT=http://storage:9000`, database
+selection, mock freight amount, transport ceiling (5 GiB), and multipart size
+(8 MiB by default). The API and customer picker admit only files within the
+malware scanner's effective 128 MiB limit by default (`SCAN_MAX_BYTES`); the
+larger-file path remains a Week 2 decision. `S3_ENDPOINT=http://storage:9000`, database
 hostname `db`,
 and the internal service ports are fixed Compose wiring. The public S3 endpoint
 must resolve from the browser; keep `http://localhost:9000` for this stack.
-Parts use 15-minute presigned URLs and uploads must finish within one day.
+Parts use 15-minute presigned URLs and unfinished reservations expire after
+one hour. Clients can cancel a reservation through the upload DELETE endpoint.
 
-Only fake integration adapters and `s3-local` storage are accepted. Startup fails
-if a production adapter/environment or nonlocal S3 endpoint is selected.
+Fake integration adapters and `s3-local` storage are the default. Mercado Pago
+and Tiny can be selected for sandbox testing only (see "Provider sandboxes");
+startup fails if their credentials are missing, if any other adapter is
+selected, or if a production environment or nonlocal S3 endpoint is used.
 The API, worker, and database run on an internal Docker network; web gateways
 and MinIO also join a network that permits loopback port publishing.
 
 Objects are private, use UUID keys rather than filenames, and persist in a named
 volume. MinIO lifecycle rules expire objects after 30 days and abandon incomplete
-multipart uploads after one day; the API also blocks expired downloads. Order
+multipart uploads after one day as a backstop; the API lease and worker release
+unfinished reservations after one hour. The API also blocks expired downloads. Order
 history remains in PostgreSQL. Completed files start in `pending`; unknown,
 scanner-error, over-limit, encrypted/unsafe, and malware results fail closed.
 Only `clean` files can cross quote, payment, download, final-approval, and queue
@@ -210,10 +230,123 @@ storage permits; otherwise reselect them. Saved quote IDs also survive reloads.
 Clearing cookies loses a guest session, while registered customers can sign in
 again. The operator can still inspect order records.
 
+## Print files
+
+Every paid order queues one print-file job per item. The worker renders a PDF
+exactly as wide as the film and as long as the approved layout, placing each
+copy at the position, rotation and mirror the customer reviewed. Each source
+image is embedded once at its original resolution (JPEG bytes unchanged, PNG
+transparency kept as a soft mask), so nothing is resampled. The Kanban card
+shows the status per item, the page size and the lowest DPI, and offers
+**Baixar PDF**. In **Arquivos de produção** the generated file is preselected
+as the final file; untick it to upload one by hand instead.
+
+JPEG, PNG, WebP and TIFF are embedded as images. A single-page PDF is placed
+as a vector form (never rasterised), using the page's CropBox and `/Rotate`
+exactly as the Site measured it with pdf.js; the card then shows **PDF
+vetorial**. PSD, AI and CDR artwork, multi-page or password-protected PDFs, a
+file whose proportions do not match the quoted size, a layout longer than was
+billed, or an image above `PRINT_MAX_PIXELS` (250 Mpx by default) goes to
+**preparar à mão** with the reason, and the operator prepares it as before.
+**Gerar arquivos de impressão** retries those items and generates files for
+orders paid before the generator existed. After a customer correction the
+generated file is no longer offered: it reproduces the replaced artwork.
+
+Layouts longer than about 5 m use the PDF `UserUnit` page scale instead of
+being split into pages. Confirm on the factory's FlexiPRINT that such a file
+imports at full length before relying on it for long orders.
+
+```bash
+docker compose -f compose.local.yaml exec -T api python -m unittest tests.test_printfile -v
+docker compose -f compose.local.yaml exec -T api python -m tests.print_file_test
+```
+
+With PyMuPDF installed locally (`pip install pymupdf`), the unit suite also
+draws each page and checks where every quadrant of the artwork lands.
+
+## Provider sandboxes
+
+`app/mercadopago.py` and `app/tiny.py` follow the providers' public API
+documentation and pass their unit suites against a fake transport. They are not
+verified integrations until they pass with the client's accounts.
+
+The default local stack gives the API and worker no route to the internet, so
+provider testing adds `compose.providers.yaml`, which does:
+
+```bash
+docker compose -f compose.local.yaml -f compose.providers.yaml up -d --wait
+```
+
+Put only **test** credentials in `.env`:
+
+```bash
+PAYMENT_ADAPTER=mercadopago
+MP_ACCESS_TOKEN=TEST-...
+MP_WEBHOOK_SECRET=...            # "Assinatura secreta" in the webhook settings
+MP_NOTIFICATION_URL=https://<public tunnel>/api/payments/webhook
+```
+
+### Tiny (API v3)
+
+Tiny uses OAuth2. In the client's Tiny (Construa plan or above, with the
+"Gestão de Aplicativos" extension): **Configurações → Geral → Aplicativos →
++ novo aplicativo**, with the redirect URL set to this system's callback. That
+gives a client ID and secret:
+
+```bash
+TINY_CLIENT_ID=...
+TINY_CLIENT_SECRET=...
+TINY_REDIRECT_URI=http://localhost:8081/api/operator/tiny/callback   # exactly as registered in Tiny
+TINY_PRODUCT_TEXTIL_FOLHA=...            # Tiny product id for each Site product
+TINY_PRODUCT_TEXTIL_AVULSA=...
+TINY_PRODUCT_UV_FOLHA=...
+TINY_PRODUCT_UV_AVULSA=...
+```
+
+With the client ID and secret set, the Kanban header shows **Conectar Tiny**.
+Someone with a Tiny login approves access once; the tokens are stored in the
+database (the refresh token rotates on every use) and the worker keeps the
+connection alive. Only then set `TINY_ADAPTER=tiny`, which starts creating an
+order in Tiny for every paid order: find or create the customer's contact by
+CNPJ, then `POST /pedidos` with `numeroOrdemCompra = DTF-<order number>`. A
+retry searches the customer's recent orders for that number first, so it does
+not create a second one. **Tiny has no sandbox**: every test order is real, so
+agree the test with the client and cancel the test orders afterwards.
+
+`tests.tiny_oauth_test` checks the connection flow against the real database
+with a fake token server; it saves and restores any existing connection.
+
+With Mercado Pago selected, an approved quote shows **Pagar com PIX** on the
+Site instead of the local test button, and **Pagar com cartão** when
+`MP_PUBLIC_KEY` is set. The card form is Mercado Pago's Card Payment Brick: the
+card is typed into Mercado Pago's secure fields and only a one-time token
+reaches the API. It loads from Mercado Pago, so the Site's CSP must allow it:
+
+```bash
+MP_PUBLIC_KEY=TEST-...
+PAYMENT_CSP_SOURCES=https://sdk.mercadopago.com https://*.mercadopago.com https://*.mlstatic.com https://*.mercadolibre.com
+```
+
+`PAYMENT_CSP_SOURCES` is empty by default, which keeps the Site at
+`script-src 'self'`. The payment page offers credit card (the default), debit
+card and PIX. Card payments ask for 3-D Secure when the issuer requires it,
+which debit cards usually do: the bank's confirmation page opens in a frame on
+the issuer's own domain, so it needs `PAYMENT_CHALLENGE_SOURCES=https:` (frames
+and form posts only, never scripts; empty by default). Once a payment for a
+quote is approved, or a card payment is in review, the API refuses any further
+attempt for that quote; a card left waiting for the bank's confirmation stops
+blocking after ten minutes. The order is created only by the signed
+notification, after the payment is fetched from the Mercado Pago API and its
+BRL amount matches the approved total. Mercado Pago must be able to reach the
+webhook, so a local run needs a public HTTPS tunnel to the Site port. A paid
+notification that cannot become an order, or a refund on an existing order,
+appears under **Pagamentos que precisam de atenção** on the Kanban until an
+operator records the resolution.
+
 ## Local backup and restore check
 
 ```bash
-python3 -m local.backup create-and-verify
+python3 -m ops.backup create-and-verify
 ```
 
 This writes a private four-file bundle in `backups/` (ignored by Git and Docker
@@ -230,7 +363,7 @@ checks database counts, bundle hashes, every archived object's hash, and the byt
 downloaded after restore, then removes only the temporary database and objects. It
 never restores over active data. Keep every bundle file private: it contains
 customer data, password hashes, and customer artwork. To verify it again, run
-`python3 -m local.backup verify` followed by the printed
+`python3 -m ops.backup verify` followed by the printed
 `backups/...manifest.json` path. Legacy database-only `.dump` backups remain
 verifiable. Scheduling, offsite copies, and a production restore runbook remain
 unfinished.
@@ -238,7 +371,7 @@ unfinished.
 After building the current image, test retention with synthetic files:
 
 ```bash
-docker compose exec -T api python -m local.retention_test
+docker compose -f compose.local.yaml exec -T api python3 -m tests.retention_test
 ```
 
 This checks that expired bytes are removed while unexpired files survive. It
@@ -247,14 +380,14 @@ cleans up its own synthetic object bytes and retains their metadata.
 ## Operations and troubleshooting
 
 ```bash
-docker compose logs --tail=100 api worker scanner
-docker compose restart api worker
-docker compose ps
-docker compose down
+docker compose -f compose.local.yaml logs --tail=100 api worker scanner
+docker compose -f compose.local.yaml restart api worker
+docker compose -f compose.local.yaml ps
+docker compose -f compose.local.yaml down
 ```
 
 `down` stops the stack and preserves named database/storage volumes. Restart
-with `docker compose up -d --wait`. Do not add `--volumes` unless you intend to
+with `docker compose -f compose.local.yaml up -d --wait`. Do not add `--volumes` unless you intend to
 permanently erase all local orders and artwork. No reset is required for tests.
 
 Seven long-running services have Docker health checks; the database and storage
@@ -266,7 +399,7 @@ exposes `/minio/health/ready`.
 Run the redacted local alert summary inside the API network namespace:
 
 ```bash
-docker compose exec -T api python -m local.security_status
+docker compose -f compose.local.yaml exec -T api python3 -m ops.security_status
 ```
 
 Exit status 1 means attention is required. Review blocked artwork, rate limits,
@@ -302,13 +435,13 @@ Offline PDF previews may fall back to the prototype's manual/table-price path.
 ## Dependency lock
 
 The API, worker, and database initializer install every Python dependency from
-`local/requirements.lock` with `--require-hashes`. `local/requirements.txt`
+`infra/requirements.lock` with `--require-hashes`. `infra/requirements.txt`
 remains the human-maintained direct dependency list. After deliberately changing
 a direct pin, regenerate the lock in the same Python 3.12 environment and rebuild:
 
 ```bash
-./local/lock_dependencies.sh
-docker compose up --build -d --wait
+./infra/lock_dependencies.sh
+docker compose -f compose.local.yaml up --build -d --wait
 ```
 
 The generator downloads public package metadata in a disposable container and
@@ -335,7 +468,7 @@ contracts and owners. See `staging/README.md`.
 Keep this stack local. Before connecting real services, confirm the production
 checkout trust workflow, complete `PRODUCTION_INPUTS.md`, and pass the isolated
 staging-readiness gate. Then implement the actual staging composition using the adapter contracts in
-`local/adapters.py`: start with private S3 staging storage, CORS, signed multipart
+`app/adapters.py`: start with private S3 staging storage, CORS, signed multipart
 contract tests and scoped credentials injected outside Git. Add provider sandbox
 adapters one at a time. Mercado Pago requires authenticated, signed, idempotent
 webhook handling before real payment is allowed; Tiny/Olist and WhatsApp need
@@ -359,7 +492,7 @@ Run the source-only gate without credentials:
 python3 deploy/production_preflight.py --source-only
 ```
 
-It must remain blocked while `local/` supports only local fake adapters and does
+It must remain blocked while `app/` supports only local fake adapters and does
 not load Docker secret `*_FILE` settings. Do not bypass or delete this check.
 After approved production implementations and inputs exist, follow
 `PORTAINER.md` and `deploy/PRODUCTION_CHECKLIST.md`; release and deployment

docs/PORTAINER.md

@@ -0,0 +1,184 @@
+# Portainer deployment
+
+DTF follows the same operating model as Graphs and ComporHUB: Gitea builds
+prebuilt images, pushes them to the Gitea registry, and calls one Portainer
+webhook. Portainer owns and redeploys one Docker Swarm stack named `dtf-cloud`.
+
+The deployed stack is the repository's `docker-compose.yml`, which the
+`dtf-cloud` Portainer stack points at. It was once accompanied by `deploy/stack.yaml`, a more hardened definition
+supplying credentials as Docker secrets; that file was removed in favour of one
+definition. See `ROADMAP.md` 2.12 for the reasoning and what remains open.
+
+The stack contains Site, Kanban, API,
+worker, PostgreSQL, ClamAV, and a one-time database initializer. Production uses
+Cloudflare R2, so MinIO is not part of this stack.
+
+## 1. Gitea configuration
+
+The single workflow is `.gitea/workflows/deploy.yml`. Every push and pull request
+runs static validation, the integration suite against a real stack, and a secret
+scan. When all of them pass on a push to `main`, the images are built, scanned
+and published as both `latest` and the full commit SHA. Nothing is deployed:
+production changes when someone pulls and redeploys the stack in Portainer. A
+manual workflow run on `main` does the same and also calls the Portainer
+webhook, if `PORTAINER_WEBHOOK` is configured.
+
+What actually gates a deployment:
+
+| Check | Gates? |
+|---|---|
+| `py_compile` and the unit tests | yes |
+| Integration suite on a live stack (smoke, workflow, security, scanning, retention, runtime) | yes |
+| Browser suites | yes; Chrome runs in the Compose test container |
+| Trivy secret scan (HIGH/CRITICAL) | yes |
+| Source preflight (`deploy/production_preflight.py --source-only`) | advisory unless `ENFORCE_PRODUCTION_PREFLIGHT` is `true`, which blocks publishing |
+| Trivy image vulnerabilities, CRITICAL | yes |
+| Trivy image vulnerabilities, HIGH | no — reported before publication |
+| Configured Portainer webhook | no — called on manual runs when present; otherwise redeploy in Portainer |
+
+The source preflight reports while the payment and messaging adapters are
+fake. From 2026-09-23 it was enforced on every manual release, and since the
+adapters are still fake no release could succeed: production kept running
+older images while `main` moved on. It is now advisory everywhere. Set the
+repository variable `ENFORCE_PRODUCTION_PREFLIGHT` to `true` once the real
+adapters are in place, and a blocked preflight then stops images from being
+published. Before a manual release, run the full configuration
+preflight below against the actual Portainer values; CI checks source only.
+
+CRITICAL image findings block. Both images carry none: the bases are pinned by
+digest, both Dockerfiles upgrade their OS packages, and the web image moved off
+the 1.28 nginx line, which pins `nginx=1.28.3-r1` in `/etc/apk/world` and so
+cannot be patched in place. HIGH findings are reported rather than enforced
+because the remainder have no upstream fix.
+
+`PYTHON_BASE_IMAGE` and `NGINX_BASE_IMAGE` override the digests pinned in the
+Dockerfiles. Update the Dockerfile default in the same change, so the repository
+still records what a build used.
+
+Repository variables:
+
+- `REGISTRY_HOST` — normally `gitea.blyzer.com.br`.
+- `REGISTRY_OWNER` — normally `blyzer`.
+- `PYTHON_BASE_IMAGE`, `NGINX_BASE_IMAGE`, `TRIVY_IMAGE` — approved immutable
+  `@sha256:` image references.
+
+Repository secrets:
+
+- `REGISTRY_USERNAME` and `REGISTRY_TOKEN` — package write credentials.
+- `PORTAINER_WEBHOOK` — webhook generated by the `dtf-cloud` Portainer stack.
+
+The webhook is called only after the release gates above pass.
+`ENFORCE_PRODUCTION_PREFLIGHT` and `TRIVY_IMAGE` are optional repository
+variables; the former affects push checks and the latter defaults to a pinned
+scanner image.
+
+## 2. One-time Portainer resources
+
+Use a Docker Swarm environment. Create a dedicated production PostgreSQL volume
+and set its name as `POSTGRES_VOLUME`. Label its Swarm node
+`dtf_database=true`. Do not reuse the localhost Compose volume.
+
+Create each application credential under **Secrets**. Use versioned names such
+as `dtf_prod_database_url_v1`, then place only those names in the corresponding
+`*_SECRET` stack variables. The stack expects distinct secrets for:
+
+- runtime and administrator database URLs;
+- database administrator and application-role passwords;
+- R2 access key and secret key;
+- operator password;
+- Mercado Pago token and webhook secret;
+- Tiny/Olist token;
+- WhatsApp token.
+
+Credential values must never be entered into Git, `portainer.env`, or Gitea
+workflow variables.
+
+**R2 CORS.** The Site uploads artwork straight from the browser to the bucket
+with presigned `PUT` requests, so the bucket must allow the Site's origin.
+Without it the preflight is refused (403) and the Site shows "NetworkError
+when attempting to fetch resource" at checkout (found 2026-09-28). In the
+Cloudflare dashboard, R2 → the bucket → Settings → CORS policy:
+
+```json
+[
+  {
+    "AllowedOrigins": ["https://<SITE_DOMAIN>", "https://<KANBAN_DOMAIN>"],
+    "AllowedMethods": ["PUT", "GET", "HEAD"],
+    "AllowedHeaders": ["content-type"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+## 3. Create the stack once
+
+In Portainer select **Stacks → Add stack → Git repository**:
+
+- Name: `dtf-cloud`
+- Repository: this Gitea repository
+- Reference: `main`
+- Compose path: `docker-compose.yml` (the repository default, which is what the
+  existing `dtf-cloud` stack uses; it must stay at the root for this reason)
+- Registry: the private `gitea.blyzer.com.br` registry
+- Re-pull image: enabled
+- Automatic update: webhook
+
+Load a completed copy of `deploy/portainer.env.example` as the stack's
+non-secret environment variables. Do not load the example unchanged: `TBD` and
+zero digests are deliberate blockers. Keep `IMAGE_TAG=latest` for normal
+webhook deployments.
+
+Before entering those values in Portainer, validate the completed ignored file:
+
+```bash
+set -a
+. deploy/portainer.env
+set +a
+python3 deploy/production_preflight.py
+```
+
+The public reverse proxy should send the Site hostname to `SITE_PORT` and the
+Kanban hostname to `KANBAN_PORT`. `/api/` and `/portal.html` are served through
+the Site gateway. Preserve the original Host header. Do not expose PostgreSQL,
+API, worker, or ClamAV. Restrict the
+two published web ports at the host firewall so only the reverse proxy can use
+them, and terminate HTTPS at the proxy.
+
+The `db-init` service completing and stopping is expected. The other six
+services must be healthy. A failed `db-init` task or an unhealthy service blocks
+acceptance.
+
+## 4. Manual deployment
+
+Push the reviewed commit to `main` and wait for its validation workflow to pass.
+After validating the actual Portainer configuration with the full preflight in
+section 3, use Gitea Actions to manually run **Build and deploy** on `main` at
+that commit. The workflow repeats validation, tests and scans, then publishes
+these images and calls the webhook:
+
+```text
+gitea.blyzer.com.br/blyzer/dtf-api:latest
+gitea.blyzer.com.br/blyzer/dtf-api:<full-commit-sha>
+gitea.blyzer.com.br/blyzer/dtf-web:latest
+gitea.blyzer.com.br/blyzer/dtf-web:<full-commit-sha>
+```
+
+In Portainer, verify the new image digests, service health, `db-init` result, and
+the public `/health` endpoints. Back up PostgreSQL and R2 before changes that
+affect stored data or retention.
+
+## 5. Rollback
+
+In the Portainer stack variables, change `IMAGE_TAG` from `latest` to the full
+SHA of the last known-good Gitea commit and redeploy. This rolls back Site, API,
+Kanban, and worker code; it does not undo database migrations or restore data.
+After recovery and a corrected release, return `IMAGE_TAG` to `latest`.
+
+## Current blocker
+
+This is the final deployment shape, but it is not authorized for production
+today. Production adapters, Docker-secret file loading, provider sandbox tests,
+current clean base images, approved inputs, and a production restore rehearsal
+are still required. Do not bypass `deploy/production_preflight.py` or the Gitea
+scan gates to make a deployment run.

docs/README.md

@@ -0,0 +1,15 @@
+# Documents
+
+| File | What it is |
+|---|---|
+| `reuniao-2026-09-09-anotacoes.pdf` | Meeting notes that set the business direction: the bottleneck, the 24h goal, the automation and payment decisions. Still the record of what was asked for. |
+| `roadmap-cliente.pdf` | The client-facing plan, as last sent. Generated by `tools/generate_dtf_report.py`; regenerate rather than edit. |
+| `historico/` | The original specification and prototype documents. Background only — they describe a model this system does not implement. |
+
+Current engineering documents live at the repository root: `CONTEXT.md` for how
+the system works, `ROADMAP.md` for what is outstanding, `LOCAL_SETUP.md` to run
+it, `PORTAINER.md` to deploy it, `SECURITY_REPORT.md` and `PRODUCTION_INPUTS.md`
+for the security position and the decisions still owed by the client.
+
+Weekly client reports are deliverables, not repository content. They are produced
+for a specific week and are deliberately not versioned here.

docs/REMEDIATION-2026-09-22.md

@@ -0,0 +1,85 @@
+# DTF remediation register — 2026-09-22
+
+This is the action list for all 37 findings in [the September 21 review](REVIEW-2026-09-21.md). That review contains the evidence and severity for each ID. This register includes the September 22 payment review. It is a plan, not evidence that a finding has been closed in production.
+
+**Current position:** We are in Week 2. The local fixes for foreign-quote order disclosure and approval without a verified amount are implemented and tested, but are not committed or deployed. The first order-correctness slice now covers parts of findings 2, 5–8, and 11; see the progress note below. The remaining work and production verification stay open. Payment webhook work is partial progress on finding 31, not completion of real payments.
+
+**Local progress, 2026-09-22:** Browser and API regressions covered stale editor items, DPI refusal and warning acknowledgement, changed-cart quote actions, oversized width, and finals invalidated by a later correction. A versioned per-file source specification survived quote review into the order snapshot. At that point exact placement coordinates and a generated print file were still missing. None of these changes is a production release.
+
+**Local progress, 2026-09-23:** Specification v2 adds per-copy film coordinates, validates every copy and the quote height, and keeps a downloadable layout manifest in the approved order. The board now pages pending and approved unpaid quotes; a local regression reached all 105 pending and 22 approved fixture quotes. Final print-file generation, completed-order search, and quote cancellation/expiry lifecycle remain open.
+
+**Operational progress, 2026-09-23:** Finding 23's entrypoints are repaired locally. The staging gate passed in a network-disabled image with non-secret fixture data; `ops.security_status` ran in the API image and correctly reported stale local signatures; `ops.backup create-and-verify` restored database counts and 78 clean objects in isolated temporary targets; the production API image built and imported `ops`. This verifies the commands, not production offsite recovery (finding 30) or a fresh scanner (finding 17).
+
+**Quality progress, 2026-09-23:** Findings 9 and 10 are partly repaired: failed image decoding blocks checkout, mixed analyzed/manual sheets stay at table price, and rotated DPI uses the correct pixel axis. PDF measurement now uses the PDF.js page model with effective crop, rotation, UserUnit and page count; invalid or multi-page files block quoting. The same-origin PDF worker and isolated browser checks pass. Unsupported image operators, representative print-file evidence and final printability remain open.
+
+**Upload progress, 2026-09-23:** The API and customer picker now reject files above the effective ClamAV stream limit before transfer, and the session advertises that limit. Unfinished reservations have a one-hour lease and a customer/operator cancel endpoint; owner-scoped cancellation has an integration check. Quota remains reserved until the object is actually purged, so a failed cleanup cannot admit unaccounted storage. PDF rendering now destroys the parser job when its timeout fires, covered by a browser check. This closes the misleading upload-then-quarantine path locally but does not satisfy the agreed large-file capability in finding 3. A tested large-file scan/release design, stronger anonymous admission controls (finding 16), and remaining browser resource bounds (finding 12) are still required.
+
+## Gates
+
+| Gate | Meaning |
+|---|---|
+| **W2** | Fix during Week 2 before calling the corresponding client workflow complete. These defects can be worked on while provider contracts are clarified. |
+| **Upload** | Resolve before inviting the public to upload customer artwork. |
+| **Paid** | Resolve before enabling live checkout or accepting a real paid order. |
+| **Release** | Resolve before declaring the deployed production system ready. |
+| **Incremental** | Improve alongside feature work; it does not justify a standalone rewrite. |
+
+The gates are cumulative: a live release must pass W2, Upload, Paid, and Release checks. Decisions labelled **business** require an agreed product rule; engineering can build and test the surrounding flow in parallel. Where a deployment risk is conditional, verify the actual topology and document the result before closing it.
+
+## Complete finding-to-action map
+
+| Review ID | Gate | Required action and closure evidence |
+|---|---|---|
+| 1 | Paid | Implement real payment, freight, ERP, and notification adapters with sandbox acceptance and reconciliation; remove fake adapters from the live path. |
+| 2 | W2 | Store a versioned per-file production specification and approved layout on quote and order; prove the factory can reproduce the purchased job. |
+| 3 | Upload; business | Agree the advertised maximum and implement a scan/release path that actually supports it; reject unsupported sizes before transfer. |
+| 4 | W2 | Give quotes an explicit lifecycle and paginated/searchable operator view; verify the 101st actionable quote remains visible. |
+| 5 | W2 | Invalidate or revision-bind finals when a new correction arrives; test a correction submitted after a final was uploaded. |
+| 6 | W2 | Make quality eligibility a checkout gate and store any required acknowledgement against the artwork revision. |
+| 7 | W2 | Clear the current cart item immediately when artwork is removed or becomes invalid; test the submitted payload. |
+| 8 | W2 | Bind checkout to an immutable quoted cart snapshot; require re-quote after any material edit, including same-price edits. |
+| 9 | W2 | Measure PDF pages through the parser's page model; handle every supported page or reject multi-page/unsupported geometry explicitly. |
+| 10 | W2 | Require quality evidence per billable source; make undecodable/unknown sources explicit and correct rotation-sensitive DPI calculations. |
+| 11 | W2 | Validate physical dimensions before packing; never silently scale a requested print size. |
+| 12 | Upload | Bound browser decoding, copy count, PDF work, and preview size; cancel obsolete work and test representative large inputs. |
+| 13 | Paid | Capture and validate a full delivery-address snapshot, then connect it to freight quote and order fulfilment. |
+| 14 | Paid; business | Set written auto-approval rules and manual-exception criteria; prove eligible orders can complete after hours without an operator. |
+| 15 | W2; business | Define accepted print output, generate it from the approved versioned layout, and compare produced geometry/metres with the quote. If scope changes, update the client commitment and site claims explicitly. |
+| 16 | Upload | Limit anonymous reservation capacity and lifetime; add cancellation and cleanup, then test quota-exhaustion behavior. |
+| 17 | Upload | Update ClamAV signatures on a controlled schedule; surface signature age and fail the intake gate when stale. |
+| 18 | Release | Trust only the actual proxy hop, restrict origin access, and test real client IP/rate limits through the deployed Swarm topology. |
+| 19 | Release | Wire file-backed secrets into the active stack; give each service only necessary credentials and remove unused bootstrap secrets. |
+| 20 | Release | Recheck operator `active` atomically when issuing and using sessions; test disable-versus-login concurrency and document password-change session policy. |
+| 21 | Paid | Provide email verification and customer recovery/guest continuity, and make checkout's account-creation claim match reality. |
+| 22 | Release; business | Agree retention/export/deletion rules for profiles, quotes, orders, payloads, artwork, and backups; implement and verify them. |
+| 23 | W2 | Repair staging, backup, and security commands after the directory move; smoke-test them in the images and Compose files actually shipped. |
+| 24 | Release | Set and test PostgreSQL node placement/persistence for the intended Swarm size, plus recovery after host failure. |
+| 25 | Release | Scan before promotion, publish immutable paired API/web image identities, and deploy exactly the scanned release. |
+| 26 | Release | Make preflight enforce the active stack contract and provider behavior; verify Portainer/deployment convergence after promotion. |
+| 27 | Release | Run browser tests in a network where signed storage URLs work; fail CI when Chrome or the test endpoint is unavailable. |
+| 28 | Release | Isolate each CI Compose project, ports, networks, and volumes; serialize release promotion and test overlapping runs. |
+| 29 | Release | Separate liveness/readiness, monitor provider backlog, cleanup, scanner freshness and backup age; test alert routing and rollback acceptance. |
+| 30 | Release; business | Set recovery objectives, make consistent encrypted offsite backups, and rehearse restore of database plus required live artwork. |
+| 31 | Paid | Finish durable payment intent, idempotent webhook handling, status/refund rules, reconciliation, and ordered outbox/dead-letter recovery; test provider-success/database-failure cases. Signed event work is only partial progress. |
+| 32 | Upload | Bound upload concurrency, decouple upload from scan waiting, measure queue latency, and distinguish transient scan errors from rejected content. |
+| 33 | Release | Introduce ordered schema migrations and core constraints/relationships; test both clean install and upgrade from the existing schema. |
+| 34 | Incremental | Replace shared mutable browser cart state as part of IDs 2/7/8; then extract reusable business operations from routes and add bounded DB connection management where load measurements warrant it. |
+| 35 | Release | Add representative artwork, real PDF, failure/retry, migration, operational-command, and exact-release acceptance tests. |
+| 36 | W2 | Correct executable setup/Portainer/security instructions and PDF generator paths; check generated output against current scope. |
+| 37 | Release | Inventory and scan every deployed image and vendored asset, pin release dependencies, and set a controlled refresh process. Do not describe the existing PDF.js advisory as a proven exploit. |
+
+## Execution order
+
+1. **Correct the customer/order model now:** IDs 2, 4–11, 23, and 36. Keep an immutable quote revision through payment, production output, and correction approval. Close each defect with a focused regression test and a real artwork example where geometry matters.
+2. **Set the missing product rules while coding continues:** IDs 3, 14, 15, 22, and 30. Obtain representative files, accepted print format, auto-approval thresholds, retention rules, recovery objectives, and provider sandbox access. Do not collect credentials in this document.
+3. **Make public intake safe:** IDs 3, 12, 16, 17, and 32. Test the declared upload size end to end, including scan, release, quota, browser memory, and timeout behavior.
+4. **Complete live commerce:** IDs 1, 13, 14, 15, 21, and 31. Build freight/address, payment/reconciliation, ERP, and notification flows; test duplicates, outages, refunds, and human exceptions in provider sandboxes.
+5. **Prove the deployed system:** IDs 18–20, 22, 24–30, 33, 35, and 37. Run the exact images and stack, exercise migration, backup/restore, monitoring, secrets, CI and release rollback. Improve ID 34 as the affected areas are changed.
+
+## Who supplies what
+
+- **Engineering:** implement and test the code, schema, operational commands, CI gates, provider adapters, and recovery runbooks; gather evidence for each closure. This work can start with the order/cart defects without waiting for provider access.
+- **Business/client:** approve unattended-pricing exceptions, final print-file format and samples, the real maximum file size, shipping services and policy, privacy retention, and recovery objectives. The detailed worksheet is [production inputs](PRODUCTION_INPUTS.md).
+- **Provider/operations owners:** supply sandbox accounts and configuration through the approved secret channel, plus the real deployment topology, backup destination, alert recipients, and release/rollback ownership. No credentials belong in this register or the repository.
+
+**Closure rule:** A checkbox or passing mocked flow is insufficient. For each ID, keep the original evidence, record the implemented change and test, then verify in the environment that carries the risk. The [working roadmap](ROADMAP.md) tracks Week 2 delivery status; this register tracks the full defect disposition.

docs/REVIEW-2026-09-21.md

@@ -0,0 +1,144 @@
+**DTF project review — September 21, 2026**
+
+Reviewed revision: `7386469`. Commit window: September 21, 00:00–24:00, America/Sao_Paulo; 26 commits. This is a review, not an implementation change or production approval.
+
+**Assessment**
+
+The project has a useful local workflow and several sound controls, but it is not yet the automated ordering and production system described in the meeting. The largest risks are incomplete commercial integrations, loss of production instructions between the editor and API, incorrect cart/quote behavior, an upload limit that the scanner cannot support, and operational controls that are documented more strongly than they are implemented.
+
+Today's restructuring improved navigation through the repository, but introduced broken operational entrypoints. Today's board limit also introduced a starvation bug. Passing the existing tests does not establish that the requested artwork can be reproduced correctly or that the production deployment is recoverable.
+
+**Business baseline and scope**
+
+I read [the September 9 meeting notes](/home/farelos/compor/dtf-sistema/docs/reuniao-2026-09-09-anotacoes.pdf) first, then compared the implementation with [the later project context](/home/farelos/compor/dtf-sistema/docs/CONTEXT.md:20) and [the client roadmap](/home/farelos/compor/dtf-sistema/docs/roadmap-cliente.pdf).
+
+The meeting's core outcome is unattended order intake and payment, fewer designer handoffs, reliable large-file handling, a traceable queue, and separation of ready artwork from artwork needing assistance. Later decisions explicitly defer automatic print preflight, factory agents, FlexiPRINT integration, machine dashboards, and advanced reports. Their absence is not reported here as an accidental regression. The approved site pricing also supersedes the meeting's simplified 20% discount description; changing those prices would require a separate business decision.
+
+The active layout is `web/` for browser code; `app/api/` for HTTP routes; `app/core/` for shared foundations; the remaining `app/` modules for storage, artwork, scanning, initialization, and background work; `infra/` for local images and configuration; `deploy/`, the root Swarm composition, and `.gitea/` for delivery; `ops/` for operational commands; and `tests/` for checks. Historical documents describe earlier models and should not define current acceptance criteria.
+
+**Evidence and limits**
+
+- Inspected the active first-party application, browser logic, schema, deployment definitions, operational scripts, tests, project documents, and today's commit history and relevant diffs. Vendored PDF.js was checked as a third-party dependency, not subjected to a line-by-line audit of its minified implementation. Historical material was used as background.
+- Ran the current fast suite: 29 tests executed, 28 passed, one skipped because it still looks for the deleted `deploy/stack.yaml`.
+- Parsed all first-party Python files and checked the syntax of all first-party browser JavaScript files successfully.
+- Ran the isolated artwork browser suite with additional review probes against synthetic files. The existing checks passed; the probes reproduced findings 6, 7, and 10 below.
+- Ran the production source preflight: it correctly reported the fake payment and messaging adapters as blockers. CI does not enforce that result by default.
+- Used read-only checks in the running local API container: `ops` is absent, `app.staging_readiness` is absent, a 128 MiB + 1 byte scan is rejected, and ClamAV reports `1.5.4/28122/Sun Sep 13 06:26:25 2026`.
+- Executed the actual `submit_files` function body against an in-memory connection double to confirm which file kinds it invalidates. Also reproduced the board query's 101st-quote omission against synthetic SQL data. These are targeted logic checks, not production database tests.
+- Did not change application code, production services, credentials, orders, or stored artwork. Did not rerun the full container integration suite, perform a current Trivy audit, test provider sandboxes, or inspect production firewall/Portainer settings. Deployment-dependent risks below are explicitly qualified.
+
+P1 means a delivery blocker or a material correctness, security, or recovery risk that should be resolved before accepting real customer work. P2 means an important correctness, reliability, or maintenance issue. A finding labelled a gap or design risk is not presented as an observed production incident.
+
+**Commercial flow and artwork correctness**
+
+1. **P1 — Production cannot complete an order. Confirmed delivery gap.** `dev-paid` returns 503 outside local mode, while runtime configuration requires fake payment, freight, Tiny, and WhatsApp adapters. There is no real payment creation/webhook/reconciliation flow, carrier quote, ERP order, or notification delivery. R2 connectivity and a healthy public page therefore do not establish a usable sales system. Complete the provider contracts and implement their sandbox-tested flows before treating the deployment as live commerce. Evidence: [orders.py:17](/home/farelos/compor/dtf-sistema/app/api/orders.py:17), [adapters.py:9](/home/farelos/compor/dtf-sistema/app/adapters.py:9), [runtime.py:24](/home/farelos/compor/dtf-sistema/app/runtime.py:24).
+
+2. **P1 — The customer's production instructions disappear at checkout. Confirmed defect.** The editor records width, copies, rotation, mirroring, and ready-sheet repetitions, but `itemAtual` retains only totals and original Files. The API receives only mode, aggregate metres, grade, and upload IDs. It cannot tell the factory whether one artwork should be printed six times at 20 cm or with a different combination producing the same length. Neither the saved cart nor the order contains the full reproducible layout. Persist a versioned per-file production specification and the approved layout/revision. Evidence: [site-cart.js:65](/home/farelos/compor/dtf-sistema/web/site-cart.js:65), [checkout.js:65](/home/farelos/compor/dtf-sistema/web/checkout.js:65), [models.py:59](/home/farelos/compor/dtf-sistema/app/core/models.py:59).
+
+3. **P1 — The 5 GiB upload path cannot deliver files above 128 MiB. Reproduced.** The browser/API accept 5 GiB, but `ClamAV.scan` hard-caps acceptance at `min(128 MiB, SCAN_MAX_BYTES)`, and ClamAV has matching limits. Raising the environment variable alone cannot fix it. Oversized files are rejected, blocked from quote/download/production, and scheduled for deletion; the customer may upload gigabytes before discovering this. Expose the usable limit before transfer and implement a deliberate large-file scan/release design. Evidence: [scanning.py:32](/home/farelos/compor/dtf-sistema/app/scanning.py:32), [clamd.conf:8](/home/farelos/compor/dtf-sistema/infra/clamd.conf:8), [docker-compose.yml:31](/home/farelos/compor/dtf-sistema/docker-compose.yml:31).
+
+4. **P1 — The oldest 100 unpaid quotes can permanently hide new work. Introduced today in `543a9a9`.** The board selects the oldest unpaid quotes with a limit, including approved, expired, and abandoned quotes. There is no pagination, archive/cancel action, or pending-quote expiry that frees this window. Approved quotes are immutable, and expired ones cannot be paid, so old entries can remain indefinitely. Quote 101 is invisible even while needing review. Finished-order trimming also has no operator search/archive view for older completed work. Paginate/search history and give quotes an explicit lifecycle; do not silently cap actionable work. Evidence: [operator.py:59](/home/farelos/compor/dtf-sistema/app/api/operator.py:59), [kanban.js:24](/home/farelos/compor/dtf-sistema/web/kanban.js:24).
+
+5. **P1 — A new correction can leave an obsolete final approved. Targeted logic reproduction.** An operator may submit finals while the order is in `cor`. The customer may then submit another correction using the latest version. `submit_files` deactivates only files of the incoming kind, so the earlier final remains active. Moving `cor → tra → fil` checks final coverage, not whether those finals were approved after the latest correction, and can accept the stale set. Invalidate finals on every accepted customer correction, or bind final approval to the specific correction revision. Evidence: [artwork.py:15](/home/farelos/compor/dtf-sistema/app/artwork.py:15), [artwork.py:40](/home/farelos/compor/dtf-sistema/app/artwork.py:40), [operator.py:118](/home/farelos/compor/dtf-sistema/app/api/operator.py:118).
+
+6. **P2 — The stated DPI rejection and customer acknowledgement do not gate checkout. Browser-reproduced.** With 25.4-DPI artwork, the quality button was disabled but the payment button remained enabled and a cart item existed. `pintaEntrega` checks only customer data and freight; `dtfCheckout` does not check the resolution gate. The warning acknowledgement is also never recorded in the order. Manual operator review currently provides a later checkpoint, but the UI's claim that these files cannot proceed is false. Use one eligibility state for cart submission and retain any required acknowledgement against the artwork revision. Evidence: [site-quality.js:158](/home/farelos/compor/dtf-sistema/web/site-quality.js:158), [site-flow.js:90](/home/farelos/compor/dtf-sistema/web/site-flow.js:90), [checkout.js:49](/home/farelos/compor/dtf-sistema/web/checkout.js:49).
+
+7. **P1 — Removing artwork can leave it in the submitted cart. Browser-reproduced.** After deleting the only artwork, `artes.length` became zero while `itemAtual.localFiles` still contained the removed file and checkout stayed enabled. An incomplete evaluation hides panels without clearing `itemAtual`; other invalid edits can similarly leave old totals and Files alive. Clear or invalidate the current cart item immediately whenever its underlying artwork becomes incomplete. Evidence: [site-cart.js:7](/home/farelos/compor/dtf-sistema/web/site-cart.js:7), [site-quality.js:79](/home/farelos/compor/dtf-sistema/web/site-quality.js:79), [site-pdf.js:348](/home/farelos/compor/dtf-sistema/web/site-pdf.js:348).
+
+8. **P1 — Editing the cart after requesting a quote can still purchase the old quote. Confirmed control-flow defect.** Once `draftId` exists, checkout returns early through `refresh()` and never compares the current cart with the stored quote. The editor remains usable. The confirmation displays a server total but no full immutable item comparison, so quantity/artwork edits can be silently ignored, especially when the one-metre minimum keeps the total unchanged. Bind the UI to the quoted snapshot and explicitly replace the quote on edits. Evidence: [checkout.js:51](/home/farelos/compor/dtf-sistema/web/checkout.js:51), [checkout.js:89](/home/farelos/compor/dtf-sistema/web/checkout.js:89).
+
+9. **P2 — PDF quantity and geometry are not reliably measured. Confirmed algorithm limitation.** Measurement searches the first/last 4 MiB for the first textual `MediaBox` and an unrelated first `UserUnit`; rendering/quality checks only page 1. There is no multi-page rejection or sum across pages. A multi-page print file can therefore be quoted as one page. Compressed/inherited page dictionaries, rotation, and page-specific units are not handled by this textual search. Use the PDF parser's page model, and either support every page or explicitly reject unsupported documents. Evidence: [site-pdf.js:101](/home/farelos/compor/dtf-sistema/web/site-pdf.js:101), [site-pdf.js:132](/home/farelos/compor/dtf-sistema/web/site-pdf.js:132).
+
+10. **P2 — Quality grades can be based on missing or incorrect evidence. Partly browser-reproduced.** A CDR with no analysis plus an analysed PNG received grade 50 and R$18.70/m for the entire item rather than the CDR's stated table rate of R$19.90/m. `filter(Boolean)` removes unanalysed files from grading while their metres remain billable. For loose artwork, failed image decoding leaves a pixel estimate derived from compressed file size. Rotation retains the original width for DPI even when the physical width now corresponds to image height. The PDF image walker also treats no recognized images as vector artwork, although unsupported image operators or failed object lookup can yield the same result. Track quality per source and fail explicitly when measurement is unknown. Evidence: [site-quality.js:19](/home/farelos/compor/dtf-sistema/web/site-quality.js:19), [site-config.js:107](/home/farelos/compor/dtf-sistema/web/site-config.js:107), [site-upload.js:96](/home/farelos/compor/dtf-sistema/web/site-upload.js:96), [site-pdf.js:46](/home/farelos/compor/dtf-sistema/web/site-pdf.js:46).
+
+11. **P2 — Oversized artwork is silently shrunk by the packer. Confirmed code path.** Width inputs advertise a maximum, but their JavaScript handlers accept larger values without validating form constraints. When no orientation fits, `encaixar` scales the artwork down to film width. The requested dimension and actual preview geometry then disagree, without an explicit approval to resize. Reject impossible dimensions or offer a visible, accepted resize. Evidence: [site-pdf.js:349](/home/farelos/compor/dtf-sistema/web/site-pdf.js:349), [site-packing.js:175](/home/farelos/compor/dtf-sistema/web/site-packing.js:175).
+
+12. **P2 — The browser processing path is not bounded for large artwork. Confirmed design risk.** Images are loaded as full data URLs and decoded repeatedly; PDFs use full-file `arrayBuffer`; copy count has no effective upper bound before `Array.from`; preview canvas height grows with the whole layout. PDF timeouts race a promise without cancelling parsing/rendering or destroying the document. Large files or copy counts can exhaust memory or freeze the main thread before resumable upload helps. Bound work, avoid repeated full decodes, tile previews, cancel obsolete parsing, and provide a path that does not require browser rasterization of huge files. Evidence: [site-packing.js:6](/home/farelos/compor/dtf-sistema/web/site-packing.js:6), [site-packing.js:204](/home/farelos/compor/dtf-sistema/web/site-packing.js:204), [site-pdf.js:97](/home/farelos/compor/dtf-sistema/web/site-pdf.js:97).
+
+13. **P1 — Home-delivery orders cannot capture a deliverable address. Confirmed MVP gap.** Customer data contains CNPJ, phone, and email; freight contains only service and CEP. There is no recipient name, street, number, complement, city/state, or validated delivery snapshot. A CEP can support an estimate, but it does not identify the destination needed to fulfil the order. Add the delivery contract together with freight integration; automated label purchase can remain out of scope. Evidence: [models.py:10](/home/farelos/compor/dtf-sistema/app/core/models.py:10), [models.py:43](/home/farelos/compor/dtf-sistema/app/core/models.py:43), [index.html:1209](/home/farelos/compor/dtf-sistema/web/index.html:1209).
+
+14. **P1 — Unattended sales still depend on a human commercial review. Product decision outstanding.** Server pricing safely recalculates prices, but metres and grade become trusted only when an operator approves every quote. This intentionally protects the local prototype; it does not solve the meeting's after-hours bottleneck. Decide which orders can be accepted automatically, what evidence supports their price, and what exceptions require a person. Automatic print preflight being deferred does not itself settle the pricing-authority question. Evidence: [orders.py:28](/home/farelos/compor/dtf-sistema/app/api/orders.py:28), [operator.py:78](/home/farelos/compor/dtf-sistema/app/api/operator.py:78), [CONTEXT.md:262](/home/farelos/compor/dtf-sistema/docs/CONTEXT.md:262).
+
+15. **P1 — Final print-file generation remains missing from the promised delivery. Confirmed gap.** The server stores originals and manually uploaded finals; it never generates the layout shown in the browser, applies repetitions, splits output, or adds the promised order identification. Consequently the factory must reconstruct the job, and billed metres have no machine-verifiable connection to produced metres. The client roadmap includes final-file generation in week 2 even while deferring automatic preflight. Implement a reproducible output path and print acceptance checks, or explicitly renegotiate that deliverable and the site's promises. Evidence: [api/artwork.py:45](/home/farelos/compor/dtf-sistema/app/api/artwork.py:45), [site-packing.js:342](/home/farelos/compor/dtf-sistema/web/site-packing.js:342), [ROADMAP.md:171](/home/farelos/compor/dtf-sistema/docs/ROADMAP.md:171).
+
+**Security and access**
+
+16. **P1 — Anonymous reservations can exhaust the entire storage quota without uploading bytes. Confirmed arithmetic/control-flow risk; no attack run.** Quota accounting immediately reserves the declared file size. With current defaults, five guest identities can reserve two 5 GiB uploads each and occupy the global 50 GiB allowance. Guest sessions and per-owner limits do not prevent this; all reservations remain until incomplete-upload cleanup after one day, and no customer abort endpoint releases them. Add global admission safeguards, short idle reservation leases, explicit cancellation, and a suitable identity/abuse policy. Evidence: [uploads.py:21](/home/farelos/compor/dtf-sistema/app/api/uploads.py:21), [health.py:26](/home/farelos/compor/dtf-sistema/app/api/health.py:26), [worker.py:21](/home/farelos/compor/dtf-sistema/app/worker.py:21).
+
+17. **P1 — Malware signatures are already stale in the inspected local runtime. Reproduced operational gap.** The scanner runs `clamd` directly from a pinned image on an internal network, with no updater or scheduled replacement. It reports September 13 signatures on September 21, exceeding the repository's own seven-day threshold. Worker health only requires a live thread and PING. A running scanner is therefore reported healthy despite stale detection data. Establish controlled signature updates and make signature freshness visible to operations. [ClamAV's signature-management documentation](https://docs.clamav.net/manual/Usage/SignatureManagement.html) describes the update mechanism. Evidence: [docker-compose.yml:79](/home/farelos/compor/dtf-sistema/docker-compose.yml:79), [worker.py:60](/home/farelos/compor/dtf-sistema/app/worker.py:60), [security_status.py:7](/home/farelos/compor/dtf-sistema/ops/security_status.py:7).
+
+18. **P1 — The reverse-proxy trust boundary is broader than the claimed protection. Deployment-dependent security risk introduced in `3b92813`.** Nginx accepts forwarded client addresses from every RFC1918 network, rather than the actual trusted proxy. Any reachable private peer can supply that header. The web ports use Swarm ingress, so the assumption that a direct internet request necessarily arrives with a public socket peer also needs topology testing. If untrusted traffic arrives through a trusted internal peer, it can spoof audit addresses and rate-limit buckets. Restrict trusted proxy hops and firewall the origin ports; verify through the actual Swarm/reverse-proxy chain. I did not verify production exposure or demonstrate a public exploit. Evidence: [nginx.conf.template:17](/home/farelos/compor/dtf-sistema/deploy/nginx.conf.template:17), [docker-compose.yml:143](/home/farelos/compor/dtf-sistema/docker-compose.yml:143). References: [Nginx real-IP trust](https://nginx.org/en/docs/http/ngx_http_realip_module.html), [Docker ingress routing](https://docs.docker.com/engine/swarm/ingress/).
+
+19. **P2 — Production credentials remain plain service environment values. Confirmed configuration risk.** The actual stack supplies DB, R2, and operator secrets directly, despite the new secret-file loader and documentation describing external secrets. API and worker both receive the bootstrap operator password even though runtime authentication now uses the database. Removing the unused second stack reduced drift, but did not remove this exposure from the active one. Use the implemented file loader in the real stack and restrict each service to the secrets it needs. This is metadata/operational exposure, not evidence of a public credential leak. Evidence: [docker-compose.yml:3](/home/farelos/compor/dtf-sistema/docker-compose.yml:3), [core/secrets.py:1](/home/farelos/compor/dtf-sistema/app/core/secrets.py:1).
+
+20. **P2 — Operator disable can race with login. Introduced with accounts in `a874033`; static concurrency finding.** Login reads the active account, performs expensive password verification, then inserts a session in a separate transaction without rechecking `active`. Disabling between those steps deletes existing sessions, but the in-flight login can create a new one afterwards. The request guard checks only session existence/expiry, so that session can authorize a disabled account for eight hours. Recheck active status atomically when issuing sessions and in authorization. Password changes also intentionally retain current sessions; document or revise that recovery policy. Evidence: [operator.py:23](/home/farelos/compor/dtf-sistema/app/api/operator.py:23), [auth.py:102](/home/farelos/compor/dtf-sistema/app/core/auth.py:102), [operators.py:80](/home/farelos/compor/dtf-sistema/app/operators.py:80).
+
+21. **P2 — Account recovery and guest continuity are incomplete. Confirmed gap.** There is no email verification, password recovery/change flow for customers, or durable guest recovery mechanism. A guest who loses the cookie or passes its seven-day expiry cannot prove ownership merely by knowing the order/CNPJ, correctly, but also has no supported way to regain access. The site incorrectly promises account creation at payment; the order route creates no account. Complete the identity/recovery journey without weakening the existing ownership checks. Evidence: [customer.py:25](/home/farelos/compor/dtf-sistema/app/api/customer.py:25), [auth.py:58](/home/farelos/compor/dtf-sistema/app/core/auth.py:58), [index.html:1190](/home/farelos/compor/dtf-sistema/web/index.html:1190).
+
+22. **P2 — Personal-data lifecycle is undefined beyond artwork cleanup. Confirmed governance gap, not a legal conclusion.** Profiles, quote drafts, immutable order snapshots, and integration payloads duplicate contact data without an implemented deletion/anonymization/export policy. Artwork expiry does not cover those records or retained backups. The site does link an external privacy/terms page, so claiming there is no privacy link would be inaccurate; this review did not establish whether that notice covers this processing. Define retention and access requirements for each data class, then implement them consistently. Evidence: [schema.sql:9](/home/farelos/compor/dtf-sistema/app/schema.sql:9), [schema.sql:28](/home/farelos/compor/dtf-sistema/app/schema.sql:28), [index.html:1358](/home/farelos/compor/dtf-sistema/web/index.html:1358).
+
+**Operations and release engineering**
+
+23. **P1 — Today's directory move broke staging, backup, and security operations. Reproduced packaging failure in `b329f76`.** Staging runs `app.staging_readiness`, but the module now lives under `ops`. Neither API Dockerfile copies `ops`. Backup still calls `local.storage_backup` inside the API container and selects plain `docker compose`, which now means the production-oriented root file rather than `compose.local.yaml`. Documentation calls nonexistent `app.backup` and `app.security_status`. These are broken operational commands, not merely stale comments. Package a deliberate operational runtime, update every executable entrypoint, and smoke-test the shipped commands. Evidence: [compose.staging.yaml:11](/home/farelos/compor/dtf-sistema/compose.staging.yaml:11), [infra/Dockerfile:10](/home/farelos/compor/dtf-sistema/infra/Dockerfile:10), [backup.py:13](/home/farelos/compor/dtf-sistema/ops/backup.py:13), [backup.py:41](/home/farelos/compor/dtf-sistema/ops/backup.py:41).
+
+24. **P1 — PostgreSQL has no Swarm data-placement contract. Conditional recovery risk.** The active stack uses a normal local named volume with no node constraint. On a multi-node Swarm, rescheduling can attach a same-named empty local volume on another node rather than the existing database. The documented `POSTGRES_VOLUME` and `dtf_database=true` placement contract is not implemented. A single-node VPS is also a single failure domain. Specify and test persistence, placement, and recovery instead of relying on the volume name alone. Evidence: [docker-compose.yml:40](/home/farelos/compor/dtf-sistema/docker-compose.yml:40), [docker-compose.yml:180](/home/farelos/compor/dtf-sistema/docker-compose.yml:180), [PORTAINER.md:73](/home/farelos/compor/dtf-sistema/docs/PORTAINER.md:73).
+
+25. **P1 — `latest` is published before the release scan, and deployment is not tied to the scanned pair. Confirmed pipeline design defect.** API and web `latest` tags are pushed independently before vulnerability checks. A failed scan leaves the mutable deployment tags pointing at rejected images; a manual redeploy or another run can consume them. Concurrent runs can also overwrite each other's API/web tags, while the webhook carries no exact release identity. Build and scan first, then promote one immutable API/web release and deploy that release. Evidence: [deploy.yml:194](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:194), [deploy.yml:217](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:217), [deploy.yml:243](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:243).
+
+26. **P1 — The production gate does not validate the deployed contract. Confirmed gap.** CI runs only `--source-only`, treats failure as advisory by default, and never validates the actual Portainer metadata or observes deployment convergence. Full config validation expects names/secrets/volumes from the removed stack, while the active stack uses different variables. Positive secret-loader checks also derive their cases from that deleted file, leaving the set empty; the associated unit test skips. The two remaining provider checks match literal source strings, not working provider behavior. Retarget validation to the actual deployment, retain positive loader tests independently of a file's existence, and add release acceptance against real capabilities. Evidence: [deploy.yml:155](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:155), [production_preflight.py:17](/home/farelos/compor/dtf-sistema/deploy/production_preflight.py:17), [production_preflight.py:81](/home/farelos/compor/dtf-sistema/deploy/production_preflight.py:81), [test_secrets.py:75](/home/farelos/compor/dtf-sistema/tests/test_secrets.py:75).
+
+27. **P1 — Browser tests can be skipped on a green release, and their upload endpoint is incompatible with the runner topology. Confirmed CI gap.** Missing Chrome or inaccessible host loopback returns success. Meanwhile CI signs browser storage URLs for `http://storage:9000`, a Compose-only hostname; installing Chrome or making host ports reachable does not by itself give that browser access to storage. These are the only broad tests of the artwork/cart journey. Run Chrome and the tests in a compatible network, then make omission fail the release. Evidence: [deploy.yml:45](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:45), [deploy.yml:90](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:90), [browser_test.mjs:44](/home/farelos/compor/dtf-sistema/tests/browser_test.mjs:44).
+
+28. **P2 — CI runs share fixed ports and lack enforced project isolation. Conditional concurrency risk.** The integration job uses the same five host ports, relies on the default Compose project name, and ends with `down -v`. Overlapping runs on the shared Docker daemon can collide; if their project names coincide, they can also operate on each other's containers and volumes. Selecting currently unused ports fixed one collision but not concurrency. Allocate a unique project/network per run, avoid unnecessary published ports, and serialize release promotion. Evidence: [deploy.yml:27](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:27), [deploy.yml:121](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:121).
+
+29. **P1 — Health checks do not establish operational readiness or successful delivery. Confirmed monitoring gap.** Public `/health` always returns 200 from Nginx. API health checks DB/storage, while worker health can remain green during repeated provider failures, stale signatures, or failed cleanup. `last_tick` advances even after a delivery retry is scheduled. Cleanup handles a batch in one transaction; one consistently failing object can roll back progress and repeatedly block later expired objects. There is no implemented external alert routing or post-webhook application verification, and the stack lacks explicit rollback/update policies described in the docs. Separate liveness from readiness and alert on backlog age, cleanup progress, signatures, backup age, and deployment acceptance. Evidence: [nginx.conf.template:32](/home/farelos/compor/dtf-sistema/deploy/nginx.conf.template:32), [worker.py:21](/home/farelos/compor/dtf-sistema/app/worker.py:21), [worker.py:35](/home/farelos/compor/dtf-sistema/app/worker.py:35), [deploy.yml:243](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:243).
+
+30. **P1 — Recoverability is not implemented as a production service. Confirmed gap beyond the broken commands.** There is no scheduled offsite encrypted backup, production restoration procedure, or tested recovery objective. The local backup dumps PostgreSQL and selects object bytes afterwards, without a shared snapshot or enforced pause; concurrent uploads/retention can produce mismatched state. Its restore check validates database counts and archived bytes separately, not that every required live order file is restorable. Define a consistent recovery boundary, required data classes, backup retention, and a rehearsed restoration procedure. Evidence: [backup.py:27](/home/farelos/compor/dtf-sistema/ops/backup.py:27), [storage_backup.py:46](/home/farelos/compor/dtf-sistema/ops/storage_backup.py:46), [LOCAL_SETUP.md:216](/home/farelos/compor/dtf-sistema/docs/LOCAL_SETUP.md:216).
+
+31. **P1 — Real payment and integration failure semantics are not yet represented. Design gap before enabling providers.** The mock payment is called before the order transaction commits. A future provider success followed by a DB failure needs a durable payment intent, provider idempotency, and reconciliation. The outbox has a useful unique event key, but retries can let a later event for the same order overtake an earlier failed event; permanent failures retry forever without a dead-letter/operator resolution path. Provider-side success followed by a crash can also repeat delivery. There are no real pending/failed/refunded/cancelled payment states or corresponding production rules. Implement those contracts before substituting real network calls for fakes. Evidence: [orders.py:34](/home/farelos/compor/dtf-sistema/app/api/orders.py:34), [worker.py:35](/home/farelos/compor/dtf-sistema/app/worker.py:35), [runtime.py:43](/home/farelos/compor/dtf-sistema/app/runtime.py:43).
+
+32. **P2 — Upload/scanning throughput and timeout behavior are poorly matched. Confirmed design limitation.** Files and their 8 MiB parts are uploaded sequentially, with one API presign round-trip per part; the browser then waits for scanning before uploading the next file. One scan thread handles all work, holds a DB transaction during the remote read/scan, and the browser gives up after roughly 150 polls. Scanner errors shorten retention to three days even if a later retry succeeds; success does not restore that deadline. Add bounded transfer concurrency, separate upload completion from scan waiting, measure queue latency, and distinguish transient scanner faults from rejected content. Evidence: [upload.js:9](/home/farelos/compor/dtf-sistema/web/upload.js:9), [checkout.js:60](/home/farelos/compor/dtf-sistema/web/checkout.js:60), [scanning.py:55](/home/farelos/compor/dtf-sistema/app/scanning.py:55).
+
+**Architecture, verification, and maintenance**
+
+33. **P2 — Database integrity and schema evolution rely too heavily on application convention. Confirmed design weakness.** Startup replays one growing SQL script without a general ordered migration/version contract. Orders reference artwork inside JSON instead of relational order-item/upload references; states and scan states lack checks, and upload expiry remains nullable. The database cannot enforce several invariants that the application assumes. Today's index-before-table regression, fixed in `86b8199`, demonstrates why clean initialization and upgrade paths both need testing. Use versioned migrations, explicit core relationships/constraints, and verify supported upgrades as well as empty installations. Evidence: [bootstrap.py:29](/home/farelos/compor/dtf-sistema/app/bootstrap.py:29), [schema.sql:14](/home/farelos/compor/dtf-sistema/app/schema.sql:14), [schema.sql:71](/home/farelos/compor/dtf-sistema/app/schema.sql:71).
+
+34. **P2 — File separation has not yet produced clear internal boundaries. Confirmed maintenance risk.** The browser scripts share mutable globals and a required evaluation order; cart and editor state can diverge, as reproduced above. API routes still implement SQL/business transactions, and the operator artwork router imports and calls the customer upload route functions directly. `runtime.py` constructs environment-bound adapters at import time, making isolated business tests harder. Every database operation creates a new connection, and synchronous audit DB writes also run directly in async middleware. Keep the small deployment, but move reusable use cases behind explicit interfaces, use one cart state model, and introduce bounded connection management as load requires. Evidence: [index.html:1376](/home/farelos/compor/dtf-sistema/web/index.html:1376), [api/artwork.py:15](/home/farelos/compor/dtf-sistema/app/api/artwork.py:15), [runtime.py:21](/home/farelos/compor/dtf-sistema/app/runtime.py:21), [db.py:6](/home/farelos/compor/dtf-sistema/app/core/db.py:6), [app.py:30](/home/farelos/compor/dtf-sistema/app/app.py:30).
+
+35. **P2 — Existing tests verify the mock workflow more strongly than the delivered product. Confirmed coverage gap.** Pricing parity is valuable, but uses only 11 lengths and shared tables; it cannot validate print geometry. Integration fixtures deliberately use plain text with a `.cdr` extension, which tests transport but proves no printability. The current isolated browser server does not serve `/vendor/...`, and its tests do not exercise real PDF parsing. Missing operational entrypoints and stale-cart behavior passed the suite. CI tests local images/configuration, not the final production images and Swarm proxy topology. Add targeted acceptance for the defects above, real representative artwork, fault/retry cases, clean/upgrade schema paths, operational command packaging, and the exact release artifacts. Evidence: [test_pricing.py:10](/home/farelos/compor/dtf-sistema/tests/test_pricing.py:10), [fixtures/local-test.cdr](/home/farelos/compor/dtf-sistema/tests/fixtures/local-test.cdr), [artwork_browser_test.mjs:26](/home/farelos/compor/dtf-sistema/tests/artwork_browser_test.mjs:26), [deploy.yml:59](/home/farelos/compor/dtf-sistema/.gitea/workflows/deploy.yml:59).
+
+36. **P2 — Documentation and generated deliverables can send operators to the wrong system. Partly introduced today.** README's active quick start still selects the production Compose file. Portainer instructions tell users to populate secret/volume/host variables the actual stack does not consume. Security/context documents still claim absent rollback, secrets, blocked deployment, or obsolete CDN behavior. The historical index calls the local milestone report a different prototype. The client PDF's diagram still labels a worker preflight while its scope defers it. Moving the PDF generator in `66ddb17` left `parents[2]`, which now resolves to `/home/farelos/compor`, outside this repository, and its output path no longer matches the documented PDF. Correct executable instructions and current claims, and validate generated output paths. Evidence: [README.md:3](/home/farelos/compor/dtf-sistema/README.md:3), [PORTAINER.md:73](/home/farelos/compor/dtf-sistema/docs/PORTAINER.md:73), [SECURITY_REPORT.md:40](/home/farelos/compor/dtf-sistema/docs/SECURITY_REPORT.md:40), [generate_dtf_report.py:17](/home/farelos/compor/dtf-sistema/tools/generate_dtf_report.py:17).
+
+37. **P2 — Dependency/rebuild claims exceed the enforced supply-chain contract. Confirmed maintenance gap.** Vendoring PDF.js removed the CDN dependency, but version 3.11.174 remains old and has no automated inventory/update check. Its known eval advisory is mitigated by the existing `isEvalSupported:false` and restrictive CSP; this is not reported as demonstrated arbitrary code execution. PostgreSQL remains a mutable tag; CI scans only the application images. Unversioned OS upgrades and optional base-image overrides also mean a pinned base alone does not guarantee identical rebuilt images. The pricing tables are still separately maintained in JS/Python, though parity tests help. Record complete dependency provenance, scan all deployed images and vendored assets, and maintain a controlled refresh process. Evidence: [vendor/README.md:7](/home/farelos/compor/dtf-sistema/web/vendor/README.md:7), [site-pdf.js:97](/home/farelos/compor/dtf-sistema/web/site-pdf.js:97), [docker-compose.yml:41](/home/farelos/compor/dtf-sistema/docker-compose.yml:41), [deploy/Dockerfile.api:16](/home/farelos/compor/dtf-sistema/deploy/Dockerfile.api:16). Reference: [Mozilla's advisory and workaround](https://github.com/mozilla/pdf.js/security/advisories/GHSA-wgrm-67xf-hhpq). No fresh vulnerability counts are asserted here.
+
+**Today's commit assessment**
+
+| Commits | Result at reviewed HEAD |
+|---|---|
+| `341f154`, `d2f7b2c` | Secret-file loader and tests are useful; active stack still does not use them. |
+| `9da2a7d`, `bbcc8ab` | Added real gates, but source readiness remains advisory and publication precedes image acceptance. |
+| `4c9fa24`, `010c2a1` | Pinned application bases and added CRITICAL scanning. Do not infer current zero findings for every deployed service. |
+| `6c52ad6`, `6a50e6d` | Fixed CI image retrieval/configuration packaging. |
+| `24cb52d`, `7cab210`, `c1a07a7`, `dbc9ba4` | Improved integration execution after port/network failures; browser/network coverage and run isolation remain incomplete. |
+| `3b92813` | Recovered proxy client headers but trusts overly broad private ranges; needs real-topology verification. |
+| `e95a42d`, `9926d3a`, `91269ce` | Removed duplicate stack definition; active hardening and documentation were not reconciled completely. |
+| `da903db` | Removed PDF.js CDN dependency; old dependency and PDF logic remain. |
+| `a874033` | Added useful per-operator attribution; session issuance has a disable/login race. |
+| `543a9a9`, `86b8199` | Added useful indexes and bounded finished history; fixed table/index ordering. Quote truncation creates starvation. |
+| `ca69843` | Removed inactive prototypes; this correctly reduces ambiguity and should not be counted as lost active functionality. |
+| `96f1d27`, `c9f8122` | Improved code navigation and router assembly. Global state and business boundaries remain coupled. |
+| `66ddb17` | Removed accidentally tracked deliverables from HEAD and relocated artifacts; generator root/output was not updated. Untracking does not remove historical Git objects. |
+| `b329f76` | Improved directory roles; broke staging/backup/security command packaging. |
+| `7386469` | Centralized engineering docs; several executable instructions and current-state claims still disagree with code. |
+
+The overall problem with today's work is incomplete acceptance around operational entrypoints and domain behavior. The reorganizations themselves are reasonable. Neither a microservice rewrite nor returning to the deleted prototypes would address the findings above.
+
+**Recommended order of work**
+
+1. Fix confirmed data/work-loss defects: preserve production instructions; clear stale cart state; bind quotes to the displayed cart; remove quote starvation; invalidate finals after corrections.
+2. Repair operational command packaging and establish a real backup/restore path. Address stale signatures, anonymous quota exhaustion, and the actual proxy trust boundary before accepting public uploads.
+3. Resolve the two central product decisions: unattended price authority and supported large-file processing. Align the site promises with the chosen interim behavior.
+4. Complete the MVP contracts: destination address/freight, durable payment intents and webhooks, Tiny, final-file generation, and the four WhatsApp events. Test their failure/reconciliation paths in staging.
+5. Make release identity, exact-artifact testing, browser tests, production configuration checks, and post-deployment verification enforceable. Reconcile the documentation with that one implementation.
+
+The current controls worth preserving are server-calculated prices, immutable approved quotes, owner-scoped access, parameterized SQL, password hashing, revocable HttpOnly sessions, strict script CSP, private signed storage access, malware quarantine, state/version checks, transactional outbox insertion, and dependency hashes. This review identifies material defects and gaps supported by the inspected code; it does not establish that every possible flaw has been found.

docs/SECURITY_REPORT.md

@@ -77,14 +77,15 @@ the signatures bundled into that image. On closeout it reported ClamAV
 below the seven-day alert threshold.
 
 The multipart transport supports uploads up to 5 GiB, but `SCAN_MAX_BYTES` and
-ClamAV stream limits release at most 128 MiB by default. Larger files remain
-blocked. Supporting larger files requires a deliberate resource/timeout design,
-not simply increasing the upload limit.
+ClamAV stream limits release at most 128 MiB by default. As of 2026-09-23 the
+API and customer picker reject larger files before transfer. Supporting them
+requires a deliberate resource/timeout design, not simply increasing the
+transport limit.
 
 Run:
 
 ```bash
-docker compose exec -T api python -m local.security_status
+docker compose -f compose.local.yaml exec -T api python3 -m ops.security_status
 ```
 
 An exit status of 1 requires review. At closeout, attention was expected because
@@ -99,7 +100,7 @@ errors, unexplained authentication bursts, or stale signatures as incidents.
 
 `pip-audit` inspected the exact packages installed in the hash-enforced rebuilt API
 and found no known Python advisories on 2026-09-15. All 26 direct and transitive
-runtime packages are pinned with artifact hashes in `local/requirements.lock`.
+runtime packages are pinned with artifact hashes in `infra/requirements.lock`.
 `local/lock_dependencies.sh` regenerates it in a disposable Python 3.12 container.
 This is a point-in-time package-database result, not proof that the dependencies
 or image are vulnerability-free. Scheduled lock refresh and audit automation remain
@@ -129,10 +130,14 @@ change when the advisory database or selected base digest changes.
 ## Production delivery security boundary
 
 The files in `deploy/` and `.gitea/workflows/` are a guarded delivery mechanism,
-not an approval to operate the current application on the public internet. The
-single Gitea workflow requires a protected Docker runner, exact commit checkout,
-digest-pinned base/scanner images, regressions, and HIGH/CRITICAL Trivy gates.
-It publishes both `latest` and the full commit SHA, then calls the Portainer
+not an approval to operate the current application on the public internet.
+
+Updated 2026-09-23: pushes to `main` run checks only. A manual workflow run on
+`main` requires the source preflight and a configured Portainer webhook before
+building. It scans built images before publication; CRITICAL findings block and
+HIGH findings are reported. The browser suites run in a required Compose Chrome
+container. `PORTAINER.md` holds the authoritative gate table. A permitted release
+publishes both `latest` and the full commit SHA, then calls the Portainer
 webhook. Application/provider secrets are created directly as versioned external
 Swarm secrets and never cross the workflow. Rollback selects the prior commit SHA
 in Portainer and does not roll back the database.

docs/guias/imprimir.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Print the guide sources in docs/guias/ to the PDFs in docs/ with headless
+# Chrome (A4, no browser header or footer). Needs Chrome and the DejaVu fonts.
+set -eu
+cd "$(dirname "$0")"
+CHROME=${CHROME:-$(command -v google-chrome-stable || command -v google-chrome || command -v chromium)}
+"$CHROME" --headless --disable-gpu --no-pdf-header-footer --run-all-compositor-stages-before-draw \
+  --print-to-pdf="$PWD/../guia-operador-kanban.pdf" "file://$PWD/operador/guia-operador-kanban.html"

docs/guias/operador/guia-operador-kanban.html

@@ -0,0 +1,320 @@
+<!DOCTYPE html>
+<!-- Source of docs/guia-operador-kanban.pdf. Print with docs/guias/imprimir.sh.
+     Screenshots in img/ come from a throwaway stack with fictional orders. -->
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<title>Kanban DTF · Guia do operador</title>
+<style>
+  @page { size: A4; margin: 0; }
+  :root {
+    --navy: #0B1320; --orange: #F08A24; --ink: #1B2331; --muted: #6B7280;
+    --line: #D6DCE4; --head: #EAF0F8; --note: #FFF5E8; --note-line: #F4C58E;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body { font-family: 'DejaVu Sans', sans-serif; color: var(--ink); font-size: 9.7pt; line-height: 1.55;
+         -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  .page { width: 210mm; height: 297mm; position: relative; padding: 26mm 18mm 20mm; overflow: hidden;
+          page-break-after: always; break-after: page; }
+  .page:last-child { page-break-after: auto; break-after: auto; }
+  .running { position: absolute; top: 9mm; left: 18mm; right: 18mm; font-size: 7.4pt; color: var(--muted);
+             border-bottom: 0.6pt solid #E3E7ED; padding-bottom: 2.4mm; }
+  .folio { position: absolute; bottom: 9mm; right: 18mm; font-size: 7.4pt; color: var(--muted); }
+  .kicker { color: var(--orange); font-weight: bold; font-size: 7.6pt; letter-spacing: 0.04em; margin: 0 0 1mm; }
+  h1 { font-size: 20.5pt; line-height: 1.2; margin: 0 0 2mm; color: #101826; }
+  h1::after { content: ""; display: block; width: 18mm; height: 1.4mm; background: var(--orange); margin-top: 3mm; }
+  h2 { font-size: 11.5pt; margin: 7mm 0 2.5mm; color: #101826; }
+  p { margin: 0 0 2.6mm; }
+  b { font-weight: bold; }
+  table { width: 100%; border-collapse: collapse; margin: 2mm 0 3mm; font-size: 8.6pt; line-height: 1.45; }
+  th, td { border: 0.6pt solid var(--line); padding: 2mm 2.4mm; vertical-align: top; text-align: left; }
+  th { background: var(--head); font-weight: bold; }
+  td.n { color: var(--orange); font-weight: bold; font-size: 11pt; width: 7mm; text-align: center; }
+  td.k { font-weight: bold; }
+  .note { background: var(--note); border: 0.6pt solid var(--note-line); border-radius: 2mm; padding: 3mm 3.6mm;
+          font-size: 8.6pt; margin: 3mm 0; }
+  ul { margin: 0 0 3mm; padding-left: 4.5mm; }
+  ul li { margin-bottom: 1.1mm; }
+  ul li::marker { color: var(--orange); }
+  ol { margin: 0 0 3mm; padding-left: 5mm; }
+  ol li { margin-bottom: 1.3mm; }
+  ol li::marker { color: var(--orange); font-weight: bold; }
+  .chip { display: inline-block; border: 0.6pt solid #C9D0DA; background: #F4F6F9; border-radius: 1.2mm;
+          padding: 0 1.6mm; font-size: 7.6pt; line-height: 1.6; white-space: nowrap; }
+  .shot { display: block; width: 100%; border-radius: 1.6mm; margin: 2mm 0 1mm; }
+  .caption { font-size: 7.2pt; color: var(--muted); margin: 0 0 3mm; }
+  .split { display: flex; gap: 6mm; align-items: flex-start; }
+  .split > div { flex: 1; }
+  .split > .side { flex: 0 0 79.5mm; }
+  .quote { font-style: normal; }
+
+  /* Cover */
+  .cover { background: var(--navy); color: #F3F5F8; padding: 0 18mm; }
+  .cover .block { position: absolute; left: 18mm; right: 18mm; top: 158mm; }
+  .cover .kicker { margin-bottom: 4mm; }
+  .cover .title { font-size: 27pt; font-weight: bold; line-height: 1.25; margin: 0 0 4mm; color: #fff; }
+  .cover .lead { font-size: 9.6pt; color: #C8CFDA; margin: 0 0 8mm; }
+  .cover table { font-size: 8pt; margin: 0 0 8mm; }
+  .cover th, .cover td { border-color: #2A3547; background: transparent; color: #E6EAF0; padding: 3mm 3.6mm; }
+  .cover th { color: var(--orange); }
+  .cover .version { font-size: 8pt; color: #A9B2C0; }
+</style>
+</head>
+<body>
+
+<!-- 1 · Capa -->
+<section class="page cover">
+  <div class="block">
+    <p class="kicker">GUIA DE OPERAÇÃO</p>
+    <p class="title">Kanban DTF<br>Guia do operador</p>
+    <p class="lead">Como conferir, produzir e entregar os pedidos que chegam pelo Site DTF.</p>
+    <table>
+      <tr><th style="width:50%">Acesso</th><th>Quem usa</th></tr>
+      <tr><td>dtf.kanban.agenciacompor.com.br<br>e-mail e senha do operador</td>
+          <td>Equipe da sala de DTF e atendimento</td></tr>
+    </table>
+    <p class="version">Versão de 25 de setembro de 2026</p>
+  </div>
+</section>
+
+<!-- 2 · Visão geral -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">VISÃO GERAL</p>
+  <h1>O caminho de um pedido</h1>
+  <p>O cliente monta a folha e envia as artes pelo Site DTF. Daí em diante, tudo acontece no Kanban: a equipe
+    confere a cotação, o cliente paga, e o pedido percorre as etapas de produção até ficar pronto para retirada.</p>
+  <table>
+    <tr><td class="n">1</td><td class="k" style="width:31mm">Cliente envia</td>
+        <td>Monta a folha no Site, vê a nota e o preço e envia o pedido para conferência.</td></tr>
+    <tr><td class="n">2</td><td class="k">Equipe confere a cotação</td>
+        <td>Na aba <b>Cotações</b>: confere arquivos, metragem e nota e aprova.</td></tr>
+    <tr><td class="n">3</td><td class="k">Cliente paga</td>
+        <td>O total aprovado aparece no Site. O pagamento é pelo Mercado Pago (PIX ou cartão).</td></tr>
+    <tr><td class="n">4</td><td class="k">Pedido entra na produção</td>
+        <td>Com o pagamento aprovado, o pedido aparece em <b>Arte recebida</b>, com o PDF de impressão já gerado.</td></tr>
+    <tr><td class="n">5</td><td class="k">Equipe produz</td>
+        <td>Aprova o arquivo final, baixa, importa no FlexiPRINT e move o card a cada etapa.</td></tr>
+    <tr><td class="n">6</td><td class="k">Pedido pronto</td>
+        <td>Em <b>Finalizado</b>, o pedido fica pronto para retirada e o cliente é avisado (página 7).</td></tr>
+  </table>
+  <h2>As quatro abas</h2>
+  <table>
+    <tr><th style="width:31mm">Aba</th><th>Para que serve</th></tr>
+    <tr><td class="k">Produção</td><td>O quadro com os pedidos pagos, uma coluna por etapa.</td></tr>
+    <tr><td class="k">Cotações</td><td>Pedidos enviados pelo Site esperando conferência. O número ao lado indica quantos faltam revisar.</td></tr>
+    <tr><td class="k">Pagamentos</td><td>Pagamentos que o sistema não conseguiu ligar a um pedido. Normalmente fica vazia.</td></tr>
+    <tr><td class="k">Integrações</td><td>Situação do Tiny, Mercado Pago, frete e WhatsApp, e o registro de tudo o que foi enviado a eles.</td></tr>
+  </table>
+  <div class="note">O quadro não se atualiza sozinho. Clique em <b>Atualizar</b>, no canto superior direito, para ver pedidos e cotações novos.</div>
+  <div class="folio">Página 2</div>
+</section>
+
+<!-- 3 · Entrar e ler o quadro -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PRODUÇÃO</p>
+  <h1>Entrar e ler o quadro</h1>
+  <div class="split">
+    <div>
+      <p>Acesse <b>dtf.kanban.agenciacompor.com.br</b> e entre com seu e-mail e senha. Cada operador tem o próprio
+        acesso: é o nome dele que fica registrado em cada movimento do pedido.</p>
+      <p>Depois de várias senhas erradas seguidas, o acesso fica bloqueado por 15 minutos.</p>
+    </div>
+    <div class="side"><img class="shot" src="img/login.png" alt="Tela de entrada do Kanban"></div>
+  </div>
+  <img class="shot" src="img/quadro.png" alt="Quadro de produção">
+  <p class="caption">Quadro de produção com três pedidos em etapas diferentes.</p>
+  <h2>O que cada card mostra</h2>
+  <ul>
+    <li><b>#número</b> do pedido e há quanto tempo ele está parado na etapa.</li>
+    <li>E-mail do cliente, produto e metragem cobrada (ex.: <span class="chip">Têxtil avulsa · 1,00 m</span>).</li>
+    <li>Situação do arquivo: <span class="chip">PDF pronto</span> (gerado, falta aprovar), <span class="chip">Final aprovado</span>
+      (pode ir para a fila) ou <span class="chip">Preparar à mão</span> (o sistema não conseguiu gerar; veja a página 6).</li>
+    <li><span class="chip">Retirada</span> ou <span class="chip">Entrega · UF</span>.</li>
+    <li>Um aviso <b>Parado há mais de 4 h</b> aparece quando o pedido não anda.</li>
+  </ul>
+  <p>Os filtros <b>Têxtil</b>, <b>UV</b> e <b>Preparar à mão</b> mostram só esses pedidos. A busca encontra pedido, cliente ou CNPJ.</p>
+  <div class="folio">Página 3</div>
+</section>
+
+<!-- 4 · Cotações -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">COTAÇÕES</p>
+  <h1>Conferir e aprovar uma cotação</h1>
+  <img class="shot" src="img/cotacoes.png" alt="Aba Cotações">
+  <p class="caption">À esquerda, as cotações a revisar; à direita, a cotação selecionada.</p>
+  <ol>
+    <li>Abra a aba <b>Cotações</b> e clique na cotação em <b>A revisar</b>.</li>
+    <li>Confira a montagem na miniatura. Se precisar, abra os arquivos em <b>Original</b> ou a lista de peças em <b>Manifesto</b>.</li>
+    <li>Confira <b>Metros conferidos</b> e <b>Nota conferida</b>. Os valores do cliente já vêm preenchidos; mude só se
+      estiverem errados. A nota define o preço do metro.</li>
+    <li>Marque <b>Arquivos, metragem e nota conferidos</b> e clique em <b>Aprovar cotação</b>.</li>
+  </ol>
+  <p>O cliente vê o total aprovado no Site e tem <b>24 horas</b> para pagar. As aprovadas ficam em
+    <b>Aprovadas, aguardando pagamento</b> até o pagamento chegar.</p>
+  <div class="note"><b>Ressalva de resolução aceita pelo cliente</b>: alguma arte tem menos de 300 DPI e o cliente confirmou
+    que quer imprimir assim. <b>Montagem antiga</b>: a cotação foi feita numa versão anterior do Site; peça ao cliente
+    para enviar de novo.</div>
+  <div class="folio">Página 4</div>
+</section>
+
+<!-- 5 · Abrir um pedido -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PRODUÇÃO</p>
+  <h1>Abrir um pedido</h1>
+  <img class="shot" src="img/painel.png" alt="Painel do pedido">
+  <p class="caption">Clique em qualquer card para abrir o painel do pedido.</p>
+  <table>
+    <tr><th style="width:36mm">Parte do painel</th><th>O que tem</th></tr>
+    <tr><td class="k">Topo</td><td>Número, etapa atual, data do pagamento e os botões para mover o pedido.</td></tr>
+    <tr><td class="k">Cliente e Entrega</td><td>E-mail, CNPJ e WhatsApp do cliente; endereço ou <b>Retirada em Franca</b>.</td></tr>
+    <tr><td class="k">Itens e arquivos de impressão</td><td>Montagem de cada item, peças, tamanho da folha e nota. <b>Baixar PDF</b>
+      baixa o arquivo pronto para o FlexiPRINT; <b>Original</b> baixa o arquivo que o cliente enviou; <b>Manifesto</b>
+      lista as peças e suas posições.</td></tr>
+    <tr><td class="k">Arquivos finais</td><td>O arquivo que vai ser impresso, aprovado por um operador (próxima página).</td></tr>
+    <tr><td class="k">Histórico</td><td>Cada movimento do pedido, com hora, operador e motivo.</td></tr>
+  </table>
+  <div class="folio">Página 5</div>
+</section>
+
+<!-- 6 · Arquivo final -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PRODUÇÃO</p>
+  <h1>Aprovar o arquivo final</h1>
+  <div class="split">
+    <div>
+      <p>Antes de ir para a <b>Fila de impressão</b>, todo item precisa de um arquivo final aprovado. O sistema já gera
+        um PDF com a montagem que o cliente viu e pagou.</p>
+      <ol>
+        <li>Baixe o PDF em <b>Baixar PDF</b> e confira.</li>
+        <li>Deixe marcado <b>Usar o PDF gerado</b>. Se preferir usar outro arquivo, desmarque e envie o seu.</li>
+        <li>Escreva uma <b>Nota da revisão</b> (ex.: “Conferido, pronto para imprimir”).</li>
+        <li>Marque <b>Arquivos conferidos</b> e clique em <b>Aprovar arquivos finais</b>.</li>
+      </ol>
+      <p>O card passa a mostrar <span class="chip">Final aprovado</span>.</p>
+    </div>
+    <div class="side"><img class="shot" src="img/arquivo-final.png" alt="Aprovação do arquivo final"></div>
+  </div>
+  <h2>Quando o PDF não é gerado</h2>
+  <table>
+    <tr><th style="width:40mm">No card ou no item</th><th>O que fazer</th></tr>
+    <tr><td><span class="chip">Na fila para gerar</span></td><td>Aguarde alguns segundos e clique em <b>Atualizar</b>.</td></tr>
+    <tr><td><span class="chip">Preparar à mão</span></td><td>O cliente enviou um formato que o gerador não lê (CDR, AI, PSD, TIFF)
+      ou pediu correção. Baixe o <b>Original</b>, prepare o arquivo no seu programa e envie-o em <b>Arquivos finais</b>.</td></tr>
+    <tr><td><span class="chip">Falhou ao gerar</span></td><td>Clique em <b>Gerar novamente</b>. Se falhar de novo, prepare à mão.</td></tr>
+  </table>
+  <div class="folio">Página 6</div>
+</section>
+
+<!-- 7 · Mover pelas etapas -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PRODUÇÃO</p>
+  <h1>Mover o pedido pelas etapas</h1>
+  <p>Use o botão laranja <b>Mover para…</b> no topo do painel ou arraste o card para a coluna seguinte. Ao arrastar,
+    só as colunas permitidas ficam destacadas.</p>
+  <table>
+    <tr><th style="width:27mm">Etapa</th><th>Significa</th><th style="width:43mm">Aviso ao cliente</th></tr>
+    <tr><td class="k">Arte recebida</td><td>Pedido pago, arquivo gerado. Ainda não conferido.</td><td>Pedido aprovado (automático)</td></tr>
+    <tr><td class="k">Arte tratada</td><td>Arquivo conferido e ajustado, se preciso.</td><td>—</td></tr>
+    <tr><td class="k">Fila de impressão</td><td>Pronto para imprimir. Exige o arquivo final aprovado.</td><td>—</td></tr>
+    <tr><td class="k">Imprimindo</td><td>Na máquina.</td><td>—</td></tr>
+    <tr><td class="k">Finalizado</td><td>Impresso e pronto para retirada ou envio.</td><td>Pedido pronto para retirada</td></tr>
+    <tr><td class="k">Correção</td><td>Algo no arquivo precisa ser resolvido pelo cliente.</td><td>O motivo aparece em Minha conta, no Site (página 8)</td></tr>
+  </table>
+  <div class="note">Os avisos por WhatsApp saem pelo número e pelas mensagens que a Dropstar já usa, a partir da situação
+    do pedido no Tiny: o pedido pago fica <b>Aprovado</b> e, em <b>Finalizado</b>, o pedido de retirada fica
+    <b>Pronto para envio</b>. Cada aviso sai <b>uma vez só</b>, mesmo que o pedido volte uma etapa e avance de novo.
+    As outras etapas não mudam o pedido no Tiny. Enquanto essa integração não estiver ativa, avise o cliente como hoje.</div>
+  <h2>Moveu errado? Volte uma etapa</h2>
+  <img class="shot" src="img/voltar-etapa.png" alt="Botão Voltar para">
+  <p class="caption">Botão <b>Voltar para…</b>: pede um motivo interno e não avisa o cliente.</p>
+  <p>Clique em <b>Voltar para [etapa anterior]</b>, escreva o motivo (ex.: “movi por engano”) e confirme. O retorno fica
+    no histórico como <b>Voltou para…</b>. O cliente não vê esse retorno nem o motivo.</p>
+  <div class="folio">Página 7</div>
+</section>
+
+<!-- 8 · Correção -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PRODUÇÃO</p>
+  <h1>Pedir correção ao cliente</h1>
+  <img class="shot" src="img/pedir-correcao.png" alt="Botão Pedir correção" style="width:78%">
+  <p class="caption">Botão <b>Pedir correção</b>: o motivo vai para o cliente.</p>
+  <ol>
+    <li>No painel do pedido, clique em <b>Pedir correção</b>.</li>
+    <li>Escreva o motivo de forma clara para o cliente (ex.: “A arte escudo.png está com fundo branco. Envie com fundo transparente.”).</li>
+    <li>Clique em <b>Enviar para correção</b>. O pedido vai para a coluna <b>Correção</b>.</li>
+  </ol>
+  <p>O cliente vê o motivo em <b>Minha conta</b>, no Site, e envia por lá o arquivo corrigido. Esse aviso ainda não sai
+    pelo WhatsApp: avise o cliente de que há uma correção pendente. O arquivo corrigido aparece em <b>Arquivos finais</b>
+    como <b>Correção do cliente</b>. Confira, mova o pedido para <b>Arte recebida</b> ou <b>Arte tratada</b> e siga o fluxo normal.</p>
+  <div class="note">Correção é para problemas que só o cliente resolve (resolução, fundo, arte errada). Ajustes que a equipe
+    faz sozinha não precisam de correção: trate o arquivo em <b>Arte tratada</b>.</div>
+  <h2>Histórico</h2>
+  <img class="shot" src="img/historico.png" alt="Histórico do pedido" style="width:78%">
+  <p class="caption">Cada movimento fica registrado com data, hora e operador.</p>
+  <div class="folio">Página 8</div>
+</section>
+
+<!-- 9 · Pagamentos e integrações -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">PAGAMENTOS E INTEGRAÇÕES</p>
+  <h1>Pagamentos com problema e integrações</h1>
+  <p>A aba <b>Pagamentos</b> lista os pagamentos que chegaram mas não puderam virar pedido sozinhos. Exemplos:</p>
+  <ul>
+    <li>valor pago diferente do total da cotação;</li>
+    <li>cotação vencida antes do pagamento (passou das 24 h);</li>
+    <li>pagamento estornado ou cancelado depois que o pedido já existia.</li>
+  </ul>
+  <p>Resolva com o cliente ou no Mercado Pago e clique em <b>Registrar resolução</b>, descrevendo o que foi feito.
+    O item passa para <b>Resolvidos</b>.</p>
+  <img class="shot" src="img/pagamentos.png" alt="Aba Pagamentos">
+  <h2>Integrações</h2>
+  <img class="shot" src="img/integracoes.png" alt="Aba Integrações">
+  <p class="caption">Imagem de um ambiente sem integrações ativas. Em produção, cada cartão mostra se a integração está conectada.</p>
+  <ul>
+    <li><b>Tiny</b>: o cartão mostra quem conectou, quando a conexão foi renovada e até quando vale; o sistema renova
+      sozinho. Se aparecer <b>Não conectado</b> ou <b>Verificar</b>, clique em <b>Conectar Tiny</b> ou <b>Reconectar</b> e
+      entre com o usuário do Tiny indicado pela Dropstar. <b>Testar conexão</b> confere pedidos, contatos, os produtos
+      e a forma de envio de retirada, sem criar nada.</li>
+    <li><b>Registro de envios</b>: tudo o que o sistema mandou ao Tiny e ao WhatsApp, com filtros por destino, situação,
+      evento e pedido. <b>Com erro</b> indica um envio que falhou; o sistema tenta de novo sozinho, mas o erro precisa de atenção.</li>
+  </ul>
+  <div class="folio">Página 9</div>
+</section>
+
+<!-- 10 · Dúvidas -->
+<section class="page">
+  <div class="running">DTF Dropstar - guia do operador</div>
+  <p class="kicker">DÚVIDAS FREQUENTES</p>
+  <h1>Mensagens e o que fazer</h1>
+  <table>
+    <tr><th style="width:62mm">Mensagem ou situação</th><th>O que fazer</th></tr>
+    <tr><td>“O pedido mudou. Clique em Atualizar.”</td><td>Outra pessoa mexeu no pedido ao mesmo tempo. Clique em <b>Atualizar</b> e repita a ação.</td></tr>
+    <tr><td>“Aprove os arquivos finais de todos os itens antes de colocar na fila.”</td><td>Aprove o arquivo final de cada item (página 6) e tente de novo.</td></tr>
+    <tr><td>“Informe o motivo da correção.” / “Informe por que o pedido está voltando de etapa.”</td><td>Preencha o motivo antes de confirmar.</td></tr>
+    <tr><td>Cotação com <b>Montagem antiga</b></td><td>Peça ao cliente para enviar o pedido de novo pelo Site.</td></tr>
+    <tr><td>Card com <b>Parado há mais de 4 h</b></td><td>Veja se o pedido está esperando alguém ou se esqueceram de movê-lo.</td></tr>
+    <tr><td>Arquivo aparece como <b>expirado</b></td><td>Os arquivos ficam guardados por 30 dias. Depois disso, o cliente precisa enviar de novo.</td></tr>
+    <tr><td>No topo, <b>Tiny: verificar conexão</b> ou <b>Tiny não conectado</b></td><td>Abra <b>Integrações</b> e siga a mensagem do cartão do Tiny. Se pedir, clique em <b>Reconectar</b>.</td></tr>
+    <tr><td>A internet da fábrica caiu</td><td>O Site continua recebendo pedidos e pagamentos. Quando a conexão voltar, clique em <b>Atualizar</b>.</td></tr>
+  </table>
+  <h2>Boas práticas</h2>
+  <ul>
+    <li>Mova o card assim que a etapa mudar: é o que avisa o cliente e mede o tempo de produção.</li>
+    <li>Escreva motivos que outra pessoa entenda sem perguntar.</li>
+    <li>Use sempre o seu acesso: o histórico mostra quem fez cada movimento.</li>
+    <li>Clique em <b>Sair</b> ao deixar o computador.</li>
+  </ul>
+  <div class="folio">Página 10</div>
+</section>
+
+</body>
+</html>

docs/historico/README.md

@@ -0,0 +1,26 @@
+# Historical documents
+
+These describe the project as it was originally designed: a Tiny-first flow with
+token upload links, a factory-side agent, a local SQLite Kanban, FlexiPRINT
+automation, 90-day retention and 12-month artwork reuse.
+
+**None of it describes the system that exists.** `CONTEXT.md` is the current
+source of truth and `ROADMAP.md` tracks outstanding work. These are kept because
+they record decisions and reasoning that the current documents do not repeat —
+read them for background, never as instructions.
+
+| File | What it was |
+|---|---|
+| `ESPECIFICACAO.md` | Original specification of the Tiny-first model |
+| `API.md` | Endpoint sketch for the prototype portal |
+| `TAREFAS.md` | Task plan written before the current scope |
+| `IMPLEMENTATION_REPORT.md` | Status report for the prototype milestone |
+| `dtf-organograma-*` | Organisation charts, referenced by nothing |
+
+The prototype code they describe — `portal/`, `kanban/`, `agente/`, the root
+`schema.sql` and `.env.exemplo` — was removed once nothing referenced it. Recover
+it from Git history if it is ever needed:
+
+```bash
+git log --oneline --diff-filter=D -- portal kanban agente
+```

infra/Dockerfile

@@ -0,0 +1,20 @@
+# Same pinned base as deploy/Dockerfile.api, so the integration suite exercises
+# the image that ships rather than a different one.
+FROM python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9
+# pg_dump and age are for the database backup (ops/db_backup.py). Debian 13
+# ships PostgreSQL 17, the server's major version, which pg_dump must match.
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y --no-install-recommends postgresql-client-17 age \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY infra/requirements.txt infra/requirements.lock /app/infra/
+RUN pip install --no-cache-dir --require-hashes -r infra/requirements.lock
+COPY app /app/app
+COPY ops /app/ops
+# The local image carries the suites so they can run inside the stack network.
+# deploy/Dockerfile.api deliberately does not: tests are not part of what ships.
+COPY tests /app/tests
+RUN useradd --uid 10001 --create-home dtf
+USER dtf
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1

infra/Dockerfile.browser-tests

@@ -0,0 +1,13 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends chromium ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+COPY tests /workspace/tests
+COPY web /workspace/web
+RUN mkdir -p /workspace/output/local \
+    && chown -R node:node /workspace/output
+USER node
+ENV CHROME_BIN=/usr/bin/chromium

infra/Dockerfile.scanner

@@ -0,0 +1,7 @@
+# The scanner configuration is baked in rather than bind-mounted.
+# A containerised CI runner shares the host's Docker daemon, so a host path from
+# the runner's workspace does not exist where the daemon creates the mount: it
+# makes an empty directory instead and the container fails to start.
+ARG CLAMAV_IMAGE=clamav/clamav@sha256:9cb27d7660bdf66e9878c832cb433dd8aa152cfbe16f3c2c0084c80b04ae22b4
+FROM ${CLAMAV_IMAGE}
+COPY infra/clamd.conf /etc/clamav/clamd.conf

infra/Dockerfile.storage-init

@@ -0,0 +1,6 @@
+# Provisioning script and policies baked in, for the same reason as the scanner.
+ARG MINIO_IMAGE=cgr.dev/chainguard/minio@sha256:bd014394a80898e68c149f2311fdf8d5a2c2f3bb2c33b9327ae6d02b4b065ae1
+FROM ${MINIO_IMAGE}
+COPY infra/storage-init.sh /init.sh
+COPY infra/storage-policy.json /policy.json
+COPY infra/storage-lifecycle.json /lifecycle.json

infra/Dockerfile.web

@@ -0,0 +1,15 @@
+FROM python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9 AS policy
+WORKDIR /build
+COPY web /build/web
+COPY infra /build/infra
+RUN python infra/compile_web.py
+
+# Same pinned base as deploy/Dockerfile.web.
+FROM nginx:alpine@sha256:62ff2089abf5a9ed33bd232895bef5e22f7bb4b200675cec49a5ebc48e3d4ac8
+RUN apk upgrade --no-cache
+ENV WEB_INDEX=index.html
+COPY --from=policy /build/default.conf.template /etc/nginx/templates/default.conf.template
+ENV S3_PUBLIC_ENDPOINT=http://localhost:9000
+# The HTML from the policy stage, with every asset address versioned.
+COPY --from=policy /build/web/ /usr/share/nginx/html/
+

infra/clamd.conf

@@ -5,10 +5,12 @@ TCPSocket 3310
 TCPAddr 0.0.0.0
 MaxThreads 2
 MaxQueue 8
-StreamMaxLength 128M
-MaxFileSize 128M
-MaxScanSize 256M
-MaxScanTime 120000
+StreamMaxLength 2000M
+MaxFileSize 2000M
+MaxScanSize 4000M
+MaxScanTime 900000
+ReadTimeout 900
+CommandReadTimeout 900
 AlertExceedsMax yes
 AlertEncrypted yes
 ScanPDF yes

infra/compile_web.py

@@ -0,0 +1,43 @@
+"""Compile the gateway configuration and version the Site's assets.
+
+Inline scripts are hashed for the CSP; local scripts and stylesheets get a
+content hash in their address.
+
+The Site's behaviour now lives in separate files, so normally there is nothing to
+hash and the policy is simply script-src 'self' — no allowlist to get wrong. The
+hashing stays because an inline script added later must not silently need
+'unsafe-inline'; it is hashed automatically instead.
+"""
+import base64
+import hashlib
+import os
+from pathlib import Path
+import re
+
+root = Path('/build')
+
+# Every local script and stylesheet is addressed by its content, so a release
+# can never pair new HTML with an old cached file: the proxy in front of the
+# stack caches assets for hours, and a new index.html calling an old script
+# broke the Site (2026-09-28). The HTML itself is served no-cache.
+def versioned(match):
+    attribute, path = match.group(1), match.group(2)
+    digest = hashlib.sha256((root / 'web' / path.lstrip('/')).read_bytes()).hexdigest()[:12]
+    return f'{attribute}="{path}?v={digest}"'
+
+for html in (root / 'web').glob('*.html'):
+    text = re.sub(r'\b(src|href)="(/[\w./-]+\.(?:js|css))(?:\?[^"]*)?"', versioned, html.read_text())
+    html.write_text(text)
+
+hashes = []
+for html in (root / 'web').glob('*.html'):
+    for attributes, script in re.findall(r'<script\b([^>]*)>(.*?)</script>', html.read_text(), re.S | re.I):
+        if not re.search(r'\bsrc\s*=', attributes, re.I) and script.strip():
+            hashes.append("'sha256-" + base64.b64encode(hashlib.sha256(script.encode()).digest()).decode() + "'")
+
+template = Path(os.environ.get('NGINX_TEMPLATE', root / 'infra/nginx.conf.template')).read_text()
+rendered = template.replace('@SCRIPT_HASHES@', ' '.join(hashes))
+# Collapse the gap an empty hash list leaves behind, so the policy reads cleanly.
+rendered = re.sub(r"(script-src 'self')\s+;", r'\1;', rendered)
+(root / 'default.conf.template').write_text(rendered)
+print(f'CSP script-src: {len(hashes)} inline hash(es)')

infra/lock_dependencies.sh

@@ -10,4 +10,4 @@ docker run --rm \
   --volume "$root:/src" \
   --workdir /src \
   python:3.12-slim \
-  sh -c 'python -m pip install --no-cache-dir --target /tmp/piptools pip==25.3 pip-tools==7.5.2 && PYTHONPATH=/tmp/piptools python -m piptools compile --generate-hashes --allow-unsafe --strip-extras --no-emit-index-url --output-file local/requirements.lock local/requirements.txt'
+  sh -c 'python -m pip install --no-cache-dir --target /tmp/piptools pip==25.3 pip-tools==7.5.2 && PYTHONPATH=/tmp/piptools python -m piptools compile --generate-hashes --allow-unsafe --strip-extras --no-emit-index-url --output-file infra/requirements.lock infra/requirements.txt'