Odoo-Modules/fusion_repairs/wizard/repair_visit_report_wizard.py

# -*- coding: utf-8 -*-
# Copyright 2024-2026 Nexa Systems Inc.
# License OPL-1 (Odoo Proprietary License v1.0)

"""Technician visit report wizard.

Opened from a completed (or in-progress) repair.order. Captures:
- labour hours
- parts/consumables used
- recommended upsell products
- optional client signature

On confirm:
- writes labour + parts as repair.order lines (Odoo native operations)
- updates x_fc_actual_cost on the repair
- triggers variance reconciliation (sets x_fc_requires_requote if over threshold)
- if not requote: confirms the repair (state='under_repair' -> 'done' via Odoo native flow)
- offers an action_collect_payment shortcut to fire Poynt on the resulting invoice
"""

import logging
from datetime import timedelta

from markupsafe import Markup

from odoo import _, api, fields, models
from odoo.exceptions import UserError

_logger = logging.getLogger(__name__)


class RepairVisitReportWizard(models.TransientModel):
    _name = 'fusion.repair.visit.report.wizard'
    _description = 'Repair Visit Report Wizard'

    repair_id = fields.Many2one(
        'repair.order',
        string='Repair Order',
        required=True,
        readonly=True,
    )
    technician_id = fields.Many2one(
        'res.users',
        string='Technician',
        default=lambda self: self.env.user,
        domain="[('x_fc_is_field_staff', '=', True)]",
    )

    # Labour
    labour_hours = fields.Float(
        string='Labour Hours',
        required=True,
        default=1.0,
    )

    # Parts used (simple line model below)
    parts_line_ids = fields.One2many(
        'fusion.repair.visit.report.wizard.line',
        'wizard_id',
        string='Parts Used',
    )

    # Outcome
    notes = fields.Html(string='Technician Notes')
    found_another_issue = fields.Boolean(
        string='Found Another Issue',
        help='Tick to spawn a follow-up repair after saving this visit.',
    )

    # M1: tick when the visit was a safety inspection. On save the wizard
    # creates a fusion.repair.inspection.certificate.
    issue_inspection_cert = fields.Boolean(
        string='Issue Compliance Certificate',
        help='Tick when the visit was an annual safety inspection. Creates an '
             'inspection certificate record and prints the PDF on save.',
    )
    inspection_cert_id = fields.Many2one(
        'fusion.repair.inspection.certificate',
        string='Issued Certificate',
        readonly=True,
    )

    # ----- T4 client signature -----
    client_signature = fields.Binary(
        string='Client Signature',
        attachment=True,
        help='Captured via signature widget on tech mobile - proves the '
             'client accepted the work.',
    )
    client_signature_name = fields.Char(
        string='Signed By',
        help='Type the client name as they signed (for the audit log).',
    )

    # ----- T7 no-show photo proof -----
    no_show = fields.Boolean(
        string='Client No-Show',
        help='Tick if the client was not present. Forces a no-show photo.',
    )
    no_show_photo = fields.Binary(
        string='No-Show Photo',
        attachment=True,
        help='Photo of the door / driveway proving the technician attended.',
    )

    # ----- T6 parts replaced - serial capture -----
    parts_serial_capture = fields.Text(
        string='Replaced Parts - Serials',
        help='One serial per line. Used for OEM warranty claims.',
    )

    # ----- Bundle 8: Cannot Fix Today - Needs Parts -----
    outcome = fields.Selection(
        [
            ('completed', 'Repair Complete - Close It'),
            ('parts_needed', "Can't Fix Today - Need to Order Parts"),
            ('rescheduled', 'Could Not Reach / Rescheduled'),
        ],
        string='Visit Outcome',
        default='completed',
        required=True,
        help='Drives what happens after you submit: completed -> closes the '
             "repair; parts_needed -> captures the part info, emails the client, "
             "schedules follow-up; rescheduled -> repair stays open.",
    )
    needs_parts_line_ids = fields.One2many(
        'fusion.repair.visit.report.wizard.partline',
        'wizard_id',
        string='Parts To Order',
        help='ONE line per distinct part. Description + OEM number + photos go to '
             'procurement so they can place the manufacturer order from your input '
             'alone.',
    )

    # ----- Bundle 9: callout pricing + warranty -----
    callout_distance_km = fields.Float(
        related='repair_id.x_fc_callout_distance_km',
        string='One-Way Distance (km)',
        readonly=False,
        help='Distance from shop to client. Beyond the rate-card threshold, '
             'EVERY km is billed BOTH WAYS, per tech.',
    )
    callout_techs = fields.Integer(
        related='repair_id.x_fc_callout_techs',
        string='Technicians on Callout',
        readonly=False,
    )
    callout_tier = fields.Selection(
        related='repair_id.x_fc_callout_tier',
        string='Callout Tier',
        readonly=False,
    )
    callout_in_shop = fields.Boolean(
        related='repair_id.x_fc_in_shop',
        string='In-Shop Repair',
        readonly=False,
    )
    callout_labor_hours_used = fields.Float(
        string='Repair Hours (after 30 min inspection)',
        default=1.0,
        help='Total hours of REPAIR WORK after the 30 minutes the callout fee covers. '
             'Minimum 1 hour is billed even if the actual fix took less.',
    )
    quote_total_preview = fields.Monetary(
        related='repair_id.x_fc_quote_total',
        currency_field='company_currency_id',
        readonly=True,
    )
    quote_breakdown_preview = fields.Text(
        related='repair_id.x_fc_quote_breakdown_text',
        readonly=True,
    )
    labor_warranty_status_preview = fields.Selection(
        related='repair_id.x_fc_labor_warranty_status',
        readonly=True,
    )
    labor_warranty_id_preview = fields.Many2one(
        related='repair_id.x_fc_labor_warranty_id',
        readonly=True,
    )
    # Void path: tech finds misuse / negligence -> warranty is void
    warranty_void_reason = fields.Selection(
        [
            ('user_negligence', 'User Negligence'),
            ('gross_negligence', 'Gross Negligence'),
            ('misuse', 'Misuse'),
            ('over_recommended_use', 'Over-Recommended Use'),
            ('accidental_damage', 'Accidental Damage'),
        ],
        string='Void Warranty Reason',
        help='If you find evidence the unit was misused, pick the reason. The '
             'matching labor warranty record (if any) is voided permanently '
             'and the client is billed full labor.',
    )
    warranty_void_notes = fields.Text(string='Void Notes')

    # Variance display
    estimated_cost = fields.Monetary(
        related='repair_id.x_fc_estimated_cost',
        currency_field='company_currency_id',
        readonly=True,
    )
    actual_cost = fields.Monetary(
        string='Actual Cost',
        compute='_compute_actual_cost',
        currency_field='company_currency_id',
    )
    variance_pct = fields.Float(
        string='Variance %',
        compute='_compute_actual_cost',
    )
    requires_requote = fields.Boolean(
        compute='_compute_actual_cost',
    )

    company_currency_id = fields.Many2one(
        'res.currency',
        related='repair_id.company_currency_id',
        readonly=True,
    )

    @api.depends('labour_hours', 'parts_line_ids.subtotal', 'repair_id.x_fc_estimated_cost')
    def _compute_actual_cost(self):
        ICP = self.env['ir.config_parameter'].sudo()
        try:
            threshold_pct = float(ICP.get_param('fusion_repairs.variance_threshold_pct', '20'))
        except (ValueError, TypeError):
            threshold_pct = 20.0
        try:
            threshold_amt = float(ICP.get_param('fusion_repairs.variance_threshold_amount', '100'))
        except (ValueError, TypeError):
            threshold_amt = 100.0

        for w in self:
            catalog = w.repair_id.x_fc_service_catalog_id
            labour_rate = 0.0
            if catalog and catalog.service_product_id:
                labour_rate = catalog.service_product_id.list_price
            parts_total = sum(w.parts_line_ids.mapped('subtotal'))
            w.actual_cost = (w.labour_hours * labour_rate) + parts_total
            est = w.estimated_cost or 0.0
            variance_pct = ((w.actual_cost - est) / est * 100) if est else 0.0
            w.variance_pct = variance_pct
            # One-sided: only OVER-cost triggers re-quote. Coming in under
            # estimate is good news and must not block invoicing.
            over_pct = variance_pct
            over_amt = w.actual_cost - est
            w.requires_requote = est > 0 and (
                over_pct >= threshold_pct or over_amt >= threshold_amt
            )

    # ------------------------------------------------------------------
    # ACTION
    # ------------------------------------------------------------------
    def action_confirm(self):
        self.ensure_one()
        repair = self.repair_id
        if not repair:
            raise UserError(_('No repair selected.'))

        # Create native repair operations (stock moves) for the parts used.
        # 'add' type moves consume parts from the parts source location and
        # flow through to the invoice when action_create_sale_order() is run.
        self._create_repair_part_moves(repair)

        # Persist actual cost + requote flag on the repair.
        repair.write({
            'x_fc_actual_cost': self.actual_cost,
            'x_fc_requires_requote': self.requires_requote,
            # Bundle 9 - persist hours the tech actually worked + resolve warranty
            'x_fc_callout_labor_hours': self.callout_labor_hours_used,
        })

        # Bundle 9: resolve labor warranty + apply void reason if the tech
        # found misuse during the visit.
        repair.action_check_labor_warranty()
        if self.warranty_void_reason and repair.x_fc_labor_warranty_id:
            repair.x_fc_labor_warranty_id.action_void(
                reason=self.warranty_void_reason,
                notes=self.warranty_void_notes or '',
            )
            repair.x_fc_labor_warranty_status = 'void_misuse'
            repair.message_post(body=Markup(_(
                'Warranty <b>VOIDED</b> on this visit. Reason: %(r)s. '
                'Full labor charged.'
            )) % {'r': dict(self._fields['warranty_void_reason'].selection).get(
                self.warranty_void_reason)})

        # Append technician notes to chatter.
        if self.notes:
            repair.message_post(body=self.notes)

        # Spawn a follow-up repair if the tech found another issue.
        stub = False
        if self.found_another_issue:
            stub = repair.copy({
                'state': 'draft',
                'internal_notes': _(
                    '<p><em>Spawned from visit report on %(ref)s. Add details for the new issue.</em></p>',
                    ref=repair.name,
                ),
                'x_fc_intake_source': 'manual',
                'x_fc_intake_session_id': repair.x_fc_intake_session_id,
                'x_fc_estimated_cost': 0.0,
                'x_fc_actual_cost': 0.0,
                'x_fc_requires_requote': False,
                'x_fc_intake_template_id': False,
                'x_fc_service_catalog_id': False,
                'x_fc_maintenance_contract_id': False,
            })
            repair.message_post(
                body=Markup(_(
                    'Spawned follow-up repair <b>%(name)s</b> for "found another issue".'
                )) % {'name': stub.name or ''},
            )

        # M1: issue an inspection certificate when the box is ticked
        # AND the equipment is safety-critical (stairlift / porch lift / power chair).
        if self.issue_inspection_cert:
            self._create_inspection_certificate(repair)

        # T4 / T6 / T7: persist captured artefacts as ir.attachment on the
        # repair so they survive the wizard close.
        self._persist_mobile_artefacts(repair)

        # M5: burn a pre-paid service plan visit if the client has one and
        # the repair is a maintenance visit. The wizard intentionally does NOT
        # zero out the client's invoice line - the office still posts the
        # invoice; the burn is informational + the office reconciles credits
        # in their accounting flow.
        if not repair.x_fc_is_quote_only:
            self._burn_service_plan_visit(repair)

        # Bundle 8: parts-needed branch - capture the parts, flag the repair,
        # email the client, leave the repair OPEN with awaiting_parts substate.
        if self.outcome == 'parts_needed':
            self._handle_parts_needed(repair)
        elif self.outcome == 'rescheduled':
            repair.message_post(body=Markup(_(
                'Visit reported as <b>rescheduled</b>. Repair kept open.'
            )))
        # BUG-B1 fix: actually close the repair so the whole downstream chain
        # (NPS cron, dashboard "done this month" stats, customer survey) fires.
        # Leave open if requote needed - the office will re-quote and the tech
        # will revisit. No-show / parts-needed / rescheduled / quote-only also
        # stay open.
        elif (self.outcome == 'completed'
                and not self.requires_requote
                and not self.no_show
                and not repair.x_fc_is_quote_only
                and not stub):
            self._close_repair(repair)
        elif self.no_show:
            repair.message_post(body=Markup(_(
                'Repair kept <b>open</b> due to no-show. Office to reschedule.'
            )))
        elif self.requires_requote:
            repair.message_post(body=Markup(_(
                'Repair kept <b>open</b> pending re-quote (variance flag).'
            )))

        # If a stub was spawned, open it directly so the tech can fill in details.
        # Otherwise, if a certificate was issued, jump to it so the tech can print.
        if stub:
            return {
                'type': 'ir.actions.act_window',
                'name': stub.name,
                'res_model': 'repair.order',
                'view_mode': 'form',
                'res_id': stub.id,
            }
        if self.inspection_cert_id:
            return {
                'type': 'ir.actions.act_window',
                'name': self.inspection_cert_id.name,
                'res_model': 'fusion.repair.inspection.certificate',
                'view_mode': 'form',
                'res_id': self.inspection_cert_id.id,
            }
        return {
            'type': 'ir.actions.act_window',
            'name': repair.name,
            'res_model': 'repair.order',
            'view_mode': 'form',
            'res_id': repair.id,
        }

    def _persist_mobile_artefacts(self, repair):
        """T4/T6/T7: attach signature image, no-show photo, and serial list
        to the repair so they survive after the transient wizard closes."""
        Attachment = self.env['ir.attachment'].sudo()
        if self.client_signature:
            Attachment.create({
                'name': f'signature-{repair.name}.png',
                'datas': self.client_signature,
                'res_model': 'repair.order',
                'res_id': repair.id,
                'mimetype': 'image/png',
            })
            who = self.client_signature_name or repair.partner_id.name or ''
            repair.message_post(body=Markup(_(
                'Client signature captured (<b>%s</b>).'
            )) % who)
        if self.no_show:
            if self.no_show_photo:
                Attachment.create({
                    'name': f'no-show-{repair.name}.jpg',
                    'datas': self.no_show_photo,
                    'res_model': 'repair.order',
                    'res_id': repair.id,
                    'mimetype': 'image/jpeg',
                })
            repair.message_post(body=Markup(_(
                'Visit recorded as <b>client no-show</b>%s.'
            )) % (' (photo attached)' if self.no_show_photo else ''))
        if self.parts_serial_capture and self.parts_serial_capture.strip():
            repair.message_post(body=Markup(_(
                'Replaced part serials captured:<br/><pre>%s</pre>'
            )) % self.parts_serial_capture.strip())

    def _handle_parts_needed(self, repair):
        """Capture each part line as a fusion.repair.part.order record,
        flag the repair as Awaiting Parts, and email the client a
        "we found the problem - here's the timeline" note."""
        if not self.needs_parts_line_ids:
            raise UserError(_(
                'Tick "Can\'t Fix Today - Need to Order Parts" but no parts '
                'are captured. Add at least one part line so procurement can '
                'place the order.'
            ))
        PartOrder = self.env['fusion.repair.part.order'].sudo()
        Attachment = self.env['ir.attachment'].sudo()
        max_lead = 0
        for line in self.needs_parts_line_ids:
            # Copy any uploaded photos onto attachments owned by the part order.
            photo_ids = []
            for att in line.photo_ids:
                copied = Attachment.create({
                    'name': att.name,
                    'datas': att.datas,
                    'mimetype': att.mimetype,
                })
                photo_ids.append(copied.id)
            part = PartOrder.create({
                'repair_order_id': repair.id,
                'description': line.description,
                'oem_part_number': line.oem_part_number,
                'manufacturer': line.manufacturer,
                'quantity': line.quantity or 1.0,
                'notes': line.notes,
                'photo_ids': [(6, 0, photo_ids)] if photo_ids else False,
                'expected_date': line.expected_lead_days and (
                    fields.Date.context_today(self)
                    + timedelta(days=line.expected_lead_days)
                ) or False,
            })
            max_lead = max(max_lead, int(line.expected_lead_days or 0))
        repair.write({
            'x_fc_parts_awaiting': True,
            'x_fc_parts_eta_date': (
                fields.Date.context_today(self) + timedelta(days=max_lead + 2)
                if max_lead else False
            ),
        })
        # Office activity - "place these orders today".
        repair.activity_schedule(
            summary='Order parts from manufacturer(s)',
            note=_('Tech captured %d part(s) - place the order(s) today.'
                   ) % len(self.needs_parts_line_ids),
            user_id=repair.user_id.id or self.env.uid,
        )
        # Client comms.
        tpl = self.env.ref(
            'fusion_repairs.email_template_repair_awaiting_parts',
            raise_if_not_found=False,
        )
        if tpl and repair.partner_id and repair.partner_id.email:
            try:
                tpl.send_mail(repair.id, force_send=False)
            except Exception:
                _logger.exception('Awaiting-parts email failed for %s', repair.name)
        repair.message_post(body=Markup(_(
            'Visit reported as <b>parts needed</b>. Captured %(n)d part order(s); '
            'repair flagged "Awaiting Parts". Client notified.'
        )) % {'n': len(self.needs_parts_line_ids)})

    def _close_repair(self, repair):
        """Drive the Odoo native state machine from draft -> done.

        Odoo 19 sequence: draft -> action_validate (confirmed/under_repair)
        -> action_repair_start (under_repair) -> action_repair_end (done).
        Calls are guarded - silently re-runs only the missing steps.
        """
        try:
            if repair.state == 'draft':
                # action_validate is the standard entry path; if the product is
                # storable it expects reservations etc., so fall back to the
                # simpler _action_repair_confirm() helper if validate refuses.
                try:
                    repair.action_validate()
                except Exception as e:
                    _logger.info(
                        'action_validate skipped for %s: %s; using internal confirm.',
                        repair.name, e,
                    )
                    repair._action_repair_confirm()
            if repair.state == 'confirmed':
                repair.action_repair_start()
            if repair.state == 'under_repair':
                repair.action_repair_end()
            repair.message_post(body=Markup(_(
                'Visit report submitted - repair closed by <b>%s</b>.'
            )) % (self.technician_id.name or self.env.user.name))
        except Exception as e:
            _logger.exception(
                'Visit report could not close repair %s automatically: %s',
                repair.name, e,
            )
            repair.message_post(body=Markup(_(
                '<b>Could not auto-close repair</b>: %s. Office must close manually.'
            )) % str(e))

    def _burn_service_plan_visit(self, repair):
        """M5: deduct one visit from the most-recently-active service plan
        covering this repair. Quietly no-ops if the client has no plan."""
        Plan = self.env['fusion.repair.service.plan.subscription'].sudo()
        sub = Plan.find_for_repair(repair)
        if sub:
            sub.burn_visit(repair)

    def _create_inspection_certificate(self, repair):
        """M1: create the inspection certificate. Requires a safety-critical
        equipment category - otherwise just logs to chatter and skips."""
        category = repair.x_fc_repair_category_id
        if not category or not category.safety_critical:
            repair.message_post(body=_(
                'Inspection certificate skipped - equipment category is not '
                'flagged as safety_critical. Only stairlifts, porch lifts, '
                'and power wheelchairs receive annual certificates.'
            ))
            return
        if not repair.product_id:
            repair.message_post(body=_(
                'Inspection certificate skipped - the repair has no product set.'
            ))
            return
        Cert = self.env['fusion.repair.inspection.certificate'].sudo()
        cert = Cert.create({
            'partner_id': repair.partner_id.id,
            'product_id': repair.product_id.id,
            'lot_id': repair.lot_id.id if repair.lot_id else False,
            'repair_order_id': repair.id,
            'inspector_user_id': self.technician_id.id or self.env.uid,
        })
        self.inspection_cert_id = cert
        repair.message_post(body=_(
            'Issued inspection certificate %s (expires %s).'
        ) % (cert.name, cert.expiry_date))

    def _create_repair_part_moves(self, repair):
        """Create stock.move records for each part used (repair_line_type='add').

        Locations follow the repair order's configured source / parts locations;
        Odoo natively links these moves to the SO line generated by
        action_create_sale_order() so they invoice correctly.
        """
        Move = self.env['stock.move'].sudo()
        for line in self.parts_line_ids:
            if not line.product_id or line.quantity <= 0:
                continue
            vals = {
                'name': line.product_id.display_name,
                'product_id': line.product_id.id,
                'product_uom_qty': line.quantity,
                'product_uom': line.product_id.uom_id.id,
                'repair_id': repair.id,
                'repair_line_type': 'add',
                'location_id': repair.location_id.id,
                'location_dest_id': repair.parts_location_id.id or repair.location_id.id,
                'company_id': repair.company_id.id,
            }
            try:
                Move.create(vals)
            except Exception as e:
                _logger.warning(
                    'Could not create repair part move on %s for %s: %s',
                    repair.name, line.product_id.display_name, e,
                )


class RepairVisitReportWizardLine(models.TransientModel):
    _name = 'fusion.repair.visit.report.wizard.line'
    _description = 'Repair Visit Report Wizard - Part Line'

    wizard_id = fields.Many2one(
        'fusion.repair.visit.report.wizard',
        required=True,
        ondelete='cascade',
    )
    product_id = fields.Many2one(
        'product.product',
        string='Part',
        required=True,
    )
    quantity = fields.Float(default=1.0, required=True)
    unit_price = fields.Float(string='Unit Price')
    subtotal = fields.Float(compute='_compute_subtotal', store=True)

    @api.onchange('product_id')
    def _onchange_product_id(self):
        if self.product_id:
            self.unit_price = self.product_id.list_price

    @api.depends('quantity', 'unit_price')
    def _compute_subtotal(self):
        for line in self:
            line.subtotal = line.quantity * line.unit_price


class RepairVisitReportWizardPartLine(models.TransientModel):
    """Bundle 8: parts the tech needs the office to ORDER from the manufacturer.

    Captured during the visit report when outcome='parts_needed'; one record per
    distinct part. On wizard confirm, each line creates a
    fusion.repair.part.order which is the procurement-facing record.
    """
    _name = 'fusion.repair.visit.report.wizard.partline'
    _description = 'Visit Report - Part to Order'

    wizard_id = fields.Many2one(
        'fusion.repair.visit.report.wizard',
        required=True,
        ondelete='cascade',
    )
    description = fields.Char(
        string='Description',
        required=True,
        help='Plain English (e.g. "Handicare 1100 right armrest").',
    )
    oem_part_number = fields.Char(string='OEM #')
    manufacturer = fields.Char(string='Manufacturer')
    quantity = fields.Float(default=1.0, required=True)
    expected_lead_days = fields.Integer(
        string='Lead Time (days)',
        default=7,
        help='Tech estimate. Office uses this to set client ETA expectations.',
    )
    notes = fields.Text(string='Notes for Procurement')
    photo_ids = fields.Many2many(
        'ir.attachment',
        'fusion_repair_visit_partline_photo_rel',
        'partline_id', 'attachment_id',
        string='Photos',
    )