Attribute documents to a Customer via the buyer identifier, derive the company

[jbagsik]

Parent

#21

What to build

An e-billing document is attributed to the Customer it was billed under, resolved from the buyer
identifier on the invoice. The company attribution remains, but is now derived from the customer
rather than guessed from a name — and is documented as reporting only, never an access boundary.

This is the identity change. A company can hold several customer records (one per plant, price list
or settlement purpose); attributing to the company collapses them, and a company attribution frozen
at match time goes stale the moment a customer is reassigned. Consumers are told to gate visibility
on the customer attribution, which callers resolve live.

Corroboration — checking that the name, VAT identifier, country and address agree with the matched
record — is deliberately not in this ticket. Here the identifier decides alone.

Acceptance criteria

• The document carries a nullable, indexed customer attribution; the company attribution remains
  and is populated by derivation from the matched customer.
• A document whose identifier resolves to exactly one customer is attributed to it.
• Identifier comparison normalises by trim, whitespace collapse and uppercase only — no numeric
  interpretation, no stripping or padding of leading zeros. 0815 and 815 resolve to different
  customers.
• Lookups include soft-deleted customers, so a deleted customer resolves and is reported as
  found but deleted rather than not found. Same for an inactive customer.
• A customer resolving to more than one company yields a null company attribution — never a
  silently chosen first row.
• A customer with no company yields a null company attribution and still keeps the customer
  attribution.
• With no identifier present, the name fallback from the unified resolver still runs and sets the
  company attribution — and never the customer attribution.
• The package depends on moox/customer. No resolver interface is introduced.
• Covered through the field validator's public validate entry point — the matcher gets no seam of
  its own. This adds the first test for that entry point.

Blocked by

• Prefactor: unify the duplicated party-name match into one resolver #22 — extends the unified resolver rather than a second copy.
• Carry the buyer identifier from the parser DTO onto the invoice #23 — needs the identifier persisted on the invoice to match on.

[jbagsik]

Done

Implemented in mooxphp/moox (packages/e-billing) with host migration mirror in heco-gmbh/web.

What shipped

• Schema: nullable indexed ebilling_documents.customer_id FK → customers (nullOnDelete); company_id unchanged, documented as reporting-only (never an access boundary).
• Model: EbillingDocument::customer() BelongsTo; customer_id in fillable / PHPDoc.
• Matching: internal Support\CustomerMatcher (no resolver interface):
  • match() — buyer identifier via trim + whitespace collapse + uppercase; Customer::withTrashed(); exactly one hit required; 0815 ≠ 815.
  • resolveCompanyId() — derives company from customer_assignments (Company morph); exactly one assignment → id, else null (never first row).
  • isReviewableMatch() — soft-deleted or inactive customer → needs_review on customer_number while keeping customer_id.
• Validator: InvoiceFieldValidator::fillFieldValidations / validate:
  • identifier present + unique customer → customer_id + derived company_id;
  • no identifier → CompanyNameMatcher name fallback sets company_id only, never customer_id;
  • identifier present but unmatched → customer_number needs_review, name fallback may still set company_id (parent Resolve documents to a Customer by buyer identifier, with corroboration and review #21 cascade).
• Dependency: moox/customer added to composer.json.
• Tests: tests/Feature/InvoiceFieldValidatorCustomerAttributionTest.php (+ updated customer_number test) — all via public validate() / fillFieldValidations entry point; matcher has no dedicated test seam.
• Docs: CHANGELOG.md, README.md, CONTEXT.md updated.

Acceptance criteria

• Nullable indexed customer attribution; company derived from matched customer
• Identifier → exactly one customer → attributed
• Normalisation: trim, collapse whitespace, uppercase only; leading zeros preserved
• Soft-deleted / inactive customers: found, needs_review, customer_id set
• >1 company → company_id null
• 0 companies → company_id null, customer_id kept
• No identifier → name fallback → company_id only
• Depends on moox/customer; no resolver interface
• Covered through field validator public entry point

Explicitly out of scope (later tickets)

• Name/VAT/address corroboration (parent Resolve documents to a Customer by buyer identifier, with corroboration and review #21)
• Portal visibility switch from company_id to customer_id (ADR 0006 follow-up)

Follow-up (team note)

Consider moving resolveCompanyId into moox/customer (e.g. Customer::uniqueAssignedCompanyId()) so debtor→company derivation lives in one place; current direct customer_assignments query is intentional for #24 (explicit, no host relation-config dependency).

Host republish

After merge:

php artisan vendor:publish --tag="e-billing-migrations" --force
php artisan config:clear

[jbagsik]

Closing — implementation complete per acceptance criteria above. Corroboration and portal access boundary remain tracked under parent #21.