Uso de IA · Pedidos y ventas

    @Tool(name = "obtener_pedido",
          description = "Devuelve un pedido por su identificador UUID: cliente, canal, líneas, totales y estatus.")
    public String obtenerPedido(
            @ToolParam(description = "Identificador UUID del pedido", required = true) String pedidoId) {
        RegistroHerramientasUsadas.registrar("obtener_pedido");
        UUID id = identificador(pedidoId);
        if (id == null) {
            return "El identificador del pedido no es válido.";
        }
        return lectura(RUTA_BASE + "/pedidos/" + id, "No encontré ese pedido.");
    }

    @Tool(name = "preparar_pedido_borrador",
          description = "Prepara un pedido de venta en borrador. NO lo guarda: devuelve un resumen y un accion_id. "
                  + "El usuario debe confirmarlo en la aplicación antes de que se guarde. Úsala solo cuando el usuario pida crear un pedido.")
    public String prepararPedidoBorrador(
            @ToolParam(description = "Identificador UUID del cliente", required = true) String clienteId,
            @ToolParam(description = "Canal de venta: WEB, TIENDA o TELEFONO", required = true) String canal,
            @ToolParam(description = "Moneda ISO, por ejemplo MXN", required = true) String moneda,
            @ToolParam(description = "Tasa de IVA: IVA_GENERAL, IVA_FRONTERIZO o IVA_EXENTO", required = true) String tasaIva,
            @ToolParam(description = "Identificador UUID del producto", required = true) String productoId,
            @ToolParam(description = "Descripción de la línea. Puede ir vacía.", required = false) String descripcion,
            @ToolParam(description = "Cantidad entera mayor a cero", required = true) int cantidad,
            @ToolParam(description = "Precio unitario en la moneda del pedido", required = true) String precioUnitario) {
        RegistroHerramientasUsadas.registrar("preparar_pedido_borrador");
        if (acciones == null) {
            return "La preparación de pedidos no está disponible en este momento.";
        }
        if (cantidad <= 0) {
            return "La cantidad debe ser mayor a cero.";
        }
        Map<String, Object> linea = new LinkedHashMap<>();
        linea.put("productoId", productoId.trim());
        linea.put("descripcion", descripcion == null || descripcion.isBlank() ? "Artículo" : descripcion.trim());
        linea.put("cantidad", cantidad);
        linea.put("precioUnitario", precioUnitario.trim());
        Map<String, Object> cuerpo = new LinkedHashMap<>();
        cuerpo.put("clienteId", clienteId.trim());
        cuerpo.put("canal", canal.trim().toUpperCase());
        cuerpo.put("moneda", moneda.trim().toUpperCase());
        cuerpo.put("tasaIva", tasaIva.trim().toUpperCase());
        cuerpo.put("lineas", List.of(linea));
        String payload = aJson(cuerpo);
        String resumen = "Pedido en borrador para el cliente " + clienteId.trim() + ": " + cantidad + " × "
                + productoId.trim() + " a " + precioUnitario.trim() + " " + moneda.trim().toUpperCase()
                + " (" + canal.trim().toUpperCase() + ", " + tasaIva.trim().toUpperCase() + ")";
        AccionPendiente accion = acciones.preparar(usuarioActual(), AccionesPendientes.TIPO_PEDIDO_BORRADOR,
                payload, resumen);
        return FiltroDatosSensibles.redactar("Pedido preparado, no guardado. " + resumen
                + ". accion_id: " + accion.id() + ". Vence en 10 minutos; el usuario debe confirmarlo en la aplicación.")
                .texto();
    }

    static final String RUTA_BASE = "/pedidos-ventas-ms/v1";