feat(billing): wire HTTP controllers to API handlers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,17 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Editor / OS noise
+.DS_Store
+*.swp
+*.swo
+.vscode/
+.idea/
+
+# Odoo runtime
+*.pyc-tmp
+
+# Local-only diagnostic logs from test runs
+_test_*.log

CLAUDE.md

@@ -12,9 +12,26 @@
 3. **Backend OWL**: Use standalone `rpc()` from `@web/core/network/rpc`. NOT `useService("rpc")`. `static props = []` not `{}`.
 4. **HTTP routes**: `type="jsonrpc"` — NOT `type="json"` (deprecated).
 5. **res.config.settings**: Only boolean/integer/float/char/selection/many2one/datetime. NO Date fields.
+   **`config_parameter=` Boolean fields don't round-trip `False` as a string.** Odoo's `set_values()` calls `IrConfigParameter.set_param(key, value)`, and `set_param` deletes the row when `value` is falsy (False / None / empty). So writing `False` to a Boolean config field means the param no longer exists in `ir_config_parameter`; a subsequent `get_param(key)` returns the *default* (Python `False`), not `'False'`. Test like `self.assertFalse(ICP.get_param('...'))` — never `assertEqual(..., 'False')`. (Integer/Float/Char go through `repr(value)` / strip, so they DO persist as strings — `'90'`, `'0'`, etc.) Source: `odoo/addons/base/models/res_config.py::set_values` and `ir_config_parameter.py::set_param`.
 6. **res.groups**: NO `users` field, NO `category_id` field.
+   **res.users**: field was renamed `groups_id` → `group_ids` (also `all_group_ids` for implied). The plural form is gone; using `groups_id` raises `ValueError: Invalid field 'groups_id' in 'res.users'`.
+   **`ir.ui.view`**: same rename — view-level visibility gating uses `group_ids`, not `groups_id`. A record like `<field name="groups_id" eval="[(4, ref('base.group_system'))]"/>` on an `ir.ui.view` raises `ValueError: Invalid field 'groups_id' in 'ir.ui.view'` at module install. (The XML *attribute* `groups="base.group_system"` on form elements like `<page>`, `<button>`, `<field>` is unrelated and still works.)
+   **`ir.rule` `groups` field is additive, not restrictive.** A rule with `groups=[some_group]` applies ONLY to users in that group — it does NOT restrict non-members. So `domain_force=[(1,'=',1)]` + `groups=[base.group_system]` does NOT mean "only admins see rows"; it means "admins see all rows (and the rule is silent on everyone else)". Non-admins are gated by the ACL (`ir.model.access.csv`), not the rule. To truly restrict by group at the rule layer, pair a global rule (`groups=[]`, `domain_force=[(0,'=',1)]` = block-all baseline) with a group-scoped allow rule. Default to letting the ACL do the gating; use rules for row-level filters that ACLs cannot express.
 7. **Search views**: NO `group expand="0"` syntax.
 8. **SCSS imports**: `@import "./partial"` is FORBIDDEN in Odoo 19 custom SCSS. It prints a warning and silently falls back to the old cached bundle. Register every SCSS file (including `_partial.scss` tokens) as a separate entry in `web.assets_backend`. Put tokens first; Odoo concatenates bundle files so SCSS variables/mixins from the first file are visible to every later file.
+9. **SQL constraints & indexes**: Odoo 19 dropped `_sql_constraints = [(name, def, msg), ...]` and the `init()`/raw-SQL pattern. Both still parse but only emit a warning and are silently ignored. Use declarative class attributes instead:
+   ```python
+   _check_qty_positive = models.Constraint('CHECK (qty > 0)', 'Quantity must be positive.')
+   _user_time_idx = models.Index('(user_id, event_time DESC)')
+   ```
+   The attribute name after the leading underscore becomes the SQL object name suffix (`{table}_{suffix}`). `models.Index` accepts `DESC`, `WHERE` predicates, and `USING btree (...)`. Sources: `odoo/orm/model_classes.py` (warns at registry build), `odoo/orm/table_objects.py` (Constraint + Index classes).
+10. **`res.users._login` is an instance method in Odoo 19**, not a classmethod as in earlier versions. Signature is `def _login(self, credential, user_agent_env)` — there is no `db` parameter. Override it like any normal instance method (`super()._login(credential, user_agent_env)`). When called via `authenticate()` on an empty recordset, `self` carries the right env. Older recipes that build a separate `api.Environment` from `odoo.modules.registry.Registry(db)` no longer apply. Source: `odoo/addons/base/models/res_users.py:760`.
+11. **Inherited `ir.ui.view` records cannot have `groups`/`group_ids` on the record itself.** Odoo 19 raises `ParseError: Inherited view cannot have 'groups' defined on the record. Use 'groups' attributes inside the view definition` at install time. Move the gate to the inner XML nodes — every `<button>`, `<page>`, `<field>`, `<xpath>`, `<group>` etc. supports a `groups="base.group_system"` attribute. For an inherited form with a smart button + admin tab, put `groups=` on the button and the page individually; leave the `<record model="ir.ui.view">` clean.
+12. **`mail.template` QWeb/inline_template `ctx` IS `self.env.context`** — not a nested dict you can pass. `MailRenderMixin._render_eval_context()` sets `ctx = self.env.context`, so `ctx.get('foo')` in subject/body resolves to `env.context.get('foo')`. To pass dynamic data to a template, spread keys directly into the context: `tmpl.with_context(**my_data).send_mail(res_id, ...)`. Calling `tmpl.with_context(ctx=my_data)` puts the dict at `env.context['ctx']`, and the template's `ctx.get('foo')` becomes `env.context.get('foo')` → `None` (looks like a silent rendering bug — subject ends up blank).
+13. **`ir.cron` dropped `numbercall`** in Odoo 19. Old recipes set `<field name="numbercall">-1</field>` for "run forever"; that now raises `ValueError: Invalid field 'numbercall' in 'ir.cron'` at install time. Just omit the field — recurring crons keep running as long as `active=True`. Source: `odoo/addons/base/models/ir_cron.py` field list.
+14. **`cr.commit()` / `cr.rollback()` raise AssertionError inside `TransactionCase`** — they are NOT silent no-ops in Odoo 19. The test cursor explicitly refuses both ("Cannot commit or rollback a cursor from inside a test, this will lead to a broken cursor when trying to rollback the test. Please rollback to a specific savepoint instead..."). For cron/worker code that needs per-row isolation so one bad row doesn't roll back the whole batch, use `with self.env.cr.savepoint(): ...` inside the loop instead of `cr.commit()`. Savepoints work in both prod (under the outer cron transaction) and tests (under the outer test transaction). The cron transaction commits the whole batch when the method returns; in tests everything rolls back cleanly. Source: `odoo/sql_db.py::TestCursor.commit` and `Cursor.savepoint()`.
+
+15. **There is NO `sale.subscription` model in Odoo 19** (Enterprise `sale_subscription`). A subscription is a **`sale.order`** with `is_subscription=True`, `plan_id` → **`sale.subscription.plan`** (the recurrence), plus `subscription_state` / `next_invoice_date` / `recurring_monthly`. Any Many2one or relation that targets "a subscription" must point at `sale.order` (filter `domain=[('is_subscription','=',True)]`) — **not** `sale.subscription`, which does not exist and fails at install. The surviving `sale.subscription.*` records are only the plan + wizards/reports (`sale.subscription.plan`, `sale.subscription.report`, `sale.subscription.change.customer.wizard`, `sale.subscription.close.reason.wizard`). Verified on live `nexamain` (odoo-nexa, 19.0): `SELECT model FROM ir_model WHERE model LIKE 'sale.subscription%'`.
 
 ## Card Styling — Copy Odoo's Kanban Pattern
 Don't rely on `var(--bs-border-color)` or `var(--bs-body-bg)` for card surfaces — they drift between themes/addons and often render **invisible**. Odoo's own kanban (`.o_kanban_record`) uses **explicit hex** values:
@@ -79,8 +96,15 @@ Odoo content-hashes the compiled bundle URL (`/web/assets/<hash>/...`). When CSS
 - **fusion_clock** is currently being modified in Cursor — always read files fresh before editing, don't assume you know the current state
 
 ## Workflow
-- Local dev: `docker exec odoo-dev-app odoo -d fusion-dev -u <module> --stop-after-init`
-- Local URL: http://localhost:8069
+- Local dev: `docker exec odoo-modsdev-app odoo -d fusion-dev -u <module> --stop-after-init`
+- Local URL: http://localhost:8082
+- **Running module tests requires ephemeral ports.** The dev container's main Odoo process holds 8069 and 8072; a `docker exec ... odoo --test-enable` will die with `Address already in use` unless you also pass `--http-port=0 --gevent-port=0`. This is because Odoo 19 forces `http_spawn()` when `--test-enable` is set, even when `--no-http` is passed. Canonical test invocation:
+  ```bash
+  docker exec odoo-modsdev-app odoo -d fusion-dev --test-enable --test-tags /<module> \
+      -u <module> --stop-after-init --http-port=0 --gevent-port=0 2>&1 | tail -60
+  ```
+- **`fusion_centralize_billing` tests run on odoo-trial (VM 316).** Local dev is Community and cannot install this module. Use `bash scripts/fcb_test_on_trial.sh` from the repo root. The script uses `--http-port 8070` to avoid the port 8069 conflict with the live odoo-trial-app container. Pass = `FCB_EXIT=0`. Takes ~1-2 min.
+- **Python deps not bundled with `odoo:19` image:** `user_agents` (used by `fusion_login_audit`), and likely others. Install ephemerally with `docker exec -u 0 odoo-modsdev-app pip install <pkg> --break-system-packages`. The install is LOST when the container is recreated (e.g. `docker compose up -d` after a compose edit). When this happens, the symptom is `ModuleNotFoundError` deep in the auth or report code. Re-run the pip install. A persistent fix would be a custom Dockerfile or a startup hook on the compose service — not done yet.
 - Test before deploying. Edit existing files — don't create unnecessary new ones.
 
 ## PDF Preview — Prefer fusion_pdf_preview Over Downloads/New-Tab

docs/superpowers/specs/2026-05-26-fusion-login-audit-design.md

@@ -0,0 +1,444 @@
+# Fusion Login Audit — Design Spec
+
+**Status:** Approved, ready for implementation planning
+**Date:** 2026-05-26
+**Author:** Brainstormed with the user (Gurpreet) for the Westin Healthcare Odoo 19 deployment
+**Target module path:** `K:\Github\Odoo-Modules\fusion_login_audit\`
+**Production deploy target:** `/opt/odoo/custom-addons/fusion_login_audit/` on `odoo-westin` (VM 101, worker1, 192.168.1.40)
+**Production DB:** `westin-v19` (Odoo 19, PostgreSQL)
+
+## Background and motivation
+
+A spot audit of user `info@gsafinancialconsulting.com` ("GSA Accounting", uid 63) revealed Odoo's built-in login tracking is effectively unusable for compliance:
+
+- `res.users.log` rows are pruned by the daily `_gc_user_logs` cron — only the most recent login per user survives. For GSA Accounting the entire history collapsed to a single row at `2026-04-22 20:24 EDT`.
+- `/var/log/odoo` on the production VM is empty because Odoo is configured at `log_level=warn` with stdout-only logging; INFO-level auth lines aren't captured anywhere.
+- The container's json log is 444 KB and rotates frequently — nothing about the user remains.
+- The existing `network_logger` module records outbound HTTP traffic from Odoo (uid=1 always), not user activity.
+
+Result: today there is **no durable record** of who logged in, when, from where, or how often. A user with `base.group_system` + Technical Features and no 2FA — like GSA Accounting — could be active for months without any reconstructable trail.
+
+This module closes that gap with a dedicated audit table that survives Odoo's GC, captures successful and failed authentications, surfaces results in the user form, and alerts admins on suspicious failure bursts.
+
+## Goals
+
+1. **Durable audit trail** of every password-authenticated login (success and failure) on `westin-v19`.
+2. **Per-user visibility** for Settings admins via a tab + smart button on `res.users`.
+3. **Failure-burst alerting** to admins on a configurable consecutive-failure threshold.
+4. **Geo-enrichment** of IPs out-of-band so authentication latency is unaffected.
+5. **Zero risk to the auth path** — an audit-write failure must never block a real login.
+
+## Non-goals (v1)
+
+- Logging every HTTP request / page view (explicitly de-scoped during brainstorming).
+- Logging session resume events from auth cookies.
+- API-key authentication (`credential['type'] == 'apikey'`) — bypasses `_check_credentials`. Documented as a known gap; addressable in a follow-up.
+- OAuth / SSO logins — no OAuth provider configured on westin-v19.
+- Self-service "view my own login activity" for end users — visibility is admin-only.
+- Auto-disabling users on failed logins — flagged as a self-service DoS vector during brainstorming.
+
+## Architecture overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                       Odoo authentication path                       │
+│                                                                      │
+│   /web/login → res.users._login() → res.users._check_credentials()  │
+│                                  ↓                                   │
+│                          (on success)                                │
+│                                  ↓                                   │
+│                    res.users._update_last_login()                    │
+│                                  ↓                                   │
+│             ┌────────────────────┴────────────────────┐              │
+│             │                                          │              │
+│             ▼                                          ▼              │
+│  fusion.login.audit (sudo create)        Odoo's existing res_users_log │
+│  result='success' + IP + UA                                          │
+│                                                                      │
+│   (on AccessDenied)                                                  │
+│             ↓                                                        │
+│  fusion.login.audit (sudo create)                                    │
+│  result='failure' + failure_reason + attempted_login                 │
+│             ↓                                                        │
+│  _fc_recent_failure_count() >= threshold?                            │
+│             ↓ yes                                                    │
+│  _fc_send_failure_alert() → mail.mail to base.group_system           │
+└──────────────────────────────────┬──────────────────────────────────┘
+                                    │
+              ┌─────────────────────┼─────────────────────┐
+              ▼                     ▼                     ▼
+   cron: cron_geo_enrich   cron: cron_retention_gc    UI surfaces:
+   every 5 min             daily 03:00 UTC            - smart button on res.users
+   - reverse DNS           - delete rows older than   - "Login Activity" tab
+   - ip-api.com lookup       x_fc_login_audit_        - Settings → Technical →
+   - 30-day local cache      retention_days             Login Audit menus
+                                                       - Settings page section
+```
+
+The auth-path hooks are synchronous (must run inside the request). Geolocation, alerting, and retention are out-of-band so they cannot affect login latency.
+
+## Module skeleton
+
+```
+fusion_login_audit/
+├── __manifest__.py
+├── __init__.py
+├── models/
+│   ├── __init__.py
+│   ├── res_users.py              # extends res.users with capture hooks + computed fields + smart-button action
+│   ├── fusion_login_audit.py     # the new audit record model
+│   └── res_config_settings.py    # alert threshold + window + retention settings
+├── data/
+│   ├── ir_cron_data.xml          # cron_geo_enrich + cron_retention_gc
+│   └── mail_template_data.xml    # failed-login alert template
+├── security/
+│   ├── security.xml              # record rule: read for base.group_system only
+│   └── ir.model.access.csv
+├── views/
+│   ├── fusion_login_audit_views.xml   # list / form / kanban / search
+│   ├── res_users_views.xml            # tab + smart button
+│   ├── res_config_settings_views.xml  # Settings section
+│   └── menus.xml                       # Settings → Technical → Login Audit
+├── tests/
+│   ├── __init__.py
+│   ├── test_login_audit.py
+│   └── test_security.py
+└── static/
+    └── description/
+        └── icon.png              # copied from C:\Users\gsing\Downloads\fusion logs.png
+```
+
+**Manifest highlights**
+
+- `version='19.0.1.0.0'` (project naming convention)
+- `license='OPL-1'` (matches `fusion_accounts`)
+- `depends=['base', 'mail']`
+- `category='Tools'`
+- `application=False` (it's a technical addon, not a top-level app)
+
+**Dependencies (Python):** none new. Uses the `user_agents` library already shipped with Odoo. Geolocation calls `http://ip-api.com/json/<ip>` via the standard `requests` library (no API key required, 45 req/min free tier).
+
+**Field naming:** new fields on existing models (`res.users`, `res.config.settings`) use the `x_fc_*` prefix per project CLAUDE.md. The new `fusion.login.audit` model uses unprefixed field names.
+
+## Data model
+
+### `fusion.login.audit` (new model, table `fusion_login_audit`)
+
+| Field | Type | Notes |
+|---|---|---|
+| `user_id` | Many2one(`res.users`, `ondelete='set null'`) | Null if attempted login didn't match any user |
+| `attempted_login` | Char(255), indexed | Always set — even on unknown-user failures |
+| `result` | Selection(`success`, `failure`) | Indexed |
+| `failure_reason` | Selection(`bad_password`, `unknown_user`, `disabled_user`, `2fa_failed`, `other`) | Null on success |
+| `event_time` | Datetime, indexed, default `fields.Datetime.now()` | UTC; displayed in user TZ via standard widget |
+| `ip_address` | Char(45) | IPv6-safe length |
+| `ip_hostname` | Char(255) | Reverse DNS, populated by geo cron |
+| `country_code` | Char(2), indexed | ISO-3166-1 alpha-2; null until cron runs |
+| `country_name` | Char(64) | |
+| `city` | Char(128) | |
+| `geo_state` | Char(64) | Region/state name |
+| `geo_lookup_state` | Selection(`pending`, `done`, `private_ip`, `internal`, `failed`) | Drives the geo cron worklist; `internal` = no HTTP request was attached |
+| `user_agent_raw` | Char(512) | The full UA header |
+| `browser` | Char(64) | e.g. "Chrome 140" — parsed |
+| `os` | Char(64) | e.g. "Windows 11" — parsed |
+| `device_type` | Selection(`desktop`, `mobile`, `tablet`, `bot`, `unknown`) | From `user_agents` |
+| `database` | Char(64) | Multi-DB safety — which DB was logged into |
+
+**Indexes (in addition to the column-level `indexed=True`):**
+- `(user_id, event_time DESC)` — per-user history
+- `(attempted_login, event_time DESC)` — failure-burst detection by login string
+- `(geo_lookup_state, event_time)` — cron worklist
+
+**No `_inherit = ['mail.thread']`** — audit rows are append-only and should not have chatter.
+
+### `res.users` additions (per CLAUDE.md `x_fc_*` convention)
+
+| Field | Type | Notes |
+|---|---|---|
+| `x_fc_login_audit_ids` | One2many(`fusion.login.audit`, `user_id`) | Backs the tab + smart-button count |
+| `x_fc_login_audit_count` | Integer, compute, store=False | Smart-button label |
+| `x_fc_last_successful_login` | Datetime, compute, store=True | Indexed; cheap "last seen" lookup |
+| `x_fc_last_login_ip` | Char(45), compute, store=True | Surfaces last source IP in the form header |
+
+The `store=True` computes are triggered by the create on `fusion.login.audit` (via `@api.depends('x_fc_login_audit_ids.event_time', 'x_fc_login_audit_ids.result')`).
+
+### `res.config.settings` additions
+
+Booleans / integers only (per CLAUDE.md — no Date fields on settings):
+
+| Field | Default | Notes |
+|---|---|---|
+| `x_fc_login_audit_retention_days` | 365 | Retention GC cron honors this; 0 = keep forever |
+| `x_fc_login_audit_alert_threshold` | 5 | Consecutive failures before alert |
+| `x_fc_login_audit_alert_window_min` | 15 | Time window in minutes for "consecutive" |
+| `x_fc_login_audit_alert_enabled` | True | Master kill-switch for alert emails |
+
+Each is backed by an `ir.config_parameter` (`fusion_login_audit.retention_days`, etc.) so changes from the Settings page persist.
+
+### Multi-company
+
+`fusion.login.audit` is intentionally **company-agnostic**. Logins happen before any company context is established; synthesizing one would either break the unknown-user case or require a "system company" placeholder. Settings admins see all rows globally.
+
+## Capture flow
+
+### Successful login (`_update_last_login`)
+
+```python
+def _update_last_login(self):
+    result = super()._update_last_login()
+    try:
+        self._fc_record_login_event(result='success')
+    except Exception:
+        _logger.exception("fusion_login_audit: failed to record success row for %s", self.login)
+    return result
+```
+
+Called by Odoo only after the credential check has passed. Super() runs first so Odoo's own bookkeeping is unaffected.
+
+### Failed login on known user (`_check_credentials`)
+
+```python
+def _check_credentials(self, credential, env):
+    try:
+        return super()._check_credentials(credential, env)
+    except AccessDenied:
+        try:
+            self._fc_record_login_failure(credential, reason='bad_password')
+            if self._fc_recent_failure_count(credential) >= self._fc_alert_threshold():
+                self._fc_send_failure_alert(credential)
+        except Exception:
+            _logger.exception("fusion_login_audit: failed to record/alert failure")
+        raise
+```
+
+TOTP failures (from `auth_totp`) also raise `AccessDenied` and are caught here. Distinguish via `credential.get('type') == 'totp'` to set `failure_reason='2fa_failed'`.
+
+### Failed login on unknown user (`_login` classmethod)
+
+```python
+@classmethod
+def _login(cls, db, credential, user_agent_env):
+    try:
+        return super()._login(db, credential, user_agent_env)
+    except AccessDenied:
+        try:
+            cls._fc_record_unknown_user_failure(db, credential, user_agent_env)
+        except Exception:
+            _logger.exception("fusion_login_audit: failed to record unknown-user failure")
+        raise
+```
+
+Without this override, unknown-user attempts never reach `_check_credentials` and would silently disappear from the audit. The classmethod sets `user_id=None` and stores the attempted login string.
+
+### Context extraction (`_fc_build_event_vals`)
+
+Single helper shared by all three paths:
+
+```python
+def _fc_build_event_vals(self, result, attempted_login, failure_reason=None):
+    from odoo.http import request
+    vals = {
+        'attempted_login': attempted_login,
+        'result': result,
+        'failure_reason': failure_reason,
+        'event_time': fields.Datetime.now(),
+        'database': self.env.cr.dbname,
+        'geo_lookup_state': 'pending',
+    }
+    if request and request.httprequest:
+        vals['ip_address'] = request.httprequest.remote_addr  # respects proxy_mode
+        ua_str = request.httprequest.user_agent.string or ''
+        vals['user_agent_raw'] = ua_str[:512]
+        from user_agents import parse as ua_parse
+        ua = ua_parse(ua_str)
+        vals['browser'] = f"{ua.browser.family} {ua.browser.version_string}"[:64]
+        vals['os'] = f"{ua.os.family} {ua.os.version_string}"[:64]
+        vals['device_type'] = (
+            'mobile' if ua.is_mobile else
+            'tablet' if ua.is_tablet else
+            'bot' if ua.is_bot else
+            'desktop' if ua.is_pc else 'unknown'
+        )
+    else:
+        vals['ip_address'] = 'internal'
+        vals['user_agent_raw'] = '<no-request>'
+        vals['geo_lookup_state'] = 'internal'  # distinct from private_ip; cron skips both
+    return vals
+```
+
+### Write semantics
+
+- All writes use `self.env['fusion.login.audit'].sudo().create(vals)` — low-privilege users can still generate their own audit rows despite the read-only record rule.
+- `mail_create_nolog=True` context to avoid chatter noise.
+- The password value is **never** present in `vals` and is hard-stripped from any `credential` dict before logging. A regression test asserts this.
+
+## Async geolocation cron (`cron_geo_enrich`)
+
+**Schedule:** every 5 minutes, `numbercall=-1`, `priority=10`.
+
+**Worker logic:**
+
+1. Select 100 oldest rows where `geo_lookup_state='pending'`.
+2. For each row:
+   - **Private-IP shortcut:** if `ip_address` is in `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `::1`, or `fe80::/10` → set `geo_lookup_state='private_ip'`, `country_code='--'`, `city='Private network'`.
+   - **Cache check:** look for any prior row with the same `ip_address` and `country_code IS NOT NULL` and `event_time > now() - interval '30 days'`. If found, copy `country_code` / `country_name` / `city` / `geo_state` / `ip_hostname` locally; set state `done`. No external call.
+   - **Reverse DNS:** `socket.gethostbyaddr(ip)` with `socket.setdefaulttimeout(1.5)`.
+   - **HTTP lookup:** `requests.get('http://ip-api.com/json/' + ip, params={'fields': 'status,country,countryCode,regionName,city'}, timeout=3, headers={'User-Agent': 'Odoo-FusionLoginAudit/19.0'})`. The call passes through `network_logger` automatically.
+   - On `status='success'` → fill fields, set state `done`.
+   - On HTTP error, timeout, or `status='fail'` → set state `failed` (no retry).
+3. `self.env.cr.commit()` after each row so one bad IP cannot roll back the batch.
+4. **Rate limit defense:** if the response header `X-Rl` is `'0'`, break early and leave remaining rows as `pending` for the next run.
+
+**Privacy:** the only outbound data is the IP itself. No user identifiers, no Odoo URL, no headers beyond `User-Agent: Odoo-FusionLoginAudit/19.0`. All outbound calls are auditable in `network_logger`.
+
+## UI surfaces
+
+### `res.users` form view
+
+- **Smart button** in the button box, gated `groups="base.group_system"`:
+  ```
+  ┌──────────────┐
+  │ 🔑 N Logins  │
+  └──────────────┘
+  ```
+  Click → opens `fusion.login.audit` list view filtered to this user (`domain=[('user_id', '=', active_id)]`).
+- **New tab "Login Activity"** appended after existing tabs, gated `groups="base.group_system"`:
+  - Header summary: `x_fc_last_successful_login`, `x_fc_last_login_ip` (readonly).
+  - Embedded one2many tree on `x_fc_login_audit_ids`, `limit="30"`, columns: `event_time`, `result` (colored badge), `ip_address`, `country_code` (with flag emoji display), `browser`, `os`, `failure_reason`.
+  - Tree is `create="false" edit="false" delete="false"`.
+  - "View full history →" button below the tree, same action as the smart button.
+
+### Standalone views for `fusion.login.audit`
+
+- **List view:** `event_time`, `user_id` (clickable), `attempted_login` (only when `user_id IS NULL`), `result` badge, `ip_address`, `country_code`, `city`, `browser`, `device_type`. Default sort `event_time DESC`.
+- **Search view:** filters for "Successes", "Failures", "Last 24h", "Last 7d", "Last 30d", "Unknown users (no user_id)"; group-by IP / country / user.
+- **Form view:** readonly; collapsible "Raw" section for `user_agent_raw`, `ip_hostname`, `database`, `geo_lookup_state`.
+- **Kanban view:** grouped by `result`, color-coded green/red.
+
+### Menus
+
+Under **Settings → Technical → Login Audit**:
+- "Login Events" → default list view
+- "Failed Logins (24h)" → list view with default `[('result', '=', 'failure'), ('event_time', '>=', context_today() - 1)]`
+
+### Settings page
+
+New "Login Audit" section in **Settings → General Settings** (gated `groups="base.group_system"`):
+- "Retention period (days)" — integer, help: "0 = keep forever"
+- "Alert threshold" — integer
+- "Alert window (minutes)" — integer
+- "Send failed-login alerts" — boolean
+
+## Security
+
+### Group
+
+No new group created. Read is bound to existing `base.group_system`. Rationale: brainstorming decision was "Settings admins only" — reusing the existing group avoids an extra checkbox to manage.
+
+### Model access (`ir.model.access.csv`)
+
+| Group | Read | Write | Create | Unlink |
+|---|---|---|---|---|
+| `base.group_system` | ✓ | ✗ | ✗ | ✗ |
+
+**No write/create/unlink for any group via the UI.** Audit rows are only written via `sudo()` from inside the auth hooks. An audit log admins can mutate is not an audit log.
+
+### Record rule
+
+Single global rule on `fusion.login.audit`: read for `base.group_system` only. The user-form one2many is additionally gated at the view level via `groups="base.group_system"` (not via a more permissive record rule) so non-admins have no read path even if they craft a custom view.
+
+### Field-level
+
+- `failure_reason` stores a category, never the attempted password.
+- `_fc_build_event_vals` strips `credential['password']` before any logging or row construction.
+- The `credential` dict is never persisted.
+- Regression test: no field on `fusion.login.audit` ever contains a known-test-password string.
+
+## Retention
+
+**Cron `cron_retention_gc`** — daily at 03:00 UTC, `numbercall=-1`:
+
+```python
+days = int(self.env['ir.config_parameter'].sudo().get_param(
+    'fusion_login_audit.retention_days', 365))
+if days > 0:
+    cutoff = fields.Datetime.now() - timedelta(days=days)
+    self.env['fusion.login.audit'].sudo().search([
+        ('event_time', '<', cutoff)
+    ]).unlink()
+```
+
+Uses `unlink()` rather than raw `DELETE` so any ORM side effects fire. Expected DB load on `westin-v19`: 27 users × ~2 logins/day × 365 days ≈ 20k rows steady state — trivial for Postgres.
+
+## Failed-login alert
+
+**Mail template** in `data/mail_template_data.xml`:
+
+- **Subject:** `[Login Audit] {threshold} failed login attempts for {attempted_login}`
+- **Body:** simple HTML table of the last N failure rows for that `attempted_login` — timestamp, IP, country, user-agent summary.
+- **Recipients:** all users in `base.group_system` with a non-empty `email`.
+- **Send path:** `mail.mail` queue with `auto_delete=True` so the auth response isn't blocked.
+
+**Cooldown:** 60 min per `attempted_login`, enforced via an `ir.config_parameter` keyed by `fusion_login_audit.last_alert:{attempted_login}` storing the last-send timestamp. Prevents a sustained attack from flooding admin inboxes.
+
+**Kill-switch:** if `x_fc_login_audit_alert_enabled = False`, no alerts are sent regardless of threshold.
+
+## Edge cases
+
+| Case | Behavior |
+|---|---|
+| `request` is None (XML-RPC, internal auth from cron) | Row written with `ip_address='internal'`, `user_agent_raw='<no-request>'`, `geo_lookup_state='internal'` (cron skips) |
+| Audit insert errors on a hot DB | Login still succeeds — every auth-path hook is wrapped in `try/except Exception: _logger.exception(...)` |
+| User deleted while audit rows remain | `ondelete='set null'` preserves history; `attempted_login` keeps the readable identifier |
+| Password reset / `auth_signup` | The reset itself generates no login event; the subsequent login does — matches expectation |
+| API key authentication | **Out of scope v1** (bypasses `_check_credentials`); documented |
+| OAuth / SSO | Out of scope v1; no provider configured on westin-v19 |
+| Portal user (`share=True`) | Logged the same way; smart button remains admin-visible |
+| Two requests racing on the same private IP | Each writes its own row; geo cache is best-effort, not transactional |
+| `proxy_mode = False` in `odoo.conf` | `remote_addr` will be the reverse-proxy IP — known limitation, fixable by setting `proxy_mode = True` (out of scope) |
+
+## Testing
+
+### `tests/test_login_audit.py` (TransactionCase)
+
+1. Successful login writes a row with `result='success'` and resolved `user_id`.
+2. Bad password writes `result='failure'` with `failure_reason='bad_password'` and re-raises `AccessDenied`.
+3. Unknown user writes `result='failure'` with `failure_reason='unknown_user'`, `user_id=None`, non-null `attempted_login`.
+4. No field on the written row contains the attempted password (regression).
+5. Geo cron: pending row gets enriched from local cache when same IP exists within 30 days (no HTTP call made).
+6. Retention cron: rows older than `retention_days` are deleted; newer survive.
+7. Alert email: 5 failures in 15 min queues exactly one `mail.mail`; a 6th failure within cooldown queues zero.
+8. `database` field is populated from `self.env.cr.dbname`.
+9. Audit-write exception inside `_update_last_login` does not block the login.
+
+### `tests/test_security.py` (HttpCase)
+
+1. Non-admin user gets `AccessError` on direct `search(fusion.login.audit)`.
+2. Non-admin sees the user form view without the smart button or "Login Activity" tab (XML node hidden by `groups`).
+3. Settings admin sees both.
+
+## Deployment notes
+
+- **Local install:** copy module to `K:\Github\Odoo-Modules\fusion_login_audit\` (bind-mounted into `odoo-modsdev-app` container). Update via:
+  ```
+  docker exec odoo-modsdev-app odoo -d fusion-dev -i fusion_login_audit --stop-after-init
+  ```
+- **Production install:** sync to `/opt/odoo/custom-addons/fusion_login_audit/` on odoo-westin (via `auto_sync.sh` or git pull on the VM). Update via:
+  ```
+  ssh odoo-westin "docker exec odoo-dev-app odoo -d westin-v19 -i fusion_login_audit --stop-after-init"
+  ```
+- **Icon:** copy `C:\Users\gsing\Downloads\fusion logs.png` to `K:\Github\Odoo-Modules\fusion_login_audit\static\description\icon.png`.
+- **Verify `proxy_mode = True`** in `/opt/odoo/odoo.conf` on odoo-westin before relying on `ip_address` accuracy — otherwise `remote_addr` will be the reverse-proxy IP rather than the real client. Confirmed out of scope for this module, but flag for the operator.
+- **Verify outbound to `ip-api.com:80`** is reachable from the odoo-westin VM (Tailscale/firewall) — if blocked, `geo_lookup_state` will simply be `failed` and the rest of the module is unaffected.
+
+## Success criteria
+
+- Logging in as any user creates exactly one `fusion.login.audit` row with `result='success'` and the correct IP/UA.
+- Failed login attempts create exactly one row with `result='failure'` and the correct `failure_reason`.
+- Unknown-user attempts create a row with `user_id=None` and the typed login string in `attempted_login`.
+- The smart button on `res.users` shows the lifetime count and opens the filtered list.
+- The "Login Activity" tab shows the last 30 events with correct color coding.
+- After 5 failures from the same login string within 15 minutes, exactly one alert email arrives in the inbox of every Settings admin with an `email` set.
+- The geo cron populates `country_code`, `city`, `ip_hostname` for public IPs within 10 minutes of the login.
+- The retention cron, set to 1 day for a test, deletes rows older than 24 hours and leaves newer ones.
+- All tests pass: `docker exec odoo-modsdev-app odoo -d fusion-dev --test-enable -i fusion_login_audit --stop-after-init`.

docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md

@@ -0,0 +1,271 @@
+# fusion_centralize_billing — Centralized Billing Engine on Odoo 19
+
+- **Date:** 2026-05-27
+- **Status:** Design approved — pending written-spec review
+- **Author:** Design session (Claude + Gurpreet)
+- **Module:** `fusion_centralize_billing` (target: `K:\Github\Odoo-Modules\fusion_centralize_billing`)
+- **Host:** odoo-nexa (Proxmox VM 315, worker1), Odoo 19 **Enterprise**, live DB `nexamain`
+
+## 1. Goal
+
+Make the Odoo Enterprise instance (`odoo-nexa`) the single billing brain for every
+NexaSystems service — hosting (NexaCloud), live chat (NexaDesk/Fusion-Chat), the
+metered maps API (NexaMaps), plus custom-app retainers, memberships, and one-off
+services. It replaces Lago in the role Lago currently plays, and absorbs NexaCloud's
+home-grown Stripe billing, so there is one customer ledger, one accounting system,
+one place revenue is recognized.
+
+## 2. Current state (recon, 2026-05-27)
+
+Billing is fragmented across **three+ independent engines**:
+
+| System | Bills for | Engine today | Data home |
+|---|---|---|---|
+| **NexaCloud** (LXC 102, `10.200.0.250`) | VPS/LXC hosting, Coolify apps, CPU-seconds + throttle-removal fees, snapshots, domains | Own Postgres models + **direct Stripe** (`stripe_service.py`, `billing_service.py`, `usage_metering.py`, `invoice_generator.py`) | `nexacloud` DB (LXC 201) |
+| **NexaDesk / Fusion-Chat** (VM 314) | Chat plans (monthly/annual), feature + channel add-ons, message/token overage, token wallets | **Lago** v1.44.0 (VM 318) + Stripe (provider code `nexadesk`) | Lago (VM 318, `192.168.1.117`) |
+| **NexaMaps** (`fusionapps.maps_*`) | Metered geocoding/routing API: monthly quota + overage per 1k | Own tables; **~189k usage events / month** for 2 clients | Supabase `fusionapps` |
+| Services / memberships | Custom apps, consulting, retainers | ad-hoc / manual | — |
+
+**Decisive fact:** `odoo-nexa` is **Odoo 19 Enterprise** and already runs the full
+Lago-equivalent stack: `sale_subscription` (+ `_stock`, `_timesheet`,
+`_external_tax`), `account_accountant`, `payment_stripe`, `website_sale` +
+`website_sale_subscription`, `crm/project/industry_fsm_sale_subscription`, plus
+custom `nexa_coa_setup`, `fusion_whitelabels`, `fusion_helpdesk_central`,
+`fusion_pdf_preview`. So Odoo already does subscriptions, recurring invoicing, full
+accounting/GL, Stripe, HST taxes, customer portal, credit notes, and self-serve
+checkout.
+
+**The only capability Lago has that Odoo lacks natively is usage-based metered
+billing** (billable metrics → aggregation → quota/overage charges). That, plus the
+integration surface, is all we build.
+
+Prior decision on record (Supabase `fusionapps.decisions`): Lago was deployed as the
+centralizer for NexaDesk + NexaCloud. This design **supersedes** that — the billing
+brain moves into the Odoo Enterprise already owned and operated.
+
+## 3. Decisions locked in this session
+
+1. **Odoo fully replaces Lago.** Build a metered-billing engine inside `fusion_centralize_billing`; decommission Lago VM 318 at the end.
+2. **One unified customer, separate invoice per service.** One `res.partner` per real client; each service bills on its own subscription/cycle. No cross-product invoice merging.
+3. **Apps drive; Odoo is the billing system of record.** Each app keeps its own signup, provisioning, and entitlement enforcement, and calls Odoo's billing API (the same way it calls Lago today). Odoo invoices, charges Stripe, and emits webhooks back.
+4. **Odoo owns the billing catalog; apps own entitlements.** Odoo is SoR for products, prices, recurrence, metric rate/quota/overage, taxes — keyed by a stable `plan_code`. Apps enforce feature limits (max_chatbots, CPU quota, API rate-limit) against the same code.
+5. **Pilot = NexaCloud, phased dual-run cutover** (one product at a time, parallel run + reconciliation before flip).
+6. **Aggregate-push usage ingestion.** Apps push periodic pre-aggregated counters; Odoo stores rollups and feeds native `sale.subscription` metered lines. No raw-event firehose into Odoo.
+
+## 4. Architecture
+
+```
+  NexaCloud   NexaDesk    NexaMaps        (apps keep signup + provisioning + entitlements)
+      │           │           │
+      │  customers / subscriptions / usage counters   (inbound REST, API-key bearer auth)
+      ▼           ▼           ▼
+┌──────────────────────────────────────────────┐
+│  fusion_centralize_billing  (custom Odoo 19 module)         │
+│  • Service registry (one row per app)          │
+│  • Identity links (ext acct → res.partner)     │
+│  • Metric + Charge catalog (quota/overage)     │
+│  • Usage engine (ingest → aggregate → bill)    │
+│  • Outbound webhook queue (HMAC + retry)       │
+└───────────────┬────────────────────────────────┘
+                │ writes billable qty onto
+                ▼
+   sale.order(is_subscription) → account.move → payment_stripe  (NATIVE Odoo Enterprise)
+                │                                        invoicing, HST tax, proration,
+                │  invoice paid / failed / sub ended     dunning, portal, credit notes
+                ▼
+   outbound webhooks ──► apps suspend / restore / deprovision
+```
+
+Principle: **build only the metering + integration layer; inherit all financial
+behaviour from native Odoo Enterprise.**
+
+## 5. Data model
+
+### 5.1 New models (`fusion.billing.*`)
+
+| Model | Key fields | Purpose |
+|---|---|---|
+| `fusion.billing.service` | `name`, `code` (nexacloud/nexadesk/nexamaps), `api_key_hash`, `webhook_url`, `webhook_secret`, `active` | One row per source app — the auth + routing boundary. |
+| `fusion.billing.account.link` | `service_id`, `external_id`, `partner_id`, `external_email`; unique `(service_id, external_id)` | Identity resolution: folds each app's account into one `res.partner`. |
+| `fusion.billing.metric` | `code`, `name`, `aggregation` (sum/max/last/unique_count), `unit_label`, `rounding` | Billable metric definition. |
+| `fusion.billing.charge` | `plan_ref`/`product_id`, `metric_id`, `included_quota`, `price_per_unit`, `unit_batch` (e.g. per 1000), `charge_model` (standard/graduated/package/volume) | Maps a plan + metric → quota & overage pricing. Where "5M quota / $0.10 per 1k" lives. |
+| `fusion.billing.usage` | `subscription_id`, `metric_id`, `period_start`, `period_end`, `quantity`, `source`, `idempotency_key`; index `(subscription, metric, period)` | **Aggregated** usage rows (rollups, not raw events). |
+| `fusion.billing.webhook` | `service_id`, `event_type`, `payload` (JSON), `state` (pending/sent/failed/dead), `attempts`, `next_retry_at`, `signature` | Outbound event queue, processed by cron with backoff + HMAC. |
+| `fusion.billing.reconciliation` | `service_id`, `partner_id`, `period`, `odoo_amount`, `external_amount`, `delta`, `status` | Dual-run shadow-mode comparison (Odoo-computed vs app-actual). |
+
+### 5.2 Native models reused as-is
+
+`res.partner` (customer), **`sale.order` with `is_subscription=True`** (the subscription),
+`sale.subscription.plan` (recurrence/plan), `sale.order.line` (metered lines),
+`account.move` (invoice + credit note), `payment_stripe`/`payment.transaction` (Stripe),
+`account.tax` (HST per province), customer portal. Catalog = `product.template` +
+`sale.subscription.plan`, tagged with the shared `plan_code`.
+
+New fields on native models use the `x_fc_*` prefix (e.g. `res.partner.x_fc_billing_external_ids`).
+
+> **Odoo 19 modeling note (verified on live `nexamain`, 2026-05-27):** there is **no
+> `sale.subscription` model**. A subscription IS a `sale.order` with `is_subscription=True`,
+> `plan_id` → `sale.subscription.plan`, plus `subscription_state` / `next_invoice_date` /
+> `recurring_monthly`. Every "subscription" reference in this spec means that. The usage
+> engine links `fusion.billing.usage.subscription_id` → `sale.order`.
+
+### 5.3 Relationship to `fusion_api` (reuse, don't duplicate)
+
+The existing **`fusion_api`** module (`fusion.api.key` / `.consumer` / `.service` /
+`.usage` / `.usage.daily`) centralizes **outbound** provider keys (OpenAI, Anthropic,
+Google Maps, Twilio) with cost/usage tracking + rate limiting — i.e. what **Nexa pays
+providers** (COGS). It is **complementary**, not a substitute:
+`fusion_centralize_billing` tracks what **customers owe Nexa**. Two concrete ties:
+(a) feed `fusion.api.usage.daily` cost into margin reporting against billed revenue;
+(b) mirror its daily-rollup aggregation pattern for `fusion.billing.usage`. The
+customer-facing metered billing and the inbound API remain ours to build.
+
+## 6. Usage engine (aggregate-push)
+
+1. Apps `POST /usage` with periodic counters and an `idempotency_key`
+   (e.g. `service:metric:subscription:window`). NexaCloud pushes CPU-seconds per
+   deployment hourly; NexaMaps pushes api_calls per client daily; NexaDesk pushes
+   messages/tokens. Upsert into `fusion.billing.usage` keyed by `idempotency_key` so
+   retries never double-bill.
+2. A **pre-invoice cron** (runs ahead of each subscription's invoice date) sums the
+   period's `fusion.billing.usage` per metric, applies the matching
+   `fusion.billing.charge` (quota → free, overage → priced by `charge_model`), and
+   writes the billable quantity/amount onto the subscription's draft invoice line
+   (usage product).
+3. Native subscription invoicing issues the invoice, applies HST, and charges Stripe.
+   Quota resets per period.
+
+At ~189k Maps events/month pushed as daily counters, Odoo stores ≈30 rows per client
+per metric per month — trivial volume.
+
+## 7. Inbound API (Lago-shaped, drop-in)
+
+Base path `/api/billing/v1/*`. Odoo 19 routing: `type="http"`, `auth="none"`,
+`csrf=False`, manual **Bearer** API-key check against `fusion.billing.service`
+(hashed), JSON request/response via `request.make_json_response`, per-service rate
+limiting. (`type="jsonrpc"` is for Odoo session RPC — not used here, because external
+apps authenticate with bearer tokens, not Odoo sessions.)
+
+Endpoints intentionally mirror `Fusion-Chat/src/lib/billing/lago-client.ts` so the
+NexaDesk swap is ≈ one file, and NexaCloud's integration is a thin client:
+
+| Method · Path | Maps to |
+|---|---|
+| `POST /customers` | upsert `res.partner` + `account.link` (identity resolution) |
+| `POST /subscriptions` · `PUT /subscriptions/:id` · `DELETE /subscriptions/:id` | create / change-upgrade / cancel subscription `sale.order` |
+| `POST /usage` | batch aggregated counters (hot path → 202 Accepted) |
+| `POST /invoices` | one-off invoice (token packs, throttle-removal fee) |
+| `GET /invoices` · `GET /invoices/:id` · `POST /invoices/:id/download` | list / fetch / PDF |
+| `POST /invoices/:id/retry_payment` · `POST /invoices/:id/void` | payment retry / void |
+| `POST /credit_notes` | refund via `account.move` reversal |
+| `GET /plans` · `GET /catalog` | apps fetch pricing (as NexaDesk fetches from Lago) |
+| `GET /customers/:id/checkout_url` | Stripe payment-method setup |
+
+## 8. Outbound webhooks (control loop)
+
+Odoo → app, HMAC-SHA256 signed, retried with exponential backoff, dead-lettered after
+N attempts (reuse the proven pattern in `Fusion-Chat/src/lib/billing/lago-payment-retry-job.ts`):
+
+| Event | App reaction |
+|---|---|
+| `invoice.payment_failed` (after dunning) | **suspend** — NexaCloud throttle/network-isolate; NexaDesk suspend tenant; NexaMaps disable API key |
+| `invoice.payment_succeeded` / `subscription.reactivated` | **restore** service |
+| `subscription.terminated` | **deprovision** |
+| `usage.threshold_reached` (80% / 100%, optional) | warn / cap |
+
+## 9. NexaCloud pilot
+
+- **Identity & catalog mapping:** `nexacloud.users` → `res.partner` via `account.link`;
+  `nexacloud.products`/`plans` → `product.template` + subscription plans
+  (`plan_code` = NexaCloud plan id/slug, prices from `price_monthly`/`price_yearly`);
+  `nexacloud.deployments` + `subscriptions` → one subscription `sale.order` per deployment
+  (NexaCloud bills per deployment).
+- **Metering:** CPU-seconds → `fusion.billing.metric` `cpu_seconds` (sum) + `charge`
+  (included = plan quota, overage priced). Throttle-removal fee → one-off invoice
+  (or add-on product). `nexacloud/.../usage_metering.py` pushes counters to `/usage`.
+- **Control loop:** `invoice.payment_failed` → NexaCloud suspends using its existing
+  `network_isolation` / `throttle_checker` / `resource_manager`; `subscription.terminated`
+  → NexaCloud deprovisions.
+
+## 10. Dual-run + migration (phased)
+
+1. **Import** NexaCloud customers + active subscriptions into Odoo (script reads the
+   `nexacloud` DB → creates partners / links / subscriptions / charges).
+2. **Shadow mode ≥ 1 billing cycle:** Odoo computes invoices while NexaCloud keeps
+   charging via its own Stripe. `fusion.billing.reconciliation` diffs Odoo-computed vs
+   NexaCloud-actual per customer/period; investigate every delta.
+3. **Flip** when deltas are within tolerance: NexaCloud calls Odoo's API as SoR and
+   stops its internal Stripe billing. Past invoices stay archived (PDF / opening
+   balances) — not re-issued.
+4. **Repeat** for NexaDesk (retire Lago for chat) → NexaMaps → then decommission
+   Lago VM 318.
+
+## 11. Risks & open items
+
+- **🟢 Stripe account unification — RESOLVED (2026-05-27).** All systems share ONE Stripe
+  account: **`acct_1ShlA9IkwUB1dVox`** (Nexa Systems Inc, CA, live). Verified live:
+  NexaCloud's direct `sk_live` key resolves to that account, and Lago has three Stripe
+  providers (`nexasystems`, `nexadesk`, `nexamaps`) that **all** resolve to the same
+  account. Therefore **no Stripe account migration is needed** — Odoo's `payment_stripe`
+  connects to that single account and **reuses existing Stripe customers + saved payment
+  methods** (map each Stripe `provider_customer_id` → `res.partner`). This removes what
+  was the biggest migration risk.
+- **Idempotency** on usage counters is mandatory (dedupe key) to prevent double billing on retries.
+- **Entitlement sync SLA:** on plan change, Odoo webhook informs the app; define how
+  fast app-side limits must update (and the reconciliation if a webhook is missed).
+- **Odoo 19 correctness:** implementation MUST read live reference files from the
+  container (`docker exec odoo-nexa-app cat …`) before coding subscription/API/account
+  internals — never from memory (per `K:\Github\CLAUDE.md`).
+- **Tax:** HST/GST per Canadian province via `account.tax`; confirm tax codes align
+  with current Lago `hst_on` usage.
+- **Auth hardening:** API keys hashed at rest, per-service scoping, rate limiting,
+  request audit log; webhook secrets rotated.
+
+## 12. Phasing — spec sequence
+
+Each is its own spec → plan → build cycle:
+
+1. **`fusion_centralize_billing` core** — service registry, identity links, metric/charge catalog,
+   usage engine, inbound API, outbound webhook engine. *(detailed below — first deliverable)*
+2. **NexaCloud adapter + dual-run reconciliation** *(the pilot — coupled to #1)*
+3. NexaDesk adapter (swap the Lago client for the Odoo billing client)
+4. NexaMaps adapter
+5. Lago decommission + memberships/services onboarding + portal polish
+
+## 13. First-deliverable scope (sub-projects #1 + #2)
+
+**In scope**
+- `fusion_centralize_billing` module skeleton (manifest, security/ACLs + record rules, README) following the `nexa_coa_setup` layout.
+- Models in §5.1; new native fields use `x_fc_*`.
+- Aggregate-push usage engine (§6) incl. pre-invoice cron + idempotent upsert.
+- Inbound API (§7) with bearer auth, and outbound webhook engine (§8).
+- NexaCloud mapping + importer + shadow-mode reconciliation (§9, §10).
+- Manifest `depends`: `sale_subscription`, `account_accountant`, `payment_stripe`,
+  `sale_management` (+ `nexa_coa_setup` if COA dependencies apply).
+
+**Out of scope (YAGNI for now)**
+- NexaDesk / NexaMaps adapters (specs #3/#4).
+- Raw-event ingestion / per-event audit in Odoo (apps retain raw events).
+- Lago decommission (spec #5) — Lago stays running until NexaDesk is migrated.
+- Customer-portal redesign — use native portal as-is initially.
+
+## 14. Success criteria (first deliverable)
+
+- A NexaCloud deployment can be created as an Odoo subscription `sale.order` via the API,
+  with one `res.partner` resolving the NexaCloud user.
+- CPU-seconds counters pushed to `/usage` aggregate correctly and produce a draft
+  invoice with quota + overage applied, taxed (HST), and charged through `payment_stripe`.
+- A simulated `invoice.payment_failed` delivers a signed webhook NexaCloud can act on.
+- Shadow-mode reconciliation report shows Odoo-computed vs NexaCloud-actual within
+  tolerance for ≥ 1 cycle before any flip.
+- No double billing under usage-counter retries (idempotency verified).
+
+## 15. Open questions for review
+
+1. ~~Stripe: one account across all products, or separate?~~ **ANSWERED (2026-05-27):** one
+   account `acct_1ShlA9IkwUB1dVox` for everything (NexaCloud direct + Lago's
+   `nexasystems`/`nexadesk`/`nexamaps` providers). No account migration; reuse existing
+   Stripe customers + payment methods.
+2. NexaCloud billing granularity — confirm **one subscription per deployment** (vs one per customer with deployment line items).
+3. Membership model — Odoo native `membership` module, or model memberships as plain recurring subscriptions?
+4. Spec/module commit target — confirm branch strategy in `Odoo-Modules` (currently on `feat/fusion-login-audit`).

fusion-plating/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls /k/Github/Odoo-Modules/ | grep -i -E \"shopfloor|tablet|fusion_plating\")"
+    ]
+  }
+}

fusion_centralize_billing/README.md

@@ -0,0 +1,70 @@
+# Fusion Centralized Billing (`fusion_centralize_billing`)
+
+Centralized billing engine that makes this Odoo 19 **Enterprise** instance the single
+billing brain for every NexaSystems service — **NexaCloud** hosting, **NexaDesk** chat,
+**NexaMaps** API, custom apps, and memberships. It replaces Lago and absorbs NexaCloud's
+home-grown Stripe billing into one customer ledger and one accounting system.
+
+> **Design spec:** [`docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md`](../docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md)
+>
+> **Status:** **SCAFFOLD.** Models + security + the API auth shell are in place and the
+> module installs. The usage engine, full inbound API, and webhook processor are stubs
+> to be implemented from the writing-plans output.
+
+## Why this module is small
+
+We build **only** the metering + integration layer. Everything financial — recurring
+invoicing, HST tax, proration, dunning, customer portal, credit notes, Stripe — is
+**native Odoo Enterprise** (`sale_subscription`, `account_accountant`, `payment_stripe`),
+already installed and running.
+
+## Design decisions (locked)
+
+1. Odoo fully replaces Lago (we build the metered-billing engine; Lago is decommissioned last).
+2. One unified `res.partner` per client; **separate invoice per service**.
+3. **Apps drive**, Odoo is the billing system of record — apps call the inbound API (as they call Lago today); Odoo bills and webhooks back.
+4. Odoo owns the **billing catalog**; apps own **feature entitlements** (shared `plan_code`).
+5. Pilot = **NexaCloud**, phased dual-run cutover.
+6. **Aggregate-push** usage ingestion (periodic counters, not a raw-event firehose).
+
+## Models (`fusion.billing.*`)
+
+| Model | Purpose |
+|---|---|
+| `fusion.billing.service` | One source app; bearer API key (hashed) + webhook config. |
+| `fusion.billing.account.link` | External account id → one `res.partner` (identity resolution). |
+| `fusion.billing.metric` | Billable metric + aggregation (sum/max/last/unique). |
+| `fusion.billing.charge` | Plan + metric → included quota + overage pricing. |
+| `fusion.billing.usage` | Aggregated per-period usage rollups (idempotent). |
+| `fusion.billing.webhook` | Outbound lifecycle event queue (HMAC + retry). |
+| `fusion.billing.reconciliation` | Dual-run Odoo-vs-app delta during cutover. |
+
+> **Odoo 19 note (verified):** a subscription is a `sale.order` with `is_subscription=True`
+> (`plan_id` → `sale.subscription.plan`). There is **no** `sale.subscription` model.
+> `fusion.billing.usage.subscription_id` therefore points at `sale.order`.
+
+## Inbound API
+
+Lago-shaped REST under `/api/billing/v1/*`, bearer auth. Endpoints mirror NexaDesk's
+existing `lago-client.ts` so migration is a thin client swap. `/health` works today;
+the rest return `501` until implemented.
+
+## Relationship to `fusion_api`
+
+`fusion_api` manages **outbound** provider keys (OpenAI, Maps, Twilio) + cost tracking —
+i.e. COGS. This module tracks **customer** revenue. Complementary: feed `fusion_api`
+cost into margin reporting; reuse its daily-rollup aggregation pattern.
+
+## Dependencies
+
+`account_accountant`, `sale_subscription`, `sale_management`, `payment_stripe`.
+
+## Local dev
+
+```bash
+docker exec odoo-nexa-app odoo -d nexamain -u fusion_centralize_billing --stop-after-init
+# tests (once added):
+docker exec odoo-nexa-app odoo -d nexamain --test-enable --test-tags /fusion_centralize_billing -u fusion_centralize_billing --stop-after-init
+```
+
+Canadian English, CAD, HST via `account.tax`. New fields on native models use the `x_fc_*` prefix.

fusion_centralize_billing/__init__.py

@@ -0,0 +1,2 @@
+from . import models
+from . import controllers

fusion_centralize_billing/__manifest__.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1 (Odoo Proprietary License v1.0)
+{
+    "name": "Fusion Centralized Billing",
+    "version": "19.0.1.0.0",
+    "category": "Accounting/Subscriptions",
+    "summary": "Centralized billing engine for all NexaSystems services — metered usage, "
+               "per-app billing API, and outbound webhooks on top of Odoo Enterprise subscriptions.",
+    "description": """
+Fusion Centralized Billing
+==========================
+
+Makes this Odoo Enterprise instance the single billing brain for every NexaSystems
+service (NexaCloud hosting, NexaDesk chat, NexaMaps API, custom apps, memberships).
+
+It adds ONLY the metering + integration layer; all financial behaviour (invoicing,
+HST tax, proration, dunning, portal, credit notes, Stripe) is native Odoo Enterprise.
+
+Capabilities
+------------
+* Service registry — one record per source app (NexaCloud / NexaDesk / NexaMaps) with
+  bearer API key + webhook config.
+* Identity links — fold each app's external account into one ``res.partner``.
+* Metric + Charge catalog — billable metrics with quota + overage pricing, keyed by a
+  shared ``plan_code`` (apps own feature entitlements; Odoo owns money).
+* Usage engine — aggregate-push: apps send periodic counters; a pre-invoice cron feeds
+  billable quantities onto the subscription ``sale.order``.
+* Inbound API — Lago-shaped REST (``/api/billing/v1/*``), bearer auth.
+* Outbound webhooks — HMAC-signed lifecycle events (payment failed/succeeded,
+  subscription terminated) so apps suspend / restore / deprovision.
+
+Design spec: docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md
+
+Status: SCAFFOLD. Model fields are in place; engine/API/webhook bodies are stubs to be
+implemented via the writing-plans output. Per repo CLAUDE.md, read live Odoo 19
+reference files from the container before implementing subscription/account internals.
+    """,
+    "author": "Nexa Systems Inc.",
+    "website": "https://nexasystems.ca",
+    "license": "OPL-1",
+    "depends": [
+        "account_accountant",
+        "sale_subscription",
+        "sale_management",
+        "payment_stripe",
+    ],
+    "data": [
+        "security/ir.model.access.csv",
+    ],
+    "installable": True,
+    "application": False,
+    "auto_install": False,
+}

fusion_centralize_billing/controllers/__init__.py

@@ -0,0 +1 @@
+from . import api

fusion_centralize_billing/controllers/api.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+"""Inbound, Lago-shaped billing API (spec §7).
+
+Auth: bearer API key matched (by SHA-256 hash) against ``fusion.billing.service``.
+Routing: ``type="http"`` + ``auth="none"`` + ``csrf=False`` — external apps present
+bearer tokens, not Odoo sessions (so NOT ``type="jsonrpc"``).
+
+STATUS: SCAFFOLD. Only auth + /health are wired. Endpoint bodies are stubs (HTTP 501)
+to be implemented from the writing-plans output. Per repo CLAUDE.md, read live Odoo 19
+references (sale.order subscription flow, account.move, payment_stripe) before
+implementing — do NOT code those internals from memory.
+"""
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+_logger = logging.getLogger(__name__)
+
+API_BASE = "/api/billing/v1"
+
+
+class FusionBillingApi(http.Controller):
+
+    # ── helpers ──────────────────────────────────────────────────────────
+    def _authenticate(self):
+        """Return the active fusion.billing.service for the bearer key, else None."""
+        auth = request.httprequest.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        return request.env["fusion.billing.service"].sudo()._match_api_key(auth[7:].strip()) or None
+
+    def _json(self, payload, status=200):
+        return request.make_json_response(payload, status=status)
+
+    def _read_json(self):
+        try:
+            raw = request.httprequest.get_data(as_text=True) or "{}"
+            return json.loads(raw)
+        except Exception:
+            return None
+
+    # ── routes ───────────────────────────────────────────────────────────
+    @http.route(f"{API_BASE}/health", type="http", auth="none", methods=["GET"], csrf=False)
+    def health(self, **kw):
+        return self._json({"status": "ok", "service": "fusion_centralize_billing"})
+
+    @http.route(f"{API_BASE}/customers", type="http", auth="none", methods=["POST"], csrf=False)
+    def post_customer(self, **kw):
+        service = self._authenticate()
+        if not service:
+            return self._json({"error": "unauthorized"}, status=401)
+        payload = self._read_json()
+        if payload is None:
+            return self._json({"error": "invalid json"}, status=400)
+        return self._json(service._api_upsert_customer(payload))
+
+    @http.route(f"{API_BASE}/usage", type="http", auth="none", methods=["POST"], csrf=False)
+    def post_usage(self, **kw):
+        service = self._authenticate()
+        if not service:
+            return self._json({"error": "unauthorized"}, status=401)
+        payload = self._read_json()
+        if payload is None:
+            return self._json({"error": "invalid json"}, status=400)
+        return self._json(service._api_record_usage(payload), status=202)
+
+    @http.route(f"{API_BASE}/plans", type="http", auth="none", methods=["GET"], csrf=False)
+    def get_plans(self, **kw):
+        service = self._authenticate()
+        if not service:
+            return self._json({"error": "unauthorized"}, status=401)
+        return self._json(service._api_catalog())
+
+    @http.route(f"{API_BASE}/subscriptions", type="http", auth="none", methods=["POST"], csrf=False)
+    def post_subscription(self, **kw):
+        service = self._authenticate()
+        if not service:
+            return self._json({"error": "unauthorized"}, status=401)
+        payload = self._read_json()
+        if payload is None:
+            return self._json({"error": "invalid json"}, status=400)
+        return self._json(service._api_create_subscription(payload))

fusion_centralize_billing/models/__init__.py

@@ -0,0 +1,7 @@
+from . import service
+from . import account_link
+from . import metric
+from . import charge
+from . import usage
+from . import webhook
+from . import reconciliation

fusion_centralize_billing/models/account_link.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import api, fields, models
+
+
+class FusionBillingAccountLink(models.Model):
+    """Identity resolution: maps an app's external account id to one res.partner.
+
+    Folds the NexaCloud user / NexaDesk tenant / NexaMaps client for the same
+    real-world client onto a single partner (the unified customer). See spec §5.1.
+    """
+
+    _name = "fusion.billing.account.link"
+    _description = "Fusion Billing — External Account → Partner Link"
+    _order = "service_id, external_id"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    external_id = fields.Char(
+        required=True, index=True,
+        help="The app's own account id (NexaCloud user, NexaDesk tenant, Maps client).",
+    )
+    external_email = fields.Char()
+    partner_id = fields.Many2one(
+        "res.partner", required=True, ondelete="restrict", index=True,
+    )
+
+    _service_external_uniq = models.Constraint(
+        "unique(service_id, external_id)",
+        "An external account can only link to one partner per service.",
+    )
+
+    @api.model
+    def _resolve_or_create_partner(self, service, external_id, name=None, email=None, extra=None):
+        """Return the link for (service, external_id), creating partner+link if needed.
+
+        Unifies customers: if a link for this external_id exists, reuse it; else if a
+        partner with the same email already exists (possibly from another service),
+        link to it; else create a new partner.
+        """
+        existing = self.search(
+            [('service_id', '=', service.id), ('external_id', '=', external_id)], limit=1)
+        if existing:
+            return existing
+        partner = self.env['res.partner']
+        if email:
+            partner = partner.search([('email', '=', email)], limit=1)
+        if not partner:
+            partner = partner.create({'name': name or external_id, 'email': email, **(extra or {})})
+        return self.create({
+            'service_id': service.id,
+            'external_id': external_id,
+            'external_email': email,
+            'partner_id': partner.id,
+        })

fusion_centralize_billing/models/charge.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+import math
+
+from odoo import api, fields, models
+
+
+class FusionBillingCharge(models.Model):
+    """Maps a plan + metric to quota + overage pricing.
+
+    This is where "5,000,000 included / $0.10 per 1k overage" (NexaMaps) or a
+    NexaCloud CPU-seconds quota lives. Keyed by the shared ``plan_code`` the app
+    references; Odoo owns the money, the app owns feature entitlements. See spec §5.1.
+    """
+
+    _name = "fusion.billing.charge"
+    _description = "Fusion Billing — Metered Charge (quota + overage)"
+    _order = "plan_code, name"
+
+    name = fields.Char(required=True)
+    plan_code = fields.Char(
+        required=True, index=True,
+        help="Shared plan_code the source app references (matches a sale.subscription.plan).",
+    )
+    plan_id = fields.Many2one(
+        "sale.subscription.plan",
+        help="Optional link to the Odoo recurrence/plan for this charge.",
+    )
+    metric_id = fields.Many2one(
+        "fusion.billing.metric", required=True, ondelete="restrict",
+    )
+    product_id = fields.Many2one(
+        "product.product", help="Usage product invoiced for overage.",
+    )
+    included_quota = fields.Float(
+        default=0.0, help="Units included before overage applies, per period.",
+    )
+    price_per_unit = fields.Monetary(help="Overage price per unit_batch.")
+    unit_batch = fields.Float(
+        default=1.0, help="Batch size for overage pricing, e.g. 1000 = priced per 1k.",
+    )
+    charge_model = fields.Selection(
+        [
+            ("standard", "Standard (per unit)"),
+            ("graduated", "Graduated"),
+            ("package", "Package"),
+            ("volume", "Volume"),
+        ],
+        default="standard", required=True,
+    )
+    currency_id = fields.Many2one(
+        "res.currency", default=lambda self: self.env.company.currency_id,
+    )
+    active = fields.Boolean(default=True)
+
+    def _compute_billable(self, total_quantity):
+        """Return (overage_units, amount) for total period usage under this charge.
+
+        - overage_units = usage above included_quota (never negative)
+        - 'standard'/'package'/'volume': priced per `unit_batch` block, partial block rounds up.
+          (graduated tiers are out of scope for the core; treated as 'standard'.)
+        """
+        self.ensure_one()
+        overage = max(0.0, (total_quantity or 0.0) - (self.included_quota or 0.0))
+        batch = self.unit_batch or 1.0
+        if self.charge_model == 'package':
+            # whole packages over the RAW quantity (quota ignored for package counting)
+            blocks = math.ceil((total_quantity or 0.0) / batch) if total_quantity else 0
+            return overage, round(blocks * (self.price_per_unit or 0.0), 2)
+        # standard / volume / graduated-fallback: price the overage in (rounded-up) batches
+        blocks = math.ceil(overage / batch) if overage > 0 else 0
+        return overage, round(blocks * (self.price_per_unit or 0.0), 2)

fusion_centralize_billing/models/metric.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingMetric(models.Model):
+    """A billable metric (CPU-seconds, API calls, messages, tokens ...).
+
+    Defines how raw usage is aggregated within a billing period. See spec §5.1 / §6.
+    """
+
+    _name = "fusion.billing.metric"
+    _description = "Fusion Billing — Billable Metric"
+    _order = "code"
+
+    name = fields.Char(required=True)
+    code = fields.Char(required=True, index=True)
+    aggregation = fields.Selection(
+        [
+            ("sum", "Sum"),
+            ("max", "Max"),
+            ("last", "Last value"),
+            ("unique_count", "Unique count"),
+        ],
+        default="sum", required=True,
+    )
+    unit_label = fields.Char(help="e.g. CPU-seconds, API calls, messages, tokens.")
+    rounding = fields.Float(default=1.0)
+    active = fields.Boolean(default=True)
+
+    _code_uniq = models.Constraint("unique(code)", "Metric code must be unique.")

fusion_centralize_billing/models/reconciliation.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingReconciliation(models.Model):
+    """Dual-run shadow-mode comparison: Odoo-computed vs the app's actual billing.
+
+    During phased cutover (NexaCloud first), Odoo computes invoices while the app
+    keeps charging. This row records the per-customer, per-period delta so we only
+    flip once deltas are within tolerance. See spec §10.
+    """
+
+    _name = "fusion.billing.reconciliation"
+    _description = "Fusion Billing — Dual-Run Reconciliation"
+    _order = "period desc, service_id"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    partner_id = fields.Many2one("res.partner", required=True, ondelete="cascade", index=True)
+    period = fields.Char(required=True, help="Billing period label, e.g. 2026-05.")
+    odoo_amount = fields.Monetary()
+    external_amount = fields.Monetary(string="App-actual Amount")
+    delta = fields.Monetary(help="odoo_amount - external_amount.")
+    currency_id = fields.Many2one(
+        "res.currency", default=lambda self: self.env.company.currency_id,
+    )
+    status = fields.Selection(
+        [
+            ("match", "Within tolerance"),
+            ("delta", "Delta — investigate"),
+            ("resolved", "Resolved"),
+        ],
+        default="delta", required=True, index=True,
+    )
+    note = fields.Text()

fusion_centralize_billing/models/service.py

@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+import hashlib
+import secrets
+
+from odoo import api, fields, models
+
+
+class FusionBillingService(models.Model):
+    """A source app that pushes billing data (NexaCloud / NexaDesk / NexaMaps).
+
+    The bearer API key is shown ONCE on generation and stored only as a SHA-256
+    hash. This record is the auth + routing boundary for the inbound API and the
+    target for outbound webhooks. See spec §5.1 / §7 / §8.
+    """
+
+    _name = "fusion.billing.service"
+    _description = "Fusion Billing — Source Service"
+    _order = "name"
+
+    name = fields.Char(required=True)
+    code = fields.Char(
+        required=True, index=True,
+        help="Stable code the app identifies itself with, e.g. nexacloud / nexadesk / nexamaps.",
+    )
+    active = fields.Boolean(default=True)
+
+    api_key_hash = fields.Char(
+        string="API Key (SHA-256)",
+        help="Hash of the bearer key. The raw key is displayed once at generation time.",
+    )
+    webhook_url = fields.Char(help="Endpoint this app exposes to receive billing webhooks.")
+    webhook_secret = fields.Char(help="Shared secret for HMAC-SHA256 webhook signatures.")
+
+    account_link_ids = fields.One2many(
+        "fusion.billing.account.link", "service_id", string="Customer Links",
+    )
+    account_link_count = fields.Integer(compute="_compute_account_link_count")
+
+    _code_uniq = models.Constraint("unique(code)", "Service code must be unique.")
+
+    @api.depends("account_link_ids")
+    def _compute_account_link_count(self):
+        for rec in self:
+            rec.account_link_count = len(rec.account_link_ids)
+
+    def action_generate_api_key(self):
+        """Generate a fresh bearer key, store only its hash, return the raw key.
+
+        TODO(spec §7): surface the raw key once in the UI (wizard/notification).
+        """
+        self.ensure_one()
+        raw = secrets.token_urlsafe(32)
+        self.api_key_hash = hashlib.sha256(raw.encode()).hexdigest()
+        return raw
+
+    @api.model
+    def _match_api_key(self, raw_key):
+        """Return the active service whose stored hash matches raw_key, else empty recordset."""
+        if not raw_key:
+            return self.browse()
+        key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
+        return self.search([('api_key_hash', '=', key_hash), ('active', '=', True)], limit=1)
+
+    def _api_upsert_customer(self, payload):
+        self.ensure_one()
+        ext = payload.get('external_id')
+        if not ext:
+            return {'status': 'error', 'error': 'external_id required'}
+        link = self.env['fusion.billing.account.link']._resolve_or_create_partner(
+            self, ext, name=payload.get('name'), email=payload.get('email'))
+        return {'status': 'ok', 'partner_id': link.partner_id.id, 'external_id': ext}
+
+    def _api_record_usage(self, payload):
+        self.ensure_one()
+        events = payload.get('events') or []
+        Usage = self.env['fusion.billing.usage']
+        accepted = 0
+        for ev in events:
+            sub = self.env['sale.order'].browse(int(ev['subscription_external_id']))
+            Usage._record_usage(
+                sub, ev['metric_code'], float(ev['quantity']),
+                ev['period_start'], ev['period_end'], idem=ev.get('idempotency_key'))
+            accepted += 1
+        return {'status': 'ok', 'accepted': accepted}
+
+    def _api_catalog(self):
+        self.ensure_one()
+        charges = self.env['fusion.billing.charge'].search([('active', '=', True)])
+        return {'status': 'ok', 'charges': [{
+            'plan_code': c.plan_code, 'metric': c.metric_id.code,
+            'included_quota': c.included_quota, 'price_per_unit': c.price_per_unit,
+            'unit_batch': c.unit_batch, 'charge_model': c.charge_model,
+        } for c in charges]}
+
+    def _api_create_subscription(self, payload):
+        """Create and confirm a subscription sale.order for an external customer.
+
+        The product on each line must have recurring_invoice=True so that
+        Odoo recognises the order as a subscription with has_recurring_line and
+        action_confirm() reaches subscription_state='3_progress'.
+        """
+        self.ensure_one()
+        link = self.env['fusion.billing.account.link'].search([
+            ('service_id', '=', self.id),
+            ('external_id', '=', payload.get('external_customer_id')),
+        ], limit=1)
+        if not link:
+            return {'status': 'error', 'error': 'unknown customer'}
+        order_lines = [(0, 0, {
+            'product_id': line['product_id'],
+            'product_uom_qty': line.get('quantity', 1),
+        }) for line in payload.get('lines', [])]
+        sub = self.env['sale.order'].sudo().create({
+            'partner_id': link.partner_id.id,
+            'plan_id': payload['plan_id'],
+            'order_line': order_lines,
+        })
+        sub.action_confirm()
+        return {'status': 'ok', 'subscription_id': sub.id,
+                'subscription_state': sub.subscription_state}

fusion_centralize_billing/models/usage.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import api, fields, models
+
+
+class FusionBillingUsage(models.Model):
+    """Aggregated usage rollup for a (subscription, metric, period).
+
+    Aggregate-push model: apps send periodic counters (not raw events). The
+    ``idempotency_key`` makes re-sent counters safe — they never double-count.
+    A pre-invoice cron sums these and feeds billable quantity onto the subscription.
+
+    NOTE (Odoo 19, verified): the subscription is a ``sale.order`` with
+    ``is_subscription=True`` — there is no ``sale.subscription`` model. See spec §5.2.
+    """
+
+    _name = "fusion.billing.usage"
+    _description = "Fusion Billing — Aggregated Usage (period rollup)"
+    _order = "period_start desc"
+
+    subscription_id = fields.Many2one(
+        "sale.order", required=True, ondelete="cascade", index=True,
+        string="Subscription", domain=[("is_subscription", "=", True)],
+    )
+    metric_id = fields.Many2one(
+        "fusion.billing.metric", required=True, ondelete="restrict", index=True,
+    )
+    period_start = fields.Datetime(required=True)
+    period_end = fields.Datetime(required=True)
+    quantity = fields.Float(default=0.0)
+    source = fields.Char(default="push")
+    idempotency_key = fields.Char(
+        index=True, help="Dedupe key so re-sent counters never double-count.",
+    )
+
+    _idempotency_uniq = models.Constraint(
+        "unique(idempotency_key)", "Usage idempotency key must be unique.",
+    )
+
+    @api.model
+    def _record_usage(self, subscription, metric_code, quantity, period_start, period_end, idem=None):
+        """Upsert one aggregated usage row. Same idempotency key updates in place (no double-count)."""
+        metric = self.env['fusion.billing.metric'].search([('code', '=', metric_code)], limit=1)
+        if not metric:
+            raise ValueError("Unknown metric code: %s" % metric_code)
+        vals = {
+            'subscription_id': subscription.id,
+            'metric_id': metric.id,
+            'period_start': period_start,
+            'period_end': period_end,
+            'quantity': quantity,
+            'idempotency_key': idem,
+        }
+        if idem:
+            existing = self.search([('idempotency_key', '=', idem)], limit=1)
+            if existing:
+                existing.write({'quantity': quantity})
+                return existing
+        return self.create(vals)
+
+    @api.model
+    def _aggregate(self, subscription, metric, period_start, period_end):
+        """Aggregate stored usage for a subscription+metric within [period_start, period_end)
+        using the metric's aggregation function."""
+        rows = self.search([
+            ('subscription_id', '=', subscription.id),
+            ('metric_id', '=', metric.id),
+            ('period_start', '>=', period_start),
+            ('period_end', '<=', period_end),
+        ])
+        qtys = rows.mapped('quantity')
+        if not qtys:
+            return 0.0
+        agg = metric.aggregation
+        if agg == 'sum':
+            return sum(qtys)
+        if agg == 'max':
+            return max(qtys)
+        if agg == 'last':
+            return rows.sorted('period_start')[-1].quantity
+        if agg == 'unique_count':
+            return float(len(set(qtys)))
+        return sum(qtys)

fusion_centralize_billing/models/webhook.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+import hashlib
+import hmac
+import json
+import logging
+from datetime import timedelta
+
+import requests
+
+from odoo import api, fields, models
+
+_logger = logging.getLogger(__name__)
+
+MAX_ATTEMPTS = 8
+
+
+class FusionBillingWebhook(models.Model):
+    """Outbound webhook queue: lifecycle events delivered to source apps.
+
+    Processed by a cron with exponential backoff + HMAC-SHA256 signing, dead-lettered
+    after N attempts (mirror the proven retry pattern in NexaDesk's
+    lago-payment-retry-job). Apps react: suspend / restore / deprovision. See spec §8.
+
+    TODO(spec §8): cron processor, HMAC signing, backoff schedule.
+    """
+
+    _name = "fusion.billing.webhook"
+    _description = "Fusion Billing — Outbound Webhook Event"
+    _order = "create_date desc"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    event_type = fields.Char(
+        required=True, index=True,
+        help="invoice.payment_failed / invoice.payment_succeeded / "
+             "subscription.terminated / subscription.reactivated / usage.threshold_reached",
+    )
+    payload = fields.Json()
+    state = fields.Selection(
+        [
+            ("pending", "Pending"),
+            ("sent", "Sent"),
+            ("failed", "Failed"),
+            ("dead", "Dead-lettered"),
+        ],
+        default="pending", required=True, index=True,
+    )
+    attempts = fields.Integer(default=0)
+    next_retry_at = fields.Datetime()
+    signature = fields.Char(help="HMAC-SHA256 of the payload using the service webhook_secret.")
+    last_error = fields.Text()
+
+    @api.model
+    def _sign(self, secret, body):
+        return hmac.new((secret or '').encode(), body.encode(), hashlib.sha256).hexdigest()
+
+    @api.model
+    def _enqueue(self, service, event_type, payload):
+        body = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+        return self.create({
+            'service_id': service.id,
+            'event_type': event_type,
+            'payload': payload,
+            'signature': self._sign(service.webhook_secret, body),
+            'state': 'pending',
+            'next_retry_at': fields.Datetime.now(),
+        })
+
+    @api.model
+    def _cron_dispatch(self):
+        now = fields.Datetime.now()
+        due = self.search([
+            ('state', 'in', ('pending', 'failed')),
+            ('next_retry_at', '<=', now),
+        ], limit=100)
+        for wh in due:
+            body = json.dumps(wh.payload, sort_keys=True, separators=(',', ':'))
+            try:
+                resp = requests.post(
+                    wh.service_id.webhook_url,
+                    data=body,
+                    headers={'Content-Type': 'application/json',
+                             'X-Fusion-Signature': wh.signature,
+                             'X-Fusion-Event': wh.event_type},
+                    timeout=10,
+                )
+                ok = 200 <= resp.status_code < 300
+            except Exception as e:  # noqa: BLE001 - record and retry
+                ok = False
+                wh.last_error = str(e)[:500]
+            wh.attempts += 1
+            if ok:
+                wh.state = 'sent'
+            elif wh.attempts >= MAX_ATTEMPTS:
+                wh.state = 'dead'
+            else:
+                wh.state = 'failed'
+                wh.next_retry_at = now + timedelta(minutes=2 ** wh.attempts)

fusion_centralize_billing/security/ir.model.access.csv

@@ -0,0 +1,11 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_fusion_billing_service_admin,fusion.billing.service admin,model_fusion_billing_service,base.group_system,1,1,1,1
+access_fusion_billing_account_link_admin,fusion.billing.account.link admin,model_fusion_billing_account_link,base.group_system,1,1,1,1
+access_fusion_billing_metric_admin,fusion.billing.metric admin,model_fusion_billing_metric,base.group_system,1,1,1,1
+access_fusion_billing_charge_admin,fusion.billing.charge admin,model_fusion_billing_charge,base.group_system,1,1,1,1
+access_fusion_billing_usage_admin,fusion.billing.usage admin,model_fusion_billing_usage,base.group_system,1,1,1,1
+access_fusion_billing_webhook_admin,fusion.billing.webhook admin,model_fusion_billing_webhook,base.group_system,1,1,1,1
+access_fusion_billing_reconciliation_admin,fusion.billing.reconciliation admin,model_fusion_billing_reconciliation,base.group_system,1,1,1,1
+access_fusion_billing_metric_acct,fusion.billing.metric accountant,model_fusion_billing_metric,account.group_account_manager,1,1,1,0
+access_fusion_billing_charge_acct,fusion.billing.charge accountant,model_fusion_billing_charge,account.group_account_manager,1,1,1,0
+access_fusion_billing_reconciliation_acct,fusion.billing.reconciliation accountant,model_fusion_billing_reconciliation,account.group_account_manager,1,1,1,0

fusion_centralize_billing/tests/__init__.py

@@ -0,0 +1,5 @@
+from . import test_identity
+from . import test_charge
+from . import test_usage
+from . import test_api
+from . import test_webhook

fusion_centralize_billing/tests/test_api.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestApiHandlers(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.service = self.env['fusion.billing.service'].sudo().create(
+            {'name': 'NexaMaps', 'code': 'nexamaps'})
+        self.env['fusion.billing.metric'].sudo().create(
+            {'name': 'API Calls', 'code': 'api_calls', 'aggregation': 'sum'})
+        self.plan = self.env['sale.subscription.plan'].sudo().create(
+            {'name': 'Monthly', 'billing_period_value': 1, 'billing_period_unit': 'month'})
+
+    def test_api_upsert_customer(self):
+        res = self.service._api_upsert_customer(
+            {'external_id': 'client-9', 'name': 'Globex', 'email': 'billing@globex.test'})
+        self.assertEqual(res['status'], 'ok')
+        link = self.env['fusion.billing.account.link'].search(
+            [('service_id', '=', self.service.id), ('external_id', '=', 'client-9')])
+        self.assertEqual(link.partner_id.name, 'Globex')
+
+    def test_api_record_usage_batch(self):
+        self.service._api_upsert_customer({'external_id': 'client-9', 'name': 'Globex'})
+        partner = self.env['fusion.billing.account.link'].search(
+            [('external_id', '=', 'client-9')]).partner_id
+        sub = self.env['sale.order'].sudo().create(
+            {'partner_id': partner.id, 'is_subscription': True, 'plan_id': self.plan.id})
+        res = self.service._api_record_usage({'events': [{
+            'subscription_external_id': str(sub.id), 'metric_code': 'api_calls',
+            'quantity': 1234.0, 'period_start': '2026-05-01', 'period_end': '2026-06-01',
+            'idempotency_key': 'maps:client-9:2026-05-01',
+        }]})
+        self.assertEqual(res['accepted'], 1)
+        usage = self.env['fusion.billing.usage'].search([('subscription_id', '=', sub.id)])
+        self.assertEqual(usage.quantity, 1234.0)
+
+    def test_api_catalog_lists_active_charges(self):
+        self.env['fusion.billing.charge'].sudo().create({
+            'name': 'Maps overage', 'plan_code': 'maps-business',
+            'metric_id': self.env['fusion.billing.metric'].search([('code', '=', 'api_calls')]).id,
+            'included_quota': 5_000_000.0, 'price_per_unit': 0.10, 'unit_batch': 1000.0})
+        cat = self.service._api_catalog()
+        codes = [c['plan_code'] for c in cat['charges']]
+        self.assertIn('maps-business', codes)
+
+    def test_api_create_subscription(self):
+        self.service._api_upsert_customer({'external_id': 'client-9', 'name': 'Globex'})
+        product = self.env['product.product'].sudo().create(
+            {'name': 'Maps Business', 'type': 'service', 'recurring_invoice': True,
+             'list_price': 249.0})
+        res = self.service._api_create_subscription({
+            'external_customer_id': 'client-9',
+            'plan_id': self.plan.id,
+            'lines': [{'product_id': product.id, 'quantity': 1}],
+        })
+        self.assertEqual(res['status'], 'ok')
+        sub = self.env['sale.order'].browse(res['subscription_id'])
+        self.assertTrue(sub.is_subscription)
+        self.assertEqual(sub.plan_id, self.plan)
+        self.assertEqual(sub.subscription_state, '3_progress')

fusion_centralize_billing/tests/test_charge.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestChargeMath(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.metric = self.env['fusion.billing.metric'].sudo().create(
+            {'name': 'API Calls', 'code': 'api_calls', 'aggregation': 'sum'})
+
+    def _charge(self, **kw):
+        vals = {
+            'name': 'Maps overage', 'plan_code': 'maps-business',
+            'metric_id': self.metric.id, 'charge_model': 'standard',
+            'included_quota': 5_000_000.0, 'price_per_unit': 0.10, 'unit_batch': 1000.0,
+        }
+        vals.update(kw)
+        return self.env['fusion.billing.charge'].sudo().create(vals)
+
+    def test_under_quota_is_free(self):
+        charge = self._charge()
+        overage_units, amount = charge._compute_billable(4_000_000.0)
+        self.assertEqual(overage_units, 0.0)
+        self.assertEqual(amount, 0.0)
+
+    def test_standard_overage_per_1k(self):
+        charge = self._charge()
+        # 6,000,000 used - 5,000,000 quota = 1,000,000 overage = 1000 batches * $0.10
+        overage_units, amount = charge._compute_billable(6_000_000.0)
+        self.assertEqual(overage_units, 1_000_000.0)
+        self.assertAlmostEqual(amount, 100.0, places=2)
+
+    def test_partial_batch_rounds_up(self):
+        charge = self._charge(included_quota=0.0)
+        # 1,500 units, batch 1000 -> 2 batches -> $0.20
+        _, amount = charge._compute_billable(1_500.0)
+        self.assertAlmostEqual(amount, 0.20, places=2)
+
+    def test_package_model_charges_whole_packages(self):
+        charge = self._charge(charge_model='package', included_quota=0.0, unit_batch=1000.0, price_per_unit=2.0)
+        # 2,001 units -> 3 packages -> $6.00
+        _, amount = charge._compute_billable(2_001.0)
+        self.assertAlmostEqual(amount, 6.0, places=2)

fusion_centralize_billing/tests/test_identity.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestServiceApiKey(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.Service = self.env['fusion.billing.service'].sudo()
+        self.service = self.Service.create({'name': 'NexaCloud', 'code': 'nexacloud'})
+
+    def test_generate_and_match_api_key(self):
+        raw = self.service.action_generate_api_key()
+        self.assertTrue(raw and len(raw) >= 20)
+        self.assertTrue(self.service.api_key_hash)
+        self.assertNotEqual(raw, self.service.api_key_hash)  # only the hash is stored
+        matched = self.Service._match_api_key(raw)
+        self.assertEqual(matched, self.service)
+
+    def test_match_api_key_rejects_unknown_and_inactive(self):
+        raw = self.service.action_generate_api_key()
+        self.assertFalse(self.Service._match_api_key('nope-not-a-key'))
+        self.service.active = False
+        self.assertFalse(self.Service._match_api_key(raw))
+
+
+@tagged('post_install', '-at_install')
+class TestIdentityResolution(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.service = self.env['fusion.billing.service'].sudo().create(
+            {'name': 'NexaDesk', 'code': 'nexadesk'})
+        self.Link = self.env['fusion.billing.account.link'].sudo()
+
+    def test_creates_partner_first_time(self):
+        link = self.Link._resolve_or_create_partner(
+            self.service, external_id='tenant-1', name='Acme Inc', email='ar@acme.test')
+        self.assertTrue(link.partner_id)
+        self.assertEqual(link.partner_id.name, 'Acme Inc')
+        self.assertEqual(link.external_id, 'tenant-1')
+
+    def test_idempotent_same_external_id(self):
+        a = self.Link._resolve_or_create_partner(self.service, 'tenant-1', 'Acme', 'ar@acme.test')
+        b = self.Link._resolve_or_create_partner(self.service, 'tenant-1', 'Acme Renamed', 'ar@acme.test')
+        self.assertEqual(a, b)                      # same link row
+        self.assertEqual(a.partner_id, b.partner_id)  # same partner
+
+    def test_reuses_partner_by_email_across_services(self):
+        other = self.env['fusion.billing.service'].sudo().create({'name': 'Maps', 'code': 'nexamaps'})
+        a = self.Link._resolve_or_create_partner(self.service, 'tenant-1', 'Acme', 'ar@acme.test')
+        b = self.Link._resolve_or_create_partner(other, 'client-9', 'Acme', 'ar@acme.test')
+        self.assertEqual(a.partner_id, b.partner_id)  # one unified customer
+        self.assertNotEqual(a, b)                     # but distinct link rows

fusion_centralize_billing/tests/test_usage.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestUsageIngestion(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.metric = self.env['fusion.billing.metric'].sudo().create(
+            {'name': 'CPU seconds', 'code': 'cpu_seconds', 'aggregation': 'sum'})
+        self.plan = self.env['sale.subscription.plan'].sudo().create(
+            {'name': 'Monthly', 'billing_period_value': 1, 'billing_period_unit': 'month'})
+        self.partner = self.env['res.partner'].sudo().create({'name': 'Acme'})
+        self.sub = self.env['sale.order'].sudo().create({
+            'partner_id': self.partner.id, 'is_subscription': True, 'plan_id': self.plan.id,
+        })
+        self.Usage = self.env['fusion.billing.usage'].sudo()
+
+    def test_record_usage_creates_row(self):
+        u = self.Usage._record_usage(
+            self.sub, 'cpu_seconds', 120.0,
+            '2026-05-01 00:00:00', '2026-06-01 00:00:00', idem='nexacloud:cpu:sub1:2026-05-01')
+        self.assertEqual(u.quantity, 120.0)
+        self.assertEqual(u.metric_id, self.metric)
+
+    def test_idempotent_key_updates_not_duplicates(self):
+        k = 'nexacloud:cpu:sub1:2026-05-01'
+        self.Usage._record_usage(self.sub, 'cpu_seconds', 100.0, '2026-05-01', '2026-06-01', idem=k)
+        self.Usage._record_usage(self.sub, 'cpu_seconds', 175.0, '2026-05-01', '2026-06-01', idem=k)
+        rows = self.Usage.search([('idempotency_key', '=', k)])
+        self.assertEqual(len(rows), 1)        # no duplicate
+        self.assertEqual(rows.quantity, 175.0)  # last value wins for the same key
+
+    def test_aggregate_sum(self):
+        for i, q in enumerate([10.0, 20.0, 30.0]):
+            self.Usage._record_usage(self.sub, 'cpu_seconds', q,
+                                     '2026-05-01', '2026-06-01', idem='cpu-%d' % i)
+        total = self.Usage._aggregate(self.sub, self.metric, '2026-05-01', '2026-06-01')
+        self.assertEqual(total, 60.0)
+
+    def test_aggregate_max(self):
+        self.metric.aggregation = 'max'
+        for i, q in enumerate([10.0, 55.0, 30.0]):
+            self.Usage._record_usage(self.sub, 'cpu_seconds', q,
+                                     '2026-05-01', '2026-06-01', idem='m-%d' % i)
+        self.assertEqual(self.Usage._aggregate(self.sub, self.metric, '2026-05-01', '2026-06-01'), 55.0)
+
+    def test_aggregate_excludes_other_periods(self):
+        self.Usage._record_usage(self.sub, 'cpu_seconds', 99.0, '2026-04-01', '2026-05-01', idem='apr')
+        self.Usage._record_usage(self.sub, 'cpu_seconds', 5.0, '2026-05-01', '2026-06-01', idem='may')
+        self.assertEqual(self.Usage._aggregate(self.sub, self.metric, '2026-05-01', '2026-06-01'), 5.0)

fusion_centralize_billing/tests/test_webhook.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+import hashlib
+import hmac
+import json
+from unittest.mock import patch
+
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestWebhookEngine(TransactionCase):
+
+    def setUp(self):
+        super().setUp()
+        self.service = self.env['fusion.billing.service'].sudo().create({
+            'name': 'NexaCloud', 'code': 'nexacloud',
+            'webhook_url': 'https://api.vps.nexasystems.ca/billing/webhook',
+            'webhook_secret': 'whsec_test',
+        })
+        self.Webhook = self.env['fusion.billing.webhook'].sudo()
+
+    def test_enqueue_signs_payload(self):
+        wh = self.Webhook._enqueue(self.service, 'invoice.payment_failed', {'invoice': 'INV-1'})
+        self.assertEqual(wh.state, 'pending')
+        body = json.dumps({'invoice': 'INV-1'}, sort_keys=True, separators=(',', ':'))
+        expected = hmac.new(b'whsec_test', body.encode(), hashlib.sha256).hexdigest()
+        self.assertEqual(wh.signature, expected)
+
+    def test_dispatch_marks_sent_on_2xx(self):
+        wh = self.Webhook._enqueue(self.service, 'invoice.paid', {'invoice': 'INV-2'})
+
+        class _Resp:
+            status_code = 200
+            text = 'ok'
+
+        with patch('odoo.addons.fusion_centralize_billing.models.webhook.requests.post',
+                   return_value=_Resp()) as mock_post:
+            self.Webhook._cron_dispatch()
+            self.assertTrue(mock_post.called)
+        self.assertEqual(wh.state, 'sent')
+
+    def test_dispatch_retries_then_deadletters(self):
+        wh = self.Webhook._enqueue(self.service, 'invoice.paid', {'invoice': 'INV-3'})
+        wh.write({'attempts': 7})  # already past max
+
+        class _Resp:
+            status_code = 500
+            text = 'err'
+
+        with patch('odoo.addons.fusion_centralize_billing.models.webhook.requests.post',
+                   return_value=_Resp()):
+            self.Webhook._cron_dispatch()
+        self.assertEqual(wh.state, 'dead')

fusion_clock/CLAUDE.md

@@ -0,0 +1,358 @@
+# Fusion Clock - Claude Code Instructions
+
+> Read together with the repo-root `../CLAUDE.md` for global Odoo 19 rules, asset-cache handling, Supabase KB notes, and shared Fusion conventions. This file is only for the `fusion_clock` module.
+
+## 1. What This Module Is
+
+- **Name**: Fusion Clock.
+- **Version**: `19.0.3.3.0`.
+- **Category**: Human Resources/Attendances.
+- **License**: OPL-1, Nexa Systems Inc.
+- **Purpose**: complete time and attendance app built on Odoo `hr.attendance`.
+- **Top-level menu**: `Fusion Clock`.
+- **Main surfaces**:
+  - Portal clock page at `/my/clock`.
+  - Portal timesheets at `/my/clock/timesheets`.
+  - Portal reports at `/my/clock/reports`.
+  - Shared PIN kiosk at `/fusion_clock/kiosk`.
+  - NFC tap kiosk at `/fusion_clock/kiosk/nfc`.
+  - Backend systray clock widget.
+  - Backend manager/team-lead dashboard client action.
+
+Core behaviours: geofenced clock-in/out, IP whitelist fallback, shift scheduling, break deduction, penalties, overtime, auto clock-out, absence detection, leave requests, correction workflow, payroll CSV export, PDF reports, weekly summaries, shared kiosk, NFC kiosk with photo capture, and activity audit logs.
+
+## 2. Dependencies
+
+Declared in `__manifest__.py`:
+
+```
+hr_attendance, hr, portal, mail, resource
+```
+
+External Python used directly:
+
+- `pytz` for timezone-safe local day boundaries.
+- `requests` for Google Geocoding, OpenStreetMap/Nominatim fallback, and IP metadata.
+- `dateutil.relativedelta` inside pay-period calculations.
+
+External browser APIs:
+
+- Browser geolocation.
+- `ipapi.co` fallback geolocation in frontend/backend clock widgets.
+- Google Maps/Places when `fusion_clock.google_maps_api_key` is configured.
+- Web NFC and camera APIs for the NFC kiosk.
+
+## 3. Naming And Field Prefixes
+
+This module uses the module-specific prefix **`x_fclk_*`** on inherited Odoo models, not `x_fc_*`.
+
+Examples:
+
+- `hr.employee.x_fclk_enable_clock`
+- `hr.employee.x_fclk_nfc_card_uid`
+- `hr.attendance.x_fclk_clock_source`
+- `res.company.x_fclk_nfc_kiosk_location_id`
+
+New inherited fields in this module should keep the `x_fclk_*` prefix unless there is a strong migration reason not to.
+
+## 4. Model Map
+
+Custom models:
+
+| Model | File | Purpose |
+|---|---|---|
+| `fusion.clock.location` | `models/clock_location.py` | Geofenced/IP-whitelisted clock locations. |
+| `fusion.clock.shift` | `models/clock_shift.py` | Shift start/end/break schedule assigned to employees. |
+| `fusion.clock.penalty` | `models/clock_penalty.py` | Late clock-in / early clock-out penalty records. |
+| `fusion.clock.activity.log` | `models/clock_activity_log.py` | Append-style audit log for clock activity, geofence misses, absences, NFC enrolment, corrections. |
+| `fusion.clock.leave.request` | `models/clock_leave_request.py` | Portal leave requests, auto-approved but office-notified. |
+| `fusion.clock.correction` | `models/clock_correction.py` | Timesheet correction requests with approve/reject workflow. |
+| `fusion.clock.report` | `models/clock_report.py` | Employee or batch pay-period report with PDF/CSV export and email send. |
+| `fusion.clock.nfc.enrollment.wizard` | `wizard/clock_nfc_enrollment_wizard.py` | Backend NFC card enrolment/reassignment wizard. |
+
+Inherited models:
+
+- `hr.employee`: enable clock, default location, shift, kiosk PIN, NFC UID, pending reason flag, streaks, absence/overtime counters, and One2many links.
+- `hr.attendance`: clock source, location, distances, photos, break minutes, net hours, penalties, auto clock-out flag, overtime fields.
+- `res.config.settings`: all `fusion_clock.*` settings.
+- `res.company`: NFC kiosk location binding.
+
+Timezone helpers live in `models/tz_utils.py`. Use `get_local_today()` and `get_local_day_boundaries()` for attendance domains instead of comparing UTC dates directly.
+
+## 5. Clocking Flow
+
+Primary API endpoint: `/fusion_clock/clock_action` in `controllers/clock_api.py`.
+
+Clock-in flow:
+
+1. Resolve current user to `hr.employee`.
+2. Block if `x_fclk_enable_clock` is false.
+3. If `x_fclk_pending_reason` is true, return `requires_reason`.
+4. Verify location against allowed active `fusion.clock.location` records.
+5. Call Odoo's `_attendance_action_change()`.
+6. Write location, distance, source, and optional photo to `hr.attendance`.
+7. Log `clock_in`.
+8. Create `late_in` penalty when outside grace.
+9. Increment/reset on-time streak; log milestone at 5, 10, 20, 50, 100.
+10. Notify office user for very-late clock-ins.
+
+Clock-out flow:
+
+1. Verify location again.
+2. Call `_attendance_action_change()`.
+3. Write out-distance.
+4. Apply break deduction when configured.
+5. Create `early_out` penalty when outside grace.
+6. Log `clock_out`.
+7. Log overtime if computed overtime is positive.
+
+Location verification uses GPS when coordinates are available and geocoded locations exist. IP whitelist matching is attempted when a client IP is available. Error types include `no_locations`, `gps_unavailable`, `no_geocoded`, and `outside`.
+
+## 6. Kiosk And NFC
+
+Classic kiosk:
+
+- Page: `/fusion_clock/kiosk`
+- JSON routes:
+  - `/fusion_clock/kiosk/search`
+  - `/fusion_clock/kiosk/verify_pin`
+  - `/fusion_clock/kiosk/clock`
+- Requires `fusion_clock.group_fusion_clock_manager`.
+- Controlled by `fusion_clock.enable_kiosk` and `fusion_clock.kiosk_pin_required`.
+- Uses `hr.employee.x_fclk_kiosk_pin`.
+
+NFC kiosk:
+
+- Page: `/fusion_clock/kiosk/nfc`
+- JSON routes:
+  - `/fusion_clock/kiosk/nfc/enroll`
+  - `/fusion_clock/kiosk/nfc/tap`
+  - `/fusion_clock/kiosk/nfc/employee_search`
+- Requires `fusion_clock.group_fusion_clock_manager`.
+- Controlled by:
+  - `fusion_clock.enable_nfc_kiosk`
+  - `fusion_clock.nfc_photo_required`
+  - `fusion_clock.nfc_enroll_password`
+  - `fusion_clock.nfc_kiosk_debug`
+  - `res.company.x_fclk_nfc_kiosk_location_id`
+- Card UID canonical format is uppercase colon-separated hex, e.g. `04:A2:B5:62:C1:80`.
+- Normalization lives in `FusionClockNfcKiosk._normalize_uid()` and is reused by the backend wizard.
+- Tap debounce is module-level memory in `controllers/clock_nfc_kiosk.py`: same UID within 5 seconds returns `debounce`.
+- Photo data URLs are stripped before writing binary fields.
+- NFC clock-ins write `x_fclk_check_in_photo`; NFC clock-outs write `x_fclk_check_out_photo`.
+
+Important: unknown-card taps currently return `card_unknown`; the `unknown_card_tap` log type exists but is not written by the endpoint.
+
+## 7. Reports And Payroll Export
+
+`fusion.clock.report` supports:
+
+- Employee reports when `employee_id` is set.
+- Batch reports when `employee_id` is empty.
+- PDF generation through QWeb reports:
+  - `fusion_clock.action_report_clock_employee`
+  - `fusion_clock.action_report_clock_batch`
+- CSV export via `action_export_csv()`.
+- Custom CSV headings via JSON in `fusion_clock.csv_column_mapping`.
+- Email send with generated PDF attached.
+
+Pay period types:
+
+```
+weekly, biweekly, semi_monthly, monthly
+```
+
+The anchor date setting is `fusion_clock.pay_period_start` as a string in `YYYY-MM-DD` format.
+
+Historical report generation is exposed through the `Generate Historical Reports` menu action and creates draft reports for completed attendance periods. The scheduled report cron only generates when yesterday is the period end.
+
+## 8. Scheduled Automation
+
+Configured in `data/ir_cron_data.xml`:
+
+| Cron | Model method | Frequency |
+|---|---|---|
+| Fusion Clock: Auto Clock-Out | `hr.attendance._cron_fusion_auto_clock_out()` | Every 15 minutes |
+| Fusion Clock: Generate Period Reports | `fusion.clock.report._cron_generate_period_reports()` | Daily |
+| Fusion Clock: Daily Absence Check | `hr.attendance._cron_fusion_check_absences()` | Daily |
+| Fusion Clock: Employee Reminders | `hr.attendance._cron_fusion_employee_reminders()` | Every 15 minutes |
+| Fusion Clock: Weekly Summary | `hr.attendance._cron_fusion_weekly_summary()` | Daily, internally sends Mondays |
+
+Auto clock-out closes open attendances after scheduled end plus grace, capped by max shift hours. It sets `x_fclk_pending_reason` so the employee must explain before clocking in again.
+
+Absence detection checks enabled employees, skips weekends and global resource calendar leaves, and logs `absent` when no attendance or leave request exists.
+
+## 9. Security
+
+Groups:
+
+- `group_fusion_clock_user`
+- `group_fusion_clock_team_lead`
+- `group_fusion_clock_manager`
+
+Admin is auto-assigned to manager in `security/security.xml`.
+
+Access pattern:
+
+- Users and portal users can read their own clock data.
+- Team leads can read direct reports for penalties, activity logs, corrections, and dashboard data.
+- Managers have full model access and all configuration/kiosk/report menus.
+- Portal rules are defined for `hr.attendance`, `fusion.clock.location`, `fusion.clock.report`, `fusion.clock.penalty`, `fusion.clock.activity.log`, `fusion.clock.leave.request`, `fusion.clock.correction`, and `fusion.clock.shift`.
+
+Backend dashboard access is checked in `/fusion_clock/dashboard_data`: manager sees all enabled employees; team lead sees employees where `parent_id` is the current user's employee.
+
+## 10. Frontend Assets
+
+Frontend bundle:
+
+- `static/src/css/portal_clock.css`
+- `static/src/scss/nfc_kiosk.scss`
+- `static/src/js/fusion_clock_portal.js`
+- `static/src/js/fusion_clock_kiosk.js`
+- `static/src/js/fusion_clock_nfc_kiosk.js`
+
+Backend bundle:
+
+- `static/src/scss/fusion_clock.scss`
+- `static/src/js/fusion_clock_systray.js`
+- `static/src/xml/systray_clock.xml`
+- `static/src/js/fusion_clock_dashboard.js`
+- `static/src/xml/fusion_clock_dashboard.xml`
+- `static/src/js/fusion_clock_location_map.js`
+- `static/src/js/fusion_clock_location_places.js`
+- `static/src/xml/fusion_clock_location.xml`
+
+Patterns:
+
+- Public portal/kiosk JS should use `Interaction` from `@web/public/interaction` and register in `registry.category("public.interactions")`.
+- Backend OWL client actions and field widgets use standalone `rpc()` from `@web/core/network/rpc`.
+- `fusion_clock_systray.js` is a systray OWL component registered as `fusion_clock.ClockSystray`.
+- `fusion_clock_dashboard.js` is a client action registered as `fusion_clock.Dashboard`.
+- Location widgets are registered field widgets: `fclk_location_map` and `fclk_places_autocomplete`.
+
+Known technical debt:
+
+- `static/src/js/fusion_clock_nfc_kiosk.js` is currently an isolated IIFE. If touching it, prefer migrating to an Odoo 19 `Interaction` instead of expanding the IIFE pattern.
+- `static/src/css/portal_clock.css` and `static/src/scss/fusion_clock.scss` contain runtime dark-mode selectors/media rules. For backend SCSS changes, follow the repo-root Odoo 19 compile-time dark bundle guidance.
+- `fusion_clock.scss` uses some Bootstrap CSS vars for status accents. Avoid relying on Bootstrap vars for card/background/border surfaces in new dashboard work.
+
+## 11. Settings Keys
+
+Important `ir.config_parameter` keys:
+
+```
+fusion_clock.default_clock_in_time
+fusion_clock.default_clock_out_time
+fusion_clock.default_break_minutes
+fusion_clock.auto_deduct_break
+fusion_clock.break_threshold_hours
+fusion_clock.enable_auto_clockout
+fusion_clock.grace_period_minutes
+fusion_clock.max_shift_hours
+fusion_clock.enable_penalties
+fusion_clock.penalty_grace_minutes
+fusion_clock.penalty_deduction_minutes
+fusion_clock.enable_overtime
+fusion_clock.daily_overtime_threshold
+fusion_clock.weekly_overtime_threshold
+fusion_clock.office_user_id
+fusion_clock.very_late_threshold_minutes
+fusion_clock.max_monthly_absences
+fusion_clock.enable_employee_notifications
+fusion_clock.reminder_before_shift_minutes
+fusion_clock.reminder_before_end_minutes
+fusion_clock.send_weekly_summary
+fusion_clock.enable_ip_fallback
+fusion_clock.enable_photo_verification
+fusion_clock.google_maps_api_key
+fusion_clock.enable_kiosk
+fusion_clock.kiosk_pin_required
+fusion_clock.enable_correction_requests
+fusion_clock.enable_sounds
+fusion_clock.pay_period_type
+fusion_clock.pay_period_start
+fusion_clock.auto_generate_reports
+fusion_clock.send_employee_reports
+fusion_clock.report_recipient_user_ids
+fusion_clock.report_recipient_emails
+fusion_clock.csv_column_mapping
+fusion_clock.enable_nfc_kiosk
+fusion_clock.nfc_photo_required
+fusion_clock.nfc_enroll_password
+fusion_clock.nfc_kiosk_debug
+```
+
+`fclk_report_recipient_user_ids` is a Many2many on settings but is persisted manually as comma-separated user IDs in `fusion_clock.report_recipient_user_ids`.
+
+## 12. Routes
+
+HTTP pages:
+
+```
+/my/clock
+/my/clock/timesheets
+/my/clock/reports
+/my/clock/reports/<report_id>/download
+/fusion_clock/kiosk
+/fusion_clock/kiosk/nfc
+```
+
+JSON-RPC endpoints:
+
+```
+/fusion_clock/verify_location
+/fusion_clock/clock_action
+/fusion_clock/submit_reason
+/fusion_clock/request_leave
+/fusion_clock/request_correction
+/fusion_clock/get_status
+/fusion_clock/get_locations
+/fusion_clock/get_settings
+/fusion_clock/dashboard_data
+/fusion_clock/kiosk/search
+/fusion_clock/kiosk/verify_pin
+/fusion_clock/kiosk/clock
+/fusion_clock/kiosk/nfc/enroll
+/fusion_clock/kiosk/nfc/tap
+/fusion_clock/kiosk/nfc/employee_search
+```
+
+All new JSON endpoints must use `type="jsonrpc"`, not deprecated `type="json"`.
+
+## 13. Gotchas
+
+- Always use local-day helpers for date domains. UTC midnight boundaries will break attendance totals around timezone offsets.
+- `hr.employee._get_fclk_scheduled_times(date)` returns naive UTC datetimes suitable for Odoo comparisons.
+- Break deduction is stored as minutes in `hr.attendance.x_fclk_break_minutes`; penalties add to that same field.
+- `x_fclk_net_hours` is computed from Odoo `worked_hours` minus break minutes.
+- Daily overtime currently compares net hours to employee scheduled hours or daily threshold; weekly threshold is configured but not used in `hr.attendance._compute_overtime_hours()`.
+- `fusion_clock.enable_ip_fallback` exists in settings, but server-side `_verify_location()` attempts IP whitelist matching whenever a client IP is present.
+- NFC kiosk needs a company-level `x_fclk_nfc_kiosk_location_id`; without it taps return `no_location_configured`.
+- Kiosk routes are authenticated (`auth='user'`) and manager-gated; wall tablets need a manager-authorised kiosk user.
+- Portal report download manually streams the PDF binary rather than using `fusion_pdf_preview`.
+- If CSS/assets change, bump `__manifest__.py` version so Odoo rebuilds bundles.
+
+## 14. Tests
+
+Tests are post-install tagged:
+
+```
+@tagged('-at_install', 'post_install', 'fusion_clock')
+```
+
+Coverage currently focuses on NFC:
+
+- `tests/test_nfc_models.py`: employee UID uniqueness, attendance NFC source/photo fields, company kiosk location field.
+- `tests/test_clock_nfc_kiosk.py`: kiosk page gating, UID normalization, enroll endpoint, tap happy path, tap errors, photo-required handling, employee search.
+
+Run locally:
+
+```bash
+docker exec odoo-dev-app odoo -d fusion-dev -u fusion_clock --test-tags fusion_clock --stop-after-init
+```
+
+For a normal module upgrade:
+
+```bash
+docker exec odoo-dev-app odoo -d fusion-dev -u fusion_clock --stop-after-init
+```

fusion_clock/__manifest__.py

@@ -5,7 +5,7 @@
 
 {
     'name': 'Fusion Clock',
-    'version': '19.0.3.3.0',
+    'version': '19.0.3.5.6',
     'category': 'Human Resources/Attendances',
     'summary': 'Complete Employee T&A with Geofencing, Shifts, Penalties, Overtime, Kiosk, Dashboard & Payroll Export',
     'description': """
@@ -70,6 +70,7 @@ Integrates natively with Odoo's hr.attendance module for full payroll compatibil
         'views/clock_correction_views.xml',
         'views/clock_dashboard_views.xml',
         'views/hr_employee_views.xml',
+        'views/clock_schedule_views.xml',
         # Wizards (must load before clock_menus.xml since menu references wizard action)
         'wizard/clock_nfc_enrollment_views.xml',
         'views/clock_menus.xml',
@@ -89,15 +90,22 @@ Integrates natively with Odoo's hr.attendance module for full payroll compatibil
             'fusion_clock/static/src/js/fusion_clock_nfc_kiosk.js',
         ],
         'web.assets_backend': [
+            'fusion_clock/static/src/scss/_fusion_clock_shift_planner_tokens.scss',
+            'fusion_clock/static/src/scss/fusion_clock_shift_planner.scss',
             'fusion_clock/static/src/scss/fusion_clock.scss',
             'fusion_clock/static/src/js/fusion_clock_systray.js',
             'fusion_clock/static/src/xml/systray_clock.xml',
             'fusion_clock/static/src/js/fusion_clock_dashboard.js',
             'fusion_clock/static/src/xml/fusion_clock_dashboard.xml',
+            'fusion_clock/static/src/js/fusion_clock_shift_planner.js',
+            'fusion_clock/static/src/xml/fusion_clock_shift_planner.xml',
             'fusion_clock/static/src/js/fusion_clock_location_map.js',
             'fusion_clock/static/src/js/fusion_clock_location_places.js',
             'fusion_clock/static/src/xml/fusion_clock_location.xml',
         ],
+        'web.assets_web_dark': [
+            'fusion_clock/static/src/scss/fusion_clock_shift_planner.dark.scss',
+        ],
     },
     'installable': True,
     'auto_install': False,

fusion_clock/controllers/__init__.py

@@ -4,3 +4,4 @@ from . import portal_clock
 from . import clock_api
 from . import clock_kiosk
 from . import clock_nfc_kiosk
+from . import shift_planner

fusion_clock/controllers/clock_api.py

@@ -5,6 +5,7 @@
 import base64
 import math
 import logging
+import pytz
 from datetime import datetime, timedelta
 from odoo import http, fields, _
 from odoo.http import request
@@ -108,6 +109,9 @@ class FusionClockAPI(http.Controller):
         ICP = request.env['ir.config_parameter'].sudo()
         if ICP.get_param('fusion_clock.enable_penalties', 'True') != 'True':
             return
+        day_plan = employee._get_fclk_day_plan(get_local_today(request.env, employee))
+        if day_plan.get('source') == 'schedule' and day_plan.get('is_off'):
+            return
 
         grace = float(ICP.get_param('fusion_clock.penalty_grace_minutes', '5'))
         deduction = float(ICP.get_param('fusion_clock.penalty_deduction_minutes', '15'))
@@ -161,7 +165,16 @@ class FusionClockAPI(http.Controller):
         worked = attendance.worked_hours or 0.0
 
         if worked >= threshold:
-            break_min = employee._get_fclk_break_minutes()
+            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)
@@ -268,6 +281,8 @@ class FusionClockAPI(http.Controller):
 
         now = fields.Datetime.now()
         today = get_local_today(request.env, employee)
+        day_plan = employee._get_fclk_day_plan(today)
+        is_scheduled_off = day_plan.get('source') == 'schedule' and day_plan.get('is_off')
 
         geo_info = {
             'latitude': latitude,
@@ -307,6 +322,34 @@ class FusionClockAPI(http.Controller):
                     source=source,
                 )
 
+                if is_scheduled_off:
+                    self._log_activity(
+                        employee, 'unscheduled_shift',
+                        f"Clocked in on a scheduled OFF day at {location.name}.",
+                        attendance=attendance, location=location,
+                        latitude=latitude, longitude=longitude, distance=distance,
+                        source=source,
+                    )
+                    office_user_id = int(ICP.get_param('fusion_clock.office_user_id', '0'))
+                    if office_user_id:
+                        request.env['hr.attendance'].sudo()._fclk_notify_office(
+                            office_user_id,
+                            f"Unscheduled Shift: {employee.name}",
+                            f"{employee.name} clocked in on a scheduled OFF day.",
+                            'hr.attendance',
+                            attendance.id,
+                        )
+                    return {
+                        'success': True,
+                        'action': 'clock_in',
+                        'attendance_id': attendance.id,
+                        'check_in': fields.Datetime.to_string(attendance.check_in),
+                        'location_name': location.name,
+                        'location_address': location.address or '',
+                        'message': f'Clocked in at {location.name} (unscheduled shift)',
+                        'streak': employee.x_fclk_ontime_streak,
+                    }
+
                 # Check for late clock-in penalty
                 scheduled_in, _ = self._get_scheduled_times(employee, today)
                 self._check_and_create_penalty(employee, attendance, 'late_in', scheduled_in, now)
@@ -359,8 +402,9 @@ class FusionClockAPI(http.Controller):
                 self._apply_break_deduction(attendance, employee)
 
                 # Check for early clock-out penalty
-                _, scheduled_out = self._get_scheduled_times(employee, today)
-                self._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
+                if not is_scheduled_off:
+                    _, scheduled_out = self._get_scheduled_times(employee, today)
+                    self._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
 
                 # Log clock-out
                 self._log_activity(
@@ -518,6 +562,13 @@ class FusionClockAPI(http.Controller):
             'pending_reason': employee.x_fclk_pending_reason,
             'ontime_streak': employee.x_fclk_ontime_streak,
         }
+        local_today = get_local_today(request.env, employee)
+        day_plan = employee._get_fclk_day_plan(local_today)
+        result.update({
+            'scheduled_shift': day_plan.get('label') or '',
+            'scheduled_hours': round(day_plan.get('hours') or 0.0, 2),
+            'scheduled_off': bool(day_plan.get('is_off')),
+        })
 
         if is_checked_in:
             att = request.env['hr.attendance'].sudo().search([
@@ -533,7 +584,6 @@ class FusionClockAPI(http.Controller):
                     'location_id': att.x_fclk_location_id.id or False,
                 })
 
-        local_today = get_local_today(request.env, employee)
         today_start_utc, today_end_utc = get_local_day_boundaries(request.env, local_today, employee)
         today_atts = request.env['hr.attendance'].sudo().search([
             ('employee_id', '=', employee.id),

fusion_clock/controllers/clock_kiosk.py

@@ -5,6 +5,7 @@
 import logging
 from odoo import http, fields, _
 from odoo.http import request
+from odoo.addons.fusion_clock.models.tz_utils import get_local_today
 
 _logger = logging.getLogger(__name__)
 
@@ -93,7 +94,9 @@ class FusionClockKiosk(http.Controller):
 
         is_checked_in = employee.attendance_state == 'checked_in'
         now = fields.Datetime.now()
-        today = now.date()
+        today = get_local_today(request.env, employee)
+        day_plan = employee._get_fclk_day_plan(today)
+        is_scheduled_off = day_plan.get('source') == 'schedule' and day_plan.get('is_off')
 
         geo_info = {
             'latitude': latitude,
@@ -120,8 +123,17 @@ class FusionClockKiosk(http.Controller):
                     source='kiosk',
                 )
 
-                scheduled_in, _ = api._get_scheduled_times(employee, today)
-                api._check_and_create_penalty(employee, attendance, 'late_in', scheduled_in, now)
+                if is_scheduled_off:
+                    api._log_activity(
+                        employee, 'unscheduled_shift',
+                        f"Kiosk clock-in on a scheduled OFF day at {location.name}",
+                        attendance=attendance, location=location,
+                        latitude=latitude, longitude=longitude, distance=distance,
+                        source='kiosk',
+                    )
+                else:
+                    scheduled_in, _ = api._get_scheduled_times(employee, today)
+                    api._check_and_create_penalty(employee, attendance, 'late_in', scheduled_in, now)
 
                 return {
                     'success': True,
@@ -135,8 +147,9 @@ class FusionClockKiosk(http.Controller):
                 })
                 api._apply_break_deduction(attendance, employee)
 
-                _, scheduled_out = api._get_scheduled_times(employee, today)
-                api._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
+                if not is_scheduled_off:
+                    _, scheduled_out = api._get_scheduled_times(employee, today)
+                    api._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
 
                 api._log_activity(
                     employee, 'clock_out',

fusion_clock/controllers/clock_nfc_kiosk.py

@@ -8,6 +8,7 @@ import time
 import threading
 from odoo import fields, http
 from odoo.http import request
+from odoo.addons.fusion_clock.models.tz_utils import get_local_today
 
 _logger = logging.getLogger(__name__)
 _UID_HEX_PATTERN = re.compile(r'^[0-9A-F]+$')
@@ -183,7 +184,9 @@ class FusionClockNfcKiosk(http.Controller):
 
         is_checked_in = employee.attendance_state == 'checked_in'
         now = fields.Datetime.now()
-        today = now.date()
+        today = get_local_today(request.env, employee)
+        day_plan = employee._get_fclk_day_plan(today)
+        is_scheduled_off = day_plan.get('source') == 'schedule' and day_plan.get('is_off')
 
         geo_info = {
             'latitude': 0,
@@ -208,8 +211,17 @@ class FusionClockNfcKiosk(http.Controller):
                 latitude=0, longitude=0, distance=0,
                 source='nfc_kiosk',
             )
-            scheduled_in, _ = api._get_scheduled_times(employee, today)
-            api._check_and_create_penalty(employee, attendance, 'late_in', scheduled_in, now)
+            if is_scheduled_off:
+                api._log_activity(
+                    employee, 'unscheduled_shift',
+                    f"NFC kiosk clock-in on a scheduled OFF day at {location.name}",
+                    attendance=attendance, location=location,
+                    latitude=0, longitude=0, distance=0,
+                    source='nfc_kiosk',
+                )
+            else:
+                scheduled_in, _ = api._get_scheduled_times(employee, today)
+                api._check_and_create_penalty(employee, attendance, 'late_in', scheduled_in, now)
             return {
                 'success': True,
                 'action': 'clock_in',
@@ -224,8 +236,9 @@ class FusionClockNfcKiosk(http.Controller):
                 'x_fclk_check_out_photo': photo_bytes if photo_bytes else False,
             })
             api._apply_break_deduction(attendance, employee)
-            _, scheduled_out = api._get_scheduled_times(employee, today)
-            api._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
+            if not is_scheduled_off:
+                _, scheduled_out = api._get_scheduled_times(employee, today)
+                api._check_and_create_penalty(employee, attendance, 'early_out', scheduled_out, now)
             api._log_activity(
                 employee, 'clock_out',
                 f"NFC kiosk clock-out from {location.name}. Net: {attendance.x_fclk_net_hours:.1f}h",

fusion_clock/controllers/portal_clock.py

@@ -100,7 +100,9 @@ class FusionClockPortal(CustomerPortal):
             ], limit=1)
 
         # Today stats
-        today_start, _ = get_local_day_boundaries(request.env, get_local_today(request.env, employee), employee)
+        today = get_local_today(request.env, employee)
+        today_schedule = employee._get_fclk_day_plan(today)
+        today_start, _ = get_local_day_boundaries(request.env, today, employee)
         today_atts = request.env['hr.attendance'].sudo().search([
             ('employee_id', '=', employee.id),
             ('check_in', '>=', today_start),
@@ -109,7 +111,6 @@ class FusionClockPortal(CustomerPortal):
         today_hours = sum(a.x_fclk_net_hours or 0 for a in today_atts)
 
         # Week stats
-        today = get_local_today(request.env, employee)
         week_start = today - timedelta(days=today.weekday())
         week_start_dt, _ = get_local_day_boundaries(request.env, week_start, employee)
         week_atts = request.env['hr.attendance'].sudo().search([
@@ -151,6 +152,7 @@ class FusionClockPortal(CustomerPortal):
             'current_attendance': current_attendance,
             'today_hours': round(today_hours, 1),
             'week_hours': round(week_hours, 1),
+            'today_schedule': today_schedule,
             'recent_attendances': recent,
             'google_maps_key': google_maps_key,
             'enable_sounds': enable_sounds,

fusion_clock/controllers/shift_planner.py

@@ -0,0 +1,269 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1 (Odoo Proprietary License v1.0)
+
+import base64
+import io
+from collections import defaultdict
+from datetime import timedelta
+
+from odoo import fields, http, _
+from odoo.exceptions import ValidationError
+from odoo.http import request
+
+
+class FusionClockShiftPlanner(http.Controller):
+    """Backend JSON-RPC API for the Excel-style weekly shift planner."""
+
+    def _check_manager(self):
+        return request.env.user.has_group('fusion_clock.group_fusion_clock_manager')
+
+    def _week_start(self, week_start=None):
+        date_obj = fields.Date.to_date(week_start) if week_start else fields.Date.today()
+        return date_obj - timedelta(days=date_obj.weekday())
+
+    def _manager_employees(self):
+        return request.env['hr.employee'].sudo().search([
+            ('x_fclk_enable_clock', '=', True),
+            ('company_id', 'in', request.env.user.company_ids.ids),
+        ], order='department_id, name')
+
+    def _load_week_data(self, week_start=None):
+        start = self._week_start(week_start)
+        days = [start + timedelta(days=i) for i in range(7)]
+        employees = self._manager_employees()
+        Schedule = request.env['fusion.clock.schedule'].sudo()
+
+        schedules = Schedule.search([
+            ('employee_id', 'in', employees.ids),
+            ('schedule_date', '>=', start),
+            ('schedule_date', '<=', days[-1]),
+        ])
+        schedule_map = {
+            (schedule.employee_id.id, schedule.schedule_date): schedule
+            for schedule in schedules
+        }
+
+        grouped = defaultdict(list)
+        for employee in employees:
+            grouped[employee.department_id.id or 0].append(employee)
+
+        departments = []
+        employee_rows = []
+        for department_id, department_employees in grouped.items():
+            department = department_employees[0].department_id
+            departments.append({
+                'id': department_id,
+                'name': department.name if department else _('No Department'),
+                'employee_ids': [emp.id for emp in department_employees],
+            })
+            for employee in department_employees:
+                cells = {}
+                for day in days:
+                    cells[str(day)] = Schedule.fclk_cell_payload(
+                        employee,
+                        day,
+                        schedule_map.get((employee.id, day)),
+                    )
+                employee_rows.append({
+                    'id': employee.id,
+                    'name': employee.name,
+                    'department_id': department_id,
+                    'department_name': department.name if department else _('No Department'),
+                    'job_title': employee.job_title or '',
+                    'cells': cells,
+                })
+
+        shifts = request.env['fusion.clock.shift'].sudo().search([
+            ('active', '=', True),
+            ('company_id', 'in', request.env.user.company_ids.ids),
+        ], order='sequence, name')
+
+        return {
+            'week_start': str(start),
+            'week_end': str(days[-1]),
+            'days': [{
+                'date': str(day),
+                'weekday': day.strftime('%a').upper(),
+                'label': day.strftime('%d-%b'),
+            } for day in days],
+            'departments': departments,
+            'employees': employee_rows,
+            'shifts': [{
+                'id': shift.id,
+                'name': shift.name,
+                'start_time': shift.start_time,
+                'end_time': shift.end_time,
+                'break_minutes': shift.break_minutes,
+                'hours': shift.scheduled_hours,
+                'hours_display': Schedule.fclk_hours_display(shift.scheduled_hours),
+                'label': '%s - %s' % (
+                    Schedule.fclk_float_to_display(shift.start_time),
+                    Schedule.fclk_float_to_display(shift.end_time),
+                ),
+                'option_label': '%s (%s - %s)' % (
+                    shift.name,
+                    Schedule.fclk_float_to_display(shift.start_time),
+                    Schedule.fclk_float_to_display(shift.end_time),
+                ),
+            } for shift in shifts],
+        }
+
+    @http.route('/fusion_clock/shift_planner/load', type='jsonrpc', auth='user', methods=['POST'])
+    def load(self, week_start=None, **kw):
+        if not self._check_manager():
+            return {'error': 'Access denied.'}
+        return self._load_week_data(week_start)
+
+    @http.route('/fusion_clock/shift_planner/save', type='jsonrpc', auth='user', methods=['POST'])
+    def save(self, week_start=None, changes=None, **kw):
+        if not self._check_manager():
+            return {'error': 'Access denied.'}
+
+        employees = self._manager_employees()
+        employee_map = {employee.id: employee for employee in employees}
+        Schedule = request.env['fusion.clock.schedule'].sudo()
+        errors = []
+        saved = 0
+
+        for change in changes or []:
+            employee_id = int(change.get('employee_id') or 0)
+            employee = employee_map.get(employee_id)
+            date_str = change.get('date')
+            if not employee:
+                errors.append({
+                    'employee_id': employee_id,
+                    'date': date_str,
+                    'message': 'Employee not found or not allowed.',
+                })
+                continue
+            try:
+                Schedule.fclk_apply_planner_cell(employee, date_str, change, request.env.user)
+                saved += 1
+            except ValidationError as exc:
+                errors.append({
+                    'employee_id': employee_id,
+                    'date': date_str,
+                    'message': str(exc.args[0] if exc.args else exc),
+                })
+
+        if errors:
+            return {'success': False, 'saved': saved, 'errors': errors}
+        return {
+            'success': True,
+            'saved': saved,
+            'data': self._load_week_data(week_start),
+        }
+
+    @http.route('/fusion_clock/shift_planner/copy_previous_week', type='jsonrpc', auth='user', methods=['POST'])
+    def copy_previous_week(self, week_start=None, **kw):
+        if not self._check_manager():
+            return {'error': 'Access denied.'}
+
+        start = self._week_start(week_start)
+        prev_start = start - timedelta(days=7)
+        employees = self._manager_employees()
+        Schedule = request.env['fusion.clock.schedule'].sudo()
+        prev_schedules = Schedule.search([
+            ('employee_id', 'in', employees.ids),
+            ('schedule_date', '>=', prev_start),
+            ('schedule_date', '<=', prev_start + timedelta(days=6)),
+        ])
+        prev_map = {
+            (schedule.employee_id.id, schedule.schedule_date): schedule
+            for schedule in prev_schedules
+        }
+
+        before_count = request.env['fusion.clock.schedule.audit'].sudo().search_count([])
+        for employee in employees:
+            for offset in range(7):
+                source_date = prev_start + timedelta(days=offset)
+                target_date = start + timedelta(days=offset)
+                source = prev_map.get((employee.id, source_date))
+                if not source:
+                    payload = {'input': ''}
+                elif source.is_off:
+                    payload = {'input': 'OFF'}
+                elif source.shift_id:
+                    payload = {'shift_id': source.shift_id.id, 'input': source.fclk_display_value()}
+                else:
+                    payload = {
+                        'input': source.fclk_display_value(),
+                        'start_time': source.start_time,
+                        'end_time': source.end_time,
+                        'break_minutes': source.break_minutes,
+                    }
+                Schedule.fclk_apply_planner_cell(employee, target_date, payload, request.env.user)
+
+        after_count = request.env['fusion.clock.schedule.audit'].sudo().search_count([])
+        return {
+            'success': True,
+            'changed': after_count - before_count,
+            'data': self._load_week_data(start),
+        }
+
+    @http.route('/fusion_clock/shift_planner/export_xlsx', type='jsonrpc', auth='user', methods=['POST'])
+    def export_xlsx(self, week_start=None, **kw):
+        if not self._check_manager():
+            return {'error': 'Access denied.'}
+
+        data = self._load_week_data(week_start)
+        output = io.BytesIO()
+        import xlsxwriter
+
+        workbook = xlsxwriter.Workbook(output, {'in_memory': True})
+        sheet = workbook.add_worksheet('Shift Planner')
+
+        fmt_day = workbook.add_format({'bold': True, 'align': 'center', 'bg_color': '#b7dff5', 'border': 1})
+        fmt_sub = workbook.add_format({'bold': True, 'align': 'center', 'bg_color': '#d8e9bd', 'border': 1})
+        fmt_employee = workbook.add_format({'bold': True, 'border': 1})
+        fmt_shift = workbook.add_format({'border': 1})
+        fmt_hours = workbook.add_format({'border': 1, 'align': 'center', 'bg_color': '#f5d39b'})
+        fmt_department = workbook.add_format({'bold': True, 'bg_color': '#eeeeee', 'border': 1})
+
+        sheet.set_column(0, 0, 22)
+        for col in range(1, 15, 2):
+            sheet.set_column(col, col, 24)
+            sheet.set_column(col + 1, col + 1, 9)
+
+        sheet.write(0, 0, 'EMPLOYEE', fmt_day)
+        col = 1
+        for day in data['days']:
+            sheet.merge_range(0, col, 0, col + 1, day['weekday'], fmt_day)
+            sheet.merge_range(1, col, 1, col + 1, day['label'], fmt_day)
+            sheet.write(2, col, 'Shift', fmt_sub)
+            sheet.write(2, col + 1, 'Hours', fmt_sub)
+            col += 2
+        sheet.write(2, 0, 'EMPLOYEE', fmt_sub)
+
+        row = 3
+        employee_by_id = {emp['id']: emp for emp in data['employees']}
+        for department in data['departments']:
+            sheet.merge_range(row, 0, row, 14, department['name'], fmt_department)
+            row += 1
+            for employee_id in department['employee_ids']:
+                employee = employee_by_id[employee_id]
+                sheet.write(row, 0, employee['name'], fmt_employee)
+                col = 1
+                for day in data['days']:
+                    cell = employee['cells'][day['date']]
+                    sheet.write(row, col, cell.get('label') or '', fmt_shift)
+                    sheet.write(row, col + 1, cell.get('hours_display') or '0:00', fmt_hours)
+                    col += 2
+                row += 1
+
+        workbook.close()
+        output.seek(0)
+        filename = 'shift_planner_%s.xlsx' % data['week_start']
+        attachment = request.env['ir.attachment'].sudo().create({
+            'name': filename,
+            'type': 'binary',
+            'datas': base64.b64encode(output.read()),
+            'mimetype': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        })
+        return {
+            'success': True,
+            'attachment_id': attachment.id,
+            'filename': filename,
+            'url': '/web/content/%s?download=true' % attachment.id,
+        }

fusion_clock/models/__init__.py

@@ -9,5 +9,6 @@ from . import res_config_settings
 from . import clock_activity_log
 from . import clock_leave_request
 from . import clock_shift
+from . import clock_schedule
 from . import clock_correction
 from . import res_company

fusion_clock/models/clock_activity_log.py

@@ -34,6 +34,7 @@ class FusionClockActivityLog(models.Model):
             ('correction_request', 'Correction Request'),
             ('ip_fallback', 'IP Fallback Used'),
             ('streak_milestone', 'Streak Milestone'),
+            ('unscheduled_shift', 'Unscheduled Shift'),
             ('card_enrollment', 'Card Enrollment'),
             ('unknown_card_tap', 'Unknown Card Tap'),
         ],
@@ -108,6 +109,7 @@ class FusionClockActivityLog(models.Model):
         'correction_request': 'Correction Request',
         'ip_fallback': 'IP Fallback Used',
         'streak_milestone': 'Streak Milestone',
+        'unscheduled_shift': 'Unscheduled Shift',
     }
 
     @api.depends('latitude', 'longitude')

fusion_clock/models/clock_schedule.py

@@ -0,0 +1,414 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1 (Odoo Proprietary License v1.0)
+
+import re
+
+from odoo import api, fields, models, _
+from odoo.exceptions import ValidationError
+
+
+class FusionClockSchedule(models.Model):
+    _name = 'fusion.clock.schedule'
+    _description = 'Clock Shift Schedule Entry'
+    _order = 'schedule_date, employee_id'
+    _rec_name = 'display_name'
+
+    employee_id = fields.Many2one(
+        'hr.employee',
+        string='Employee',
+        required=True,
+        index=True,
+        ondelete='cascade',
+    )
+    schedule_date = fields.Date(
+        string='Date',
+        required=True,
+        index=True,
+    )
+    shift_id = fields.Many2one(
+        'fusion.clock.shift',
+        string='Shift Template',
+        ondelete='set null',
+    )
+    is_off = fields.Boolean(
+        string='Off',
+        default=False,
+        index=True,
+    )
+    start_time = fields.Float(
+        string='Start Time',
+        default=9.0,
+    )
+    end_time = fields.Float(
+        string='End Time',
+        default=17.0,
+    )
+    break_minutes = fields.Float(
+        string='Break (min)',
+        default=30.0,
+    )
+    planned_hours = fields.Float(
+        string='Hours',
+        compute='_compute_planned_hours',
+        store=True,
+    )
+    note = fields.Char(string='Note')
+    company_id = fields.Many2one(
+        'res.company',
+        string='Company',
+        related='employee_id.company_id',
+        store=True,
+        readonly=True,
+    )
+    department_id = fields.Many2one(
+        'hr.department',
+        string='Department',
+        related='employee_id.department_id',
+        store=True,
+        readonly=True,
+    )
+    display_name = fields.Char(
+        compute='_compute_display_name',
+        store=True,
+    )
+
+    _employee_date_unique = models.Constraint(
+        'UNIQUE(employee_id, schedule_date)',
+        'Only one shift schedule is allowed per employee per day.',
+    )
+
+    @api.depends('is_off', 'start_time', 'end_time', 'break_minutes')
+    def _compute_planned_hours(self):
+        for rec in self:
+            if rec.is_off:
+                rec.planned_hours = 0.0
+                continue
+            raw_hours = (rec.end_time or 0.0) - (rec.start_time or 0.0)
+            rec.planned_hours = round(max(raw_hours - ((rec.break_minutes or 0.0) / 60.0), 0.0), 2)
+
+    @api.depends('employee_id', 'schedule_date', 'is_off', 'start_time', 'end_time')
+    def _compute_display_name(self):
+        for rec in self:
+            emp = rec.employee_id.name or ''
+            date_str = str(rec.schedule_date) if rec.schedule_date else ''
+            rec.display_name = f"{emp} - {date_str} - {rec.fclk_display_value()}"
+
+    @api.constrains('is_off', 'start_time', 'end_time', 'break_minutes')
+    def _check_schedule_times(self):
+        for rec in self:
+            if rec.break_minutes < 0:
+                raise ValidationError(_("Break minutes cannot be negative."))
+            if rec.is_off:
+                continue
+            if rec.start_time < 0 or rec.start_time >= 24:
+                raise ValidationError(_("Start time must be between 00:00 and 23:59."))
+            if rec.end_time <= 0 or rec.end_time > 24:
+                raise ValidationError(_("End time must be between 00:01 and 24:00."))
+            if rec.end_time <= rec.start_time:
+                raise ValidationError(_("End time must be after start time. Overnight shifts are not supported yet."))
+            shift_minutes = (rec.end_time - rec.start_time) * 60.0
+            if rec.break_minutes >= shift_minutes:
+                raise ValidationError(_("Break duration must be shorter than the scheduled shift."))
+
+    @api.onchange('shift_id')
+    def _onchange_shift_id(self):
+        for rec in self:
+            if rec.shift_id:
+                rec.is_off = False
+                rec.start_time = rec.shift_id.start_time
+                rec.end_time = rec.shift_id.end_time
+                rec.break_minutes = rec.shift_id.break_minutes
+
+    @api.model
+    def fclk_float_to_display(self, value):
+        value = float(value or 0.0)
+        hour = int(value)
+        minute = int(round((value - hour) * 60))
+        if minute == 60:
+            hour += 1
+            minute = 0
+        suffix = 'am' if hour < 12 or hour == 24 else 'pm'
+        display_hour = hour % 12
+        if display_hour == 0:
+            display_hour = 12
+        return f"{display_hour}:{minute:02d} {suffix}"
+
+    def fclk_display_value(self):
+        self.ensure_one()
+        if self.is_off:
+            return 'OFF'
+        return (
+            f"{self.env['fusion.clock.schedule'].fclk_float_to_display(self.start_time)} - "
+            f"{self.env['fusion.clock.schedule'].fclk_float_to_display(self.end_time)}"
+        )
+
+    @api.model
+    def fclk_hours_display(self, hours):
+        hours = float(hours or 0.0)
+        whole = int(hours)
+        minutes = int(round((hours - whole) * 60))
+        if minutes == 60:
+            whole += 1
+            minutes = 0
+        return f"{whole}:{minutes:02d}"
+
+    @api.model
+    def _fclk_parse_time_part(self, raw):
+        text = (raw or '').strip().lower().replace('.', '')
+        match = re.match(r'^(\d{1,2})(?::(\d{1,2}))?\s*(am|pm)?$', text)
+        if not match:
+            raise ValidationError(_("Could not understand time '%s'.") % raw)
+        hour = int(match.group(1))
+        minute = int(match.group(2) or 0)
+        meridiem = match.group(3)
+        if minute < 0 or minute > 59:
+            raise ValidationError(_("Minutes must be between 00 and 59."))
+        if meridiem:
+            if hour < 1 or hour > 12:
+                raise ValidationError(_("12-hour times must use hours from 1 to 12."))
+            if meridiem == 'am':
+                hour = 0 if hour == 12 else hour
+            else:
+                hour = 12 if hour == 12 else hour + 12
+        elif hour > 24:
+            raise ValidationError(_("Hours must be between 0 and 24."))
+        return hour + (minute / 60.0)
+
+    @api.model
+    def fclk_parse_planner_input(self, input_value, default_break_minutes=30.0):
+        text = (input_value or '').strip()
+        if not text:
+            return {'clear': True}
+        if text.upper() == 'OFF':
+            return {
+                'clear': False,
+                'is_off': True,
+                'shift_id': False,
+                'start_time': 0.0,
+                'end_time': 0.0,
+                'break_minutes': 0.0,
+            }
+
+        normalized = (
+            text.replace('–', '-')
+            .replace('—', '-')
+            .replace(' to ', '-')
+            .replace(' TO ', '-')
+        )
+        parts = [p.strip() for p in normalized.split('-', 1)]
+        if len(parts) != 2 or not parts[0] or not parts[1]:
+            raise ValidationError(_("Enter a shift as '9-5', '9:00-5:30', '9:00 am - 5:30 pm', or OFF."))
+        start = self._fclk_parse_time_part(parts[0])
+        end = self._fclk_parse_time_part(parts[1])
+        if end <= start and end + 12 <= 24:
+            end += 12
+        if end <= start:
+            raise ValidationError(_("End time must be after start time. Overnight shifts are not supported yet."))
+        return {
+            'clear': False,
+            'is_off': False,
+            'shift_id': False,
+            'start_time': start,
+            'end_time': end,
+            'break_minutes': float(default_break_minutes or 0.0),
+        }
+
+    @api.model
+    def fclk_values_from_planner_payload(self, payload, employee):
+        payload = payload or {}
+        if 'start_time' in payload and 'end_time' in payload and not payload.get('shift_id'):
+            if payload.get('is_off'):
+                return {
+                    'clear': False,
+                    'is_off': True,
+                    'shift_id': False,
+                    'start_time': 0.0,
+                    'end_time': 0.0,
+                    'break_minutes': 0.0,
+                }
+            return {
+                'clear': False,
+                'is_off': False,
+                'shift_id': False,
+                'start_time': float(payload.get('start_time') or 0.0),
+                'end_time': float(payload.get('end_time') or 0.0),
+                'break_minutes': float(payload.get('break_minutes') or 0.0),
+            }
+        shift_id = int(payload.get('shift_id') or 0)
+        if shift_id:
+            shift = self.env['fusion.clock.shift'].sudo().browse(shift_id)
+            if not shift.exists():
+                raise ValidationError(_("Selected shift template no longer exists."))
+            return {
+                'clear': False,
+                'shift_id': shift.id,
+                'is_off': False,
+                'start_time': shift.start_time,
+                'end_time': shift.end_time,
+                'break_minutes': shift.break_minutes,
+            }
+
+        default_break = employee._get_fclk_break_minutes() if employee else 30.0
+        return self.fclk_parse_planner_input(payload.get('input', ''), default_break)
+
+    @api.model
+    def fclk_snapshot(self, schedule):
+        if not schedule:
+            return ''
+        return schedule.fclk_display_value()
+
+    @api.model
+    def fclk_apply_planner_cell(self, employee, schedule_date, payload, user=None):
+        self = self.sudo()
+        employee = employee.sudo()
+        date_obj = fields.Date.to_date(schedule_date)
+        if not employee.exists() or not date_obj:
+            raise ValidationError(_("Invalid employee or schedule date."))
+
+        existing = self.search([
+            ('employee_id', '=', employee.id),
+            ('schedule_date', '=', date_obj),
+        ], limit=1)
+        old_value = self.fclk_snapshot(existing)
+        parsed = self.fclk_values_from_planner_payload(payload, employee)
+
+        if parsed.get('clear'):
+            if existing:
+                existing.unlink()
+            new_schedule = self.browse()
+            new_value = ''
+        else:
+            vals = {
+                'employee_id': employee.id,
+                'schedule_date': date_obj,
+                'shift_id': parsed.get('shift_id') or False,
+                'is_off': bool(parsed.get('is_off')),
+                'start_time': parsed.get('start_time') or 0.0,
+                'end_time': parsed.get('end_time') or 0.0,
+                'break_minutes': parsed.get('break_minutes') or 0.0,
+                'note': payload.get('note') or False,
+            }
+            if existing:
+                existing.write(vals)
+                new_schedule = existing
+            else:
+                new_schedule = self.create(vals)
+            new_value = new_schedule.fclk_display_value()
+
+        if old_value != new_value:
+            self.env['fusion.clock.schedule.audit'].sudo().create({
+                'schedule_id': new_schedule.id if new_schedule else False,
+                'employee_id': employee.id,
+                'schedule_date': date_obj,
+                'old_value': old_value,
+                'new_value': new_value,
+                'changed_by_id': (user or self.env.user).id,
+                'changed_at': fields.Datetime.now(),
+                'company_id': employee.company_id.id,
+                'department_id': employee.department_id.id,
+            })
+        return new_schedule
+
+    @api.model
+    def fclk_cell_payload(self, employee, date_obj, schedule=None):
+        schedule = schedule or self.search([
+            ('employee_id', '=', employee.id),
+            ('schedule_date', '=', date_obj),
+        ], limit=1)
+        Schedule = self.env['fusion.clock.schedule']
+        if schedule:
+            return {
+                'schedule_id': schedule.id,
+                'source': 'schedule',
+                'input': schedule.fclk_display_value(),
+                'label': schedule.fclk_display_value(),
+                'is_off': schedule.is_off,
+                'shift_id': schedule.shift_id.id or False,
+                'start_time': schedule.start_time,
+                'end_time': schedule.end_time,
+                'break_minutes': schedule.break_minutes,
+                'hours': schedule.planned_hours,
+                'hours_display': Schedule.fclk_hours_display(schedule.planned_hours),
+                'note': schedule.note or '',
+            }
+
+        plan = employee._get_fclk_day_plan(date_obj)
+        return {
+            'schedule_id': False,
+            'source': plan.get('source') or 'fallback',
+            'input': plan.get('label') or '',
+            'label': plan.get('label') or '',
+            'is_off': plan.get('is_off', False),
+            'shift_id': False,
+            'start_time': plan.get('start_time') or 0.0,
+            'end_time': plan.get('end_time') or 0.0,
+            'break_minutes': plan.get('break_minutes') or 0.0,
+            'hours': plan.get('hours') or 0.0,
+            'hours_display': Schedule.fclk_hours_display(plan.get('hours') or 0.0),
+            'note': '',
+        }
+
+
+class FusionClockScheduleAudit(models.Model):
+    _name = 'fusion.clock.schedule.audit'
+    _description = 'Clock Schedule Change Audit'
+    _order = 'changed_at desc, id desc'
+    _rec_name = 'display_name'
+
+    schedule_id = fields.Many2one(
+        'fusion.clock.schedule',
+        string='Schedule',
+        ondelete='set null',
+        index=True,
+    )
+    employee_id = fields.Many2one(
+        'hr.employee',
+        string='Employee',
+        required=True,
+        index=True,
+        ondelete='cascade',
+    )
+    schedule_date = fields.Date(
+        string='Schedule Date',
+        required=True,
+        index=True,
+    )
+    old_value = fields.Char(string='Old Value')
+    new_value = fields.Char(string='New Value')
+    changed_by_id = fields.Many2one(
+        'res.users',
+        string='Changed By',
+        required=True,
+        ondelete='restrict',
+    )
+    changed_at = fields.Datetime(
+        string='Changed At',
+        default=fields.Datetime.now,
+        required=True,
+        index=True,
+    )
+    company_id = fields.Many2one(
+        'res.company',
+        string='Company',
+        index=True,
+    )
+    department_id = fields.Many2one(
+        'hr.department',
+        string='Department',
+        index=True,
+    )
+    display_name = fields.Char(
+        compute='_compute_display_name',
+        store=True,
+    )
+
+    @api.depends('employee_id', 'schedule_date', 'old_value', 'new_value')
+    def _compute_display_name(self):
+        for rec in self:
+            rec.display_name = "%s - %s: %s -> %s" % (
+                rec.employee_id.name or '',
+                rec.schedule_date or '',
+                rec.old_value or 'blank',
+                rec.new_value or 'blank',
+            )

fusion_clock/models/hr_attendance.py

@@ -227,7 +227,18 @@ class HrAttendance(models.Model):
                 continue
 
             employee = att.employee_id
-            scheduled_hours = employee._get_fclk_scheduled_hours() if employee else daily_threshold
+            scheduled_hours = daily_threshold
+            if employee:
+                local_date = get_local_today(self.env, employee)
+                if att.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(att.check_in).astimezone(pytz.timezone(tz_name)).date()
+                scheduled_hours = employee._get_fclk_scheduled_hours(local_date)
             net = att.x_fclk_net_hours or 0.0
 
             if net > scheduled_hours:
@@ -264,11 +275,14 @@ class HrAttendance(models.Model):
             employee = att.employee_id
             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()
-            _, scheduled_out = employee._get_fclk_scheduled_times(check_in_date)
-
-            deadline = scheduled_out + timedelta(minutes=grace_min)
             max_deadline = check_in + timedelta(hours=max_shift)
-            effective_deadline = min(deadline, max_deadline)
+            day_plan = employee._get_fclk_day_plan(check_in_date)
+            if day_plan.get('source') == 'schedule' and day_plan.get('is_off'):
+                effective_deadline = max_deadline
+            else:
+                _, scheduled_out = employee._get_fclk_scheduled_times(check_in_date)
+                deadline = scheduled_out + timedelta(minutes=grace_min)
+                effective_deadline = min(deadline, max_deadline)
 
             if now > effective_deadline:
                 clock_out_time = min(effective_deadline, now)
@@ -283,7 +297,7 @@ class HrAttendance(models.Model):
                     # Apply break deduction
                     threshold = float(ICP.get_param('fusion_clock.break_threshold_hours', '4.0'))
                     if (att.worked_hours or 0) >= threshold:
-                        break_min = employee._get_fclk_break_minutes()
+                        break_min = employee._get_fclk_break_minutes(check_in_date)
                         att.sudo().write({'x_fclk_break_minutes': break_min})
 
                     att.sudo().message_post(
@@ -346,6 +360,9 @@ class HrAttendance(models.Model):
 
             if yesterday.weekday() >= 5:
                 continue
+            day_plan = emp._get_fclk_day_plan(yesterday)
+            if day_plan.get('source') == 'schedule' and day_plan.get('is_off'):
+                continue
 
             day_start, day_end = get_local_day_boundaries(self.env, yesterday, emp)
 
@@ -423,6 +440,9 @@ class HrAttendance(models.Model):
 
             if today.weekday() >= 5:
                 continue
+            day_plan = emp._get_fclk_day_plan(today)
+            if day_plan.get('source') == 'schedule' and day_plan.get('is_off'):
+                continue
 
             if emp.x_fclk_last_reminder_date == today:
                 continue

fusion_clock/models/hr_employee.py

@@ -120,11 +120,82 @@ class HrEmployee(models.Model):
         help="Tracks the last date a reminder was sent to avoid duplicates.",
     )
 
-    def _get_fclk_break_minutes(self):
-        """Return effective break minutes for this employee.
-        Priority: employee override > shift > global setting.
+    def _get_fclk_schedule_for_date(self, date):
+        """Return this employee's dated Fusion Clock schedule for a local date."""
+        self.ensure_one()
+        date_obj = fields.Date.to_date(date)
+        if not date_obj:
+            return self.env['fusion.clock.schedule']
+        return self.env['fusion.clock.schedule'].sudo().search([
+            ('employee_id', '=', self.id),
+            ('schedule_date', '=', date_obj),
+        ], limit=1)
+
+    def _get_fclk_day_plan(self, date):
+        """Return the effective plan for a local date.
+
+        Dated schedules are the source of truth.  If none exists, the legacy
+        employee shift/global settings remain the fallback.
         """
         self.ensure_one()
+        Schedule = self.env['fusion.clock.schedule'].sudo()
+        schedule = self._get_fclk_schedule_for_date(date)
+        if schedule:
+            return {
+                'source': 'schedule',
+                'schedule_id': schedule.id,
+                'is_off': schedule.is_off,
+                'start_time': schedule.start_time,
+                'end_time': schedule.end_time,
+                'break_minutes': schedule.break_minutes,
+                'hours': schedule.planned_hours,
+                'label': schedule.fclk_display_value(),
+            }
+        if self.x_fclk_shift_id:
+            shift = self.x_fclk_shift_id
+            hours = max((shift.end_time - shift.start_time) - (shift.break_minutes / 60.0), 0.0)
+            return {
+                'source': 'fallback',
+                'schedule_id': False,
+                'is_off': False,
+                'start_time': shift.start_time,
+                'end_time': shift.end_time,
+                'break_minutes': shift.break_minutes,
+                'hours': hours,
+                'label': '%s - %s' % (
+                    Schedule.fclk_float_to_display(shift.start_time),
+                    Schedule.fclk_float_to_display(shift.end_time),
+                ),
+            }
+
+        ICP = self.env['ir.config_parameter'].sudo()
+        start_time = float(ICP.get_param('fusion_clock.default_clock_in_time', '9.0'))
+        end_time = float(ICP.get_param('fusion_clock.default_clock_out_time', '17.0'))
+        break_minutes = float(ICP.get_param('fusion_clock.default_break_minutes', '30'))
+        hours = max((end_time - start_time) - (break_minutes / 60.0), 0.0)
+        return {
+            'source': 'fallback',
+            'schedule_id': False,
+            'is_off': False,
+            'start_time': start_time,
+            'end_time': end_time,
+            'break_minutes': break_minutes,
+            'hours': hours,
+            'label': '%s - %s' % (
+                Schedule.fclk_float_to_display(start_time),
+                Schedule.fclk_float_to_display(end_time),
+            ),
+        }
+
+    def _get_fclk_break_minutes(self, date=None):
+        """Return effective break minutes for this employee.
+        Priority: dated schedule > employee override > shift > global setting.
+        """
+        self.ensure_one()
+        if date:
+            plan = self._get_fclk_day_plan(date)
+            if plan.get('source') == 'schedule' and not plan.get('is_off'):
+                return plan.get('break_minutes') or 0.0
         if self.x_fclk_break_minutes > 0:
             return self.x_fclk_break_minutes
         if self.x_fclk_shift_id and self.x_fclk_shift_id.break_minutes > 0:
@@ -138,7 +209,7 @@ class HrEmployee(models.Model):
     def _get_fclk_scheduled_times(self, date):
         """Return (scheduled_in_dt, scheduled_out_dt) for a given date.
 
-        Uses employee shift if assigned, otherwise global settings.
+        Uses dated schedule first, employee shift second, then global settings.
         The configured hours are interpreted in the employee's local
         timezone and converted to naive-UTC datetimes so they can be
         compared with Odoo's UTC-based ``fields.Datetime.now()``.
@@ -146,13 +217,9 @@ class HrEmployee(models.Model):
         import pytz
 
         self.ensure_one()
-        if self.x_fclk_shift_id:
-            in_hour = self.x_fclk_shift_id.start_time
-            out_hour = self.x_fclk_shift_id.end_time
-        else:
-            ICP = self.env['ir.config_parameter'].sudo()
-            in_hour = float(ICP.get_param('fusion_clock.default_clock_in_time', '9.0'))
-            out_hour = float(ICP.get_param('fusion_clock.default_clock_out_time', '17.0'))
+        plan = self._get_fclk_day_plan(date)
+        in_hour = plan.get('start_time') or 0.0
+        out_hour = plan.get('end_time') or 0.0
 
         in_h = int(in_hour)
         in_m = int((in_hour - in_h) * 60)
@@ -179,16 +246,13 @@ class HrEmployee(models.Model):
         scheduled_out = local_out.astimezone(utc).replace(tzinfo=None)
         return scheduled_in, scheduled_out
 
-    def _get_fclk_scheduled_hours(self):
+    def _get_fclk_scheduled_hours(self, date=None):
         """Return the expected work hours for this employee's shift."""
         self.ensure_one()
-        if self.x_fclk_shift_id:
-            return self.x_fclk_shift_id.scheduled_hours
-        ICP = self.env['ir.config_parameter'].sudo()
-        in_hour = float(ICP.get_param('fusion_clock.default_clock_in_time', '9.0'))
-        out_hour = float(ICP.get_param('fusion_clock.default_clock_out_time', '17.0'))
-        break_hrs = self._get_fclk_break_minutes() / 60.0
-        return max((out_hour - in_hour) - break_hrs, 0.0)
+        plan = self._get_fclk_day_plan(date or get_local_today(self.env, self))
+        if plan.get('is_off'):
+            return 0.0
+        return plan.get('hours') or 0.0
 
     def _compute_absence_counts(self):
         ActivityLog = self.env['fusion.clock.activity.log'].sudo()

fusion_clock/security/ir.model.access.csv

@@ -11,6 +11,9 @@ access_fusion_clock_leave_request_user,fusion.clock.leave.request.user,model_fus
 access_fusion_clock_leave_request_manager,fusion.clock.leave.request.manager,model_fusion_clock_leave_request,group_fusion_clock_manager,1,1,1,1
 access_fusion_clock_shift_user,fusion.clock.shift.user,model_fusion_clock_shift,group_fusion_clock_user,1,0,0,0
 access_fusion_clock_shift_manager,fusion.clock.shift.manager,model_fusion_clock_shift,group_fusion_clock_manager,1,1,1,1
+access_fusion_clock_schedule_user,fusion.clock.schedule.user,model_fusion_clock_schedule,group_fusion_clock_user,1,0,0,0
+access_fusion_clock_schedule_manager,fusion.clock.schedule.manager,model_fusion_clock_schedule,group_fusion_clock_manager,1,1,1,1
+access_fusion_clock_schedule_audit_manager,fusion.clock.schedule.audit.manager,model_fusion_clock_schedule_audit,group_fusion_clock_manager,1,0,0,0
 access_fusion_clock_correction_user,fusion.clock.correction.user,model_fusion_clock_correction,group_fusion_clock_user,1,0,0,0
 access_fusion_clock_correction_manager,fusion.clock.correction.manager,model_fusion_clock_correction,group_fusion_clock_manager,1,1,1,1
 access_fusion_clock_location_portal,fusion.clock.location.portal,model_fusion_clock_location,base.group_portal,1,0,0,0
@@ -22,4 +25,5 @@ access_fusion_clock_correction_portal,fusion.clock.correction.portal,model_fusio
 access_hr_attendance_portal,hr.attendance.portal,hr_attendance.model_hr_attendance,base.group_portal,1,0,0,0
 access_hr_employee_portal_clock,hr.employee.portal.clock,hr.model_hr_employee,base.group_portal,1,0,0,0
 access_fusion_clock_shift_portal,fusion.clock.shift.portal,model_fusion_clock_shift,base.group_portal,1,0,0,0
+access_fusion_clock_schedule_portal,fusion.clock.schedule.portal,model_fusion_clock_schedule,base.group_portal,1,0,0,0
 access_fusion_clock_nfc_enrollment_wizard_manager,fusion.clock.nfc.enrollment.wizard.manager,model_fusion_clock_nfc_enrollment_wizard,group_fusion_clock_manager,1,1,1,1

fusion_clock/security/security.xml

@@ -174,6 +174,49 @@
         <field name="groups" eval="[(4, ref('group_fusion_clock_manager'))]"/>
     </record>
 
+    <!-- ================================================================
+         Record Rules - Dated Schedules
+         ================================================================ -->
+    <record id="rule_schedule_user" model="ir.rule">
+        <field name="name">Schedule: User sees own</field>
+        <field name="model_id" ref="model_fusion_clock_schedule"/>
+        <field name="domain_force">[('employee_id.user_id', '=', user.id)]</field>
+        <field name="groups" eval="[(4, ref('group_fusion_clock_user'))]"/>
+        <field name="perm_read" eval="True"/>
+        <field name="perm_write" eval="False"/>
+        <field name="perm_create" eval="False"/>
+        <field name="perm_unlink" eval="False"/>
+    </record>
+
+    <record id="rule_schedule_team_lead" model="ir.rule">
+        <field name="name">Schedule: Team Lead sees direct reports</field>
+        <field name="model_id" ref="model_fusion_clock_schedule"/>
+        <field name="domain_force">['|', ('employee_id.user_id', '=', user.id), ('employee_id.parent_id.user_id', '=', user.id)]</field>
+        <field name="groups" eval="[(4, ref('group_fusion_clock_team_lead'))]"/>
+        <field name="perm_read" eval="True"/>
+        <field name="perm_write" eval="False"/>
+        <field name="perm_create" eval="False"/>
+        <field name="perm_unlink" eval="False"/>
+    </record>
+
+    <record id="rule_schedule_manager" model="ir.rule">
+        <field name="name">Schedule: Manager full access</field>
+        <field name="model_id" ref="model_fusion_clock_schedule"/>
+        <field name="domain_force">[('company_id', 'in', company_ids)]</field>
+        <field name="groups" eval="[(4, ref('group_fusion_clock_manager'))]"/>
+    </record>
+
+    <record id="rule_schedule_audit_manager" model="ir.rule">
+        <field name="name">Schedule Audit: Manager reads all</field>
+        <field name="model_id" ref="model_fusion_clock_schedule_audit"/>
+        <field name="domain_force">[('company_id', 'in', company_ids)]</field>
+        <field name="groups" eval="[(4, ref('group_fusion_clock_manager'))]"/>
+        <field name="perm_read" eval="True"/>
+        <field name="perm_write" eval="False"/>
+        <field name="perm_create" eval="False"/>
+        <field name="perm_unlink" eval="False"/>
+    </record>
+
     <!-- ================================================================
          Record Rules - Correction Request
          ================================================================ -->
@@ -286,4 +329,15 @@
         <field name="perm_unlink" eval="False"/>
     </record>
 
+    <record id="rule_schedule_portal" model="ir.rule">
+        <field name="name">Schedule: Portal user sees own</field>
+        <field name="model_id" ref="model_fusion_clock_schedule"/>
+        <field name="domain_force">[('employee_id.user_id', '=', user.id)]</field>
+        <field name="groups" eval="[(4, ref('base.group_portal'))]"/>
+        <field name="perm_read" eval="True"/>
+        <field name="perm_write" eval="False"/>
+        <field name="perm_create" eval="False"/>
+        <field name="perm_unlink" eval="False"/>
+    </record>
+
 </odoo>

fusion_clock/static/src/css/portal_clock.css

@@ -219,6 +219,63 @@ body:has(.fclk-app) .o_footer {
     opacity: 0.5;
 }
 
+/* ---- Scheduled Shift Card ---- */
+.fclk-schedule-card {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    background: var(--fclk-card);
+    border: 1px solid var(--fclk-card-border);
+    border-radius: 14px;
+    padding: 14px 16px;
+    margin: -14px 0 28px;
+    box-shadow: var(--fclk-shadow);
+}
+
+.fclk-schedule-icon {
+    width: 38px;
+    height: 38px;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 10px;
+    background: rgba(59, 130, 246, 0.12);
+    color: var(--fclk-blue);
+    font-size: 16px;
+}
+
+.fclk-schedule-info {
+    min-width: 0;
+    flex: 1;
+}
+
+.fclk-schedule-label {
+    color: var(--fclk-text-muted);
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+
+.fclk-schedule-value {
+    color: var(--fclk-text);
+    font-size: 14px;
+    font-weight: 650;
+    margin-top: 2px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.fclk-schedule-hours {
+    color: var(--fclk-text);
+    font-size: 18px;
+    font-weight: 700;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+
 /* ---- Timer Section ---- */
 .fclk-timer-section {
     text-align: center;

fusion_clock/static/src/js/fusion_clock_shift_planner.js

@@ -0,0 +1,741 @@
+/** @odoo-module **/
+
+import { Component, onPatched, onWillStart, useExternalListener, useRef, useState } from "@odoo/owl";
+import { rpc } from "@web/core/network/rpc";
+import { registry } from "@web/core/registry";
+import { useService } from "@web/core/utils/hooks";
+
+export class FusionClockShiftPlanner extends Component {
+    static template = "fusion_clock.ShiftPlanner";
+    static props = [];
+
+    setup() {
+        this.notification = useService("notification");
+        this.dirtyCells = {};
+        this.root = useRef("root");
+        this.editorRef = useRef("shiftEditor");
+        this.activeCellAnchor = null;
+        this.activeEditorEmployee = null;
+        this.activeEditorDay = null;
+        this.timeOptions = this._buildTimeOptions();
+        this.state = useState({
+            loading: true,
+            saving: false,
+            weekStart: "",
+            weekEnd: "",
+            days: [],
+            departments: [],
+            employees: [],
+            shifts: [],
+            error: "",
+            dirtyCount: 0,
+            invalidCount: 0,
+            collapsed: {},
+            editor: {
+                open: false,
+                employeeId: false,
+                employeeName: "",
+                date: "",
+                dayLabel: "",
+                startValue: "9.00",
+                endValue: "17.00",
+                breakMinutes: 30,
+                hoursDisplay: "7:30",
+                error: "",
+                top: 0,
+                left: 0,
+            },
+        });
+
+        onWillStart(async () => {
+            await this.loadWeek();
+        });
+        useExternalListener(
+            window,
+            "click",
+            (ev) => this.onGlobalClick(ev),
+            { capture: true }
+        );
+        useExternalListener(window, "resize", () => this._positionActiveEditor());
+        useExternalListener(window, "scroll", () => this._positionActiveEditor(), true);
+        onPatched(() => {
+            this._positionActiveEditor();
+        });
+    }
+
+    async loadWeek(weekStart = null) {
+        this.state.loading = true;
+        this.state.error = "";
+        try {
+            const data = await rpc("/fusion_clock/shift_planner/load", { week_start: weekStart });
+            if (data.error) {
+                this.state.error = data.error;
+            } else {
+                this._applyData(data);
+            }
+        } catch (error) {
+            this.state.error = error.message || "Failed to load shift planner.";
+        }
+        this.state.loading = false;
+    }
+
+    _applyData(data) {
+        this.dirtyCells = {};
+        this.state.weekStart = data.week_start;
+        this.state.weekEnd = data.week_end;
+        this.state.days = data.days || [];
+        this.state.departments = data.departments || [];
+        this.state.employees = data.employees || [];
+        this.state.shifts = data.shifts || [];
+        this.state.dirtyCount = 0;
+        this.state.invalidCount = 0;
+        this.state.error = "";
+        this.closeCellEditor();
+    }
+
+    get weekTitle() {
+        if (!this.state.weekStart || !this.state.weekEnd) {
+            return "";
+        }
+        return `${this.state.weekStart} to ${this.state.weekEnd}`;
+    }
+
+    getDepartmentEmployees(department) {
+        const ids = new Set(department.employee_ids || []);
+        return this.state.employees.filter((employee) => ids.has(employee.id));
+    }
+
+    isCollapsed(department) {
+        return !!this.state.collapsed[department.id];
+    }
+
+    toggleDepartment(department) {
+        this.state.collapsed[department.id] = !this.state.collapsed[department.id];
+        this.closeCellEditor();
+    }
+
+    async previousWeek() {
+        await this.loadWeek(this._dateAdd(this.state.weekStart, -7));
+    }
+
+    async nextWeek() {
+        await this.loadWeek(this._dateAdd(this.state.weekStart, 7));
+    }
+
+    async currentWeek() {
+        await this.loadWeek();
+    }
+
+    async copyPreviousWeek() {
+        if (!window.confirm("Copy the previous week into this week? Current saved cells for the week may be replaced.")) {
+            return;
+        }
+        this.state.saving = true;
+        try {
+            const result = await rpc("/fusion_clock/shift_planner/copy_previous_week", {
+                week_start: this.state.weekStart,
+            });
+            if (result.error) {
+                this.notification.add(result.error, { type: "danger" });
+            } else {
+                this._applyData(result.data);
+                this.notification.add(`Copied previous week (${result.changed || 0} changes).`, { type: "success" });
+            }
+        } catch (error) {
+            this.notification.add(error.message || "Could not copy previous week.", { type: "danger" });
+        }
+        this.state.saving = false;
+    }
+
+    async save() {
+        this._recountInvalid();
+        if (this.state.invalidCount) {
+            this.notification.add("Fix invalid shift cells before saving.", { type: "danger" });
+            return;
+        }
+        const changes = Object.values(this.dirtyCells);
+        if (!changes.length) {
+            this.notification.add("No shift changes to save.", { type: "info" });
+            return;
+        }
+        this.state.saving = true;
+        try {
+            const result = await rpc("/fusion_clock/shift_planner/save", {
+                week_start: this.state.weekStart,
+                changes,
+            });
+            if (result.error) {
+                this.notification.add(result.error, { type: "danger" });
+            } else if (!result.success) {
+                this._markServerErrors(result.errors || []);
+                this.notification.add("Some shift cells could not be saved.", { type: "danger" });
+            } else {
+                this._applyData(result.data);
+                this.notification.add(`Saved ${result.saved || 0} shift changes.`, { type: "success" });
+            }
+        } catch (error) {
+            this.notification.add(error.message || "Could not save shift planner.", { type: "danger" });
+        }
+        this.state.saving = false;
+    }
+
+    async exportXlsx() {
+        try {
+            const result = await rpc("/fusion_clock/shift_planner/export_xlsx", {
+                week_start: this.state.weekStart,
+            });
+            if (result.error) {
+                this.notification.add(result.error, { type: "danger" });
+                return;
+            }
+            window.location = result.url;
+        } catch (error) {
+            this.notification.add(error.message || "Could not export shift planner.", { type: "danger" });
+        }
+    }
+
+    openCellEditor(employee, day, ev) {
+        if (this.state.loading || this.state.saving) {
+            return;
+        }
+        const anchor = ev.currentTarget.closest(".fclk-planner__shift-cell") || ev.currentTarget;
+        this.activeCellAnchor = anchor;
+        this.activeEditorEmployee = employee;
+        this.activeEditorDay = day;
+
+        const cell = employee.cells[day.date] || {};
+        const fallback = this._defaultTimes(employee, day);
+        const start = cell.is_off ? fallback.start : (cell.start_time || fallback.start);
+        const end = cell.is_off ? fallback.end : (cell.end_time || fallback.end);
+        const breakMinutes = cell.is_off ? 0 : (cell.break_minutes || fallback.breakMinutes || 30);
+        const hours = cell.is_off ? 0 : Math.max(end - start - breakMinutes / 60, 0);
+
+        this.state.editor.open = true;
+        this.state.editor.employeeId = employee.id;
+        this.state.editor.employeeName = employee.name;
+        this.state.editor.date = day.date;
+        this.state.editor.dayLabel = `${day.weekday} ${day.label}`;
+        this.state.editor.startValue = this._timeValue(start);
+        this.state.editor.endValue = this._timeValue(end);
+        this.state.editor.breakMinutes = breakMinutes;
+        this.state.editor.hoursDisplay = cell.hours_display || this._formatHours(hours);
+        this.state.editor.error = cell.error || "";
+        this._positionActiveEditor(anchor);
+    }
+
+    closeCellEditor() {
+        this.state.editor.open = false;
+        this.activeCellAnchor = null;
+        this.activeEditorEmployee = null;
+        this.activeEditorDay = null;
+    }
+
+    onGlobalClick(ev) {
+        if (!this.state.editor.open) {
+            return;
+        }
+        const target = ev.target;
+        const clickedEditor = this.editorRef.el && this.editorRef.el.contains(target);
+        const clickedCell = this.activeCellAnchor && this.activeCellAnchor.contains(target);
+        if (!clickedEditor && !clickedCell) {
+            this.closeCellEditor();
+        }
+    }
+
+    isActiveCell(employee, day) {
+        return this.state.editor.open
+            && this.state.editor.employeeId === employee.id
+            && this.state.editor.date === day.date;
+    }
+
+    onCellInput(employee, day, ev) {
+        this._setCellFromInput(employee, day, ev.target.value, ev.target);
+    }
+
+    onCellKeydown(employee, day, ev) {
+        if (ev.key === "Escape") {
+            ev.preventDefault();
+            this.closeCellEditor();
+            return;
+        }
+        if (ev.key === "Tab") {
+            this._setCellFromInput(employee, day, ev.currentTarget.value, ev.currentTarget);
+            this.closeCellEditor();
+            return;
+        }
+        if (ev.key === "Enter") {
+            ev.preventDefault();
+            this._setCellFromInput(employee, day, ev.currentTarget.value, ev.currentTarget);
+            if (!employee.cells[day.date]?.error) {
+                this.closeCellEditor();
+                this._focusRelativeCell(ev.currentTarget, ev.shiftKey ? -this.state.days.length : this.state.days.length);
+            }
+        }
+    }
+
+    selectQuickShift(option) {
+        const context = this._activeEditorContext();
+        if (!context) {
+            return;
+        }
+        let parsed;
+        if (option.type === "template") {
+            parsed = {
+                is_off: false,
+                shift_id: option.shiftId,
+                start_time: option.start,
+                end_time: option.end,
+                break_minutes: option.breakMinutes,
+                hours: option.hours,
+                hours_display: option.hoursDisplay,
+                label: option.input,
+                normalized_input: option.input,
+            };
+        } else {
+            parsed = this._parseInput(option.input, context.cell);
+        }
+        this._applyParsedToCell(context.employee, context.day, parsed, option.input);
+        this._syncEditorFromCell(context.employee, context.day);
+        this.closeCellEditor();
+    }
+
+    clearActiveCell() {
+        const context = this._activeEditorContext();
+        if (!context) {
+            return;
+        }
+        this._setCellFromInput(context.employee, context.day, "");
+        this.closeCellEditor();
+    }
+
+    onEditorStartChange(ev) {
+        this.state.editor.startValue = ev.target.value;
+        this.applyEditorRange(false);
+    }
+
+    onEditorEndChange(ev) {
+        this.state.editor.endValue = ev.target.value;
+        this.applyEditorRange(false);
+    }
+
+    applyEditorRange(close = true) {
+        const context = this._activeEditorContext();
+        if (!context) {
+            return;
+        }
+        const start = Number(this.state.editor.startValue);
+        let end = Number(this.state.editor.endValue);
+        if (end <= start) {
+            end = Math.min(start + 0.5, 24);
+            this.state.editor.endValue = this._timeValue(end);
+        }
+        const parsed = this._rangeToParsed(start, end, this.state.editor.breakMinutes || 0);
+        if (parsed.error) {
+            context.cell.error = parsed.error;
+            this.state.editor.error = parsed.error;
+        } else {
+            this._applyParsedToCell(context.employee, context.day, parsed, parsed.label);
+            this._syncEditorFromCell(context.employee, context.day);
+        }
+        this._recountInvalid();
+        if (close && !parsed.error) {
+            this.closeCellEditor();
+        }
+    }
+
+    _setCellFromInput(employee, day, input, target = null) {
+        const cell = employee.cells[day.date];
+        cell.input = input;
+
+        const parsed = this._parseInput(input, cell);
+        this._applyParsedToCell(employee, day, parsed, input);
+        if (!parsed.error && target && parsed.normalized_input !== undefined) {
+            target.value = parsed.normalized_input;
+        }
+        this._syncEditorFromCell(employee, day);
+    }
+
+    _applyParsedToCell(employee, day, parsed, input) {
+        const cell = employee.cells[day.date];
+        cell.error = parsed.error || "";
+        if (parsed.error) {
+            cell.input = input;
+            this.state.editor.error = parsed.error;
+            this._markDirty(employee, day);
+            this._recountInvalid();
+            return;
+        }
+
+        cell.is_off = parsed.is_off || false;
+        cell.shift_id = parsed.shift_id || false;
+        cell.start_time = parsed.start_time || 0;
+        cell.end_time = parsed.end_time || 0;
+        cell.break_minutes = parsed.break_minutes || 0;
+        cell.hours = parsed.hours || 0;
+        cell.hours_display = parsed.hours_display || "0:00";
+        cell.label = parsed.label || "";
+        cell.input = parsed.normalized_input !== undefined ? parsed.normalized_input : input;
+        this.state.editor.error = "";
+        this._markDirty(employee, day);
+        this._recountInvalid();
+    }
+
+    _markDirty(employee, day) {
+        const cell = employee.cells[day.date];
+        const key = `${employee.id}:${day.date}`;
+        const payload = {
+            employee_id: employee.id,
+            date: day.date,
+            input: cell.input,
+            shift_id: cell.shift_id || false,
+            note: cell.note || "",
+        };
+        if ((cell.input || "").trim()) {
+            payload.is_off = !!cell.is_off;
+            payload.start_time = cell.start_time || 0;
+            payload.end_time = cell.end_time || 0;
+            payload.break_minutes = cell.break_minutes || 0;
+        }
+        this.dirtyCells[key] = payload;
+        this.state.dirtyCount = Object.keys(this.dirtyCells).length;
+    }
+
+    _markServerErrors(errors) {
+        for (const error of errors) {
+            const employee = this.state.employees.find((emp) => emp.id === error.employee_id);
+            const cell = employee && employee.cells[error.date];
+            if (cell) {
+                cell.error = error.message;
+            }
+        }
+        this._recountInvalid();
+    }
+
+    _recountInvalid() {
+        let invalid = 0;
+        for (const employee of this.state.employees) {
+            for (const day of this.state.days) {
+                if (employee.cells[day.date]?.error) {
+                    invalid++;
+                }
+            }
+        }
+        this.state.invalidCount = invalid;
+    }
+
+    _parseInput(value, currentCell = {}) {
+        const text = (value || "").trim();
+        if (!text) {
+            return {
+                is_off: false,
+                shift_id: false,
+                start_time: 0,
+                end_time: 0,
+                break_minutes: 0,
+                label: "",
+                hours: 0,
+                hours_display: "0:00",
+                normalized_input: "",
+            };
+        }
+        if (text.toUpperCase() === "OFF") {
+            return {
+                is_off: true,
+                shift_id: false,
+                start_time: 0,
+                end_time: 0,
+                break_minutes: 0,
+                hours: 0,
+                hours_display: "0:00",
+                label: "OFF",
+                normalized_input: "OFF",
+            };
+        }
+
+        const lowerText = text.toLowerCase();
+        const template = this.state.shifts.find((shift) =>
+            [shift.option_label, shift.label, shift.name].some((value) => (value || "").toLowerCase() === lowerText)
+        );
+        if (template) {
+            return {
+                is_off: false,
+                shift_id: template.id,
+                start_time: template.start_time,
+                end_time: template.end_time,
+                break_minutes: template.break_minutes,
+                hours: template.hours,
+                hours_display: template.hours_display,
+                label: template.label,
+                normalized_input: template.label,
+            };
+        }
+
+        try {
+            const parsed = this._parseTypedShift(text, currentCell);
+            return parsed;
+        } catch (error) {
+            return { error: error.message };
+        }
+    }
+
+    _parseTypedShift(value, currentCell = {}) {
+        const normalized = value.replaceAll("–", "-").replaceAll("—", "-").replace(/\s+to\s+/i, "-");
+        const parts = normalized.split("-");
+        if (parts.length !== 2 || !parts[0].trim() || !parts[1].trim()) {
+            throw new Error("Use 9-5, 9:00-5:30, 9:00 am - 5:30 pm, or OFF.");
+        }
+        const start = this._parseTimePart(parts[0]);
+        let end = this._parseTimePart(parts[1]);
+        if (end <= start && end + 12 <= 24) {
+            end += 12;
+        }
+        if (end <= start) {
+            throw new Error("End must be after start.");
+        }
+        const breakMinutes = currentCell.break_minutes || 30;
+        const hours = Math.max(end - start - breakMinutes / 60, 0);
+        const label = `${this._formatFloatTime(start)} - ${this._formatFloatTime(end)}`;
+        return {
+            is_off: false,
+            shift_id: false,
+            start_time: start,
+            end_time: end,
+            break_minutes: breakMinutes,
+            hours,
+            hours_display: this._formatHours(hours),
+            label,
+            normalized_input: label,
+        };
+    }
+
+    _rangeToParsed(start, end, breakMinutes) {
+        if (Number.isNaN(start) || Number.isNaN(end)) {
+            return { error: "Choose a start and end time." };
+        }
+        if (end <= start) {
+            return { error: "End must be after start." };
+        }
+        const hours = Math.max(end - start - breakMinutes / 60, 0);
+        const label = `${this._formatFloatTime(start)} - ${this._formatFloatTime(end)}`;
+        return {
+            is_off: false,
+            shift_id: false,
+            start_time: start,
+            end_time: end,
+            break_minutes: breakMinutes,
+            hours,
+            hours_display: this._formatHours(hours),
+            label,
+            normalized_input: label,
+        };
+    }
+
+    _parseTimePart(raw) {
+        const text = raw.trim().toLowerCase().replaceAll(".", "");
+        const match = text.match(/^(\d{1,2})(?::(\d{1,2}))?\s*(am|pm)?$/);
+        if (!match) {
+            throw new Error(`Could not read "${raw.trim()}".`);
+        }
+        let hour = Number(match[1]);
+        const minute = Number(match[2] || 0);
+        const meridiem = match[3];
+        if (minute < 0 || minute > 59) {
+            throw new Error("Minutes must be 00-59.");
+        }
+        if (meridiem) {
+            if (hour < 1 || hour > 12) {
+                throw new Error("Use 1-12 with am/pm.");
+            }
+            if (meridiem === "am") {
+                hour = hour === 12 ? 0 : hour;
+            } else {
+                hour = hour === 12 ? 12 : hour + 12;
+            }
+        }
+        if (hour < 0 || hour > 24) {
+            throw new Error("Hours must be 0-24.");
+        }
+        return hour + minute / 60;
+    }
+
+    _formatFloatTime(value) {
+        let hour = Math.floor(value);
+        let minute = Math.round((value - hour) * 60);
+        if (minute === 60) {
+            hour += 1;
+            minute = 0;
+        }
+        const suffix = hour < 12 || hour === 24 ? "am" : "pm";
+        let displayHour = hour % 12;
+        if (displayHour === 0) {
+            displayHour = 12;
+        }
+        return `${displayHour}:${String(minute).padStart(2, "0")} ${suffix}`;
+    }
+
+    _formatHours(value) {
+        let hour = Math.floor(value);
+        let minute = Math.round((value - hour) * 60);
+        if (minute === 60) {
+            hour += 1;
+            minute = 0;
+        }
+        return `${hour}:${String(minute).padStart(2, "0")}`;
+    }
+
+    _timeValue(value) {
+        const rounded = Math.round(Number(value || 0) * 4) / 4;
+        return rounded.toFixed(2);
+    }
+
+    _buildTimeOptions() {
+        const options = [];
+        for (let minutes = 0; minutes <= 24 * 60; minutes += 15) {
+            const value = minutes / 60;
+            options.push({
+                value: this._timeValue(value),
+                label: this._formatFloatTime(value),
+            });
+        }
+        return options;
+    }
+
+    _defaultTimes(employee, day) {
+        const dayIndex = this.state.days.findIndex((item) => item.date === day.date);
+        if (dayIndex > 0) {
+            const previousDay = this.state.days[dayIndex - 1];
+            const previousCell = employee.cells[previousDay.date];
+            if (previousCell && !previousCell.is_off && previousCell.start_time && previousCell.end_time) {
+                return {
+                    start: previousCell.start_time,
+                    end: previousCell.end_time,
+                    breakMinutes: previousCell.break_minutes || 30,
+                };
+            }
+        }
+        const firstShift = this.state.shifts[0];
+        if (firstShift) {
+            return {
+                start: firstShift.start_time,
+                end: firstShift.end_time,
+                breakMinutes: firstShift.break_minutes || 30,
+            };
+        }
+        return { start: 9, end: 17, breakMinutes: 30 };
+    }
+
+    get quickShiftOptions() {
+        const options = [{
+            key: "off",
+            type: "input",
+            input: "OFF",
+            label: "OFF",
+            detail: "0:00",
+        }];
+        const seen = new Set(["OFF"]);
+        for (const shift of this.state.shifts) {
+            if (seen.has(shift.label)) {
+                continue;
+            }
+            seen.add(shift.label);
+            options.push({
+                key: `shift-${shift.id}`,
+                type: "template",
+                shiftId: shift.id,
+                input: shift.label,
+                label: shift.name || shift.label,
+                detail: `${shift.label} - ${shift.hours_display}`,
+                start: shift.start_time,
+                end: shift.end_time,
+                breakMinutes: shift.break_minutes,
+                hours: shift.hours,
+                hoursDisplay: shift.hours_display,
+            });
+        }
+        for (const input of ["9:00 am - 5:00 pm", "7:00 am - 3:30 pm", "8:00 am - 4:30 pm", "11:00 am - 7:30 pm", "12:00 pm - 8:30 pm"]) {
+            if (seen.has(input)) {
+                continue;
+            }
+            const parsed = this._parseInput(input, { break_minutes: 30 });
+            seen.add(input);
+            options.push({
+                key: `common-${input}`,
+                type: "input",
+                input,
+                label: input,
+                detail: parsed.hours_display || "0:00",
+            });
+        }
+        return options.slice(0, 10);
+    }
+
+    _activeEditorContext() {
+        if (!this.state.editor.open || !this.activeEditorEmployee || !this.activeEditorDay) {
+            return null;
+        }
+        return {
+            employee: this.activeEditorEmployee,
+            day: this.activeEditorDay,
+            cell: this.activeEditorEmployee.cells[this.activeEditorDay.date],
+        };
+    }
+
+    _syncEditorFromCell(employee, day) {
+        if (!this.isActiveCell(employee, day)) {
+            return;
+        }
+        const cell = employee.cells[day.date] || {};
+        if (!cell.is_off && cell.start_time && cell.end_time) {
+            this.state.editor.startValue = this._timeValue(cell.start_time);
+            this.state.editor.endValue = this._timeValue(cell.end_time);
+        }
+        this.state.editor.breakMinutes = cell.break_minutes || 0;
+        this.state.editor.hoursDisplay = cell.hours_display || "0:00";
+        this.state.editor.error = cell.error || "";
+    }
+
+    _focusRelativeCell(input, offset) {
+        const inputs = Array.from(document.querySelectorAll(".fclk-planner__shift-input"));
+        const index = inputs.indexOf(input);
+        const next = inputs[index + offset];
+        if (next) {
+            next.focus();
+            next.select();
+        }
+    }
+
+    _positionActiveEditor(anchor = null) {
+        if (!this.state.editor.open) {
+            return;
+        }
+        const target = anchor || this.activeCellAnchor;
+        if (!target || !target.isConnected) {
+            this.closeCellEditor();
+            return;
+        }
+        const rect = target.getBoundingClientRect();
+        const editorWidth = Math.min(380, window.innerWidth - 16);
+        const editorHeight = this.editorRef.el?.offsetHeight || 300;
+        let left = Math.max(8, Math.min(rect.left, window.innerWidth - editorWidth - 8));
+        let top = rect.bottom + 8;
+        if (top + editorHeight > window.innerHeight - 8) {
+            top = Math.max(8, rect.top - editorHeight - 8);
+        }
+        left = Math.round(left);
+        top = Math.round(top);
+        if (this.state.editor.left !== left) {
+            this.state.editor.left = left;
+        }
+        if (this.state.editor.top !== top) {
+            this.state.editor.top = top;
+        }
+    }
+
+    _dateAdd(dateString, days) {
+        const date = new Date(`${dateString}T12:00:00`);
+        date.setDate(date.getDate() + days);
+        return date.toISOString().slice(0, 10);
+    }
+}
+
+registry.category("actions").add("fusion_clock.ShiftPlanner", FusionClockShiftPlanner);

fusion_clock/static/src/scss/_fusion_clock_shift_planner_tokens.scss

@@ -0,0 +1,77 @@
+$o-webclient-color-scheme: bright !default;
+
+$_fclk-planner-page: #f3f4f6;
+$_fclk-planner-panel: #eef1f4;
+$_fclk-planner-card: #ffffff;
+$_fclk-planner-text: #1f2937;
+$_fclk-planner-muted: #6b7280;
+$_fclk-planner-border: #d8dadd;
+$_fclk-planner-border-strong: #9ca3af;
+$_fclk-planner-day: #b7dff5;
+$_fclk-planner-subhead: #d8e9bd;
+$_fclk-planner-hours: #f5d39b;
+$_fclk-planner-fallback: #fff8e5;
+$_fclk-planner-row-hover: #f9fafb;
+$_fclk-planner-error: #dc2626;
+$_fclk-planner-focus: #2563eb;
+$_fclk-planner-shadow: rgba(15, 23, 42, 0.08);
+$_fclk-planner-editor: #111827;
+$_fclk-planner-editor-text: #f9fafb;
+$_fclk-planner-editor-muted: #cbd5e1;
+$_fclk-planner-editor-border: #374151;
+$_fclk-planner-editor-control: #ffffff;
+$_fclk-planner-editor-control-text: #111827;
+$_fclk-planner-editor-chip: #1f2937;
+$_fclk-planner-editor-chip-hover: #334155;
+
+@if $o-webclient-color-scheme == dark {
+    $_fclk-planner-page: #171a1f !global;
+    $_fclk-planner-panel: #20242b !global;
+    $_fclk-planner-card: #262b33 !global;
+    $_fclk-planner-text: #f3f4f6 !global;
+    $_fclk-planner-muted: #a3aab8 !global;
+    $_fclk-planner-border: #3b424c !global;
+    $_fclk-planner-border-strong: #647082 !global;
+    $_fclk-planner-day: #21465f !global;
+    $_fclk-planner-subhead: #394b2d !global;
+    $_fclk-planner-hours: #6f4f22 !global;
+    $_fclk-planner-fallback: #393326 !global;
+    $_fclk-planner-row-hover: #2b313a !global;
+    $_fclk-planner-error: #f87171 !global;
+    $_fclk-planner-focus: #60a5fa !global;
+    $_fclk-planner-shadow: rgba(0, 0, 0, 0.32) !global;
+    $_fclk-planner-editor: #0f172a !global;
+    $_fclk-planner-editor-text: #f9fafb !global;
+    $_fclk-planner-editor-muted: #cbd5e1 !global;
+    $_fclk-planner-editor-border: #475569 !global;
+    $_fclk-planner-editor-control: #1f2937 !global;
+    $_fclk-planner-editor-control-text: #f9fafb !global;
+    $_fclk-planner-editor-chip: #1e293b !global;
+    $_fclk-planner-editor-chip-hover: #334155 !global;
+}
+
+:root {
+    --fclk-planner-page: #{$_fclk-planner-page};
+    --fclk-planner-panel: #{$_fclk-planner-panel};
+    --fclk-planner-card: #{$_fclk-planner-card};
+    --fclk-planner-text: #{$_fclk-planner-text};
+    --fclk-planner-muted: #{$_fclk-planner-muted};
+    --fclk-planner-border: #{$_fclk-planner-border};
+    --fclk-planner-border-strong: #{$_fclk-planner-border-strong};
+    --fclk-planner-day: #{$_fclk-planner-day};
+    --fclk-planner-subhead: #{$_fclk-planner-subhead};
+    --fclk-planner-hours: #{$_fclk-planner-hours};
+    --fclk-planner-fallback: #{$_fclk-planner-fallback};
+    --fclk-planner-row-hover: #{$_fclk-planner-row-hover};
+    --fclk-planner-error: #{$_fclk-planner-error};
+    --fclk-planner-focus: #{$_fclk-planner-focus};
+    --fclk-planner-shadow: #{$_fclk-planner-shadow};
+    --fclk-planner-editor: #{$_fclk-planner-editor};
+    --fclk-planner-editor-text: #{$_fclk-planner-editor-text};
+    --fclk-planner-editor-muted: #{$_fclk-planner-editor-muted};
+    --fclk-planner-editor-border: #{$_fclk-planner-editor-border};
+    --fclk-planner-editor-control: #{$_fclk-planner-editor-control};
+    --fclk-planner-editor-control-text: #{$_fclk-planner-editor-control-text};
+    --fclk-planner-editor-chip: #{$_fclk-planner-editor-chip};
+    --fclk-planner-editor-chip-hover: #{$_fclk-planner-editor-chip-hover};
+}

fusion_clock/static/src/scss/fusion_clock_shift_planner.dark.scss

@@ -0,0 +1,25 @@
+:root {
+    --fclk-planner-page: #171a1f;
+    --fclk-planner-panel: #20242b;
+    --fclk-planner-card: #262b33;
+    --fclk-planner-text: #f3f4f6;
+    --fclk-planner-muted: #a3aab8;
+    --fclk-planner-border: #3b424c;
+    --fclk-planner-border-strong: #647082;
+    --fclk-planner-day: #21465f;
+    --fclk-planner-subhead: #394b2d;
+    --fclk-planner-hours: #6f4f22;
+    --fclk-planner-fallback: #393326;
+    --fclk-planner-row-hover: #2b313a;
+    --fclk-planner-error: #f87171;
+    --fclk-planner-focus: #60a5fa;
+    --fclk-planner-shadow: rgba(0, 0, 0, 0.32);
+    --fclk-planner-editor: #0f172a;
+    --fclk-planner-editor-text: #f9fafb;
+    --fclk-planner-editor-muted: #cbd5e1;
+    --fclk-planner-editor-border: #475569;
+    --fclk-planner-editor-control: #1f2937;
+    --fclk-planner-editor-control-text: #f9fafb;
+    --fclk-planner-editor-chip: #1e293b;
+    --fclk-planner-editor-chip-hover: #334155;
+}

fusion_clock/static/src/scss/fusion_clock_shift_planner.scss

@@ -0,0 +1,447 @@
+.fclk-planner {
+    min-height: 100%;
+    background: var(--fclk-planner-page, #f3f4f6);
+    color: var(--fclk-planner-text, #1f2937);
+    display: flex;
+    flex-direction: column;
+}
+
+.fclk-planner__toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    padding: 16px 20px;
+    background: var(--fclk-planner-card, #ffffff);
+    border-bottom: 1px solid var(--fclk-planner-border, #d8dadd);
+    box-shadow: 0 1px 3px var(--fclk-planner-shadow, rgba(15, 23, 42, 0.08));
+}
+
+.fclk-planner__title {
+    margin: 0;
+    font-size: 20px;
+    font-weight: 650;
+    line-height: 1.2;
+}
+
+.fclk-planner__subtitle {
+    color: var(--fclk-planner-muted, #6b7280);
+    font-size: 13px;
+    margin-top: 3px;
+}
+
+.fclk-planner__actions {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    flex-wrap: wrap;
+    gap: 8px;
+}
+
+.fclk-planner__warning {
+    margin: 12px 16px 0;
+    padding: 10px 12px;
+    background: #fff7ed;
+    border: 1px solid #fed7aa;
+    border-radius: 6px;
+    color: #9a3412;
+    font-size: 13px;
+}
+
+.fclk-planner__loading {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    min-height: 340px;
+    color: var(--fclk-planner-muted, #6b7280);
+}
+
+.fclk-planner__table-wrap {
+    flex: 1;
+    margin: 16px;
+    overflow: auto;
+    background: var(--fclk-planner-panel, #eef1f4);
+    border: 1px solid var(--fclk-planner-border, #d8dadd);
+    border-radius: 6px;
+    box-shadow: 0 6px 20px var(--fclk-planner-shadow, rgba(15, 23, 42, 0.08));
+}
+
+.fclk-planner__table {
+    --fclk-planner-shift-width: 135px;
+    --fclk-planner-hours-width: 55px;
+    --fclk-planner-days-width: 1330px;
+    width: 100%;
+    min-width: 1600px;
+    border-collapse: separate;
+    border-spacing: 0;
+    table-layout: fixed;
+    background: var(--fclk-planner-card, #ffffff);
+    font-size: 13px;
+}
+
+.fclk-planner__employee-col {
+    width: calc(100% - var(--fclk-planner-days-width));
+}
+
+.fclk-planner__shift-col {
+    width: var(--fclk-planner-shift-width);
+}
+
+.fclk-planner__hours-col {
+    width: var(--fclk-planner-hours-width);
+}
+
+.fclk-planner__table th,
+.fclk-planner__table td {
+    border-right: 1px solid var(--fclk-planner-border-strong, #9ca3af);
+    border-bottom: 1px solid var(--fclk-planner-border-strong, #9ca3af);
+}
+
+.fclk-planner__employee-head,
+.fclk-planner__day-head,
+.fclk-planner__sub-head {
+    position: sticky;
+    top: 0;
+    z-index: 6;
+    color: var(--fclk-planner-text, #1f2937);
+}
+
+.fclk-planner__employee-head {
+    left: 0;
+    z-index: 8;
+    width: calc(100% - var(--fclk-planner-days-width));
+    background: var(--fclk-planner-day, #b7dff5);
+    text-align: left;
+    padding: 10px 12px;
+    border-left: 1px solid var(--fclk-planner-border-strong, #9ca3af);
+}
+
+.fclk-planner__day-head {
+    background: var(--fclk-planner-day, #b7dff5);
+    text-align: center;
+    padding: 6px 8px;
+    font-weight: 700;
+}
+
+.fclk-planner__sub-head {
+    top: 47px;
+    background: var(--fclk-planner-subhead, #d8e9bd);
+    text-align: left;
+    padding: 5px 8px;
+    font-weight: 650;
+}
+
+.fclk-planner__hours-head {
+    width: var(--fclk-planner-hours-width);
+    text-align: center;
+    padding-left: 2px;
+    padding-right: 2px;
+}
+
+.fclk-planner__weekday {
+    font-size: 14px;
+    line-height: 1.1;
+}
+
+.fclk-planner__date {
+    font-size: 12px;
+    font-weight: 500;
+    margin-top: 2px;
+}
+
+.fclk-planner__department-row td {
+    background: var(--fclk-planner-panel, #eef1f4);
+    padding: 0;
+    position: sticky;
+    left: 0;
+    z-index: 5;
+}
+
+.fclk-planner__department-toggle {
+    width: 100%;
+    min-height: 34px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    border: 0;
+    background: transparent;
+    color: var(--fclk-planner-text, #1f2937);
+    font-weight: 650;
+    padding: 7px 12px;
+    text-align: left;
+}
+
+.fclk-planner__department-count {
+    color: var(--fclk-planner-muted, #6b7280);
+    font-weight: 500;
+    font-size: 12px;
+}
+
+.fclk-planner__employee-row {
+    background: var(--fclk-planner-card, #ffffff);
+}
+
+.fclk-planner__employee-row:hover {
+    background: var(--fclk-planner-row-hover, #f9fafb);
+}
+
+.fclk-planner__employee-cell {
+    position: sticky;
+    left: 0;
+    z-index: 4;
+    width: calc(100% - var(--fclk-planner-days-width));
+    background: inherit;
+    padding: 8px 12px;
+    border-left: 1px solid var(--fclk-planner-border-strong, #9ca3af);
+}
+
+.fclk-planner__employee-name {
+    font-weight: 650;
+    line-height: 1.2;
+}
+
+.fclk-planner__employee-role {
+    margin-top: 2px;
+    color: var(--fclk-planner-muted, #6b7280);
+    font-size: 12px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.fclk-planner__shift-cell {
+    width: var(--fclk-planner-shift-width);
+    min-height: 42px;
+    padding: 4px;
+    vertical-align: top;
+    background: var(--fclk-planner-card, #ffffff);
+}
+
+.fclk-planner__shift-cell--fallback {
+    background: var(--fclk-planner-fallback, #fff8e5);
+}
+
+.fclk-planner__shift-cell--error {
+    background: #fef2f2;
+}
+
+.fclk-planner__shift-cell--active {
+    box-shadow: inset 0 0 0 2px var(--fclk-planner-focus, #2563eb);
+}
+
+.fclk-planner__shift-input {
+    width: 100%;
+    height: 32px;
+    border: 1px solid transparent;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--fclk-planner-text, #1f2937);
+    padding: 4px 6px;
+    font-size: 13px;
+    line-height: 1.2;
+    outline: none;
+    white-space: nowrap;
+}
+
+.fclk-planner__shift-input:focus {
+    background: var(--fclk-planner-card, #ffffff);
+    border-color: var(--fclk-planner-focus, #2563eb);
+    box-shadow: 0 0 0 2px rgba(37, 99, 235, 0.16);
+}
+
+.fclk-planner__cell-error {
+    color: var(--fclk-planner-error, #dc2626);
+    font-size: 11px;
+    line-height: 1.2;
+    padding: 3px 5px 0;
+}
+
+.fclk-planner__hours-cell {
+    width: var(--fclk-planner-hours-width);
+    background: var(--fclk-planner-hours, #f5d39b);
+    text-align: center;
+    font-variant-numeric: tabular-nums;
+    font-weight: 650;
+    vertical-align: middle;
+    padding: 6px 2px;
+}
+
+.fclk-planner__cell-editor {
+    position: fixed;
+    z-index: 1080;
+    width: calc(100vw - 16px);
+    max-width: 380px;
+    padding: 14px;
+    color: var(--fclk-planner-editor-text, #f9fafb);
+    background: var(--fclk-planner-editor, #111827);
+    border: 1px solid var(--fclk-planner-editor-border, #374151);
+    border-radius: 8px;
+    box-shadow: 0 18px 45px rgba(0, 0, 0, 0.32);
+}
+
+.fclk-planner__cell-editor::before {
+    content: "";
+    position: absolute;
+    top: -7px;
+    left: 28px;
+    width: 14px;
+    height: 14px;
+    background: var(--fclk-planner-editor, #111827);
+    border-left: 1px solid var(--fclk-planner-editor-border, #374151);
+    border-top: 1px solid var(--fclk-planner-editor-border, #374151);
+    transform: rotate(45deg);
+}
+
+.fclk-planner__editor-head {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 12px;
+}
+
+.fclk-planner__editor-name {
+    font-size: 14px;
+    font-weight: 700;
+    line-height: 1.2;
+}
+
+.fclk-planner__editor-day {
+    margin-top: 2px;
+    color: var(--fclk-planner-editor-muted, #cbd5e1);
+    font-size: 12px;
+}
+
+.fclk-planner__editor-hours {
+    min-width: 56px;
+    padding: 5px 8px;
+    text-align: center;
+    color: #111827;
+    background: var(--fclk-planner-hours, #f5d39b);
+    border-radius: 6px;
+    font-weight: 700;
+    font-variant-numeric: tabular-nums;
+}
+
+.fclk-planner__quick-grid {
+    position: relative;
+    z-index: 1;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 8px;
+}
+
+.fclk-planner__quick-chip {
+    min-height: 46px;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    justify-content: center;
+    gap: 2px;
+    padding: 7px 9px;
+    color: var(--fclk-planner-editor-text, #f9fafb);
+    background: var(--fclk-planner-editor-chip, #1f2937);
+    border: 1px solid var(--fclk-planner-editor-border, #374151);
+    border-radius: 6px;
+    text-align: left;
+}
+
+.fclk-planner__quick-chip:hover,
+.fclk-planner__quick-chip:focus {
+    background: var(--fclk-planner-editor-chip-hover, #334155);
+    outline: none;
+}
+
+.fclk-planner__quick-label {
+    width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 13px;
+    font-weight: 650;
+    line-height: 1.15;
+}
+
+.fclk-planner__quick-detail {
+    width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--fclk-planner-editor-muted, #cbd5e1);
+    font-size: 11px;
+    line-height: 1.15;
+}
+
+.fclk-planner__time-row {
+    position: relative;
+    z-index: 1;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 10px;
+    margin-top: 12px;
+}
+
+.fclk-planner__time-field {
+    display: flex;
+    flex-direction: column;
+    gap: 5px;
+    margin: 0;
+    color: var(--fclk-planner-editor-muted, #cbd5e1);
+    font-size: 12px;
+    font-weight: 650;
+}
+
+.fclk-planner__time-field select {
+    width: 100%;
+    height: 34px;
+    color: var(--fclk-planner-editor-control-text, #111827);
+    background: var(--fclk-planner-editor-control, #ffffff);
+    border: 1px solid var(--fclk-planner-editor-border, #374151);
+    border-radius: 6px;
+    padding: 4px 8px;
+    font-size: 13px;
+}
+
+.fclk-planner__editor-error {
+    position: relative;
+    z-index: 1;
+    margin-top: 10px;
+    padding: 7px 8px;
+    color: #991b1b;
+    background: #fee2e2;
+    border-radius: 6px;
+    font-size: 12px;
+    line-height: 1.25;
+}
+
+.fclk-planner__editor-actions {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+    margin-top: 12px;
+}
+
+@media (max-width: 900px) {
+    .fclk-planner__toolbar {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+
+    .fclk-planner__actions {
+        justify-content: flex-start;
+    }
+
+    .fclk-planner__table-wrap {
+        margin: 10px;
+    }
+
+    .fclk-planner__cell-editor {
+        width: calc(100vw - 16px);
+    }
+}

fusion_clock/static/src/xml/fusion_clock_shift_planner.xml

@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="utf-8"?>
+<templates xml:space="preserve">
+
+    <t t-name="fusion_clock.ShiftPlanner">
+        <div class="o_action fclk-planner" t-ref="root">
+            <div class="fclk-planner__toolbar">
+                <div>
+                    <h2 class="fclk-planner__title">Shift Planner</h2>
+                    <div class="fclk-planner__subtitle"><t t-esc="weekTitle"/></div>
+                </div>
+                <div class="fclk-planner__actions">
+                    <button class="btn btn-light" t-on-click="() => this.previousWeek()" t-att-disabled="state.loading or state.saving">
+                        <i class="fa fa-chevron-left"/>
+                    </button>
+                    <button class="btn btn-light" t-on-click="() => this.currentWeek()" t-att-disabled="state.loading or state.saving">This Week</button>
+                    <button class="btn btn-light" t-on-click="() => this.nextWeek()" t-att-disabled="state.loading or state.saving">
+                        <i class="fa fa-chevron-right"/>
+                    </button>
+                    <button class="btn btn-outline-secondary" t-on-click="() => this.copyPreviousWeek()" t-att-disabled="state.loading or state.saving">
+                        <i class="fa fa-copy me-1"/> Copy Previous Week
+                    </button>
+                    <button class="btn btn-outline-secondary" t-on-click="() => this.exportXlsx()" t-att-disabled="state.loading or state.saving">
+                        <i class="fa fa-file-excel-o me-1"/> Export XLSX
+                    </button>
+                    <button class="btn btn-primary" t-on-click="() => this.save()" t-att-disabled="state.loading or state.saving or !state.dirtyCount">
+                        <t t-if="state.saving"><i class="fa fa-spinner fa-spin me-1"/></t>
+                        <t t-else=""><i class="fa fa-save me-1"/></t>
+                        Save
+                        <t t-if="state.dirtyCount">(<t t-esc="state.dirtyCount"/>)</t>
+                    </button>
+                </div>
+            </div>
+
+            <t t-if="state.error">
+                <div class="alert alert-danger mx-3 mt-3"><t t-esc="state.error"/></div>
+            </t>
+
+            <t t-if="state.invalidCount">
+                <div class="fclk-planner__warning">
+                    <i class="fa fa-exclamation-triangle me-1"/>
+                    <t t-esc="state.invalidCount"/> invalid cells need attention.
+                </div>
+            </t>
+
+            <t t-if="state.loading">
+                <div class="fclk-planner__loading">
+                    <i class="fa fa-spinner fa-spin fa-2x"/>
+                    <span>Loading shift planner...</span>
+                </div>
+            </t>
+
+            <t t-if="!state.loading and !state.error">
+                <div class="fclk-planner__table-wrap">
+                    <table class="fclk-planner__table">
+                        <colgroup>
+                            <col class="fclk-planner__employee-col"/>
+                            <t t-foreach="state.days" t-as="day" t-key="'col_' + day.date">
+                                <col class="fclk-planner__shift-col"/>
+                                <col class="fclk-planner__hours-col"/>
+                            </t>
+                        </colgroup>
+                        <thead>
+                            <tr>
+                                <th class="fclk-planner__employee-head" rowspan="2">Employee</th>
+                                <t t-foreach="state.days" t-as="day" t-key="day.date">
+                                    <th class="fclk-planner__day-head" colspan="2">
+                                        <div class="fclk-planner__weekday"><t t-esc="day.weekday"/></div>
+                                        <div class="fclk-planner__date"><t t-esc="day.label"/></div>
+                                    </th>
+                                </t>
+                            </tr>
+                            <tr>
+                                <t t-foreach="state.days" t-as="day" t-key="'sub_' + day.date">
+                                    <th class="fclk-planner__sub-head">Shift</th>
+                                    <th class="fclk-planner__sub-head fclk-planner__hours-head">Hours</th>
+                                </t>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <t t-foreach="state.departments" t-as="department" t-key="department.id">
+                                <tr class="fclk-planner__department-row">
+                                    <td t-att-colspan="1 + state.days.length * 2">
+                                        <button class="fclk-planner__department-toggle" t-on-click="() => this.toggleDepartment(department)">
+                                            <i t-att-class="isCollapsed(department) ? 'fa fa-chevron-right' : 'fa fa-chevron-down'"/>
+                                            <span><t t-esc="department.name"/></span>
+                                            <span class="fclk-planner__department-count">
+                                                <t t-esc="department.employee_ids.length"/> employees
+                                            </span>
+                                        </button>
+                                    </td>
+                                </tr>
+                                <t t-if="!isCollapsed(department)">
+                                    <t t-foreach="getDepartmentEmployees(department)" t-as="employee" t-key="employee.id">
+                                        <tr class="fclk-planner__employee-row">
+                                            <td class="fclk-planner__employee-cell">
+                                                <div class="fclk-planner__employee-name"><t t-esc="employee.name"/></div>
+                                                <div class="fclk-planner__employee-role" t-if="employee.job_title">
+                                                    <t t-esc="employee.job_title"/>
+                                                </div>
+                                            </td>
+                                            <t t-foreach="state.days" t-as="day" t-key="employee.id + '_' + day.date">
+                                                <t t-set="cell" t-value="employee.cells[day.date]"/>
+                                                <td t-att-class="'fclk-planner__shift-cell ' + (cell.error ? 'fclk-planner__shift-cell--error ' : '') + (cell.source === 'fallback' ? 'fclk-planner__shift-cell--fallback ' : '') + (this.isActiveCell(employee, day) ? 'fclk-planner__shift-cell--active' : '')"
+                                                    t-on-click="(ev) => this.openCellEditor(employee, day, ev)">
+                                                    <input class="fclk-planner__shift-input"
+                                                           t-att-value="cell.input"
+                                                           t-att-title="cell.error || cell.label"
+                                                           t-on-focus="(ev) => this.openCellEditor(employee, day, ev)"
+                                                           t-on-change="(ev) => this.onCellInput(employee, day, ev)"
+                                                           t-on-keydown="(ev) => this.onCellKeydown(employee, day, ev)"/>
+                                                    <div class="fclk-planner__cell-error" t-if="cell.error">
+                                                        <t t-esc="cell.error"/>
+                                                    </div>
+                                                </td>
+                                                <td class="fclk-planner__hours-cell">
+                                                    <t t-esc="cell.hours_display || '0:00'"/>
+                                                </td>
+                                            </t>
+                                        </tr>
+                                    </t>
+                                </t>
+                            </t>
+                        </tbody>
+                    </table>
+                </div>
+
+                <div t-if="state.editor.open"
+                     t-ref="shiftEditor"
+                     class="fclk-planner__cell-editor"
+                     t-att-style="'top: ' + state.editor.top + 'px; left: ' + state.editor.left + 'px;'">
+                    <div class="fclk-planner__editor-head">
+                        <div class="fclk-planner__editor-person">
+                            <div class="fclk-planner__editor-name"><t t-esc="state.editor.employeeName"/></div>
+                            <div class="fclk-planner__editor-day"><t t-esc="state.editor.dayLabel"/></div>
+                        </div>
+                        <div class="fclk-planner__editor-hours">
+                            <span><t t-esc="state.editor.hoursDisplay"/></span>
+                        </div>
+                    </div>
+
+                    <div class="fclk-planner__quick-grid">
+                        <t t-foreach="quickShiftOptions" t-as="option" t-key="option.key">
+                            <button type="button"
+                                    class="fclk-planner__quick-chip"
+                                    t-on-click="() => this.selectQuickShift(option)">
+                                <span class="fclk-planner__quick-label"><t t-esc="option.label"/></span>
+                                <span class="fclk-planner__quick-detail"><t t-esc="option.detail"/></span>
+                            </button>
+                        </t>
+                    </div>
+
+                    <div class="fclk-planner__time-row">
+                        <label class="fclk-planner__time-field">
+                            <span>Start</span>
+                            <select t-on-change="(ev) => this.onEditorStartChange(ev)">
+                                <t t-foreach="timeOptions" t-as="option" t-key="'start_' + option.value">
+                                    <option t-att-value="option.value"
+                                            t-att-selected="option.value === state.editor.startValue">
+                                        <t t-esc="option.label"/>
+                                    </option>
+                                </t>
+                            </select>
+                        </label>
+                        <label class="fclk-planner__time-field">
+                            <span>End</span>
+                            <select t-on-change="(ev) => this.onEditorEndChange(ev)">
+                                <t t-foreach="timeOptions" t-as="option" t-key="'end_' + option.value">
+                                    <option t-att-value="option.value"
+                                            t-att-selected="option.value === state.editor.endValue">
+                                        <t t-esc="option.label"/>
+                                    </option>
+                                </t>
+                            </select>
+                        </label>
+                    </div>
+
+                    <div class="fclk-planner__editor-error" t-if="state.editor.error">
+                        <t t-esc="state.editor.error"/>
+                    </div>
+
+                    <div class="fclk-planner__editor-actions">
+                        <button type="button"
+                                class="btn btn-sm btn-light"
+                                t-on-click="() => this.clearActiveCell()">
+                            <i class="fa fa-eraser me-1"/> Clear
+                        </button>
+                        <button type="button"
+                                class="btn btn-sm btn-primary"
+                                t-on-click="() => this.applyEditorRange(true)">
+                            <i class="fa fa-check me-1"/> Done
+                        </button>
+                    </div>
+                </div>
+            </t>
+        </div>
+    </t>
+
+</templates>

fusion_clock/tests/__init__.py

@@ -2,3 +2,4 @@
 
 from . import test_nfc_models
 from . import test_clock_nfc_kiosk
+from . import test_shift_planner

fusion_clock/tests/test_shift_planner.py

@@ -0,0 +1,254 @@
+# -*- coding: utf-8 -*-
+
+import json
+from datetime import date, timedelta
+
+from psycopg2 import IntegrityError
+
+from odoo import fields
+from odoo.exceptions import ValidationError
+from odoo.tests.common import HttpCase, TransactionCase, tagged
+from odoo.tools.misc import mute_logger
+
+
+@tagged('-at_install', 'post_install', 'fusion_clock')
+class TestShiftPlannerModels(TransactionCase):
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.Schedule = cls.env['fusion.clock.schedule'].sudo()
+        cls.Shift = cls.env['fusion.clock.shift'].sudo()
+        cls.employee = cls.env['hr.employee'].sudo().create({
+            'name': 'Planner Model Employee',
+            'company_id': cls.env.company.id,
+            'x_fclk_enable_clock': True,
+        })
+        cls.default_shift = cls.Shift.create({
+            'name': 'Default Planner Shift',
+            'start_time': 8.0,
+            'end_time': 16.5,
+            'break_minutes': 30,
+            'company_id': cls.env.company.id,
+        })
+        cls.employee.x_fclk_shift_id = cls.default_shift.id
+        cls.schedule_date = date(2026, 1, 5)
+
+    def test_unique_employee_date_schedule(self):
+        self.Schedule.create({
+            'employee_id': self.employee.id,
+            'schedule_date': self.schedule_date,
+            'is_off': True,
+        })
+        with self.assertRaises(IntegrityError), mute_logger('odoo.sql_db'):
+            with self.env.cr.savepoint():
+                self.Schedule.create({
+                    'employee_id': self.employee.id,
+                    'schedule_date': self.schedule_date,
+                    'is_off': True,
+                })
+
+    def test_off_schedule_has_zero_hours(self):
+        schedule = self.Schedule.create({
+            'employee_id': self.employee.id,
+            'schedule_date': date(2026, 1, 6),
+            'is_off': True,
+        })
+        self.assertEqual(schedule.planned_hours, 0)
+        self.assertEqual(schedule.fclk_display_value(), 'OFF')
+
+    def test_working_schedule_computes_hours_minus_break(self):
+        schedule = self.Schedule.create({
+            'employee_id': self.employee.id,
+            'schedule_date': date(2026, 1, 7),
+            'start_time': 9.0,
+            'end_time': 17.5,
+            'break_minutes': 30,
+        })
+        self.assertEqual(schedule.planned_hours, 8.0)
+        self.assertEqual(self.Schedule.fclk_hours_display(schedule.planned_hours), '8:00')
+
+    def test_invalid_same_day_range_is_rejected(self):
+        with self.assertRaises(ValidationError):
+            self.Schedule.create({
+                'employee_id': self.employee.id,
+                'schedule_date': date(2026, 1, 8),
+                'start_time': 17.0,
+                'end_time': 9.0,
+                'break_minutes': 30,
+            })
+
+    def test_apply_planner_cell_creates_audit(self):
+        schedule_date = date(2026, 1, 9)
+        self.Schedule.fclk_apply_planner_cell(
+            self.employee,
+            schedule_date,
+            {'input': '9:00 am - 5:30 pm'},
+            self.env.user,
+        )
+        audit = self.env['fusion.clock.schedule.audit'].sudo().search([
+            ('employee_id', '=', self.employee.id),
+            ('schedule_date', '=', schedule_date),
+        ], limit=1)
+        self.assertTrue(audit)
+        self.assertFalse(audit.old_value)
+        self.assertEqual(audit.new_value, '9:00 am - 5:30 pm')
+
+    def test_dated_schedule_overrides_employee_shift_and_fallback_remains(self):
+        planned_date = date(2026, 1, 12)
+        self.Schedule.create({
+            'employee_id': self.employee.id,
+            'schedule_date': planned_date,
+            'start_time': 10.0,
+            'end_time': 18.0,
+            'break_minutes': 60,
+        })
+
+        planned = self.employee._get_fclk_day_plan(planned_date)
+        fallback = self.employee._get_fclk_day_plan(planned_date + timedelta(days=1))
+
+        self.assertEqual(planned['source'], 'schedule')
+        self.assertEqual(planned['start_time'], 10.0)
+        self.assertEqual(planned['hours'], 7.0)
+        self.assertEqual(fallback['source'], 'fallback')
+        self.assertEqual(fallback['start_time'], 8.0)
+
+
+@tagged('-at_install', 'post_install', 'fusion_clock')
+class TestShiftPlannerApi(HttpCase):
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        manager_group = cls.env.ref('fusion_clock.group_fusion_clock_manager')
+        user_group = cls.env.ref('fusion_clock.group_fusion_clock_user')
+        cls.manager_user = cls.env['res.users'].sudo().create({
+            'name': 'Planner Manager',
+            'login': 'planner-manager',
+            'password': 'plannerpass',
+            'company_id': cls.env.company.id,
+            'company_ids': [(6, 0, [cls.env.company.id])],
+            'group_ids': [(6, 0, [manager_group.id])],
+        })
+        cls.employee_user = cls.env['res.users'].sudo().create({
+            'name': 'Planner Employee User',
+            'login': 'planner-employee-user',
+            'password': 'plannerpass',
+            'company_id': cls.env.company.id,
+            'company_ids': [(6, 0, [cls.env.company.id])],
+            'group_ids': [(6, 0, [user_group.id])],
+            'tz': 'UTC',
+        })
+        cls.employee = cls.env['hr.employee'].sudo().create({
+            'name': 'Planner API Employee',
+            'user_id': cls.employee_user.id,
+            'company_id': cls.env.company.id,
+            'x_fclk_enable_clock': True,
+        })
+        cls.shift = cls.env['fusion.clock.shift'].sudo().create({
+            'name': 'API Morning',
+            'start_time': 7.0,
+            'end_time': 15.5,
+            'break_minutes': 30,
+            'company_id': cls.env.company.id,
+        })
+        cls.week_start = '2026-01-19'
+
+    def _json_call(self, route, payload, login='planner-manager'):
+        self.authenticate(login, 'plannerpass')
+        response = self.url_open(
+            route,
+            data=json.dumps({'jsonrpc': '2.0', 'method': 'call', 'params': payload}),
+            headers={'Content-Type': 'application/json'},
+        )
+        return response.json().get('result', {})
+
+    def test_manager_can_load_save_and_export_planner(self):
+        load_result = self._json_call('/fusion_clock/shift_planner/load', {
+            'week_start': self.week_start,
+        })
+        self.assertIn(self.employee.id, [row['id'] for row in load_result['employees']])
+
+        save_result = self._json_call('/fusion_clock/shift_planner/save', {
+            'week_start': self.week_start,
+            'changes': [{
+                'employee_id': self.employee.id,
+                'date': self.week_start,
+                'input': '9-5',
+                'shift_id': False,
+            }],
+        })
+        self.assertTrue(save_result.get('success'))
+
+        schedule = self.env['fusion.clock.schedule'].sudo().search([
+            ('employee_id', '=', self.employee.id),
+            ('schedule_date', '=', fields.Date.to_date(self.week_start)),
+        ], limit=1)
+        self.assertTrue(schedule)
+        self.assertEqual(schedule.start_time, 9.0)
+        self.assertEqual(schedule.end_time, 17.0)
+
+        export_result = self._json_call('/fusion_clock/shift_planner/export_xlsx', {
+            'week_start': self.week_start,
+        })
+        self.assertTrue(export_result.get('success'))
+        self.assertTrue(export_result.get('url', '').startswith('/web/content/'))
+        self.assertTrue(self.env['ir.attachment'].sudo().browse(export_result['attachment_id']).exists())
+
+    def test_copy_previous_week(self):
+        previous_monday = fields.Date.to_date(self.week_start) - timedelta(days=7)
+        self.env['fusion.clock.schedule'].sudo().create({
+            'employee_id': self.employee.id,
+            'schedule_date': previous_monday,
+            'shift_id': self.shift.id,
+            'start_time': self.shift.start_time,
+            'end_time': self.shift.end_time,
+            'break_minutes': self.shift.break_minutes,
+        })
+        result = self._json_call('/fusion_clock/shift_planner/copy_previous_week', {
+            'week_start': self.week_start,
+        })
+        self.assertTrue(result.get('success'))
+        copied = self.env['fusion.clock.schedule'].sudo().search([
+            ('employee_id', '=', self.employee.id),
+            ('schedule_date', '=', fields.Date.to_date(self.week_start)),
+        ], limit=1)
+        self.assertEqual(copied.shift_id, self.shift)
+
+    def test_non_manager_cannot_mutate_planner(self):
+        result = self._json_call('/fusion_clock/shift_planner/save', {
+            'week_start': self.week_start,
+            'changes': [],
+        }, login='planner-employee-user')
+        self.assertEqual(result.get('error'), 'Access denied.')
+
+    def test_off_day_clock_in_succeeds_and_logs_unscheduled_shift(self):
+        today = fields.Date.today()
+        location = self.env['fusion.clock.location'].sudo().create({
+            'name': 'Planner Test Location',
+            'latitude': 43.65,
+            'longitude': -79.38,
+            'radius': 100,
+            'company_id': self.env.company.id,
+            'all_employees': True,
+        })
+        self.env['fusion.clock.schedule'].sudo().create({
+            'employee_id': self.employee.id,
+            'schedule_date': today,
+            'is_off': True,
+        })
+
+        result = self._json_call('/fusion_clock/clock_action', {
+            'latitude': location.latitude,
+            'longitude': location.longitude,
+            'source': 'portal',
+        }, login='planner-employee-user')
+
+        self.assertTrue(result.get('success'))
+        self.assertEqual(result.get('action'), 'clock_in')
+        self.assertIn('unscheduled', result.get('message', ''))
+        log = self.env['fusion.clock.activity.log'].sudo().search([
+            ('employee_id', '=', self.employee.id),
+            ('log_type', '=', 'unscheduled_shift'),
+        ], limit=1)
+        self.assertTrue(log)

fusion_clock/views/clock_menus.xml

@@ -16,6 +16,34 @@
               sequence="5"
               groups="group_fusion_clock_manager,group_fusion_clock_team_lead"/>
 
+    <!-- Scheduling -->
+    <menuitem id="menu_fusion_clock_scheduling"
+              name="Scheduling"
+              parent="menu_fusion_clock_root"
+              sequence="8"
+              groups="group_fusion_clock_manager"/>
+
+    <menuitem id="menu_fusion_clock_shift_planner"
+              name="Shift Planner"
+              parent="menu_fusion_clock_scheduling"
+              action="action_fusion_clock_shift_planner"
+              sequence="5"
+              groups="group_fusion_clock_manager"/>
+
+    <menuitem id="menu_fusion_clock_scheduled_shifts"
+              name="Scheduled Shifts"
+              parent="menu_fusion_clock_scheduling"
+              action="action_fusion_clock_schedule"
+              sequence="10"
+              groups="group_fusion_clock_manager"/>
+
+    <menuitem id="menu_fusion_clock_schedule_audit"
+              name="Schedule Audit"
+              parent="menu_fusion_clock_scheduling"
+              action="action_fusion_clock_schedule_audit"
+              sequence="20"
+              groups="group_fusion_clock_manager"/>
+
     <!-- Attendance Sub-Menu -->
     <menuitem id="menu_fusion_clock_attendance"
               name="Attendance"

fusion_clock/views/clock_schedule_views.xml

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+
+    <record id="action_fusion_clock_shift_planner" model="ir.actions.client">
+        <field name="name">Shift Planner</field>
+        <field name="tag">fusion_clock.ShiftPlanner</field>
+    </record>
+
+    <record id="view_fusion_clock_schedule_list" model="ir.ui.view">
+        <field name="name">fusion.clock.schedule.list</field>
+        <field name="model">fusion.clock.schedule</field>
+        <field name="arch" type="xml">
+            <list>
+                <field name="schedule_date"/>
+                <field name="employee_id"/>
+                <field name="department_id"/>
+                <field name="is_off"/>
+                <field name="shift_id"/>
+                <field name="start_time" widget="float_time"/>
+                <field name="end_time" widget="float_time"/>
+                <field name="break_minutes"/>
+                <field name="planned_hours"/>
+                <field name="company_id" groups="base.group_multi_company"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_fusion_clock_schedule_form" model="ir.ui.view">
+        <field name="name">fusion.clock.schedule.form</field>
+        <field name="model">fusion.clock.schedule</field>
+        <field name="arch" type="xml">
+            <form>
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="employee_id"/>
+                            <field name="schedule_date"/>
+                            <field name="is_off"/>
+                            <field name="shift_id"/>
+                        </group>
+                        <group>
+                            <field name="start_time" widget="float_time"/>
+                            <field name="end_time" widget="float_time"/>
+                            <field name="break_minutes"/>
+                            <field name="planned_hours" readonly="1"/>
+                        </group>
+                    </group>
+                    <group>
+                        <field name="note"/>
+                        <field name="department_id" readonly="1"/>
+                        <field name="company_id" readonly="1" groups="base.group_multi_company"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="view_fusion_clock_schedule_search" model="ir.ui.view">
+        <field name="name">fusion.clock.schedule.search</field>
+        <field name="model">fusion.clock.schedule</field>
+        <field name="arch" type="xml">
+            <search>
+                <field name="employee_id"/>
+                <field name="department_id"/>
+                <field name="schedule_date"/>
+                <filter name="off" string="OFF" domain="[('is_off', '=', True)]"/>
+                <filter name="working" string="Working" domain="[('is_off', '=', False)]"/>
+                <filter name="group_department" string="Department" context="{'group_by': 'department_id'}"/>
+                <filter name="group_date" string="Date" context="{'group_by': 'schedule_date'}"/>
+            </search>
+        </field>
+    </record>
+
+    <record id="action_fusion_clock_schedule" model="ir.actions.act_window">
+        <field name="name">Scheduled Shifts</field>
+        <field name="res_model">fusion.clock.schedule</field>
+        <field name="view_mode">list,form</field>
+    </record>
+
+    <record id="view_fusion_clock_schedule_audit_list" model="ir.ui.view">
+        <field name="name">fusion.clock.schedule.audit.list</field>
+        <field name="model">fusion.clock.schedule.audit</field>
+        <field name="arch" type="xml">
+            <list create="0" edit="0" delete="0">
+                <field name="changed_at"/>
+                <field name="employee_id"/>
+                <field name="schedule_date"/>
+                <field name="old_value"/>
+                <field name="new_value"/>
+                <field name="changed_by_id"/>
+                <field name="department_id"/>
+                <field name="company_id" groups="base.group_multi_company"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_fusion_clock_schedule_audit_form" model="ir.ui.view">
+        <field name="name">fusion.clock.schedule.audit.form</field>
+        <field name="model">fusion.clock.schedule.audit</field>
+        <field name="arch" type="xml">
+            <form create="0" edit="0" delete="0">
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="changed_at"/>
+                            <field name="changed_by_id"/>
+                            <field name="employee_id"/>
+                            <field name="schedule_date"/>
+                        </group>
+                        <group>
+                            <field name="old_value"/>
+                            <field name="new_value"/>
+                            <field name="department_id"/>
+                            <field name="company_id" groups="base.group_multi_company"/>
+                        </group>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_fusion_clock_schedule_audit" model="ir.actions.act_window">
+        <field name="name">Schedule Audit</field>
+        <field name="res_model">fusion.clock.schedule.audit</field>
+        <field name="view_mode">list,form</field>
+    </record>
+
+</odoo>

fusion_clock/views/portal_clock_templates.xml

@@ -142,6 +142,28 @@
                         </div>
                     </div>
 
+                    <!-- Scheduled Shift -->
+                    <div class="fclk-schedule-card">
+                        <div class="fclk-schedule-icon">
+                            <i class="fa fa-calendar-check-o"/>
+                        </div>
+                        <div class="fclk-schedule-info">
+                            <div class="fclk-schedule-label">Today's Shift</div>
+                            <div class="fclk-schedule-value">
+                                <t t-if="today_schedule.get('is_off')">OFF</t>
+                                <t t-else="">
+                                    <t t-esc="today_schedule.get('label') or 'Not scheduled'"/>
+                                </t>
+                            </div>
+                        </div>
+                        <div class="fclk-schedule-hours">
+                            <t t-if="today_schedule.get('is_off')">0:00</t>
+                            <t t-else="">
+                                <t t-esc="'%.1f' % (today_schedule.get('hours') or 0.0)"/>h
+                            </t>
+                        </div>
+                    </div>
+
                     <!-- Timer Section -->
                     <div class="fclk-timer-section">
                         <div class="fclk-timer-label" id="fclk-timer-label">

fusion_login_audit/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+from . import models

fusion_login_audit/__manifest__.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1 (Odoo Proprietary License v1.0)
+{
+    'name': 'Fusion Login Audit',
+    'version': '19.0.1.0.0',
+    'category': 'Tools',
+    'summary': 'Durable login audit log with geo-enrichment, retention, and failure alerts.',
+    'description': """
+Fusion Login Audit
+==================
+
+Captures every password authentication event (success + failure) in a
+dedicated, append-only audit table. Surfaces history on the user form
+as a smart button + tab (admins only). Async-enriches IPs with country,
+city, and reverse DNS. Emails Settings admins on consecutive-failure
+bursts. Daily retention cron honours a configurable horizon.
+    """,
+    'author': 'Nexa Systems Inc.',
+    'website': 'https://nexasystems.ca',
+    'license': 'OPL-1',
+    'depends': ['base', 'mail', 'base_setup'],
+    'external_dependencies': {
+        'python': ['user_agents'],
+    },
+    'data': [
+        'security/ir.model.access.csv',
+        'security/security.xml',
+        'data/mail_template_data.xml',
+        'data/ir_cron_data.xml',
+        'views/fusion_login_audit_views.xml',
+        'views/res_users_views.xml',
+        'views/res_config_settings_views.xml',
+        'views/menus.xml',
+    ],
+    'installable': True,
+    'application': False,
+    'auto_install': False,
+}

fusion_login_audit/data/ir_cron_data.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+    <data noupdate="1">
+
+        <record id="cron_retention_gc" model="ir.cron">
+            <field name="name">Fusion Login Audit: Retention GC</field>
+            <field name="model_id" ref="model_fusion_login_audit"/>
+            <field name="state">code</field>
+            <field name="code">model._fc_retention_gc()</field>
+            <field name="interval_number">1</field>
+            <field name="interval_type">days</field>
+            <field name="active" eval="True"/>
+        </record>
+
+        <record id="cron_geo_enrich" model="ir.cron">
+            <field name="name">Fusion Login Audit: Geo Enrichment</field>
+            <field name="model_id" ref="model_fusion_login_audit"/>
+            <field name="state">code</field>
+            <field name="code">model._fc_geo_enrich_pending(limit=100)</field>
+            <field name="interval_number">5</field>
+            <field name="interval_type">minutes</field>
+            <field name="active" eval="True"/>
+            <field name="priority">10</field>
+        </record>
+
+    </data>
+</odoo>

fusion_login_audit/data/mail_template_data.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+    <data noupdate="1">
+
+        <record id="mail_template_failure_burst" model="mail.template">
+            <field name="name">Fusion Login Audit — Failure Burst Alert</field>
+            <field name="model_id" ref="base.model_res_users"/>
+            <field name="subject">[Login Audit] Failed login attempts for {{ ctx.get('attempted_login') }}</field>
+            <field name="body_html" type="html">
+<div>
+    <p>The login audit detected
+        <strong t-out="ctx.get('failure_count')"/> failed login attempt(s)
+        in the last <t t-out="ctx.get('window_min')"/> minute(s) for
+        <strong t-out="ctx.get('attempted_login')"/>.</p>
+    <p>Most recent attempts:</p>
+    <table border="1" cellpadding="4" cellspacing="0"
+           style="border-collapse: collapse; font-family: sans-serif; font-size: 12px;">
+        <thead style="background: #f3f4f6;">
+            <tr>
+                <th>Time</th>
+                <th>IP</th>
+                <th>Country</th>
+                <th>Browser</th>
+                <th>OS</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr t-foreach="ctx.get('rows', [])" t-as="row">
+                <td t-out="row['event_time']"/>
+                <td t-out="row['ip_address']"/>
+                <td t-out="row.get('country_code') or ''"/>
+                <td t-out="row.get('browser') or ''"/>
+                <td t-out="row.get('os') or ''"/>
+            </tr>
+        </tbody>
+    </table>
+    <p style="color: #6b7280; font-size: 11px;">
+        Sent by Fusion Login Audit. Tune the threshold and window in
+        Settings → General Settings → Login Audit.
+    </p>
+</div>
+            </field>
+        </record>
+
+    </data>
+</odoo>

fusion_login_audit/models/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from . import fusion_login_audit
+from . import res_users
+from . import res_config_settings

fusion_login_audit/models/fusion_login_audit.py

@@ -0,0 +1,256 @@
+# -*- coding: utf-8 -*-
+import ipaddress
+import logging
+import socket
+from datetime import timedelta
+
+import requests
+
+from odoo import api, fields, models
+
+_logger = logging.getLogger(__name__)
+
+
+class FusionLoginAudit(models.Model):
+    _name = 'fusion.login.audit'
+    _description = 'Login Audit Event'
+    _order = 'event_time desc, id desc'
+    _rec_name = 'attempted_login'
+
+    user_id = fields.Many2one(
+        'res.users', string='User', ondelete='set null', index=True,
+        help='Null when the attempted login did not match any user.',
+    )
+    attempted_login = fields.Char(
+        string='Attempted Login', size=255, required=True, index=True,
+    )
+    result = fields.Selection(
+        [('success', 'Success'), ('failure', 'Failure')],
+        string='Result', required=True, index=True,
+    )
+    failure_reason = fields.Selection(
+        [
+            ('bad_password', 'Bad password'),
+            ('unknown_user', 'Unknown user'),
+            ('disabled_user', 'Disabled user'),
+            ('2fa_failed', '2FA failed'),
+            ('other', 'Other'),
+        ],
+        string='Failure Reason',
+    )
+    event_time = fields.Datetime(
+        string='Event Time', required=True, index=True,
+        default=fields.Datetime.now,
+    )
+    ip_address = fields.Char(string='IP Address', size=45)
+    ip_hostname = fields.Char(string='Reverse DNS', size=255)
+    country_code = fields.Char(string='Country Code', size=2, index=True)
+    country_name = fields.Char(string='Country', size=64)
+    city = fields.Char(string='City', size=128)
+    geo_state = fields.Char(string='Region', size=64)
+    geo_lookup_state = fields.Selection(
+        [
+            ('pending', 'Pending'),
+            ('done', 'Done'),
+            ('private_ip', 'Private IP'),
+            ('internal', 'Internal (no request)'),
+            ('failed', 'Lookup failed'),
+        ],
+        string='Geo Lookup State', default='pending', index=True,
+    )
+    user_agent_raw = fields.Char(string='User Agent', size=512)
+    browser = fields.Char(string='Browser', size=64)
+    os = fields.Char(string='OS', size=64)
+    device_type = fields.Selection(
+        [
+            ('desktop', 'Desktop'),
+            ('mobile', 'Mobile'),
+            ('tablet', 'Tablet'),
+            ('bot', 'Bot'),
+            ('unknown', 'Unknown'),
+        ],
+        string='Device Type', default='unknown',
+    )
+    database = fields.Char(string='Database', size=64)
+
+    # Odoo 19 replaces the legacy `_sql_constraints = [...]` list with
+    # declarative `models.Constraint` attributes. The plan template used the
+    # legacy form, which now only emits a warning and is silently dropped.
+    _result_failure_reason_consistent = models.Constraint(
+        "CHECK ((result = 'success' AND failure_reason IS NULL) "
+        "OR (result = 'failure' AND failure_reason IS NOT NULL))",
+        'A failure row must have a failure_reason; a success row must not.',
+    )
+
+    # Composite indexes supporting the three hot queries:
+    #   - per-user history       (user_id, event_time DESC)
+    #   - failure-burst by login (attempted_login, event_time DESC)
+    #   - geo cron worklist      (geo_lookup_state, event_time)
+    # Odoo 19 ships `models.Index` as the declarative replacement for the
+    # init()/raw-SQL pattern; the attribute name becomes the index suffix
+    # (e.g. `_user_time_idx` -> `fusion_login_audit_user_time_idx`).
+    _user_time_idx = models.Index('(user_id, event_time DESC)')
+    _login_time_idx = models.Index('(attempted_login, event_time DESC)')
+    _geo_state_idx = models.Index('(geo_lookup_state, event_time)')
+
+    @api.model
+    def _fc_retention_gc(self):
+        """Delete audit rows older than `fusion_login_audit.retention_days`.
+        Called daily by ir.cron. retention_days=0 means keep forever."""
+        ICP = self.env['ir.config_parameter'].sudo()
+        try:
+            days = int(ICP.get_param(
+                'fusion_login_audit.retention_days', 365))
+        except (TypeError, ValueError):
+            days = 365
+        if days <= 0:
+            return 0
+        cutoff = fields.Datetime.now() - timedelta(days=days)
+        old = self.sudo().search([('event_time', '<', cutoff)])
+        count = len(old)
+        if old:
+            old.unlink()
+        return count
+
+    _FC_PRIVATE_NETWORKS = (
+        ipaddress.ip_network('10.0.0.0/8'),
+        ipaddress.ip_network('172.16.0.0/12'),
+        ipaddress.ip_network('192.168.0.0/16'),
+        ipaddress.ip_network('127.0.0.0/8'),
+        ipaddress.ip_network('::1/128'),
+        ipaddress.ip_network('fe80::/10'),
+    )
+
+    @api.model
+    def _fc_is_private_ip(self, ip):
+        if not ip or ip == 'internal':
+            return False  # 'internal' uses its own state
+        try:
+            addr = ipaddress.ip_address(ip)
+        except ValueError:
+            return False
+        return any(addr in net for net in self._FC_PRIVATE_NETWORKS)
+
+    @api.model
+    def _fc_geo_cache_hit(self, ip):
+        """Return a dict of geo fields if we've resolved this IP in the last
+        30 days, else None."""
+        if not ip:
+            return None
+        cutoff = fields.Datetime.now() - timedelta(days=30)
+        cached = self.sudo().search([
+            ('ip_address', '=', ip),
+            ('geo_lookup_state', '=', 'done'),
+            ('event_time', '>=', cutoff),
+        ], limit=1, order='event_time desc')
+        if not cached:
+            return None
+        return {
+            'country_code': cached.country_code,
+            'country_name': cached.country_name,
+            'city': cached.city,
+            'geo_state': cached.geo_state,
+            'ip_hostname': cached.ip_hostname,
+        }
+
+    @api.model
+    def _fc_geo_reverse_dns(self, ip):
+        try:
+            socket.setdefaulttimeout(1.5)
+            host, _aliases, _ips = socket.gethostbyaddr(ip)
+            return (host or '')[:255]
+        except (socket.herror, socket.gaierror, OSError):
+            return ''
+        finally:
+            socket.setdefaulttimeout(None)
+
+    @api.model
+    def _fc_geo_http_lookup(self, ip):
+        """Call ip-api.com. Returns (vals_dict, rate_limited_bool).
+        Falls back to ({}, False) on any error."""
+        try:
+            resp = requests.get(
+                'http://ip-api.com/json/' + ip,
+                params={'fields': 'status,country,countryCode,regionName,city'},
+                timeout=3,
+                headers={'User-Agent': 'Odoo-FusionLoginAudit/19.0'},
+            )
+            rate_limited = resp.headers.get('X-Rl', '') == '0'
+            if resp.status_code != 200:
+                return ({}, rate_limited)
+            data = resp.json() or {}
+            if data.get('status') != 'success':
+                return ({}, rate_limited)
+            return ({
+                'country_code': (data.get('countryCode') or '')[:2],
+                'country_name': (data.get('country') or '')[:64],
+                'geo_state': (data.get('regionName') or '')[:64],
+                'city': (data.get('city') or '')[:128],
+            }, rate_limited)
+        except (requests.RequestException, ValueError):
+            _logger.warning("fusion_login_audit: geo lookup failed for %s",
+                            ip, exc_info=True)
+            return ({}, False)
+
+    @api.model
+    def _fc_geo_enrich_pending(self, limit=100):
+        """Cron worker: process up to `limit` pending rows.
+
+        Per-row isolation is provided by `cr.savepoint()` rather than
+        `cr.commit()`/`cr.rollback()` — the latter raises an AssertionError
+        inside a TransactionCase (Odoo's test cursor refuses commit/rollback).
+        Savepoints work in both prod and tests; the outer cron transaction
+        commits the lot once the method returns. One bad IP rolls back only
+        its own savepoint, so the rest of the batch still lands.
+        """
+        pending = self.sudo().search(
+            [('geo_lookup_state', '=', 'pending')],
+            order='event_time asc', limit=limit,
+        )
+        if not pending:
+            return 0
+        processed = 0
+        stop_after_this = False
+        for row in pending:
+            ip = row.ip_address
+            try:
+                with self.env.cr.savepoint():
+                    if self._fc_is_private_ip(ip):
+                        row.write({
+                            'geo_lookup_state': 'private_ip',
+                            'country_code': '--',
+                            'country_name': 'Private network',
+                            'city': 'Private network',
+                        })
+                        processed += 1
+                        continue
+
+                    cached = self._fc_geo_cache_hit(ip)
+                    if cached:
+                        cached['geo_lookup_state'] = 'done'
+                        row.write(cached)
+                        processed += 1
+                        continue
+
+                    hostname = self._fc_geo_reverse_dns(ip) if ip and ip != 'internal' else ''
+                    vals, rate_limited = self._fc_geo_http_lookup(ip) if ip and ip != 'internal' else ({}, False)
+                    if vals:
+                        vals['ip_hostname'] = hostname
+                        vals['geo_lookup_state'] = 'done'
+                        row.write(vals)
+                    else:
+                        row.write({
+                            'geo_lookup_state': 'failed',
+                            'ip_hostname': hostname,
+                        })
+                    processed += 1
+                    if rate_limited:
+                        _logger.info("fusion_login_audit: ip-api rate limit "
+                                     "hit, stopping batch early")
+                        stop_after_this = True
+            except Exception:
+                _logger.exception(
+                    "fusion_login_audit: geo enrich failed for row %s", row.id)
+            if stop_after_this:
+                break
+        return processed

fusion_login_audit/models/res_config_settings.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+from odoo import fields, models
+
+
+class ResConfigSettings(models.TransientModel):
+    _inherit = 'res.config.settings'
+
+    x_fc_login_audit_retention_days = fields.Integer(
+        string='Login Audit Retention (days)',
+        default=365,
+        config_parameter='fusion_login_audit.retention_days',
+        help='Login audit rows older than this are deleted by the nightly '
+             'cron. Set to 0 to keep forever.',
+    )
+    x_fc_login_audit_alert_threshold = fields.Integer(
+        string='Alert After N Consecutive Failures',
+        default=5,
+        config_parameter='fusion_login_audit.alert_threshold',
+        help='When this many failures for the same attempted login occur '
+             'within the alert window, Settings admins receive one email.',
+    )
+    x_fc_login_audit_alert_window_min = fields.Integer(
+        string='Alert Window (minutes)',
+        default=15,
+        config_parameter='fusion_login_audit.alert_window_min',
+    )
+    x_fc_login_audit_alert_enabled = fields.Boolean(
+        string='Send Failed-Login Alerts',
+        default=True,
+        config_parameter='fusion_login_audit.alert_enabled',
+    )

fusion_login_audit/models/res_users.py

@@ -0,0 +1,392 @@
+# -*- coding: utf-8 -*-
+import logging
+
+from odoo import _, api, fields, models
+from odoo.exceptions import AccessDenied
+
+# Top-level import (vs lazy inside the method): if the dep is missing — most
+# likely because the dev container got recreated and dropped its pip install
+# (see CLAUDE.md Workflow) — Odoo crashes at registry load with a clear
+# `ModuleNotFoundError`, not deep in the auth path after the first login.
+from user_agents import parse as ua_parse
+
+_logger = logging.getLogger(__name__)
+
+
+class ResUsers(models.Model):
+    _inherit = 'res.users'
+
+    @api.model
+    def _fc_build_event_vals(
+        self,
+        result,
+        attempted_login,
+        failure_reason=None,
+        user_id=None,
+        _override_ip=None,
+        _override_ua=None,
+        _credential=None,
+    ):
+        """Build the dict of values for a fusion.login.audit row.
+
+        Pulls IP / User-Agent from the live HTTP request when available.
+        Falls back to ('internal', '<no-request>') for XML-RPC / cron-initiated
+        auth, with geo_lookup_state='internal' so the geo cron skips them.
+
+        An empty IP from an otherwise-live request (rare; misconfigured
+        reverse proxy) also routes to the 'internal' fallback — an empty
+        string isn't useful audit data and is arguably suspicious.
+
+        The _override_* kwargs exist for tests so we don't have to fake a
+        full request. They are NOT a public API.
+
+        Password safety: `_credential` MAY contain a 'password' key from the
+        Odoo auth flow. We never read that key, never log it, never put it
+        in vals. The test `test_build_event_vals_strips_password` locks
+        this property in via `assertNotIn(secret, repr(vals))`.
+        """
+        vals = {
+            'attempted_login': (attempted_login or '')[:255],
+            'result': result,
+            'failure_reason': failure_reason,
+            'event_time': fields.Datetime.now(),
+            'database': self.env.cr.dbname,
+            'user_id': user_id,
+        }
+
+        ip = _override_ip
+        ua_str = _override_ua
+
+        if ip is None or ua_str is None:
+            try:
+                from odoo.http import request
+                if request and getattr(request, 'httprequest', None):
+                    if ip is None:
+                        ip = request.httprequest.remote_addr
+                    if ua_str is None:
+                        ua_str = request.httprequest.user_agent.string or ''
+            except Exception:
+                _logger.debug("fusion_login_audit: no request context", exc_info=True)
+
+        if ip and ua_str is not None:
+            ua_text = ua_str or ''
+            vals['ip_address'] = ip[:45]
+            vals['user_agent_raw'] = ua_text[:512]
+            ua = ua_parse(ua_text)
+            vals['browser'] = (f"{ua.browser.family} {ua.browser.version_string}".strip())[:64]
+            vals['os'] = (f"{ua.os.family} {ua.os.version_string}".strip())[:64]
+            if ua.is_bot:
+                vals['device_type'] = 'bot'
+            elif ua.is_mobile:
+                vals['device_type'] = 'mobile'
+            elif ua.is_tablet:
+                vals['device_type'] = 'tablet'
+            elif ua.is_pc:
+                vals['device_type'] = 'desktop'
+            else:
+                vals['device_type'] = 'unknown'
+            vals['geo_lookup_state'] = 'pending'
+        else:
+            vals['ip_address'] = 'internal'
+            vals['user_agent_raw'] = '<no-request>'
+            vals['device_type'] = 'unknown'
+            vals['geo_lookup_state'] = 'internal'
+
+        # _credential is accepted in the signature so callers (T6 _check_credentials,
+        # T7 _login) can hand the dict in without filtering. The helper deliberately
+        # touches NO keys from it — see the password-safety note in the docstring.
+        # `_credential` is intentionally unread here; the parameter exists so future
+        # work can read `credential.get('type')` for `2fa_failed` discrimination
+        # only via the explicit failure_reason kwarg, never from the dict directly.
+        del _credential  # explicit no-op — locks down the read surface
+
+        return vals
+
+    def _fc_record_login_event(self, result, failure_reason=None,
+                                user_id=None, attempted_login=None,
+                                _credential=None):
+        """Build vals + create the audit row via sudo. Never raises.
+
+        The row is written through an INDEPENDENT cursor
+        (``registry.cursor()``) so that:
+
+        * A failure-path call from ``_check_credentials`` survives the
+          outer transaction rollback that follows ``AccessDenied``
+          (the HTTP layer closes the cursor without committing, see
+          ``odoo/service/model.py:retrying``).
+        * A broken audit table can never block a real user from logging
+          in: the cursor block is wrapped in try/except; exceptions are
+          logged and swallowed.
+
+        The independent cursor commits on context exit. Note that this
+        means the row is durable even if the caller's transaction later
+        rolls back — intentional for audit semantics: a recorded bad
+        password should NOT disappear because some unrelated downstream
+        op blew up.
+        """
+        try:
+            vals = self._fc_build_event_vals(
+                result=result,
+                attempted_login=attempted_login
+                                or (self.login if self else None)
+                                or 'unknown',
+                failure_reason=failure_reason,
+                user_id=user_id or (self.id if self else None),
+                _credential=_credential,
+            )
+            with self.env.registry.cursor() as audit_cr:
+                audit_env = api.Environment(audit_cr, self.env.uid, self.env.context)
+                audit_env['fusion.login.audit'].sudo().with_context(
+                    mail_create_nolog=True
+                ).create(vals)
+        except Exception:
+            _logger.exception(
+                "fusion_login_audit: failed to record %s row for %s",
+                result, attempted_login or (self.login if self else 'unknown'),
+            )
+
+    def _update_last_login(self):
+        result = super()._update_last_login()
+        # Self is the singleton recordset of the user that just logged in.
+        self._fc_record_login_event(result='success')
+        return result
+
+    def _fc_alert_threshold(self):
+        ICP = self.env['ir.config_parameter'].sudo()
+        try:
+            return max(1, int(ICP.get_param(
+                'fusion_login_audit.alert_threshold', 5)))
+        except (TypeError, ValueError):
+            return 5
+
+    def _fc_alert_window_min(self):
+        ICP = self.env['ir.config_parameter'].sudo()
+        try:
+            return max(1, int(ICP.get_param(
+                'fusion_login_audit.alert_window_min', 15)))
+        except (TypeError, ValueError):
+            return 15
+
+    def _fc_alert_enabled(self):
+        ICP = self.env['ir.config_parameter'].sudo()
+        # CLAUDE.md rule #5: Boolean config_parameter deletes on False.
+        # An absent key means True (the default). Explicit 'False' or 'false'
+        # means disabled.
+        raw = ICP.get_param('fusion_login_audit.alert_enabled', 'True')
+        return str(raw).strip().lower() != 'false'
+
+    def _fc_recent_failure_count(self, attempted_login):
+        """Failures for this attempted_login within the alert window."""
+        from datetime import timedelta
+        if not attempted_login:
+            return 0
+        cutoff = fields.Datetime.now() - timedelta(
+            minutes=self._fc_alert_window_min())
+        return self.env['fusion.login.audit'].sudo().search_count([
+            ('attempted_login', '=', attempted_login),
+            ('result', '=', 'failure'),
+            ('event_time', '>=', cutoff),
+        ])
+
+    def _fc_send_failure_alert(self, attempted_login):
+        """Queue one alert mail unless cooldown is active. Cooldown is
+        60 minutes, keyed by attempted_login, stored in ir.config_parameter."""
+        from datetime import timedelta
+        if not self._fc_alert_enabled():
+            return
+        if not attempted_login:
+            return
+        ICP = self.env['ir.config_parameter'].sudo()
+        cd_key = f'fusion_login_audit.last_alert:{attempted_login}'
+        cd_raw = ICP.get_param(cd_key)
+        now = fields.Datetime.now()
+        if cd_raw:
+            try:
+                last = fields.Datetime.from_string(cd_raw)
+                if last and (now - last) < timedelta(minutes=60):
+                    return  # cooldown active
+            except (TypeError, ValueError):
+                pass
+
+        window = self._fc_alert_window_min()
+        cutoff = now - timedelta(minutes=window)
+        Audit = self.env['fusion.login.audit'].sudo()
+        rows = Audit.search([
+            ('attempted_login', '=', attempted_login),
+            ('result', '=', 'failure'),
+            ('event_time', '>=', cutoff),
+        ], order='event_time desc', limit=20)
+
+        # Admin recipients: members of base.group_system (the Settings group)
+        # who have an email set and are not portal/share users. Note:
+        # CLAUDE.md rule #6 — res.groups has no `users` field in Odoo 19, so
+        # search res.users by group_ids directly. The __system__ superuser
+        # (uid=1) is excluded automatically by Odoo's default user filter.
+        admins = self.env['res.users'].sudo().search([
+            ('group_ids', 'in', self.env.ref('base.group_system').id),
+            ('email', '!=', False),
+            ('share', '=', False),
+        ])
+        if not admins:
+            return
+
+        tmpl = self.env.ref(
+            'fusion_login_audit.mail_template_failure_burst',
+            raise_if_not_found=False)
+        if not tmpl:
+            return
+
+        # CLAUDE.md rule #12: in mail.template QWeb, `ctx` IS env.context.
+        # So `ctx.get('foo')` resolves to env.context.get('foo'). Pass data
+        # by SPREADING keys into the context, not wrapping in a dict.
+        # `with_context(ctx=ctx_data)` would silently render an empty subject.
+        ctx_data = {
+            'attempted_login': attempted_login,
+            'failure_count': len(rows),
+            'window_min': window,
+            'rows': [{
+                'event_time': fields.Datetime.to_string(r.event_time),
+                'ip_address': r.ip_address or '',
+                'country_code': r.country_code or '',
+                'browser': r.browser or '',
+                'os': r.os or '',
+            } for r in rows],
+        }
+        for admin in admins:
+            tmpl.with_context(**ctx_data).send_mail(
+                admin.id,
+                email_values={'email_to': admin.email,
+                              'auto_delete': True},
+                force_send=False,
+            )
+        ICP.set_param(cd_key, fields.Datetime.to_string(now))
+
+    def _check_credentials(self, credential, env):
+        try:
+            return super()._check_credentials(credential, env)
+        except AccessDenied:
+            cred_type = (credential or {}).get('type', 'password')
+            reason = '2fa_failed' if cred_type == 'totp' else 'bad_password'
+            attempted_login = (credential or {}).get('login') or self.login
+            self._fc_record_login_event(
+                result='failure',
+                failure_reason=reason,
+                user_id=self.id,
+                attempted_login=attempted_login,
+                _credential=credential,
+            )
+            try:
+                if self._fc_recent_failure_count(attempted_login) \
+                        >= self._fc_alert_threshold():
+                    self._fc_send_failure_alert(attempted_login)
+            except Exception:
+                _logger.exception(
+                    "fusion_login_audit: failed to send failure alert")
+            raise
+
+    def _login(self, credential, user_agent_env):
+        """Catch the unknown-user branch of upstream _login.
+
+        In Odoo 19 ``_login`` is an *instance* method (not a classmethod as in
+        earlier versions). Upstream raises ``AccessDenied`` in three cases:
+
+        1. Unknown login string — ``_assert_can_auth`` or the user-lookup
+           ``search()`` returns empty → ``_check_credentials`` never fires →
+           THIS override is the only chance to record the attempt.
+        2. Wrong password — user exists, ``_check_credentials`` raises →
+           our ``_check_credentials`` override already wrote a ``bad_password``
+           row → re-raise propagates up to here. We MUST NOT write a second
+           row.
+        3. 2FA failure — same as #2 but ``failure_reason='2fa_failed'``.
+
+        We distinguish #1 from #2/#3 by checking whether the login string
+        resolves to any user. If it does, ``_check_credentials`` ran (and
+        already logged); if it doesn't, the user lookup failed and we log
+        ``unknown_user`` here.
+
+        ``_fc_record_login_event`` writes through an INDEPENDENT cursor
+        (``self.env.registry.cursor()``), so the audit row survives the
+        outer transaction rollback that follows the re-raised
+        ``AccessDenied``. Audit-side exceptions never block the re-raise.
+        """
+        try:
+            return super()._login(credential, user_agent_env)
+        except AccessDenied:
+            login = (credential or {}).get('login') or ''
+            try:
+                user_exists = bool(self.sudo().search(
+                    [('login', '=', login)], limit=1))
+            except Exception:
+                user_exists = False  # be permissive — log the row anyway
+            if not user_exists:
+                self._fc_record_login_event(
+                    result='failure',
+                    failure_reason='unknown_user',
+                    user_id=False,
+                    attempted_login=login or 'unknown',
+                    _credential=credential,
+                )
+            raise
+
+    # ──────────────────────────────────────────────────────────────────
+    # Per-user surface — fields + action method backing the smart button
+    # and "Login Activity" tab on the user form view.
+    # ──────────────────────────────────────────────────────────────────
+
+    x_fc_login_audit_ids = fields.One2many(
+        'fusion.login.audit', 'user_id',
+        string='Login Activity',
+    )
+    x_fc_login_audit_count = fields.Integer(
+        string='Login Audit Count',
+        compute='_compute_x_fc_login_audit_count',
+    )
+    x_fc_last_successful_login = fields.Datetime(
+        string='Last Successful Login',
+        compute='_compute_x_fc_last_successful_login',
+        store=True,
+    )
+    x_fc_last_login_ip = fields.Char(
+        string='Last Login IP', size=45,
+        compute='_compute_x_fc_last_successful_login',
+        store=True,
+    )
+
+    @api.depends('x_fc_login_audit_ids')
+    def _compute_x_fc_login_audit_count(self):
+        # Odoo 19: read_group → _read_group, returns list of tuples
+        # (group_key, aggregate_value) when given groupby + aggregates.
+        Audit = self.env['fusion.login.audit'].sudo()
+        rows = Audit._read_group(
+            domain=[('user_id', 'in', self.ids)],
+            groupby=['user_id'],
+            aggregates=['__count'],
+        )
+        counts = {user.id: count for user, count in rows}
+        for user in self:
+            user.x_fc_login_audit_count = counts.get(user.id, 0)
+
+    @api.depends('x_fc_login_audit_ids.event_time',
+                 'x_fc_login_audit_ids.result',
+                 'x_fc_login_audit_ids.ip_address')
+    def _compute_x_fc_last_successful_login(self):
+        Audit = self.env['fusion.login.audit'].sudo()
+        for user in self:
+            row = Audit.search(
+                [('user_id', '=', user.id), ('result', '=', 'success')],
+                order='event_time desc', limit=1,
+            )
+            user.x_fc_last_successful_login = row.event_time or False
+            user.x_fc_last_login_ip = row.ip_address or False
+
+    def action_fc_view_login_audit(self):
+        self.ensure_one()
+        return {
+            'name': _('Login Activity'),
+            'type': 'ir.actions.act_window',
+            'res_model': 'fusion.login.audit',
+            'view_mode': 'list,form',
+            'domain': [('user_id', '=', self.id)],
+            'context': {'create': False, 'edit': False, 'delete': False,
+                        'default_user_id': self.id},
+        }

fusion_login_audit/security/ir.model.access.csv

@@ -0,0 +1,2 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_fusion_login_audit_system,fusion.login.audit system,model_fusion_login_audit,base.group_system,1,0,0,0

fusion_login_audit/security/security.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+    <data noupdate="1">
+
+        <record id="rule_fusion_login_audit_admin_read" model="ir.rule">
+            <field name="name">fusion.login.audit: admin read only</field>
+            <field name="model_id" ref="model_fusion_login_audit"/>
+            <field name="domain_force">[(1, '=', 1)]</field>
+            <field name="groups" eval="[(4, ref('base.group_system'))]"/>
+            <field name="perm_read" eval="True"/>
+            <field name="perm_write" eval="False"/>
+            <field name="perm_create" eval="False"/>
+            <field name="perm_unlink" eval="False"/>
+        </record>
+
+    </data>
+</odoo>

fusion_login_audit/tests/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+from . import test_login_audit
+from . import test_security

fusion_login_audit/tests/test_login_audit.py

@@ -0,0 +1,541 @@
+# -*- coding: utf-8 -*-
+from odoo import fields
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestFusionLoginAuditModel(TransactionCase):
+
+    def setUp(self):
+        # `_fc_record_login_event` uses `registry.cursor()` so that the audit
+        # row survives the outer rollback that follows AccessDenied (see
+        # res_users.py for the rationale). Inside a TransactionCase that
+        # rolls back per test, a fresh cursor on a new connection cannot
+        # see uncommitted records (the freshly-created test user FKs into
+        # the audit row), so we put the registry in test mode — that swaps
+        # `registry.cursor()` for a TestCursor that wraps the test cursor.
+        super().setUp()
+        self.registry_enter_test_mode()
+        # The alert tests below assume at least one admin has an email
+        # (otherwise the recipient filter empties and no mail is queued).
+        # In a fresh fusion-dev DB, base.user_admin's email is NULL; the
+        # superuser (__system__) has an email but is filtered out of normal
+        # res.users searches. Ensure admin has a usable email.
+        admin = self.env.ref('base.user_admin')
+        if not admin.email:
+            admin.sudo().write({'email': 'admin@test.example.com'})
+
+    def test_model_exists_and_creates(self):
+        """Audit row can be created with all expected fields."""
+        Audit = self.env['fusion.login.audit'].sudo()
+        rec = Audit.create({
+            'attempted_login': 'demo@example.com',
+            'result': 'success',
+            'ip_address': '203.0.113.5',
+            'user_agent_raw': 'Mozilla/5.0 Test',
+            'browser': 'Test 1.0',
+            'os': 'TestOS',
+            'device_type': 'desktop',
+            'database': self.env.cr.dbname,
+            'geo_lookup_state': 'pending',
+        })
+        self.assertTrue(rec.id)
+        self.assertEqual(rec.result, 'success')
+        self.assertEqual(rec.geo_lookup_state, 'pending')
+        self.assertEqual(rec.database, self.env.cr.dbname)
+        self.assertTrue(rec.event_time)  # default fires
+
+    def test_failure_reason_optional(self):
+        """failure_reason is null on success rows."""
+        rec = self.env['fusion.login.audit'].sudo().create({
+            'attempted_login': 'demo@example.com',
+            'result': 'success',
+        })
+        self.assertFalse(rec.failure_reason)
+
+    def test_geo_state_internal_value(self):
+        """`internal` is an accepted geo_lookup_state value (distinct from private_ip)."""
+        rec = self.env['fusion.login.audit'].sudo().create({
+            'attempted_login': 'demo@example.com',
+            'result': 'success',
+            'geo_lookup_state': 'internal',
+        })
+        self.assertEqual(rec.geo_lookup_state, 'internal')
+
+    def test_build_event_vals_with_no_request(self):
+        """Without a live request, geo_lookup_state is 'internal'."""
+        ResUsers = self.env['res.users']
+        vals = ResUsers._fc_build_event_vals(
+            result='success',
+            attempted_login='cron@example.com',
+        )
+        self.assertEqual(vals['result'], 'success')
+        self.assertEqual(vals['attempted_login'], 'cron@example.com')
+        self.assertEqual(vals['ip_address'], 'internal')
+        self.assertEqual(vals['user_agent_raw'], '<no-request>')
+        self.assertEqual(vals['geo_lookup_state'], 'internal')
+        self.assertEqual(vals['database'], self.env.cr.dbname)
+
+    def test_build_event_vals_parses_user_agent(self):
+        """Parser fills browser/os/device_type from a stub UA dict."""
+        ResUsers = self.env['res.users']
+        vals = ResUsers._fc_build_event_vals(
+            result='success',
+            attempted_login='ua@example.com',
+            _override_ip='203.0.113.5',
+            _override_ua='Mozilla/5.0 (Windows NT 10.0; Win64; x64) '
+                         'AppleWebKit/537.36 Chrome/140.0 Safari/537.36',
+        )
+        self.assertEqual(vals['ip_address'], '203.0.113.5')
+        self.assertIn('Chrome', vals['browser'])
+        self.assertIn('Windows', vals['os'])
+        self.assertEqual(vals['device_type'], 'desktop')
+        self.assertEqual(vals['geo_lookup_state'], 'pending')
+
+    def test_build_event_vals_strips_password(self):
+        """If a credential dict sneaks in, no password leaks into vals."""
+        ResUsers = self.env['res.users']
+        vals = ResUsers._fc_build_event_vals(
+            result='failure',
+            attempted_login='leak@example.com',
+            failure_reason='bad_password',
+            _credential={'login': 'leak@example.com',
+                         'password': 'super-secret-pw',
+                         'type': 'password'},
+        )
+        serialized = repr(vals)
+        self.assertNotIn('super-secret-pw', serialized)
+        self.assertEqual(vals['failure_reason'], 'bad_password')
+
+    def test_update_last_login_writes_audit_row(self):
+        """Calling _update_last_login on a user creates a success row."""
+        user = self.env['res.users'].sudo().create({
+            'name': 'Audit Tester',
+            'login': 'audit-tester@example.com',
+            'password': 'audit-tester-pw-1',
+        })
+        Audit = self.env['fusion.login.audit'].sudo()
+        before = Audit.search_count([('user_id', '=', user.id)])
+        user._update_last_login()
+        after = Audit.search_count([('user_id', '=', user.id)])
+        self.assertEqual(after, before + 1)
+        row = Audit.search([('user_id', '=', user.id)],
+                           order='event_time desc', limit=1)
+        self.assertEqual(row.result, 'success')
+        self.assertEqual(row.attempted_login, user.login)
+        self.assertFalse(row.failure_reason)
+        self.assertEqual(row.database, self.env.cr.dbname)
+
+    def test_audit_write_failure_does_not_block_login(self):
+        """An exception inside the audit write must not propagate."""
+        from unittest.mock import patch
+        user = self.env['res.users'].sudo().create({
+            'name': 'Resilient Tester',
+            'login': 'resilient-tester@example.com',
+            'password': 'resilient-tester-pw-1',
+        })
+
+        def boom(self_, vals):
+            raise RuntimeError('simulated audit DB failure')
+
+        with patch.object(type(self.env['fusion.login.audit']),
+                          'create', boom):
+            # Must not raise.
+            user._update_last_login()
+
+    def test_bad_password_writes_failure_row(self):
+        """A wrong password creates a result=failure row with failure_reason='bad_password'."""
+        from odoo.exceptions import AccessDenied
+        user = self.env['res.users'].sudo().create({
+            'name': 'Wrongpw Tester',
+            'login': 'wrongpw-tester@example.com',
+            'password': 'wrongpw-tester-pw-1',
+        })
+        Audit = self.env['fusion.login.audit'].sudo()
+        before = Audit.search_count([('attempted_login', '=', user.login),
+                                     ('result', '=', 'failure')])
+        # NB: cannot use `self.assertRaises(AccessDenied)` — it opens an extra
+        # savepoint (see odoo/tests/common.py::_assertRaises) that rolls back
+        # the audit row written from inside the override.
+        raised = False
+        try:
+            user._check_credentials(
+                {'login': user.login, 'password': 'definitely-wrong',
+                 'type': 'password'},
+                {'interactive': False},
+            )
+        except AccessDenied:
+            raised = True
+        self.assertTrue(raised, "AccessDenied not raised on wrong password")
+        after = Audit.search_count([('attempted_login', '=', user.login),
+                                    ('result', '=', 'failure')])
+        self.assertEqual(after, before + 1)
+        row = Audit.search([('attempted_login', '=', user.login),
+                            ('result', '=', 'failure')],
+                           order='event_time desc', limit=1)
+        self.assertEqual(row.failure_reason, 'bad_password')
+        self.assertEqual(row.user_id, user)
+
+    def test_bad_password_never_appears_in_row(self):
+        """The attempted password string never lands in any field."""
+        from odoo.exceptions import AccessDenied
+        secret = 'NeverInTheRow-9f3a82'
+        user = self.env['res.users'].sudo().create({
+            'name': 'Leak Test',
+            'login': 'leak-test-2@example.com',
+            'password': 'leak-test-pw-1',
+        })
+        # NB: manual try/except instead of assertRaises — see note above.
+        raised = False
+        try:
+            user._check_credentials(
+                {'login': user.login, 'password': secret, 'type': 'password'},
+                {'interactive': False},
+            )
+        except AccessDenied:
+            raised = True
+        self.assertTrue(raised, "AccessDenied not raised on wrong password")
+        row = self.env['fusion.login.audit'].sudo().search(
+            [('attempted_login', '=', user.login),
+             ('result', '=', 'failure')],
+            order='event_time desc', limit=1)
+        self.assertTrue(row, "Audit row not created for bad-password attempt")
+        for fname in ('attempted_login', 'failure_reason', 'user_agent_raw',
+                      'browser', 'os', 'ip_address', 'ip_hostname',
+                      'city', 'country_name', 'country_code', 'geo_state',
+                      'database'):
+            self.assertNotIn(secret, (row[fname] or ''),
+                             f"Password leaked into field {fname}")
+
+    def test_unknown_user_writes_failure_row(self):
+        """A login attempt for a username that does not exist gets logged
+        with user_id=NULL and failure_reason='unknown_user'."""
+        from odoo.exceptions import AccessDenied
+        bogus = 'this-user-does-not-exist@example.com'
+        Audit = self.env['fusion.login.audit'].sudo()
+        before = Audit.search_count([('attempted_login', '=', bogus)])
+        # NB: manual try/except instead of assertRaises — see comment in
+        # test_bad_password_writes_failure_row. _login is an instance method
+        # in Odoo 19 (not a classmethod as in earlier versions); we call it
+        # on the empty recordset of res.users, which matches what
+        # authenticate() does internally.
+        raised = False
+        try:
+            self.env['res.users']._login(
+                {'login': bogus, 'password': 'whatever',
+                 'type': 'password'},
+                {'interactive': False},
+            )
+        except AccessDenied:
+            raised = True
+        self.assertTrue(raised, "AccessDenied must propagate after the audit write")
+        after = Audit.search_count([('attempted_login', '=', bogus)])
+        self.assertEqual(after, before + 1)
+        row = Audit.search([('attempted_login', '=', bogus)],
+                           order='event_time desc', limit=1)
+        self.assertFalse(row.user_id)
+        self.assertEqual(row.failure_reason, 'unknown_user')
+        self.assertEqual(row.result, 'failure')
+
+    def test_login_known_user_bad_password_single_row(self):
+        """When _login is the entry point for an existing user with the
+        wrong password, only ONE failure row is written (bad_password from
+        _check_credentials) — NOT two (bad_password + unknown_user). The
+        unknown_user branch must only fire when the login string does not
+        resolve to any user.
+
+        Regression test for the duplicate-row bug discovered during the
+        production deploy smoke on westin-v19: a single failed login for
+        an existing user was creating two audit rows.
+        """
+        from odoo.exceptions import AccessDenied
+        user = self.env['res.users'].sudo().create({
+            'name': 'NoDupTester',
+            'login': 'nodup-tester@example.com',
+            'password': 'nodup-tester-pw-1',
+        })
+        Audit = self.env['fusion.login.audit'].sudo()
+        before = Audit.search_count([('attempted_login', '=', user.login)])
+        raised = False
+        try:
+            self.env['res.users']._login(
+                {'login': user.login, 'password': 'wrong-not-the-real-one',
+                 'type': 'password'},
+                {'interactive': False},
+            )
+        except AccessDenied:
+            raised = True
+        self.assertTrue(raised)
+        after = Audit.search_count([('attempted_login', '=', user.login)])
+        self.assertEqual(after - before, 1,
+                         "Exactly one row per failed login attempt — not two")
+        row = Audit.search([('attempted_login', '=', user.login)],
+                           order='event_time desc', limit=1)
+        self.assertEqual(row.failure_reason, 'bad_password',
+                         "Existing-user failure must record bad_password, "
+                         "not unknown_user (the user IS in the system)")
+
+    def test_computed_last_successful_login(self):
+        """x_fc_last_successful_login reflects the latest success row."""
+        user = self.env['res.users'].sudo().create({
+            'name': 'Compute Tester',
+            'login': 'compute-tester@example.com',
+            'password': 'compute-tester-pw-1',
+        })
+        # Use registry cursor so the audit row survives the transactional
+        # boundary the way the auth-time path does.
+        with self.env.registry.cursor() as audit_cr:
+            from odoo import api
+            audit_env = api.Environment(audit_cr, self.env.uid, self.env.context)
+            audit_env['fusion.login.audit'].sudo().create({
+                'user_id': user.id,
+                'attempted_login': user.login,
+                'result': 'success',
+                'database': self.env.cr.dbname,
+                'ip_address': '198.51.100.42',
+            })
+        user.invalidate_recordset(['x_fc_last_successful_login',
+                                    'x_fc_login_audit_count',
+                                    'x_fc_last_login_ip'])
+        self.assertTrue(user.x_fc_last_successful_login)
+        self.assertGreaterEqual(user.x_fc_login_audit_count, 1)
+        self.assertEqual(user.x_fc_last_login_ip, '198.51.100.42')
+
+    def test_action_view_login_audit_returns_window_action(self):
+        """The smart-button action returns an act_window scoped to this user."""
+        user = self.env['res.users'].sudo().create({
+            'name': 'Action Tester',
+            'login': 'action-tester@example.com',
+            'password': 'action-tester-pw-1',
+        })
+        action = user.action_fc_view_login_audit()
+        self.assertEqual(action['res_model'], 'fusion.login.audit')
+        self.assertEqual(action['type'], 'ir.actions.act_window')
+        # Domain must filter to this user
+        self.assertIn(('user_id', '=', user.id), action['domain'])
+
+    def test_settings_round_trip(self):
+        """Writing settings persists them via ir.config_parameter."""
+        Settings = self.env['res.config.settings'].sudo()
+        Settings.create({
+            'x_fc_login_audit_retention_days': 90,
+            'x_fc_login_audit_alert_threshold': 3,
+            'x_fc_login_audit_alert_window_min': 5,
+            'x_fc_login_audit_alert_enabled': False,
+        }).execute()
+        ICP = self.env['ir.config_parameter'].sudo()
+        self.assertEqual(ICP.get_param('fusion_login_audit.retention_days'), '90')
+        self.assertEqual(ICP.get_param('fusion_login_audit.alert_threshold'), '3')
+        self.assertEqual(ICP.get_param('fusion_login_audit.alert_window_min'), '5')
+        # Odoo's set_param deletes the row when the value is falsy, so a
+        # Boolean field set to False yields get_param() == False (Python
+        # bool, the default), not the string 'False'.
+        self.assertFalse(ICP.get_param('fusion_login_audit.alert_enabled'))
+
+    def test_failure_burst_queues_one_email(self):
+        """N consecutive failures (within window) queue exactly one mail.mail."""
+        from odoo.exceptions import AccessDenied
+        ICP = self.env['ir.config_parameter'].sudo()
+        ICP.set_param('fusion_login_audit.alert_threshold', '3')
+        ICP.set_param('fusion_login_audit.alert_window_min', '15')
+        ICP.set_param('fusion_login_audit.alert_enabled', 'True')
+        # Clear any cooldown leftover from earlier tests.
+        ICP.set_param('fusion_login_audit.last_alert:burst@example.com', '')
+
+        user = self.env['res.users'].sudo().create({
+            'name': 'Burst Tester',
+            'login': 'burst@example.com',
+            'password': 'burst-tester-pw-1',
+        })
+        Mail = self.env['mail.mail'].sudo()
+        before = Mail.search_count([('subject', 'ilike', 'burst@example.com')])
+        for _i in range(3):
+            raised = False
+            try:
+                user._check_credentials(
+                    {'login': user.login, 'password': 'wrong',
+                     'type': 'password'},
+                    {'interactive': False},
+                )
+            except AccessDenied:
+                raised = True
+            self.assertTrue(raised)
+        after = Mail.search_count([('subject', 'ilike', 'burst@example.com')])
+        self.assertEqual(after, before + 1,
+                         "Exactly one alert mail should be queued")
+
+    def test_cooldown_suppresses_second_alert(self):
+        """Failures beyond the threshold within the cooldown queue zero more emails."""
+        from odoo.exceptions import AccessDenied
+        ICP = self.env['ir.config_parameter'].sudo()
+        ICP.set_param('fusion_login_audit.alert_threshold', '3')
+        ICP.set_param('fusion_login_audit.alert_window_min', '15')
+        ICP.set_param('fusion_login_audit.alert_enabled', 'True')
+        ICP.set_param('fusion_login_audit.last_alert:cool@example.com', '')
+
+        user = self.env['res.users'].sudo().create({
+            'name': 'Cooldown Tester',
+            'login': 'cool@example.com',
+            'password': 'cooldown-tester-pw-1',
+        })
+        Mail = self.env['mail.mail'].sudo()
+        for _i in range(3):
+            try:
+                user._check_credentials(
+                    {'login': user.login, 'password': 'wrong',
+                     'type': 'password'},
+                    {'interactive': False},
+                )
+            except AccessDenied:
+                pass
+        count_after_3 = Mail.search_count([('subject', 'ilike', 'cool@example.com')])
+        for _i in range(2):
+            try:
+                user._check_credentials(
+                    {'login': user.login, 'password': 'wrong',
+                     'type': 'password'},
+                    {'interactive': False},
+                )
+            except AccessDenied:
+                pass
+        count_after_5 = Mail.search_count([('subject', 'ilike', 'cool@example.com')])
+        self.assertEqual(count_after_5, count_after_3,
+                         "Cooldown should suppress additional emails")
+
+    def test_alert_disabled_master_switch(self):
+        """alert_enabled=False suppresses all alerts regardless of threshold."""
+        from odoo.exceptions import AccessDenied
+        ICP = self.env['ir.config_parameter'].sudo()
+        ICP.set_param('fusion_login_audit.alert_threshold', '1')
+        ICP.set_param('fusion_login_audit.alert_window_min', '15')
+        # Use the actual boolean field's storage semantics — see CLAUDE.md rule #5.
+        # Writing False through the settings form deletes the param; here we
+        # set the string 'False' explicitly to simulate "disabled".
+        ICP.set_param('fusion_login_audit.alert_enabled', 'False')
+        ICP.set_param('fusion_login_audit.last_alert:disabled@example.com', '')
+
+        user = self.env['res.users'].sudo().create({
+            'name': 'Disabled Tester',
+            'login': 'disabled@example.com',
+            'password': 'disabled-tester-pw-1',
+        })
+        Mail = self.env['mail.mail'].sudo()
+        before = Mail.search_count([('subject', 'ilike', 'disabled@example.com')])
+        try:
+            user._check_credentials(
+                {'login': user.login, 'password': 'wrong',
+                 'type': 'password'},
+                {'interactive': False},
+            )
+        except AccessDenied:
+            pass
+        after = Mail.search_count([('subject', 'ilike', 'disabled@example.com')])
+        self.assertEqual(after, before, "Disabled alerts should queue nothing")
+
+    def test_retention_gc_deletes_old_rows(self):
+        """The GC method deletes rows older than retention_days."""
+        from datetime import timedelta
+        ICP = self.env['ir.config_parameter'].sudo()
+        ICP.set_param('fusion_login_audit.retention_days', '30')
+
+        now = fields.Datetime.now()
+        Audit = self.env['fusion.login.audit'].sudo()
+        old = Audit.create({
+            'attempted_login': 'gc-old@example.com',
+            'result': 'success',
+            'event_time': now - timedelta(days=45),
+        })
+        recent = Audit.create({
+            'attempted_login': 'gc-recent@example.com',
+            'result': 'success',
+            'event_time': now - timedelta(days=5),
+        })
+        old_id, recent_id = old.id, recent.id
+
+        Audit._fc_retention_gc()
+
+        self.assertFalse(Audit.browse(old_id).exists(),
+                         "Row older than retention_days should be gone")
+        self.assertTrue(Audit.browse(recent_id).exists(),
+                        "Row inside retention_days should survive")
+
+    def test_retention_zero_keeps_forever(self):
+        """retention_days=0 keeps all rows."""
+        from datetime import timedelta
+        ICP = self.env['ir.config_parameter'].sudo()
+        ICP.set_param('fusion_login_audit.retention_days', '0')
+
+        now = fields.Datetime.now()
+        Audit = self.env['fusion.login.audit'].sudo()
+        ancient = Audit.create({
+            'attempted_login': 'forever@example.com',
+            'result': 'success',
+            'event_time': now - timedelta(days=3650),
+        })
+        ancient_id = ancient.id
+
+        Audit._fc_retention_gc()
+
+        self.assertTrue(Audit.browse(ancient_id).exists(),
+                        "retention_days=0 must keep everything")
+
+    def test_geo_private_ip_shortcut(self):
+        """Private IPs short-circuit to state='private_ip' without HTTP."""
+        Audit = self.env['fusion.login.audit'].sudo()
+        rec = Audit.create({
+            'attempted_login': 'lan@example.com',
+            'result': 'success',
+            'ip_address': '192.168.1.40',
+            'geo_lookup_state': 'pending',
+        })
+        Audit._fc_geo_enrich_pending(limit=10)
+        rec.invalidate_recordset()
+        self.assertEqual(rec.geo_lookup_state, 'private_ip')
+        self.assertEqual(rec.country_code, '--')
+
+    def test_geo_cache_hit_avoids_http(self):
+        """A second row with the same recent IP copies from cache."""
+        from unittest.mock import patch
+        Audit = self.env['fusion.login.audit'].sudo()
+        # Seed a "done" row from the same IP.
+        Audit.create({
+            'attempted_login': 'seed@example.com',
+            'result': 'success',
+            'ip_address': '203.0.113.99',
+            'geo_lookup_state': 'done',
+            'country_code': 'CA',
+            'country_name': 'Canada',
+            'city': 'Toronto',
+            'geo_state': 'Ontario',
+        })
+        target = Audit.create({
+            'attempted_login': 'hit@example.com',
+            'result': 'success',
+            'ip_address': '203.0.113.99',
+            'geo_lookup_state': 'pending',
+        })
+
+        with patch(
+            'odoo.addons.fusion_login_audit.models.fusion_login_audit.requests.get'
+        ) as mock_get:
+            Audit._fc_geo_enrich_pending(limit=10)
+            mock_get.assert_not_called()
+
+        target.invalidate_recordset()
+        self.assertEqual(target.geo_lookup_state, 'done')
+        self.assertEqual(target.country_code, 'CA')
+        self.assertEqual(target.city, 'Toronto')
+
+    def test_geo_internal_skipped(self):
+        """Rows with geo_lookup_state='internal' are not picked up."""
+        Audit = self.env['fusion.login.audit'].sudo()
+        rec = Audit.create({
+            'attempted_login': 'cron@example.com',
+            'result': 'success',
+            'ip_address': 'internal',
+            'geo_lookup_state': 'internal',
+        })
+        # Should be a no-op for 'internal' state (cron only picks 'pending').
+        Audit._fc_geo_enrich_pending(limit=10)
+        rec.invalidate_recordset()
+        self.assertEqual(rec.geo_lookup_state, 'internal')

fusion_login_audit/tests/test_security.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+from odoo.exceptions import AccessError
+from odoo.tests.common import TransactionCase, tagged
+
+
+@tagged('post_install', '-at_install')
+class TestFusionLoginAuditSecurity(TransactionCase):
+    """Tests for the layered protection on `fusion.login.audit`:
+
+    Layer 1 — ACL (security/ir.model.access.csv): grants read-only access to
+    `base.group_system` and nothing to any other group. Blocks write/create/
+    unlink for everyone via the ORM regardless of `sudo()`.
+
+    Layer 2 — Record rule (security/security.xml): group-specific rule that
+    grants admins an unrestricted domain (`[(1,'=',1)]`). The rule does NOT
+    actively restrict non-admins — Odoo's semantics for a group-scoped rule
+    is "the rule only applies to users in that group". Non-admins are gated
+    purely by the ACL, which denies them everything. The rule's value is
+    documentation + future-proofing (it keeps admin access explicit if the
+    ACL is ever loosened with a per-group read row; the admin path remains
+    explicit and self-documenting). It is NOT a security gate the ACL relies on.
+
+    Test naming reflects which layer actually does the work:
+    - test_acl_blocks_*  — exercises Layer 1 (ACL alone is sufficient).
+    - test_admin_can_read_through_acl_and_rule — exercises both layers in
+                          the positive path (admin must satisfy ACL grant
+                          AND the admin-scoped rule's domain).
+    """
+
+    def setUp(self):
+        super().setUp()
+        self.audit_row = self.env['fusion.login.audit'].sudo().create({
+            'attempted_login': 'sec-test@example.com',
+            'result': 'success',
+            'database': self.env.cr.dbname,
+        })
+        # Internal non-admin user (active employee, not a Settings admin).
+        self.regular_user = self.env['res.users'].sudo().create({
+            'name': 'Regular Tester',
+            'login': 'regular-tester@example.com',
+            'password': 'regular-tester-pw-1',
+            'group_ids': [(6, 0, [self.env.ref('base.group_user').id])],
+        })
+        # Portal user (share=True) — must not see audit data either.
+        self.portal_user = self.env['res.users'].sudo().create({
+            'name': 'Portal Tester',
+            'login': 'portal-tester@example.com',
+            'password': 'portal-tester-pw-1',
+            'group_ids': [(6, 0, [self.env.ref('base.group_portal').id])],
+        })
+
+    def test_admin_can_read_through_acl_and_rule(self):
+        """A Settings admin satisfies both the ACL (grants read) and the
+        record rule (admin-only domain), so the read succeeds."""
+        admin = self.env.ref('base.user_admin')
+        rec = self.audit_row.with_user(admin).read(['attempted_login'])
+        self.assertEqual(rec[0]['attempted_login'], 'sec-test@example.com')
+
+    def test_acl_blocks_read_for_regular_user(self):
+        """A `base.group_user` member has no ACL grant on the model. The
+        ACL alone denies the read; the record rule never gets consulted."""
+        with self.assertRaises(AccessError):
+            self.audit_row.with_user(self.regular_user).read(['attempted_login'])
+
+    def test_acl_blocks_read_for_portal_user(self):
+        """A `base.group_portal` (share=True) user has no ACL grant either.
+        Audit data must never leak to a portal user — IP and attempted_login
+        are sensitive."""
+        with self.assertRaises(AccessError):
+            self.audit_row.with_user(self.portal_user).read(['attempted_login'])
+
+    def test_acl_blocks_write_for_admin(self):
+        """Even Settings admins cannot write — the ACL grants no group any
+        write permission on this model (audit log is append-only). The rule's
+        `perm_write=False` means 'rule does not constrain this op', so this
+        denial is the ACL's work alone."""
+        admin = self.env.ref('base.user_admin')
+        with self.assertRaises(AccessError):
+            self.audit_row.with_user(admin).write({'attempted_login': 'tampered'})
+
+    def test_acl_blocks_unlink_for_admin(self):
+        """Append-only also at the unlink boundary. ACL grants no group
+        delete permission; the record rule's `perm_unlink=False` exempts
+        it from gating this op."""
+        admin = self.env.ref('base.user_admin')
+        with self.assertRaises(AccessError):
+            self.audit_row.with_user(admin).unlink()
+
+    # Note: a "rule actively blocks non-admins" test was attempted but
+    # removed once the actual Odoo semantics were verified. A group-scoped
+    # rule (groups=[base.group_system]) only applies to users in that group.
+    # Granting a base.group_user member an ACL read row would let them read
+    # rows — the rule does not filter them. To make the rule truly restrictive
+    # we would need a global rule (groups=[]) with domain [(0,'=',1)] paired
+    # with the admin grant. That is a security-model redesign and out of
+    # scope for T3. The ACL already provides the actual gate.
+
+    # ─────────────────────────────────────────────────────────────────────
+    # T14: view-level visibility checks. The smart button and the "Login
+    # Activity" tab on res.users are gated by groups="base.group_system"
+    # on the inner XML nodes (the inherited view record itself cannot
+    # carry groups — CLAUDE.md rule #11). Verify the gate works by asking
+    # for the form view as a non-admin and confirming the x_fc_* fields
+    # are stripped from the arch.
+    # ─────────────────────────────────────────────────────────────────────
+
+    def test_view_hides_button_and_tab_for_non_admin(self):
+        """A regular user's get_view() does not contain the x_fc_login_audit_*
+        fields — they live behind groups="base.group_system" XML attributes."""
+        view = self.env['res.users'].with_user(self.regular_user).get_view(
+            view_id=self.env.ref('base.view_users_form').id,
+            view_type='form',
+        )
+        arch = view['arch']
+        self.assertNotIn('x_fc_login_audit_count', arch,
+                         "Smart-button field must not leak into non-admin view")
+        self.assertNotIn('x_fc_login_audit_ids', arch,
+                         "Login Activity tab must not leak into non-admin view")
+
+    def test_view_shows_button_and_tab_for_admin(self):
+        """A Settings admin DOES see both nodes."""
+        admin = self.env.ref('base.user_admin')
+        view = self.env['res.users'].with_user(admin).get_view(
+            view_id=self.env.ref('base.view_users_form').id,
+            view_type='form',
+        )
+        arch = view['arch']
+        self.assertIn('x_fc_login_audit_count', arch)
+        self.assertIn('x_fc_login_audit_ids', arch)

fusion_login_audit/views/fusion_login_audit_views.xml

@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+
+    <!-- List -->
+    <record id="view_fusion_login_audit_list" model="ir.ui.view">
+        <field name="name">fusion.login.audit.list</field>
+        <field name="model">fusion.login.audit</field>
+        <field name="arch" type="xml">
+            <list create="false" edit="false" delete="false"
+                  default_order="event_time desc"
+                  decoration-success="result=='success'"
+                  decoration-danger="result=='failure'">
+                <field name="event_time"/>
+                <field name="user_id"/>
+                <field name="attempted_login"/>
+                <field name="result" widget="badge"/>
+                <field name="failure_reason"/>
+                <field name="ip_address"/>
+                <field name="country_code"/>
+                <field name="city"/>
+                <field name="browser"/>
+                <field name="device_type"/>
+                <field name="database" optional="hide"/>
+            </list>
+        </field>
+    </record>
+
+    <!-- Form (readonly) -->
+    <record id="view_fusion_login_audit_form" model="ir.ui.view">
+        <field name="name">fusion.login.audit.form</field>
+        <field name="model">fusion.login.audit</field>
+        <field name="arch" type="xml">
+            <form create="false" edit="false" delete="false">
+                <sheet>
+                    <group>
+                        <group string="Event">
+                            <field name="event_time" readonly="1"/>
+                            <field name="result" readonly="1" widget="badge"/>
+                            <field name="failure_reason" readonly="1"/>
+                            <field name="user_id" readonly="1"/>
+                            <field name="attempted_login" readonly="1"/>
+                            <field name="database" readonly="1"/>
+                        </group>
+                        <group string="Source">
+                            <field name="ip_address" readonly="1"/>
+                            <field name="ip_hostname" readonly="1"/>
+                            <field name="country_code" readonly="1"/>
+                            <field name="country_name" readonly="1"/>
+                            <field name="geo_state" readonly="1"/>
+                            <field name="city" readonly="1"/>
+                            <field name="geo_lookup_state" readonly="1"/>
+                        </group>
+                    </group>
+                    <group string="Client">
+                        <field name="device_type" readonly="1"/>
+                        <field name="browser" readonly="1"/>
+                        <field name="os" readonly="1"/>
+                        <field name="user_agent_raw" readonly="1"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <!-- Search -->
+    <record id="view_fusion_login_audit_search" model="ir.ui.view">
+        <field name="name">fusion.login.audit.search</field>
+        <field name="model">fusion.login.audit</field>
+        <field name="arch" type="xml">
+            <search>
+                <field name="attempted_login"/>
+                <field name="user_id"/>
+                <field name="ip_address"/>
+                <field name="country_code"/>
+                <filter name="filter_success" string="Successes"
+                        domain="[('result','=','success')]"/>
+                <filter name="filter_failure" string="Failures"
+                        domain="[('result','=','failure')]"/>
+                <separator/>
+                <filter name="filter_24h" string="Last 24 hours"
+                        domain="[('event_time','&gt;=', (context_today() - relativedelta(days=1)).strftime('%Y-%m-%d 00:00:00'))]"/>
+                <filter name="filter_7d" string="Last 7 days"
+                        domain="[('event_time','&gt;=', (context_today() - relativedelta(days=7)).strftime('%Y-%m-%d 00:00:00'))]"/>
+                <filter name="filter_30d" string="Last 30 days"
+                        domain="[('event_time','&gt;=', (context_today() - relativedelta(days=30)).strftime('%Y-%m-%d 00:00:00'))]"/>
+                <separator/>
+                <filter name="filter_unknown_user" string="Unknown users"
+                        domain="[('user_id','=',False)]"/>
+                <group>
+                    <filter name="group_user" string="User"
+                            context="{'group_by': 'user_id'}"/>
+                    <filter name="group_country" string="Country"
+                            context="{'group_by': 'country_code'}"/>
+                    <filter name="group_ip" string="IP"
+                            context="{'group_by': 'ip_address'}"/>
+                </group>
+            </search>
+        </field>
+    </record>
+
+    <!-- Window actions -->
+    <record id="action_fusion_login_audit_all" model="ir.actions.act_window">
+        <field name="name">Login Events</field>
+        <field name="res_model">fusion.login.audit</field>
+        <field name="view_mode">list,form</field>
+        <field name="search_view_id" ref="view_fusion_login_audit_search"/>
+        <field name="context">{}</field>
+    </record>
+
+    <record id="action_fusion_login_audit_failures_24h" model="ir.actions.act_window">
+        <field name="name">Failed Logins (24h)</field>
+        <field name="res_model">fusion.login.audit</field>
+        <field name="view_mode">list,form</field>
+        <field name="search_view_id" ref="view_fusion_login_audit_search"/>
+        <field name="context">{'search_default_filter_failure': 1, 'search_default_filter_24h': 1}</field>
+    </record>
+
+</odoo>

fusion_login_audit/views/menus.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+
+    <menuitem id="menu_fusion_login_audit_root"
+              name="Login Audit"
+              parent="base.menu_administration"
+              groups="base.group_system"
+              sequence="100"/>
+
+    <menuitem id="menu_fusion_login_audit_all"
+              name="Login Events"
+              parent="menu_fusion_login_audit_root"
+              action="action_fusion_login_audit_all"
+              groups="base.group_system"
+              sequence="10"/>
+
+    <menuitem id="menu_fusion_login_audit_failures"
+              name="Failed Logins (24h)"
+              parent="menu_fusion_login_audit_root"
+              action="action_fusion_login_audit_failures_24h"
+              groups="base.group_system"
+              sequence="20"/>
+
+</odoo>

fusion_login_audit/views/res_config_settings_views.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+
+    <record id="view_res_config_settings_form_login_audit" model="ir.ui.view">
+        <field name="name">res.config.settings.form.login.audit</field>
+        <field name="model">res.config.settings</field>
+        <field name="inherit_id" ref="base_setup.res_config_settings_view_form"/>
+        <field name="arch" type="xml">
+            <xpath expr="//block[@id='user_default_rights']" position="after">
+                <block title="Login Audit"
+                       name="login_audit_block"
+                       groups="base.group_system">
+                    <setting id="login_audit_retention"
+                             string="Retention (days)"
+                             help="0 = keep forever">
+                        <field name="x_fc_login_audit_retention_days"/>
+                    </setting>
+                    <setting id="login_audit_alert_enabled"
+                             string="Send failed-login alerts"
+                             help="Email Settings admins when consecutive failures cross the threshold">
+                        <field name="x_fc_login_audit_alert_enabled"/>
+                    </setting>
+                    <setting id="login_audit_alert_threshold"
+                             string="Alert threshold (failures)">
+                        <field name="x_fc_login_audit_alert_threshold"/>
+                    </setting>
+                    <setting id="login_audit_alert_window"
+                             string="Alert window (minutes)">
+                        <field name="x_fc_login_audit_alert_window_min"/>
+                    </setting>
+                </block>
+            </xpath>
+        </field>
+    </record>
+
+</odoo>

fusion_login_audit/views/res_users_views.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+
+    <record id="view_users_form_inherit_login_audit" model="ir.ui.view">
+        <field name="name">res.users.form.inherit.fusion_login_audit</field>
+        <field name="model">res.users</field>
+        <field name="inherit_id" ref="base.view_users_form"/>
+        <!-- Odoo 19: groups MUST be on the inherited XML nodes (button + page
+             below), NOT on the ir.ui.view record itself. Setting `group_ids`
+             on the record raises ParseError "Inherited view cannot have
+             'groups' defined on the record. Use 'groups' attributes inside
+             the view definition". -->
+        <field name="arch" type="xml">
+            <!-- Smart button -->
+            <xpath expr="//div[@name='button_box']" position="inside">
+                <button name="action_fc_view_login_audit"
+                        type="object"
+                        class="oe_stat_button"
+                        icon="fa-key"
+                        groups="base.group_system">
+                    <field name="x_fc_login_audit_count" widget="statinfo"
+                           string="Logins"/>
+                </button>
+            </xpath>
+
+            <!-- Login Activity tab appended at the end of the notebook -->
+            <xpath expr="//notebook" position="inside">
+                <page string="Login Activity"
+                      name="fc_login_activity"
+                      groups="base.group_system">
+                    <group>
+                        <field name="x_fc_last_successful_login" readonly="1"/>
+                        <field name="x_fc_last_login_ip" readonly="1"/>
+                    </group>
+                    <field name="x_fc_login_audit_ids" readonly="1"
+                           context="{'create': False, 'edit': False, 'delete': False}">
+                        <list create="false" edit="false" delete="false"
+                              limit="30" default_order="event_time desc">
+                            <field name="event_time"/>
+                            <field name="result" decoration-success="result=='success'"
+                                                  decoration-danger="result=='failure'"
+                                                  widget="badge"/>
+                            <field name="failure_reason"/>
+                            <field name="ip_address"/>
+                            <field name="country_code"/>
+                            <field name="city"/>
+                            <field name="browser"/>
+                            <field name="os"/>
+                        </list>
+                    </field>
+                </page>
+            </xpath>
+        </field>
+    </record>
+
+</odoo>

fusion_plating/.gitignore

@@ -2,6 +2,10 @@
 # The companion server saves files here; not project source.
 .superpowers/
 
+# Claude Code preview-tooling state (launch.json for preview_start,
+# throwaway HTML mockups from brainstorming sessions).
+.claude/
+
 # Local Odoo dev artifacts
 *.pyc
 __pycache__/

fusion_plating/CLAUDE.md

@@ -166,18 +166,83 @@ These modules have **source code in this repo** but are **intentionally NOT inst
 | `fusion_plating_culture` | `state=uninstalled`, dir removed from entech disk | Soft people-ops feature (peer kudos / "Fundamental of the Week"); zero data entered; not a client priority. Top-level "Culture" menu confused operators. | Ask the client whether they want it before reinstalling. If yes: re-sync folder + `-i fusion_plating_culture` + seed a value set. |
 | `fusion_plating_sensors` | deleted entirely (not in repo anymore) | Duplicated `fusion_plating_iot`'s scope but with no working alerting logic. Its valuables (sensor_type taxonomy, dashboard, location flexibility) were ported into `fusion_iot/fusion_plating_iot/`. | N/A — gone. Any new sensor work goes in `fusion_iot/fusion_plating_iot/`. |
 
-## Shop-floor action endpoints — credit the correct tech via `tablet_tech_id`
-The tablet sits on a long-lived "shopfloor service" Odoo session shared by many techs. The actual tech-of-record is established via the PIN unlock (Phase 6); their id lives in the OWL `fp_shopfloor_tech_store` service and is sent as `tablet_tech_id` on every action RPC.
+## Shop-floor action endpoints — attribution is automatic via `request.env.user`
 
-When writing a NEW shop-floor controller endpoint that **writes** (creates a record, calls a `button_*` method, posts to chatter):
-1. Add `tablet_tech_id=None` as a kwarg on the route handler.
-2. At the top, call: `env = env_for_tablet_tech(request.env, tablet_tech_id)` (from `fusion_plating_shopfloor/controllers/_tablet_audit.py`).
-3. Use `env` (not `request.env`) for all subsequent writes. `env.with_user(...)` is applied internally so `create_uid` / `write_uid` / chatter authorship carry the right uid.
-4. Read-only endpoints (load / kanban / funnel / overview) don't need this — leave them as `request.env`.
+As of `fusion_plating_shopfloor 19.0.33.1.0` (2026-05-24 Tablet PIN session redesign, Phase G cleanup), tablet writes are attributed via **real per-tech Odoo sessions**, not via a `tablet_tech_id` kwarg.
 
-On the client side: use `fpRpc()` from `services/fp_rpc.js` (drop-in for `rpc()`) for action calls. It auto-injects `tablet_tech_id`. Read calls can keep using plain `rpc()`.
+**How it works now:**
+- The tablet browser holds a session as the kiosk user (xmlid `fusion_plating_shopfloor.user_fp_tablet_kiosk`, id 141 on entech) when nobody is unlocked.
+- PIN unlock POSTs to `/fp/tablet/unlock_session`, which calls `request.session.authenticate(type='fp_tablet_pin', login, pin)`. The custom `_check_credentials` override on `res.users` validates the PIN hash + `all_group_ids` shop-branch membership and mints a real session AS the tech. Browser cookie swaps.
+- Subsequent writes use `request.env.user` (= the tech) automatically. `create_uid` / `write_uid` / chatter authorship are correct with zero plumbing.
+- Lock-back (`/fp/tablet/lock_session`) destroys the tech's session and re-auths the browser as the kiosk via the password stored in `ir.config_parameter['fp.tablet.kiosk_password']`.
 
-If `tablet_tech_id` is missing or invalid, `env_for_tablet_tech` falls back to the session uid — old callers and pre-Phase-6.3 endpoints continue working.
+**When writing a NEW shop-floor controller endpoint that writes:**
+1. Use `env = request.env` directly. No `tablet_tech_id` kwarg, no `env_for_tablet_tech` helper.
+2. Read-only endpoints — same thing, `request.env` is fine.
+
+**Gone post-Phase-G** — do NOT re-introduce:
+- `tablet_tech_id` kwarg on any HTTP route
+- `env_for_tablet_tech(...)` helper (the `_tablet_audit.py` file is deleted)
+- `fp_shopfloor_tech_store` OWL service (the `services/tech_store.js` file is deleted)
+- Legacy `/fp/tablet/unlock` route (the new one is `/fp/tablet/unlock_session`)
+- `fp.shopfloor.tablet_session_mode` feature flag (`session_swap` is the only flow; flag was for the 1-week overlap window during rollout — now retired)
+
+**Kiosk password lives in TWO places — keep them in sync:**
+The kiosk user's actual `res.users.password` AND `ir.config_parameter['fp.tablet.kiosk_password']` must match. The lock_session endpoint reads ICP to re-auth as kiosk after the tech session is destroyed. If they diverge (e.g. someone resets the password on the user form without updating ICP), lock-back fails and the endpoint returns `needs_kiosk_relogin=True` — the tablet then needs a manual login. Two valid states:
+- **Both set to the same value** — kiosk password is plaintext-readable in DB but lock-back works automatically.
+- **ICP key deleted entirely** — `DELETE FROM ir_config_parameter WHERE key = 'fp.tablet.kiosk_password';` — accepts manual re-login after every lock event in exchange for no plaintext in DB or backups.
+
+**Identify the kiosk user by xmlid, NEVER by login string:**
+The kiosk login (`fp_tablet_kiosk@enplating.local` at creation time) is a `noupdate="1"` data record — admins can rename it on the user form for memorability (entech's actual kiosk login is `tablet@enplating.ca` as of 2026-05-24), and the rename PERSISTS through `-u`. Any code that hardcoded `'fp_tablet_kiosk@enplating.local'` as a string silently breaks after a rename — caught when Phase G's `lock_session` had the login hardcoded and broke after the user renamed the kiosk; fixed by resolving via `env.ref('fusion_plating_shopfloor.user_fp_tablet_kiosk').sudo().login`. Same pattern applies to any other user/group/record an admin might rename on the form. The xmlid is the stable identity; the display fields are not.
+
+**Audit log** (`fp.tablet.session.event`): append-only model with Owner-only read ACL + Python `write`/`unlink` overrides (only the force-lock cron + retention crons bypass via context flags `fp_tablet_audit_admin_write` / `fp_tablet_audit_admin_purge`). Captures every unlock / failed_unlock / manual_lock / idle_lock / ceiling_lock / force_lock / admin_reset event with sha256(session sid), ip, user-agent, acting_uid, duration. View under Plating → Configuration → Tablet Audit Log (Owner-only menu). Per-user 7-day count smart button on `res.users` form.
+
+## Mail templates: `email_from` MUST match the active mail server's `from_filter` (or M365 greylists)
+Entech relays through Gmail OAuth as `orders@enplating.ca` (the mail server's `from_filter`). When a `mail.template` renders `email_from` to ANY other address (e.g. `{{ object.company_id.email }}` → `sales@enplating.ca`), Odoo logs `WARNING ir_mail_server: No mail server matches the from_filter, using <X> as fallback` and ships the message anyway — but the message has misaligned authentication:
+- SMTP-AUTH = `orders@enplating.ca`
+- `From:` header = `sales@enplating.ca`
+- DKIM signs the `mail-from` domain, NOT the `From:` domain
+- DMARC alignment check at recipient FAILS
+
+Recipients on Microsoft 365 (like nexasystems.ca) react to DMARC fail by **greylisting for 5–15 minutes** before delivery — or routing straight to junk. The user feels this as "the email takes a while" or "I never got it."
+
+**Rule:** every mail.template's `email_from` must resolve to an address inside the mail server's `from_filter`. Easiest pattern — add a helper on the template's target model that picks the active mail server's `from_filter` dynamically, then reference it from the template:
+
+```xml
+<field name="email_from">{{ object._fp_resolve_from_header() }}</field>
+<field name="reply_to">{{ object._fp_resolve_from_header() }}</field>
+```
+
+`res.users._fp_resolve_from_header()` (in `fusion_plating_shopfloor/models/res_users.py`) is the reference implementation — sudo-search `ir.mail_server`, prefer `from_filter` (if it's an `addr@domain` form, not a wildcard), then `smtp_user`, then fall back to `company.email`. Reuse it on other models by either inheriting `res.users`-style helpers or duplicating the same lookup pattern (the lookup is 6 lines).
+
+**Also avoid emojis in subject lines for cross-provider mail.** M365's spam classifier bumps emoji-containing subjects ~1.5–2 points; combined with cross-provider routing it pushes mail to junk or delay. PIN-reset codes / invoice notifications / shipment alerts — keep the subject plain.
+
+If you must use a different From for branding reasons, the proper fix is multi-step (add the From address as a verified "Send as" alias on the Gmail account, ensure SPF lists Gmail's IPs for that domain, set up DKIM signing for the From domain). That's a config-side change, not a code change — flag it for the admin instead of working around it in the template.
+
+## `send_mail(force_send=False)` is broken for interactive flows on entech
+Entech's `Mail: Email Queue Manager` cron (id 3) runs every **1 hour**, not the per-minute default that vanilla Odoo demos use. A controller that queues an email with `force_send=False` for an interactive flow (PIN reset code, password reset, "click here for a one-time link", any flow where the user is staring at the screen waiting for the email) will sit in the outbox for up to 60 minutes. The mail row stays at `state='outgoing'`, no error is logged, the user thinks it never sent. Bit us 2026-05-25 on tablet PIN reset — codes 2253 and 7780 sat queued for 36+ minutes before we noticed.
+
+**Rule:** for any interactive email flow, use `force_send=True` in `template.send_mail(res_id, force_send=True)`. The synchronous send adds ~1s of latency but the user gets the email before they can tab to their inbox. The cron is for batch / fire-and-forget notifications where the user isn't watching (NCR escalations, daily digests, etc.).
+
+**Don't change the cron interval to "fix" this** — the hourly schedule is intentional on entech (Gmail SMTP daily quota mitigation + reduced relay overhead for the 95% of notifications that aren't time-sensitive). Per-flow `force_send=True` is the right knob.
+
+When `force_send=True`, errors propagate (Gmail SMTP refusal, from_filter mismatch, etc.). Wrap with try/except and log, but consider returning a user-visible `{ok: false, error: 'email_send_failed'}` so the operator knows to retry or ask the manager — better than silent success that never arrives.
+
+## Brainstorming visual previews — the user is on Mac, this Windows host can't show them
+The user runs Claude Code from a **Mac** via Tailscale into this Windows host (`Home`). Any browser preview server bound to `localhost` on the Windows side (`http://localhost:8765`, the brainstorm script's preview server, `python -m http.server`, etc.) is unreachable from the Mac browser. Has bitten us three times now — Quality Dashboard redesign (2026-05-23), and twice during the Express Orders brainstorm (2026-05-25).
+
+**Rule:** when running on this Windows host, do NOT spin up the `superpowers:brainstorming` visual companion (or any other browser-preview-style server) unless the user explicitly asks for it. Default to text-based design discussion — ASCII tables, structured lists, reference to existing files. The Excel mockup or screenshot the user provides is plenty of reference. If a visual companion IS requested anyway, the only path that works is binding to the Windows host's Tailscale IP (`100.87.38.59` on `Home`) — but even that requires firewall coordination and isn't worth the friction.
+
+**Mac-side sessions:** localhost previews work fine; this rule doesn't apply. The user typically switches to a native Mac Claude Code session for visual-heavy work.
+
+## Deleting an OWL component — also audit the localStorage / shared state it wrote
+When you delete an OWL component (delete .js/.xml/.scss + drop manifest entries), the component's code is gone, but **any localStorage keys it wrote remain on every browser that ever rendered it**. If another live component reads those keys (with the deleted component's name in the key), the stale value still feeds into requests.
+
+Concrete failure 2026-05-25: deleted `fp_shopfloor_landing` (which used `localStorage.fp_landing_station_id` to pair the tablet to a station). `tablet_lock.js` was reading the same key to scope the lock-screen tile query (`/fp/tablet/tiles?station_id=…`). After the delete, every tablet that had ever paired via the old component kept sending that stale id; the kiosk session can't read `fusion.plating.shopfloor.station` (locked-down ACL), so the endpoint hit AccessError and returned an empty tile list. The lock screen rendered "no operators." Took us ten minutes of "but my code didn't break anything" before finding it.
+
+**Mandatory grep before deleting an OWL component:** `grep -rn '<key-the-component-wrote>' --include='*.js' static/src/`. For every hit in OTHER files: decide (a) read a different source, (b) clear-on-read and read a different source, or (c) keep the key and add a server-side endpoint that writes it. Also clear the key from the surviving components on next load so existing tablets self-heal — don't make the user clear browser storage.
+
+Same audit applies to: window globals the component attached (`window.fpFoo = …`), CustomEvents it dispatched, IndexedDB stores it created, ServiceWorker registrations, BroadcastChannel topics.
 
 ## Removing menus/records — Odoo does NOT auto-delete orphans
 Deleting a `<menuitem>` (or any `<record>`) from a data XML file does NOT remove the corresponding database row. The XML loader only updates records it sees; orphans persist in `ir.ui.menu` / `ir.model.data` until you delete them explicitly. Symptom: the menu still appears in the UI after `-u`. Fix — add a `<delete>` directive in a data file with `noupdate="0"`:
@@ -186,6 +251,8 @@ Deleting a `<menuitem>` (or any `<record>`) from a data XML file does NOT remove
 ```
 Caught 2026-05-22 when the Phase 3 Plant Overview menu kept showing alongside the new Workstation menu after deploy.
 
+**`<delete>` is single-use — remove it after the deploy that fires it.** Subsequent `-u` runs against a missing xmlid raise `ValueError: External ID not found in the system: <module>.<xmlid>` because the XML loader evaluates the `id="..."` ref at parse time. The error is non-fatal (load continues), but it bloats the log on every restart and obscures real failures. Workflow: ship the `<delete>` directive in deploy N, then DELETE the directive itself in deploy N+1 (or replace with a comment noting when the row was removed). The `<delete>` is not idempotent against an already-missing row. Caught 2026-05-25 when `<delete model="ir.ui.menu" id="fusion_plating_shopfloor.menu_fp_shopfloor_plant_overview"/>` in legacy_menu_hide.xml had been firing this error for weeks after the menu was already gone.
+
 ## Odoo 19 ir.cron — `numbercall` and `doall` are gone
 The legacy `numbercall=-1` (run-forever) and `doall=False` (catch-up-missed) fields were removed from `ir.cron` in Odoo 19. Including them in `<record model="ir.cron">` data XML produces:
 ```
@@ -208,6 +275,104 @@ Use only: `name`, `model_id`, `state`, `code` (or `function`/`model`), `interval
 11. **XML data ordering**: Window actions must be defined BEFORE `<menuitem>` elements that reference them in the same file.
 12. **Module install on new modules**: Use `--update=base` alongside `-i MODULE` to ensure Odoo rescans the addons path and finds the new module directory.
 13. **Implied group cascade**: `implied_ids` on `res.groups` does NOT reliably propagate to users on module install. Always include `user_ids` to explicitly assign admin, or fix via SQL post-install.
+13b. **Kanban template name — Odoo 19 wants `<t t-name="card">`, NOT `<t t-name="kanban-box">`**. Old name silently fails at render: `Error: Missing 'card' template`. Use the new structure with semantic `<aside>` + `<main>`:
+    ```xml
+    <templates>
+        <t t-name="card" class="flex-row align-items-center">
+            <aside><field name="image_128" widget="image"/></aside>
+            <main class="ms-2"><field name="name"/></main>
+        </t>
+    </templates>
+    ```
+    Reference: `/usr/lib/python3/dist-packages/odoo/addons/web/static/src/views/kanban/kanban_arch_parser.js`. Pre-existing `fp_rack_views.xml` still uses the old name and would also fail at render — fix when next touched. Caught 2026-05-24 by final reviewer of permissions-overhaul branch.
+13m. **Tablet / kanban / dashboard controllers that surface DENORMALIZED cross-module data must `sudo()` the source recordset** at the top of the rendering helper. Low-privilege roles (Technician / Sales Rep) can read `fp.job` but NOT the cross-module fields it links to (sale.order, fp.part.catalog, fusion.plating.customer.spec, etc.) — naive `job.sale_order_id.x_fc_po_number` AccessErrors at render time and the kanban returns empty. The output is safe-to-expose display data; ACL gating is enforced by the CALLER's access to fp.job itself. Pattern:
+    ```python
+    def _render_card(job, paired):
+        job = job.sudo()  # cross-module reads now bypass ACL
+        so = job.sale_order_id    # was AccessError for Technician
+        ...
+    ```
+    Caught 2026-05-24 when Technicians saw an empty Shop Floor kanban post-migration (log: `Access Denied by ACLs ... model: sale.order`). Same pattern likely needed in any controller returning a job-centric card payload to a non-Manager user.
+13l. **`res.groups.user_ids` returns DIRECT members only — implied/transitive memberships are NOT stored in `user.groups_id`**. When you `user.write({'groups_id': [(4, owner_group.id)]})`, Odoo adds JUST the Owner group to the user — it does NOT cascade and write the implied Manager/Shop Manager/Technician group rows into res_groups_users_rel. The implication chain is resolved at READ time by `has_group()` and `_get_trans_implied_groups()`, but NOT materialized in storage. So:
+    - `env.ref('fusion_plating.group_fp_technician').user_ids` returns ONLY the 18 direct Technicians, NOT the Owners/QMs/Managers/Shop Managers who reach Technician via implication.
+    - `env.ref('fusion_plating.group_fusion_plating_operator').user_ids` (the deprecated group) returns EMPTY post-migration for the same reason — no user holds it directly.
+
+    **Fix for "enumerate everyone with role X or higher":** search `res.users` directly with the union of group ids:
+    ```python
+    shop_branch_ids = [env.ref(x).id for x in (
+        'fusion_plating.group_fp_technician',
+        'fusion_plating.group_fp_shop_manager_v2',
+        'fusion_plating.group_fp_manager',
+        'fusion_plating.group_fp_quality_manager',
+        'fusion_plating.group_fp_owner',
+    )]
+    users = env['res.users'].sudo().search([
+        ('group_ids', 'in', shop_branch_ids),  # NB: group_ids not groups_id in Odoo 19, see rule 13c
+        ('share', '=', False), ('active', '=', True),
+    ])
+    ```
+    `('groups_id', 'in', [...])` is the right operator — it matches the DIRECT membership rel table without trying to follow implications. Since each user has exactly one primary plating role (Phase F `x_fc_plating_role` Selection enforces this), this returns every shop-branch user with no duplicates.
+
+    For `has_group`-style intent ("does this single user have role X or any role that implies X"), use `user.has_group('fusion_plating.group_fp_X')` — that DOES follow the implication chain at read time.
+
+    Caught 2026-05-24 in two waves: (1) tablet lock screen showed "No operators configured" because it queried the deprecated `group_fusion_plating_operator.user_ids`; (2) after fixing to `group_fp_technician.user_ids`, it still missed Owners/Managers because implication chains don't populate `user_ids`. Final fix: search-based query across the 5 shop-branch role ids. Audit for other instances: `grep -rn "env\.ref.*\.user_ids\b" --include='*.py'` (skip test files which intentionally exercise backward-compat).
+13k. **Custom fields on `res.users` must be added to `SELF_WRITEABLE_FIELDS` (and often `SELF_READABLE_FIELDS`) or non-admin users can't save their own Preferences dialog**. Odoo 19's User Preferences dialog goes through `res.users.write` on the user's own record — Odoo bypasses the standard write ACL ONLY IF every field being written is in `SELF_WRITEABLE_FIELDS`. Any unknown field forces fallback to the standard ACL (admin-only on entech) → `AccessError: You are not allowed to modify 'User' records. Required group: Access Rights`.
+
+    **In Odoo 19, `SELF_WRITEABLE_FIELDS` and `SELF_READABLE_FIELDS` are `@property`-decorated methods, NOT class attributes.** Extend via super(), not list concatenation on `models.Model.SELF_*` (that AttributeErrors at module load — Model base doesn't define them, only res.users does). Canonical pattern (matches hr/res_users.py and mail/res_users.py):
+
+    ```python
+    class ResUsers(models.Model):
+        _inherit = 'res.users'
+
+        @property
+        def SELF_WRITEABLE_FIELDS(self):
+            return super().SELF_WRITEABLE_FIELDS + [
+                'x_fc_plating_landing_action_id', 'x_fc_signature_image',
+            ]
+
+        @property
+        def SELF_READABLE_FIELDS(self):
+            return super().SELF_READABLE_FIELDS + [
+                'x_fc_plating_role', 'x_fc_tablet_pin_set_date', ...
+            ]
+    ```
+
+    Readonly fields on the preferences form ALSO need SELF_READABLE_FIELDS (the form fetches them before the user clicks Save). Methods invoked by buttons that do their own `sudo().write()` bypass this — only DIRECT form-level writes hit the check. Caught 2026-05-24 when Technician tried to save their preferences after the plating landing field was added; the initial fix used the wrong class-attribute syntax and crashed odoo at module load.
+13j. **Non-stored Many2many computes STILL require user-level read access on the comodel** for field-assignment cache fill, even when the compute body is wrapped in `sudo()`. The `user.field = [(6, 0, ids)]` assignment populates the cache by relating to comodel records the CURRENT USER must be able to read — `sudo()` on the lookup doesn't help because the assignment is per-record-context. If the comodel is admin-only (like `ir.actions.actions` / `ir.actions.act_window` on entech), a non-admin opening their own preferences will fail with `Failed to write field X. You are not allowed to access 'Y' records.` Two fixes: (a) drop the Many2many compute and use a static domain filter instead, plus add an ACL row granting read on the comodel to whichever role group needs to evaluate the picker domain; (b) replace the Many2many with a Json/Char that stores IDs, lose the auto-validation. Option (a) is simpler — Odoo's design assumes pickers' comodels are user-readable. Caught 2026-05-24 when a Technician tried to open their Preferences after the per-user `accessible_landing_action_ids` field was added.
+13i. **`res.users` does NOT have `message_post()`** — chatter posting must go through `user.partner_id.message_post(...)`. `res.users` uses `_inherits = {'res.partner': 'partner_id'}` (delegation), which proxies FIELDS through partner_id but NOT METHODS. `user.message_post(...)` raises `AttributeError: 'res.users' object has no attribute 'message_post'`. Note that mail's tracking IS recorded on the user record (via partner) — the chatter widget on user form displays partner's chatter — but the post call itself targets the partner. Caught 2026-05-24 during Owner approval click on the migration preview screen.
+13c. **`res.users.group_ids` NOT `groups_id`**: Odoo 19 renamed the m2m field. Old name doesn't resolve; `@api.depends('groups_id')` raises `ValueError` at module load. Also: domain on relational pickers should use `all_group_ids` (transitive set incl. implied) instead of `group_ids` (only directly-assigned) — otherwise an Owner user won't match a domain looking for QM members. See `feedback_odoo19_groups_id_renamed.md`.
+13d. **`post_init_hook` ONLY fires on INSTALL, not UPGRADE** in Odoo 19. For logic that must run on `-u` of an existing install (entech case), add a `migrations/<version>/post-migrate.py` with a `migrate(cr, version)` function that calls the same helper. The hook still works on fresh install; the migration script bridges the gap on `-u`. Both should be idempotent so re-runs are safe.
+13g. **Odoo 19's `sale.view_order_form` uses a single `<field name="tax_totals" widget="account-tax-totals-field"/>` widget instead of separate `amount_total` / `amount_untaxed` / `amount_tax` fields**. Inheriting xpaths targeting any of the three separate fields will fail at view load: `Element '<xpath expr="//field[@name='amount_total']">' cannot be located in parent view`. To gate or modify totals, target the `tax_totals` widget (one xpath hides the whole totals block). Other views in the file (kanban, list, pivot) DO still have the individual fields — only the FORM view consolidated to the widget. Same likely applies to `purchase.purchase_order_form` and `account.view_move_form` — verify per-view before porting Odoo 17/18 xpaths. Caught 2026-05-24.
+13h. **`user_has_groups('xmlid')` is NOT available inside Odoo 19's `invisible=`/`readonly=`/`required=` attribute expressions**. The view validator parses `user_has_groups` as a field name on the host model and fails: `field 'user_has_groups' does not exist in model 'X'`. Group-based UI gating must use the `groups=` attribute on the element instead. To combine group-AND-state logic, EITHER split into two elements with mutually-exclusive `invisible` AND different `groups=`, OR enforce one half at the model layer (ir.rule / @api.constrains) and the other in the view. Caught 2026-05-24 when a single button used `invisible="state != 'draft' or (cert_type == 'nadcap' and not user_has_groups(...))"` — rewrote as a single button with `groups="group_fp_manager"` + `invisible="state != 'draft'"` and let the ir.rule enforce the Nadcap-write restriction (Manager clicking Issue on a Nadcap cert now raises AccessError).
+13f. **Odoo 19 view validator rejects `ref('xmlid')` inside `<field domain="...">`**: the validator parses `ref(...)` as a field-access on the host model and fails with `field 'ref' does not exist in model 'X'`. Even though `ref()` IS resolved at runtime by the client, validation fires first and aborts module load. Workarounds (pick one):
+    - **Drop the domain** and enforce eligibility via `@api.constrains` on the Python side (simplest — used for `res.company.x_fc_cgp_designated_official_id` in this project; the Owner makes a deliberate choice and Python validates at save time).
+    - **Pre-compute eligible IDs** in a stored `Many2many` compute on the host model, then `domain="[('id', 'in', eligible_ids_field)]"`.
+    - Move the domain into the field definition in Python (`fields.Many2one(..., domain="[...]")`) — but Python-side domains have the same `ref()` limitation, so this isn't always an escape.
+    Caught 2026-05-24 deploying permissions-overhaul to entech.
+13e. **`res_groups_name_uniq` constraint is `(privilege_id, name)` — cross-module display-name collisions during `-u` need a `pre-migrate.py` rename**. If a base module's new XML defines a group with the same display name as a DOWNSTREAM module's existing group (e.g. core adds new `Shop Manager (v2)` while configurator already has old `Shop Manager`), the new INSERT collides with the still-named-the-same downstream row, because Odoo loads modules in dep order and the downstream rename via XML hasn't happened yet. The fix is a `migrations/<version>/pre-migrate.py` in the BASE module that SQL-renames the downstream row before the new XML loads:
+    ```python
+    def migrate(cr, version):
+        cr.execute(\"\"\"
+            UPDATE res_groups
+               SET name = jsonb_build_object('en_US', '[DEPRECATED] Shop Manager (...)')
+             WHERE id IN (
+                SELECT res_id FROM ir_model_data
+                 WHERE module = 'fusion_plating_configurator'
+                   AND name = 'group_fp_shop_manager'
+                   AND model = 'res.groups'
+             )
+               AND (name IS NULL OR name->>'en_US' NOT LIKE '[DEPRECATED]%');
+        \"\"\")
+    ```
+    Pre-migrate scripts run BEFORE the module's data files reload, so the constraint is clear by the time the new group XML INSERTs. Caught 2026-05-24 during permissions-overhaul deploy — `fp_security_v2.xml` claimed `'Shop Manager'` while old configurator's `group_fp_shop_manager` still held that display name in the DB. Same pattern applies to ANY base-module XML adding groups with names that overlap downstream-module groups.
+13a. **Cross-module xmlid refs — base modules CANNOT forward-ref downstream xmlids**: A BASE module's data XML cannot `ref('downstream_module.some_xmlid')` because at fresh install, the base module loads FIRST and `ir.model.data` has no row for the downstream xmlid yet → `ValueError: External ID not found`. This bites on entech (existing DB has the row) but breaks fresh CI/test/demo/new-client installs. **Fix pattern: relocate the cross-module link to the downstream module's own security/data file, using an additive write to the BASE module's record:**
+    ```xml
+    <!-- In downstream module's security XML -->
+    <record id="fusion_plating.group_fp_sales_rep" model="res.groups">
+        <field name="implied_ids" eval="[(4, ref('fusion_plating_configurator.group_fp_estimator'))]"/>
+    </record>
+    ```
+    Odoo's XML loader treats `id="other_module.xmlid"` as an additive update to the existing record, and `(4, ref(...))` (Command.link) stacks idempotently across install/-u cycles. Use this whenever a base module group/record needs to imply or reference something defined in a downstream module. Caught 2026-05-24 when `fusion_plating/security/fp_security_v2.xml` referenced groups from configurator/receiving/invoicing/cgp — worked on entech, would have broken fresh installs.
 14a. **FP report palette + border rendering**: `fusion_plating_reports/report/report_base_styles.xml` uses **`#c1c1c1`** for section-header backgrounds and **`#1d1f1e`** (th text on grey) / **`#4e4e4e`** (h2/h4 on white) — NOT `res.company.primary_color`. Per-customer request (2026-05-17) the FP reports stopped following the company brand colour so every shop gets the same neutral look. The `fp_primary` template variable is still computed in the styles block so per-report templates can opt back in if needed, but the default `.fp-report` / `.fp-landscape` rules use the hardcoded greys. **Don't "fix" this back to `fp_primary` without confirming.**
 
     **Border-rendering gotcha** (entech wkhtmltopdf): with the standard `border-collapse: collapse` + `border: 1px solid #000` pattern, vertical borders can render slightly softer than horizontal borders because of how wkhtmltopdf rounds sub-pixels in its collapse-adjudication. Cells with a `background-color` also paint over the border edge unless clipped. Mitigations in place:
@@ -228,6 +393,20 @@ Use only: `name`, `model_id`, `state`, `code` (or `function`/`model`), `interval
     Both are test-data scaffolding; neither weakens assertions and neither must appear in production code paths.
 18. **Portal list pages — no pagination, 500-record cap**: All FP portal list routes (quote requests, jobs, certifications, deliveries) load up to 500 records and rely on client-side JS filtering. Do NOT re-add `portal_pager` to these routes. The `fp_portal_list_controls` macro + `fp_portal_list_search.js` handle filtering, counting, and the sort dropdown. Hidden `<td class="d-none">` cells inside each row carry extra searchable text (part number, customer PO, contact) that isn't displayed but is matched by the JS.
 19. **QWeb `t-value` is Python, not Jinja**: `t-value="orders|length"` does NOT call a filter — Python parses `|` as bitwise/recordset OR, so on a non-empty recordset it tries `recordset | length_var` and raises `TypeError: unsupported operand types in: sale.order(…) | None` (when `length` is undefined) or returns a merged recordset (when `length` happens to be another recordset). Use `len(orders)` or `bool(orders)` or `(orders and orders[0]) or False` — explicit Python. Same trap applies to `|default`, `|first`, `|join`, etc. — none of these Jinja filters exist in QWeb. Bit us 2026-05-18 on `fp_sale_order_portal.xml` injecting `result_total` into the list-controls macro.
+20. **OWL templates expose `Math` but NOT `String` / `Number` / `Array` / `Object` / `Boolean` / `JSON` / `parseInt` / `parseFloat`**: writing `t-on-click="() => this._press(String(d))"` (or similar coercion inside any template expression) throws `Uncaught TypeError: v2 is not a function` at click time — `v2` is OWL's compiled reference to a global that doesn't exist in template scope. The click handler dies before its body runs, so the bug looks like "nothing happens when I press" (no error in the UI, only DevTools shows the trace). **Fixes, in order of preference**: (a) eliminate the coercion entirely — store data in the right type up front, e.g. `t-foreach="['1','2','3']"` instead of `[1,2,3]` so `d` is already a string. (b) Use a JS-side coercion: pass the raw value to the handler and call `String(digit)` inside the component method. (c) Use a pure-expression workaround like string concatenation: `'' + d` does work because `+` is an operator, not a function. **Do NOT try to monkey-patch `String` onto the component (e.g. `this.String = String`) or onto `env` — leaks the global into every component and is fragile across OWL upgrades.** Bit us 2026-05-23 on `pin_pad.xml` — operators couldn't tap PIN digits at all because the click handler died on `String(d)`; the SCSS, reactivity, and `_press` method were all fine, the template scope was the entire bug. Same trap applies to OWL templates anywhere in the codebase: `move_parts_dialog.xml`, `manager_dashboard.xml`, `fp_record_inputs_dialog.xml`, etc. — grep all `t-on-click`, `t-att-*`, and `t-out` expressions for `String(`, `Number(`, `Array(`, `parseInt(`, `parseFloat(`, `JSON.` before merging.
+21. **`ir.actions.act_window_close` is a no-op when the current action was opened with `target: "current"`**: replacing the current action wipes the breadcrumb backstack, so there's nothing to close back to. The user clicks "Back" and nothing happens (no error, no navigation). This bites every OWL client-action surface that calls another client action via `doAction({..., target: "current"})` — the destination has no way to return to the source. **Fix pattern for "Back" buttons in OWL client actions**: navigate EXPLICITLY to the landing/parent action by tag, e.g. `this.action.doAction({ type: "ir.actions.client", tag: "fp_plant_kanban", target: "current" })` — works regardless of how the action was reached (kanban tap, QR scan, smart button, direct URL). **Do NOT rely on `act_window_close`, `history.back()`, or `this.env.config.breadcrumbs`** — all three are unreliable across navigation paths. Bit us 2026-05-23 on the Job Workspace Back button after the kanban opened the workspace with `target: "current"`. The same pattern applies to every other "Back" button in shopfloor / manager / portal OWL surfaces — explicit destination via `tag:` is the only robust answer.
+22. **Odoo 19 HTML fields auto-wrap plain-string writes**: writing `co.report_header = 'Plating & Finishing'` to an HTML field (like `res.company.report_header`, `res.partner.comment`, `mail.template.body_html`, `product.template.description_sale`) stores `<p>Plating &amp; Finishing</p>` after Odoo's HTML sanitizer runs. Equality tests against the raw input string FAIL (`payload['tagline'] != 'Plating & Finishing'`). **Three implications**: (a) **In tests**, don't `assertEqual` against the literal string you wrote — strip tags first, OR write the wrapped form (`<p>Plating & Finishing</p>`), OR write an explicit `Markup('<p>...</p>')` so the round-trip stays stable. (b) **In display code**, render HTML fields with `t-out` (QWeb) or `markup(...)` (OWL) — `t-esc` would render the literal `<p>` tags as text. (c) **In comparison logic**, normalize first: `from markupsafe import escape; escape(input_str)` produces the same shape the field stores. Bit us 2026-05-24 testing the lock-screen tagline source (`_lock_company_payload` reads `res.company.report_header`); the test that wrote a plain string and asserted equality failed because the value came back wrapped. The fix was to delete the brittle equality test — the helper's responsibility is just "use the field's value when present, else fall back," which is covered by the empty-field test. Generalizes to ANY HTML-typed Odoo field. Distinct from the `mail.template.body_html is Markup + jsonb` gotcha noted earlier in this file — that's about Markup objects vs strings; this is about the sanitizer wrapping plain strings on write.
+23. **`res.users.group_ids` vs `all_group_ids` for domain filters**: in Odoo 19, `res.users` carries TWO M2M-to-`res.groups` fields and they have different membership semantics. `group_ids` is the user's DIRECTLY-assigned groups (what the user record literally wrote). `all_group_ids` is the TRANSITIVE set — direct groups PLUS every group implied via `implied_ids` chains. **For domain filters on user pickers** (e.g. "show users who can act as a Quality Manager"), ALWAYS use `all_group_ids`, never `group_ids`. An Owner user only carries `group_fp_owner` directly; the QM capability comes via `implied_ids → group_fp_quality_manager`, so a `domain="[('group_ids', 'in', [ref('...quality_manager')])]"` excludes Owners and the picker looks empty. Use `domain="[('all_group_ids', 'in', [ref('...quality_manager'), ref('...owner')])]"` instead. Compute helpers (`@api.depends('group_ids')`) and write vals (`{'group_ids': [(4, gid)]}`) still use `group_ids` because those operate on direct assignments — only domain filters need the transitive set. Bit us 2026-05-24 on the CGP DO + Nadcap Authority pickers on `res.company`. Same gotcha applies to ANY domain that needs "does this user effectively have role X" semantics across user-facing pickers, ACL rules, server actions, and search filters.
+24. **`env.get('model.name')` returns an EMPTY recordset (falsy), NOT None — never use it as a presence check**: `self.env.get('fp.notification.template')` returns `fp.notification.template()` (empty recordset) when the model IS registered. Empty recordsets are falsy in Python, so `if not Template: return` silently exits even when the model exists and the call should proceed. Same gotcha for `env.get('any.model')` — they all return empty recordsets. **Fix: use the membership check first, then index:**
+```python
+if 'fp.notification.template' not in self.env:
+    return  # model not installed
+Template = self.env['fp.notification.template']
+# now Template is the model class; use it
+```
+The `Template.sudo()._some_classmethod()` call works on the empty recordset because `@api.model` methods run on the class. The breakage is purely the truthy-check. Bit us 2026-05-25 deploying `_fp_schedule_cert_activity` — the helper hit `env.get(...)` and immediately returned without ever attempting `activity_schedule`, so the QM never got their Issue-CoC activity. Took a monkey-patch trace through the helper to surface, because the function was silently no-oping with no exception. Same pattern likely scattered in any code that gates on `if env.get(...): ...` — grep for it.
+
+25. **`mail.template` data files validate templates at PARSE time — only reference CORE-module fields on the target model**: when Odoo loads a `<record model="mail.template">` from XML, it eagerly RENDERS the `subject`/`body_html` once against a sample `object` to validate the inline_template renders cleanly. If the template references a field defined in a DOWNSTREAM module (one that loads AFTER the data-file's home module), the field isn't on the model yet and you get `AttributeError: 'fp.job' object has no attribute 'X'` → `ParseError: Failed to render inline_template template` → module install/upgrade ABORTS. Bit us 2026-05-25 deploying the cert authority templates: `fusion_plating_notifications` loads BEFORE `fusion_plating_jobs` in dep order, and the templates referenced `object.display_wo_name` and `object.part_catalog_id` (both added by `fusion_plating_jobs` via `_inherit`). Even though the columns exist in the DB from previous installs, the Python class hadn't registered the field yet at parse time. **Fix:** mail.template files in upstream modules must only reference fields defined in the SAME module's classes or earlier-loading deps. For `fp.job` references in `fusion_plating_notifications/data/`, that means CORE-only fields: `name`, `partner_id`, `qty_done`, `recipe_id`, `state`, `date_*`, `company_id` — NOT `display_wo_name`, `part_catalog_id`, `customer_spec_id`, `delivery_id`, `portal_job_id` (all jobs-module fields). Same trap for any other cross-module template (`account.move`, `sale.order`, `stock.picking`). **Two structural alternatives** if you really need downstream fields: (a) move the mail.template + fp.notification.template data records into the downstream module so they load after the field is registered (cleanest); (b) compute the value in the calling Python code and pass via `email_values` to the dispatch — no template-time rendering.
 
 ## Naming
 - **New custom models** (post-2026-04): `fp.*` prefix (e.g. `fp.part.catalog`, `fp.certificate`)
@@ -372,7 +551,7 @@ Spec: [docs/superpowers/specs/2026-05-22-shopfloor-tablet-redesign-design.md](do
 Plan: [docs/superpowers/plans/2026-05-22-shopfloor-tablet-redesign-plan.md](docs/superpowers/plans/2026-05-22-shopfloor-tablet-redesign-plan.md)
 
 **Three OWL client actions** (registered under `registry.category("actions")`):
-- `fp_shopfloor_landing` — Workstation kanban entry. Station-scoped or All-Plant mode toggle. Tap a card → JobWorkspace. Replaces the legacy `fp_shopfloor_tablet` and folds in `fp_plant_overview`.
+- `fp_plant_kanban` — sole Shop Floor surface as of 2026-05-25. One card per `fp.job` grouped into 9 fixed columns. Inline QR scanner (camera + wedge text drawer) + station pairing via `/fp/landing/pair_work_centre`. Tap a card → JobWorkspace. (The legacy `fp_shopfloor_landing` component was deleted entirely on 2026-05-25 — its inline QR feature was ported here. The earlier `fp_shopfloor_tablet` and `fp_plant_overview` xmlids still exist but their `tag` re-points at `fp_plant_kanban` for bookmark back-compat.)
 - `fp_job_workspace` — Full-screen single-WO surface. Sticky header (WO #, customer, qty, workflow chip), sticky 9-stage workflow bar, step list with GateViz blockers, side panel (spec/attachments/chatter), sticky action rail (Hold/Note/Milestone). Opens from kanban tap, smart button, QR scan, or manager card tap.
 - `fp_manager_dashboard` — Manager Desk with 4 sibling tabs: **Workflow Funnel** (default), **Approval Inbox**, **Plant Board** (existing 3-column), **At-Risk** (trending late + hold reasons + bottleneck heatmap).
 
@@ -410,7 +589,12 @@ Plan: [docs/superpowers/plans/2026-05-22-shopfloor-tablet-redesign-plan.md](docs
 **Deprecated but still live** (cleanup is Phase 5):
 - OWL components: `fp_shopfloor_tablet`, `fp_plant_overview` — registered but no menu points at them
 - Endpoints: `/fp/shopfloor/tablet_overview`, `plant_overview`, `queue` — marked DEPRECATED with INFO log lines, bodies intact for back-compat
-- `/fp/shopfloor/plant_overview/move_card` is **NOT** deprecated — the new Landing component uses it for drag-and-drop
+- `/fp/shopfloor/plant_overview/move_card` is **NOT** deprecated — the new plant kanban uses it for drag-and-drop
+
+**Retired entirely 2026-05-25** (do NOT re-introduce):
+- OWL component `fp_shopfloor_landing` + its JS / XML / SCSS files — deleted. The inline QR scanner (text/wedge drawer + camera component) was ported into `plant_kanban`. The landing resolver always returns `action_fp_plant_kanban` for technicians + shop managers regardless of the orphaned `fusion_plating_shopfloor.layout` ir.config_parameter.
+- The `/fp/landing/kanban` endpoint is no longer used by any live client (was only consumed by `fp_shopfloor_landing`). The new endpoint is `/fp/landing/plant_kanban`. Don't accidentally bind a new client to the old one.
+- Station pairing via `localStorage[fp_landing_station_id]` is gone — pairing now writes `res.users.paired_work_centre_ids` server-side via the new `/fp/landing/pair_work_centre` endpoint, and the kanban reads it back via `request.env.user.paired_work_centre_ids[:1]`. Per-tablet localStorage pairing won't survive a browser cache wipe; per-user server-side pairing does.
 
 **Old patterns to avoid:**
 - Don't read `fp.job.name` for display — use `display_wo_name` everywhere on tablet/dashboard
@@ -418,6 +602,143 @@ Plan: [docs/superpowers/plans/2026-05-22-shopfloor-tablet-redesign-plan.md](docs
 - Don't add `web.assets_web_dark` entries to the manifest — Odoo 19 auto-compiles `web.assets_backend` SCSS into both bundles
 - Don't bypass `_fp_should_block_predecessors()` when computing step blockers — keep `blocker_kind=predecessor` logic in sync with `can_start`
 
+## Shop Floor — Plant View kanban (2026-05-23 redesign)
+
+**Sole Shop Floor surface** for every install as of 2026-05-25. The
+legacy per-step kanban (`fp_shopfloor_landing`) was deleted the same
+day, after porting its inline QR scanner into plant_kanban. The
+`ir.config_parameter['fusion_plating_shopfloor.layout']` flag is now
+orphaned — flipping it has no effect on the landing surface. The
+setting UI stays for one release cycle so it can be ripped out in a
+separate sweep without breaking migrations.
+
+**Why redesign:** the per-step kanban produced one card per recipe step
+per column, so a 14-step recipe spawned 9+ cards for ONE job across the
+board. With 17 active jobs the board showed 100+ duplicate cards across
+narrow columns. The new design is **one card per `fp.job`** at the
+**department level** — recipe step count no longer drives layout width.
+
+**Spec:** `docs/superpowers/specs/2026-05-23-shopfloor-plant-view-design.md`
+**Plan:** `docs/superpowers/plans/2026-05-23-shopfloor-plant-view-plan.md`
+
+### Layout — 9 fixed columns in process sequence
+
+`Receiving → Masking → Blasting → Racking → Plating → Baking →
+De-Racking → Final inspection → Shipping`
+
+Columns are first-class — they always render in this exact order, never
+reorder, never collapse when empty. Driven by `fp.work.centre.area_kind`
+Selection (added 2026-05-23). Each `fp.job.step.area_kind` is computed
+(stored) from `work_centre.area_kind` with a fallback to a step-kind
+dispatch table (`_STEP_KIND_TO_AREA` in `fusion_plating_jobs/models/fp_job_step.py`).
+
+**Spec D3:** all wet-line steps (Soak Clean, Electroclean, Acid Dip,
+Etch, Desmut, Zincate, Rinse, E-Nickel, Chrome, Anodize, Black Oxide,
+Drying) roll up into the **Plating** column. The tank chip on the card
+distinguishes them.
+
+**Spec D4:** De-Masking folds into De-Racking (no separate column).
+
+**Spec D5:** Contract Review (paperwork) cards live in Receiving with a
+purple "📋 QA-005" chip — they're admin gates, not physical work.
+
+### Card state catalog — 13 mutually-exclusive states
+
+`fp.job.card_state` is a stored Char computed in `_compute_card_state`
+(see `fusion_plating_jobs/models/fp_job.py`). Explicit precedence
+dispatch matching spec §6.2 — first match wins:
+
+`no_parts → on_hold → awaiting_signoff → awaiting_qc → bake_due →
+predecessor_locked → idle_warning → done → contract_review →
+running_mine/running → ready_mine/ready`
+
+Each state has a distinct background tint + left-border color + chip +
+mini-timeline marker color. See `_plant_card.scss` for the mapping. The
+"mine" variants (`ready_mine`, `running_mine`) light up only when the
+active step's work centre is in `res.users.paired_work_centre_ids` (the
+M2M holds one row in MVP, mirrors the existing single-station picker).
+
+### Backend — single endpoint, denormalized payload
+
+`/fp/landing/plant_kanban` (controller in
+`fusion_plating_shopfloor/controllers/plant_kanban.py`) returns
+`{ok, mode, paired_station, kpis, columns, cards}` in one JSONRPC call.
+Frontend has zero per-card RPCs — every card field comes pre-formatted
+from the controller's `_render_card`. State-chip text (with elapsed
+times, operator names, hours-idle) is interpolated server-side.
+
+### Frontend — OWL component tree
+
+```
+FpPlantKanban (client action 'fp_plant_kanban')
+└── FpTabletLock (PIN gate wrapper)
+    ├── PlantHeader (KPIs + filter chips + mode toggle + station picker)
+    └── Board (9 × Column)
+        ├── FpColumnHeader (with 'You're here' badge for paired column)
+        └── FpPlantCard[] (each with FpMiniTimeline)
+```
+
+Polls every 10s. Filter state persists in localStorage. All 13 card
+states styled via `.state-<name>` CSS modifier classes on a single
+shared `.o_fp_plant_card` base. The mini-timeline renders 9 colored
+dots driven by `fp.job.mini_timeline_json` (Python emits the array
+shape — frontend just maps state → CSS class).
+
+### Critical implementation gotchas (project rules applied)
+
+- **OWL templates only expose `Math` as a JS global** (Rule 20). All
+  coercion (String, Number, parseInt) MUST happen in JS — `tag_chip_class()`
+  / `progress_style` etc. live in plant_card.js, not in the XML.
+- **SCSS @import is forbidden** (Rule 8). `_plant_tokens.scss` loads
+  FIRST in the manifest's `web.assets_backend`; subsequent component
+  partials get the `$plant-*` vars via the concatenated bundle.
+- **Dark mode** via `$o-webclient-color-scheme == dark` compile-time
+  branch in `_plant_tokens.scss` (NOT runtime class selectors).
+
+### How to switch back to legacy
+
+```sql
+UPDATE ir_config_parameter SET value = 'legacy'
+ WHERE key = 'fusion_plating_shopfloor.layout';
+```
+
+Or use Settings → Fusion Plating → Shop Floor Layout. Both surfaces
+write the same `ir.config_parameter` key.
+
+### Legacy-action redirect (general rule for OWL component swaps)
+
+When replacing an OWL client-action component with a new one, **don't
+just register the new action's XMLID**. There are usually 2-5 legacy
+`ir.actions.client` data records scattered across the module pointing
+at the old tag (`action_fp_plant_overview`, `action_fp_shopfloor_tablet`,
+etc. — every "old bookmarks keep working" record). The landing-action
+resolver only sees one entry point. Bookmarks, breadcrumbs, QR-scan
+landings, and "Plant Overview" / "Tablet Station" menu items go
+through the OTHER actions and load the old component.
+
+**Fix: change every legacy data record's `tag` to the new tag.** Grep
+the views/ and data/ dirs for the old tag, and update each `<field
+name="tag">` to the new one. The old OWL component stays registered
+(no code removed), but no `ir.actions.client` row points at it
+anymore. Caught 2026-05-23 when the plant-view rollout dispatched
+the resolver correctly but a user clicking via the legacy "Shop Floor"
+menu still saw the per-step kanban — `action_fp_shopfloor_tablet`
+and `action_fp_plant_overview` were both still hard-coded to
+`fp_shopfloor_landing` tag.
+
+**Also grep JS for hardcoded `doAction({tag: ...})` calls** — XML
+data records are only half the story. OWL components that wire up
+"Back" buttons / navigation often hardcode the destination tag in
+JS (e.g. `this.action.doAction({type: "ir.actions.client", tag:
+"fp_shopfloor_landing", target: "current"})`). These bypass the
+data layer entirely, so the redirect trick above doesn't cover
+them. Caught 2026-05-24 — the Job Workspace `onBack()` still
+pointed at `fp_shopfloor_landing`, so tapping a card in the new
+plant kanban → opening the workspace → clicking Back dropped the
+user into the deprecated per-step kanban. Fix: `grep -rn
+'tag: ["\x27]<old_tag>' static/src/js/` before considering the
+swap complete; rewrite every match to point at the new tag.
+
 ## Deployment
 
 ### odoo-entech (LXC 111 on pve-worker5)
@@ -1132,6 +1453,9 @@ Each script is self-contained — builds a fresh SO + job, walks the scenario, a
 | **S19** | Lisa uploads Fischerscope X-Ray thickness PDF to QC; CoC ships without it as page 2 — and even after the back-end merge worked, operators couldn't *see* in the cert form whether the merge would happen | Existing merge logic lived in uninstalled `fusion_plating_bridge_mrp` (keyed off `mrp.production` — gone with Sub 11). Post-Sub-11 cert path rendered CoC only; Fischerscope PDF stayed orphaned on the QC record. Even after Phase 1 fix shipped, the cert form had **zero** indicator that a thickness PDF was on file or had been merged → user reported "I did not see anything in the certification issue" | **Phase 1 (back-end merge):** Ported merge to `fp.certificate._fp_merge_thickness_into_pdf`. New `_fp_render_and_attach_pdf` wraps cert PDF generation: renders the CoC via QWeb, then looks up the linked `fusion.plating.quality.check` (`x_fc_job_id → fp.job → QC`), finds the most recent passed QC with `thickness_report_pdf_id`, merges via `pypdf.PdfWriter.append()` (PyPDF2 `PdfMerger` fallback), posts chatter audit `Fischerscope thickness report from QC <name> appended to CoC PDF.`. Hooked into `action_issue` so the multi-page PDF lands on `attachment_id` automatically. **Phase 2 (UI surface):** Added 3 computed fields on `fp.certificate` (in `fusion_plating_jobs`): `x_fc_thickness_qc_id` (linked QC), `x_fc_thickness_pdf_id` (Fischerscope PDF), `x_fc_thickness_status` (`none` / `pending` / `merged`). Cert form now shows: (1) coloured banner above the title — blue "Will Append on Issue" / green "Merged" / amber "No PDF — operator action required"; (2) two new smart buttons (Plating Job, Fischerscope status); (3) new "Thickness Report (Fischerscope)" notebook tab with clickable PDF preview + step-by-step instructions when none uploaded | `fusion_plating_certificates 19.0.5.2.0`, `fusion_plating_jobs 19.0.6.20.0` | `bt_s19_fischer_merge.py` (asserts both pre-Issue `pending` + post-Issue `merged` status flips) |
 | **S20** | Tablet Station UX hardening — three real-world UX gaps surfaced during a persona walk on the Tablet + Manager Desk client actions | (a) **Scrap reason dropped**: `/fp/shopfloor/bump_qty_scrapped` accepted operator's typed reason via `window.prompt`, passed it through context as `fp_scrap_reason` — but `fp.job.write` never read it, so the auto-spawned Hold's description had the generic "OPERATOR: replace this text with the actual reason" placeholder instead of what Carlos typed. Audit trail lost what just happened on the floor. (b) **KPI/panel mismatch**: tablet KPI strip showed plant-wide totals ("Quality Holds: 12") but the Holds panel below was scoped to the operator's own jobs (might show 0). Operator stares at a big red 12, scrolls down, sees nothing — confused/distrustful. (c) **UserError stack-trace leak**: when `start_wo` hit an S14 predecessor lock (or any other `button_start`-side guard), the raw `UserError` propagated through the JSON-RPC handler and operator got a Python stack-trace dialog instead of the nice `setMessage("...", "danger")` flash. Same hole on `stop_wo`, `start_bake`, `end_bake`, `mark_gate`, `bump_qty_done`, `bump_qty_scrapped`. | (a) `fp.job.write` now reads `self.env.context.get('fp_scrap_reason')` and prepends `Operator reason: <text>` to the Hold description so the audit row captures what the operator actually typed. (b) Tablet KPI strip now reuses `my_job_ids_for_kpi` (the operator's own steps) for `awaiting_bakes`, `bake_in_progress`, `missed`, `open_holds` — same scope as the panels below, so the strip never lies. Manager dashboard keeps its own plant-wide KPI set. (c) Wrapped every action endpoint in `try: ... except UserError as e: return {'ok': False, 'error': str(e.args[0])}` — operator now gets the clean `setMessage` flash with the real guard text ("Step 'X' requires predecessors done first…") instead of a stack-trace popup. | `fusion_plating_jobs 19.0.6.22.0`, `fusion_plating_shopfloor 19.0.24.4.0` | persona walk via `sim_tablet_actions.py` + `sim_reverify.py` (asserts: typed reason ends up in hold.description, KPI=panel for holds, `start_wo` returns `{ok:False, error:"..."}` for locked step) |
 | **S20** | **Tablet usability pass** — operators were squinting at the tablet, scanning back-and-forth between recipe binders and the screen because the tablet showed step names but no targets, no live timer, no predecessor visibility. QC fail left parts in limbo with no Hold record. Manager Desk showed feel-good KPIs but hid the compliance bombs (missed bakes, stale steps, locked steps, holds, pending QC missing PDF) | Tablet `My Queue` rows had no `instructions`, `thickness_target`, `dwell_time_minutes`, `bake_setpoint_temp`, `requires_signoff` — operators kept scanning the QR code just to read the bake temperature. Steps with `requires_predecessor_done=True` (S14) showed a green Start that always failed with a UserError. Active step "duration" was a stale number that only refreshed every 30s. Holds and bake windows showed plant-wide noise from other crews. **No banner alerted Carlos when his job had a pending QC** (Lisa was not called → QC sat for hours). **No way to bump qty_done or scrap from the tablet** → S17 hold auto-spawn never fired because operators didn't update the field. **`action_fail` on QC marked the check failed but spawned no Hold** — AS9100 disposition trail broken. **Manager Desk KPIs were missing 7 compliance metrics**: stale paused/in-progress steps (cron data), missed bake windows, open holds, predecessor-locked steps, pending QCs, QCs missing Fischerscope PDF, draft cert pipeline | **Carlos's Shopfloor Tablet** — every queue row now carries the recipe-author fields (instructions snippet, thickness target chip, dwell-time chip, bake-temp chip, sign-off badge) so operators read the targets inline. Predecessor-blocked steps render with a 🔒 lock icon, an "Awaiting [step name]" notice, and a disabled `Locked` button (no more Start-then-fail). Active step now shows a **live ticking HH:MM:SS clock** (1s interval, computed from `date_started_iso` JS-side; flips to red on >1.5× planned duration) plus `+1 Done` and `Scrap` buttons that hit two new endpoints (`/fp/shopfloor/bump_qty_done`, `/fp/shopfloor/bump_qty_scrapped` — scrap prompts for reason and S17 auto-spawns the Hold). New **Pending QC banner** lists open QCs for my jobs with line-progress + Fischerscope-PDF status badge, and a tap deep-links into Lisa's mobile QC checklist. Holds and bake windows are now **scoped to my jobs first** (fall back to facility-wide for managers). **QC checklist** — `action_fail` now auto-creates a `fusion.plating.quality.hold` with `hold_reason='qc_failure'` (new selection value), populated description listing the failed checks, idempotent on retry. **Manager Desk** — 7 new clickable compliance KPI tiles: Missed Bakes (S15), Open Holds (S17 + QC fail), Stale Steps (S10/S16 cron data), Locked Steps (S14), Pending QC + "X need PDF" (S19 + missing-Fischerscope), Draft Certs + "Y today" (cert pipeline). Each tile drills into a list filtered to the relevant exception | `fusion_plating_shopfloor 19.0.24.3.0`, `fusion_plating_quality 19.0.4.8.0` | `sim_tablet_walk.py`, `sim_timer_pred_test.py`, `sim_qc_fail_hold.py`, `sim_manager_qc_fail.py` (one-off persona walkthroughs) |
+| **S21** | Riya finished steps on WO-30051 without filling in mandatory recipe-author prompts — Incoming Inspection skipped "Take and Upload Photos" (1/5 missed), Check Sulfamate Nickel Area skipped both masking-verification booleans (2/3 missed). AS9100 audit trail broken on a per-step basis. | (a) `_fp_has_uncaptured_step_inputs` returned False as soon as ANY move with input values existed since `date_started` — too coarse, let operators clear the dialog re-open by saving a single prompt. (b) `button_finish` had NO gate enforcing required step_input coverage — only Contract Review + Receiving gates fired. (c) OWL `Record Inputs` dialog `onSave()` had no client-side check for required prompts either, so operators got zero feedback when leaving fields blank. (d) Also caught: `fp_job_step.py` had **two `def button_finish` in the same class** — Python silently kept only the second definition, so the bake.window auto-spawn + duration-overrun warning at line 596 had been dead code for the entire WO-30051 era. | **Server gate** — new `_fp_check_step_inputs_complete()` on `fp.job.step` raises `UserError` listing every missing required step_input by name. Hooked into `button_finish` ahead of the existing Contract Review + Receiving gates. New helper `_fp_missing_required_step_inputs()` returns the recordset of required prompts with NO recorded value across any move from this step (centralised — used by both the gate and the dialog re-open helper). `_fp_has_uncaptured_step_inputs()` tightened to delegate to the new helper. **Client gate** — `onSave()` on `FpRecordInputsDialog` mirrors the server check when `advanceAfter=true` (Finish & Next path) so operators see a sticky red "Cannot finish step — N required prompts missing: ..." notification instantly rather than after a server roundtrip. Partial saves via the per-row Record button (`advanceAfter=false`) remain unblocked — operators can still capture progress and come back to fill the rest. **Manager bypass** — `fp_skip_required_inputs_gate=True` (documented deviations / paper-form catch-up); posts chatter audit naming the user. **Dead-code merge** — the duplicate `button_finish` at line 596 was deleted; its bake.window auto-spawn + duration-overrun chatter logic was folded into the canonical `button_finish` (which now runs in order: required-inputs gate → CR gate → receiving gate → `super()` → post-finish side effects). **Critical lesson — never put two `def <name>` in the same `models.Model` class body**. Python silently keeps the last one; the earlier definition becomes dead code with no warning. Always grep for duplicates after any structural edit on a long model file. | `fusion_plating_jobs 19.0.10.22.0` | Smoke: `step._fp_missing_required_step_inputs()` on any in_progress step returns the prompt recordset that would block finish. Server: try `step.button_finish()` on a step with required prompts unrecorded — should raise UserError listing them. Manager bypass: `step.with_context(fp_skip_required_inputs_gate=True).button_finish()` succeeds + posts audit. |
+| **S22** | Deep-audit finding F1 (2026-05-23) — `fp.job.step.requires_signoff` was 100% unenforced on entech: 42 of 42 done steps with the field set had `signoff_user_id IS NULL`. Recipe authors believed they'd gated aerospace / Nadcap steps; reality was the field was decorative. Pre-Sub-11 the `mrp.workorder.x_fc_signoff_user_id` had working logic, but Sub 11's MRP cutout removed bridge_mrp without porting the gate. | `signoff_user_id` was defined `readonly=True` on `fp.job.step` (from `fusion_plating/models/fp_job_step.py`) but **no code anywhere wrote to it**. No autosign on finish, no UI button, no `action_signoff`. Deep audit caught this because the 42/42 = 100% NULL ratio is the dead giveaway — when a "required" field has zero non-NULL rows across 42 records, the field's enforcement code is missing entirely. | **Three-piece fix on `fp.job.step`**: (1) `_fp_autosign_if_required()` — auto-sets `signoff_user_id = env.user.id` for the user clicking Finish, idempotent (preserves a supervisor's pre-sign via `action_signoff`). (2) `_fp_check_signoff_complete()` — raises `UserError` when `requires_signoff=True` and `signoff_user_id` is still NULL after the autosign helper has run (i.e. migration scripts, background crons with no env.user). (3) `action_signoff()` — explicit sign-off action for the case where a supervisor reviews and signs BEFORE the operator clicks Finish. Same-user re-click is a no-op; a DIFFERENT user re-signing overwrites the prior signer and posts a chatter reassignment ("Sign-off on step X reassigned from A to B"). Both helpers hook into `button_finish` AFTER `_fp_check_step_inputs_complete` and BEFORE the Contract-Review gate. **Manager bypass** — `fp_skip_signoff_gate=True` (documented deviations); posts chatter naming the user. **Lesson — for ANY "required" Boolean field that gates downstream behaviour, ALWAYS deep-audit the enforcement path: search the codebase for writes to the gated field, not just the boolean.** If zero writes exist, the gate is structural / decorative only. Grep the codebase periodically for `_check_*` helpers whose triggering field has no inverse writer. | `fusion_plating_jobs 19.0.10.23.0` | Verified end-to-end on entech: autosign sets signoff_user_id, gate raises UserError with the right message, bypass posts chatter audit, action_signoff sets + posts chatter, and the S21 required-inputs gate still fires (no regression). |
+| **S23 (shipped)** | Deep-audit bonus finding (2026-05-23) — `fp.job.step.requires_transition_form` had the same dormant-field shape as S22's signoff bug. The bypass context flag `fp_skip_transition_form` was already wired into the move controller's audit trail, but **no actual gate ever fired** because `_blockers_for_move` only enumerated `rack_required` + `predecessor_lock`. 0 of 286 moves on entech had this set (recipe authors hadn't enabled it), so no current audit gap — but the next recipe author who flips the toggle would discover the same cosmetic-only behaviour Riya found on S21. Caught preventively rather than reactively. NB: numbering conflicts with the open-scenarios list (also lists S23) — accept; the open list will be renumbered in a future doc-cleanup pass. | (a) `_blockers_for_move` in `fusion_plating_shopfloor/controllers/move_controller.py` had no `transition_form_required` case, only rack + predecessor. (b) The Move Rack controller `_do_move_rack_commit` didn't capture transition prompts at all — even if `requires_transition_form` were enforced on Move Parts, rack moves silently bypassed it. (c) The model layer `fp.job.step.move` had no helper to compute "missing required transition inputs", so any backend caller (wizards, scripts) had no way to enforce the contract. | **Model layer** — added two helpers to `fp.job.step.move` (canonical location): `_fp_missing_required_transition_inputs()` returns the recordset of required transition_input prompts on `to_step.recipe_node_id` that have no captured value on the move. `_fp_check_transition_inputs_complete()` raises `UserError` listing the missing prompts, manager bypass via `fp_skip_transition_form=True` (consistent with the existing audit-trail flag, NOT a new flag name), posts chatter on the move record on bypass. **Controller wiring** — `move_parts_commit` calls the gate AFTER `_capture_prompt_value` (so the operator gets credit for whatever they filled in; rollback unwinds the move + values on failure). `move_rack_commit` pre-rejects with a clear message ("use Move Parts so the form can be filled in") because rack moves have no per-batch prompt-capture UI. **Design choice** — gate is invoked explicitly by callers rather than via `create()` override; values are written in a separate call after the move row, so a model-level `create()` hook would always misfire. Future backend wizards / scripts MUST call `_fp_check_transition_inputs_complete()` after capturing prompt values, or pass `fp_skip_transition_form=True` if intentionally bypassing. **Two-layer pattern lesson** — when a recipe-author flag (here `requires_transition_form`) has BOTH a quick path (Move Rack — no form UI) AND a rich path (Move Parts — full form UI), the quick path MUST either implement the form OR reject the operation. A silent quick-path bypass defeats the whole gate. | `fusion_plating 19.0.20.9.0`, `fusion_plating_shopfloor 19.0.30.3.0` | Verified live on entech: helpers callable, move-parts commit raises on missing required prompts, move-rack commit rejects up-front when `to_step.requires_transition_form=True`, manager bypass via context flag posts move-chatter audit. |
 
 ### Manager-bypass context flags
 
@@ -1145,6 +1469,9 @@ When you need to override a guard (documented customer deviation, emergency rewo
 | `fp_skip_bake_gate=True` | bake.window pending check on `button_mark_done` (S15) |
 | `fp_skip_predecessor_check=True` | requires_predecessor_done check on `button_start` (S14) |
 | `fp_skip_missed_window=True` | missed_window block on `bake.window.action_start_bake` (S6) |
+| `fp_skip_required_inputs_gate=True` | required step_input prompts check on `fp.job.step.button_finish` (S21). Posts chatter audit naming the user. |
+| `fp_skip_signoff_gate=True` | `requires_signoff` + `signoff_user_id` check on `fp.job.step.button_finish` (S22). Posts chatter audit naming the user. Note: button_finish auto-sets signoff_user_id to the finisher first (via `_fp_autosign_if_required`); this bypass only matters when even the autosign can't fire (migration scripts, background crons with no env.user). |
+| `fp_skip_transition_form=True` | `requires_transition_form` + required transition_input coverage check on `fp.job.step.move._fp_check_transition_inputs_complete` (S23). Also drops the existing rack-vs-transition-form pre-reject on `move_rack_commit`. Posts chatter audit on the move record. Manager-only — controller checks the `fusion_plating.group_fusion_plating_manager` membership before honoring the flag. |
 
 ### Daily / hourly crons added by battle tests
 
@@ -1156,13 +1483,13 @@ When you need to override a guard (documented customer deviation, emergency rewo
 
 ### Open scenarios — flagged for next session
 
-- **S21** — Operator clocks two steps simultaneously across different jobs (multi-tasking conflict)
-- **S22** — Bath chemistry drift mid-step — operator measures bath while plating, value out of spec; no alert on the step
-- **S23** — Wrong recipe attached — Carlos sees mismatch with the part he's holding; recovery path?
-- **S24** — Customer orders 100 parts spread across 3 jobs; one job's recipe gets edited — does it propagate to siblings?
-- **S25** — Hold-aging cron + 3-day escalation (flagged in original audit, not yet built)
-- **S26** — Calibration + permit-expiry cron (flagged in original audit, not yet built)
-- **S27** — FAIR detection on first-shipment to a new customer/part combo (flagged in original audit, not yet built)
+- **S23** — Bath chemistry drift mid-step — operator measures bath while plating, value out of spec; no alert on the step (renumbered from S22 when S22 was claimed for the signoff gate)
+- **S24** — Wrong recipe attached — Carlos sees mismatch with the part he's holding; recovery path?
+- **S25** — Customer orders 100 parts spread across 3 jobs; one job's recipe gets edited — does it propagate to siblings?
+- **S26** — Hold-aging cron + 3-day escalation (flagged in original audit, not yet built)
+- **S27** — Calibration + permit-expiry cron (flagged in original audit, not yet built)
+- **S28** — FAIR detection on first-shipment to a new customer/part combo (flagged in original audit, not yet built)
+- **S29** — Operator clocks two steps simultaneously across different jobs (multi-tasking conflict; renumbered from S21 → S28 → S29)
 
 ### Tablet UI / persona-coverage gaps (S20 audit follow-ups)
 
@@ -1398,6 +1725,8 @@ Customer feedback: "too many top-level menus" + "configuration is unorganized".
   - Settings → Fusion Plating → Plating Landing Page block (company default).
 - `fusion_plating_configurator`'s earlier menu_fp_root override (action_fp_sale_orders direct) was removed — core's resolver now owns the routing.
 - Pickable list is curated via inline `<field name="x_fc_pickable_landing" eval="True"/>` on action records — currently flagged: `action_fp_sale_orders`, `action_fp_quotations`, `action_fp_process_recipe`. Add more by tagging the relevant act_window record at its source.
+- **`x_fc_pickable_landing` lives on `ir.actions.actions` (BASE)** so the picker dropdown on `res.users.x_fc_plating_landing_action_id` can offer BOTH act_window records (Sale Orders, Quotations, Process Recipes) AND client-action records (Manager Desk, Plant Kanban, Quality Dashboard). The picker Many2one points at `ir.actions.actions` (not `act_window`); the domain `[('x_fc_pickable_landing', '=', True)]` filters across all action types. `_render_resolved()` on the base dispatches to the correct subclass by `type`. **Pickable accessibility compute MUST be `sudo()`'d** — non-admin users (Technician, Sales Rep) lack read access on `ir.actions.actions` and opening their own Preferences dialog would AccessError otherwise; the per-user `check_access_rights` per-action still runs unprivileged so the picklist filters correctly. Tag a new landing candidate by adding `<field name="x_fc_pickable_landing" eval="True"/>` to its `<record>` definition — works regardless of whether the model is `ir.actions.act_window` or `ir.actions.client`.
+- **Role-based dispatch** (Phase E): the resolver now reads `res.users` group membership and routes by precedence — Owner → Manager Desk; QM → Quality Dashboard; Manager → Manager Desk; Sales Manager → Sale Orders; Shop Manager → Plant Kanban/Workstation; Sales Rep → Quotations; Technician → Plant Kanban/Workstation. `_fp_workstation_action_for_layout()` reads `ir.config_parameter['fusion_plating_shopfloor.layout']` (v2 vs legacy) so flipping the flag retargets every Tech/Shop Manager on next page load. Per-user override still wins. Picklist domain is tightened via `res.users.accessible_landing_action_ids` (compute that runs `check_access_rights('read')` per pickable action) so a Tech can't pick "Manager Desk" they can't see.
 
 ### Phase 2 — Configuration sub-folder grouping (`fusion_plating` 19.0.11.1.0, commits `3641b78` + `62c1315` + `4671541`)
 

fusion_plating/docs/superpowers/handoffs/2026-05-25-express-orders-brainstorm-handoff.md

@@ -0,0 +1,160 @@
+# Express Orders — Brainstorming Handoff (2026-05-25)
+
+**Status:** Mid-brainstorming. Clarifying questions answered. NOT yet at "propose 2-3 architectural approaches" or "present design sections" stages.
+
+**Why this handoff exists:** Previous session ran on a Windows machine (the user works from a Mac via Tailscale). Browser preview kept fighting cross-network localhost issues. User asked to restart natively on Mac. This doc preserves everything the brainstorming had reached so the new Mac session resumes instantly without re-asking.
+
+**How to resume:** When the user opens Claude Code on their Mac and points it at this repo, kick off with:
+
+> "Resume the Express Orders brainstorming from `docs/superpowers/handoffs/2026-05-25-express-orders-brainstorm-handoff.md`. Skip the visual companion entirely — design in text using the Excel mockup the user already sent. Pick up at 'propose 2-3 architectural approaches'."
+
+---
+
+## What "Express Orders" is
+
+A new sale-order entry surface that will eventually replace the current Direct Order Wizard. UX inspiration: a customer-shared Excel mockup showing a spreadsheet-style flat entry — header grid on top with customer/PO/job#/material-process/lead-time/terms/delivery, line table in the middle with per-row Part-#/Description/Specification/Job#/Thickness/Masking-checkbox/Baking-pill/Notes/Qty/UOM/Price/Subtotal + per-line Upload-Drawing + Open-Part buttons, footer with sub-total/tooling/tax/currency-selector/grand-total.
+
+Goal: faster repeat-customer order entry. Type once on the line, no jumping to a separate part screen for routine work, every column inline.
+
+---
+
+## Clarifying questions ANSWERED
+
+| # | Question | Answer | Implication |
+|---|---|---|---|
+| 1 | Model strategy | **D — new view on existing `fp.direct.order.wizard`** | Reuse the 500+ lines of onchange / recipe-cloning / spec-auto-fill / thickness-carry / tax-seeding logic that already debugged. Add masking/baking/currency fields to the existing model. Write a new "Express" form view. Retire the old direct-order view. Open drafts seamlessly become Express Orders (same DB rows). |
+| 2 | Specification text storage | **Free-text on the part** — `default_specification_text` Text field on `fp.part.catalog` | Type once → saves to part. Next order for same part → auto-fills. Cell value writes to `sale.order.line.name` (customer-facing). Bypasses the structured `fusion.plating.customer.spec` model entirely — simpler. |
+| 3 | Per-line Job# column (ABC/DEF/GHJ) | **NEW per-line customer sub-job-ref field** | Header keeps `x_fc_customer_job_number` (e.g. 12345). Add NEW `x_fc_customer_line_ref` Char on sale.order.line. Both print on customer docs. |
+| 4 | Masking checkbox scope | **Both masking AND de-masking together** | Unchecking creates override(included=False) for every node where `default_kind` IN ('masking', 'de_masking'). Logical pairing — can't unmask what was never masked. |
+| 5 | Baking field shape | **Free-text input + auto-fill from part default** | Add `default_bake_instructions` Text on `fp.part.catalog`. Type once → saves. Next order → auto-fills. Empty cell = exclude baking node (override included=False on all baking-kind nodes). Non-empty cell = include baking node + write the text to `fp.job.step.instructions` for the bake step at job-creation time. |
+| 6 | Currency mechanic | **Pricelist-per-currency, labelled "Currency"** | Selector shows currencies the company has pricelists for. Picking USD → looks up company's USD pricelist → sets `sale.order.pricelist_id`. `currency_id` flows from there. Admin must configure one pricelist per currency. |
+| 7-14 | 8 default interpretations | **All 8 accepted** | PO Pending = keep existing flag + chase mechanism; Material Process = new informational Char; Upload Part Drawing = per-line button to part.drawing_attachment_ids; Create Part = per-line modal opening fp.part.catalog form; Lead Time = reuse min/max days; Blanket SO = reuse boolean; Delivery Method = reuse x_fc_delivery_method; phase-out path = both menus visible initially, retire old view after Express is stable on entech. |
+
+---
+
+## Exploration findings (already verified by reading source — these are GROUND TRUTH)
+
+### Existing `fp.direct.order.wizard` model
+- Persistent (not transient) — state machine `draft → confirmed → cancelled`
+- File: `fusion_plating_configurator/wizard/fp_direct_order_wizard.py`
+- Line model: `fp.direct.order.line` in `fusion_plating_configurator/wizard/fp_direct_order_line.py`
+- Creates SO in quotation state on confirm. Does NOT auto-confirm SO or auto-email.
+
+### Existing `sale.order.line` x_fc_* fields (verified — keep using these)
+- `x_fc_part_catalog_id` Many2one(fp.part.catalog)
+- `x_fc_internal_description` Text REQUIRED — Notes column maps here
+- `x_fc_description_template_id` Many2one
+- `x_fc_serial_ids` Many2many(fp.serial) + `x_fc_serial_id` (primary, computed)
+- `x_fc_thickness_range` Char — Thickness column maps here
+- `x_fc_revision_snapshot` Char (frozen at line save time)
+- `x_fc_process_variant_id` Many2one(fusion.plating.process.node) — recipe
+- `x_fc_save_as_default_process` Boolean
+- `x_fc_job_number` Char — shop's auto-sequenced ref (NOT customer's; that's the new x_fc_customer_line_ref)
+- `x_fc_customer_job_number` related from order
+- `x_fc_po_number` related from order
+- `x_fc_part_deadline` Date + offset_days + effective computes
+- `x_fc_archived` Boolean
+- `name` (Odoo standard) = customer-facing description — Specification column writes here
+
+### NEW fields the Express Orders feature must add
+On `sale.order.line`:
+- `x_fc_customer_line_ref` Char — per-line customer sub-job (the ABC/DEF/GHJ column)
+- `x_fc_masking_enabled` Boolean default=True — Masking checkbox
+- `x_fc_bake_instructions` Text — Baking free-text
+
+On `fp.part.catalog`:
+- `default_specification_text` Text — for Spec auto-fill
+- `default_bake_instructions` Text — for Baking auto-fill
+
+On `fp.direct.order.wizard` (header):
+- `material_process` Char — informational order-level tag (ENP-STEEL-HP-ADVANCED)
+
+On `fp.direct.order.line` (wizard mirror, to be carried to SO line on confirm):
+- `customer_line_ref` Char
+- `masking_enabled` Boolean default=True
+- `bake_instructions` Text
+
+### Existing `fp.job.node.override` model (verified — schema is exactly 3 fields)
+File: `fusion_plating_jobs/models/fp_job_node_override.py`
+- `job_id` Many2one(fp.job) required ondelete=cascade
+- `node_id` Many2one(fusion.plating.process.node)
+- `included` Boolean
+
+**No instructions-text override field.** For the bake free-text feature, do NOT extend this model — instead write the typed text to `fp.job.step.instructions` directly at job-creation time. Simpler, less schema churn.
+
+### Existing recipe model (`fusion.plating.process.node`)
+File: `fusion_plating/models/fp_process_node.py`
+- `default_kind` is a Char (line 526), not Selection — flexible
+- Values seen: `masking`, `de_masking`, `baking`, plating, inspection, contract_review, racking, etc.
+- `node_type` is a Selection (line 54): `opt_in`, `opt_out`, `mandatory`, `recipe`
+
+### Job-creation hook
+File: `fusion_plating_jobs/models/sale_order.py` — `action_confirm()` calls `_fp_auto_create_job()` which groups lines by recipe. New Express-Orders-driven overrides should be injected here:
+- Walk each SO line
+- Resolve the line's recipe
+- If `x_fc_masking_enabled == False`, create `fp.job.node.override(included=False)` for every node in recipe where `default_kind IN ('masking', 'de_masking')`
+- If `x_fc_bake_instructions` empty, create `fp.job.node.override(included=False)` for every node in recipe where `default_kind == 'baking'`
+- If `x_fc_bake_instructions` non-empty, write the text to `fp.job.step.instructions` for the baking step (find by recipe_node_id.default_kind == 'baking')
+
+### Currency
+- `sale.order.currency_id` related from `pricelist_id.currency_id` (Odoo native)
+- No multi-currency customisations in fusion_plating modules — using Odoo standard
+- Per the answer to Q6, the Express Orders feature adds a selector on the wizard that looks up the matching pricelist by currency code
+
+### `fp.part.catalog` (file: `fusion_plating_configurator/models/fp_part_catalog.py`)
+Verified key fields:
+- `x_fc_default_customer_spec_id` (added by quality module) — NOT used by Express Orders per Q2
+- `x_fc_default_thickness_range` Char
+- `description_template_ids` O2M(fp.sale.description.template) with internal + customer descriptions
+- `drawing_attachment_ids` M2M(ir.attachment) — Upload Part Drawing button writes here
+- `model_attachment_id` M2O — 3D model
+- `x_fc_certificate_requirement` Selection — inherit/none/coc/coc_thickness
+
+---
+
+## What's LEFT to do (resume here)
+
+1. ✅ Exploration complete
+2. ✅ Clarifying questions complete
+3. ❌ **Propose 2-3 architectural approaches** with the answered constraints baked in. Lead with recommendation. (Most of the architectural picture is already settled by Q1=D; this section should be brief — mostly the "where exactly does the recipe override logic live: in the wizard's `_prepare_order_vals`, or post-confirm in `_fp_auto_create_job`, or a model hook?")
+4. ❌ **Present design in sections**, get approval after each:
+   - Section 1 — Header layout + field-to-model mapping
+   - Section 2 — Line widget design (the spreadsheet table behavior)
+   - Section 3 — Masking + baking override flow at job creation
+   - Section 4 — Currency switcher mechanic
+   - Section 5 — Inline part create + drawing upload buttons
+   - Section 6 — Phase-out path for direct order
+5. ❌ **Write design doc** to `docs/superpowers/specs/2026-05-25-express-orders-design.md` and commit
+6. ❌ **Spec self-review** + user review gate
+7. ❌ **Transition to writing-plans** skill (after user approves spec)
+
+---
+
+## Lesson: SKIP the visual companion on this user's setup
+
+The user runs Claude Code from their **Mac** via Tailscale into a **Windows** machine (this `Home` host). Browser previews bound to `localhost` on the Windows side are unreachable from the Mac browser. The bash-script brainstorm server (port 65170) hit this. The Python http.server (port 8765) hit this. We spent 20 minutes fighting it.
+
+**Resolution:** the user said to switch to a native Mac Claude Code session entirely. On Mac the visual companion should "just work" — but consider whether it's necessary. The user already provided an Excel mockup as reference. Text-based design discussion using ASCII tables / structured lists is plenty for this feature. Don't push the visual companion unless the user explicitly asks for it.
+
+---
+
+## Recent in-flight work (NOT Express Orders, but on the same Windows host)
+
+For context: this Windows session also shipped these things today (2026-05-25) — they're DEPLOYED on entech but may need follow-up on the Mac:
+
+1. **Tablet PIN self-service** (cycle 4) — fully shipped, code 4018 last sent. `fusion_plating_shopfloor` 19.0.36.0.3. Three improvements during the day: SCSS undefined-variable bug fix, switch to `force_send=True`, mail template `email_from` aligned to mail-server `from_filter` (fixes M365 DMARC misalignment / delivery delay).
+2. **fp_shopfloor_landing removal** — entire OWL component deleted, QR scanner ported into `fp_plant_kanban`, all references cleaned up. Same module version above.
+3. **Tablet lock-screen orphan localStorage** — cleared `fp_landing_station_id` to fix empty-tiles bug.
+
+All committed to git on `main`. Pushed via the multi-remote (GitHub + Gitea). On Mac, you'll need to `git pull origin main` from the fresh local clone before doing anything.
+
+---
+
+## Files written this session that the new Mac session should know exist
+
+- `K:\Github\Odoo-Modules\fusion_plating\.claude\launch.json` — Mockups preview config (port 8765). Mac equivalent path will be the same but on local Mac filesystem.
+- `K:\Github\Odoo-Modules\fusion_plating\.claude\mockups\index.html` — 15KB layout-direction mockup with A/B comparison. Can be deleted (was for the failed Windows-side preview); if you want to show it on Mac it works fine.
+- `K:\Github\Odoo-Modules\fusion_plating\.superpowers\brainstorm\944-1779751836\` — dead bash-script brainstorm server directory; safe to delete.
+- This handoff doc.
+
+End of handoff.

fusion_plating/docs/superpowers/plans/2026-05-24-recipe-cleanup-plan.md

@@ -0,0 +1,784 @@
+# Recipe Cleanup + Receiving Enforcement 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:** Fix recipe 3620 ENP-ALUM-BASIC's duplicate-sequence bug, delete all 24 per-part clone recipes, backfill `kind=other` nodes via an extended name resolver, add an auto-classify hook on every node create/write, and make `no_parts` cards always land in the Receiving column.
+
+**Architecture:** One migration in `fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py` does all the data work in 5 phases (resequence 3620 → backfill kinds → delete clones → recompute step.area_kind → recompute job.active_step_id + card_state). Two code-side changes: extend `fp_resolve_step_kind()` with new aliases + parenthetical stripping, add `_fp_autoclassify_kind()` to `fusion.plating.process.node.create/write` so future authoring + recipe duplication self-correct.
+
+**Spec:** [docs/superpowers/specs/2026-05-24-recipe-cleanup-design.md](../specs/2026-05-24-recipe-cleanup-design.md)
+
+**Tech Stack:** Odoo 19, Python (ORM/migrations), PostgreSQL.
+
+---
+
+## File Inventory
+
+| Path | Responsibility |
+|---|---|
+| `fusion_plating/__init__.py` | Extend `_STARTER_KIND_BY_NAME` aliases; add parenthetical-strip to `fp_resolve_step_kind()`; expose `RESOLVER_KIND_TO_ACTIVE_KIND` map |
+| `fusion_plating/models/fp_process_node.py` | `_fp_autoclassify_kind()` helper + create/write hooks |
+| `fusion_plating/__manifest__.py` | Version bump to `19.0.21.3.0` |
+| `fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py` | NEW — 5-phase data migration |
+| `fusion_plating_jobs/__manifest__.py` | Version bump to `19.0.10.26.0` |
+| `fusion_plating_shopfloor/controllers/plant_kanban.py` | `no_parts` → receiving column override in `_resolve_card_area` |
+| `fusion_plating_shopfloor/__manifest__.py` | Version bump to `19.0.33.1.4` |
+
+---
+
+## Task 1: Extend `fp_resolve_step_kind()` with new aliases + parenthetical stripping
+
+**Files:**
+- Modify: `fusion_plating/__init__.py:208-304`
+
+- [ ] **Step 1: Add `re` to imports**
+
+At the top of `fusion_plating/__init__.py`, after the existing `import logging` line, add:
+
+```python
+import re
+```
+
+- [ ] **Step 2: Extend `_STARTER_KIND_BY_NAME`**
+
+Find the dict at line 208. Inside the dict (before the closing `}`), add the following keys (preserve the existing entries):
+
+```python
+    # 2026-05-24 — Recipe cleanup additions (live-step fix follow-up).
+    # Blasting variants
+    'blasting':                                'blast',
+    'bead blast':                              'blast',
+    'bead blasting':                           'blast',
+    'media blast':                             'blast',
+    'media blasting':                          'blast',
+    # Inspection variants the resolver didn't know
+    'adhesion test coupon':                    'inspect',
+    'adhesion testing':                        'inspect',
+    'corrosion testing':                       'inspect',
+    'lab testing':                             'inspect',
+    'check sulfamate nickel area':             'inspect',
+    'pre-measurements':                        'inspect',
+    'pre measurements':                        'inspect',
+    'hot water porosity':                      'inspect',
+    # Strip / chemical conversion / plugging (wet line)
+    'strip process':                           'wet_process',
+    'strip process - al':                      'wet_process',
+    'nickel strip - aluminum line':            'wet_process',
+    'chemical conversion':                     'wet_process',
+    'trivalent chromate conversion':           'wet_process',
+    'plug the threaded holes':                 'mask',
+    # Misc wet line variants seen on entech recipes
+    'air dry':                                 'dry',
+    'desmut':                                  'etch',
+    'soak clean':                              'cleaning',
+    'cleaner':                                 'cleaning',
+    'nickel strike':                           'plate',
+    'nickel strip':                            'plate',
+```
+
+- [ ] **Step 3: Add parenthetical stripping inside `fp_resolve_step_kind()`**
+
+Find the function around line 288. Replace its body:
+
+```python
+def fp_resolve_step_kind(name):
+    """Resolve a step name to a default_kind, tolerant of whitespace and
+    case. Used by both the seeder and the migration backfill so we don't
+    have two slightly-different lookup paths.
+
+    Handles parenthetical suffixes like "(Standard)", "(If Required)",
+    "(A-14 / A)" by stripping them before the second lookup attempt.
+
+    Returns the kind str or None when no match.
+    """
+    if not name:
+        return None
+    key = name.strip().lower()
+    if key in _STARTER_KIND_BY_NAME:
+        return _STARTER_KIND_BY_NAME[key]
+    # Parenthetical strip — "Masking (If Required)" → "Masking",
+    # "Incoming Inspection (Standard)" → "Incoming Inspection".
+    bare = re.sub(r'\s*\([^)]*\)\s*', ' ', key).strip()
+    if bare and bare != key and bare in _STARTER_KIND_BY_NAME:
+        return _STARTER_KIND_BY_NAME[bare]
+    # Gating "Ready for / Ready For" prefix — anything starting with that
+    # is a gating node regardless of the destination step name.
+    if key.startswith('ready for ') or key.startswith('ready '):
+        return 'gating'
+    return None
+```
+
+- [ ] **Step 4: Add `RESOLVER_KIND_TO_ACTIVE_KIND` translation map**
+
+Right after the `fp_resolve_step_kind` function (around line 305), add:
+
+```python
+# Translates the resolver's kind output to the active fp.step.kind.code
+# values. The resolver still returns the OLD vocabulary (cleaning,
+# electroclean, etch, rinse, strike, dry, wbf_test) which were
+# deactivated in 19.0.20.6.0 — those roll up to the active wet_process
+# kind. Other codes pass through 1:1.
+RESOLVER_KIND_TO_ACTIVE_KIND = {
+    # Wet-line kinds → wet_process (active rollup)
+    'cleaning':        'wet_process',
+    'electroclean':    'wet_process',
+    'etch':            'wet_process',
+    'rinse':           'wet_process',
+    'strike':          'wet_process',
+    'dry':             'wet_process',
+    'wbf_test':        'wet_process',
+    # 1:1 mappings (kind exists and is active)
+    'contract_review': 'contract_review',
+    'mask':            'mask',
+    'racking':         'racking',
+    'plate':           'plate',
+    'bake':            'bake',
+    'derack':          'derack',
+    'demask':          'demask',
+    'inspect':         'inspect',
+    'final_inspect':   'final_inspect',
+    'ship':            'ship',
+    'gating':          'gating',
+    'blast':           'blast',
+}
+```
+
+- [ ] **Step 5: Confirm import structure (no commit yet)**
+
+Run:
+```bash
+grep -n "^import re\|^from\|^import" fusion_plating/fusion_plating/__init__.py | head -5
+```
+Expected: `import re` appears before `from . import controllers`.
+
+Commit happens in Task 3.
+
+---
+
+## Task 2: Auto-classify hook on `fusion.plating.process.node`
+
+**Files:**
+- Modify: `fusion_plating/models/fp_process_node.py`
+
+- [ ] **Step 1: Find an insertion point near the existing `create/write/copy` methods**
+
+In [`fusion_plating/models/fp_process_node.py`](../../fusion_plating/models/fp_process_node.py), find the `copy()` method around line 789 (it's at the bottom of the FpProcessNode class). The autoclassify helper goes near it, and the create/write overrides slot in alongside copy.
+
+- [ ] **Step 2: Add the helper + create/write overrides**
+
+In `FpProcessNode`, add this block right before the `copy()` method at line ~787. Insert AFTER all the other fields/methods but BEFORE `copy()`:
+
+```python
+    # ---- Auto-classify kind from name (2026-05-24) ----------------------
+    # Safety net: when a node's kind is the catch-all 'other' AND its
+    # name resolves via fp_resolve_step_kind(), upgrade kind_id to the
+    # resolved active kind. Runs on create() and on write() when name
+    # or kind_id changes. Prevents recipe authoring + recipe duplication
+    # from silently leaving nodes as 'other' (which then routes them to
+    # the wrong Shop Floor column).
+    #
+    # Skip with context flag fp_skip_kind_autoclassify=True for admin
+    # workflows that need to keep kind=other despite a known name.
+
+    def _fp_autoclassify_kind(self):
+        """Upgrade kind_id when current is 'other' and name resolves."""
+        if self.env.context.get('fp_skip_kind_autoclassify'):
+            return
+        from odoo.addons.fusion_plating import (
+            fp_resolve_step_kind,
+            RESOLVER_KIND_TO_ACTIVE_KIND,
+        )
+        Kind = self.env['fp.step.kind']
+        other = Kind.search([('code', '=', 'other')], limit=1)
+        if not other:
+            return
+        for node in self:
+            if not node.name or node.kind_id != other:
+                continue
+            resolver_code = fp_resolve_step_kind(node.name)
+            if not resolver_code:
+                continue
+            target_code = RESOLVER_KIND_TO_ACTIVE_KIND.get(resolver_code)
+            if not target_code:
+                continue
+            target = Kind.search([('code', '=', target_code)], limit=1)
+            if target:
+                node.with_context(
+                    fp_skip_kind_autoclassify=True,
+                ).write({'kind_id': target.id})
+
+    @api.model_create_multi
+    def create(self, vals_list):
+        nodes = super().create(vals_list)
+        nodes._fp_autoclassify_kind()
+        return nodes
+
+    def write(self, vals):
+        res = super().write(vals)
+        if 'name' in vals or 'kind_id' in vals:
+            self._fp_autoclassify_kind()
+        return res
+
+```
+
+- [ ] **Step 3: Verify the file parses (no commit yet)**
+
+Run:
+```bash
+python3 -c "import ast; ast.parse(open('fusion_plating/fusion_plating/models/fp_process_node.py').read()); print('OK')"
+```
+Expected: `OK`.
+
+Commit happens in Task 3.
+
+---
+
+## Task 3: Version bump fusion_plating + commit Phase 1
+
+**Files:**
+- Modify: `fusion_plating/__manifest__.py`
+
+- [ ] **Step 1: Bump the version**
+
+In [`fusion_plating/__manifest__.py`](../../fusion_plating/__manifest__.py), change:
+
+```python
+'version': '19.0.21.2.0',
+```
+
+to:
+
+```python
+'version': '19.0.21.3.0',
+```
+
+- [ ] **Step 2: Commit Phase 1**
+
+```bash
+git add fusion_plating/fusion_plating/__init__.py \
+        fusion_plating/fusion_plating/models/fp_process_node.py \
+        fusion_plating/fusion_plating/__manifest__.py
+git commit -m "$(cat <<'EOF'
+feat(fusion_plating): extend resolver + auto-classify hook on process node
+
+Resolver (fp_resolve_step_kind) extensions:
+- New aliases: blasting/bead blast/media blast variants, adhesion
+  testing, corrosion testing, lab testing, strip process, chemical
+  conversion, trivalent chromate, plug the threaded holes, air dry,
+  desmut, soak clean, cleaner, nickel strike/strip
+- Parenthetical suffix stripping — "Masking (If Required)" resolves
+  through "masking", "Incoming Inspection (Standard)" through
+  "incoming inspection"
+- New RESOLVER_KIND_TO_ACTIVE_KIND map translates the resolver's
+  vocabulary (cleaning/electroclean/etch/rinse/strike/dry/wbf_test
+  → wet_process) so the resolver output lands on active kinds only
+
+Auto-classify hook on fusion.plating.process.node:
+- _fp_autoclassify_kind() upgrades kind_id when current is 'other'
+  AND name resolves via the resolver. Idempotent — never overrides
+  a non-'other' kind. Skip via context flag fp_skip_kind_autoclassify
+- Wired into create() and write() (only fires when name or kind_id
+  changed on write)
+- Side-effects: recipe duplication via copy() auto-corrects newly
+  copied nodes; Simple/Tree editor authoring auto-classifies as soon
+  as the name is saved
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: Write the 19.0.10.26.0 migration
+
+**Files:**
+- Create: `fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py`
+
+- [ ] **Step 1: Create the migration directory**
+
+```bash
+mkdir -p fusion_plating/fusion_plating_jobs/migrations/19.0.10.26.0
+```
+
+- [ ] **Step 2: Write the migration file**
+
+Create `fusion_plating/fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py`:
+
+```python
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1 (Odoo Proprietary License v1.0)
+"""19.0.10.26.0 — Recipe cleanup + per-part clone delete.
+
+Spec: docs/superpowers/specs/2026-05-24-recipe-cleanup-design.md
+
+Phases (in order):
+  1. Resequence recipe 3620 ENP-ALUM-BASIC operations + delete the
+     duplicate empty ENP-Alum Line sub_process (id 4056).
+  2. Backfill kind on all kind=other nodes via the extended
+     fp_resolve_step_kind() resolver + RESOLVER_KIND_TO_ACTIVE_KIND
+     translation.
+  3. Delete all 24 per-part clone recipes (name ILIKE '% — %').
+     CASCADE handles child nodes; SET NULL handles fp.job /
+     fp.job.step / fp.coating.config / fp.pricing.rule /
+     fp.part.catalog references.
+  4. Recompute fp.job.step.area_kind on all rows.
+  5. Recompute fp.job.active_step_id + card_state on in-flight jobs.
+
+All phases idempotent — re-running -u is safe.
+"""
+import logging
+
+from odoo.api import Environment, SUPERUSER_ID
+
+_logger = logging.getLogger(__name__)
+
+
+# Recipe 3620's ops in the desired final order. Maps the existing node
+# id (as documented in the spec) to its target sequence. The user
+# decided mask-first-then-rack per spec Section "Mask vs Rack order".
+RECIPE_3620_RESEQUENCE = [
+    # (node_id, new_sequence, expected_name)
+    (3853,  10, 'Contract Review'),
+    (3854,  20, 'Incoming Inspection (Standard)'),
+    (3877,  30, 'Masking'),
+    (3855,  40, 'Racking'),
+    (3858,  50, 'Ready for processing'),
+    (3859,  60, 'ENP-Alum Line'),
+    (3861,  70, 'De-Masking'),
+    (3864,  80, 'Oven baking'),
+    (3867,  90, 'De-racking'),
+    (4067, 100, 'Oven bake (Post de-rack)'),
+    (3873, 110, 'Post-plate Inspection'),
+    (3876, 120, 'Final Inspection'),
+]
+
+# Empty duplicate ENP-Alum Line sub_process on recipe 3620 (no
+# children — the real one is id 3859 with E-Nickel Plating as child).
+RECIPE_3620_DUPLICATE_TO_DELETE = 4056
+
+
+def migrate(cr, version):
+    env = Environment(cr, SUPERUSER_ID, {})
+
+    # ============================================================
+    # Phase 1 — Resequence recipe 3620 + delete duplicate sub_process
+    # ============================================================
+    Node = env['fusion.plating.process.node']
+    recipe_3620 = Node.browse(3620).exists()
+    if not recipe_3620:
+        _logger.warning(
+            '[recipe-cleanup] Recipe 3620 ENP-ALUM-BASIC not found; '
+            'skipping resequence phase'
+        )
+    else:
+        # Verify the expected nodes exist, then resequence them.
+        # We do this idempotently — only update if the sequence
+        # differs from the target.
+        renumbered = 0
+        for node_id, new_seq, expected_name in RECIPE_3620_RESEQUENCE:
+            node = Node.browse(node_id).exists()
+            if not node:
+                _logger.warning(
+                    '[recipe-cleanup] Recipe 3620: expected node %s '
+                    '("%s") not found; skipping',
+                    node_id, expected_name,
+                )
+                continue
+            if node.sequence != new_seq:
+                # Skip the autoclassify hook on this write (nothing
+                # changes about kind_id; we're only touching sequence).
+                node.with_context(
+                    fp_skip_kind_autoclassify=True,
+                ).write({'sequence': new_seq})
+                renumbered += 1
+        _logger.info(
+            '[recipe-cleanup] Recipe 3620: %s nodes resequenced',
+            renumbered,
+        )
+
+        # Delete the empty duplicate ENP-Alum Line sub_process.
+        dup = Node.browse(RECIPE_3620_DUPLICATE_TO_DELETE).exists()
+        if dup:
+            if dup.child_ids:
+                _logger.warning(
+                    '[recipe-cleanup] Duplicate sub_process %s has '
+                    '%s children — NOT deleting (safety check). '
+                    'Expected an empty node.',
+                    dup.id, len(dup.child_ids),
+                )
+            else:
+                dup.unlink()
+                _logger.info(
+                    '[recipe-cleanup] Deleted empty duplicate '
+                    'ENP-Alum Line sub_process (id %s)',
+                    RECIPE_3620_DUPLICATE_TO_DELETE,
+                )
+
+    # ============================================================
+    # Phase 2 — Backfill kind on all kind=other nodes via resolver
+    # ============================================================
+    from odoo.addons.fusion_plating import (
+        fp_resolve_step_kind,
+        RESOLVER_KIND_TO_ACTIVE_KIND,
+    )
+    Kind = env['fp.step.kind']
+    other_kind = Kind.search([('code', '=', 'other')], limit=1)
+    if not other_kind:
+        _logger.error(
+            '[recipe-cleanup] No "other" kind found; skipping kind '
+            'backfill phase'
+        )
+    else:
+        # Build a cache of code → kind.id so we don't search per-row
+        kind_by_code = {k.code: k.id for k in Kind.search([])}
+        affected_nodes = Node.search([
+            ('kind_id', '=', other_kind.id),
+            ('name', '!=', False),
+            ('node_type', 'in', ('operation', 'step', 'sub_process')),
+        ])
+        fixed = 0
+        for node in affected_nodes:
+            resolver_code = fp_resolve_step_kind(node.name)
+            if not resolver_code:
+                continue
+            target_code = RESOLVER_KIND_TO_ACTIVE_KIND.get(resolver_code)
+            if not target_code or target_code not in kind_by_code:
+                continue
+            node.with_context(
+                fp_skip_kind_autoclassify=True,
+            ).write({'kind_id': kind_by_code[target_code]})
+            fixed += 1
+        _logger.info(
+            '[recipe-cleanup] Phase 2: backfilled kind on %s nodes '
+            '(of %s currently kind=other)',
+            fixed, len(affected_nodes),
+        )
+
+    # ============================================================
+    # Phase 3 — Delete all 24 per-part clone recipes
+    # ============================================================
+    # Identify by name pattern. The configurator names clones
+    # "BASE_NAME — PART_NUMBER Rev X" with an em-dash separator.
+    # No base recipe uses em-dash in its name.
+    clone_recipes = Node.search([
+        ('node_type', '=', 'recipe'),
+        ('name', 'ilike', '% — %'),
+    ])
+    if clone_recipes:
+        # Log what we're about to delete for forensic visibility.
+        clone_names = [c.name for c in clone_recipes]
+        _logger.info(
+            '[recipe-cleanup] Phase 3: deleting %s clone recipes: %s',
+            len(clone_recipes),
+            ', '.join(clone_names[:10])
+            + (' …' if len(clone_names) > 10 else ''),
+        )
+        clone_recipes.unlink()
+        _logger.info(
+            '[recipe-cleanup] Phase 3: deleted %s clone recipes '
+            '(CASCADE removed their child nodes; FK SET NULL applied '
+            'to historical fp.job + fp.job.step references)',
+            len(clone_recipes),
+        )
+    else:
+        _logger.info(
+            '[recipe-cleanup] Phase 3: no clone recipes found '
+            '(already deleted on a prior run, or none exist)'
+        )
+
+    # ============================================================
+    # Phase 4 — Recompute area_kind on all fp.job.step rows
+    # ============================================================
+    # After Phase 2, many recipe nodes have new kinds. After Phase 3,
+    # some fp.job.step rows have NULL recipe_node_id (FK SET NULL'd
+    # when the clone got deleted). Recompute picks up the new kinds
+    # for active recipes and falls back to catch-all 'plating' for
+    # orphans (all historical / terminal jobs — won't show on board).
+    Step = env['fp.job.step']
+    steps = Step.search([])
+    if steps:
+        steps._compute_area_kind()
+        steps.flush_recordset(['area_kind'])
+    _logger.info(
+        '[recipe-cleanup] Phase 4: recomputed area_kind on %s steps',
+        len(steps),
+    )
+
+    # ============================================================
+    # Phase 5 — Recompute active_step_id + card_state on in-flight jobs
+    # ============================================================
+    Job = env['fp.job']
+    jobs = Job.search([
+        ('state', 'in', ('confirmed', 'in_progress')),
+    ])
+    if jobs:
+        jobs._compute_active_step_id()
+        jobs._compute_card_state()
+        jobs.flush_recordset(['active_step_id', 'card_state'])
+    _logger.info(
+        '[recipe-cleanup] Phase 5: recomputed active_step_id + '
+        'card_state on %s in-flight jobs',
+        len(jobs),
+    )
+```
+
+- [ ] **Step 3: Verify the file parses**
+
+Run:
+```bash
+python3 -c "import ast; ast.parse(open('fusion_plating/fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py').read()); print('OK')"
+```
+Expected: `OK`.
+
+---
+
+## Task 5: Version bump fusion_plating_jobs
+
+**Files:**
+- Modify: `fusion_plating_jobs/__manifest__.py`
+
+- [ ] **Step 1: Bump the version**
+
+In [`fusion_plating_jobs/__manifest__.py`](../../fusion_plating_jobs/__manifest__.py), change:
+
+```python
+'version': '19.0.10.25.0',
+```
+
+to:
+
+```python
+'version': '19.0.10.26.0',
+```
+
+- [ ] **Step 2: No commit yet — grouped with Task 6's commit.**
+
+---
+
+## Task 6: `no_parts` cards always show in Receiving column
+
+**Files:**
+- Modify: `fusion_plating_shopfloor/controllers/plant_kanban.py:165-180`
+- Modify: `fusion_plating_shopfloor/__manifest__.py`
+
+- [ ] **Step 1: Update `_resolve_card_area`**
+
+In [`fusion_plating_shopfloor/controllers/plant_kanban.py`](../../fusion_plating_shopfloor/controllers/plant_kanban.py), find `_resolve_card_area` (around line 165). Replace its body with:
+
+```python
+def _resolve_card_area(job):
+    """Pick the column a card lives in.
+
+    Active-step area_kind wins, EXCEPT for no_parts cards which always
+    land in Receiving regardless of active step — the receiver is who
+    needs to act, and they work the Receiving column. With the live-step
+    priority chain (see fp.job._compute_active_step_id), active_step_id
+    is False only when the job has NO steps at all (recipe not assigned)
+    OR every step is `done`. Done jobs are filtered off the board
+    upstream, so the orphan fallback fires only for truly orphaned cards.
+
+    See spec 2026-05-24-recipe-cleanup-design.md Change 6.
+    """
+    # no_parts cards belong in Receiving regardless of where the active
+    # step is — the receiver is who acts.
+    if job.card_state == 'no_parts':
+        return 'receiving'
+    if job.active_step_id and job.active_step_id.area_kind:
+        return job.active_step_id.area_kind
+    # Orphan fallback — represents a data integrity issue, not a
+    # normal state. Cards here have NO steps assigned at all.
+    return 'receiving'
+```
+
+- [ ] **Step 2: Bump fusion_plating_shopfloor manifest**
+
+In [`fusion_plating_shopfloor/__manifest__.py`](../../fusion_plating_shopfloor/__manifest__.py):
+
+```python
+'version': '19.0.33.1.3',
+```
+
+to:
+
+```python
+'version': '19.0.33.1.4',
+```
+
+- [ ] **Step 3: Commit Phase 2 (Tasks 4-6)**
+
+```bash
+git add fusion_plating/fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py \
+        fusion_plating/fusion_plating_jobs/__manifest__.py \
+        fusion_plating/fusion_plating_shopfloor/controllers/plant_kanban.py \
+        fusion_plating/fusion_plating_shopfloor/__manifest__.py
+git commit -m "$(cat <<'EOF'
+feat(jobs+shopfloor): recipe cleanup migration + no_parts column fix
+
+Migration 19.0.10.26.0/post-migrate.py runs in 5 phases:
+1. Resequence recipe 3620 ENP-ALUM-BASIC ops (fixes the duplicate-
+   sequence bug that caused WO-30057 to skip Receiving)
+2. Backfill kind on all kind=other nodes via the extended resolver
+   from fusion_plating 19.0.21.3.0
+3. Delete all 24 per-part clone recipes
+4. Recompute fp.job.step.area_kind on all steps
+5. Recompute fp.job.active_step_id + card_state on in-flight jobs
+
+Plant kanban: no_parts cards now always land in the Receiving column
+regardless of active_step area_kind. The receiver works Receiving;
+that's where the card belongs when parts haven't arrived.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 7: Deploy to entech + verify
+
+- [ ] **Step 1: Fetch + check concurrent commits**
+
+```bash
+git fetch origin
+git log HEAD..origin/main --oneline
+```
+Expected: empty (we're ahead, not behind). If anything shows, rebase first.
+
+- [ ] **Step 2: Copy modified files to entech**
+
+```bash
+for f in \
+  fusion_plating/__init__.py \
+  fusion_plating/models/fp_process_node.py \
+  fusion_plating/__manifest__.py \
+  fusion_plating_jobs/migrations/19.0.10.26.0/post-migrate.py \
+  fusion_plating_jobs/__manifest__.py \
+  fusion_plating_shopfloor/controllers/plant_kanban.py \
+  fusion_plating_shopfloor/__manifest__.py; do
+    echo "Copying $f"
+    cat "$f" | ssh pve-worker5 "pct exec 111 -- bash -c \"mkdir -p \\\$(dirname /mnt/extra-addons/custom/$f) && cat > /mnt/extra-addons/custom/$f\""
+done
+echo "=== ALL COPIED ==="
+```
+
+(Run from `/Users/gurpreet/Github/Odoo-Modules/fusion_plating/` so the file paths line up.)
+
+- [ ] **Step 3: Upgrade modules + restart**
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'systemctl stop odoo && su - odoo -s /bin/bash -c \"/usr/bin/odoo -c /etc/odoo/odoo.conf -d admin -u fusion_plating,fusion_plating_jobs,fusion_plating_shopfloor --stop-after-init\" 2>&1 | tail -60 && systemctl start odoo && sleep 3 && systemctl is-active odoo'"
+```
+
+Expected log lines (in order):
+- `[recipe-cleanup] Recipe 3620: N nodes resequenced`
+- `[recipe-cleanup] Deleted empty duplicate ENP-Alum Line sub_process (id 4056)`
+- `[recipe-cleanup] Phase 2: backfilled kind on N nodes …`
+- `[recipe-cleanup] Phase 3: deleting 24 clone recipes: …`
+- `[recipe-cleanup] Phase 3: deleted 24 clone recipes …`
+- `[recipe-cleanup] Phase 4: recomputed area_kind on N steps`
+- `[recipe-cleanup] Phase 5: recomputed active_step_id + card_state on N in-flight jobs`
+- Service prints `active` at the end.
+
+No tracebacks. If you see one, STOP and report it.
+
+- [ ] **Step 4: SQL spot-check — clones deleted**
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'echo \"SELECT COUNT(*) AS clones_remaining FROM fusion_plating_process_node WHERE node_type='\\''recipe'\\'' AND name ILIKE '\\''% — %'\\'';\" | sudo -u postgres psql -d admin'"
+```
+Expected: `clones_remaining = 0`.
+
+- [ ] **Step 5: SQL spot-check — recipe 3620 resequenced**
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'echo \"SELECT sequence, name FROM fusion_plating_process_node WHERE parent_id = 3620 AND node_type IN ('\\''operation'\\'', '\\''sub_process'\\'') ORDER BY sequence;\" | sudo -u postgres psql -d admin'"
+```
+Expected output (12 unique-sequence rows):
+```
+ 10 | Contract Review
+ 20 | Incoming Inspection (Standard)
+ 30 | Masking
+ 40 | Racking
+ 50 | Ready for processing
+ 60 | ENP-Alum Line
+ 70 | De-Masking
+ 80 | Oven baking
+ 90 | De-racking
+100 | Oven bake (Post de-rack)
+110 | Post-plate Inspection
+120 | Final Inspection
+```
+NO duplicate sequences. NO second ENP-Alum Line row.
+
+- [ ] **Step 6: SQL spot-check — kind=other nodes backfilled**
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'echo \"SELECT n.name, COUNT(*) AS still_other FROM fusion_plating_process_node n JOIN fp_step_kind k ON k.id = n.kind_id WHERE k.code = '\\''other'\\'' AND n.node_type IN ('\\''operation'\\'', '\\''step'\\'', '\\''sub_process'\\'') GROUP BY n.name ORDER BY still_other DESC;\" | sudo -u postgres psql -d admin'"
+```
+Expected: very few rows, only names like `ENP-Alum Line - HP` (sub_process with no clear category) or genuinely-niche operation names. Should NOT include `Contract Review`, `Masking`, `Racking`, `Incoming Inspection`, `E-Nickel Plating`, `Final Inspection`, `Shipping`, `Bake`, `Blasting`, `De-Masking`, `De-racking`, `Hot Water Porosity`, etc.
+
+- [ ] **Step 7: End-to-end smoke**
+
+On the entech UI:
+1. Open Plating → Sales & Quoting → Sale Orders → New
+2. Add a customer + a part whose default recipe is `ENP-ALUM-BASIC` (id 3620)
+3. Confirm the SO
+4. Check the new WO on Plating → Operations → Plating Jobs:
+   a. Recipe should be a fresh clone named `ENP-ALUM-BASIC — <PART#> Rev <X>`
+   b. The clone's first 4 operations should be: Contract Review (10), Incoming Inspection (20), Masking (30), Racking (40)
+5. Open Shop Floor — the job card should be in the **Receiving** column (because card_state='no_parts' AND/OR because Incoming Inspection is now the next live step after Contract Review auto-completes)
+6. Open Plating → Configuration → Recipes & Steps → Recipes — confirm no recipe has " — " in its name (the clones are gone)
+
+- [ ] **Step 8: Autoclassify hook smoke**
+
+In the Simple Editor on any recipe:
+1. Drop a new step, type name "Masking" without picking a kind
+2. Save
+3. Refresh the page
+4. Confirm the step's kind reads "Masking" (not "Other")
+
+---
+
+## Task 8: Commit spec + plan, push to origin
+
+- [ ] **Step 1: Stage and commit the spec + plan docs**
+
+```bash
+git add fusion_plating/docs/superpowers/specs/2026-05-24-recipe-cleanup-design.md \
+        fusion_plating/docs/superpowers/plans/2026-05-24-recipe-cleanup-plan.md
+git commit -m "$(cat <<'EOF'
+docs(plating): spec + plan for recipe cleanup + receiving enforcement
+
+Spec documents:
+- Root cause 1: duplicate sequences on recipe 3620 ENP-ALUM-BASIC
+- Root cause 2: 24 per-part clone recipes carrying the broken order
+- Root cause 3: ~10 kind=other stragglers across base recipes
+- Root cause 4: recipe duplication has no kind safety net
+
+Implementation shipped in commits referenced from the plan's task list.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+- [ ] **Step 2: Final fetch + push**
+
+```bash
+git fetch origin
+git log HEAD..origin/main --oneline  # expect empty
+git push origin main
+```
+
+---
+
+## Rollback
+
+If anything fails on entech:
+
+1. `git reset --hard <prior-commit>` locally, force-copy the prior files back to entech.
+2. Force-rerun the prior version's post-migrate by setting `ir_module_module.latest_version` back to `19.0.10.25.0` for fusion_plating_jobs and `19.0.21.2.0` for fusion_plating, then `-u`.
+
+(Migration is idempotent so re-running the broken version is safe; you may need to manually re-create the deleted clones from a DB backup if rollback needed clones back — out of scope per "we don't need to worry about current data".)