# Arsenal Nexora V2 · Fase 5 — Opciones inteligentes por item

## Objetivo

Sacar los valores raw del flujo normal de AdminCP y convertir las definiciones entregadas por el servidor en controles asistidos. El administrador selecciona un codigo `Section:Index` y Arsenal limita las opciones a lo que las fuentes tecnicas declaran para ese item.

Esta fase no agrega dependencias al catalogo publico. `item-options.json` y la logica adicional se cargan solamente al editar Arsenal en AdminCP o al validar un guardado.

## Fuentes integradas

El catalogo normalizado `includes/plugins/itemshop/data/item-options.json` se genera a partir de:

- `Ancient_Items.xml`: relacion `Type:Index` con variantes Ancient A/B.
- `Ancient_Type.xml`: nombres de las familias Ancient.
- `Harmony_Attack.xml`: opciones Harmony para armas Section 0-4.
- `Harmony_Staffs.xml`: opciones Harmony para bastones Section 5.
- `Harmony_Defensive.xml`: opciones Harmony para escudos y set Section 6-11.
- `Socket_Options.xml`: semillas, slot libre/sin slot y bonus Socket.
- `Items.xml` / `item-catalog.json`: perfil Excellent, compatibilidad Socket y flag Level380.
- `Item.txt` / `item-catalog.json`: Skill y disponibilidad de opcion adicional.

El build actual contiene 474 codigos con Ancient, 217 niveles Harmony distribuidos en 26 grupos, 29 definiciones Socket (27 semillas/opciones + los sentinelas 254/255) y 7 definiciones de bonus. El sentinela `No Bonus` (Index 50) no se ofrece como byte de bonus: las capturas reales confirman que sin bonus el byte 10 es `0x00`, por lo que quedan 6 bonus accionables. `Items.xml` marca 197 items Socket y 95 items Level380.

## AdminCP

El formulario ya no pide `Ancient raw` ni `Harmony raw` como entrada principal.

- Excellent muestra el perfil declarado por `Items.xml`. Para armas y armaduras/escudos se muestran los seis significados DbVersion 3. Los perfiles especiales 3/4/5 (alas/Fenrir) quedan identificados pero bloqueados porque las fuentes entregadas no definen la semantica de cada bit; Arsenal no inventa opciones.
- Skill se habilita solo si Item.txt declara un Skill para el codigo.
- Luck y opcion adicional se habilitan solo cuando Item.txt declara que el item admite opciones.
- Ancient solo lista variantes asociadas a ese `Section:Index`.
- Harmony selecciona automaticamente la familia Attack / Staffs / Defensive segun Section.
- Un item Socket reserva el byte compartido para Socket Bonus y fuerza Harmony a Ninguno.
- Socket expone cinco slots explicitos: `255` sin slot, `254` slot vacio o el Index de una opcion de `Socket_Options.xml` compatible con arma/set.
- Los slots Socket deben ser contiguos desde Slot 1.
- Socket Bonus requiere al menos un slot configurado.
- Opcion 380 solo puede activarse si `Items.xml` marca `Level380=True`.

El backend repite todas las validaciones. Manipular el HTML o enviar un POST manual no permite saltarse las restricciones del catalogo.

## Persistencia y migracion

Se agregan a `NEXORA_ITEMSHOP_ITEMS`:

- `option_380`
- `socket_bonus`
- `socket_option_1` ... `socket_option_5`

`socket_count` se conserva por compatibilidad y se recalcula desde los cinco slots al guardar. Al migrar una instalacion existente, un `socket_count` legacy se convierte en slots vacios `0xFE` contiguos y el resto queda `0xFF`.

Despues de aplicar el parche, ejecutar en Seasonal y Legacy:

`AdminCP -> Arsenal Nexora -> Configuracion -> Instalar / validar tablas`

El diagnostico `Motor de opciones inteligentes` debe quedar en verde.

## Bytes DbVersion 3

La Fase 5 conserva la codificacion de Index extendido confirmada en Fase 4 y agrega persistencia explicita para los bytes de opciones:

- byte 7: Excellent + tercer bit de opcion + bit alto del Index;
- byte 8: Ancient;
- byte 9: Section y flag 380;
- byte 10: Harmony o Socket Bonus segun el tipo de item;
- bytes 11-15: cinco slots Socket.

Las cuatro muestras HEX de Fase 4 siguen reproduciendose exactamente cuando no se seleccionan opciones nuevas.

## Decoder publico

`NexoraItemDecoder` ahora separa el flag 380 y distingue el byte compartido Harmony/Socket Bonus cuando el item contiene payload Socket. El perfil puede reportar `Opcion 380` y `Socket Bonus detectado` sin alterar el inventario.

## Regeneracion del catalogo de opciones

Si cambian los XML del Warehouse Editor:

```bash
php includes/plugins/itemshop/tools_build_option_catalog.php \
  /ruta/Ancient_Items.xml /ruta/Ancient_Type.xml \
  /ruta/Harmony_Attack.xml /ruta/Harmony_Defensive.xml \
  /ruta/Harmony_Staffs.xml /ruta/Socket_Options.xml
```

El JSON guarda SHA-256 de cada fuente para poder comprobar que la build corresponde a los archivos usados.

## Validacion ejecutada

- PHP lint de los archivos modificados.
- `node --check` del JavaScript AdminCP.
- Regeneracion reproducible de `item-options.json` desde los seis XML entregados.
- 474 codigos Ancient, 29 definiciones Socket y 7 definiciones de bonus detectadas; 27 opciones Socket y 6 bonus quedan accionables tras excluir sentinelas de interfaz.
- Encoder Fase 4 verificado contra los cuatro HEX reales del Warehouse Editor.
- Pruebas de byte 380, Ancient, Harmony, Socket Bonus y slots explicitos.
- Decoder probado para Index extendido, 380, Harmony y payload Socket.
- Validacion backend probada para rechazar gaps Socket y 380 en items no compatibles.
- La funcion `purchase()` se mantiene sin cambios respecto a Fase 4.

## Frontera de validacion

Los XML definen que opciones existen y a que items/familias pertenecen. Las capturas suministradas confirmaron de forma exacta el Index extendido y los items base sin opciones. Para 380, Ancient, Harmony y semillas/bonus Socket no se suministro aun una captura HEX de cada opcion activa. Por eso la build mantiene las altas nuevas ocultas por defecto y se recomienda una entrega controlada por familia antes de publicar configuraciones masivas.
