POS KDS Stage Reset Fix
=======================

**Module:** ``pos_kds_fix``

**Version:** 19.0.1.0.0

**Author:** Suherdy Yacob

**Category:** Sales/Point of Sale

**License:** GPL-3

Overview
--------

This module fixes a bug in the Odoo 19 Preparation Display (Kitchen Display System)
where previously completed order items are incorrectly reset back to the "To Prepare"
stage when a customer adds a new item to the same table.

The Bug
-------

**Scenario:**

1. Table 1 sends 5 items to the KDS.
2. Kitchen staff advances all 5 items through the stages to "Completed".
3. Customer adds 1 new item to Table 1.
4. The new item correctly appears on the KDS in "To Prepare" stage.
5. **BUG:** The 5 previously completed items reappear on the KDS as "To Prepare".

**Root Cause:**

When a new item is added to an existing POS order that was already sent to the
kitchen, Odoo creates a new ``pos.prep.order`` record for the new item. The KDS
frontend then reloads all open prep states for that POS order via the bus
notification ``LOAD_ORDERS``.

The ``_get_open_orderlines_in_display()`` filter excludes only states where:

- ``todo = False`` AND ``stage = last_stage``

When kitchen staff advances items to the last stage using the stage-advance button,
the state is set to:

- ``todo = True``, ``stage = last_stage``

These states pass the filter and are returned to the KDS frontend, causing the
completed items to reappear.

The Fix
-------

This module overrides ``PosOrder._process_preparation_changes()`` to detect when
a new ``pos.prep.order`` is being created for an existing POS order (i.e., new
items added to an already-sent order). When that happens, all states from the
**previous** prep orders that are at the last stage (regardless of ``todo`` status)
are automatically set to ``todo=False``. This ensures the KDS filter correctly
excludes them from subsequent reloads.

Technical Details
-----------------

**Overridden Method:** ``pos.order._process_preparation_changes()``

**Model:** ``pos.order``

**Logic:**

- Capture existing ``pos.prep.order`` IDs before calling ``super()``.
- After ``super()`` runs, check if ``result['order_added']`` is ``True``
  (indicating new lines were added and a new prep ticket was created).
- For each relevant prep display, find all ``pos.prep.state`` records from the
  old prep orders that are at the last stage with ``todo=True``.
- Set those states to ``todo=False`` to hide them from the KDS.

Dependencies
------------

- ``pos_enterprise``

Installation
------------

1. Copy the ``pos_kds_fix`` folder into your Odoo addons directory.
2. Update the apps list in Odoo settings.
3. Search for "POS KDS Stage Reset Fix" and install it.
4. No additional configuration is required.

Performance Optimization
------------------------

This module also optimizes the Preparation Display's rendering, backend loading, and idle CPU usage:

- Order Pagination: Limits rendering to 16 order cards per page, significantly reducing DOM nodes.
- Pagination Controls: Adds Page Navigation buttons at the bottom of the main orders area.
- Timer Refresh Rate: Reduces the order age/duration update frequency from 1 second to 15 seconds.
- Backend Query Optimization: Eliminates N+1 query loops when loading the KDS list, reducing loading times from minutes to sub-second.
- Robust Notes Parsing: Gracefully parses and handles custom kitchen notes to prevent blank page crashes.

Compatibility
-------------

- Odoo 19 Enterprise (requires ``pos_enterprise`` module)