# History

How the History of a car and of the collection (M-Historico) is derived from purchases, sales, services, upgrades, documents, valuations and flagged odometer readings, sold cars included.

## What it does [#what-it-does]

The History (RF21, US25) is the story of one car, or of every car the Organization has owned: sold cars are included, archived cars are left out of the collection's. Nothing is stored for it. One procedure reads the records as they stand and returns History Events newest first, a page at a time:

| Kind        | From                                                                                                       |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| `bought`    | each Ownership Period: the date of its latest Acquisition header, or the period's start before one         |
| `sold`      | each Disposal                                                                                              |
| `service`   | each Service, with its title and reading                                                                   |
| `expense`   | each upgrade Expense, through the ledger entry holding its current values (running costs stay on M-Gastos) |
| `document`  | each Vehicle Document but receipts, on the day it was filed                                                |
| `valuation` | the latest Valuation of each car per calendar year, with its source and confidence (RN03)                  |
| `odometer`  | each flagged (lower) Odometer Reading, with its reason (RN07)                                              |

## Procedures [#procedures]

| Procedure                                                               | Who                         | Failures                              |
| ----------------------------------------------------------------------- | --------------------------- | ------------------------------------- |
| `vehicleHistory.list` `{ vehicleId?, kinds?, years?, cursor?, limit? }` | Members of the Organization | `INPUT_VALIDATION`, `NOT_FOUND` (car) |

`limit` is at most 100 (50 by default). The cursor is the last event's date and id. The first page also answers `years`, every year with an event in scope, for the filter.

## Data and isolation [#data-and-isolation]

Every branch filters by the Active Organization and runs as `app_tenant`, so row-level security isolates it too. Amounts are integer minor units with their currency; distances are km.

## App [#app]

M-Historico (`screen-M-Historico`, route `/history`) opens from a car's profile (that car) and, with no `vehicleId`, for the whole collection. The segmented control narrows to Costs (upgrades), Service or Documents; the filter button (`historico-filtro`) opens a sheet with the car (or every car), the kinds of event and the years. Each card shows the year, the car, what happened, and the car's photo for a purchase or sale, else a grey icon chip. A service or document opens its record, anything else the car's profile.

`autofolio://dev/M-Historico` opens the seeded collection.

## Key files [#key-files]

- [`packages/api/src/features/vehicle-history/vehicle-history.contract.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/api/src/features/vehicle-history/vehicle-history.contract.ts)
- [`packages/api/src/features/vehicle-history/vehicle-history.service.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/api/src/features/vehicle-history/vehicle-history.service.ts)
- [`apps/mobile/src/features/vehicle-history/vehicle-history.screen.tsx`](https://github.com/CarlosZiegler/autofolio/blob/main/apps/mobile/src/features/vehicle-history/vehicle-history.screen.tsx)