feat(change_request_v2): redesign Change Head of Household CR (#873)

Replace the single new-head dropdown with an editable members-with-roles
table: one role line is seeded per active group member, and the member
assigned the Head role becomes the new head (a constraint blocks two heads).
Make the current head non-clickable, drop the unused Effective Date field,
and remove the Voluntary Transfer reason.

Add reason-driven required documents: a per-reason document config on the
CR type (shown only for types whose detail exposes a reason) drives the
request's required documents via _get_effective_required_document_ids().

The review preview now renders the household, reason, remarks and a members
table (Name / Current Role / New Role).

Author: emjay0921

spp_change_request_v2/details/change_hoh.py

@@ -1,8 +1,12 @@
-from odoo import api, fields, models
+from odoo import _, api, fields, models
+from odoo.exceptions import ValidationError
+
+ROLE_NAMESPACE = "urn:openspp:vocab:group-membership-type"
+HEAD_ROLE_CODE = "head"
 
 
 class SPPCRDetailChangeHOH(models.Model):
-    """Detail model for Change Head of Household CR type."""
+    """Detail model for Change Head of Household CR type (OP#873)."""
 
     _name = "spp.cr.detail.change_hoh"
     _description = "CR Detail: Change Head of Household"
@@ -19,51 +23,26 @@ class SPPCRDetailChangeHOH(models.Model):
         store=True,
         readonly=True,
     )
-    available_individual_ids = fields.Many2many(
-        "res.partner",
-        string="Available Individuals",
-        compute="_compute_available_individuals",
-        help="Active members excluding current head of household",
-    )
-    new_head_id = fields.Many2one(
-        "res.partner",
-        string="New Head of Household",
-        tracking=True,
-        domain="[('is_group', '=', False), ('is_registrant', '=', True)]",
-        help="Select the individual who will become the new head of household",
-    )
-    new_head_membership_id = fields.Many2one(
-        "spp.group.membership",
-        string="New Head Membership",
-        readonly=True,
-        help="Membership record for the new head (automatically set)",
-    )
-    previous_head_new_role_id = fields.Many2one(
-        "spp.vocabulary.code",
-        string="Previous Head's New Role",
-        domain="[('vocabulary_id.namespace_uri', '=', 'urn:openspp:vocab:group-membership-type'),"
-        " ('code', '!=', 'head')]",
-        tracking=True,
-        help="The new role for the previous head (e.g., Spouse, Other Adult)",
+    # One editable role line per active group member. The new head is whichever
+    # member is assigned the Head role (OP#873 — replaces the single new-head
+    # dropdown with a members-with-roles table).
+    member_line_ids = fields.One2many(
+        "spp.cr.detail.change_hoh.member",
+        "detail_id",
+        string="Members",
     )
     reason = fields.Selection(
         [
             ("deceased", "Head Deceased"),
             ("incapacitated", "Head Incapacitated"),
             ("left_household", "Head Left Household"),
             ("age_change", "Age-based Change"),
-            ("voluntary", "Voluntary Transfer"),
             ("correction", "Data Correction"),
             ("other", "Other"),
         ],
         string="Reason for Change",
         tracking=True,
     )
-    effective_date = fields.Date(
-        string="Effective Date",
-        default=fields.Date.today,
-        tracking=True,
-    )
     remarks = fields.Text(string="Remarks", tracking=True)
 
     # ══════════════════════════════════════════════════════════════════════════
@@ -73,58 +52,80 @@ class SPPCRDetailChangeHOH(models.Model):
     @api.depends("change_request_id.registrant_id")
     def _compute_current_head(self):
         """Find the current head of household."""
-        head_kind = self.env["spp.vocabulary.code"].get_code("urn:openspp:vocab:group-membership-type", "head")
+        head_kind = self.env["spp.vocabulary.code"].get_code(ROLE_NAMESPACE, HEAD_ROLE_CODE)
         for rec in self:
             current_head = False
             if rec.change_request_id.registrant_id and head_kind:
-                memberships = self.env["spp.group.membership"].search(
+                membership = self.env["spp.group.membership"].search(
                     [
                         ("group", "=", rec.change_request_id.registrant_id.id),
                         ("membership_type_ids", "in", [head_kind.id]),
                         ("status", "=", "active"),
                     ],
                     limit=1,
                 )
-                if memberships:
-                    current_head = memberships.individual
+                if membership:
+                    current_head = membership.individual
             rec.current_head_id = current_head
 
-    @api.depends("change_request_id.registrant_id", "current_head_id")
-    def _compute_available_individuals(self):
-        """Compute available individuals excluding current head of household."""
-        head_kind = self.env["spp.vocabulary.code"].get_code("urn:openspp:vocab:group-membership-type", "head")
-        for rec in self:
-            available_individuals = self.env["res.partner"]
-            if rec.change_request_id.registrant_id:
-                # Get all active memberships for this group
-                all_memberships = self.env["spp.group.membership"].search(
-                    [
-                        ("group", "=", rec.change_request_id.registrant_id.id),
-                        ("status", "=", "active"),
-                    ]
-                )
-                # Exclude current head
-                if head_kind:
-                    available_memberships = all_memberships.filtered(lambda m: head_kind not in m.membership_type_ids)
-                else:
-                    available_memberships = all_memberships
-                # Get the individuals from these memberships
-                available_individuals = available_memberships.mapped("individual")
-            rec.available_individual_ids = available_individuals
+    @api.model_create_multi
+    def create(self, vals_list):
+        details = super().create(vals_list)
+        for detail in details:
+            if not detail.member_line_ids:
+                detail._seed_member_lines()
+        return details
 
-    @api.onchange("new_head_id")
-    def _onchange_new_head_id(self):
-        """Set the membership_id when individual is selected."""
-        self.new_head_membership_id = False
-        if self.new_head_id and self.change_request_id.registrant_id:
-            # Find the membership for this individual in this group
-            membership = self.env["spp.group.membership"].search(
-                [
-                    ("group", "=", self.change_request_id.registrant_id.id),
-                    ("individual", "=", self.new_head_id.id),
-                    ("status", "=", "active"),
-                ],
-                limit=1,
+    def _seed_member_lines(self):
+        """Populate one editable role line per active group member, defaulting
+        each member's new role to their current role."""
+        self.ensure_one()
+        group = self.change_request_id.registrant_id
+        if not group or not group.is_group:
+            return
+        memberships = self.env["spp.group.membership"].search([("group", "=", group.id), ("status", "=", "active")])
+        lines = []
+        for membership in memberships:
+            current_roles = membership.membership_type_ids
+            lines.append(
+                (
+                    0,
+                    0,
+                    {
+                        "individual_id": membership.individual.id,
+                        "membership_id": membership.id,
+                        "old_role_display": ", ".join(current_roles.mapped("display")),
+                        "new_role_id": current_roles[:1].id if current_roles else False,
+                    },
+                )
             )
-            if membership:
-                self.new_head_membership_id = membership
+        self.member_line_ids = lines
+
+
+class SPPCRDetailChangeHOHMember(models.Model):
+    """One editable role line per current group member (Change HoH, OP#873)."""
+
+    _name = "spp.cr.detail.change_hoh.member"
+    _description = "CR Detail: Change HoH - Member Role"
+
+    detail_id = fields.Many2one(
+        "spp.cr.detail.change_hoh",
+        required=True,
+        ondelete="cascade",
+    )
+    individual_id = fields.Many2one("res.partner", string="Member", readonly=True)
+    membership_id = fields.Many2one("spp.group.membership", readonly=True)
+    old_role_display = fields.Char(string="Current Role", readonly=True)
+    new_role_id = fields.Many2one(
+        "spp.vocabulary.code",
+        string="New Role",
+        domain="[('vocabulary_id.namespace_uri', '=', 'urn:openspp:vocab:group-membership-type')]",
+    )
+
+    @api.constrains("new_role_id")
+    def _check_single_head(self):
+        """A group can have at most one Head of Household."""
+        head = self.env["spp.vocabulary.code"].get_code(ROLE_NAMESPACE, HEAD_ROLE_CODE)
+        for detail in self.mapped("detail_id"):
+            if head and len(detail.member_line_ids.filtered(lambda r: r.new_role_id == head)) > 1:
+                raise ValidationError(_("A group can have at most one Head of Household."))

spp_change_request_v2/models/change_request.py

@@ -392,10 +392,36 @@ def _compute_stage_banner_html(self):
                 )
             rec.stage_banner_html = html
 
-    @api.depends("document_ids", "document_ids.document_type_id", "request_type_id.required_document_ids")
+    def _get_effective_required_document_ids(self):
+        """Return the document types required for this request.
+
+        When the request type defines per-reason document rules (OP#873) and the
+        request's detail exposes a matching reason, that rule's documents take
+        precedence over the flat ``required_document_ids`` list. A configured
+        rule with no documents means nothing is required for that reason."""
+        self.ensure_one()
+        empty = self.env["spp.vocabulary.code"]
+        rt = self.request_type_id
+        if not rt:
+            return empty
+        reason_rules = rt.reason_document_ids
+        if reason_rules:
+            detail = self.get_detail()
+            reason = detail.reason if detail and "reason" in detail._fields else False
+            if reason:
+                rule = reason_rules.filtered(lambda r: r.reason == reason)
+                return rule[:1].required_document_ids if rule else empty
+        return rt.required_document_ids
+
+    @api.depends(
+        "document_ids",
+        "document_ids.document_type_id",
+        "request_type_id.required_document_ids",
+        "request_type_id.reason_document_ids",
+    )
     def _compute_missing_required_documents(self):
         for rec in self:
-            required = rec.request_type_id.required_document_ids if rec.request_type_id else None
+            required = rec._get_effective_required_document_ids() if rec.request_type_id else None
             if not required:
                 rec.missing_required_document_ids = self.env["spp.vocabulary.code"]
                 rec.documents_complete = True
@@ -405,10 +431,15 @@ def _compute_missing_required_documents(self):
             rec.missing_required_document_ids = missing
             rec.documents_complete = not bool(missing)
 
-    @api.depends("document_ids", "document_ids.document_type_id", "request_type_id.required_document_ids")
+    @api.depends(
+        "document_ids",
+        "document_ids.document_type_id",
+        "request_type_id.required_document_ids",
+        "request_type_id.reason_document_ids",
+    )
     def _compute_required_documents_html(self):
         for rec in self:
-            required = rec.request_type_id.required_document_ids if rec.request_type_id else None
+            required = rec._get_effective_required_document_ids() if rec.request_type_id else None
             if not required:
                 rec.required_documents_html = (
                     '<div class="alert alert-info mb-3 py-2">'

spp_change_request_v2/models/change_request_type.py

@@ -171,6 +171,23 @@ class SPPChangeRequestType(models.Model):
         string="Required Documents (Deprecated)",
         help="Deprecated: Use required_document_ids instead",
     )
+    # Per-reason document rules (OP#873). When a CR type exposes a "reason"
+    # (e.g. Change Head of Household), the required documents can be driven by
+    # the chosen reason instead of the flat required_document_ids list.
+    supports_reason_documents = fields.Boolean(
+        string="Supports Reason-based Documents",
+        compute="_compute_supports_reason_documents",
+        help="True when the detail model exposes a 'reason' field, so required "
+        "documents can depend on the chosen reason.",
+    )
+    reason_document_ids = fields.One2many(
+        "spp.cr.type.reason.document",
+        "cr_type_id",
+        string="Required Documents by Reason",
+        help="Optional: make required documents depend on the request's Reason. "
+        "When set and the request has a matching reason, these documents are "
+        "required in place of the flat 'Required Documents' list.",
+    )
     allow_document_download = fields.Boolean(
         string="Allow Document Download",
         default=False,
@@ -343,6 +360,15 @@ def _compute_detail_model_exists(self):
         for rec in self:
             rec.is_detail_model_exists = bool(rec.detail_model and rec.detail_model in self.env)
 
+    @api.depends("detail_model")
+    def _compute_supports_reason_documents(self):
+        """A CR type supports reason-driven documents only when its detail model
+        has a 'reason' field (e.g. Change Head of Household)."""
+        for rec in self:
+            rec.supports_reason_documents = bool(
+                rec.detail_model and rec.detail_model in self.env and "reason" in self.env[rec.detail_model]._fields
+            )
+
     @api.depends("detail_model")
     def _compute_available_field_ids(self):
         """Compute available fields from the detail model."""
@@ -521,3 +547,51 @@ def validate_required_fields(self, detail_record):
                 missing_fields.append(field.field_description)
 
         return len(missing_fields) == 0, missing_fields
+
+
+class SPPCRTypeReasonDocument(models.Model):
+    """Maps a request reason to the set of documents required for it (OP#873).
+
+    Configured on a change request type; consumed by
+    spp.change.request._get_effective_required_document_ids(). The reason values
+    mirror spp.cr.detail.change_hoh.reason."""
+
+    _name = "spp.cr.type.reason.document"
+    _description = "CR Type: Required Documents by Reason"
+    _order = "cr_type_id, reason"
+
+    cr_type_id = fields.Many2one(
+        "spp.change.request.type",
+        string="Change Request Type",
+        required=True,
+        ondelete="cascade",
+    )
+    reason = fields.Selection(
+        [
+            ("deceased", "Head Deceased"),
+            ("incapacitated", "Head Incapacitated"),
+            ("left_household", "Head Left Household"),
+            ("age_change", "Age-based Change"),
+            ("correction", "Data Correction"),
+            ("other", "Other"),
+        ],
+        string="Reason",
+        required=True,
+    )
+    required_document_ids = fields.Many2many(
+        "spp.vocabulary.code",
+        "cr_type_reason_doc_rel",
+        "rule_id",
+        "doc_id",
+        string="Required Documents",
+        domain="[('vocabulary_id.namespace_uri', '=', 'urn:openspp:vocab:cr_document_type')]",
+        help="Documents required when the request's reason matches this rule.",
+    )
+
+    _sql_constraints = [
+        (
+            "reason_uniq",
+            "unique(cr_type_id, reason)",
+            "A reason can only have one document rule per change request type.",
+        ),
+    ]

spp_change_request_v2/security/ir.model.access.csv

@@ -151,3 +151,11 @@ access_spp_change_request_log_user,spp.change.request.log user,model_spp_change_
 access_spp_change_request_log_validator,spp.change.request.log validator,model_spp_change_request_log,group_cr_validator,1,0,0,0
 access_spp_change_request_log_validator_hq,spp.change.request.log validator hq,model_spp_change_request_log,group_cr_validator_hq,1,0,0,0
 access_spp_change_request_log_manager,spp.change.request.log manager,model_spp_change_request_log,group_cr_manager,1,1,1,1
+access_spp_cr_detail_change_hoh_member_user,spp.cr.detail.change_hoh.member user,model_spp_cr_detail_change_hoh_member,group_cr_user,1,1,1,1
+access_spp_cr_detail_change_hoh_member_validator,spp.cr.detail.change_hoh.member validator,model_spp_cr_detail_change_hoh_member,group_cr_validator,1,1,1,1
+access_spp_cr_detail_change_hoh_member_validator_hq,spp.cr.detail.change_hoh.member validator hq,model_spp_cr_detail_change_hoh_member,group_cr_validator_hq,1,1,1,1
+access_spp_cr_detail_change_hoh_member_manager,spp.cr.detail.change_hoh.member manager,model_spp_cr_detail_change_hoh_member,group_cr_manager,1,1,1,1
+access_spp_cr_type_reason_document_user,spp.cr.type.reason.document user,model_spp_cr_type_reason_document,group_cr_user,1,0,0,0
+access_spp_cr_type_reason_document_validator,spp.cr.type.reason.document validator,model_spp_cr_type_reason_document,group_cr_validator,1,0,0,0
+access_spp_cr_type_reason_document_validator_hq,spp.cr.type.reason.document validator hq,model_spp_cr_type_reason_document,group_cr_validator_hq,1,0,0,0
+access_spp_cr_type_reason_document_manager,spp.cr.type.reason.document manager,model_spp_cr_type_reason_document,group_cr_manager,1,1,1,1