QA Metric Exposure in MccsSubarray
===================================

Overview
--------

This document describes the design for exposing Quality Assurance (QA) metrics from the ``MccsSubarray`` Tango device.

The interface is defined under::

    MccsSubarray.qualityAssuranceMetrics

Purpose
-------

The QA metrics interface is intended to:

- Expose QA state for all beams within a subarray
- Enable external systems to monitor beam QA in a single place via event-driven updates
- Evolve with versioned SCHEMA.


Core Concept
------------

The interface exposes a hierarchical view of QA metrics:

- **Subarray level**
  - Aggregated metrics across all beams
- **Beam level**
  - Aggregated metrics across apertures
- **Aperture level**
  - Fine-grained QA metrics per aperture

The initial metric supported is:

- ``is_beam_locked`` – indicates whether pointing delays are being updated in a timely and consistent manner


Data Model
----------

Top-Level Structure
~~~~~~~~~~~~~~~~~~~

.. code-block:: text

    {
      "subarray_beams": {
        "<subarray_beam_id>": {
          "apertures": {
            "<aperture_id>": {
              "is_beam_locked": bool,
              "<metric_name>": value
            }
          },
          "is_beam_locked": bool
        }
      },
      "beam_locked_percent": float
    }


Field Definitions
-----------------

subarray_beams
~~~~~~~~~~~~~~~

A dictionary keyed by ``subarray_beam_id``.

Each entry represents a beam within the subarray and contains:

- A set of aperture-level QA metrics
- A derived beam-level ``is_beam_locked`` state


subarray_beams.<beam_id>.apertures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Dictionary keyed by ``aperture_id`` (e.g. ``AP001.01``). 

This is aligned with the allocation and configuration SCHEMA.


subarray_beams.<beam_id>.is_beam_locked
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A **derived boolean metric** representing the aggregated lock state of the beam.

This value is computed from aperture-level ``is_beam_locked`` states.

It provides a simplified view for higher-level consumers that do not require aperture-level granularity.


beam_locked_percent
~~~~~~~~~~~~~~~~~~~

A **derived subarray-level metric** representing the percentage of beams that are currently locked.

This is intended for:

- Dashboard summarisation
- Alerting thresholds
- High-level system health monitoring


Example
-------

.. code-block:: text

    {
      "subarray_beams": {
        "1": {
          "apertures": {
            "AP001.01": {
              "is_beam_locked": true
            },
            "AP002.01": {
              "is_beam_locked": false
            }
          },
          "is_beam_locked": false
        },
        "2": {
          "apertures": {
            "AP003.01": {
              "is_beam_locked": false
            }
          },
          "is_beam_locked": false
        }
      },
      "beam_locked_percent": 0.0
    }