Metadata-Version: 2.4
Name: odoo-addon-crm_lead_dms_somconnexio
Version: 16.0.1.0.0.11
Summary: Som Connexió required document categories under the document management system.
Home-page: https://git.coopdevs.org/coopdevs/som-connexio/odoo/odoo-somconnexio
Author: Som Connexió SCCL, Coopdevs Treball SCCL
License: AGPL-3
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 16.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Requires-Python: >=3.10
Requires-Dist: odoo-addon-cooperator_somconnexio<16.1dev,>=16.0dev
Requires-Dist: odoo-addon-crm_lead_dms_category<16.1dev,>=16.0dev
Requires-Dist: odoo-addon-crm_lead_personal_file_data<16.1dev,>=16.0dev
Requires-Dist: odoo-addon-dms_file_api<16.1dev,>=16.0dev
Requires-Dist: odoo-addon-dms_res_model_root_directory<16.1dev,>=16.0dev
Requires-Dist: odoo-addon-somconnexio<16.1dev,>=16.0dev
Requires-Dist: odoo<16.1dev,>=16.0a
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

##########################
 CRM LEAD DMS SOMCONNEXIO
##########################

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
   :alt: Beta
   :target: https://odoo-community.org/page/development-status

.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
   :alt: License: AGPL-3
   :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html

|badge1| |badge2|

This module adds a documentation review flow to the CRM lead pipeline,
requiring the Som Connexió specific documents to be uploaded and
validated before a lead can be validated (won).

*********************
 Document categories
*********************

It creates three ``dms.category`` records, each with its own ``code``,
as children of the ``personal data`` and ``lead_data`` categories
provided by ``crm_lead_personal_file_data``:

-  **DNI usuària** (``code``: ``dni_titular_actual``)
-  **DNI titular anterior** (``code``: ``dni_titular_anterior``)
-  **Factura Telèfon Fix** (``code``: ``factura``)

Because they hang from such categories, they reuse the existing root
directories (for ``res.partner`` and ``crm.lead``) and storage. The
``code`` of each category is the value the front sends to the
``dms_file_api`` service as ``category`` and the value returned by the
documents API as ``document_category``.

The module also inherits from the ``add.dms.file.wizard`` from the
``dms_res_model_root_directory`` module, in order to filter the
categories shown in the wizard to only those present on the lead's
``dms_category_ids`` field, in case of a wizard applied on ``crm.lead``
model.

**********************
 Documentation stages
**********************

The module adds three ``crm.stage`` records that a lead goes through
after ``Remesa Done`` (``somconnexio.stage_lead_remesa_done``), before
it can be validated:

-  **Pendent Documentació**: some of the required documents are still
   missing.
-  **Validar Documentació**: all the required documents have been
   uploaded and are waiting for manual validation.
-  **Documentació Validada**: the documentation has been validated (or
   was not required); the lead can be validated (won).

Required documentation
======================

The required categories are computed on ``dms_category_ids`` from the
lead's lines as soon as the lead reaches the ``New`` stage
(``crm.stage_lead1``) - whether it is created directly in ``New`` or
created in another stage and later written into it. A lead created
outside ``New`` and never written into it keeps an empty
``dms_category_ids`` until it does:

-  **DNI usuària**: required unless the lead already has a partner with
   an active contract.

-  **DNI titular anterior**: required when a mobile or fiber portability
   line has a different previous owner (i.e.
   ``previous_owner_vat_number`` is set on its ISP info).

-  **Factura Telèfon Fix**: required when there is a fiber portability
   line with a landline phone number
   (``broadband_isp_info_phone_number``).

If none of these conditions apply, no category is required and the lead
is moved straight to ``Documentació Validada`` once it reaches ``Remesa
Done``.

Automatic flow
==============

-  Moving a lead into the ``Remesa Done`` stage (e.g. via
   ``action_set_remesa_done``, or any ``write`` setting that
   ``stage_id``) immediately evaluates its documentation stage -
   ``update_documentation_stage``.

   -  **No categories required**: there is nothing to review, so the
      lead is validated directly through ``action_set_won`` (with all of
      its checks: ICC, IBAN, banned action tags).

   -  **All the required documentation uploaded, not yet confirmed**:
      moved to ``Validar Documentació``, waiting for manual validation.

   -  **All the required documentation uploaded and already confirmed**
      (``confirmed_documentation``): moved to ``Documentació Validada``.

   -  **Documentation still missing**: moved to ``Pendent
      Documentació``.

-  The evaluation only re-applies while the lead is in ``Remesa Done``,
   ``Pendent Documentació`` or ``Validar Documentació``; a lead that
   already left the documentation flow (e.g. validated or cancelled
   manually) is left untouched.

-  Passing the ``skip_documentation_stage`` context key disables the
   evaluation on ``write`` (used by callers, such as internal
   integrations, that do not take part in the documentation review); the
   lead is simply left in ``Remesa Done``. This same context key is also
   honoured by ``crm_lead_token_somconnexio`` to skip the documentation
   request email, so a caller opting out of one opts out of both.

-  Independently of the above, ``crm_lead_dms_category`` (which defines
   ``dms_category_ids``) provides the ``has_all_required_documentation``
   computed field on ``crm.lead``, kept up to date whenever a document
   is uploaded or removed on the lead itself (documentation is not
   created directly on the partner for now), reflecting whether every
   category in ``dms_category_ids`` already has a matching ``dms.file``.
   As soon as nothing is missing, the lead is moved straight to
   ``Validar Documentació`` without waiting for another ``Remesa Done``
   evaluation.

Manual actions
==============

Three button actions let a user move a lead between stages by hand:

-  ``action_set_pending_documentation``

-  ``action_set_validate_documentation``: raises a ``ValidationError``
   if the lead does not have all the required documentation uploaded
   yet.

-  ``action_set_documentation_validated``: also flags the lead as
   ``confirmed_documentation``.

They are exposed as buttons on the lead form, visible depending on the
current stage.

Validation and provisioning
===========================

-  A lead with required ``dms_category_ids`` can only be validated
   (``validate_won``) once it is in the ``Documentació Validada`` stage;
   otherwise a ``ValidationError`` is raised. ``Documentació Validada``
   is added to the stages allowed to reach won
   (``_won_allowed_stages``). As with the rest of the flow, the
   ``skip_documentation_stage`` context key also disables this check,
   for callers that never enter the documentation review to begin with.

-  On ``res.partner``, the three documentation stages are considered
   part of an ongoing provisioning (``_provisioning_crm_stages``), so a
   lead under documentation review still counts as being provisioned.

Directories
===========

The lead form's *Documentació* tab shows the ``dms.directory`` holding
the lead's own uploaded documents and the one holding its partner's.
Opening either of them shows a simplified ``dms.directory`` form -
``record`` reference, category and the list of files, each downloadable
from an icon next to its name - instead of the full DMS directory form.

**Table of contents**

.. contents::
   :local:

Configuration
-------------

-  Assign the required categories to each lead through the
   ``dms_category_ids`` field on ``crm.lead`` so the documents API lists
   them for that lead (this happens automatically for every lead as soon
   as it reaches the ``New`` stage, see *Usage*).

Usage
-----

The categories and stages are loaded automatically on install/update. As
soon as a lead reaches the ``New`` stage, the required documentation is
computed; once it reaches ``Remesa Done``, its stage is kept up to date
automatically as documents are uploaded and whenever it is written back
into ``Remesa Done``. Users can also move a lead between documentation
stages manually with the corresponding buttons on the lead form.

Known issues / Roadmap
----------------------

There are no issues for the moment.

Credits
-------

*********
 Authors
*********

-  Som Connexio SCCL

**************
 Contributors
**************

-  `Som Connexio SCCL <https://somconnexio.coop>`_:

      -  Borja Gimeno <borja.gimeno@somconnexio.coop>
