validades dos modelos

backend/app/services/pesquisa_service.py

@@ -16,7 +16,7 @@ import pandas as pd
 from fastapi import HTTPException
 from joblib import load
 
-from app.core.elaboracao.core import _migrar_pacote_v1_para_v2
+from app.core.elaboracao.core import _migrar_pacote_v1_para_v2, normalizar_observacao_modelo
 from app.core.map_layers import add_bairros_layer, add_indice_marker, add_zoom_responsive_circle_markers
 from app.services import model_repository
 from app.services.serializers import sanitize_value
@@ -563,6 +563,7 @@ def _construir_resumo_modelo(caminho_modelo: Path) -> dict[str, Any]:
         "total_trabalhos": None,
         "endereco_referencia": None,
         "equacao": None,
+        "observacao_modelo": None,
         "r2": None,
         "tem_app": False,
         "mapa_disponivel": False,
@@ -608,6 +609,9 @@ def _construir_resumo_modelo(caminho_modelo: Path) -> dict[str, Any]:
     if resumo["equacao"] is None:
         resumo["equacao"] = _equacao_do_pacote(pacote)
 
+    if resumo["observacao_modelo"] is None:
+        resumo["observacao_modelo"] = normalizar_observacao_modelo(pacote.get("observacao_modelo"))
+
     if resumo["r2"] is None:
         resumo["r2"] = _r2_do_pacote(pacote)
 

frontend/src/components/PesquisaTab.jsx

@@ -8,6 +8,7 @@ import MapFrame from './MapFrame'
 import PlotFigure from './PlotFigure'
 import PesquisaAdminConfigPanel from './PesquisaAdminConfigPanel'
 import SectionBlock from './SectionBlock'
+import { getFaixaDataRecencyInfo } from '../modelRecency'
 
 const EMPTY_FILTERS = {
   nomeModelo: '',
@@ -192,16 +193,33 @@ function CompactHoverList({
   modalContent = null,
 }) {
   const rootRef = useRef(null)
+  const closePreviewTimeoutRef = useRef(null)
   const panelRef = useRef(null)
   const [previewOpen, setPreviewOpen] = useState(false)
   const [modalOpen, setModalOpen] = useState(false)
-  const [previewSide, setPreviewSide] = useState('left')
-  const [previewVertical, setPreviewVertical] = useState('down')
-  const [previewMaxHeight, setPreviewMaxHeight] = useState(160)
-  const [previewMaxWidth, setPreviewMaxWidth] = useState(560)
+  const [previewStyle, setPreviewStyle] = useState({})
   const inlinePreviewText = String(previewText || '').trim()
   const inlineModalText = String(modalText || '').trim()
 
+  function clearPreviewCloseTimeout() {
+    if (closePreviewTimeoutRef.current) {
+      window.clearTimeout(closePreviewTimeoutRef.current)
+      closePreviewTimeoutRef.current = null
+    }
+  }
+
+  function schedulePreviewClose() {
+    clearPreviewCloseTimeout()
+    closePreviewTimeoutRef.current = window.setTimeout(() => {
+      setPreviewOpen(false)
+    }, 80)
+  }
+
+  function openPreview() {
+    clearPreviewCloseTimeout()
+    setPreviewOpen(true)
+  }
+
   function updatePreviewLayout() {
     const bounds = rootRef.current?.getBoundingClientRect()
     const panel = panelRef.current
@@ -209,45 +227,89 @@ function CompactHoverList({
 
     const viewportWidth = window.innerWidth
     const viewportHeight = window.innerHeight
-    const gap = 8
+    const gap = 10
     const padding = 16
     const triggerCenter = bounds.left + (bounds.width / 2)
-    const viewportCenter = viewportWidth / 2
-    const triggerMiddleY = bounds.top + (bounds.height / 2)
-    const viewportMiddleY = viewportHeight / 2
-
-    const preferredSide = triggerCenter >= viewportCenter ? 'left' : 'right'
-    const preferredVertical = triggerMiddleY >= viewportMiddleY ? 'up' : 'down'
-
-    const availableLeft = Math.max(120, bounds.right - padding)
-    const availableRight = Math.max(120, viewportWidth - bounds.left - padding)
-    const availableAbove = Math.max(96, bounds.top - gap - padding)
-    const availableBelow = Math.max(96, viewportHeight - bounds.bottom - gap - padding)
+    const towardCenterSide = triggerCenter >= (viewportWidth / 2) ? 'left' : 'right'
+    const oppositeSide = towardCenterSide === 'left' ? 'right' : 'left'
+    const downwardSpace = viewportHeight - bounds.bottom - gap - padding
+    const upwardSpace = bounds.top - gap - padding
+    const preferredVertical = downwardSpace >= upwardSpace ? 'down' : 'up'
+    const oppositeVertical = preferredVertical === 'down' ? 'up' : 'down'
 
     const desiredWidth = Math.min(panel.scrollWidth || 560, 560)
-    const desiredHeight = Math.min(panel.scrollHeight || 160, 320)
+    const desiredHeight = Math.min(panel.scrollHeight || 220, 420)
 
-    let nextSide = preferredSide
-    if (preferredSide === 'left' && desiredWidth > availableLeft && availableRight > availableLeft) {
-      nextSide = 'right'
-    } else if (preferredSide === 'right' && desiredWidth > availableRight && availableLeft > availableRight) {
-      nextSide = 'left'
+    function clamp(value, min, max) {
+      if (max < min) return min
+      return Math.min(Math.max(value, min), max)
     }
 
-    let nextVertical = preferredVertical
-    if (preferredVertical === 'up' && desiredHeight > availableAbove && availableBelow > availableAbove) {
-      nextVertical = 'down'
-    } else if (preferredVertical === 'down' && desiredHeight > availableBelow && availableAbove > availableBelow) {
-      nextVertical = 'up'
+    function makeVerticalCandidate(side, vertical) {
+      const maxWidth = Math.max(160, viewportWidth - (padding * 2))
+      const width = Math.min(desiredWidth, maxWidth)
+      const maxHeight = Math.max(96, vertical === 'down' ? downwardSpace : upwardSpace)
+      const height = Math.min(desiredHeight, maxHeight)
+      const leftBase = side === 'left'
+        ? bounds.right - width
+        : bounds.left
+      const left = clamp(leftBase, padding, viewportWidth - padding - width)
+      const topBase = vertical === 'down'
+        ? bounds.bottom + gap
+        : bounds.top - gap - height
+      const top = clamp(topBase, padding, viewportHeight - padding - height)
+      return {
+        left,
+        top,
+        maxWidth,
+        maxHeight,
+        score: (Math.min(maxWidth, desiredWidth) / desiredWidth) + (Math.min(maxHeight, desiredHeight) / desiredHeight),
+      }
     }
 
-    const nextMaxWidth = nextSide === 'left' ? availableLeft : availableRight
-    const nextMaxHeight = nextVertical === 'up' ? availableAbove : availableBelow
+    function makeSideCandidate(side) {
+      const maxWidth = Math.max(180, side === 'right'
+        ? viewportWidth - bounds.right - gap - padding
+        : bounds.left - gap - padding)
+      const width = Math.min(desiredWidth, maxWidth)
+      const maxHeight = Math.max(120, viewportHeight - (padding * 2))
+      const height = Math.min(desiredHeight, maxHeight)
+      const leftBase = side === 'right'
+        ? bounds.right + gap
+        : bounds.left - gap - width
+      const left = clamp(leftBase, padding, viewportWidth - padding - width)
+      const top = clamp(bounds.top, padding, viewportHeight - padding - height)
+      return {
+        left,
+        top,
+        maxWidth,
+        maxHeight,
+        score: (Math.min(maxWidth, desiredWidth) / desiredWidth) + (Math.min(maxHeight, desiredHeight) / desiredHeight),
+      }
+    }
 
-    setPreviewSide(nextSide)
-    setPreviewVertical(nextVertical)
-    setPreviewMaxWidth(nextMaxWidth)
-    setPreviewMaxHeight(nextMaxHeight)
+    const candidates = [
+      makeVerticalCandidate(towardCenterSide, preferredVertical),
+      makeVerticalCandidate(towardCenterSide, oppositeVertical),
+      makeSideCandidate(towardCenterSide),
+      makeSideCandidate(oppositeSide),
+      makeVerticalCandidate(oppositeSide, preferredVertical),
+      makeVerticalCandidate(oppositeSide, oppositeVertical),
+    ]
+
+    const best = candidates.reduce((current, candidate) => {
+      if (!current || candidate.score > current.score) return candidate
+      return current
+    }, null)
+
+    if (!best) return
+
+    setPreviewStyle({
+      left: `${best.left}px`,
+      top: `${best.top}px`,
+      maxWidth: `${Math.max(160, best.maxWidth)}px`,
+      maxHeight: `${Math.max(96, best.maxHeight)}px`,
+    })
   }
 
   useEffect(() => {
@@ -268,6 +330,10 @@ function CompactHoverList({
     }
   }, [previewOpen])
 
+  useEffect(() => () => {
+    clearPreviewCloseTimeout()
+  }, [])
+
   useEffect(() => {
     if (!modalOpen) return undefined
 
@@ -296,15 +362,9 @@ function CompactHoverList({
       <span
         ref={rootRef}
         className={`pesquisa-card-popover-wrap${previewOpen ? ' is-open' : ''}`}
-        data-preview-side={previewSide}
-        data-preview-vertical={previewVertical}
-        onMouseEnter={() => {
-          setPreviewOpen(true)
-        }}
-        onMouseLeave={() => setPreviewOpen(false)}
-        onFocus={() => {
-          setPreviewOpen(true)
-        }}
+        onMouseEnter={() => openPreview()}
+        onMouseLeave={() => schedulePreviewClose()}
+        onFocus={() => openPreview()}
         onBlur={(event) => {
           if (!rootRef.current?.contains(event.relatedTarget)) {
             setPreviewOpen(false)
@@ -324,19 +384,23 @@ function CompactHoverList({
         >
           {buttonLabel}
         </button>
-        <span
-          ref={panelRef}
-          className="pesquisa-card-popover-panel"
-          role="tooltip"
-          aria-label={label}
-          style={{
-            maxWidth: `${Math.max(120, previewMaxWidth)}px`,
-            maxHeight: `${Math.max(96, previewMaxHeight)}px`,
-          }}
-        >
-          <span className="pesquisa-card-popover-preview">{previewContent || inlinePreviewText || inlineModalText}</span>
-        </span>
       </span>
+      {previewOpen && typeof document !== 'undefined'
+        ? createPortal(
+          <span
+            ref={panelRef}
+            className="pesquisa-card-popover-panel is-floating"
+            role="tooltip"
+            aria-label={label}
+            style={previewStyle}
+            onMouseEnter={() => openPreview()}
+            onMouseLeave={() => schedulePreviewClose()}
+          >
+            <span className="pesquisa-card-popover-preview">{previewContent || inlinePreviewText || inlineModalText}</span>
+          </span>,
+          document.body,
+        )
+        : null}
       {modalOpen && typeof document !== 'undefined'
         ? createPortal(
           <div
@@ -1274,13 +1338,21 @@ export default function PesquisaTab({ sessionId, onUsarModeloEmAvaliacao = null
           <div className="pesquisa-card-grid">
             {result.modelos.map((modelo) => {
               const selecionado = selectedIds.includes(modelo.id)
+              const faixaDataRecency = getFaixaDataRecencyInfo(modelo.faixa_data)
               const finalidadesText = uppercaseListText(modelo.finalidades || [])
               const bairrosText = uppercaseListText(modelo.bairros || [])
               const variaveisText = buildVariablesDisplay(modelo)
+              const observacaoText = String(modelo.observacao_modelo || '').trim()
+              const cardClassName = [
+                'pesquisa-card',
+                selecionado ? 'is-selected' : '',
+              ].filter(Boolean).join(' ')
+
               return (
-                <article key={modelo.id} className={`pesquisa-card${selecionado ? ' is-selected' : ''}`}>
+                <article key={modelo.id} className={cardClassName}>
                   <div className="pesquisa-card-top">
                     <h4 className="pesquisa-card-title">{modelo.nome_modelo || modelo.arquivo}</h4>
+                    <div className="pesquisa-card-divider" aria-hidden="true" />
                     <div className="pesquisa-card-actions">
                       <button
                         type="button"
@@ -1303,7 +1375,14 @@ export default function PesquisaTab({ sessionId, onUsarModeloEmAvaliacao = null
                         <div><strong>Dados:</strong> {formatCount(modelo.total_dados)}</div>
                         <div><strong>Faixa area:</strong> {formatRange(modelo.faixa_area)}</div>
                         <div><strong>Faixa RH:</strong> {formatRange(modelo.faixa_rh)}</div>
-                        <div><strong>Faixa data:</strong> {formatRange(modelo.faixa_data)}</div>
+                        <div>
+                          <strong>Faixa data:</strong> {formatRange(modelo.faixa_data)}
+                          {faixaDataRecency.label ? (
+                            <span className={`pesquisa-card-faixa-data-badge is-aged-${faixaDataRecency.tone}`}>
+                              {faixaDataRecency.label}
+                            </span>
+                          ) : null}
+                        </div>
                       </div>
                     </div>
                     <div className="pesquisa-card-meta-actions">
@@ -1327,6 +1406,12 @@ export default function PesquisaTab({ sessionId, onUsarModeloEmAvaliacao = null
                         previewContent={buildVariablesContent(variaveisText)}
                         modalContent={buildVariablesContent(variaveisText)}
                       />
+                      <CompactHoverList
+                        label="Observação"
+                        buttonLabel="Obs"
+                        previewText={observacaoText}
+                        modalText={observacaoText}
+                      />
                     </div>
                   </div>
 

frontend/src/components/RepositorioTab.jsx

@@ -5,6 +5,7 @@ import EquationFormatsPanel from './EquationFormatsPanel'
 import LoadingOverlay from './LoadingOverlay'
 import MapFrame from './MapFrame'
 import PlotFigure from './PlotFigure'
+import { getFaixaDataRecencyInfo } from '../modelRecency'
 
 const REPO_INNER_TABS = [
   { key: 'mapa', label: 'Mapa' },
@@ -395,8 +396,6 @@ export default function RepositorioTab({ authUser, sessionId }) {
                 <th>Autor</th>
                 <th>Período</th>
                 <th>Dados</th>
-                <th>APP</th>
-                <th>Status</th>
                 <th className="repo-col-open">Abrir</th>
                 {isAdmin ? <th className="repo-col-delete">Excluir</th> : null}
               </tr>
@@ -405,16 +404,24 @@ export default function RepositorioTab({ authUser, sessionId }) {
               {modelos.map((item) => {
                 const key = String(item.id)
                 const emConfirmacao = confirmDeleteId === key
+                const periodoRecency = getFaixaDataRecencyInfo(item.periodo_dados)
                 return (
                   <tr key={key}>
                     <td>{item.nome_modelo || item.arquivo || key}</td>
                     <td>{item.tipo_imovel || '-'}</td>
                     <td>{item.finalidade || '-'}</td>
                     <td>{item.autor || '-'}</td>
-                    <td>{item.periodo_dados?.label || '-'}</td>
+                    <td>
+                      <span className="repo-periodo-wrap">
+                        <span>{item.periodo_dados?.label || '-'}</span>
+                        {periodoRecency.label ? (
+                          <span className={`pesquisa-card-faixa-data-badge is-aged-${periodoRecency.tone}`}>
+                            {periodoRecency.label}
+                          </span>
+                        ) : null}
+                      </span>
+                    </td>
                     <td>{item.total_dados ?? '-'}</td>
-                    <td>{item.tem_app ? 'Sim' : 'Não'}</td>
-                    <td>{item.status || '-'}</td>
                     <td className="repo-col-open">
                       <button
                         type="button"
@@ -466,7 +473,7 @@ export default function RepositorioTab({ authUser, sessionId }) {
               })}
               {!modelos.length ? (
                 <tr>
-                  <td colSpan={isAdmin ? 10 : 9}>
+                  <td colSpan={isAdmin ? 8 : 7}>
                     {loading ? 'Carregando modelos...' : 'Nenhum modelo encontrado no repositório.'}
                   </td>
                 </tr>

frontend/src/modelRecency.js

@@ -0,0 +1,55 @@
+function parseIsoDateOnly(value) {
+  const text = String(value ?? '').trim()
+  const isoMatch = text.match(/^(\d{4})-(\d{2})-(\d{2})$/)
+  if (!isoMatch) return null
+
+  const year = Number(isoMatch[1])
+  const month = Number(isoMatch[2])
+  const day = Number(isoMatch[3])
+  const date = new Date(Date.UTC(year, month - 1, day))
+
+  if (
+    Number.isNaN(date.getTime())
+    || date.getUTCFullYear() !== year
+    || date.getUTCMonth() !== month - 1
+    || date.getUTCDate() !== day
+  ) {
+    return null
+  }
+
+  return date
+}
+
+function subtractMonthsUtc(date, months) {
+  const year = date.getUTCFullYear()
+  const month = date.getUTCMonth()
+  const day = date.getUTCDate()
+  const base = new Date(Date.UTC(year, month - months, 1))
+  const lastDayOfTargetMonth = new Date(
+    Date.UTC(base.getUTCFullYear(), base.getUTCMonth() + 1, 0),
+  ).getUTCDate()
+
+  base.setUTCDate(Math.min(day, lastDayOfTargetMonth))
+  return base
+}
+
+export function getFaixaDataRecencyInfo(periodo) {
+  const dataFinal = parseIsoDateOnly(periodo?.max ?? periodo?.data_final)
+  if (!dataFinal) return { tone: '', label: '' }
+
+  const now = new Date()
+  const hojeUtc = new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()))
+  if (dataFinal > hojeUtc) return { tone: '', label: '' }
+
+  if (dataFinal <= subtractMonthsUtc(hojeUtc, 24)) {
+    return { tone: '2y', label: '>= 2 anos' }
+  }
+  if (dataFinal <= subtractMonthsUtc(hojeUtc, 12)) {
+    return { tone: '1y', label: '>= 1 ano' }
+  }
+  if (dataFinal <= subtractMonthsUtc(hojeUtc, 6)) {
+    return { tone: '6m', label: '>= 6 meses' }
+  }
+
+  return { tone: '', label: '' }
+}

frontend/src/styles.css

@@ -493,6 +493,13 @@ textarea {
   color: #48627a;
 }
 
+.repo-periodo-wrap {
+  display: inline-flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
 .repo-col-open,
 .repo-col-delete {
   width: 68px;
@@ -1929,9 +1936,14 @@ button.pesquisa-coluna-remove:hover {
 }
 
 .pesquisa-card {
-  border: 1px solid #dbe7f2;
+  --pesquisa-card-bg-start: #ffffff;
+  --pesquisa-card-bg-end: #fcfdff;
+  --pesquisa-card-border: #dbe7f2;
+  --pesquisa-card-border-hover: #c8dced;
+  --pesquisa-card-divider: #e7eef5;
+  border: 1px solid var(--pesquisa-card-border);
   border-radius: 14px;
-  background: linear-gradient(180deg, #ffffff 0%, #fcfdff 100%);
+  background: linear-gradient(180deg, var(--pesquisa-card-bg-start) 0%, var(--pesquisa-card-bg-end) 100%);
   padding: 12px;
   display: flex;
   flex-direction: column;
@@ -1951,17 +1963,16 @@ button.pesquisa-coluna-remove:hover {
 .pesquisa-card:focus-within {
   z-index: 3;
   transform: translateY(-1px);
-  border-color: #c8dced;
+  border-color: var(--pesquisa-card-border-hover);
   box-shadow:
     0 10px 22px rgba(26, 43, 61, 0.08),
     inset 0 0 0 1px rgba(255, 255, 255, 0.82);
 }
 
 .pesquisa-card.is-selected {
-  border-color: #ffbe77;
   box-shadow:
     0 10px 24px rgba(255, 163, 63, 0.17),
-    0 0 0 1px rgba(255, 163, 63, 0.28);
+    0 0 0 2px rgba(255, 163, 63, 0.18);
 }
 
 .pesquisa-card-top {
@@ -1981,6 +1992,12 @@ button.pesquisa-coluna-remove:hover {
   overflow-wrap: anywhere;
 }
 
+.pesquisa-card-divider {
+  width: 100%;
+  height: 1px;
+  background: var(--pesquisa-card-divider);
+}
+
 .pesquisa-card-actions {
   display: grid;
   grid-template-columns: repeat(3, minmax(0, 1fr));
@@ -1990,7 +2007,7 @@ button.pesquisa-coluna-remove:hover {
 
 .pesquisa-card-meta-actions {
   display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-template-columns: repeat(4, minmax(0, 1fr));
   gap: 8px;
   min-width: 0;
   margin-top: auto;
@@ -2058,7 +2075,7 @@ button.pesquisa-coluna-remove:hover {
   gap: 9px;
   min-width: 0;
   flex: 1 1 auto;
-  border-top: 1px solid #e7eef5;
+  border-top: 1px solid var(--pesquisa-card-divider);
   padding-top: 9px;
 }
 
@@ -2088,6 +2105,40 @@ button.pesquisa-coluna-remove:hover {
   line-height: 1.34;
 }
 
+.pesquisa-card-faixa-data-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-left: 8px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid transparent;
+  font-size: 0.72rem;
+  font-weight: 800;
+  line-height: 1.2;
+  letter-spacing: 0.01em;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
+.pesquisa-card-faixa-data-badge.is-aged-6m {
+  background: #fff0b8;
+  border-color: #d9bd72;
+  color: #705800;
+}
+
+.pesquisa-card-faixa-data-badge.is-aged-1y {
+  background: #ffd7a8;
+  border-color: #d5a16a;
+  color: #754100;
+}
+
+.pesquisa-card-faixa-data-badge.is-aged-2y {
+  background: #f4c0c0;
+  border-color: #d69292;
+  color: #7a2f2f;
+}
+
 .pesquisa-card-popover-row {
   display: flex;
   align-items: flex-start;
@@ -2151,12 +2202,11 @@ button.pesquisa-coluna-remove:hover {
 }
 
 .pesquisa-card-popover-panel {
-  position: absolute;
-  top: calc(100% + 8px);
-  right: 0;
+  position: fixed;
   display: block;
   width: min(560px, calc(100vw - 56px));
   max-height: 160px;
+  overflow: auto;
   padding: 10px 12px;
   border: 1px solid #000;
   border-radius: 10px;
@@ -2166,39 +2216,15 @@ button.pesquisa-coluna-remove:hover {
   opacity: 0;
   visibility: hidden;
   transform: translateY(6px);
-  pointer-events: none;
+  pointer-events: auto;
   transition: opacity 0.16s ease, transform 0.16s ease, visibility 0.16s ease;
+  z-index: 1600;
 }
 
-.pesquisa-card-popover-wrap[data-preview-vertical='up'] .pesquisa-card-popover-panel {
-  top: auto;
-  bottom: calc(100% + 8px);
-  transform: translateY(-6px);
-}
-
-.pesquisa-card-popover-wrap[data-preview-vertical='down'] .pesquisa-card-popover-panel {
-  top: calc(100% + 8px);
-  bottom: auto;
-  transform: translateY(6px);
-}
-
-.pesquisa-card-popover-wrap[data-preview-side='right'] .pesquisa-card-popover-panel {
-  left: 0;
-  right: auto;
-}
-
-.pesquisa-card-popover-wrap[data-preview-side='left'] .pesquisa-card-popover-panel {
-  right: 0;
-  left: auto;
-}
-
-.pesquisa-card-popover-wrap:hover .pesquisa-card-popover-panel,
-.pesquisa-card-popover-wrap:focus-within .pesquisa-card-popover-panel,
-.pesquisa-card-popover-wrap.is-open .pesquisa-card-popover-panel {
+.pesquisa-card-popover-panel.is-floating {
   opacity: 1;
   visibility: visible;
   transform: translateY(0);
-  pointer-events: auto;
 }
 
 .pesquisa-card-popover-preview {