Odoo-Modules/docs/superpowers/specs/2026-05-31-fusion-clock-statutory-break-design.md

Fusion Clock — Province-Aware Automatic Unpaid Break (2-tier)

• Date: 2026-05-31
• Module: fusion_clock
• Version bump: 19.0.4.0.3 → 19.0.4.1.0
• Status: Approved design, pending implementation plan
• Author: Claude Code (brainstormed with user)

1. Problem

Statutory unpaid meal breaks are jurisdiction-driven: a break is required after N1 hours of work, and a second break after a higher N2 threshold. Ontario, for example: a 30-minute eating period after 5 hours of work, and (per the user's policy) another 30 minutes after 10 hours. The deduction must be automatic and must apply on every way an attendance is recorded — including a manager manually adding or editing hours.

Audit of current behaviour (what exists today)

The deduction field is hr.attendance.x_fclk_break_minutes (minutes). Net hours are x_fclk_net_hours = worked_hours − x_fclk_break_minutes/60 (models/hr_attendance.py:261).

Break minutes are written from four places, all implementing variations of one rule:

1. controllers/clock_api.py::_apply_break_deduction (line 161) — on clock-out; reused by the PIN kiosk (controllers/clock_kiosk.py:158) and NFC kiosk (controllers/clock_nfc_kiosk.py:381). Logic: if worked_hours >= break_threshold_hours (default 4.0h) → set break to employee._get_fclk_break_minutes() (default 30), using max(new, current) so it doesn't wipe penalty minutes.
2. Auto-clock-out cron (models/hr_attendance.py:343) — same single-threshold write.
3. controllers/clock_api.py::_check_and_create_penalty (line 140) — adds penalty minutes into the same x_fclk_break_minutes field.

Gaps vs. requirement

1. Single tier only — one threshold (4h), one break (30m). No second break.
2. Not applied on manual entry — there is no create/write override on hr.attendance. A manager-created or manager-edited attendance gets break = 0. This is the central gap.
3. No province/country awareness — no jurisdiction field exists anywhere (location has address/timezone but no province; company has none). Threshold + amount are flat global config params.
4. First-break default is 4h, not 5h (Ontario is 5h).

2. Goals / Non-goals

Goals

• Statutory unpaid break applies automatically based on actual worked hours, on every path (portal, systray, PIN kiosk, NFC kiosk, auto-clock-out cron, and manual backend create/edit).
• Two tiers: first break after N1 hours, second break adds after N2 hours. Trigger is worked_hours >= N (inclusive; nothing under N1).
• Rules are defined per province/country in a table; an employee resolves its rule from its company's province, with a single global default fallback.
• Eliminate the duplicated deduction logic — one calculator, called everywhere.

Non-goals (YAGNI)

• Per-employee break-rule override (resolver is structured so this is a cheap add later).
• GPS/location-based jurisdiction detection.
• More than two tiers (the table is 2-tier; a 3rd break would be a future schema change).
• Changing the planned break concept used for scheduled-hours math.

3. Locked decisions

#	Decision	Choice
1	Rule model	Per-province table, 2-tier (fusion.clock.break.rule)
2	Jurisdiction source	Company province (company_id.state_id) + global default fallback
3	Override behaviour	Fully automatic — idempotent stored compute, recomputes on every save
4	Planned-vs-statute	Statutory only — the planned/scheduled break never affects the actual deduction

4. Design

4.1 New model fusion.clock.break.rule

models/clock_break_rule.py, _name = 'fusion.clock.break.rule', _description = 'Statutory Break Rule', _order = 'sequence, name'.

Field	Type	Default	Notes
name	Char (required)	—	e.g. "Ontario"
country_id	Many2one res.country	—	scopes the province picker
state_id	Many2one res.country.state	—	the province; domain on country_id
is_default	Boolean	False	global fallback when no province matches
break1_after_hours	Float	5.0	first break trigger N1
break1_minutes	Float	30.0	first break amount M1 (0 = disabled)
break2_after_hours	Float	10.0	second break trigger N2
break2_minutes	Float	30.0	second break amount M2 (0 = disabled)
sequence	Integer	10
active	Boolean	True

Constraints (models.Constraint, per repo Odoo-19 rule 9):

• break1_after_hours >= 0, break2_after_hours >= 0, minutes >= 0.
• When break2_minutes > 0: break2_after_hours > break1_after_hours (a misordered second tier is a config error).
• (Soft) at most one is_default = True — enforced in a Python @api.constrains rather than a partial unique index, to give a friendly message.

Method — break_minutes_for(self, worked_hours):

self.ensure_one()
total = 0.0
if self.break1_minutes and worked_hours >= self.break1_after_hours:
    total += self.break1_minutes
if self.break2_minutes and worked_hours >= self.break2_after_hours:
    total += self.break2_minutes
return total

>= is intentional and matches the requirement ("equal to or more than N1").

Seed (data/clock_break_rule_data.xml, noupdate="1"): one row — name="Ontario", state_id=base.state_ca_on, is_default=True, break1_after_hours=5.0, break1_minutes=30.0, break2_after_hours=10.0, break2_minutes=30.0. (Acting as both the Ontario match and the global fallback for this deployment. Other provinces can be added as rows.)

4.2 Jurisdiction resolver — hr.employee._get_fclk_break_rule()

self.ensure_one()
Rule = self.env['fusion.clock.break.rule'].sudo()
state = self.company_id.state_id
rule = Rule.browse()
if state:
    rule = Rule.search([('state_id', '=', state.id)], limit=1)
if not rule:
    rule = Rule.search([('is_default', '=', True)], limit=1)
return rule   # may be empty recordset → caller treats as 0 break

sudo() so the portal net-hours compute (run as the employee) can read the rule table without a direct ACL grant. Resolver is a single method → adding a per-employee override (x_fclk_break_rule_id) later is a two-line change.

4.3 hr.attendance — x_fclk_break_minutes becomes a stored compute

The field changes from a plain editable Float to a stored computed field — this is the single calculator that replaces all four write sites.

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 (by province "
         "rule, from actual hours worked) plus any penalty minutes.",
)

@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

Properties:

• Idempotent — same hours + same penalties always yield the same value; no drift, nothing to wipe.
• Fires on every path — worked_hours recomputes whenever check_in/check_out change, so portal, kiosk, NFC, cron, and manual backend create/edit all recompute automatically. This is what fixes the manual-entry gap.
• Mid-shift = 0 — check_out empty → statutory 0 (penalties, if any, still counted).
• Master toggle preserved — auto_deduct_break False → statutory 0 (penalties remain).
• _compute_net_hours is unchanged (still worked_hours − break/60); it now depends on a computed-stored field, which Odoo chains correctly.

The attendance form's Break field becomes read-only (consistent with "fully automatic"). views/hr_attendance_views.xml updated accordingly.

4.4 Removals (the de-duplication)

Remove	File	Replaced by
_apply_break_deduction method + its 3 call sites	controllers/clock_api.py:161, controllers/clock_kiosk.py:158, controllers/clock_nfc_kiosk.py:381	the compute
cron's x_fclk_break_minutes write	models/hr_attendance.py:343-346	the compute
penalty's current_break + deduction write	controllers/clock_api.py:140-144	the compute's Σ penalty_minutes
setting fclk_break_threshold_hours + fusion_clock.break_threshold_hours	models/res_config_settings.py:39, seed in data/ir_config_parameter_data.xml	per-rule break1_after_hours

Kept and untouched: hr.employee._get_fclk_break_minutes(), fusion_clock.default_break_minutes, fusion.clock.shift.break_minutes, fusion.clock.schedule.break_minutes — these are the planned break (used to compute scheduled planned_hours), a separate concept from the actual worked-hours deduction. Decision #4 keeps them out of the deduction path.

Kept: the auto_deduct_break master toggle (now gates the statutory portion only).

4.5 UI / security / data

• Menu: Fusion Clock → Configuration → Break Rules (new ir.actions.act_window + list/form views in views/clock_break_rule_views.xml), gated to group_fusion_clock_manager. Add the menu item in views/clock_menus.xml.
• Security: security/ir.model.access.csv — fusion.clock.break.rule: manager = full CRUD; team-lead/user = read (or none — the resolver uses sudo, so no direct grant is strictly required; grant manager full, no portal access).
• Manifest data: add data/clock_break_rule_data.xml (after security, before crons) and views/clock_break_rule_views.xml (with the other config views, before clock_menus.xml). Bump version to 19.0.4.1.0.

5. Edge cases

• No rule resolvable (no province match, no default) → statutory 0. The seeded default prevents this in practice.
• Company has no state_id → falls to the default rule.
• break2_after_hours <= break1_after_hours → blocked by constraint.
• Penalty created after clock-out → x_fclk_penalty_ids change retriggers the compute; final break = statutory + penalty (preserves today's combined-field semantics, reported as one "Break" number).
• Open attendance (no checkout) → break 0; recomputed when it's closed.
• Worked hours exactly at a boundary (5.0h, 10.0h) → tier fires (>=).

6. Migration / upgrade

• On upgrade, flipping x_fclk_break_minutes to store=True compute makes Odoo recompute it for all existing rows. For closed attendances this re-derives break from worked_hours + linked penalties using the seeded Ontario rule — which is the intended corrected value. Any historical hand-edited break values are replaced (acceptable per Decision #3, "fully automatic"). Call this out in the change log.
• No pre/post migration script is required; the recompute is automatic. (If we later want to avoid touching very old periods, a guarded post-migrate could pin them — out of scope for now.)

7. Testing (tests/test_break_rules.py, @tagged('-at_install','post_install','fusion_clock'))

1. break_minutes_for: 4.99h→0, 5.0h→30, 9.99h→30, 10.0h→60.
2. Resolver: company in Ontario → Ontario rule; company with unset/other province → default.
3. Manual backend create of a closed attendance (check_in/out spanning 6h) → break 30, net = worked − 0.5. Manual edit extending to 10h → break 60. (This is the headline gap; assert it directly via env['hr.attendance'].create(...), not via a controller.)
4. Penalty additivity: 6h + one 15-min penalty record → break 45.
5. Master toggle off (auto_deduct_break=False) → statutory 0 (penalty-only).
6. Constraint: break2_after_hours <= break1_after_hours raises.

Run (note ephemeral ports per repo CLAUDE.md):

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

8. Rollout notes

• Dual-path write during dev: edit files in both K:\Github\odoo-modsdev\addons\fusion_clock (Docker-mounted, for tests) and K:\Github\Odoo-Modules\fusion_clock (git); commit from the git path only. (Per project memory.)
• Live target is entech (odoo-entech); deploy after local tests pass and user review.
• Asset/version bump already covered by the manifest version change.

9. Open questions

None — all four design forks resolved (see §3).