# Opening Balance Import Semantics

**Task:** AST-1.8.1
**Workbook:** [`templates/asset-opening-balance-import-template-v1.0.0.xlsx`](./templates/asset-opening-balance-import-template-v1.0.0.xlsx)
**Related cards:** AST-1.8.2 (staging), AST-1.8.3 (validation), and AST-1.8.4 (confirm)

## Workbook use

The workbook has three sheets with exact names:

1. `Serialized Assets`
2. `Quantity Assets`
3. `Optional Warranty`

The first row of every sheet is the header row. Rows after the header are data rows. Yellow empty cells are user-entry cells; the two rows already present on each sheet are fictional examples only and may be removed before a real upload.

The workbook is an opening-balance input contract. It does not authorise import processing, create an asset, post stock, or create a finance event. The later implementation must stage and validate all rows before a separately confirmed import applies them.

## Approved business rules

The following rules were explicitly approved for AST-1.8.1 and apply consistently to all future import processing.

1. **Reject duplicate Asset Codes.** A duplicate within the uploaded serialized sheet or against an existing `serialized_assets.asset_code` for the company is invalid. Asset Codes are never silently deduplicated.
2. **Never update existing Assets through opening balance import.** A matching existing Asset Code is an error, not an update instruction. The import only creates new opening records.
3. **Require explicit confirmation before import processing.** Uploading and validating a workbook do not create assets or stock. A separate, authorized confirm action is required before records are applied.

## Sheet behaviour

### Serialized Assets

Each row represents exactly one new `serialized_assets` record. `Item Code` must resolve to a serialized item, and reference-code fields must resolve within the importing company. The later import processor must enforce uniqueness of a supplied serial number for the resolved item as well as Asset Code uniqueness.

### Quantity Assets

Each row represents one opening quantity at one item-location pair. Confirmation must apply it through the existing receipt/inventory flow as an `OPENING_BALANCE` transaction, which updates the balance projection in the same transaction. Quantity must be positive. This task does not define weighted-average costing or finance postings.

### Optional Warranty

This sheet may be empty. When it contains a row, it must point to a serialized Asset Code created by the import and to an existing service provider. A warranty cannot be linked to a quantity item. `Ends On` must not precede `Starts On`.

## Out of scope

This version does not define upload endpoints, queue processing, preview, retries, migrations, employee asset writes, stock postings, finance postings, or a new approval engine. Those functions belong to later WBS cards.