Troubleshooting Guide¶

This guide is organized by symptom. Each section describes a problem, its likely causes, and the steps to resolve it.

1. Device Allocation Issues¶

Problem: Device not showing in the allocation wizard¶

Possible Causes and Checks:

Device status must be available. A device in reserved or sold status will not appear. If a device was previously allocated to an SO that was cancelled, verify its status was reset. You can check and correct this in the Odoo shell:
```
lot = env['stock.lot'].browse(<lot_id>)
print(lot.device_status)
lot.device_status = 'available'
```
QC status must be qc_complete. Devices that have not passed QC will be excluded from the wizard. Check qc_status on the stock.lot record. The device must have gone through the full QC flow (status: pending_qc → in_qc → qc_complete).
Company scope. The device must either belong to the selling company or be consigned to it via an active device.consignment.agreement. Devices owned by an unrelated company will not appear.
Already allocated to another SO. A device cannot be allocated to more than one active SO. Search sale.order.line.device for records referencing the lot to find any existing active allocation.

Problem: "Allocate" button not visible on the Sales Order¶

Cause: The Device Allocation tab is only rendered when total_devices > 0. The total_devices field is computed from device_line_ids on the SO. If no devices are allocated yet, the tab (and the button inside it) will not appear — this is a bootstrapping constraint.

Resolution: Perform the first allocation from the device list view:

Navigation: Inventory → Device Inventory → Inventory → All Devices

From the device list, use the allocation action to associate a device with the SO line. Once at least one sale.order.line.device record exists, the tab and button will render on the SO form.

Alternatively, allocate directly via the Odoo shell:

DeviceAlloc = env['sale.order.line.device']
DeviceAlloc.create({
    'sale_order_line_id': <so_line_id>,
    'lot_id': <lot_id>,
    'unit_price': <price>,
})

2. Commission Issues¶

Problem: Commission amount showing as 0¶

Possible Causes and Checks:

No active consignment agreement. The agreement between the device owner and consignee must be in active state. Agreements in draft or expired state will not generate commission.
commission_type is set to none. Navigate to the consignment agreement and confirm commission_type is either percentage or fixed.
commission_rate stored incorrectly. The rate is stored as a decimal: 0.15 represents 15%. If the field was set to 15 instead of 0.15, the commission will appear as 1500% of the sale price, not 15%. Correct the value on the agreement record.

Note: Odoo 19 applies a percentage widget to Float fields, so 0.15 displays as "15%" in the UI automatically. Do not enter 15 in the field.

sale_price is 0 or not set on the allocation. Commission is calculated as sale_price * commission_rate. If the unit price on the sale.order.line.device record is 0, commission will be 0 regardless of the rate.

3. Settlement Report Issues¶

Problem: Settlement report not created after delivery¶

Possible Causes and Checks:

Device has no owner_company_id. Settlement reports are only generated for consignment sales, i.e., when owner_company_id != sold_by_company_id. If both fields point to the same company (or owner_company_id is not set), no report is created.
No active consignment agreement. An active device.consignment.agreement must exist between the owner company and the consignee. Without it, the settlement creation logic will not run.
Manifest _process_customer_delivery() was not reached. Confirm the manifest was fully completed (all lines received or marked missing) and the "Mark Complete" action was triggered successfully. Check for any Python errors in the Odoo server log at the time of completion.

Problem: Vendor bill not created when settlement report is confirmed¶

Possible Causes and Checks:

settlement_journal_id is not configured. Navigate to:

Settings → Inventory tab → Consignment Settlement section

The settlement journal must be set. This is the journal used to post the vendor bill for the owner payout.

total_owner_amount is 0 or negative. The system will not create a zero-value vendor bill. Verify that owner_amount is set correctly on the settlement report lines.

4. Manifest and Receiving Issues¶

Problem: Barcode scanner not matching IMEIs¶

Possible Causes and Checks:

Exact format match required. The scanned IMEI must match the value stored in stock.lot.name character-for-character. Leading zeros, spaces, or formatting differences will cause a mismatch. Verify the lot name in the database matches what the scanner is producing.
Manifest not in the correct state. For receiving operations, the manifest must be in uploaded or in_progress state. For delivery scanning, it must be in in_progress state. A manifest in draft or complete state will not process scan input.
Manifest line does not exist. The IMEI must have a corresponding device.manifest.line record on the manifest. If the device was added to the PO after the manifest was generated, it may not have a line.

Problem: Cannot mark manifest as complete¶

Possible Causes and Checks:

For receiving manifests: All expected lines must be in received status or explicitly marked as missing. Any line still in pending will block completion.
For delivery manifests: The number of delivered devices must satisfy the SO quantity. A mismatch between manifest lines and SO line quantities will trigger a validation error.

5. Accounting Issues¶

Problem: Inventory GL entry not created on receiving¶

Cause: All three accounting fields must be configured. If any one is missing, the GL entry will be skipped silently.

Resolution: Navigate to:

Settings → Inventory tab → Device Inventory Accounting section

Verify all three fields are populated: | Field | Purpose | |---|---| | device_stock_journal_id | Journal for inventory postings | | device_valuation_account_id | Debit account (Inventory Valuation) | | device_input_account_id | Credit account (Inventory Input) |

Problem: COGS entry missing after sale¶

Possible Causes and Checks:

device_cogs_account_id not configured. This account is required for the COGS debit. Set it in:

Settings → Inventory tab → Device Inventory Accounting section
device_valuation_account_id not configured. This is also the credit side of the COGS entry.
purchase_cost is 0 on the device. The COGS amount is derived from purchase_cost on the stock.lot. If the device was received without a cost, the COGS entry will be $0. Update purchase_cost on the lot and re-process if needed.

6. Inter-Company Transfer Issues¶

Problem: PO not auto-created for inter-company transfer¶

Possible Causes and Checks:

intercompany_partner_id not set on the destination company. Each company that participates in inter-company flows must have a partner record configured. Navigate to the destination company settings and verify intercompany_partner_id is populated.
SO was not flagged as inter-company. The is_inter_company flag must be True on the SO. This is typically set automatically when the customer on the SO matches an inter-company partner, but verify the flag if auto-creation did not fire.

7. Multi-Company and Data Separation Issues¶

Problem: Axis user can see Reyder's customer data¶

Cause: This is most often observed when testing with the admin user, who belongs to both companies. Odoo's cids cookie auto-expands to include all companies the user belongs to, so admin will always see records from both Reyder Enterprises and Axis Mobile.

Resolution:

Test data separation exclusively with a user that belongs to only one company — use axis_user (uid=5, Axis Mobile only).
Record rules use the condition ('company_id', 'in', company_ids). For admin, company_ids contains both company IDs, so all records match.
If testing in the Odoo shell, note that the shell runs as SUPERUSER_ID=1, which bypasses all record rules. Use with_user() to test rule enforcement:
```
axis_user = env['res.users'].browse(5)
reports = env['consignment.settlement.report'].with_user(axis_user).search([])
```

Problem: Records not visible after switching companies in the UI¶

Cause: Odoo automatically expands the active cids cookie to include the company that owns the record being viewed. This means navigating to a record from Company A while Company B is active will silently add Company A to the active session.

Resolution: For reliable isolation testing, use axis_user (belongs only to Axis Mobile) rather than admin. The cids expansion only applies when the user actually belongs to multiple companies.

8. Retail Operations Issues¶

Problem: Retail reservation not auto-closing¶

Cause: The _check_auto_close() method triggers when remaining_count on the reservation reaches 0, meaning all reserved devices have been sold. If the reservation is not closing:

Check remaining_count on the device.retail.reservation record. If it is still > 0, there are devices not yet sold.
Verify that the retail sale records for the devices are in confirmed or sold status.
Confirm _check_auto_close() is being invoked — it runs as part of the retail sale confirmation flow. If a sale was confirmed outside the normal wizard flow, the check may not have fired.

Problem: Retail sale import failing¶

Possible Causes and Checks:

CSV format. The import file must contain at minimum an IMEI column and a Sale Price column. Column headers are case-sensitive. Missing or misspelled headers will cause a silent import failure or row-level errors.
IMEIs must exist as stock.lot records. If an IMEI in the CSV does not match any lot in the system, that row will be skipped or error. Pre-validate your CSV against the device inventory.
Device status. Devices being imported into a retail sale must have device_status of available or reserved. Devices with status sold, in_qc, or pending_qc will be rejected.

9. QC Issues¶

Problem: Cannot mark QC complete on a device¶

Requirements — all must be met:

Requirement	Field to Check
M360 session assigned	`m360_session_id` must be set on `stock.lot`
Grade assigned	`grade_id` must be set on `stock.lot`
Correct status	`device_status` must be `in_qc` (not `pending_qc`)

Resolution:

If the device is in pending_qc, it has not been moved into an active QC session yet. Assign it to an M360 session first, which transitions the status to in_qc.
If grade_id is missing, assign a grade (Excellent, Good, Fair, or Poor) before attempting to complete QC.

Note: Valid grade values are: Excellent, Good, Fair, Poor. Letter grades (A/B/C) are not used.

Frequently Asked Questions¶

Q: What is the difference between the owner report and the consignee report?

A: The owner report (e.g., Axis Mobile's view) shows only IMEI, model, storage capacity, grade, commission amount, and owner payout. It deliberately excludes customer names, SO numbers, and sale prices. The consignee report (Reyder's view) includes the full transaction details. This is enforced at both the data level (sensitive fields are not stored on owner lines) and the view level (sale_order_id is hidden when report_type == 'owner'). A record rule also prevents Axis from accessing the paired consignee report directly.

Q: How is commission calculated?

A: Commission is calculated as sale_price * commission_rate. The commission_rate is stored as a decimal (0.15 = 15%). For example: a $100 sale at 15% commission yields $15 commission and $85 to the owner. The division by 100 is not needed in code — do not store 15 in the commission_rate field.

Q: Can there be multiple consignment agreements between the same two companies?

A: No. There is a unique constraint enforcing one agreement per owner/consignee pair. If you need to change commission terms, edit the existing agreement rather than creating a new one.

Q: What happens when a Sales Order is cancelled?

A: Cancelling an SO will: 1. Release all device reservations — device_status on each allocated lot is reset to available. 2. Cancel any draft delivery manifests associated with the SO.

Confirmed manifests and completed settlements are not affected by SO cancellation.

Q: Where do I configure the accounting accounts for device inventory?

A: All accounting configuration is in:

Settings → Inventory tab → Device Inventory Accounting section (bottom of the page)

The following fields are available in that section:

Field	Used For
Device Stock Journal	Journal for all inventory GL entries
Device Valuation Account	Inventory asset account (DR on receive, CR on COGS)
Device Input Account	Goods received not invoiced (CR on receive)
Device COGS Account	Cost of goods sold (DR on sale)

Additionally, for consignment settlements:

Settings → Inventory tab → Consignment Settlement section

Field	Used For
Settlement Journal	Journal for vendor bills generated on settlement confirmation