# Gold Evaluation

## Gold rate settings

CRM admins save branch-wide 24K, 22K and 18K rates plus LTV at `POST /api/crm/gold-rate-settings`. Records are append-only: the latest saved record for today's effective date (Asia/Kolkata) is current. `GET /api/crm/gold-rate-settings/current` returns that record or `null`, and `GET /api/crm/gold-rate-settings` returns paginated history. `MAX_GOLD_LTV_PERCENT` sets the allowed upper LTV limit (default 90%). Existing databases can apply `prisma/gold_rate_settings.sql` once, then generate the Prisma client.

New evaluations use today's settings. Drafts pin a settings record; later corrections require `POST /api/crm/applications/evaluation/refresh-rates/:id` before finalisation. A draft without today's settings can be saved, but finalisation requires today's latest record. A finalised evaluation retains its settings ID, item rates, LTV and totals when future rates change. Rates for 22K and 18K are used directly, with no purity conversion. Mixed purity has no configured rate and cannot be finalised until a supported purity is selected.

The CRM Gold Evaluation queue reads applications with stored status `GOLD_EVALUATION`. The API also accepts `status=EVALUATING` when listing, to match the UI label. The list supports the same search, date, branch, pagination and Refresh controls as Pending and Follow-up. Each row shows KYC and evaluation state and opens the saved assessment.

## Data

- `gold_evaluations.application_id` is unique: one editable evaluation per application. Status is `DRAFT` or `FINALIZED`; `gold_rate_setting_id` pins the settings record.
- `gold_items` contains the saved ornaments. Draft items may be incomplete. A draft PUT updates existing item IDs, adds new items and removes omitted items in one transaction.
- `gold_item_images` maps each saved item to private Firebase Storage file keys. A photo belongs to one item.
- Photos are stored at `golditems/<applicationId>/<uuid>.png` or `golditems/<applicationId>/<uuid>.jpg` in the configured Firebase bucket. Only the key is stored in MySQL. The CRM preview endpoint checks the admin and branch before returning bytes. PNG and JPEG uploads are limited to 5 MB and checked by file signature.
- If a finalised evaluation changes after moving to Loan Offer, the save returns the application to Gold Evaluation, resets the assessment to Draft and adds a status-history entry. Staff must finalise and move it again. Existing accepted or declined offer versions remain in history; a new offer version needs a fresh decision before Credit Approval.

## APIs

All CRM endpoints require an active admin session. The application or image ID is the final route segment.

| Method | Route | Use |
| --- | --- | --- |
| GET | `/api/crm/applications?status=EVALUATING` | Evaluation queue. Stored status is `GOLD_EVALUATION`. |
| GET | `/api/crm/applications/evaluation/:id` | Application, KYC summary and saved evaluation. |
| PUT | `/api/crm/applications/evaluation/:id` | Save or replace a draft. Body: `goldRate`, `ltvPercentage`, `remarks`, `items[]`. |
| POST | `/api/crm/applications/evaluation/finalize/:id` | Validate saved items/photos/KYC and calculate final totals. Application stays in Gold Evaluation. |
| POST | `/api/crm/applications/evaluation/refresh-rates/:id` | Recalculate a saved draft from today's latest settings. |
| POST | `/api/crm/applications/evaluation/images/:id` | Upload PNG/JPEG bytes as `application/octet-stream`; returns `file_key`. |
| GET | `/api/crm/applications/evaluation/image/:imageId` | Authorized photo preview. |
| PATCH | `/api/crm/applications/status/:id` | Move to `LOAN_OFFER` only if evaluation is finalised and KYC remains verified, or to `REJECTED` with a reason. |

Item fields: `id` for existing items, `itemType`, `quantity`, `purity`, `grossWeight`, `deductionWeight`, `description`, and `images` as an array of uploaded file keys. The server chooses `rateUsed` from the pinned settings for each item's purity, derives net weight as gross minus deduction, item valuation as net weight times rate used, total valuation as the sum of items, and eligible amount as total valuation times LTV / 100. It uses decimal arithmetic and rounds monetary results to two places.

Saving an unchanged finalised evaluation preserves its state. Changing rate, LTV, remarks, items or photos resets finalisation. Finalising requires verified KYC, positive rate and LTV, at least one complete item and a saved photo for each item. The Loan Offer move is a separate status action and its update and history insert are atomic.