Skip to content

Commit 54bc14c

Browse files
gonzalesedwin1123emjay0921
gonzalesedwin1123
authored and
emjay0921
committed
docs(spp_hazard_programs): update description and add QA testing guide
Align DESCRIPTION.md with actual code: fix menu paths, add field names to key models table, document ribbon/stat buttons/list columns, and note auto_install behavior. Add USAGE.md with 9 UI test scenarios for QA.
1 parent a9f126b commit 54bc14c

File tree

4 files changed

+713
-66
lines changed

4 files changed

+713
-66
lines changed

‎spp_hazard_programs/README.rst‎

Lines changed: 249 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -24,51 +24,62 @@ OpenSPP Hazard Programs Integration
2424

2525
Links hazard incidents to emergency response programs. Enables programs
2626
to target affected populations using verified impact data, filter
27-
registrants by damage severity, and automatically enable emergency mode
28-
when responding to active incidents.
27+
registrants by damage severity, and flag programs as emergency when
28+
responding to active incidents. Auto-installs when both ``spp_hazard``
29+
and ``spp_programs`` are present.
2930

3031
Key Capabilities
3132
~~~~~~~~~~~~~~~~
3233

3334
- Link programs to one or more hazard incidents via many-to-many
3435
relation
35-
- Automatically flag programs as emergency when linked to incidents in
36-
alert/active/recovery status
37-
- Filter eligible registrants by damage level threshold (any, moderate+,
38-
severe+, critical only)
39-
- Count affected registrants based on verified impacts matching damage
40-
criteria
41-
- Track which programs are responding to each incident (bidirectional
42-
navigation)
36+
- Compute ``is_emergency_program`` flag when any linked incident has
37+
status alert, active, or recovery
38+
- Filter eligible registrants by damage level threshold: any, moderate+,
39+
severe+, or critical/totally damaged only
40+
- Count affected registrants from verified ``spp.hazard.impact`` records
41+
matching the damage criteria
42+
- Toggle ``is_emergency_mode`` to apply relaxed compliance rules during
43+
active response
44+
- Navigate from programs to target incidents and affected registrants
45+
via stat buttons
46+
- Navigate from incidents to response programs via stat button
47+
- Show "Emergency Response" ribbon on program forms when
48+
``is_emergency_program`` is true
4349

4450
Key Models
4551
~~~~~~~~~~
4652

4753
+----------------------------------+-----------------------------------+
4854
| Model | Description |
4955
+==================================+===================================+
50-
| ``spp.program`` (extend) | Adds target incidents, emergency |
51-
| | mode, damage filter |
56+
| ``spp.program`` (extend) | Adds ``target_incident_ids``, |
57+
| | ``is_emergency_program``, |
58+
| | ``is_emergency_mode``, |
59+
| | ``qualifying_damage_levels`` |
5260
+----------------------------------+-----------------------------------+
53-
| ``spp.hazard.incident`` (extend) | Adds reverse relation to response |
54-
| | programs |
61+
| ``spp.hazard.incident`` (extend) | Adds ``program_ids`` reverse |
62+
| | relation and ``program_count`` |
5563
+----------------------------------+-----------------------------------+
5664

5765
UI Location
5866
~~~~~~~~~~~
5967

60-
- **Programs**: Programs > Programs > "Emergency Response" tab
61-
- **Incidents**: Hazard & Emergency > Incidents > All Incidents >
62-
"Response Programs" tab
63-
- **Stat buttons**: Programs show incident count and affected registrant
64-
count; incidents show response program count
65-
- **Filters**: "Emergency Programs" and "Has Target Incidents" filters
66-
in program search view
68+
- **Programs form**: Programs > Programs > "Emergency Response" tab
69+
- **Incidents form**: Hazard and Emergency > Incidents > All Incidents >
70+
"Response Programs" tab (visible when programs linked)
71+
- **Stat buttons**: Program form shows incident count and affected
72+
registrant count; incident form shows response program count
73+
- **List views**: Program list adds "Emergency" column; incident list
74+
adds "Programs" column
75+
- **Filters**: "Emergency Programs" and "Has Target Incidents" in
76+
program search view
6777

6878
Security
6979
~~~~~~~~
7080

71-
No new ACL entries. Access inherited from base models:
81+
No new models or ACL entries. Fields added to existing models inherit
82+
access from:
7283

7384
- ``spp.program``: Controlled by ``spp_programs`` security groups
7485
- ``spp.hazard.incident``: Controlled by ``spp_hazard`` security groups
@@ -94,6 +105,222 @@ Dependencies
94105
.. contents::
95106
:local:
96107

108+
Usage
109+
=====
110+
111+
Prerequisites
112+
~~~~~~~~~~~~~
113+
114+
Before testing, ensure the following modules are installed:
115+
116+
- ``spp_hazard`` (provides incidents, impacts, categories)
117+
- ``spp_programs`` (provides programs)
118+
- ``spp_hazard_programs`` (auto-installs when both above are present)
119+
120+
You will also need:
121+
122+
- At least one hazard category (e.g., "Typhoon") created at **Hazard and
123+
Emergency > Configuration > Hazard Categories**
124+
- At least one impact type (e.g., "Property Damage") created at **Hazard
125+
and Emergency > Configuration > Impact Types**
126+
- At least two registrants with ``is_registrant = True``
127+
- At least one incident with impact records linked to those registrants
128+
129+
Test Scenario 1: Link a Program to Incidents
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131+
132+
**Steps:**
133+
134+
1. Navigate to **Programs > Programs**
135+
2. Open an existing program or create a new one
136+
3. Click the **"Emergency Response"** tab in the form notebook
137+
4. In the "Target Incidents" section, confirm the **Is Emergency
138+
Program** field is read-only and shows ``False``
139+
5. In the "Emergency Settings" section, confirm:
140+
141+
- **Qualifying Damage Levels** defaults to "Any Damage Level"
142+
- **Emergency Mode** checkbox defaults to unchecked
143+
144+
6. In the inline list below, click "Add a line" to add an incident
145+
7. Select an incident with status **Active**
146+
8. Save the program
147+
148+
**Expected results:**
149+
150+
- The **Is Emergency Program** field changes to ``True``
151+
- A yellow **"Emergency Response"** ribbon appears at the top of the
152+
form
153+
- An **"Incidents"** stat button (bolt icon) appears in the button box
154+
showing "1"
155+
- An **"Affected"** stat button (users icon) appears showing the count
156+
of registrants with verified impacts from that incident
157+
158+
Test Scenario 2: Verify Emergency Flag by Incident Status
159+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160+
161+
**Steps:**
162+
163+
1. Link a program to an incident with status **Alert**
164+
2. Save and confirm **Is Emergency Program** is ``True``
165+
3. Change the incident status to **Active** -- confirm still ``True``
166+
4. Change the incident status to **Recovery** -- confirm still ``True``
167+
5. Change the incident status to **Closed** -- confirm **Is Emergency
168+
Program** becomes ``False`` (assuming no other linked incidents have
169+
alert/active/recovery status)
170+
171+
**Expected results:**
172+
173+
- The emergency flag is ``True`` for alert, active, and recovery
174+
statuses
175+
- The emergency flag is ``False`` for closed status (when no other
176+
active incidents are linked)
177+
- The yellow ribbon appears/disappears accordingly
178+
179+
Test Scenario 3: Damage Level Filtering
180+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
181+
182+
**Setup:** Ensure the linked incident has verified impact records with
183+
different damage levels (e.g., one "critical", one "moderate", one
184+
unverified "severe").
185+
186+
**Steps:**
187+
188+
1. Open a program linked to the incident
189+
2. Go to the **"Emergency Response"** tab
190+
3. Set **Qualifying Damage Levels** to each option and save after each
191+
change:
192+
193+
+---------------------------------+------------------------------------+
194+
| Setting | Expected "Affected" count |
195+
+=================================+====================================+
196+
| "Any Damage Level" | All registrants with verified |
197+
| | impacts (unverified excluded) |
198+
+---------------------------------+------------------------------------+
199+
| "Moderate and Above" | Registrants with moderate, severe, |
200+
| | critical, partially damaged, or |
201+
| | totally damaged verified impacts |
202+
+---------------------------------+------------------------------------+
203+
| "Severe and Above" | Registrants with severe, critical, |
204+
| | or totally damaged verified |
205+
| | impacts |
206+
+---------------------------------+------------------------------------+
207+
| "Critical/Totally Damaged Only" | Registrants with critical or |
208+
| | totally damaged verified impacts |
209+
+---------------------------------+------------------------------------+
210+
211+
**Expected results:**
212+
213+
- The **"Affected"** stat button count updates after each save
214+
- Unverified impact records are always excluded regardless of damage
215+
level
216+
217+
Test Scenario 4: Stat Button Navigation
218+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219+
220+
**Steps:**
221+
222+
1. Open a program with at least one linked incident and affected
223+
registrants
224+
2. Click the **"Incidents"** stat button (bolt icon)
225+
3. Confirm it opens a list view of ``spp.hazard.incident`` records
226+
filtered to only the program's target incidents
227+
4. Navigate back to the program
228+
5. Click the **"Affected"** stat button (users icon)
229+
6. Confirm it opens a list view of ``res.partner`` records filtered to
230+
only registrants with qualifying verified impacts
231+
232+
**Expected results:**
233+
234+
- Each stat button opens the correct model with the correct filtered
235+
records
236+
- The number of records in the opened list matches the stat button count
237+
238+
Test Scenario 5: Incident Side -- Response Programs
239+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240+
241+
**Steps:**
242+
243+
1. Navigate to **Hazard and Emergency > Incidents > All Incidents**
244+
2. Open an incident that has NO programs linked to it
245+
3. Confirm:
246+
247+
- No **"Programs"** stat button is visible in the button box
248+
- No **"Response Programs"** tab is visible in the notebook
249+
250+
4. Now link a program to this incident (from the program side, add this
251+
incident to a program's target incidents)
252+
5. Reload the incident form
253+
254+
**Expected results:**
255+
256+
- A **"Programs"** stat button (list icon) appears showing "1"
257+
- A **"Response Programs"** tab appears in the notebook
258+
- The tab contains a read-only list showing the linked program's name,
259+
state (badge), qualifying damage levels, and emergency mode
260+
- Clicking the stat button opens a list view of ``spp.program`` records
261+
filtered to the responding programs
262+
263+
Test Scenario 6: Bidirectional Relationship
264+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265+
266+
**Steps:**
267+
268+
1. Open a program and add Incident A to its target incidents via the
269+
"Emergency Response" tab
270+
2. Save the program
271+
3. Open Incident A and check the "Response Programs" tab
272+
273+
**Expected results:**
274+
275+
- Incident A's "Response Programs" tab shows the program
276+
- Removing the incident from the program also removes the program from
277+
the incident's response programs (and vice versa)
278+
279+
Test Scenario 7: Program List View Columns
280+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281+
282+
**Steps:**
283+
284+
1. Navigate to **Programs > Programs** (list view)
285+
2. Check the column headers
286+
287+
**Expected results:**
288+
289+
- An **"Emergency"** column is visible by default (shows True/False)
290+
- An **"Incidents"** column is available via the optional columns toggle
291+
(hidden by default)
292+
293+
Test Scenario 8: Search Filters
294+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
295+
296+
**Steps:**
297+
298+
1. Navigate to **Programs > Programs** (list view)
299+
2. Open the search bar's **Filters** dropdown
300+
3. Activate the **"Emergency Programs"** filter
301+
4. Confirm only programs with ``is_emergency_program = True`` are shown
302+
5. Deactivate that filter and activate **"Has Target Incidents"**
303+
6. Confirm only programs with at least one target incident are shown
304+
305+
**Expected results:**
306+
307+
- Both filters appear in the search dropdown
308+
- Each filter correctly narrows the program list
309+
310+
Test Scenario 9: Incident List View Column
311+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
312+
313+
**Steps:**
314+
315+
1. Navigate to **Hazard and Emergency > Incidents > All Incidents**
316+
(list view)
317+
2. Check the column headers
318+
319+
**Expected results:**
320+
321+
- A **"Programs"** column is visible by default showing the count of
322+
response programs for each incident
323+
97324
Bug Tracker
98325
===========
99326

‎spp_hazard_programs/readme/DESCRIPTION.md‎

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,38 @@
1-
Links hazard incidents to emergency response programs. Enables programs to target affected populations using verified impact data, filter registrants by damage severity, and automatically enable emergency mode when responding to active incidents.
1+
Links hazard incidents to emergency response programs. Enables programs to
2+
target affected populations using verified impact data, filter registrants
3+
by damage severity, and flag programs as emergency when responding to
4+
active incidents. Auto-installs when both `spp_hazard` and `spp_programs`
5+
are present.
26

37
### Key Capabilities
48

59
- Link programs to one or more hazard incidents via many-to-many relation
6-
- Automatically flag programs as emergency when linked to incidents in alert/active/recovery status
7-
- Filter eligible registrants by damage level threshold (any, moderate+, severe+, critical only)
8-
- Count affected registrants based on verified impacts matching damage criteria
9-
- Track which programs are responding to each incident (bidirectional navigation)
10+
- Compute `is_emergency_program` flag when any linked incident has status alert, active, or recovery
11+
- Filter eligible registrants by damage level threshold: any, moderate+, severe+, or critical/totally damaged only
12+
- Count affected registrants from verified `spp.hazard.impact` records matching the damage criteria
13+
- Toggle `is_emergency_mode` to apply relaxed compliance rules during active response
14+
- Navigate from programs to target incidents and affected registrants via stat buttons
15+
- Navigate from incidents to response programs via stat button
16+
- Show "Emergency Response" ribbon on program forms when `is_emergency_program` is true
1017

1118
### Key Models
1219

13-
| Model | Description |
14-
| --------------------------- | ---------------------------------------------------- |
15-
| `spp.program` (extend) | Adds target incidents, emergency mode, damage filter |
16-
| `spp.hazard.incident` (extend) | Adds reverse relation to response programs |
20+
| Model | Description |
21+
| -------------------------------- | ------------------------------------------------------------------ |
22+
| `spp.program` (extend) | Adds `target_incident_ids`, `is_emergency_program`, `is_emergency_mode`, `qualifying_damage_levels` |
23+
| `spp.hazard.incident` (extend) | Adds `program_ids` reverse relation and `program_count` |
1724

1825
### UI Location
1926

20-
- **Programs**: Programs > Programs > "Emergency Response" tab
21-
- **Incidents**: Hazard & Emergency > Incidents > All Incidents > "Response Programs" tab
22-
- **Stat buttons**: Programs show incident count and affected registrant count; incidents show response program count
23-
- **Filters**: "Emergency Programs" and "Has Target Incidents" filters in program search view
27+
- **Programs form**: Programs > Programs > "Emergency Response" tab
28+
- **Incidents form**: Hazard and Emergency > Incidents > All Incidents > "Response Programs" tab (visible when programs linked)
29+
- **Stat buttons**: Program form shows incident count and affected registrant count; incident form shows response program count
30+
- **List views**: Program list adds "Emergency" column; incident list adds "Programs" column
31+
- **Filters**: "Emergency Programs" and "Has Target Incidents" in program search view
2432

2533
### Security
2634

27-
No new ACL entries. Access inherited from base models:
35+
No new models or ACL entries. Fields added to existing models inherit access from:
2836

2937
- `spp.program`: Controlled by `spp_programs` security groups
3038
- `spp.hazard.incident`: Controlled by `spp_hazard` security groups

0 commit comments

Comments
 (0)