---
date: 2026-04-20
session_type: code_review_and_refactor
scope: modulo_fichas_inventario
analyst: kimi-code-cli
branches_affected:
  - main
---

# Reporte de Sesión: Análisis y Correcciones — Módulo Fichas de Inventario

## Resumen Ejecutivo

Sesión de análisis profundo del módulo de gestión de fichas de inventario, enfocada en las secciones 0, 1 y 2. Se identificaron incoherencias, malas prácticas y bugs. Se aplicaron correcciones mínimas y se extrajo un trait reutilizable para la validación de estado editable en todas las actions del módulo.

**Estado final:** 346 tests pasando, 0 fallos. Código pusheado a `origin/main`.

---

## 1. Correcciones Aplicadas

### Sección 0 — Cabecera / Código Catastral

| Archivo | Cambio |
|---|---|
| `resources/js/pages/fichas-inventario/components/sections/Section0.tsx` | Corregidas las claves de errores de validación (`errors['inventario.codigo_zona']` → `errors['codigo_zona']`, etc.) para que los `<InputError>` funcionen correctamente. |
| `app/Actions/FichaInventario/SaveSeccion0Action.php` | Agregada validación de estado editable: solo permite guardar si `estado === borrador \|\| observado`. |
| `app/Models/Inventario.php` | Corregido `getCodigoCatastralAttribute`: ahora omite el guion final cuando `codigo_sublote` es `null` (usando `array_filter(..., fn ($v) => $v !== null)`). |
| `app/Models/FichaRegistro.php` | Mismo fix del accessor `getCodigoCatastralAttribute` para `codigo_signo` nullable. |

### Sección 1 — Identificación del Bien Inmueble

| Archivo | Cambio |
|---|---|
| `app/Actions/FichaInventario/SaveSeccion1Action.php` | Agregada validación de estado editable (mismo patrón que Sección 0). |
| `app/Models/InvSeccion1.php` | Reemplazado `protected $guarded = []` por `$fillable` explícito con los 6 campos permitidos. |

### Sección 2 — Georreferenciación por Coordenadas

- **No se aplicaron correcciones** en esta sesión. Se identificaron dos hallazgos menores para futura sesión (ver sección 3).

---

## 2. Refactorización Global: Trait `FichaEditable`

### Motivación

Todas las actions de guardado (Secciones 0–19, anexos y filas 16.1) repetían la misma lógica de autorización: permiso `fichas.inventario.manage` + estado editable (`borrador` u `observado`). Esto era código duplicado en ~25 archivos.

### Implementación

**Nuevo archivo:** `app/Actions/FichaInventario/Concerns/FichaEditable.php`

```php
<?php

namespace App\Actions\FichaInventario\Concerns;

use App\Enums\InventarioEstado;
use App\Models\Inventario;
use Lorisleiva\Actions\ActionRequest;

trait FichaEditable
{
    protected function fichaIsEditable(ActionRequest $request): bool
    {
        $inventario = $request->route('inventario');

        if (! $inventario instanceof Inventario) {
            return false;
        }

        return $inventario->estado === InventarioEstado::Borrador
            || $inventario->estado === InventarioEstado::Observado;
    }
}
```

### Aplicación

El trait fue aplicado a **25 actions** del módulo:

- `SaveSeccion0Action` → `SaveSeccion19Action`
- `SaveSeccion161FilasAction`
- `SaveSeccionAnexosAction`
- `Seccion161SyncFilasAction`

Cada action ahora tiene:

```php
use AsAction;
use FichaEditable;

public function authorize(ActionRequest $request): bool
{
    return $request->user()?->can('fichas.inventario.manage')
        && $this->fichaIsEditable($request);
}
```

---

## 3. Hallazgos Pendientes para Futuras Sesiones

### Sección 2 (Georreferenciación)

- `app/Models/InvSeccion2.php` usa `protected $guarded = []` (debería ser `$fillable` explícito).
- `Section2.tsx`: el input `readOnly` de `zona_utm` muestra la constante hardcodeada `DEFAULT_ZONA_UTM` en lugar de `formData.zona_utm`. Si el backend guarda otro valor, no se reflejaría al recargar.

### Arquitectura General

- **`FichaInventarioController::edit()`** carga **todas** las relaciones de las 19 secciones + archivos, sin importar qué sección se está visualizando. Esto es ineficiente; se debería cargar solo la relación activa + datos mínimos para completitud.
- **`sectionCompletionResults()`** usa `new \ReflectionMethod` en cada iteración del loop (1–19). Funciona pero genera overhead innecesario en cada carga del formulario.
- **Duplicación de definiciones de pasos:** los títulos y labels de secciones existen en 3 lugares:
  1. `resources/js/pages/fichas-inventario/lib/helpers.ts` (`stepDefinitions`)
  2. `resources/js/layouts/inventory-form-layout.tsx` (`STEP_DEFINITIONS`)
  3. `resources/js/pages/fichas-inventario/edit.tsx` (`getSectionTitle`)
- **No existen Policies** dedicadas al módulo de inventario. La autorización se maneja únicamente via middleware de permisos de Spatie (`permission:fichas.inventario.manage`).
- **`Inventario.php`** tiene la constante `DEFAULT_ZONA_UTM` sin uso en ningún lado.
- **Estado `edited` en pasos:** el tipo `InventoryStepVisualStatus` incluye `'edited'`, pero el layout solo renderiza `complete` / `incomplete` / `pending`. El estado intermedio no está implementado.

### Patrón de Errores Validado

- **Toast-only:** todas las secciones usan `useSectionForm` que muestra errores de validación via `toast.error()` de Sonner. No se debe agregar `<InputError>` por campo en nuevas secciones a menos que se decida cambiar el patrón global.

---

## 4. Métricas de la Sesión

| Métrica | Valor |
|---|---|
| Tests ejecutados | 346 |
| Tests pasados | 346 (100%) |
| Assertions | 1488 |
| Archivos modificados | 25 |
| Archivos creados | 1 (trait) |
| Commits generados | 3 |

### Commits de la sesión

1. `580e882` — `fix(inventario-seccion-0): corrige errores de validacion frontend, bloqueo de estado no editable y codigo catastral con guion final`
2. `33d4a57` — `fix(inventario-seccion-1): bloquea edicion en estados no editables y reemplaza guarded por fillable`
3. `6c01a5e` — `refactor(inventario): extrae validacion de estado editable al trait FichaEditable y aplica a todas las secciones (0-19, anexos, 161)`

---

## 5. Notas para Continuación

- **Siguiente sección recomendada:** Sección 2 (aplicar `$fillable` en `InvSeccion2` y corregir input de `zona_utm`) o Sección 3 (Regimen de Propiedad).
- **Si se edita desde otro equipo:** hacer `git pull origin main` para obtener el trait `FichaEditable` y las correcciones de las Secciones 0 y 1.
- **Regla de oro para nuevas actions:** siempre usar `use FichaEditable;` y delegar la validación de estado a `$this->fichaIsEditable($request)`.