From 4a706fbf5069f7eebcfec11c3c0223969afd4cb9 Mon Sep 17 00:00:00 2001
From: emjay0921 <michael@acn.fr>
Date: Tue, 10 Feb 2026 09:17:38 +0800
Subject: [PATCH 1/4] fix(spp_area, spp_gis_report): add labels and help to
 classification and GIS reference fields

---
 spp_area/views/area_base.xml        | 105 +++++++++++++++++++---------
 spp_gis_report/views/area_views.xml |  20 ++++--
 2 files changed, 89 insertions(+), 36 deletions(-)

diff --git a/spp_area/views/area_base.xml b/spp_area/views/area_base.xml
index 94b0fc0..8718658 100644
--- a/spp_area/views/area_base.xml
+++ b/spp_area/views/area_base.xml
@@ -5,15 +5,20 @@
         <field name="priority">1</field>
         <field name="arch" type="xml">
             <list>
-                <field name="name" column_invisible="1"/>
-                <field name="draft_name" string="Name"/>
+                <field name="name" column_invisible="1" />
+                <field name="draft_name" string="Name" />
                 <field name="altnames" />
                 <field name="code" />
                 <field name="parent_id" />
                 <field name="complete_name" string="Complete Name" />
                 <field name="area_level" />
                 <field name="area_type_id" string="Area Type" />
-                <field name="tag_ids" widget="many2many_tags" options="{'color_field': 'color'}" optional="hide" />
+                <field
+                    name="tag_ids"
+                    widget="many2many_tags"
+                    options="{'color_field': 'color'}"
+                    optional="hide"
+                />
             </list>
         </field>
     </record>
@@ -27,56 +32,74 @@
                 <sheet>
                     <!-- Title Section -->
                     <div class="oe_title">
-                        <label for="parent_id" class="oe_edit_only"/>
+                        <label for="parent_id" class="oe_edit_only" />
                         <h3 class="text-muted mb-2">
                             <field
                                 name="parent_id"
                                 placeholder="Select Parent Area..."
-                                options="{'no_open':True,'no_create_edit':True,'no_create':True}"/>
+                                options="{'no_open':True,'no_create_edit':True,'no_create':True}"
+                            />
                         </h3>
-                        <label for="name" class="oe_edit_only"/>
+                        <label for="name" class="oe_edit_only" />
                         <h1>
                             <field
                                 name="name"
                                 placeholder="Area Name..."
                                 readonly="1"
                                 force_save="1"
-                                class="oe_read_only"/>
+                                class="oe_read_only"
+                            />
                             <field
                                 name="draft_name"
                                 placeholder="Enter Area Name..."
-                                class="oe_edit_only"/>
+                                class="oe_edit_only"
+                            />
                         </h1>
                     </div>
 
                     <!-- Hidden Fields -->
-                    <field name="level" invisible="1"/>
+                    <field name="level" invisible="1" />
 
                     <!-- Main Information -->
                     <group>
                         <group string="Basic Information">
-                            <field name="code" placeholder="Area Code..."/>
-                            <field name="altnames"
-                                   string="Alternate Names"
-                                   placeholder="Alternative names for this area..."/>
-                            <field name="complete_name" readonly="1"/>
+                            <field name="code" placeholder="Area Code..." />
+                            <field
+                                name="altnames"
+                                string="Alternate Names"
+                                placeholder="Alternative names for this area..."
+                            />
+                            <field name="complete_name" readonly="1" />
                         </group>
                         <group string="Classification">
-                            <field name="area_level"/>
-                            <field name="area_type_id"
-                                   options="{'no_open': True, 'no_create': True}"/>
-                            <field name="area_sqkm"
-                                   string="Area (sq/km)"
-                                   widget="float"/>
+                            <field
+                                name="area_level"
+                                string="Admin Level"
+                                help="Hierarchical level of this area, automatically computed from its position in the area tree (0 = top-level)."
+                            />
+                            <field
+                                name="area_type_id"
+                                string="Area Type"
+                                help="Classification type for this area (e.g., Province, Municipality, Barangay)."
+                                options="{'no_open': True, 'no_create': True}"
+                            />
+                            <field
+                                name="area_sqkm"
+                                string="Area (sq km)"
+                                help="Geographic size of this area in square kilometers."
+                                widget="float"
+                            />
                         </group>
                     </group>
 
                     <!-- Tags Section -->
                     <group string="Tags">
-                        <field name="tag_ids"
-                               widget="many2many_tags"
-                               placeholder="Add tags..."
-                               options="{'color_field': 'color', 'no_create_edit': True}"/>
+                        <field
+                            name="tag_ids"
+                            widget="many2many_tags"
+                            placeholder="Add tags..."
+                            options="{'color_field': 'color', 'no_create_edit': True}"
+                        />
                     </group>
 
                     <!-- Child Areas -->
@@ -84,10 +107,14 @@
                         <page name="child" string="Child Areas">
                             <field name="child_ids" nolabel="1">
                                 <list>
-                                    <field name="name"/>
-                                    <field name="code" optional="show"/>
-                                    <field name="area_type_id" string="Type" optional="show"/>
-                                    <field name="area_level" optional="hide"/>
+                                    <field name="name" />
+                                    <field name="code" optional="show" />
+                                    <field
+                                        name="area_type_id"
+                                        string="Type"
+                                        optional="show"
+                                    />
+                                    <field name="area_level" optional="hide" />
                                 </list>
                             </field>
                         </page>
@@ -106,8 +133,16 @@
                 <field name="name" />
                 <field name="parent_id" />
                 <field name="tag_ids" />
-                <filter name="grp_parent" string="Parent" context="{'group_by': 'parent_id'}" />
-                <filter name="grp_level" string="Level" context="{'group_by': 'area_level'}" />
+                <filter
+                    name="grp_parent"
+                    string="Parent"
+                    context="{'group_by': 'parent_id'}"
+                />
+                <filter
+                    name="grp_level"
+                    string="Level"
+                    context="{'group_by': 'area_level'}"
+                />
             </search>
         </field>
     </record>
@@ -123,7 +158,8 @@
         <field name="help" type="html">
             <p class="o_view_nocontent_smiling_face">
                 Create a new Area!
-            </p><p>
+            </p>
+            <p>
                 Click the create button to enter the information of the Area.
             </p>
         </field>
@@ -151,7 +187,12 @@
         sequence="0"
     />
 
-    <menuitem id="area_main_top_menu" name="Areas" parent="area_main_menu_root" sequence="10" />
+    <menuitem
+        id="area_main_top_menu"
+        name="Areas"
+        parent="area_main_menu_root"
+        sequence="10"
+    />
 
     <menuitem
         id="menu_spparea"
diff --git a/spp_gis_report/views/area_views.xml b/spp_gis_report/views/area_views.xml
index 3391a5d..7458598 100644
--- a/spp_gis_report/views/area_views.xml
+++ b/spp_gis_report/views/area_views.xml
@@ -18,12 +18,24 @@ Part of OpenSPP. See LICENSE file for full copyright and licensing details.
                 <separator string="Reference Data for GIS Reports" />
                 <group name="gis_reference_data" col="2">
                     <group name="population_group">
-                        <field name="population" />
-                        <field name="population_date" />
-                        <field name="population_source" />
+                        <field
+                            name="population"
+                            help="Total population from census or official estimate. Used for per-capita normalization in GIS reports."
+                        />
+                        <field
+                            name="population_date"
+                            help="Date when the population data was collected or published."
+                        />
+                        <field
+                            name="population_source"
+                            help="Source of the population data, e.g., 'National Census 2020' or 'UNFPA Estimate'."
+                        />
                     </group>
                     <group name="household_group">
-                        <field name="household_count" />
+                        <field
+                            name="household_count"
+                            help="Number of households in this area. Used for per-household normalization in GIS reports."
+                        />
                     </group>
                 </group>
             </xpath>

From a85ea4bc2c17cbc3cf9ef82d8c0440e85a57cb71 Mon Sep 17 00:00:00 2001
From: emjay0921 <michael@acn.fr>
Date: Tue, 10 Feb 2026 09:26:50 +0800
Subject: [PATCH 2/4] fix(spp_area, spp_gis_report): move GIS reference data
 outside classification group to fix labels

---
 spp_area/views/area_base.xml        | 2 +-
 spp_gis_report/views/area_views.xml | 8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/spp_area/views/area_base.xml b/spp_area/views/area_base.xml
index 8718658..57836c2 100644
--- a/spp_area/views/area_base.xml
+++ b/spp_area/views/area_base.xml
@@ -61,7 +61,7 @@
                     <field name="level" invisible="1" />
 
                     <!-- Main Information -->
-                    <group>
+                    <group name="main_info">
                         <group string="Basic Information">
                             <field name="code" placeholder="Area Code..." />
                             <field
diff --git a/spp_gis_report/views/area_views.xml b/spp_gis_report/views/area_views.xml
index 7458598..698c5e3 100644
--- a/spp_gis_report/views/area_views.xml
+++ b/spp_gis_report/views/area_views.xml
@@ -13,9 +13,13 @@ Part of OpenSPP. See LICENSE file for full copyright and licensing details.
         <field name="inherit_id" ref="spp_area.view_spparea_form" />
         <field name="priority">20</field>
         <field name="arch" type="xml">
-            <!-- Add Reference Data section after area_sqkm field -->
-            <xpath expr="//field[@name='area_sqkm']" position="after">
+            <!-- Add Reference Data section after the main info group -->
+            <xpath expr="//group[@name='main_info']" position="after">
                 <separator string="Reference Data for GIS Reports" />
+                <div class="text-muted small mb-2">
+                    These fields are populated from external sources such as national census data or official estimates.
+                    They are used for normalization in GIS reports (e.g., per-capita or per-household calculations).
+                </div>
                 <group name="gis_reference_data" col="2">
                     <group name="population_group">
                         <field

From d33793b80d8f39f0d64656d823bc04ddf6a0183f Mon Sep 17 00:00:00 2001
From: emjay0921 <michael@acn.fr>
Date: Tue, 10 Feb 2026 09:27:51 +0800
Subject: [PATCH 3/4] fix(spp_gis_report): make GIS reference data fields
 readonly

---
 spp_gis_report/views/area_views.xml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/spp_gis_report/views/area_views.xml b/spp_gis_report/views/area_views.xml
index 698c5e3..f3b37fc 100644
--- a/spp_gis_report/views/area_views.xml
+++ b/spp_gis_report/views/area_views.xml
@@ -24,20 +24,24 @@ Part of OpenSPP. See LICENSE file for full copyright and licensing details.
                     <group name="population_group">
                         <field
                             name="population"
+                            readonly="1"
                             help="Total population from census or official estimate. Used for per-capita normalization in GIS reports."
                         />
                         <field
                             name="population_date"
+                            readonly="1"
                             help="Date when the population data was collected or published."
                         />
                         <field
                             name="population_source"
+                            readonly="1"
                             help="Source of the population data, e.g., 'National Census 2020' or 'UNFPA Estimate'."
                         />
                     </group>
                     <group name="household_group">
                         <field
                             name="household_count"
+                            readonly="1"
                             help="Number of households in this area. Used for per-household normalization in GIS reports."
                         />
                     </group>

From baaa41911de17ff797925449fdff23aa89d2907d Mon Sep 17 00:00:00 2001
From: emjay0921 <michael@acn.fr>
Date: Tue, 10 Feb 2026 09:29:50 +0800
Subject: [PATCH 4/4] =?UTF-8?q?fix(spp=5Fgis=5Freport):=20use=20km=C2=B2?=
 =?UTF-8?q?=20symbol,=20move=20help=20text=20to=20model=20definitions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 spp_area/views/area_base.xml        |  2 +-
 spp_gis_report/models/area_ext.py   |  8 ++++----
 spp_gis_report/views/area_views.xml | 24 ++++--------------------
 3 files changed, 9 insertions(+), 25 deletions(-)

diff --git a/spp_area/views/area_base.xml b/spp_area/views/area_base.xml
index 57836c2..16b7131 100644
--- a/spp_area/views/area_base.xml
+++ b/spp_area/views/area_base.xml
@@ -85,7 +85,7 @@
                             />
                             <field
                                 name="area_sqkm"
-                                string="Area (sq km)"
+                                string="Area (km²)"
                                 help="Geographic size of this area in square kilometers."
                                 widget="float"
                             />
diff --git a/spp_gis_report/models/area_ext.py b/spp_gis_report/models/area_ext.py
index 6afc8e1..c6b720f 100644
--- a/spp_gis_report/models/area_ext.py
+++ b/spp_gis_report/models/area_ext.py
@@ -17,20 +17,20 @@ class Area(models.Model):
     # ===== Reference Data for Normalization =====
     population = fields.Integer(
         "Population",
-        help="Total population from census or estimate",
+        help="Total population from census or official estimate. Used for per-capita normalization in GIS reports.",
     )
     population_date = fields.Date(
         "Population Data Date",
-        help="Date of population data",
+        help="Date when the population data was collected or published.",
     )
     population_source = fields.Char(
         "Population Data Source",
-        help="Source of population data (e.g., 'National Census 2020')",
+        help="Source of the population data, e.g., 'National Census 2020' or 'UNFPA Estimate'.",
     )
 
     household_count = fields.Integer(
         "Household Count",
-        help="Number of households in this area",
+        help="Number of households in this area. Used for per-household normalization in GIS reports.",
     )
 
     # ===== Registry Counts (Updated via scheduled refresh) =====
diff --git a/spp_gis_report/views/area_views.xml b/spp_gis_report/views/area_views.xml
index f3b37fc..c3dcef9 100644
--- a/spp_gis_report/views/area_views.xml
+++ b/spp_gis_report/views/area_views.xml
@@ -22,28 +22,12 @@ Part of OpenSPP. See LICENSE file for full copyright and licensing details.
                 </div>
                 <group name="gis_reference_data" col="2">
                     <group name="population_group">
-                        <field
-                            name="population"
-                            readonly="1"
-                            help="Total population from census or official estimate. Used for per-capita normalization in GIS reports."
-                        />
-                        <field
-                            name="population_date"
-                            readonly="1"
-                            help="Date when the population data was collected or published."
-                        />
-                        <field
-                            name="population_source"
-                            readonly="1"
-                            help="Source of the population data, e.g., 'National Census 2020' or 'UNFPA Estimate'."
-                        />
+                        <field name="population" readonly="1" />
+                        <field name="population_date" readonly="1" />
+                        <field name="population_source" readonly="1" />
                     </group>
                     <group name="household_group">
-                        <field
-                            name="household_count"
-                            readonly="1"
-                            help="Number of households in this area. Used for per-household normalization in GIS reports."
-                        />
+                        <field name="household_count" readonly="1" />
                     </group>
                 </group>
             </xpath>