Odoo-Modules/fusion_clock/docs/superpowers/specs/2026-06-04-remove-planning-dependency-design.md

Remove the Odoo Planning dependency from the Fusion Clock family

Date: 2026-06-04 Module: fusion_clock (absorbs fusion_planning, which is retired) Status: Design — awaiting spec review

---

1. Goal

Make the Fusion Clock product family fully Community-installable (no Odoo Enterprise planning dependency) and simplify the Entech deployment, while preserving every scheduling capability currently delivered through Odoo Planning. No feature is removed; the work is sequenced, not trimmed.

Driver (confirmed): Both — ship to clients without Enterprise and cut the barely-used Planning Gantt out of Entech.

2. Current state (verified)

fusion_clock itself does not depend on planning. Its deps are clean: hr_attendance, hr, portal, mail, resource. The entire Odoo-planning coupling lives in one bridge module, fusion_planning:

Coupling point	Where
depends: ['planning']	fusion_planning/__manifest__.py
_inherit = 'planning.slot' (+ x_fc_additional_resource_ids, auto-publish create())	fusion_planning/models/planning_slot.py
inherits planning.planning_view_form, uses planning.group_planning_manager	fusion_planning/views/planning_slot_views.xml
uses hr.employee.default_planning_role_id / planning_role_ids, menu under planning.planning_menu_settings	fusion_planning/views/hr_employee_role_views.xml
reads planning.slot for the portal Schedule tab (already merges with native schedule)	fusion_planning/controllers/portal_schedule.py
the Planning Gantt backend UI (web_gantt, Enterprise)	Odoo Planning

Live Entech data (LXC 111, DB admin, Enterprise):

Table	Rows
planning.slot	8 (7 published)
planning.role	1
fusion.clock.schedule (native per-day planner)	144
fusion.clock.shift (native templates)	6

The native per-day planner (fusion.clock.schedule + the OWL shift planner) is the real workhorse. Odoo Planning is essentially vestigial here.

No other module in the repo references planning or fusion_planning (the one grep hit in fusion_plating is the English word "Planning" in a selection — noise).

3. Decision & rationale

Chosen approach: re-fit Planning's logic onto the native per-day model (fusion.clock.schedule), extended to full feature parity. Retire fusion_planning by folding everything into fusion_clock.

Rejected alternative: vendor planning.slot + planning.recurrency + planning.planning wholesale. Why rejected:

1. The Gantt can't come to Community anyway. web_gantt is Enterprise. Vendoring planning.slot's datetime model still leaves us building a non-Gantt UI — so wholesale vendoring buys the heavy data model but not the UI.
2. Bugs live in the attendance pipeline, not the recurrence engine. fusion_clock's penalties (money), overtime, absence detection, reminders, portal and dashboard all read one contract: hr.employee._get_fclk_day_plan() off fusion.clock.schedule. Option 1 leaves that pipeline's data source untouched and confines new code to isolated, testable features. Wholesale vendoring forces either a dual schedule model or a rewire of that money-critical pipeline onto Planning's datetime model plus a migration of the 144 live rows — the highest-risk change possible, in exactly the code we most need to keep correct.
3. Reuse is still honoured. We copy the parts that copy cleanly (planning.role near-verbatim, the recurrence field design + repeat semantics, the mail templates) and re-fit only the generation loop — which is less code on the per-day model because it drops the resource-interval/DST math.

Two honest deltas vs Odoo Planning (only these):

• The Gantt drag-drop board → replaced by the native weekly OWL planner. Capability preserved, UX differs. (Accepted by owner.) Drag-drop is a possible future enhancement, out of scope here.
• Full resource-calendar-aware generation. Planning's recurrence consults resource work-intervals, flexible-resource flags and contract-end dates when generating. The native re-fit uses the employee weekday pattern and skips approved-leave days. This covers the real case; the heavy resource-calendar engine is overkill at Entech's scale (8 slots). Documented simplification.

4. End-state architecture

• fusion_clock becomes self-contained and Community-installable. It owns: native scheduling (existing), roles, recurrence, publish/notify (send), the portal Schedule tab, and open / multi / overnight shift support. Manifest deps unchanged (hr_attendance, hr, portal, mail, resource) — crucially no planning.
• fusion_planning is retired — its functionality is folded into fusion_clock, then it is uninstalled on Entech.
• The attendance automation contract (_get_fclk_day_plan) is unchanged in shape; new schedule capabilities resolve into the same single per-day work-window it already returns (see §5.4).

5. Detailed design

5.1 New model: fusion.clock.role (copied from planning.role)

Near-verbatim copy of planning/models/planning_role.py:

• name — Char, required, translate
• color — Integer, default random 1–11
• active — Boolean, default True
• sequence — Integer
• company_id — Many2one res.company (added for fusion multi-company consistency; Planning's role had none)
• Copy _get_color_from_code(is_open_shift) → returns the fullcalendar-compatible hex used to colour shifts on the portal Schedule tab.
• Drop resource_ids m2m and slot_properties_definition (unused here).

5.2 hr.employee — native role fields

• x_fclk_default_role_id — Many2one fusion.clock.role (fills new shifts)
• x_fclk_role_ids — Many2many fusion.clock.role (allowed roles)

(Migrated from default_planning_role_id / planning_role_ids.)

Employee Roles editor — port fusion_planning/views/hr_employee_role_views.xml to the native fields; reparent the menu from planning.planning_menu_settings to a fusion_clock config menu; gate with group_fusion_clock_manager.

5.3 fusion.clock.shift (existing template) — additions

• role_id — Many2one fusion.clock.role (a template can carry a default role)

5.4 fusion.clock.schedule (existing per-day) — additions

Part A additions (ship with the core dependency removal; the UNIQUE(employee_id, schedule_date) one-shift/day constraint is kept):

• role_id — Many2one fusion.clock.role; default from shift_id.role_id or employee_id.x_fclk_default_role_id. Drives portal colour/label.
• recurrence_id — Many2one fusion.clock.schedule.recurrence (set when a rule generated the row); ondelete='set null'.

In Part A the attendance contract _get_fclk_day_plan is completely unchanged (one posted row per employee per day, exactly as today).

Part B additions (parity for currently-unused Planning capabilities; built after A — see §10):

• is_open — Boolean; an open / unassigned shift available for self-assign.
• crosses_midnight — Boolean (overnight support).
• Constraint changes: replace the hard UNIQUE(employee_id, schedule_date) with a partial unique that still forbids accidental duplicate assigned rows while allowing intentional multiple shifts/day. Exact predicate finalised in the plan; use models.Constraint / models.UniqueIndex per Odoo-19 rules. employee_id becomes not required only when is_open = True (enforced by a Python @api.constrains).
• Overnight: relax _check_schedule_times to permit end_time <= start_time as crossing midnight (set crosses_midnight); update _compute_planned_hours ((24 - start) + end - break) and _get_fclk_scheduled_times (out datetime is next day).

The attendance contract stays single-window in Part B too. _get_fclk_day_plan(date) still returns one plan per employee per day:

• 0 assigned rows → not scheduled (unchanged).
• 1 assigned row → that row (unchanged).
• N assigned rows for the day → resolve to one work-window = earliest start → latest end across that day's assigned shifts; break = sum of breaks. This keeps penalties/overtime/absence math unchanged in shape while letting managers schedule split shifts and employees see each shift on the portal.
• is_open rows never feed any employee's plan until self-assigned.

This is the key safety property: multi-shift / overnight / open-shift live in the scheduling + UI + portal layers; the money-critical attendance layer keeps its existing one-window contract.

5.5 New model: fusion.clock.schedule.recurrence (design copied from planning.recurrency)

Fields (copied semantics):

• repeat_interval — Integer, default 1, CHECK(repeat_interval >= 1)
• repeat_unit — Selection day/week/month/year, default week
• repeat_type — Selection forever/until/x_times, default forever
• repeat_until — Date (required when repeat_type='until')
• repeat_number — Integer (>= 0)
• last_generated_date — Date, readonly
• company_id — Many2one res.company
• schedule_ids — One2many fusion.clock.schedule

Generation (_generate(stop_date=False)), re-fit of _repeat_slot onto the per-day model — much simpler (no resource-interval/DST math):

• Seed = the schedule entry the rule was created from (employee, weekday, start/end/break/role).
• Emit per-day fusion.clock.schedule rows at the cadence (repeat_interval × repeat_unit) up to a horizon = min(repeat_until, today + company.fclk_planning_generation_months, repeat_number cap).
• Skip dates the employee has an approved fusion.clock.leave.request (the "resource-calendar-aware" simplification).
• Generated rows are created in draft (must be posted/published to drive automation), carrying recurrence_id.
• Idempotent via last_generated_date (never regenerate past rows).
• _stop(from_date) deletes future draft rows of the rule (copy of Planning's _delete_slot); posted rows are kept.

Cron _cron_generate_recurring_schedules (copy of Planning's _cron_schedule_next shape) rolls the horizon forward. Odoo-19: no numbercall; active=True recurring cron.

5.6 Manager UI — native OWL planner extensions

The existing weekly planner (fusion_clock_shift_planner.js/xml + controller shift_planner.py) gains, alongside its current toolbar (Prev/This/Next week, Copy Previous Week, Export XLSX, Save, Post Schedule):

• Role shown/edited per cell (colour chip from role_id._get_color_from_code).
• Repeat… control in the cell editor → creates a fusion.clock.schedule.recurrence for that cell and generates rows; a backend list view manages/stops recurrences.
• Publish & Notify (generalises the existing post_week): pick a date range (default current week) + optional employee subset + optional message → posts matching draft rows and emails each affected employee their posted shifts for the range (see §5.8).
• Open shifts lane + bulk apply ("Apply Also To" replacement): create an open shift, or apply one cell's shift to several selected employees in one go.

All planner endpoints stay gated by group_fusion_clock_manager (unchanged).

5.7 Portal — fold the Schedule tab into fusion_clock

• Move the controller /my/clock/schedule into fusion_clock (controllers/portal_clock.py or a new portal_schedule.py), reading only fusion.clock.schedule (drop the planning.slot branch). Role colour/label come from role_id.
• Move the template fusion_planning.portal_schedule_page → fusion_clock.portal_schedule_page.
• Add the Schedule nav button inline in each fusion_clock portal page's .fclk-nav-bar (clock, timesheets, reports, payslips list, payslip detail), replacing fusion_planning's cross-module xpath inherits. Keep the .fclk-nav-bar structure stable (no shared-template refactor — see the known Odoo-19 xpath-inheritor gotcha).
• Self-assign / unassign of open shifts on the portal (respect a company "days before shift" setting, mirroring Planning's allow_self_unassign).

5.8 Mail templates (copied, reworded)

Port Planning's "send schedule" templates (planning/data/mail_template_data.xml) as the basis for fusion_clock's publish/notify email; reword for the Fusion portal link. The native fusion.clock.schedule.fclk_email_posted_week() is generalised to fclk_email_posted_range(employee, start, end). Follow Odoo-19 mail.template rules (no url_encode in QWeb; ctx is env.context).

5.9 Security & menus

• fusion.clock.role + fusion.clock.schedule.recurrence → ir.model.access.csv (manager write, user read as needed) + appropriate ir.rules.
• Employee Roles editor menu + a Recurrences menu under the fusion_clock configuration menu, gated group_fusion_clock_manager.

6. Data migration & retirement

6.1 Migration (in fusion_clock, guarded, idempotent)

A post-migration step (new module version) that runs only where Planning data exists (if 'planning.role' in env / 'planning.slot' in env):

1. Roles: each planning.role → find-or-create fusion.clock.role (name + color). Build an id map.
2. Employee roles: default_planning_role_id → x_fclk_default_role_id; planning_role_ids → x_fclk_role_ids (via the map).
3. Slots: each planning.slot → fusion.clock.schedule: resource_id→employee, local date + local float start/end (employee tz), break derived from span vs allocated_hours, role_id via map, state = posted if published else draft. Unusual slots (overnight / multi / open) handled by the §5.4 rules; anything unexpected is logged, not dropped. Idempotent via a one-time ir.config_parameter marker.

Volume is tiny (8 slots, 1 role) — fast and low-risk.

6.2 Retire fusion_planning

After fusion_clock provides the Schedule tab + roles + migration, uninstall fusion_planning (its portal templates, nav xpath-inherits and the x_fc_additional_resource_ids m2m are removed). fusion_clock now owns the Schedule tab inline. Optionally uninstall planning / web_gantt afterwards (separate, gated cleanup — destructive, so done last and only on sign-off).

6.3 Community-install guarantee

After the change, docker exec odoo-modsdev-app odoo -d fusion-dev -u fusion_clock must install on Community with no planning present (the migration is guarded; no runtime code references planning.*). Add this as a smoke check.

7. Entech rollout (gated, revert-on-failure)

1. Backup DB + module dir (outside the addons path).
2. Clone-verify: clone admin → upgrade fusion_clock (+migration) on the clone → assert: 144 native rows intact, 8 slots + 1 role migrated, roles + recurrence + portal Schedule render, attendance/penalty tests green.
3. Prod upgrade fusion_clock (stop → -u → start only if RC==0 + "Modules loaded", else restore backup, no restart). Clear asset bundle attachments; restart.
4. Uninstall fusion_planning.
5. Optional: uninstall planning / web_gantt (final, on sign-off).

8. Feature-parity matrix

Planning feature	Preserved as
Assign shifts, weekly board	Native OWL planner (extended)
Gantt drag-drop timeline	❗→ native weekly planner (Gantt can't be Community)
Shift templates	fusion.clock.shift (exists) + role_id
Roles + colour	fusion.clock.role (copied) + portal colour
Employee default/allowed roles	x_fclk_default_role_id / x_fclk_role_ids + editor
Recurrence (N day/week/month/year; forever/until/N-times) + cron	fusion.clock.schedule.recurrence (copied design)
Send / publish + email	Publish & Notify over a range (copied templates)
Multiple shifts/day	per-day model + single work-window contract (§5.4)
Overnight shifts	crosses_midnight (§5.4)
Open shifts + self-assign/unassign	is_open + portal self-assign
Auto-publish on create	native option (kept)
"Apply Also To" multi-employee	native bulk-apply
Allocated hours, portal My Schedule	planned_hours; Schedule tab folded in
Attendance/penalty/overtime/absence	UNCHANGED (per-day contract preserved)
Resource-calendar-aware generation	simplified: weekday pattern + skip leave

9. Testing strategy

• Unit: role + colour; recurrence generation across each repeat_type/unit; _stop deletes future drafts only; publish-range posts + emails; migration maps roles/slots/employee-roles; overnight planned_hours + scheduled_times; open-shift self-assign; multi-shift day-plan → correct single work-window.
• Regression: existing attendance / penalty / overtime / absence / dashboard tests stay green (data source unchanged).
• Community smoke: install fusion_clock on Community modsdev (no planning).
• Odoo-19 test runner: --http-port=0 --gevent-port=0, --test-tags /fusion_clock.

10. Sequencing

Decision: Part A and Part B ship together in one release (full Planning parity at once). The A/B labels below are internal build phases for the implementation plan (so each gets its own review checkpoint), not separate deployments.

• Phase A: drop the planning dep with parity for everything in real use — roles, recurrence, publish/notify, portal fold-in, migration, retire fusion_planning. (Per-day model keeps one-shift/day here.)
• Phase B: the remaining Planning capabilities — multi-shift/day, overnight, open shifts + self-assign, "Apply Also To" bulk — using the safe single-window attendance contract; isolated from the attendance engine.

Both phases are validated together before the single Entech rollout in §7.

11. Risks & open questions

• Recurrence correctness is new code — mitigated by isolation + unit tests across every repeat_type/unit and the idempotent last_generated_date guard.
• Multi-shift day-plan resolution (§5.4) is the subtlest change; covered by a dedicated test asserting the work-window and that penalties are unaffected.
• Licensing: the role model is generic, the recurrence loop is re-fit/original, and mail templates are reworded — so near-verbatim Enterprise code is minimal. Flag for the resale build; owner's call.
• Resolved: Parts A and B ship together in one release (§10).

12. Out of scope

• Drag-and-drop on the native planner (future enhancement).
• Full resource working-interval / flexible-resource / contract-end recurrence math (deliberate simplification, §3).
• Uninstalling planning from Entech is optional and gated separately.