Let a credit note say which invoice it corrects (fk_facture_source)

[Pichinov-Jose]

Closes #28.

The gap

The module already builds credit notes. src/Objects/CreditNote.php reuses the invoice traits, and
Invoice/CRUDTrait sets type = Facture::TYPE_CREDIT_NOTE on create. What it cannot express is
which invoice the credit note corrects: fk_facture_source appears nowhere in src/.

So every credit note that reaches Dolibarr through Splash arrives an orphan.

That link is not decoration:

• the source invoice stays settled at its full amount, so the customer ledger never nets out;
• Dolibarr's own screen cannot offer convert into a discount — compta/facture/card.php reaches
  confirm_converttoreduc through the source invoice, and that is the correct treatment when the
  money never actually moved (a waived fee, a goodwill gesture, a 100 % discount);
• reporting cannot pair a credit note with what it corrects.

The change

fk_facture_source is exposed as an Invoice object id, declared only when the object is a
CreditNote, so standard invoices are untouched:

if ($this instanceof CreditNote) {
    $this->fieldsFactory()->create((string) self::objects()->encode("Invoice", SPL_T_ID))
        ->identifier("fk_facture_source")
        ->name($langs->trans("CorrectInvoice"))
        ->microData("http://schema.org/Invoice", "referencesOrder")
        ->isIndexed()
    ;
}

Reads encode the stored id back into an Invoice object id, or null when unset.

Writes are checked before they land

Dolibarr stores this link as a bare integer with no foreign key. An invalid value is therefore
accepted silently and only surfaces much later, when the source invoice fails to load — at which
point the trail is cold. isValidSourceInvoice() refuses three cases up front:

• an id that matches no invoice;
• an id pointing at another credit note;
• an id pointing at the credit note itself.

Each refusal is logged with the offending id rather than failing quietly.

Verified

Replayed against a production install carrying 109 credit notes: all 109 resolve to a valid source
under this rule, and the three rejection cases are correctly refused while a genuine invoice is
accepted.

One question for the maintainers

CreditNote currently carries protected static bool $disabled = true;, so the object is not
offered at all. This PR deliberately does not touch that flag — enabling the object is a product
decision, not a bug fix. But the field is inert until it is lifted, so I would rather ask than
assume: is the object disabled because it is unfinished, or on purpose?

Related

Filed as SplashSync/Wordpress#17: WooCommerce refunds are never exported — there is no CreditNote
object and no refund hook on that side, so nothing produces the credit note this field would
receive. The two together are what make a refund representable end to end; this one is the half that
can be fixed today.