From 51f37025a3a95b56ab7ecf1a54f6d282691174cb Mon Sep 17 00:00:00 2001 From: maud-buchwalter Date: Tue, 20 Oct 2026 11:37:39 +0200 Subject: [PATCH] [IMP] project-dashboard-billable-hours add readme and docstrings --- project_dashboard_billable_hours/README.md | 30 ++++++++++++++ .../models/project_project.py | 41 ++++++++++++++++++- 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 project_dashboard_billable_hours/README.md diff --git a/project_dashboard_billable_hours/README.md b/project_dashboard_billable_hours/README.md new file mode 100644 index 0000000..08d123b --- /dev/null +++ b/project_dashboard_billable_hours/README.md @@ -0,0 +1,30 @@ +# Project Dashboard - Billable Hours + +Display billable hours — timesheets linked to a sales order line — in the project dashboard panel. + +This module extends the `project.project` dashboard with a "Billable Time" stat button showing the ratio of billable timesheets to total recorded timesheets. + +## Features + +- `billable_hours` computed field on projects: sum of timesheet hours whose `so_line` is set (computed in SQL via `_read_group` for batch performance). +- "Billable Time" stat button on the project dashboard, displaying + `billable / effective ` with the company's timesheet encoding unit. +- Billable rate coloring: + - red when the rate is below 50%, + - orange when the rate is below 80%, + - green when the rate is 80% or above. +- Clicking the button opens the project's billable timesheets (timesheets linked to a sales order line), reusing the `sale_timesheet` billable time action with a restricted domain. + +The button is only visible to users in the `hr_timesheet.group_hr_timesheet_user` group, on projects with both billing and timesheets enabled (`allow_billable` and `allow_timesheets`). + +## Installation + +- Odoo 18.0 +- Depends on `sale_timesheet` (which brings `sale`, `hr_timesheet` and `project`). + +## Credits + +- Author: Elabore +- Contributor: Maud Buchwalter - Assisted by AI +- Repository: +- License: AGPL-3 diff --git a/project_dashboard_billable_hours/models/project_project.py b/project_dashboard_billable_hours/models/project_project.py index 15f6d1d..8662a08 100644 --- a/project_dashboard_billable_hours/models/project_project.py +++ b/project_dashboard_billable_hours/models/project_project.py @@ -1,9 +1,19 @@ +"""Project extension: billable hours on the project dashboard. + +Adds a ``billable_hours`` computed field and a "Billable Time" stat +button to ``project.project``. Billable hours are timesheets linked to +a sales order line (``so_line`` set), so the metric reflects work that +is actually invoiced through a sale order. +""" + from odoo import api, fields, models class Project(models.Model): + """Extend projects with billable-hours tracking on the dashboard.""" + _inherit = "project.project" - + billable_hours = fields.Float( string="Billable Time", compute="_compute_billable_hours", @@ -13,6 +23,16 @@ class Project(models.Model): @api.depends('timesheet_ids.unit_amount', 'timesheet_ids.so_line') def _compute_billable_hours(self): + """Compute the total hours of timesheets linked to a SO line. + + Billable timesheets are those whose ``so_line`` is set. When the + recordset is empty (Odoo's new-record pseudo-computation), each + project is computed from its in-memory ``timesheet_ids``; + otherwise a single ``_read_group`` sums ``unit_amount`` per + project in SQL. + + :return: None (writes ``billable_hours`` on each record) + """ if not any(self._ids): for project in self: filtered_timesheets = project.timesheet_ids.filtered( @@ -42,6 +62,13 @@ class Project(models.Model): def action_project_billable_timesheets(self): + """Open the billable timesheets of a single project. + + Reuses ``sale_timesheet``'s ``action_billable_time_button`` and + restricts it to this project's timesheets with a SO line. + + :return: action dict opening the filtered timesheet list + """ self.ensure_one() action = self.action_billable_time_button() # sale_timesheet action['domain'] = [('project_id', '=', self.id), ('so_line', '!=', False)] @@ -50,6 +77,18 @@ class Project(models.Model): def _get_stat_buttons(self): + """Append the "Billable Time" stat button to the dashboard. + + The button shows ``billable / effective `` (converted to the + company's timesheet encoding unit) with the billable rate when + relevant, and opens the project's billable timesheets on click. + Color coding: red below 50%, orange below 80%, green above. + + The button is skipped when billing or timesheets are disabled on + the project, or the user lacks timesheet access rights. + + :return: list of stat button dicts (inherited + ours) + """ buttons = super()._get_stat_buttons() if not (self.allow_billable and self.allow_timesheets) \ or not self.env.user.has_group("hr_timesheet.group_hr_timesheet_user"):