Add Company & Place Population doc

Company-and-Place-Population.md

@@ -0,0 +1,37 @@
+# Company & Place Data Population
+
+Assets in the tracker display **company** (customer name) and **place** (city) information in the card view. These fields are populated from the MSFS Dynamics 365 extraction DB.
+
+## How It Works
+
+The migration script `scripts/populate_asset_company_place.py` maps each asset's `connect_id` through the extraction DB:
+
+1. `msdyn_customerasset.hsl_connectid` matches `assets.connect_id`
+2. `msdyn_customerasset.msdyn_account!id` links to `account.accountid`
+3. `account.name` → `asset.company` and `asset.customer_name`
+4. `account.address1_city` → `asset.place`
+5. `account.address1_line1` (+ line2) → `asset.address` (only if empty)
+
+## Coverage
+
+- **5,743 / 7,488** assets (~77%) have company + customer_name populated
+- **5,647 / 7,488** assets (~75%) have place (city) populated
+- The remaining ~1,745 assets have connect_ids in the extraction DB but no linked account info
+
+## Re-running
+
+The script is idempotent — it only updates fields that are empty:
+
+```bash
+cd ~/projects/canteen-asset-tracker
+python3 scripts/populate_asset_company_place.py
+```
+
+## SQL Query Fix
+
+The `GET /api/assets` endpoint uses `COALESCE(c.name, a.customer_name)` instead of `c.name AS customer_name` to prevent the LEFT JOIN from overriding stored customer_name with NULL when `customer_id` is not set.
+
+```sql
+SELECT a.*, COALESCE(c.name, a.customer_name) AS customer_name
+FROM assets a LEFT JOIN customers c ON a.customer_id = c.id
+```