========================
РуОду — Комиссии агентам
========================

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
    :alt: License: LGPL-3

|badge1| |badge2|

Учёт агентских вознаграждений (комиссий) по сделкам. Комиссии
привязываются к строкам заказа продаж по аналогии с налогами: к одной
строке можно привязать несколько комиссий. По подтверждённому заказу
комиссии начисляются одним действием в виде счетов поставщика
(Vendor Bill), сгруппированных по партнёрам-получателям.

**Содержание**

.. contents::
   :local:

Возможности
===========

* Справочник видов комиссий (меню *Учёт → Комиссии агентам*):

  * расчёт *Процентом* от суммы строки без налогов;
  * расчёт *Формулой* — python-код вида ``result = ...`` по аналогии
    с правилами модуля зарплаты;
  * журнал и счёт расходов для будущих проводок, партнёр-получатель,
    опциональный аналитический счёт.

* Привязка нескольких комиссий к строке заказа (``sale.order.line``),
  колонка «Комиссии» и расчёт суммы комиссий по строке.
* Строка «ИТОГО КОМИССИЙ» в блоке итогов заказа (не входит в итог
  заказа — это забалансовый агентский расход).
* Кнопка «Начислить комиссию» на подтверждённом заказе: формирование
  и проведение счетов поставщика по каждому партнёру-получателю со
  счетами из настроек комиссии.
* Смарт-кнопка «Комиссии» со связанными счетами поставщика.
* Каскадная отмена счетов комиссий при отмене заказа: отвязка платежей
  (штатными средствами), перевод в черновик и удаление.
* Разграничение доступа группами «Видит комиссии» и
  «Начисляет комиссии».

Зависимости
===========

* ``sale_management`` — заказы на продажу и строки заказа
* ``account`` — счета поставщика (``account.move``), журналы и счета

Модели
======

* ``commission.commission`` — вид комиссии агенту (способ расчёта,
  журнал, счёт расходов, партнёр-получатель, аналитика).
* ``sale.order.line`` (расширение) — поле ``commission_ids`` и
  вычисляемое ``commission_amount``.
* ``sale.order`` (расширение) — ``amount_commission`` («ИТОГО КОМИССИЙ»),
  начисление и просмотр счетов комиссий, каскадная отмена.
* ``account.move`` (расширение) — служебная ссылка
  ``commission_sale_order_id`` на исходный заказ.

Группы доступа
==============

* **Видит комиссии** (``group_commission_viewer``) — видит колонку
  «Комиссии», итог «ИТОГО КОМИССИЙ» и смарт-кнопку. Продавцы вне этой
  группы могут добавлять комиссии в строки, но не видят вывод.
* **Начисляет комиссии** (``group_commission_manager``, включает
  «Видит комиссии») — доступна кнопка «Начислить комиссию».

Настройка
=========

#. Откройте *Учёт → Комиссии агентам* и заведите нужные виды комиссий.
#. Для способа «Процент» укажите ставку; для «Формулы» — python-код,
   присваивающий результат переменной ``result``.
#. На каждой комиссии задайте журнал (покупки), счёт расходов
   (тип «Расходы»), партнёра-получателя и, при необходимости,
   аналитический счёт.
#. Выдайте сотрудникам группы «Видит комиссии» и «Начисляет комиссии».

Формула комиссии
================

В режиме «Формула» доступны переменные:

* ``line`` — строка заказа (``sale.order.line``)
* ``order`` — заказ (``sale.order``)
* ``product`` — товар строки (``product.product``)
* ``qty`` — количество
* ``price_unit`` — цена за единицу
* ``price_subtotal`` — сумма строки без налогов
* ``partner`` — контрагент заказа (``res.partner``)
* ``commission`` — текущий вид комиссии

Результат присваивается переменной ``result``, например::

    result = price_subtotal * 0.05

Использование
=============

#. В строках заказа выберите нужные комиссии в колонке «Комиссии».
   В блоке итогов появится «ИТОГО КОМИССИЙ».
#. Подтвердите заказ и нажмите «Начислить комиссию». Модуль обойдёт
   строки и привязанные комиссии, сгруппирует их по партнёру-получателю
   и сформирует один или несколько счетов поставщика, затем проведёт их.
#. Нажмите смарт-кнопку «Комиссии», чтобы увидеть связанные счета.
#. При отмене заказа счета комиссий автоматически отменяются, переводятся
   в черновик и удаляются; привязанные платежи предварительно
   отвязываются штатными средствами (при невозможности — выдаётся
   понятное сообщение).

Границы
=======

* Нативная бухгалтерия Odoo не изменяется сверх создания и штатной
  обработки счетов поставщика и служебного поля-ссылки.
* Проводки в РСБУ-журнал по счетам комиссий формирует штатный коннектор
  РСБУ-слоя по событию проведения (``action_post``) — вне этого модуля.

Тестирование
============

Модуль покрыт тестами ``TransactionCase`` (расчёт процентом и формулой,
несколько комиссий на строке, исключение комиссии из итога заказа,
начисление и группировка счетов по получателям, дедупликация, каскадная
отмена, смарт-кнопка). Запуск::

    docker compose run --rm odoo odoo -d <db> -i ruodoo_commission \
        --test-enable --test-tags=/ruodoo_commission --stop-after-init

Авторы
======

* MK.Lab, RuOdoo

Модуль сопровождается MK.Lab, RuOdoo.

.. image:: https://ruodoo.ru/logo.png
   :alt: MK.Lab, RuOdoo
   :target: https://ruodoo.ru

Модуль является частью решения РуОду.