diff --git a/partner_phone_country_validation/README.rst b/partner_phone_country_validation/README.rst index 6859ea5..98873fc 100644 --- a/partner_phone_country_validation/README.rst +++ b/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 `_) + +The ``base_phone`` module itself depends on the standard ``phone_validation`` +module which uses the `phonenumbers `_ +Python library. Installation ============ -Use Odoo normal module installation procedure to install -``partner_phone_country_validation``. +1. Install the ``base_phone`` module from the OCA ``connector-telephony`` repository +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 `_. In case of -trouble, please check there if your issue has already been -reported. If you spotted it first, help us smashing it by providing a -detailed and welcomed feedback. +Bugs are tracked on `Elabore Git Issues `_. + +In case of trouble, please check there if your issue has already been reported. +If you spotted it first, help us smash it by providing a detailed and welcomed +feedback. Credits ======= +Authors +------- + +* `Elabore `_ + Contributors ------------ -* Boris Gallet - `Email` - `Github` +* Boris Gallet (`GitHub `_) +* Stéphan Sainléger Funders ------- The development of this module has been financially supported by: -* Elabore (https://elabore.coop) +* `Elabore `_ Maintainer ---------- -This module is maintained by Elabore. \ No newline at end of file +.. image:: https://elabore.coop/logo.png + :alt: Elabore + :target: https://elabore.coop + +This module is maintained by Elabore.