865 lines
41 KiB
Markdown
865 lines
41 KiB
Markdown
# Fusion Clock — Province-Aware Automatic Unpaid Break Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Make the unpaid meal break deduct automatically from worked hours on every path (portal, kiosk, NFC, cron, **and manual backend entry**), using a 2-tier per-province rule table (Ontario: 5h→30min, 10h→+30min), with no duplicated logic.
|
||
|
||
**Architecture:** A new `fusion.clock.break.rule` table holds the per-province thresholds. `hr.employee._get_fclk_break_rule()` resolves an employee's rule from its company's province (global default fallback). `hr.attendance.x_fclk_break_minutes` becomes a single stored **computed** field — `statutory_break(worked_hours) + Σ penalty_minutes` — that recomputes on every save and replaces the four scattered write sites (controller `_apply_break_deduction` ×3 call sites, the auto-clock-out cron, and the penalty code's manual write).
|
||
|
||
**Tech Stack:** Odoo 19, Python, QWeb/XML views, Odoo test framework (`TransactionCase`).
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-05-31-fusion-clock-statutory-break-design.md`
|
||
|
||
---
|
||
|
||
## Dev environment & sync (READ FIRST — applies to every task)
|
||
|
||
**Two working copies (per project memory `feedback_dual_path_fusion_clock`):**
|
||
- **Git/source tree (edit + commit here):** `K:\Github\Odoo-Modules\fusion_clock`
|
||
- **Docker/active tree (what the container loads):** `K:\Github\odoo-modsdev\addons\fusion_clock`
|
||
|
||
Edit in the **git tree**, then **mirror to the Docker tree before every test run**:
|
||
|
||
```powershell
|
||
robocopy "K:\Github\Odoo-Modules\fusion_clock" "K:\Github\odoo-modsdev\addons\fusion_clock" /MIR /XD ".git" "__pycache__" /XF "*.pyc" /NFL /NDL /NJH /NJS; if ($LASTEXITCODE -lt 8) { "sync ok" } else { "sync FAILED" }
|
||
```
|
||
(robocopy exit codes < 8 = success.) **Preflight:** if `K:\Github\odoo-modsdev\addons\fusion_clock` does not exist, the dual-tree setup changed — STOP and confirm the active copy with the user before continuing.
|
||
|
||
**Container/DB:** `odoo-modsdev-app` / db `modsdev` (per memory `reference_docker_env_names`).
|
||
|
||
**Canonical commands** (note the ephemeral ports — `--test-enable` forces `http_spawn()` so 8069/8072 collide without them; per repo CLAUDE.md):
|
||
|
||
- Run this module's tests:
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo -d modsdev --test-enable --test-tags /fusion_clock -u fusion_clock --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -100
|
||
```
|
||
- Plain upgrade (no tests):
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo -d modsdev -u fusion_clock --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -50
|
||
```
|
||
- Pyflakes a changed Python file (catches undefined names instantly):
|
||
```bash
|
||
docker exec odoo-modsdev-app python3 -m pyflakes /mnt/extra-addons/fusion_clock/<relpath>.py
|
||
```
|
||
|
||
**Commit:** only from the git tree (`git -C "K:/Github/Odoo-Modules" ...`). Per memory `feedback_always_push_to_main`, push after each commit on `main`.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
**Created:**
|
||
- `fusion_clock/models/clock_break_rule.py` — the `fusion.clock.break.rule` model + tier engine + constraints.
|
||
- `fusion_clock/data/clock_break_rule_data.xml` — seed Ontario rule (`is_default`).
|
||
- `fusion_clock/views/clock_break_rule_views.xml` — list/form/action for the rule.
|
||
- `fusion_clock/migrations/19.0.4.1.0/post-migrate.py` — drop retired param + recompute break.
|
||
- `fusion_clock/tests/test_break_rules.py` — all new tests.
|
||
|
||
**Modified:**
|
||
- `fusion_clock/models/__init__.py` — import the new model.
|
||
- `fusion_clock/models/hr_employee.py` — add `_get_fclk_break_rule()`.
|
||
- `fusion_clock/models/hr_attendance.py` — `x_fclk_break_minutes` → stored compute; drop cron break-write.
|
||
- `fusion_clock/controllers/clock_api.py` — delete `_apply_break_deduction`, its clock-out call, and the penalty break-write.
|
||
- `fusion_clock/controllers/clock_kiosk.py` — delete the `_apply_break_deduction` call.
|
||
- `fusion_clock/controllers/clock_nfc_kiosk.py` — delete the `_apply_break_deduction` call.
|
||
- `fusion_clock/models/res_config_settings.py` — remove `fclk_break_threshold_hours`.
|
||
- `fusion_clock/views/res_config_settings_views.xml` — remove threshold row; relabel default-break as scheduling-only; point to Break Rules.
|
||
- `fusion_clock/data/ir_config_parameter_data.xml` — remove the `break_threshold_hours` seed record.
|
||
- `fusion_clock/security/ir.model.access.csv` — manager access for the new model.
|
||
- `fusion_clock/views/clock_menus.xml` — "Break Rules" config menu.
|
||
- `fusion_clock/__manifest__.py` — version bump + new data/view files.
|
||
- `fusion_clock/tests/__init__.py` — import the new test module.
|
||
- `fusion_clock/tests/test_settings.py` — assert the retired field is gone.
|
||
- `fusion_clock/CLAUDE.md` — model map, settings keys, break gotcha (Task 5).
|
||
|
||
**Behaviour-change note (intentional, approved by spec §4.3):** today a *late-in* penalty written at clock-in (e.g. +15) is silently swallowed at clock-out because `_apply_break_deduction` does `max(break, current)`. The new compute makes **all** penalty minutes strictly additive (`statutory + Σ penalties`), so a late-in penalty on a long shift is no longer lost. Net hours for such shifts will be correctly lower than before.
|
||
|
||
---
|
||
|
||
## Task 1: New model `fusion.clock.break.rule`
|
||
|
||
**Files:**
|
||
- Create: `fusion_clock/models/clock_break_rule.py`
|
||
- Create: `fusion_clock/data/clock_break_rule_data.xml`
|
||
- Create: `fusion_clock/views/clock_break_rule_views.xml`
|
||
- Create: `fusion_clock/tests/test_break_rules.py`
|
||
- Modify: `fusion_clock/models/__init__.py`
|
||
- Modify: `fusion_clock/tests/__init__.py`
|
||
- Modify: `fusion_clock/security/ir.model.access.csv`
|
||
- Modify: `fusion_clock/views/clock_menus.xml`
|
||
- Modify: `fusion_clock/__manifest__.py`
|
||
|
||
- [ ] **Step 1: Write the failing tests** — create `fusion_clock/tests/test_break_rules.py`:
|
||
|
||
```python
|
||
# -*- coding: utf-8 -*-
|
||
# Copyright 2026 Nexa Systems Inc.
|
||
# License OPL-1 (Odoo Proprietary License v1.0)
|
||
|
||
from datetime import datetime, timedelta
|
||
from odoo.tests import tagged, TransactionCase
|
||
from odoo.exceptions import ValidationError
|
||
|
||
|
||
@tagged('-at_install', 'post_install', 'fusion_clock')
|
||
class TestBreakRules(TransactionCase):
|
||
|
||
@classmethod
|
||
def setUpClass(cls):
|
||
super().setUpClass()
|
||
cls.ICP = cls.env['ir.config_parameter'].sudo()
|
||
cls.ICP.set_param('fusion_clock.auto_deduct_break', 'True')
|
||
cls.Rule = cls.env['fusion.clock.break.rule']
|
||
cls.default_rule = cls.Rule.search([('is_default', '=', True)], limit=1)
|
||
cls.employee = cls.env['hr.employee'].create({'name': 'FCLK Break Test'})
|
||
|
||
def _mk_att(self, hours):
|
||
check_in = datetime(2026, 1, 5, 9, 0, 0)
|
||
return self.env['hr.attendance'].create({
|
||
'employee_id': self.employee.id,
|
||
'check_in': check_in,
|
||
'check_out': check_in + timedelta(hours=hours),
|
||
})
|
||
|
||
# ---- Task 1: tier engine + constraints ----
|
||
def test_break_minutes_for_tiers(self):
|
||
rule = self.Rule.create({
|
||
'name': 'Tier Test', 'is_default': False,
|
||
'break1_after_hours': 5.0, 'break1_minutes': 30.0,
|
||
'break2_after_hours': 10.0, 'break2_minutes': 30.0,
|
||
})
|
||
self.assertEqual(rule.break_minutes_for(4.99), 0.0)
|
||
self.assertEqual(rule.break_minutes_for(5.0), 30.0)
|
||
self.assertEqual(rule.break_minutes_for(9.99), 30.0)
|
||
self.assertEqual(rule.break_minutes_for(10.0), 60.0)
|
||
self.assertEqual(rule.break_minutes_for(12.0), 60.0)
|
||
|
||
def test_second_tier_must_exceed_first(self):
|
||
with self.assertRaises(ValidationError):
|
||
self.Rule.create({
|
||
'name': 'Bad', 'is_default': False,
|
||
'break1_after_hours': 5.0, 'break1_minutes': 30.0,
|
||
'break2_after_hours': 5.0, 'break2_minutes': 30.0,
|
||
})
|
||
|
||
def test_single_default_enforced(self):
|
||
self.assertTrue(self.default_rule, "seed default rule must exist")
|
||
with self.assertRaises(ValidationError):
|
||
self.Rule.create({
|
||
'name': 'Another Default', 'is_default': True, 'active': True,
|
||
'break1_after_hours': 5.0, 'break1_minutes': 30.0,
|
||
'break2_after_hours': 10.0, 'break2_minutes': 30.0,
|
||
})
|
||
```
|
||
|
||
Append the import to `fusion_clock/tests/__init__.py` (add the line if not already present):
|
||
|
||
```python
|
||
from . import test_break_rules
|
||
```
|
||
|
||
- [ ] **Step 2: Create the model** — `fusion_clock/models/clock_break_rule.py`:
|
||
|
||
```python
|
||
# -*- coding: utf-8 -*-
|
||
# Copyright 2026 Nexa Systems Inc.
|
||
# License OPL-1 (Odoo Proprietary License v1.0)
|
||
|
||
from odoo import models, fields, api, _
|
||
from odoo.exceptions import ValidationError
|
||
|
||
|
||
class FusionClockBreakRule(models.Model):
|
||
_name = 'fusion.clock.break.rule'
|
||
_description = 'Statutory Break Rule'
|
||
_order = 'sequence, name'
|
||
|
||
name = fields.Char(string='Name', required=True)
|
||
country_id = fields.Many2one('res.country', string='Country')
|
||
state_id = fields.Many2one(
|
||
'res.country.state',
|
||
string='Province / State',
|
||
help="Employees whose company is in this province use this rule.",
|
||
)
|
||
is_default = fields.Boolean(
|
||
string='Default Rule',
|
||
help="Used when an employee's company province matches no other rule. "
|
||
"Only one active rule may be the default.",
|
||
)
|
||
break1_after_hours = fields.Float(
|
||
string='First Break After (h)', default=5.0,
|
||
help="Worked hours at or above this trigger the first unpaid break.",
|
||
)
|
||
break1_minutes = fields.Float(
|
||
string='First Break (min)', default=30.0,
|
||
help="Length of the first unpaid break. 0 disables it.",
|
||
)
|
||
break2_after_hours = fields.Float(
|
||
string='Second Break After (h)', default=10.0,
|
||
help="Worked hours at or above this add the second unpaid break.",
|
||
)
|
||
break2_minutes = fields.Float(
|
||
string='Second Break (min)', default=30.0,
|
||
help="Length of the second unpaid break. 0 disables it.",
|
||
)
|
||
sequence = fields.Integer(default=10)
|
||
active = fields.Boolean(default=True)
|
||
|
||
def break_minutes_for(self, worked_hours):
|
||
"""Total statutory unpaid break (minutes) for the given worked hours.
|
||
|
||
Tiers are inclusive (``>=``): a break applies when worked hours are
|
||
equal to or greater than the threshold. The second tier adds on top of
|
||
the first.
|
||
"""
|
||
self.ensure_one()
|
||
worked = worked_hours or 0.0
|
||
total = 0.0
|
||
if self.break1_minutes and worked >= self.break1_after_hours:
|
||
total += self.break1_minutes
|
||
if self.break2_minutes and worked >= self.break2_after_hours:
|
||
total += self.break2_minutes
|
||
return total
|
||
|
||
@api.constrains('break1_after_hours', 'break1_minutes',
|
||
'break2_after_hours', 'break2_minutes')
|
||
def _check_tiers(self):
|
||
for rule in self:
|
||
if min(rule.break1_after_hours, rule.break1_minutes,
|
||
rule.break2_after_hours, rule.break2_minutes) < 0:
|
||
raise ValidationError(_("Break hours and minutes cannot be negative."))
|
||
if rule.break2_minutes and rule.break2_after_hours <= rule.break1_after_hours:
|
||
raise ValidationError(_(
|
||
"The second break threshold (%(n2)s h) must be greater than "
|
||
"the first (%(n1)s h).",
|
||
n2=rule.break2_after_hours, n1=rule.break1_after_hours))
|
||
|
||
@api.constrains('is_default', 'active')
|
||
def _check_single_default(self):
|
||
for rule in self:
|
||
if rule.is_default and rule.active:
|
||
dupe = self.search([
|
||
('is_default', '=', True), ('active', '=', True),
|
||
('id', '!=', rule.id),
|
||
], limit=1)
|
||
if dupe:
|
||
raise ValidationError(_(
|
||
"Only one active break rule can be the default "
|
||
"(currently: %s).", dupe.name))
|
||
```
|
||
|
||
- [ ] **Step 3: Register the model** — add to `fusion_clock/models/__init__.py` after the `clock_penalty` import:
|
||
|
||
```python
|
||
from . import clock_break_rule
|
||
```
|
||
|
||
- [ ] **Step 4: Grant access** — append one row to `fusion_clock/security/ir.model.access.csv`:
|
||
|
||
```
|
||
access_fusion_clock_break_rule_manager,fusion.clock.break.rule.manager,model_fusion_clock_break_rule,group_fusion_clock_manager,1,1,1,1
|
||
```
|
||
|
||
(No user/portal grant needed — the resolver reads the table via `sudo()`.)
|
||
|
||
- [ ] **Step 5: Seed the Ontario rule** — create `fusion_clock/data/clock_break_rule_data.xml`:
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<odoo noupdate="1">
|
||
<record id="break_rule_ontario" model="fusion.clock.break.rule">
|
||
<field name="name">Ontario</field>
|
||
<field name="country_id" ref="base.ca"/>
|
||
<field name="state_id" ref="base.state_ca_on"/>
|
||
<field name="is_default" eval="True"/>
|
||
<field name="break1_after_hours">5.0</field>
|
||
<field name="break1_minutes">30.0</field>
|
||
<field name="break2_after_hours">10.0</field>
|
||
<field name="break2_minutes">30.0</field>
|
||
</record>
|
||
</odoo>
|
||
```
|
||
|
||
- [ ] **Step 6: Views + action** — create `fusion_clock/views/clock_break_rule_views.xml`:
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<odoo>
|
||
<record id="view_fusion_clock_break_rule_list" model="ir.ui.view">
|
||
<field name="name">fusion.clock.break.rule.list</field>
|
||
<field name="model">fusion.clock.break.rule</field>
|
||
<field name="arch" type="xml">
|
||
<list>
|
||
<field name="sequence" widget="handle"/>
|
||
<field name="name"/>
|
||
<field name="state_id"/>
|
||
<field name="country_id" optional="hide"/>
|
||
<field name="break1_after_hours" widget="float_time"/>
|
||
<field name="break1_minutes"/>
|
||
<field name="break2_after_hours" widget="float_time"/>
|
||
<field name="break2_minutes"/>
|
||
<field name="is_default"/>
|
||
<field name="active" widget="boolean_toggle"/>
|
||
</list>
|
||
</field>
|
||
</record>
|
||
|
||
<record id="view_fusion_clock_break_rule_form" model="ir.ui.view">
|
||
<field name="name">fusion.clock.break.rule.form</field>
|
||
<field name="model">fusion.clock.break.rule</field>
|
||
<field name="arch" type="xml">
|
||
<form>
|
||
<sheet>
|
||
<widget name="web_ribbon" title="Archived" bg_color="text-bg-danger"
|
||
invisible="active"/>
|
||
<div class="oe_title">
|
||
<h1><field name="name" placeholder="e.g. Ontario"/></h1>
|
||
</div>
|
||
<group>
|
||
<group string="Jurisdiction">
|
||
<field name="country_id"/>
|
||
<field name="state_id"
|
||
domain="[('country_id', '=', country_id)]"/>
|
||
<field name="is_default"/>
|
||
<field name="active"/>
|
||
</group>
|
||
<group string="Unpaid Break Tiers">
|
||
<label for="break1_after_hours" string="First break after"/>
|
||
<div class="o_row">
|
||
<field name="break1_after_hours" widget="float_time"/>
|
||
<span>h →</span>
|
||
<field name="break1_minutes"/>
|
||
<span>min</span>
|
||
</div>
|
||
<label for="break2_after_hours" string="Second break after"/>
|
||
<div class="o_row">
|
||
<field name="break2_after_hours" widget="float_time"/>
|
||
<span>h →</span>
|
||
<field name="break2_minutes"/>
|
||
<span>min</span>
|
||
</div>
|
||
</group>
|
||
</group>
|
||
<p class="text-muted">
|
||
Breaks are unpaid and deducted from actual worked hours. A tier with
|
||
0 minutes is disabled. Triggers are inclusive — a break applies when
|
||
worked hours are equal to or above the threshold.
|
||
</p>
|
||
</sheet>
|
||
</form>
|
||
</field>
|
||
</record>
|
||
|
||
<record id="action_fusion_clock_break_rule" model="ir.actions.act_window">
|
||
<field name="name">Break Rules</field>
|
||
<field name="res_model">fusion.clock.break.rule</field>
|
||
<field name="view_mode">list,form</field>
|
||
<field name="context">{'active_test': False}</field>
|
||
<field name="help" type="html">
|
||
<p class="o_view_nocontent_smiling_face">Create a statutory break rule</p>
|
||
<p>Define unpaid meal-break thresholds per province/country. Employees inherit
|
||
the rule matching their company's province, or the default rule.</p>
|
||
</field>
|
||
</record>
|
||
</odoo>
|
||
```
|
||
|
||
- [ ] **Step 7: Add the menu** — in `fusion_clock/views/clock_menus.xml`, insert after the `menu_fusion_clock_locations_config` menuitem (the Locations config item) and before `menu_fusion_clock_nfc_enrollment`:
|
||
|
||
```xml
|
||
<menuitem id="menu_fusion_clock_break_rules"
|
||
name="Break Rules"
|
||
parent="menu_fusion_clock_config"
|
||
action="action_fusion_clock_break_rule"
|
||
sequence="25"
|
||
groups="group_fusion_clock_manager"/>
|
||
```
|
||
|
||
- [ ] **Step 8: Wire the manifest** — in `fusion_clock/__manifest__.py`:
|
||
|
||
**Do NOT bump the version yet** — it stays `19.0.4.0.3` until Task 4, so the
|
||
`19.0.4.1.0` migration actually fires in dev (Odoo only runs a version's migration
|
||
when the installed version is *lower* than the manifest version).
|
||
|
||
Add the seed data file after `'data/ir_config_parameter_data.xml',`:
|
||
```python
|
||
'data/clock_break_rule_data.xml',
|
||
```
|
||
Add the view file after `'views/clock_schedule_views.xml',`:
|
||
```python
|
||
'views/clock_break_rule_views.xml',
|
||
```
|
||
(Data and view files reload on every `-u` regardless of the version number, so the
|
||
new model/menu install without a bump. No assets change in this plan, so the bump's
|
||
only purpose is the migration trigger — deferred to Task 4.)
|
||
|
||
- [ ] **Step 9: Sync, upgrade, run tests**
|
||
|
||
Sync (see preamble), then:
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo -d modsdev --test-enable --test-tags /fusion_clock -u fusion_clock --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -100
|
||
```
|
||
Expected: module upgrades cleanly; `test_break_minutes_for_tiers`, `test_second_tier_must_exceed_first`, `test_single_default_enforced` PASS. (Other tests in the class will error until Tasks 2–3 add their dependencies — that's expected if you scoped the run; otherwise the not-yet-added methods simply don't exist yet.)
|
||
|
||
- [ ] **Step 10: Commit**
|
||
|
||
```bash
|
||
git -C "K:/Github/Odoo-Modules" add fusion_clock/models/clock_break_rule.py fusion_clock/models/__init__.py fusion_clock/data/clock_break_rule_data.xml fusion_clock/views/clock_break_rule_views.xml fusion_clock/views/clock_menus.xml fusion_clock/security/ir.model.access.csv fusion_clock/__manifest__.py fusion_clock/tests/test_break_rules.py fusion_clock/tests/__init__.py
|
||
git -C "K:/Github/Odoo-Modules" commit -m "feat(fusion_clock): add fusion.clock.break.rule per-province break table" -m "Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
git -C "K:/Github/Odoo-Modules" push
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: Jurisdiction resolver on `hr.employee`
|
||
|
||
**Files:**
|
||
- Modify: `fusion_clock/models/hr_employee.py`
|
||
- Modify: `fusion_clock/tests/test_break_rules.py`
|
||
|
||
- [ ] **Step 1: Add the resolver tests** — append these methods to `TestBreakRules` in `fusion_clock/tests/test_break_rules.py`:
|
||
|
||
```python
|
||
# ---- Task 2: jurisdiction resolver ----
|
||
def test_resolver_matches_company_province(self):
|
||
bc = self.env.ref('base.state_ca_bc')
|
||
bc_rule = self.Rule.create({
|
||
'name': 'British Columbia', 'state_id': bc.id, 'is_default': False,
|
||
'break1_after_hours': 5.0, 'break1_minutes': 30.0,
|
||
'break2_after_hours': 10.0, 'break2_minutes': 30.0,
|
||
})
|
||
self.employee.company_id.state_id = bc.id
|
||
self.assertEqual(self.employee._get_fclk_break_rule(), bc_rule)
|
||
|
||
def test_resolver_falls_back_to_default(self):
|
||
self.assertTrue(self.default_rule, "seed default rule must exist")
|
||
alberta = self.env.ref('base.state_ca_ab') # no rule for AB
|
||
self.employee.company_id.state_id = alberta.id
|
||
self.assertEqual(self.employee._get_fclk_break_rule(), self.default_rule)
|
||
```
|
||
|
||
- [ ] **Step 2: Run to verify they fail**
|
||
|
||
Sync, then:
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo -d modsdev --test-enable --test-tags /fusion_clock -u fusion_clock --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -60
|
||
```
|
||
Expected: FAIL — `AttributeError: 'hr.employee' object has no attribute '_get_fclk_break_rule'`.
|
||
|
||
- [ ] **Step 3: Implement the resolver** — in `fusion_clock/models/hr_employee.py`, add this method immediately after the `_get_fclk_break_minutes` method (after its `return float(...)` block, before `_get_fclk_scheduled_times`):
|
||
|
||
```python
|
||
def _get_fclk_break_rule(self):
|
||
"""Return the statutory break rule for this employee.
|
||
|
||
Resolution: company's province → matching rule; else the global default
|
||
rule; else an empty recordset (caller treats as zero break). Read via
|
||
sudo so the portal net-hours compute can resolve it without a direct ACL.
|
||
"""
|
||
self.ensure_one()
|
||
Rule = self.env['fusion.clock.break.rule'].sudo()
|
||
rule = Rule.browse()
|
||
state = self.company_id.state_id
|
||
if state:
|
||
rule = Rule.search([('state_id', '=', state.id)], limit=1)
|
||
if not rule:
|
||
rule = Rule.search([('is_default', '=', True)], limit=1)
|
||
return rule
|
||
```
|
||
|
||
- [ ] **Step 4: Run to verify they pass**
|
||
|
||
Sync, then re-run the Step 2 command. Expected: `test_resolver_matches_company_province` and `test_resolver_falls_back_to_default` PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git -C "K:/Github/Odoo-Modules" add fusion_clock/models/hr_employee.py fusion_clock/tests/test_break_rules.py
|
||
git -C "K:/Github/Odoo-Modules" commit -m "feat(fusion_clock): resolve employee break rule from company province" -m "Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
git -C "K:/Github/Odoo-Modules" push
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: `x_fclk_break_minutes` → stored compute; remove all manual writes
|
||
|
||
This task is atomic: once the field is computed (no inverse), any remaining `write({'x_fclk_break_minutes': ...})` raises at runtime, so the field conversion and the removal of all four write sites must land together.
|
||
|
||
**Files:**
|
||
- Modify: `fusion_clock/models/hr_attendance.py`
|
||
- Modify: `fusion_clock/controllers/clock_api.py`
|
||
- Modify: `fusion_clock/controllers/clock_kiosk.py`
|
||
- Modify: `fusion_clock/controllers/clock_nfc_kiosk.py`
|
||
- Modify: `fusion_clock/tests/test_break_rules.py`
|
||
|
||
- [ ] **Step 1: Add the attendance tests** — append these methods to `TestBreakRules` in `fusion_clock/tests/test_break_rules.py`:
|
||
|
||
```python
|
||
# ---- Task 3: automatic deduction on every path ----
|
||
def test_manual_attendance_applies_statutory_break(self):
|
||
att = self._mk_att(6) # 6h >= 5 -> first break
|
||
self.assertEqual(att.x_fclk_break_minutes, 30.0)
|
||
self.assertAlmostEqual(att.x_fclk_net_hours, 5.5, places=2)
|
||
|
||
def test_manual_edit_extends_break(self):
|
||
att = self._mk_att(6)
|
||
self.assertEqual(att.x_fclk_break_minutes, 30.0)
|
||
att.check_out = att.check_in + timedelta(hours=10) # now >= 10
|
||
self.assertEqual(att.x_fclk_break_minutes, 60.0)
|
||
self.assertAlmostEqual(att.x_fclk_net_hours, 9.0, places=2)
|
||
|
||
def test_under_first_threshold_no_break(self):
|
||
att = self._mk_att(4) # 4h < 5 -> nothing
|
||
self.assertEqual(att.x_fclk_break_minutes, 0.0)
|
||
self.assertAlmostEqual(att.x_fclk_net_hours, 4.0, places=2)
|
||
|
||
def test_penalty_minutes_are_additive(self):
|
||
att = self._mk_att(6) # statutory 30
|
||
self.env['fusion.clock.penalty'].create({
|
||
'attendance_id': att.id,
|
||
'employee_id': self.employee.id,
|
||
'penalty_type': 'early_out',
|
||
'penalty_minutes': 15.0,
|
||
'date': att.check_in.date(),
|
||
})
|
||
self.assertEqual(att.x_fclk_break_minutes, 45.0)
|
||
|
||
def test_master_toggle_off_zero_statutory(self):
|
||
self.ICP.set_param('fusion_clock.auto_deduct_break', 'False')
|
||
att = self._mk_att(6)
|
||
self.assertEqual(att.x_fclk_break_minutes, 0.0)
|
||
|
||
def test_open_attendance_zero_break(self):
|
||
att = self.env['hr.attendance'].create({
|
||
'employee_id': self.employee.id,
|
||
'check_in': datetime(2026, 1, 5, 9, 0, 0),
|
||
})
|
||
self.assertEqual(att.x_fclk_break_minutes, 0.0)
|
||
```
|
||
|
||
- [ ] **Step 2: Run to verify they fail**
|
||
|
||
Sync, then run the module tests. Expected: the new tests FAIL — e.g. `test_manual_attendance_applies_statutory_break` asserts 30 but gets 0 (no write override exists yet).
|
||
|
||
- [ ] **Step 3: Convert the field to a stored compute** — in `fusion_clock/models/hr_attendance.py`, replace the field definition:
|
||
|
||
OLD:
|
||
```python
|
||
x_fclk_break_minutes = fields.Float(
|
||
string='Break (min)',
|
||
default=0.0,
|
||
tracking=True,
|
||
help="Break duration in minutes to deduct from worked hours.",
|
||
)
|
||
```
|
||
NEW:
|
||
```python
|
||
x_fclk_break_minutes = fields.Float(
|
||
string='Break (min)',
|
||
compute='_compute_fclk_break_minutes',
|
||
store=True,
|
||
tracking=True,
|
||
help="Unpaid break deducted from worked hours: statutory break (per the "
|
||
"employee's province rule, from actual hours worked) plus any penalty "
|
||
"minutes. Computed automatically on every save.",
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 4: Add the compute method** — in the same file, insert this method immediately before the `_compute_net_hours` method (just above its `@api.depends('worked_hours', 'x_fclk_break_minutes')` decorator):
|
||
|
||
```python
|
||
@api.depends('worked_hours', 'check_out',
|
||
'x_fclk_penalty_ids.penalty_minutes', 'employee_id')
|
||
def _compute_fclk_break_minutes(self):
|
||
ICP = self.env['ir.config_parameter'].sudo()
|
||
auto = ICP.get_param('fusion_clock.auto_deduct_break', 'True') == 'True'
|
||
for att in self:
|
||
statutory = 0.0
|
||
if auto and att.check_out and att.employee_id:
|
||
rule = att.employee_id._get_fclk_break_rule()
|
||
if rule:
|
||
statutory = rule.break_minutes_for(att.worked_hours or 0.0)
|
||
penalties = sum(att.x_fclk_penalty_ids.mapped('penalty_minutes'))
|
||
att.x_fclk_break_minutes = statutory + penalties
|
||
```
|
||
|
||
- [ ] **Step 5: Remove the cron's break write** — in the same file, inside `_cron_fusion_auto_clock_out`:
|
||
|
||
Remove the now-unused threshold read (the line near the top of the method):
|
||
```python
|
||
threshold = float(ICP.get_param('fusion_clock.break_threshold_hours', '4.0'))
|
||
```
|
||
Remove the two now-unused locals in the per-attendance loop:
|
||
```python
|
||
emp_tz = pytz.timezone(employee.tz or self.env.company.tz or 'UTC')
|
||
check_in_date = pytz.UTC.localize(check_in).astimezone(emp_tz).date()
|
||
```
|
||
Remove the break-write block (the compute now applies the break when `check_out` is set):
|
||
```python
|
||
if (att.worked_hours or 0) >= threshold:
|
||
att.sudo().write(
|
||
{'x_fclk_break_minutes': employee._get_fclk_break_minutes(check_in_date)}
|
||
)
|
||
```
|
||
(Leave the surrounding `employee = att.employee_id` and `clock_out_time = effective_deadline` lines intact.)
|
||
|
||
- [ ] **Step 6: Delete the controller helper and its call sites** — in `fusion_clock/controllers/clock_api.py`:
|
||
|
||
Delete the entire `_apply_break_deduction` method:
|
||
```python
|
||
def _apply_break_deduction(self, attendance, employee):
|
||
"""Apply automatic break deduction if configured."""
|
||
ICP = request.env['ir.config_parameter'].sudo()
|
||
if ICP.get_param('fusion_clock.auto_deduct_break', 'True') != 'True':
|
||
return
|
||
|
||
threshold = float(ICP.get_param('fusion_clock.break_threshold_hours', '4.0'))
|
||
worked = attendance.worked_hours or 0.0
|
||
|
||
if worked >= threshold:
|
||
local_date = get_local_today(request.env, employee)
|
||
if attendance.check_in:
|
||
tz_name = (
|
||
employee.resource_id.tz
|
||
or (employee.user_id.partner_id.tz if employee.user_id else False)
|
||
or employee.company_id.partner_id.tz
|
||
or 'UTC'
|
||
)
|
||
local_date = pytz.UTC.localize(attendance.check_in).astimezone(pytz.timezone(tz_name)).date()
|
||
break_min = employee._get_fclk_break_minutes(local_date)
|
||
current = attendance.x_fclk_break_minutes or 0.0
|
||
# Set to whichever is higher: configured break or existing (penalty-inflated) value
|
||
new_val = max(break_min, current)
|
||
if new_val != current:
|
||
attendance.sudo().write({'x_fclk_break_minutes': new_val})
|
||
|
||
```
|
||
Delete its clock-out call (in the CLOCK OUT branch):
|
||
```python
|
||
# Apply break deduction
|
||
self._apply_break_deduction(attendance, employee)
|
||
|
||
```
|
||
Delete the penalty break-write in `_check_and_create_penalty` (keep the penalty-record `create` above it and the activity log below it):
|
||
```python
|
||
# Deduct penalty minutes from attendance (adds to break deduction)
|
||
current_break = attendance.x_fclk_break_minutes or 0.0
|
||
attendance.sudo().write({
|
||
'x_fclk_break_minutes': current_break + deduction,
|
||
})
|
||
|
||
```
|
||
|
||
- [ ] **Step 7: Delete the kiosk call sites**
|
||
|
||
In `fusion_clock/controllers/clock_kiosk.py`, delete the line:
|
||
```python
|
||
api._apply_break_deduction(attendance, employee)
|
||
```
|
||
In `fusion_clock/controllers/clock_nfc_kiosk.py`, delete the line:
|
||
```python
|
||
api._apply_break_deduction(attendance, employee)
|
||
```
|
||
|
||
- [ ] **Step 8: Pyflakes the touched controllers/models** (catches a missed `pytz`/var reference instantly)
|
||
|
||
```bash
|
||
docker exec odoo-modsdev-app python3 -m pyflakes /mnt/extra-addons/fusion_clock/controllers/clock_api.py /mnt/extra-addons/fusion_clock/controllers/clock_kiosk.py /mnt/extra-addons/fusion_clock/controllers/clock_nfc_kiosk.py /mnt/extra-addons/fusion_clock/models/hr_attendance.py
|
||
```
|
||
Expected: no output (clean). If it flags `pytz` as unused in `hr_attendance.py`, that's fine only if no other code uses it — verify before removing the import (the absence/overtime crons still use `pytz`, so leave the import).
|
||
|
||
- [ ] **Step 9: Run to verify all Task 3 tests pass**
|
||
|
||
Sync, then run the module tests. Expected: all `test_manual_*`, `test_under_first_threshold_no_break`, `test_penalty_minutes_are_additive`, `test_master_toggle_off_zero_statutory`, `test_open_attendance_zero_break` PASS, and the existing NFC/kiosk/dashboard tests still PASS.
|
||
|
||
- [ ] **Step 10: Commit**
|
||
|
||
```bash
|
||
git -C "K:/Github/Odoo-Modules" add fusion_clock/models/hr_attendance.py fusion_clock/controllers/clock_api.py fusion_clock/controllers/clock_kiosk.py fusion_clock/controllers/clock_nfc_kiosk.py fusion_clock/tests/test_break_rules.py
|
||
git -C "K:/Github/Odoo-Modules" commit -m "feat(fusion_clock): auto-apply statutory break via one stored compute" -m "x_fclk_break_minutes is now statutory(worked_hours) + penalties, recomputed on every path including manual backend entry. Removes the four duplicated write sites (controller _apply_break_deduction + 3 call sites, auto-clock-out cron, penalty write)." -m "Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
git -C "K:/Github/Odoo-Modules" push
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: Retire `break_threshold_hours`; clean settings & migrate
|
||
|
||
**Files:**
|
||
- Modify: `fusion_clock/models/res_config_settings.py`
|
||
- Modify: `fusion_clock/views/res_config_settings_views.xml`
|
||
- Modify: `fusion_clock/data/ir_config_parameter_data.xml`
|
||
- Create: `fusion_clock/migrations/19.0.4.1.0/post-migrate.py`
|
||
- Modify: `fusion_clock/tests/test_settings.py`
|
||
|
||
- [ ] **Step 1: Add the dead-setting assertion** — in `fusion_clock/tests/test_settings.py`, add one line to `test_dead_settings_removed`:
|
||
|
||
```python
|
||
self.assertNotIn('fclk_break_threshold_hours', fields)
|
||
```
|
||
|
||
- [ ] **Step 2: Remove the settings field** — in `fusion_clock/models/res_config_settings.py`, delete:
|
||
|
||
```python
|
||
fclk_break_threshold_hours = fields.Float(
|
||
string='Break Threshold (hours)',
|
||
config_parameter='fusion_clock.break_threshold_hours',
|
||
default=4.0,
|
||
help="Only deduct break if shift is longer than this many hours.",
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 3: Fix the settings view** — in `fusion_clock/views/res_config_settings_views.xml`, replace the whole `fclk_auto_break` setting block:
|
||
|
||
OLD:
|
||
```xml
|
||
<setting id="fclk_auto_break" string="Auto-Deduct Break"
|
||
help="Automatically deduct unpaid break from worked hours on clock-out.">
|
||
<field name="fclk_auto_deduct_break"/>
|
||
<div class="content-group" invisible="not fclk_auto_deduct_break">
|
||
<div class="row mt16">
|
||
<label for="fclk_default_break_minutes" string="Duration (min)" class="col-lg-5 o_light_label"/>
|
||
<field name="fclk_default_break_minutes"/>
|
||
</div>
|
||
<div class="row mt8">
|
||
<label for="fclk_break_threshold_hours" string="Min. Shift" class="col-lg-5 o_light_label"/>
|
||
<field name="fclk_break_threshold_hours" widget="float_time"/>
|
||
</div>
|
||
</div>
|
||
</setting>
|
||
```
|
||
NEW:
|
||
```xml
|
||
<setting id="fclk_auto_break" string="Auto-Deduct Break"
|
||
help="Automatically deduct the statutory unpaid break from worked hours. Break lengths and thresholds are configured per province under Configuration → Break Rules.">
|
||
<field name="fclk_auto_deduct_break"/>
|
||
<div class="content-group" invisible="not fclk_auto_deduct_break">
|
||
<div class="row mt16">
|
||
<label for="fclk_default_break_minutes" string="Default scheduling break (min)" class="col-lg-5 o_light_label"/>
|
||
<field name="fclk_default_break_minutes"/>
|
||
</div>
|
||
<div class="text-muted small mt4">
|
||
Used as the default break when building shifts/schedules
|
||
(planned hours). Actual deductions follow the province Break Rules.
|
||
</div>
|
||
</div>
|
||
</setting>
|
||
```
|
||
|
||
- [ ] **Step 4: Remove the seed param** — in `fusion_clock/data/ir_config_parameter_data.xml`, delete:
|
||
|
||
```xml
|
||
<record id="config_break_threshold_hours" model="ir.config_parameter">
|
||
<field name="key">fusion_clock.break_threshold_hours</field>
|
||
<field name="value">4.0</field>
|
||
</record>
|
||
```
|
||
|
||
- [ ] **Step 5: Bump the version + create the migration**
|
||
|
||
First bump the manifest so the migration fires (installed `19.0.4.0.3` < manifest
|
||
`19.0.4.1.0`). In `fusion_clock/__manifest__.py`:
|
||
```python
|
||
'version': '19.0.4.1.0',
|
||
```
|
||
Then create `fusion_clock/migrations/19.0.4.1.0/post-migrate.py`:
|
||
|
||
```python
|
||
# -*- coding: utf-8 -*-
|
||
# Copyright 2026 Nexa Systems Inc.
|
||
# License OPL-1 (Odoo Proprietary License v1.0)
|
||
|
||
from odoo import api, SUPERUSER_ID
|
||
|
||
|
||
def migrate(cr, version):
|
||
"""Retire the single-threshold break param (superseded by per-rule
|
||
break1_after_hours), and force-recompute the now-computed break field so
|
||
existing closed attendances reflect the province rule + their penalties."""
|
||
cr.execute(
|
||
"DELETE FROM ir_config_parameter WHERE key = %s",
|
||
('fusion_clock.break_threshold_hours',),
|
||
)
|
||
env = api.Environment(cr, SUPERUSER_ID, {})
|
||
Attendance = env['hr.attendance']
|
||
field = Attendance._fields['x_fclk_break_minutes']
|
||
closed = Attendance.search([('check_out', '!=', False)])
|
||
if closed:
|
||
env.add_to_compute(field, closed)
|
||
closed.flush_recordset(['x_fclk_break_minutes'])
|
||
```
|
||
|
||
- [ ] **Step 6: Sync, upgrade, run tests**
|
||
|
||
Sync, then run the module tests. Expected: module upgrades cleanly and the `19.0.4.1.0` migration executes (installed `19.0.4.0.3` < manifest `19.0.4.1.0`; modsdev shows the INFO line, nexa/entech run `log_level=warn`), `test_dead_settings_removed` PASS, full `fusion_clock` suite green.
|
||
|
||
- [ ] **Step 7: Verify the param is gone and historical rows recomputed** (sanity)
|
||
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo shell -d modsdev --no-http 2>/dev/null <<'PY'
|
||
ICP = env['ir.config_parameter'].sudo()
|
||
print('threshold param:', ICP.get_param('fusion_clock.break_threshold_hours', 'ABSENT'))
|
||
print('default rule:', env['fusion.clock.break.rule'].search([('is_default','=',True)]).mapped('name'))
|
||
PY
|
||
```
|
||
Expected: `threshold param: ABSENT`; `default rule: ['Ontario']`.
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git -C "K:/Github/Odoo-Modules" add fusion_clock/models/res_config_settings.py fusion_clock/views/res_config_settings_views.xml fusion_clock/data/ir_config_parameter_data.xml fusion_clock/migrations/19.0.4.1.0/post-migrate.py fusion_clock/tests/test_settings.py fusion_clock/__manifest__.py
|
||
git -C "K:/Github/Odoo-Modules" commit -m "refactor(fusion_clock): retire break_threshold_hours; breaks now driven by Break Rules" -m "Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
git -C "K:/Github/Odoo-Modules" push
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: Full verification, docs, manual smoke
|
||
|
||
**Files:**
|
||
- Modify: `fusion_clock/CLAUDE.md`
|
||
|
||
- [ ] **Step 1: Full test run (whole module)**
|
||
|
||
Sync, then:
|
||
```bash
|
||
docker exec odoo-modsdev-app odoo -d modsdev --test-enable --test-tags /fusion_clock -u fusion_clock --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -120
|
||
```
|
||
Expected: all `fusion_clock` tests PASS, zero tracebacks. If anything fails, fix before continuing.
|
||
|
||
- [ ] **Step 2: Manual smoke (manager UI)** at http://localhost:8082
|
||
|
||
- Configuration → **Break Rules** exists; the **Ontario** row shows 5h→30 / 10h→30, Default ticked.
|
||
- Attendances → create a manual attendance, check-in 09:00 check-out 15:00 (6h) → **Break = 30**, Net = 5.5h, with no clock action.
|
||
- Edit that record's check-out to 19:00 (10h) → **Break = 60**, Net = 9.0h.
|
||
- Create a 4h attendance → **Break = 0**.
|
||
- Settings → the old "Min. Shift" threshold field is gone; the Auto-Deduct Break help points to Break Rules.
|
||
|
||
- [ ] **Step 3: Update the module CLAUDE.md** — in `fusion_clock/CLAUDE.md`:
|
||
|
||
- §4 Model Map: add a row — `fusion.clock.break.rule | models/clock_break_rule.py | Per-province statutory unpaid-break thresholds (2-tier).`
|
||
- §5 Clocking Flow: note that the break deduction is no longer a controller step — `x_fclk_break_minutes` is a stored compute (`statutory(worked_hours) + Σ penalties`) that fires on every path including manual backend entry; resolved rule via `hr.employee._get_fclk_break_rule()` (company province → default).
|
||
- §11 Settings Keys: remove `fusion_clock.break_threshold_hours`.
|
||
- §13 Gotchas: add — "Unpaid break is computed, not written: never `write({'x_fclk_break_minutes': ...})`; change the province rule (`fusion.clock.break.rule`) or `auto_deduct_break` instead. Penalty minutes are now strictly additive (the old `max()` that swallowed late-in penalties is gone)."
|
||
- Bump the version line in §1 to `19.0.4.1.0`.
|
||
|
||
- [ ] **Step 4: Commit the docs**
|
||
|
||
```bash
|
||
git -C "K:/Github/Odoo-Modules" add fusion_clock/CLAUDE.md
|
||
git -C "K:/Github/Odoo-Modules" commit -m "docs(fusion_clock): document province break rules + computed break field" -m "Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
git -C "K:/Github/Odoo-Modules" push
|
||
```
|
||
|
||
- [ ] **Step 5: Report** — summarize what changed, the behaviour-change note (penalties now additive), and that live deployment to entech (`odoo-entech`) is a separate step pending user sign-off.
|
||
|
||
---
|
||
|
||
## Self-Review (performed against the spec)
|
||
|
||
**1. Spec coverage**
|
||
- §4.1 model → Task 1. §4.2 resolver → Task 2. §4.3 stored compute → Task 3. §4.4 removals → Task 3 (writes) + Task 4 (setting/param/view). §4.5 UI/security/data → Task 1 (+ settings view in Task 4). §5 edge cases → tests in Tasks 1 & 3. §6 migration → Task 4. §7 tests → all six+ cases present across Tasks 1–3. §8 rollout → preamble + Task 5. ✓ No gaps.
|
||
|
||
**2. Placeholder scan** — every step has full code/commands; no TBD/TODO/"similar to". ✓
|
||
|
||
**3. Type/name consistency** — `break_minutes_for`, `_get_fclk_break_rule`, `_compute_fclk_break_minutes`, fields `break1_after_hours/break1_minutes/break2_after_hours/break2_minutes/is_default`, model `fusion.clock.break.rule`, access id `model_fusion_clock_break_rule`, action `action_fusion_clock_break_rule`, menu `menu_fusion_clock_break_rules` — all used identically across tasks. The compute folds `Σ penalty_minutes` (field `penalty_minutes` on `fusion.clock.penalty`, confirmed). ✓
|