Enhance deferred fields for production ETL reliability

.gitignore

@@ -60,3 +60,7 @@ node_modules
 _build
 ODF_ Strategic Blueprint.md
 .coverage
+
+# mypyc compiled extensions
+*.so
+build/

docs/guides/advanced_usage.md

@@ -115,6 +115,65 @@ product_mapping = {
 
 ---
 
+## Multi-Environment Imports
+
+When working with multiple Odoo environments (e.g., test, UAT, production), the importer automatically organizes fail files into environment-specific subfolders based on your connection file name.
+
+### How It Works
+
+The environment name is extracted from your connection file:
+
+| Connection File | Environment | Fail File Location |
+|----------------|-------------|-------------------|
+| `test_connection.conf` | `test` | `data/test/res_partner_fail.csv` |
+| `uat_connection.conf` | `uat` | `data/uat/res_partner_fail.csv` |
+| `prod_connection.conf` | `prod` | `data/prod/res_partner_fail.csv` |
+| `uat.conf` | `uat` | `data/uat/res_partner_fail.csv` |
+
+The `_connection` suffix is automatically stripped to determine the environment name.
+
+### Example: Importing to Multiple Environments
+
+**Directory Structure:**
+```
+project/
+├── data/
+│   └── res_partner.csv
+├── test_connection.conf
+├── uat_connection.conf
+└── prod_connection.conf
+```
+
+**Import to UAT:**
+```bash
+odoo-data-flow import \
+    --connection-file uat_connection.conf \
+    --file data/res_partner.csv \
+    --model res.partner
+```
+
+If any records fail, they are written to `data/uat/res_partner_fail.csv`.
+
+**Retry Failed Records:**
+```bash
+odoo-data-flow import \
+    --connection-file uat_connection.conf \
+    --file data/res_partner.csv \
+    --model res.partner \
+    --fail
+```
+
+The `--fail` flag automatically looks for the fail file in the correct environment folder (`data/uat/res_partner_fail.csv`).
+
+### Benefits
+
+- **Isolated environments**: Fail files from different environments don't mix
+- **Easy retry**: The `--fail` flag finds the correct fail file automatically
+- **Clean organization**: Each environment has its own subfolder for tracking failures
+- **Automatic folder creation**: Environment folders are created automatically when needed
+
+---
+
 ## Importing Translations
 
 The most efficient way to import translations is to perform a standard import with a special `lang` key in the context. This lets Odoo's ORM handle the translation creation process correctly.

docs/guides/configuration.md

@@ -22,7 +22,7 @@ database = my_odoo_db
 login = admin
 password = my_admin_password
 uid = 2
-protocol = xmlrpc
+protocol = jsonrpc
 ```
 
 ### Configuration Keys
@@ -62,9 +62,33 @@ protocol = xmlrpc
 
 #### `protocol`
 * **Required**: No
-* **Description**: The connection protocol to use for XML-RPC calls. `xmlrpc` uses HTTP, while `xmlrpcs` uses HTTPS for a secure connection. While modern Odoo uses JSON-RPC for its web interface, the external API for this type of integration typically uses XML-RPC.
+* **Description**: The RPC protocol to use for communication with Odoo. The choice of protocol can significantly impact performance.
 * **Default**: `xmlrpc`
-* **Example**: `protocol = xmlrpcs`
+* **Available Options**:
+  * `xmlrpc` - XML-RPC over HTTP (default, compatible with all Odoo versions)
+  * `xmlrpcs` - XML-RPC over HTTPS (secure)
+  * `jsonrpc` - JSON-RPC over HTTP (**recommended for Odoo 10+**, ~30% faster)
+  * `jsonrpcs` - JSON-RPC over HTTPS (secure, recommended for production)
+  * `json2` - JSON-2 API over HTTP (Odoo 19+ only, requires API key)
+  * `json2s` - JSON-2 API over HTTPS (Odoo 19+ only, requires API key)
+
+* **Performance Note**: JSON-RPC is approximately 30% faster than XML-RPC due to more efficient parsing and smaller payload sizes. For Odoo 10 and newer, using `jsonrpc` or `jsonrpcs` is recommended.
+
+* **Odoo 19+ Note**: Odoo 19 introduces the new JSON-2 API which will replace XML-RPC and JSON-RPC in Odoo 20. JSON-2 requires an API key instead of a password. Generate an API key from your Odoo user preferences (Account Security section) and use it in the `password` field.
+
+* **Example**: `protocol = jsonrpcs`
+
+#### Overriding Protocol via CLI
+
+You can override the protocol setting from your config file using the `--protocol` CLI option:
+
+```bash
+# Use JSON-RPC for better performance
+odoo-data-flow import --protocol jsonrpc --connection-file conf/connection.conf ...
+
+# Use JSON-2 for Odoo 19+
+odoo-data-flow import --protocol json2 --connection-file conf/connection.conf ...
+```
 
 ---