[IMP] helpdesk_user_default_ticket_team: document behaviour and convert README to markdown

- Add docstrings to ``_compute_user_id``, ``create`` and
  ``_define_user_id`` and clarify the inline comments describing the
  team-leader fallback rules.
- Convert ``README.rst`` to ``README.md``, documenting usage, the
  graceful handling of partners without a linked user, and how to run
  the test suite.

helpdesk_user_default_ticket_team/README.md

@@ -0,0 +1,92 @@
+# helpdesk_user_default_ticket_team
+
+Automate ticket team attribution when a ticket is created by a portal user.
+
+This module extends the `helpdesk_mgmt` module by allowing to configure a
+default helpdesk team per user. It provides:
+
+- A new `default_helpdesk_ticket_team_id` field on the user form, located in
+  the Preferences tab.
+- Automatic team assignment when a ticket is created:
+  - If the ticket has no team assigned and has a linked partner.
+  - The module looks up the user associated with the partner. A partner with
+    no linked user (e.g. a plain contact) is handled gracefully and left
+    untouched.
+  - If the user has a default helpdesk team configured, it is automatically
+    assigned to the ticket.
+  - If the assigned team has a default project, the ticket is also linked to
+    that project.
+- Automatic user assignment when a team is selected:
+  - When a team is set or changed on a ticket, if the current assigned user
+    is not a member of that team, the team leader (`team_id.user_id`) is
+    automatically assigned instead.
+  - If the team has no leader configured, the assigned user is left unchanged
+    (to avoid creating unassigned tickets).
+
+This is particularly useful for multi-company or multi-team environments where
+portal users should always have their tickets routed to a specific team.
+
+# Installation
+
+Use Odoo normal module installation procedure to install
+`helpdesk_user_default_ticket_team`.
+
+This module depends on:
+
+- `helpdesk_mgmt`: provides the base helpdesk ticket functionality.
+- `helpdesk_mgmt_project`: provides the link between tickets and projects.
+
+# Usage
+
+1. Open a user form (Settings > Users & Companies > Users).
+2. In the **Preferences** tab, set the **Default Helpdesk Team** field.
+3. When that user (through its linked partner) creates a ticket without an
+   explicit team, the ticket is automatically routed to the configured team,
+   its default project, and the team leader.
+
+# Testing
+
+Automated tests live in `tests/test_helpdesk_ticket.py` and cover:
+
+- The `_define_user_id` decision logic (no team, no current user, user not in
+  team, user in team, team without leader).
+- The `create` auto-assignment (with/without partner, with/without default
+  team, explicit team not overridden, partner without linked user, batch
+  creation).
+- The `_compute_user_id` recomputation when the team changes.
+- The full portal creation flow (team + project + user) and the presence of
+  the `default_helpdesk_ticket_team_id` field on `res.users`.
+
+Run them with:
+
+```
+odoo-bin -d <db> --test-enable --stop-after-init \
+    -i helpdesk_user_default_ticket_team
+```
+
+# Known issues / Roadmap
+
+None yet.
+
+# Bug Tracker
+
+Bugs are tracked on [our issues website](https://git.elabore.coop/Elabore/helpdesk-tools/issues).
+In case of trouble, please check there if your issue has already been
+reported. If you spotted it first, help us smashing it by providing a
+detailed and welcomed feedback.
+
+# Credits
+
+## Contributors
+
+- Stéphan Sainléger - [Email](mailto:stephan.sainleger@elabore.coop)
+
+## Funders
+
+The development of this module has been financially supported by:
+
+- Elabore (https://elabore.coop)
+
+## Maintainer
+
+This module is maintained by Elabore.

helpdesk_user_default_ticket_team/README.rst

@@ -1,75 +0,0 @@
-=================================
-helpdesk_user_default_ticket_team
-=================================
-
-Automate ticket team attribution when ticket created by portal user.
-
-This module extends the ``helpdesk_mgmt`` module by allowing to configure a
-default helpdesk team per user. It provides:
-
-* A new ``default_helpdesk_ticket_team_id`` field on the user form, located in
-  the Preferences tab.
-* Automatic team assignment when a ticket is created:
-
-  * If the ticket has no team assigned and has a linked partner.
-  * The module looks up the portal user associated with the partner.
-  * If the user has a default helpdesk team configured, it is automatically
-    assigned to the ticket.
-  * If the assigned team has a default project, the ticket is also linked to
-    that project.
-
-* Automatic user assignment when a team is selected:
-
-  * When a team is set or changed on a ticket, if the current assigned user
-    is not a member of that team, the team leader (``team_id.user_id``) is
-    automatically assigned instead.
-  * If the team has no leader configured, the assigned user is left unchanged
-    (to avoid creating unassigned tickets).
-
-This is particularly useful for multi-company or multi-team environments where
-portal users should always have their tickets routed to a specific team.
-
-Installation
-============
-
-Use Odoo normal module installation procedure to install
-``helpdesk_user_default_ticket_team``.
-
-This module depends on:
-
-* ``helpdesk_mgmt``: provides the base helpdesk ticket functionality.
-* ``helpdesk_mgmt_project``: provides the link between tickets and projects.
-
-Known issues / Roadmap
-======================
-
-None yet.
-
-Bug Tracker
-===========
-
-Bugs are tracked on `our issues website <https://git.elabore.coop/Elabore/helpdesk-tools/issues>`_. In case of
-trouble, please check there if your issue has already been
-reported. If you spotted it first, help us smashing it by providing a
-detailed and welcomed feedback.
-
-Credits
-=======
-
-Contributors
-------------
-
-* Stéphan Sainléger - `Email <mailto:stephan.sainleger@elabore.coop>`_
-
-Funders
--------
-
-The development of this module has been financially supported by:
-
-* Elabore (https://elabore.coop)
-
-
-Maintainer
-----------
-
-This module is maintained by Elabore.

helpdesk_user_default_ticket_team/models/helpdesk_ticket.py

@@ -6,6 +6,12 @@ class HelpdeskTicket(models.Model):
 
     @api.depends("team_id")
     def _compute_user_id(self):
+        """Recompute the assigned user whenever the team changes.
+
+        Delegates to :meth:`_define_user_id` so that, when a team is set or
+        changed, the assigned user is realigned with that team (replaced by
+        the team leader if the current user does not belong to the team).
+        """
         for ticket in self:
             ticket.user_id = self._define_user_id(
                 ticket.team_id,
@@ -14,6 +20,19 @@ class HelpdeskTicket(models.Model):
 
     @api.model_create_multi
     def create(self, vals_list):
+        """Auto-assign team, project and user for portal-created tickets.
+
+        When a ticket is created without an explicit team but with a partner,
+        the partner's linked user is looked up and, if that user has a default
+        helpdesk team configured, the ticket is routed accordingly:
+
+        * ``team_id`` is set to the user's default helpdesk team.
+        * ``project_id`` is set to the team's default project, if any.
+        * ``user_id`` is set to the team leader (via :meth:`_define_user_id`).
+
+        Tickets that already have a team, that have no partner, or whose
+        partner has no linked user / no default team are left untouched.
+        """
         for vals in vals_list:
             if not vals.get("team_id") and vals.get("partner_id"):
                 # Find the user who creates the ticket
@@ -43,13 +62,35 @@ class HelpdeskTicket(models.Model):
         return super().create(vals_list)
 
     def _define_user_id(self, team_id=None, ticket_user_id=None):
+        """Determine which user should be assigned to a ticket for a team.
+
+        Decides whether the current ticket user must be kept or replaced by
+        the helpdesk team leader (``team_id.user_id``), according to the
+        following rules:
+
+        * No team             -> keep ``ticket_user_id`` unchanged.
+        * No current user     -> use the team leader.
+        * User not in team    -> replace with the team leader.
+        * User is a team member-> keep ``ticket_user_id`` unchanged.
+
+        :param team_id: the ``helpdesk.ticket.team`` record (or falsy).
+        :param ticket_user_id: the currently assigned ``res.users`` (or falsy).
+        :return: the ``res.users`` record that should be assigned (possibly an
+            empty recordset when the team has no leader and the current user
+            is not a member of the team).
+        """
         if not team_id:
+            # If no team, return the current ticket_user_id
             return ticket_user_id
 
         if not ticket_user_id:
+            # If no current user, fall back to the team leader (may be empty).
             return team_id.user_id
 
         if ticket_user_id not in team_id.user_ids:
+            # If the current user is not a team member, replace it with the
+            # team leader (may be empty).
             return team_id.user_id
 
+        # Otherwise the current user is a valid team member: keep it unchanged.
         return ticket_user_id