@open-mercato/core 0.7.1-develop.7123.1.25365e718d → 0.7.1-develop.7130.1.fef2396fd8

package/src/modules/customers/backend/customers/deals/[id]/hooks/types.ts

@@ -6,29 +6,6 @@ export type DealAssociation = {
   isPrimary?: boolean
 }
 
-export type PersonAssociationApiRecord = {
-  id?: string
-  displayName?: string | null
-  display_name?: string | null
-  primaryEmail?: string | null
-  primary_email?: string | null
-  primaryPhone?: string | null
-  primary_phone?: string | null
-  personProfile?: { jobTitle?: string | null } | null
-  person_profile?: { jobTitle?: string | null } | null
-}
-
-export type CompanyAssociationApiRecord = {
-  id?: string
-  displayName?: string | null
-  display_name?: string | null
-  domain?: string | null
-  websiteUrl?: string | null
-  website_url?: string | null
-  companyProfile?: { domain?: string | null; websiteUrl?: string | null } | null
-  company_profile?: { domain?: string | null; websiteUrl?: string | null } | null
-}
-
 export type PipelineStageInfo = {
   id: string
   label: string

package/src/modules/customers/backend/customers/deals/[id]/hooks/useDealAssociations.ts

@@ -6,81 +6,11 @@ import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type {
-  CompanyAssociationApiRecord,
   DealAssociation,
   DealDetailPayload,
   GuardedMutationRunner,
-  PersonAssociationApiRecord,
 } from './types'
 
-export function normalizePersonAssociationRecord(
-  record: PersonAssociationApiRecord,
-  fallbackId: string,
-): DealAssociation {
-  const displayName =
-    typeof record.displayName === 'string' && record.displayName.trim().length
-      ? record.displayName.trim()
-      : typeof record.display_name === 'string' && record.display_name.trim().length
-        ? record.display_name.trim()
-        : null
-  const email =
-    typeof record.primaryEmail === 'string' && record.primaryEmail.trim().length
-      ? record.primaryEmail.trim()
-      : typeof record.primary_email === 'string' && record.primary_email.trim().length
-        ? record.primary_email.trim()
-        : null
-  const phone =
-    typeof record.primaryPhone === 'string' && record.primaryPhone.trim().length
-      ? record.primaryPhone.trim()
-      : typeof record.primary_phone === 'string' && record.primary_phone.trim().length
-        ? record.primary_phone.trim()
-        : null
-  const profile = record.personProfile ?? record.person_profile ?? null
-  const jobTitle =
-    profile && typeof profile.jobTitle === 'string' && profile.jobTitle.trim().length
-      ? profile.jobTitle.trim()
-      : null
-  return {
-    id: typeof record.id === 'string' ? record.id : fallbackId,
-    label: displayName ?? email ?? phone ?? fallbackId,
-    subtitle: jobTitle ?? email ?? phone ?? null,
-    kind: 'person',
-  }
-}
-
-export function normalizeCompanyAssociationRecord(
-  record: CompanyAssociationApiRecord,
-  fallbackId: string,
-): DealAssociation {
-  const displayName =
-    typeof record.displayName === 'string' && record.displayName.trim().length
-      ? record.displayName.trim()
-      : typeof record.display_name === 'string' && record.display_name.trim().length
-        ? record.display_name.trim()
-        : null
-  const profile = record.companyProfile ?? record.company_profile ?? null
-  const domain =
-    typeof record.domain === 'string' && record.domain.trim().length
-      ? record.domain.trim()
-      : profile && typeof profile.domain === 'string' && profile.domain.trim().length
-        ? profile.domain.trim()
-        : null
-  const website =
-    typeof record.websiteUrl === 'string' && record.websiteUrl.trim().length
-      ? record.websiteUrl.trim()
-      : typeof record.website_url === 'string' && record.website_url.trim().length
-        ? record.website_url.trim()
-        : profile && typeof profile.websiteUrl === 'string' && profile.websiteUrl.trim().length
-          ? profile.websiteUrl.trim()
-          : null
-  return {
-    id: typeof record.id === 'string' ? record.id : fallbackId,
-    label: displayName ?? domain ?? website ?? fallbackId,
-    subtitle: domain ?? website ?? null,
-    kind: 'company',
-  }
-}
-
 function sameIdList(left: string[], right: string[]): boolean {
   if (left.length !== right.length) return false
   return left.every((value, index) => value === right[index])
@@ -97,8 +27,12 @@ type UseDealAssociationsOptions = {
   data: DealDetailPayload | null
   setData: React.Dispatch<React.SetStateAction<DealDetailPayload | null>>
   runMutationWithContext: GuardedMutationRunner
-  /** Re-fetch the deal detail; wired into the conflict bar's refresh action on a 409. */
-  onRefresh?: (() => void) | null
+  /**
+   * Re-fetch the deal detail. Required, not optional: this hook no longer patches the list
+   * itself on success, so a caller without it would show a stale list *and* keep a superseded
+   * lock token that 409s on the next save. It also backs the conflict bar's refresh on a 409.
+   */
+  onRefresh: () => void | Promise<void>
 }
 
 type UseDealAssociationsResult = {
@@ -130,80 +64,6 @@ export function useDealAssociations({
     setCompaniesEditorIds(data?.linkedCompanyIds ?? [])
   }, [data?.linkedCompanyIds, data?.linkedPersonIds])
 
-  const loadPeopleAssociations = React.useCallback(async (ids: string[]): Promise<DealAssociation[]> => {
-    const uniqueIds = Array.from(new Set(ids.map((value) => value.trim()).filter(Boolean)))
-    if (!uniqueIds.length) return []
-    try {
-      const params = new URLSearchParams({
-        ids: uniqueIds.join(','),
-        pageSize: String(Math.max(uniqueIds.length, 1)),
-      })
-      const payload = await readApiResultOrThrow<{ items?: PersonAssociationApiRecord[] }>(
-        `/api/customers/people?${params.toString()}`,
-      )
-      const items = Array.isArray(payload.items) ? payload.items : []
-      const byId = new Map<string, PersonAssociationApiRecord>()
-      items.forEach((record) => {
-        if (record && typeof record.id === 'string') byId.set(record.id, record)
-      })
-      return uniqueIds.map((personId) => {
-        const record = byId.get(personId)
-        return record
-          ? normalizePersonAssociationRecord(record, personId)
-          : {
-              id: personId,
-              label: personId,
-              subtitle: null,
-              kind: 'person' as const,
-            }
-      })
-    } catch {
-      return uniqueIds.map((personId) => ({
-        id: personId,
-        label: personId,
-        subtitle: null,
-        kind: 'person' as const,
-      }))
-    }
-  }, [])
-
-  const loadCompanyAssociations = React.useCallback(async (ids: string[]): Promise<DealAssociation[]> => {
-    const uniqueIds = Array.from(new Set(ids.map((value) => value.trim()).filter(Boolean)))
-    if (!uniqueIds.length) return []
-    try {
-      const params = new URLSearchParams({
-        ids: uniqueIds.join(','),
-        pageSize: String(Math.max(uniqueIds.length, 1)),
-      })
-      const payload = await readApiResultOrThrow<{ items?: CompanyAssociationApiRecord[] }>(
-        `/api/customers/companies?${params.toString()}`,
-      )
-      const items = Array.isArray(payload.items) ? payload.items : []
-      const byId = new Map<string, CompanyAssociationApiRecord>()
-      items.forEach((record) => {
-        if (record && typeof record.id === 'string') byId.set(record.id, record)
-      })
-      return uniqueIds.map((companyId) => {
-        const record = byId.get(companyId)
-        return record
-          ? normalizeCompanyAssociationRecord(record, companyId)
-          : {
-              id: companyId,
-              label: companyId,
-              subtitle: null,
-              kind: 'company' as const,
-            }
-      })
-    } catch {
-      return uniqueIds.map((companyId) => ({
-        id: companyId,
-        label: companyId,
-        subtitle: null,
-        kind: 'company' as const,
-      }))
-    }
-  }, [])
-
   const loadLinkedPeoplePage = React.useCallback(
     async (page: number, query: string): Promise<LinkedPageResult> => {
       if (!currentDealId) {
@@ -274,17 +134,7 @@ export function useDealAssociations({
           ),
           { id: currentDealId, personIds: nextIds, operation: 'updateDealPeople' },
         )
-        const nextPeople = await loadPeopleAssociations(nextIds.slice(0, 3))
-        setData((prev) =>
-          prev
-            ? {
-                ...prev,
-                people: nextPeople,
-                linkedPersonIds: nextIds,
-                counts: { ...prev.counts, people: nextIds.length },
-              }
-            : prev,
-        )
+        await onRefresh()
       } catch (error) {
         setPeopleEditorIds(previousIds)
         setData((prev) =>
@@ -299,14 +149,14 @@ export function useDealAssociations({
         )
         // runMutationWithContext already surfaces the conflict bar on a 409; only
         // fall back to the generic flash when this is not a record conflict.
-        if (!surfaceRecordConflict(error, t, { onRefresh: onRefresh ?? null })) {
+        if (!surfaceRecordConflict(error, t, { onRefresh })) {
           flash(t('customers.deals.detail.peopleUpdateError', 'Failed to update linked people.'), 'error')
         }
       } finally {
         setPeopleSaving(false)
       }
     },
-    [currentDealId, data?.deal.updatedAt, data?.people, loadPeopleAssociations, onRefresh, peopleEditorIds, runMutationWithContext, setData, t],
+    [currentDealId, data?.deal.updatedAt, data?.people, onRefresh, peopleEditorIds, runMutationWithContext, setData, t],
   )
 
   const handleCompaniesAssociationsChange = React.useCallback(
@@ -325,17 +175,7 @@ export function useDealAssociations({
           ),
           { id: currentDealId, companyIds: nextIds, operation: 'updateDealCompanies' },
         )
-        const nextCompanies = await loadCompanyAssociations(nextIds.slice(0, 3))
-        setData((prev) =>
-          prev
-            ? {
-                ...prev,
-                companies: nextCompanies,
-                linkedCompanyIds: nextIds,
-                counts: { ...prev.counts, companies: nextIds.length },
-              }
-            : prev,
-        )
+        await onRefresh()
       } catch (error) {
         setCompaniesEditorIds(previousIds)
         setData((prev) =>
@@ -350,7 +190,7 @@ export function useDealAssociations({
         )
         // runMutationWithContext already surfaces the conflict bar on a 409; only
         // fall back to the generic flash when this is not a record conflict.
-        if (!surfaceRecordConflict(error, t, { onRefresh: onRefresh ?? null })) {
+        if (!surfaceRecordConflict(error, t, { onRefresh })) {
           flash(t('customers.deals.detail.companiesUpdateError', 'Failed to update linked companies.'), 'error')
         }
       } finally {
@@ -362,7 +202,6 @@ export function useDealAssociations({
       currentDealId,
       data?.companies,
       data?.deal.updatedAt,
-      loadCompanyAssociations,
       onRefresh,
       runMutationWithContext,
       setData,

package/src/modules/customers/backend/customers/deals/[id]/page.tsx

@@ -198,7 +198,7 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
     data,
     setData,
     runMutationWithContext,
-    onRefresh: () => { void loadData() },
+    onRefresh: () => loadData(),
   })
 
   const { isStageSaving, handleStageChange } = useDealPipeline({

package/src/modules/customers/commands/deals.ts

@@ -383,12 +383,49 @@ function toNumericString(value: number | null | undefined): string | null {
   return value.toString()
 }
 
+function sameLinkIdSet(next: Set<string>, current: Set<string>): boolean {
+  if (next.size !== current.size) return false
+  for (const id of next) {
+    if (!current.has(id)) return false
+  }
+  return true
+}
+
+/**
+ * The deal's optimistic-lock token is `customer_deals.updated_at`, and `CustomerDeal.updatedAt`
+ * is declared `onUpdate`-only — it advances only when the deal entity itself enters the change
+ * set. A `{ id, personIds }` or `{ id, companyIds }` payload mutates link rows exclusively, so
+ * without this explicit touch the token never moves: two clients editing the same deal's links
+ * from the same base version both pass the version check and the later stale whole-set payload
+ * silently reinstates what the earlier one removed.
+ *
+ * Assigning the property is what dirties the entity; the `onUpdate` hook then supplies the
+ * committed value, so the two do not fight. Same pattern as the profile-only branch in
+ * `people.ts`, which touches its parent for exactly this reason.
+ *
+ * Callers MUST only invoke this when the links actually changed — stamping on a no-op write
+ * would invalidate every other session's token on an idle save.
+ *
+ * ORDERING: this MUST be the last thing a sync helper does. MikroORM v7 discards a pending
+ * scalar change on a managed entity when a query runs on the same EntityManager before the
+ * flush (SPEC-018) — the same footgun the CRITICAL comment in `updateDealCommand` guards
+ * against, and these helpers are exactly the queries it names. Touching before
+ * `requireCustomerEntity` runs would silently drop the UPDATE and leave the token frozen.
+ */
+function touchDealLockToken(deal: CustomerDeal): void {
+  deal.updatedAt = new Date()
+}
+
 async function syncDealPeople(
   em: EntityManager,
   deal: CustomerDeal,
   personIds: string[] | undefined | null,
-  primaryPersonEntityId?: string | null
+  primaryPersonEntityId?: string | null,
+  options?: { stampLockToken?: boolean }
 ): Promise<void> {
+  // A freshly created deal has no other session holding a token to invalidate, and stamping
+  // there would only make `updated_at` overtake `created_at` on every new deal with links.
+  const stampLockToken = options?.stampLockToken !== false
   if (personIds === undefined) {
     if (primaryPersonEntityId === undefined) return
     const links = await em.find(CustomerDealPersonLink, { deal })
@@ -401,6 +438,18 @@ async function syncDealPeople(
         ),
       })
     }
+    const currentPrimaryId = links.find((link) => link.isPrimary)?.person?.id ?? null
+    // Nothing changed — same invariant the whole-set branch below enforces. Without this the
+    // clear loop and its flush would rewrite every link row just to put the flag back on the
+    // row it was already on, and would briefly leave the deal with no primary at all inside
+    // the transaction. Only one row can carry the flag (partial unique index on
+    // `deal_id where is_primary`), so there is no second stale flag left to clean up here.
+    if (currentPrimaryId === primaryPersonEntityId) return
+    // Safe here: only assignments and the explicit flush below follow — no query runs
+    // between this touch and the flush that persists it.
+    if (stampLockToken) {
+      touchDealLockToken(deal)
+    }
     for (const link of links) {
       link.isPrimary = false
     }
@@ -421,13 +470,30 @@ async function syncDealPeople(
       ),
     })
   }
+  // Read the current links once: this both resolves the inherited primary (as the previous
+  // `findOne(..., { isPrimary: true })` did) and lets us tell a real change from a no-op save,
+  // which the lock stamp below depends on.
+  const existingLinks = await em.find(CustomerDealPersonLink, { deal })
+  const currentPersonIds = new Set(existingLinks.map((link) => link.person.id))
+  const currentPrimaryId = existingLinks.find((link) => link.isPrimary)?.person?.id ?? null
+
   let effectivePrimaryId = primaryPersonEntityId
   if (effectivePrimaryId === undefined) {
-    const existingPrimary = await em.findOne(CustomerDealPersonLink, { deal, isPrimary: true })
-    effectivePrimaryId = existingPrimary?.person?.id ?? null
+    effectivePrimaryId = currentPrimaryId
   }
+  const linksChanged =
+    !sameLinkIdSet(new Set(unique), currentPersonIds) || effectivePrimaryId !== currentPrimaryId
+  // Nothing to do. Returning here also stops a no-op save from deleting and recreating every
+  // row, which would otherwise discard `participant_role`, `created_at` and the link ids while
+  // this function reports the write as a no-op to every other session.
+  //
+  // NOTE: this only covers the pure no-op. A genuine change below still deletes and recreates
+  // every row, so surviving participants do lose those columns — pre-existing behaviour that
+  // the set-diff in PR 3 of the linked-people parity spec removes. It is out of scope here
+  // because the linked date it corrupts is not rendered until that PR.
+  if (!linksChanged) return
+
   await em.nativeDelete(CustomerDealPersonLink, { deal })
-  if (!unique.length) return
   for (const personId of unique) {
     const person = await requireCustomerEntity(em, personId, { tenantId: deal.tenantId, organizationId: deal.organizationId }, 'person', 'Person not found')
     ensureSameScope(person, deal.organizationId, deal.tenantId)
@@ -438,17 +504,24 @@ async function syncDealPeople(
     })
     em.persist(link)
   }
+  // Last statement on purpose — see the ORDERING note on `touchDealLockToken`.
+  if (stampLockToken) touchDealLockToken(deal)
 }
 
 async function syncDealCompanies(
   em: EntityManager,
   deal: CustomerDeal,
-  companyIds: string[] | undefined | null
+  companyIds: string[] | undefined | null,
+  options?: { stampLockToken?: boolean }
 ): Promise<void> {
   if (companyIds === undefined) return
+  const stampLockToken = options?.stampLockToken !== false
+  const unique = Array.from(new Set(companyIds ?? []))
+  const existingLinks = await em.find(CustomerDealCompanyLink, { deal })
+  const currentCompanyIds = new Set(existingLinks.map((link) => link.company.id))
+  if (sameLinkIdSet(new Set(unique), currentCompanyIds)) return
+
   await em.nativeDelete(CustomerDealCompanyLink, { deal })
-  if (!companyIds || !companyIds.length) return
-  const unique = Array.from(new Set(companyIds))
   for (const companyId of unique) {
     const company = await requireCustomerEntity(em, companyId, { tenantId: deal.tenantId, organizationId: deal.organizationId }, 'company', 'Company not found')
     ensureSameScope(company, deal.organizationId, deal.tenantId)
@@ -458,6 +531,8 @@ async function syncDealCompanies(
     })
     em.persist(link)
   }
+  // Last statement on purpose — see the ORDERING note on `touchDealLockToken`.
+  if (stampLockToken) touchDealLockToken(deal)
 }
 
 const createDealCommand: CommandHandler<DealCreateInput, { dealId: string }> = {
@@ -530,8 +605,8 @@ const createDealCommand: CommandHandler<DealCreateInput, { dealId: string }> = {
           transitionedByUserId: normalizedTransitionAuthorUserId,
         })
       },
-      () => syncDealPeople(em, deal, parsed.personIds ?? [], parsed.primaryPersonEntityId),
-      () => syncDealCompanies(em, deal, parsed.companyIds ?? []),
+      () => syncDealPeople(em, deal, parsed.personIds ?? [], parsed.primaryPersonEntityId, { stampLockToken: false }),
+      () => syncDealCompanies(em, deal, parsed.companyIds ?? [], { stampLockToken: false }),
     ], { transaction: true })
 
     const de = (ctx.container.resolve('dataEngine') as DataEngine)

package/src/modules/customers/components/AddressEditor.tsx

@@ -24,7 +24,7 @@ import {
 } from '@open-mercato/ui/primitives/dialog'
 import { buildCountryOptions } from '@open-mercato/shared/lib/location/countries'
 import { buildHrefWithReturnTo } from '@open-mercato/shared/lib/navigation/returnTo'
-import type { AddressFormatStrategy } from '../utils/addressFormat'
+import { resolveTaxIdLabel, type AddressFormatStrategy } from '../utils/addressFormat'
 import { useAddressTypes } from './detail/hooks/useAddressTypes'
 
 type Translator = (key: string, fallback?: string, params?: Record<string, string | number>) => string
@@ -41,6 +41,20 @@ export type AddressEditorDraft = {
   region: string
   postalCode: string
   country: string
+  /**
+   * Contact details that belong to the ADDRESS rather than to the customer: the tax identifier it was
+   * invoiced under, and the phone a carrier calls about a delivery. Optional so every existing caller
+   * keeps compiling; callers must opt in with the matching `show*Field` props before they render.
+   */
+  taxId?: string
+  /**
+   * Which scheme the identifier belongs to, in Stripe's `{country}_{kind}` vocabulary. Chosen, not
+   * inferred: `PL1234567890` and `1234567890` are the same business written two ways, and a rule
+   * that reads the form of the value is guessing — the more schemes the vocabulary carries, the more
+   * often it guesses wrong, and a wrong type is worse than none because it names the number.
+   */
+  taxIdType?: string
+  phone?: string
   latitude?: string
   longitude?: string
   isPrimary: boolean
@@ -58,6 +72,9 @@ export type AddressEditorField =
   | 'region'
   | 'postalCode'
   | 'country'
+  | 'taxId'
+  | 'taxIdType'
+  | 'phone'
   | 'latitude'
   | 'longitude'
   | 'isPrimary'
@@ -72,8 +89,33 @@ type AddressEditorProps = {
   hidePrimaryToggle?: boolean
   showFormatHint?: boolean
   showCoordinateFields?: boolean
+  /**
+   * Render the phone. Off by default, opt-in for the same reason `showCoordinateFields` is: only a
+   * caller whose storage can hold a field should offer it.
+   */
+  showPhoneField?: boolean
+  /**
+   * Render the tax identifier and its scheme. Separate from the phone, and not for symmetry — a
+   * phone is a contact detail and a tax identifier is not, and the two stop travelling together at
+   * the next phase: `CustomerAddress` gains a `phone` column and no tax id, so the address book will
+   * offer one and not the other.
+   *
+   * Both gate the CALLER, not the field. Inside a tile that opts in, the input renders whether or not
+   * it carries a value and takes the same `disabled` as every neighbour.
+   */
+  showTaxIdField?: boolean
 }
 
+/**
+ * The schemes offered in the picker, in the order a Polish deployment meets them. The vocabulary is
+ * additive under the backward-compatibility contract, so a new scheme is a new entry here rather
+ * than a new branch in a rule that has to guess.
+ *
+ * The labels are the ones `resolveTaxIdLabel` resolves, so the picker and the marker beside the
+ * filled field always read the same.
+ */
+const TAX_ID_TYPES = ['pl_nip', 'eu_vat', 'other'] as const
+
 export function AddressEditor({
   value,
   onChange,
@@ -84,6 +126,8 @@ export function AddressEditor({
   hidePrimaryToggle = false,
   showFormatHint = true,
   showCoordinateFields = false,
+  showPhoneField = false,
+  showTaxIdField = false,
 }: AddressEditorProps) {
   const pathname = usePathname()
   const searchParams = useSearchParams()
@@ -102,6 +146,11 @@ export function AddressEditor({
     [t],
   )
 
+  const taxIdLabels = {
+    plNip: t('customers.people.detail.addresses.fields.taxId.plNip', 'Tax ID'),
+    euVat: t('customers.people.detail.addresses.fields.taxId.euVat', 'EU VAT'),
+    other: t('customers.people.detail.addresses.fields.taxId.other', 'Tax number'),
+  }
   const current: AddressEditorDraft = {
     name: value.name ?? '',
     purpose: value.purpose ?? '',
@@ -114,6 +163,9 @@ export function AddressEditor({
     region: value.region ?? '',
     postalCode: value.postalCode ?? '',
     country: value.country ?? '',
+    taxId: value.taxId ?? '',
+    taxIdType: value.taxIdType ?? '',
+    phone: value.phone ?? '',
     ...(showCoordinateFields
       ? { latitude: value.latitude ?? '', longitude: value.longitude ?? '' }
       : {}),
@@ -472,6 +524,69 @@ export function AddressEditor({
             {errors.longitude ? <p className="text-xs text-destructive">{errors.longitude}</p> : null}
           </>
         ) : null}
+        {showTaxIdField ? (
+          <>
+            <Select
+              value={current.taxIdType || undefined}
+              onValueChange={(next) => update('taxIdType', next ?? '')}
+              disabled={disabled}
+            >
+              <SelectTrigger
+                className={errors.taxIdType ? 'border-destructive' : undefined}
+                aria-label={t('customers.people.detail.addresses.fields.taxIdType', 'Tax id type')}
+                aria-invalid={errors.taxIdType ? 'true' : undefined}
+              >
+                <SelectValue
+                  placeholder={t('customers.people.detail.addresses.fields.taxIdType', 'Tax id type')}
+                />
+              </SelectTrigger>
+              <SelectContent>
+                {TAX_ID_TYPES.map((type) => (
+                  <SelectItem key={type} value={type}>
+                    {resolveTaxIdLabel(taxIdLabels, type)}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <Input
+              className={inputClass('taxId')}
+              placeholder={t('customers.people.detail.addresses.fields.taxId', 'Tax number')}
+              aria-label={t('customers.people.detail.addresses.fields.taxId', 'Tax number')}
+              rightIcon={
+                current.taxId ? (
+                  <span className="text-xs">{resolveTaxIdLabel(taxIdLabels, current.taxIdType)}</span>
+                ) : null
+              }
+              value={current.taxId ?? ''}
+              onChange={(evt) => update('taxId', evt.target.value)}
+              disabled={disabled}
+              aria-invalid={errors.taxId ? 'true' : undefined}
+            />
+            {errors.taxId ? <p className="text-xs text-destructive">{errors.taxId}</p> : null}
+          </>
+        ) : null}
+        {showPhoneField ? (
+          <>
+            <Input
+              className={inputClass('phone')}
+              placeholder={t('customers.people.detail.addresses.fields.phone', 'Phone')}
+              aria-label={t('customers.people.detail.addresses.fields.phone', 'Phone')}
+              rightIcon={
+                current.phone ? (
+                  <span className="text-xs">
+                    {t('customers.people.detail.addresses.fields.phone', 'Phone')}
+                  </span>
+                ) : null
+              }
+              inputMode="tel"
+              value={current.phone ?? ''}
+              onChange={(evt) => update('phone', evt.target.value)}
+              disabled={disabled}
+              aria-invalid={errors.phone ? 'true' : undefined}
+            />
+            {errors.phone ? <p className="text-xs text-destructive">{errors.phone}</p> : null}
+          </>
+        ) : null}
       </div>
       {!hidePrimaryToggle ? (
         <label className="inline-flex items-center gap-2 text-sm">

package/src/modules/customers/i18n/de.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Adresszeile 1",
   "customers.people.detail.addresses.fields.line2": "Adresszeile 2",
   "customers.people.detail.addresses.fields.longitude": "Längengrad",
+  "customers.people.detail.addresses.fields.phone": "Telefon",
   "customers.people.detail.addresses.fields.postalCode": "Postleitzahl",
   "customers.people.detail.addresses.fields.primary": "Als primär markieren",
   "customers.people.detail.addresses.fields.region": "Bundesland / Region",
   "customers.people.detail.addresses.fields.street": "Straße",
   "customers.people.detail.addresses.fields.streetExtra": "Weitere Adressangaben",
+  "customers.people.detail.addresses.fields.taxId": "Steuernummer",
+  "customers.people.detail.addresses.fields.taxId.euVat": "USt-IdNr.",
+  "customers.people.detail.addresses.fields.taxId.other": "Steuerliche Nummer",
+  "customers.people.detail.addresses.fields.taxId.plNip": "Steuernummer",
+  "customers.people.detail.addresses.fields.taxIdType": "Art der Steuernummer",
   "customers.people.detail.addresses.fields.type": "Adresstyp",
   "customers.people.detail.addresses.formatLoadError": "Adresskonfiguration konnte nicht geladen werden",
   "customers.people.detail.addresses.formatLoading": "Adresspräferenzen werden geladen…",

package/src/modules/customers/i18n/en.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Address line 1",
   "customers.people.detail.addresses.fields.line2": "Address line 2",
   "customers.people.detail.addresses.fields.longitude": "Longitude",
+  "customers.people.detail.addresses.fields.phone": "Phone",
   "customers.people.detail.addresses.fields.postalCode": "Postal code",
   "customers.people.detail.addresses.fields.primary": "Set as primary",
   "customers.people.detail.addresses.fields.region": "Region / State",
   "customers.people.detail.addresses.fields.street": "Street",
   "customers.people.detail.addresses.fields.streetExtra": "Additional address details",
+  "customers.people.detail.addresses.fields.taxId": "Tax number",
+  "customers.people.detail.addresses.fields.taxId.euVat": "EU VAT",
+  "customers.people.detail.addresses.fields.taxId.other": "Tax number",
+  "customers.people.detail.addresses.fields.taxId.plNip": "Tax ID",
+  "customers.people.detail.addresses.fields.taxIdType": "Tax id type",
   "customers.people.detail.addresses.fields.type": "Address type",
   "customers.people.detail.addresses.formatLoadError": "Failed to load address configuration",
   "customers.people.detail.addresses.formatLoading": "Loading address preferences…",

package/src/modules/customers/i18n/es.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Dirección (línea 1)",
   "customers.people.detail.addresses.fields.line2": "Dirección (línea 2)",
   "customers.people.detail.addresses.fields.longitude": "Longitud",
+  "customers.people.detail.addresses.fields.phone": "Teléfono",
   "customers.people.detail.addresses.fields.postalCode": "Código postal",
   "customers.people.detail.addresses.fields.primary": "Marcar como principal",
   "customers.people.detail.addresses.fields.region": "Provincia / región",
   "customers.people.detail.addresses.fields.street": "Calle",
   "customers.people.detail.addresses.fields.streetExtra": "Detalles adicionales de la dirección",
+  "customers.people.detail.addresses.fields.taxId": "Número fiscal",
+  "customers.people.detail.addresses.fields.taxId.euVat": "IVA UE",
+  "customers.people.detail.addresses.fields.taxId.other": "Número fiscal",
+  "customers.people.detail.addresses.fields.taxId.plNip": "NIF",
+  "customers.people.detail.addresses.fields.taxIdType": "Tipo de número fiscal",
   "customers.people.detail.addresses.fields.type": "Tipo de dirección",
   "customers.people.detail.addresses.formatLoadError": "No se pudo cargar la configuración de la dirección",
   "customers.people.detail.addresses.formatLoading": "Cargando preferencias de dirección…",