[IMP] partner_phone_country_validation: complete README

partner_phone_country_validation/README.rst

@@ -1,44 +1,150 @@
-===============
+================================
-partner_phone_country_validation
+Partner Phone Country Validation
-===============
+================================
 
-Check the correct format of phone according to country when partner creation/validation
+This module enhances phone number handling on partners by adding automatic
+country detection from phone numbers and enforcing country consistency.
+
+It extends the standard ``phone_validation`` module and the OCA ``base_phone``
+module to provide additional features for phone number management.
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Features
+========
+
+Automatic Phone Number Normalization
+------------------------------------
+
+When entering a phone number, the module automatically converts numbers
+starting with ``00`` to the international ``+`` format:
+
+* ``0033 6 12 34 56 78`` → ``+33 6 12 34 56 78``
+* ``0041 76 123 45 67`` → ``+41 76 123 45 67``
+
+This normalization happens before the standard formatting, ensuring
+compatibility with the ``phonenumbers`` library.
+
+Automatic Country Detection
+---------------------------
+
+When a phone number with an international prefix (``+xx``) is entered and
+the partner has no country set, the module automatically detects and sets
+the country based on the phone number prefix:
+
+* Enter ``+33 6 12 34 56 78`` → Country is set to **France**
+* Enter ``+32 4 123 45 67`` → Country is set to **Belgium**
+* Enter ``+41 76 123 45 67`` → Country is set to **Switzerland**
+
+This works for both ``phone`` and ``mobile`` fields.
+
+Country Validation Constraint
+-----------------------------
+
+The module enforces that a country must be set on the partner if a phone
+or mobile number is present. This ensures data consistency and allows
+proper phone number formatting.
+
+If you try to save a partner with a phone number but no country, a
+validation error will be raised.
+
+How It Works
+============
+
+The module overrides the ``_onchange_phone_validation`` and
+``_onchange_mobile_validation`` methods from the standard ``phone_validation``
+module. The processing order is:
+
+1. **Normalize**: Convert ``00xx`` format to ``+xx`` international format
+2. **Detect country**: If no country is set, detect it from the phone prefix
+3. **Format**: Call the standard formatting (via ``super()``) which formats
+   the number according to the partner's country
+
+When the country is changed on a partner, both phone and mobile numbers
+are automatically reformatted to match the new country's format.
+
+Dependencies
+============
+
+This module depends on:
+
+* ``base``: Odoo base module
+* ``base_phone``: OCA module providing the ``phone.validation.mixin``
+  (from `connector-telephony <https://github.com/OCA/connector-telephony>`_)
+
+The ``base_phone`` module itself depends on the standard ``phone_validation``
+module which uses the `phonenumbers <https://github.com/daviddrysdale/python-phonenumbers>`_
+Python library.
 
 Installation
 ============
 
-Use Odoo normal module installation procedure to install
+1. Install the ``base_phone`` module from the OCA ``connector-telephony`` repository
-``partner_phone_country_validation``.
+2. Install this module using the standard Odoo module installation procedure
 
-Known issues / Roadmap
+Configuration
-======================
+=============
 
-None yet.
+No configuration is required. The module works automatically once installed.
+
+Known Issues / Limitations
+==========================
+
+National Numbers Without International Prefix
+---------------------------------------------
+
+When changing a partner's country, phone numbers in **national format**
+(without international prefix) may not be reformatted if they are not
+valid for the new country.
+
+For example:
+
+* A French mobile ``06 12 34 56 78`` (without ``+33``) cannot be reformatted
+  to a Belgian format because ``06`` is not a valid Belgian mobile prefix.
+* The ``phonenumbers`` library validates numbers and will keep the original
+  format if the number is invalid for the target country.
+
+**Recommendation**: Always use international format (``+xx``) for phone numbers
+to ensure proper handling when countries change.
 
 Bug Tracker
 ===========
 
-Bugs are tracked on `our issues website <https://github.com/elabore-coop/partner_phone_country_validation/issues>`_. In case of
+Bugs are tracked on `Elabore Git Issues <https://git.elabore.coop/Elabore/partner-tools/issues>`_.
-trouble, please check there if your issue has already been
+
-reported. If you spotted it first, help us smashing it by providing a
+In case of trouble, please check there if your issue has already been reported.
-detailed and welcomed feedback.
+If you spotted it first, help us smash it by providing a detailed and welcomed
+feedback.
 
 Credits
 =======
 
+Authors
+-------
+
+* `Elabore <https://elabore.coop>`_
+
 Contributors
 ------------
 
-* Boris Gallet - `Email<mailto:boris.gallet@elabore.coop>` - `Github<https://github.com/b0g>`
+* Boris Gallet <boris.gallet@elabore.coop> (`GitHub <https://github.com/b0g>`_)
+* Stéphan Sainléger <stephan.sainleger@elabore.coop>
 
 Funders
 -------
 
 The development of this module has been financially supported by:
-* Elabore (https://elabore.coop)
 
+* `Elabore <https://elabore.coop>`_
 
 Maintainer
 ----------
 
-This module is maintained by Elabore.
+.. image:: https://elabore.coop/logo.png
+   :alt: Elabore
+   :target: https://elabore.coop
+
+This module is maintained by Elabore.