feat(spp_hazard): add severity_numeric bridge and document breaking changes

Softens the downstream impact of the severity -> CAP vocabulary migration
(re-land from #76):

- add a stored, computed severity_numeric (5=extreme .. 1=unknown, 0=unset)
  on spp.hazard.incident so downstream ordering/threshold logic can consume
  a numeric scale without resolving CAP vocabulary codes (mirrors the
  spp_drims incident-area mapping).
- document the breaking changes in the changelog: the severity /
  severity_override removal+rename, the new spp_vocabulary dependency, and
  the model-level category_id / start_date required relaxation.

Author: kneckinator

spp_hazard/README.rst

@@ -1189,11 +1189,29 @@ Changelog
 19.0.2.1.0
 ~~~~~~~~~~
 
+- **BREAKING**: the 1-5 ``severity`` Selection on
+  ``spp.hazard.incident`` and ``severity_override`` on
+  ``spp.hazard.incident.area`` are removed and replaced by
+  ``severity_id`` / ``severity_override_id`` (Many2one to
+  ``spp.vocabulary.code`` on the CAP severity namespace). Modules that
+  extend these models must migrate: views that reference
+  ``<field name="severity">`` / ``severity_override``, code that reads
+  ``record.severity``, records created with ``severity="…"``, and any
+  ``fields_to_log`` entries or domains naming the old fields. Read
+  ``severity_numeric`` (below) where a numeric scale is needed.
+- **BREAKING**: ``spp_hazard`` now depends on ``spp_vocabulary``.
+- **BREAKING**: ``category_id`` and ``start_date`` are no longer
+  ``required`` at the model level (they remain required in the incident
+  form view) so alert ingestion can create incidents that lack them.
 - feat: severity is now a CAP v1.2 vocabulary code (``severity_id``,
   ``severity_override_id`` on incident areas) instead of a hardcoded 1-5
   Selection; adds CAP urgency/certainty/message-type/event fields, alert
   ingestion (``create_incident_from_alert``), and incident ``uuid``
   (re-land from #76).
+- feat: ``spp.hazard.incident`` exposes a stored ``severity_numeric``
+  (5=extreme, 4=severe, 3=moderate, 2=minor, 1=unknown, 0=unset) so
+  downstream ordering and threshold logic can consume a numeric scale
+  without resolving CAP vocabulary codes.
 - feat: migration backfills legacy 1-5 severity values onto the
   vocabulary fields when upgrading from 19.0.2.0.x (1→minor, 2→moderate,
   3→severe, 4→severe, 5→extreme); existing values are never overwritten

spp_hazard/models/hazard_incident.py

@@ -18,6 +18,17 @@
 CAP_CERTAINTY_NS = "urn:oasis:names:tc:cap:certainty"
 CAP_MSG_TYPE_NS = "urn:oasis:names:tc:cap:msg-type"
 
+# CAP severity codes mapped to a 1-5 numeric scale (higher = more severe) for
+# ordering and threshold logic; 0 means no severity is set. Downstream modules
+# should read the stored ``severity_numeric`` field instead of resolving codes.
+CAP_SEVERITY_NUMERIC = {
+    "extreme": 5,
+    "severe": 4,
+    "moderate": 3,
+    "minor": 2,
+    "unknown": 1,
+}
+
 
 def _parse_datetime_string(value):
     """Parse a datetime string in either ISO 8601 or Odoo format.
@@ -109,6 +120,14 @@ class HazardIncident(models.Model):
         domain=f"[('namespace_uri', '=', '{CAP_SEVERITY_NS}')]",
         help="Overall magnitude/severity of the incident (CAP vocabulary)",
     )
+    severity_numeric = fields.Integer(
+        string="Severity (numeric)",
+        compute="_compute_severity_numeric",
+        store=True,
+        help="CAP severity mapped to a 1-5 scale (5=extreme, 4=severe, "
+        "3=moderate, 2=minor, 1=unknown; 0=unset) so downstream ordering and "
+        "threshold logic need not resolve vocabulary codes.",
+    )
 
     # CAP (Common Alerting Protocol) fields
     cap_urgency_id = fields.Many2one(
@@ -230,6 +249,12 @@ def _compute_is_ongoing(self):
                 "recovery",
             )
 
+    @api.depends("severity_id")
+    def _compute_severity_numeric(self):
+        """Map the CAP severity code to a 1-5 numeric scale for ordering."""
+        for rec in self:
+            rec.severity_numeric = CAP_SEVERITY_NUMERIC.get(rec.severity_id.code, 0)
+
     @api.depends("area_ids", "incident_area_ids.area_id")
     def _compute_area_count(self):
         """Compute the number of affected areas from both M2M and detail records."""

spp_hazard/readme/HISTORY.md

@@ -1,6 +1,10 @@
 ### 19.0.2.1.0
 
+- **BREAKING**: the 1-5 `severity` Selection on `spp.hazard.incident` and `severity_override` on `spp.hazard.incident.area` are removed and replaced by `severity_id` / `severity_override_id` (Many2one to `spp.vocabulary.code` on the CAP severity namespace). Modules that extend these models must migrate: views that reference `<field name="severity">` / `severity_override`, code that reads `record.severity`, records created with `severity="…"`, and any `fields_to_log` entries or domains naming the old fields. Read `severity_numeric` (below) where a numeric scale is needed.
+- **BREAKING**: `spp_hazard` now depends on `spp_vocabulary`.
+- **BREAKING**: `category_id` and `start_date` are no longer `required` at the model level (they remain required in the incident form view) so alert ingestion can create incidents that lack them.
 - feat: severity is now a CAP v1.2 vocabulary code (`severity_id`, `severity_override_id` on incident areas) instead of a hardcoded 1-5 Selection; adds CAP urgency/certainty/message-type/event fields, alert ingestion (`create_incident_from_alert`), and incident `uuid` (re-land from #76).
+- feat: `spp.hazard.incident` exposes a stored `severity_numeric` (5=extreme, 4=severe, 3=moderate, 2=minor, 1=unknown, 0=unset) so downstream ordering and threshold logic can consume a numeric scale without resolving CAP vocabulary codes.
 - feat: migration backfills legacy 1-5 severity values onto the vocabulary fields when upgrading from 19.0.2.0.x (1→minor, 2→moderate, 3→severe, 4→severe, 5→extreme); existing values are never overwritten and legacy columns are kept.
 - fix: demo incident-area records now set `severity_override_id` vocabulary refs (the removed `severity_override` field broke demo installs).
 

spp_hazard/static/description/index.html

@@ -2456,11 +2456,29 @@ <h2><a class="toc-backref" href="#toc-entry-2">Changelog</a></h2>
 <div class="section" id="section-1">
 <h1>19.0.2.1.0</h1>
 <ul class="simple">
+<li><strong>BREAKING</strong>: the 1-5 <tt class="docutils literal">severity</tt> Selection on
+<tt class="docutils literal">spp.hazard.incident</tt> and <tt class="docutils literal">severity_override</tt> on
+<tt class="docutils literal">spp.hazard.incident.area</tt> are removed and replaced by
+<tt class="docutils literal">severity_id</tt> / <tt class="docutils literal">severity_override_id</tt> (Many2one to
+<tt class="docutils literal">spp.vocabulary.code</tt> on the CAP severity namespace). Modules that
+extend these models must migrate: views that reference
+<tt class="docutils literal">&lt;field <span class="pre">name=&quot;severity&quot;&gt;</span></tt> / <tt class="docutils literal">severity_override</tt>, code that reads
+<tt class="docutils literal">record.severity</tt>, records created with <tt class="docutils literal"><span class="pre">severity=&quot;…&quot;</span></tt>, and any
+<tt class="docutils literal">fields_to_log</tt> entries or domains naming the old fields. Read
+<tt class="docutils literal">severity_numeric</tt> (below) where a numeric scale is needed.</li>
+<li><strong>BREAKING</strong>: <tt class="docutils literal">spp_hazard</tt> now depends on <tt class="docutils literal">spp_vocabulary</tt>.</li>
+<li><strong>BREAKING</strong>: <tt class="docutils literal">category_id</tt> and <tt class="docutils literal">start_date</tt> are no longer
+<tt class="docutils literal">required</tt> at the model level (they remain required in the incident
+form view) so alert ingestion can create incidents that lack them.</li>
 <li>feat: severity is now a CAP v1.2 vocabulary code (<tt class="docutils literal">severity_id</tt>,
 <tt class="docutils literal">severity_override_id</tt> on incident areas) instead of a hardcoded 1-5
 Selection; adds CAP urgency/certainty/message-type/event fields, alert
 ingestion (<tt class="docutils literal">create_incident_from_alert</tt>), and incident <tt class="docutils literal">uuid</tt>
 (re-land from #76).</li>
+<li>feat: <tt class="docutils literal">spp.hazard.incident</tt> exposes a stored <tt class="docutils literal">severity_numeric</tt>
+(5=extreme, 4=severe, 3=moderate, 2=minor, 1=unknown, 0=unset) so
+downstream ordering and threshold logic can consume a numeric scale
+without resolving CAP vocabulary codes.</li>
 <li>feat: migration backfills legacy 1-5 severity values onto the
 vocabulary fields when upgrading from 19.0.2.0.x (1→minor, 2→moderate,
 3→severe, 4→severe, 5→extreme); existing values are never overwritten

spp_hazard/tests/test_hazard_incident.py

@@ -340,3 +340,18 @@ def test_21_multi_record_close(self):
         # inc1 gets auto end_date, inc2 preserves its own
         self.assertTrue(inc1.end_date)
         self.assertEqual(str(inc2.end_date), "2024-04-01")
+
+    def test_22_severity_numeric(self):
+        """Test severity_numeric maps the CAP severity code to a 1-5 scale."""
+        # setUpClass created the incident with the 'severe' code -> 4
+        self.assertEqual(self.incident.severity_numeric, 4)
+
+        # Recomputes when the code changes
+        self.incident.severity_id = self.severity_extreme
+        self.assertEqual(self.incident.severity_numeric, 5)
+        self.incident.severity_id = self.severity_moderate
+        self.assertEqual(self.incident.severity_numeric, 3)
+
+        # No severity set -> 0 (sorts last in "most severe" ordering)
+        self.incident.severity_id = False
+        self.assertEqual(self.incident.severity_numeric, 0)