# Frontend Migration Prompt: Receivable/Payable API Upgrade

Use this prompt to migrate existing frontend API calls from legacy loan endpoints to the new receivable/payable architecture.

## Goal

Refactor all frontend logic that uses legacy loan modules to the new modules:
- receivable records
- receivable payments
- payable payments
- account receivable with professional name

## Critical Backend Changes

1. Legacy modules deleted:
- /api/v1/loan-accounts
- /api/v1/loans
- /api/v1/loan-payments

2. New modules added:
- /api/v1/accounts-receivable
- /api/v1/receivable-records
- /api/v1/receivable-payments
- /api/v1/accounts-payable
- /api/v1/payable-payments

3. Receivable account model update:
- new field: professionalName

4. Separate payment systems:
- receivable payments are now independent from payable payments
- do not mix payable payment endpoints with receivable record endpoints

## Endpoint Mapping

### Accounts (Receivable)
- Old: GET/POST /api/v1/loan-accounts
- New: GET/POST /api/v1/accounts-receivable

- Old: GET/PATCH/DELETE /api/v1/loan-accounts/:id
- New: GET/PATCH/DELETE /api/v1/accounts-receivable/:id

Payload updates:
- include optional professionalName in create/update forms

Response updates:
- account details now return receivableRecords instead of loans

### Receivable Records (Old Loans)
- Old: GET/POST /api/v1/loans
- New: GET/POST /api/v1/receivable-records

- Old: GET/PATCH/DELETE /api/v1/loans/:id
- New: GET/PATCH/DELETE /api/v1/receivable-records/:id

### Receivable Payments (Old Loan Payments)
- Old: GET/POST /api/v1/loan-payments
- New: GET/POST /api/v1/receivable-payments

- Old: GET/PATCH/DELETE /api/v1/loan-payments/:id
- New: GET/PATCH/DELETE /api/v1/receivable-payments/:id

- Old nested: GET/POST /api/v1/loans/:id/payments
- New nested: GET/POST /api/v1/receivable-records/:id/payments

- Old nested update/delete: PATCH/DELETE /api/v1/loans/payments/:paymentId
- New nested update/delete: PATCH/DELETE /api/v1/receivable-records/payments/:paymentId

Query updates:
- Old query key: loanId
- New query key: receivableRecordId (also accepts nested :id route)

### Payable Payments (New)
- New standalone:
  - GET/POST /api/v1/payable-payments
  - GET/PATCH/DELETE /api/v1/payable-payments/:id

- New nested on account payable:
  - GET/POST /api/v1/accounts-payable/:id/payments

## Field Naming Guidance for Frontend

Maintain backward compatibility in UI data adapters:
- Backend still stores reference field as loanId for internal compatibility
- In frontend domain models, map loanId -> receivableRecordId
- Display label changes:
  - Loan -> Receivable Record
  - Loan Payment -> Receivable Payment

Recommended UI label map:
- loanNumber -> recordNumber
- loans list -> receivable records list
- loan status -> receivable status

## Frontend Refactor Checklist

1. Replace API base paths:
- /loan-accounts -> /accounts-receivable
- /loans -> /receivable-records
- /loan-payments -> /receivable-payments

2. Add professionalName field to:
- create receivable account form
- update receivable account form
- account details card/table

3. Update route-level data fetchers and hooks:
- useReceivableRecords
- useReceivablePayments
- usePayablePayments

4. Update nested payment screens:
- account receivable record details should call /receivable-records/:id/payments
- account payable details should call /accounts-payable/:id/payments

5. Update TypeScript interfaces (or JS docs):
- AccountReceivable includes professionalName?: string
- Replace Loan types with ReceivableRecord types
- Split payment types into ReceivablePayment and PayablePayment

6. Update translation/localization keys:
- remove legacy loan naming in labels, headings, and toasts

7. Keep temporary compatibility adapter:
- if a component still expects loanId, map from receivableRecordId during transition

## Suggested Frontend Adapter Example

```ts
function normalizeReceivableRecord(raw: any) {
  return {
    ...raw,
    receivableRecordId: raw.loanId ?? raw._id,
    recordNumber: raw.loanNumber,
  };
}
```

## QA Scenarios

1. Create account receivable with professionalName.
2. Create receivable record for an account.
3. Add receivable payment from record details page.
4. Add payable payment from account payable details page.
5. Confirm payable payments do not appear in receivable payment screens.
6. Confirm receivable account details show receivableRecords list.
7. Confirm invoice creation still auto-generates receivable record linkage.

## Rollout Strategy

1. Deploy backend first.
2. Merge frontend endpoint/path changes in one branch.
3. Enable adapter layer for temporary field compatibility.
4. Remove adapter after all screens migrated.