@7365admin1/layer-common 4.35.1-staging.425 → 4.35.1-staging.427

package/components/AreaMain.vue

@@ -64,9 +64,8 @@
                       v-bind="t"
                       class="ma-1 screen-icon-btn"
                       variant="flat"
-                      href="/files/area-sample-data.xlsx"
-                      target="_blank"
-                      download
+                      :loading="templateDownloading"
+                      @click="downloadLiveTemplate"
                     >
                       <v-icon>mdi-download</v-icon>
                     </v-btn>
@@ -310,16 +309,25 @@
 
   <Snackbar v-model="messageSnackbar" :text="message" :color="messageColor" />
 
-  <input
-    ref="fileInput"
-    type="file"
-    accept=".csv,.xlsx,.xls"
-    style="display: none"
-    @change="onFileSelected"
+  <ImportExcelDialog
+    v-model="showImport"
+    title="Import Areas from Excel"
+    noun="areas"
+    name-label="Area"
+    fill-hint="One area per row: its name, Type (Common or Toilet, from the dropdown), Set and the units to check, separated by commas."
+    duplicate-note="Areas already on the list (same name and type) are skipped and left unchanged."
+    template-file-name="areas-import-template.xlsx"
+    :download-template="() => downloadTemplate('areas', importQuery)"
+    :check="(file: File) => checkImport('areas', file, importQuery)"
+    :commit="(file: File) => commitImport('areas', file, importQuery)"
+    @done="getTaskRefresh()"
+    @error="(text: string) => showMessage(text, 'error')"
   />
 </template>
 
 <script setup lang="ts">
+import useImportTemplates from "../composables/useImportTemplates";
+import { saveBlob } from "../composables/useInventory";
 import QrcodeVue from "qrcode.vue";
 import useAreas from "../composables/useAreas";
 import useUnits from "../composables/useUnits";
@@ -406,7 +414,6 @@ const {
   createArea,
   updateArea,
   deleteArea,
-  uploadAreas,
   getAreaById,
   exportAreas,
 } = useAreas();
@@ -461,7 +468,6 @@ const selectedItem = ref<Record<string, any> | null>(null);
 const message = ref("");
 const messageSnackbar = ref(false);
 const messageColor = ref("");
-const fileInput = ref<HTMLInputElement | null>(null);
 
 const dialogShowMoreActions = ref(false);
 const dialogShowForm = ref(false);
@@ -573,29 +579,26 @@ async function handleDownloadExcel() {
 }
 
 function onImportData() {
-  fileInput.value?.click();
+  showImport.value = true;
 }
 
-async function onFileSelected(event: Event) {
-  const target = event.target as HTMLInputElement;
-  const file = target.files?.[0];
-
-  if (!file) return;
-
-    try {
-      submitting.value = true;
-      const response = await uploadAreas(file, props.site, props.serviceType);
-      showMessage(response?.message, "success");
-
-      await getTaskRefresh();
-    } catch (err: any) {
-      showMessage(err?.data?.message, "error");
-    } finally {
-      submitting.value = false;
-      if (target) target.value = "";
-    }
+// The template is made live from this property's own data (dropdowns, instructions, the property named inside).
+const { downloadTemplate, checkImport, commitImport } = useImportTemplates();
+const importQuery = computed(() => ({ site: String(props.site ?? ""), serviceType: props.serviceType || undefined }));
+const showImport = ref(false);
+const templateDownloading = ref(false);
+async function downloadLiveTemplate() {
+  templateDownloading.value = true;
+  try {
+    saveBlob(await downloadTemplate("areas", importQuery.value), "areas-import-template.xlsx");
+  } catch (error: any) {
+    showMessage(error?.data?.message || "Could not download the template.", "error");
+  } finally {
+    templateDownloading.value = false;
+  }
 }
 
+
 function onCreateItem() {
   dialogMode.value = "add";
   editingItem.value = {};

package/components/BuildingManagement/units.vue

@@ -25,8 +25,21 @@
           </AppButton>
         </template>
       </PageHeader>
-      <input ref="bulkUploadFileInput" type="file" accept=".xlsx,.xls,.csv" class="d-none"
-        @change="handleBulkUploadFileChange" />
+      <!-- Check-then-save import: every row shown with its row number and reason before anything is saved. -->
+      <ImportExcelDialog
+        v-model="showImport"
+        title="Import Blocks, Levels and Units from Excel"
+        noun="rows"
+        name-label="Building / Level / Unit"
+        fill-hint="One row per unit: block number, building name, level and unit. Building Name and Level have dropdowns with this property's own values."
+        duplicate-note="Units already on that level are skipped and left unchanged."
+        template-file-name="units-import-template.xlsx"
+        :download-template="() => downloadTemplate('building-units', { site })"
+        :check="(file: File) => checkImport('building-units', file, { site })"
+        :commit="(file: File) => commitImport('building-units', file, { site })"
+        @done="getBuildingUnit()"
+        @error="(text: string) => showMessage(text, 'error')"
+      />
     </v-col>
 
     <!-- Was `v-card` + a `grey-lighten-4` `v-toolbar` + a bare `v-data-table`. -->
@@ -160,6 +173,8 @@
 </template>
 
 <script setup lang="ts">
+import useImportTemplates from "../../composables/useImportTemplates";
+import { saveBlob } from "../../composables/useInventory";
 import { useDisplay } from 'vuetify/lib/composables/display.mjs';
 
 const props = defineProps({
@@ -339,28 +354,20 @@ async function handleDeleteBuildingUnit() {
   }
 }
 
-function openBulkUploadFilePicker() {
-  if (bulkUploadLoading.value) {
-    return;
-  }
+// The template is made live from this property's data; the import checks every row before saving.
+const { downloadTemplate, checkImport, commitImport } = useImportTemplates();
+const showImport = ref(false);
 
-  bulkUploadFile.value = null;
-  bulkUploadSkippedErrors.value = [];
-  bulkUploadSkippedSummary.value = [];
-  bulkUploadSkippedDialog.value = false;
-  if (bulkUploadFileInput.value) {
-    bulkUploadFileInput.value.value = "";
-    bulkUploadFileInput.value.click();
-  }
+function openBulkUploadFilePicker() {
+  showImport.value = true;
 }
 
-function downloadBulkUploadTemplate() {
-  const link = document.createElement("a");
-  link.href = "/files/Bulk-Upload-Unit-Template.xlsx";
-  link.download = "Bulk-Upload-Unit-Template.xlsx";
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
+async function downloadBulkUploadTemplate() {
+  try {
+    saveBlob(await downloadTemplate("building-units", { site }), "units-import-template.xlsx");
+  } catch (error: any) {
+    showMessage(error?.data?.message || "Could not download the template.", "error");
+  }
 }
 
 function formatSkippedSummaryReason(item: Record<string, any>) {
@@ -413,6 +420,8 @@ function getBulkUploadSkippedSummary(result: Record<string, any> | null | undefi
   return [];
 }
 
+// ponytail: the old direct upload (this handler and the skipped-rows dialog) is no longer reachable —
+// Bulk Upload opens ImportExcelDialog. Delete it once the new import is confirmed in production.
 async function handleBulkUploadFileChange(event: Event) {
   const input = event.target as HTMLInputElement;
   const file = input.files?.[0] ?? null;

package/components/CameraBulkImportDialog.vue

@@ -6,7 +6,7 @@
       <!-- Step 1 — the file. -->
       <template v-if="!results.length">
         <p class="text-body-2 mb-4">
-          Upload the camera survey sheet as a CSV file. Each row is one camera:
+          Upload the camera survey sheet (the Excel template, or a CSV). Each row is one camera:
           its name, the recorder it is on, and its channel number on that
           recorder. The live-view address is worked out for you — do not type
           one.
@@ -14,12 +14,12 @@
 
         <v-file-input
           v-model="file"
-          accept=".csv,text/csv"
+          accept=".xlsx,.csv,text/csv"
           density="comfortable"
           variant="outlined"
           prepend-icon=""
           prepend-inner-icon="mdi-file-delimited-outline"
-          label="Camera survey sheet (.csv)"
+          label="Camera survey sheet (.xlsx or .csv)"
           :disabled="busy"
           @update:model-value="readFile"
         />
@@ -147,6 +147,9 @@
 <script setup lang="ts">
 import useSiteSettings from "../composables/useSiteSettings";
 import { cameraCsvTemplate, parseCameraCsv } from "../utils/camera-csv";
+import { isExampleLine, isWorkbookName, templateRefusal, xlsxMeta, xlsxToGrid } from "../utils/vehicle-bulk-sheet";
+import useImportTemplates from "../composables/useImportTemplates";
+import { saveBlob } from "../composables/useInventory";
 
 /**
  * Adding a site's cameras from the technician's survey sheet.
@@ -177,6 +180,7 @@ const prop = defineProps({
 const emit = defineEmits(["cancel", "imported"]);
 
 const { bulkImportSiteCameras } = useSiteSettings();
+const { downloadTemplate: downloadLiveTemplate } = useImportTemplates();
 
 const file = ref<File | File[] | null>(null);
 const fileError = ref("");
@@ -240,14 +244,22 @@ function close() {
   emit("cancel");
 }
 
-function downloadTemplate() {
-  const blob = new Blob([cameraCsvTemplate()], { type: "text/csv" });
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement("a");
-  link.href = url;
-  link.download = "camera-survey-sheet.csv";
-  link.click();
-  URL.revokeObjectURL(url);
+/** The Excel template (Yes/No dropdowns, an example row, an Instructions sheet); the CSV headings if it cannot be made. */
+async function downloadTemplate() {
+  try {
+    saveBlob(await downloadLiveTemplate("cameras", { site: prop.site }), "camera-survey-sheet.xlsx");
+  } catch {
+    saveBlob(new Blob([cameraCsvTemplate()], { type: "text/csv" }), "camera-survey-sheet.csv");
+  }
+}
+
+/** A filled-in Excel template, as the CSV text the survey-sheet reader takes; the example row left out. */
+function gridToCsv(grid: string[][]) {
+  const quote = (v: string) => (/[",\r\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v);
+  return grid
+    .filter((line) => !isExampleLine(line))
+    .map((line) => line.map((cell) => quote(String(cell ?? ""))).join(","))
+    .join("\n");
 }
 
 /** What the sheet carries that a camera record has no field for. */
@@ -264,7 +276,24 @@ async function readFile(selected: File | File[] | null) {
   const chosen = Array.isArray(selected) ? selected[0] : selected;
   if (!chosen) return;
 
-  const parsed = parseCameraCsv(await chosen.text());
+  let text: string;
+  if (isWorkbookName(chosen.name)) {
+    const workbook = await chosen.arrayBuffer();
+    const refusal = templateRefusal(await xlsxMeta(workbook), { kind: "cameras", site: prop.site });
+    if (refusal) {
+      fileError.value = refusal;
+      return;
+    }
+    try {
+      text = gridToCsv(await xlsxToGrid(workbook));
+    } catch {
+      fileError.value = "This file could not be read. Save it as Excel (.xlsx) from the template and try again.";
+      return;
+    }
+  } else {
+    text = await chosen.text();
+  }
+  const parsed = parseCameraCsv(text);
 
   if (parsed.missingColumns.length) {
     fileError.value = `This file is missing: ${parsed.missingColumns.join(", ")}. Download the blank sheet to see the columns it needs.`;

package/components/ImportExcelDialog.vue

@@ -0,0 +1,136 @@
+<template>
+  <v-dialog v-model="show" max-width="820" persistent scrollable>
+    <v-card class="screen-modal">
+      <v-card-title class="d-flex align-center">
+        {{ title }}
+        <v-spacer />
+        <v-btn icon="mdi-close" variant="text" class="screen-modal__close" aria-label="Close" :disabled="busy" @click="show = false" />
+      </v-card-title>
+      <v-card-text class="screen-modal__body">
+        <ol class="text-body-2 mb-4 pl-4">
+          <li class="mb-1">
+            Download the template. It already has this property's lists as dropdowns and an Instructions sheet.
+            <v-btn variant="text" size="small" class="text-none" prepend-icon="mdi-download" :loading="downloading" @click="download">Download template</v-btn>
+          </li>
+          <li class="mb-1">{{ fillHint }}</li>
+          <li class="mb-1">Upload it and press <strong>Check file</strong>. Nothing is saved yet — you see every row first.</li>
+          <li>If any row needs fixing, fix it in the file and upload it again. {{ duplicateNote }}</li>
+        </ol>
+
+        <v-file-input
+          v-model="file"
+          accept=".xlsx"
+          label="Excel file made from the template (.xlsx)"
+          prepend-icon="mdi-file-excel-outline"
+          density="comfortable"
+          show-size
+          :disabled="busy"
+          @update:model-value="result = null"
+        />
+
+        <template v-if="result">
+          <v-alert :type="result.committed ? 'success' : result.errors ? 'error' : 'info'" variant="tonal" class="mb-3">
+            {{ importSummary(result, noun) }}
+            <div v-if="result.errors && !result.committed" class="mt-2">
+              Fix the rows marked "Needs fixing" in your file, save it, then choose it again above.
+              <br />
+              <v-btn size="small" variant="outlined" class="text-none mt-2" prepend-icon="mdi-file-download-outline" @click="downloadErrors">Download the list of rows to fix</v-btn>
+            </div>
+          </v-alert>
+          <v-table density="compact" height="300" fixed-header>
+            <thead>
+              <tr>
+                <th style="width: 72px">Row</th>
+                <th>{{ nameLabel }}</th>
+                <th>Result</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="r in result.rows" :key="r.row">
+                <td>{{ r.row }}</td>
+                <td>{{ r.name || "—" }}</td>
+                <td :class="r.status === 'error' ? 'text-error' : r.status === 'skipped' ? 'text-medium-emphasis' : 'text-success'">
+                  <strong>{{ IMPORT_STATUS_LABEL[r.status] }}</strong>{{ r.message ? ` — ${r.message}` : "" }}
+                </td>
+              </tr>
+            </tbody>
+          </v-table>
+        </template>
+      </v-card-text>
+      <div class="screen-modal__footer">
+        <v-btn class="screen-btn-ghost" variant="outlined" :disabled="busy" @click="show = false">{{ result?.committed ? "Close" : "Cancel" }}</v-btn>
+        <v-btn v-if="!result" class="screen-btn-primary" variant="flat" :disabled="!selected" :loading="busy" @click="run(false)">Check file</v-btn>
+        <v-btn v-else-if="!result.committed && !result.errors" class="screen-btn-primary" variant="flat" :disabled="!result.ready" :loading="busy" @click="run(true)">
+          Save {{ result.ready }} {{ noun }}
+        </v-btn>
+      </div>
+    </v-card>
+  </v-dialog>
+</template>
+
+<script setup lang="ts">
+import { saveBlob } from "../composables/useInventory";
+import { IMPORT_STATUS_LABEL, importErrorReportCsv, importSummary, type TImportResult } from "../utils/import-result";
+
+/**
+ * One "Import from Excel" dialog for every list: download the live template,
+ * check the file (nothing saved), see every row with its row number and
+ * reason, download the rows to fix, and save only an error-free file.
+ */
+const show = defineModel<boolean>({ default: false });
+const props = defineProps({
+  title: { type: String, required: true },
+  /** Plural noun for the rows, e.g. "items", "units". */
+  noun: { type: String, default: "rows" },
+  nameLabel: { type: String, default: "Name" },
+  fillHint: { type: String, default: "Fill in one row per line, starting under the grey example row. Columns marked * are required." },
+  duplicateNote: { type: String, default: "Rows already in the system are skipped and left unchanged." },
+  templateFileName: { type: String, required: true },
+  downloadTemplate: { type: Function as PropType<() => Promise<Blob>>, required: true },
+  check: { type: Function as PropType<(file: File) => Promise<TImportResult>>, required: true },
+  commit: { type: Function as PropType<(file: File) => Promise<TImportResult>>, required: true },
+});
+const emit = defineEmits<{ done: [result: TImportResult]; error: [message: string] }>();
+
+const file = ref<File | File[] | null>(null);
+const selected = computed<File | null>(() => (Array.isArray(file.value) ? (file.value[0] ?? null) : file.value));
+const result = ref<TImportResult | null>(null);
+const busy = ref(false);
+const downloading = ref(false);
+
+async function download() {
+  downloading.value = true;
+  try {
+    saveBlob(await props.downloadTemplate(), props.templateFileName);
+  } catch (error: any) {
+    emit("error", error?.data?.message || "Could not download the template.");
+  } finally {
+    downloading.value = false;
+  }
+}
+
+function downloadErrors() {
+  if (!result.value) return;
+  saveBlob(new Blob([importErrorReportCsv(result.value)], { type: "text/csv;charset=utf-8" }), props.templateFileName.replace(/\.xlsx$/i, "") + "-rows-to-fix.csv");
+}
+
+async function run(commit: boolean) {
+  if (!selected.value) return;
+  busy.value = true;
+  try {
+    result.value = await (commit ? props.commit : props.check)(selected.value);
+    if (commit) emit("done", result.value);
+  } catch (error: any) {
+    emit("error", error?.data?.message || "Could not read the file.");
+  } finally {
+    busy.value = false;
+  }
+}
+
+watch(show, (open) => {
+  if (open) {
+    file.value = null;
+    result.value = null;
+  }
+});
+</script>

package/components/InventoryImportDialog.vue

@@ -1,117 +1,46 @@
 <template>
-  <v-dialog v-model="show" max-width="760" persistent scrollable>
-    <v-card class="screen-modal">
-      <v-card-title class="d-flex align-center">
-        Import Items from Excel
-        <v-spacer />
-        <v-btn icon="mdi-close" variant="text" class="screen-modal__close" aria-label="Close" @click="show = false" />
-      </v-card-title>
-      <v-card-text class="screen-modal__body">
-        <ol class="text-body-2 mb-4 pl-4">
-          <li class="mb-1">
-            Download the template and fill in one row per item, with the quantity in the store today.
-            <v-btn variant="text" size="small" class="text-none" prepend-icon="mdi-download" :loading="downloading" @click="download">Download template</v-btn>
-          </li>
-          <li class="mb-1">Upload the file. We check it first; nothing is saved yet.</li>
-          <li>Review the result and confirm. Items already in the store are skipped, so uploading twice never doubles stock.</li>
-        </ol>
-
-        <v-file-input
-          v-model="file"
-          accept=".xlsx"
-          label="Excel file (.xlsx)"
-          prepend-icon="mdi-file-excel-outline"
-          density="comfortable"
-          show-size
-          @update:model-value="result = null"
-        />
-
-        <template v-if="result">
-          <v-alert :type="result.errors ? 'warning' : 'success'" variant="tonal" class="mb-3">
-            <template v-if="result.committed">{{ result.ready }} item(s) added.</template>
-            <template v-else>{{ result.ready }} item(s) ready to add.</template>
-            <span v-if="result.skipped"> {{ result.skipped }} skipped.</span>
-            <span v-if="result.errors"> {{ result.errors }} row(s) need fixing (they will not be added).</span>
-          </v-alert>
-          <v-table density="compact" height="280" fixed-header>
-            <thead>
-              <tr>
-                <th>Row</th>
-                <th>Item</th>
-                <th>Result</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr v-for="r in result.rows" :key="r.row">
-                <td>{{ r.row }}</td>
-                <td>{{ r.name || "—" }}</td>
-                <td :class="r.status === 'error' ? 'text-error' : r.status === 'skipped' ? 'text-medium-emphasis' : 'text-success'">
-                  {{ label[r.status] }}{{ r.message ? `: ${r.message}` : "" }}
-                </td>
-              </tr>
-            </tbody>
-          </v-table>
-        </template>
-      </v-card-text>
-      <div class="screen-modal__footer">
-        <v-btn class="screen-btn-ghost" variant="outlined" :disabled="busy" @click="show = false">{{ result?.committed ? "Close" : "Cancel" }}</v-btn>
-        <v-btn v-if="!result" class="screen-btn-primary" variant="flat" :disabled="!selected" :loading="busy" @click="run(false)">Check file</v-btn>
-        <v-btn v-else-if="!result.committed" class="screen-btn-primary" variant="flat" :disabled="!result.ready" :loading="busy" @click="run(true)">
-          Add {{ result.ready }} item(s)
-        </v-btn>
-      </div>
-    </v-card>
-  </v-dialog>
+  <ImportExcelDialog
+    v-model="show"
+    :title="kind === 'receipts' ? 'Import Deliveries from Excel' : 'Import Items from Excel'"
+    :noun="kind === 'receipts' ? 'delivery lines' : 'items'"
+    name-label="Item"
+    :fill-hint="
+      kind === 'receipts'
+        ? 'One row per item delivered: date received, supplier, PO no., the item (pick from the dropdown), quantity and price. Rows with the same date, supplier and PO no. are saved as one delivery.'
+        : 'One row per item. Unit, Packing and Category have dropdowns with this store\'s values. Current Stock and the columns after it are the opening stock (date, supplier, PO no.), recorded like a delivery.'
+    "
+    :duplicate-note="kind === 'receipts' ? 'Every row is a delivery — uploading the same file twice records it twice.' : 'Items already in the store are skipped and never changed, so uploading twice never doubles stock.'"
+    :template-file-name="kind === 'receipts' ? `receive-stock-${slug}.xlsx` : `inventory-items-${slug}.xlsx`"
+    :download-template="downloadTemplate"
+    :check="(file: File) => run(file, false)"
+    :commit="(file: File) => run(file, true)"
+    @done="finished"
+    @error="(message: string) => notify(message, 'error')"
+  />
 </template>
 
 <script setup lang="ts">
-import useInventory, { saveBlob } from "../composables/useInventory";
+import useInventory from "../composables/useInventory";
+import type { TImportResult } from "../utils/import-result";
 
 const show = defineModel<boolean>({ default: false });
-const props = defineProps({ store: { type: Object as PropType<TInventoryStore>, required: true } });
+const props = defineProps({
+  store: { type: Object as PropType<TInventoryStore>, required: true },
+  /** items: the item list with opening stock. receipts: bulk deliveries of existing items. */
+  kind: { type: String as PropType<"items" | "receipts">, default: "items" },
+});
 const emit = defineEmits(["done"]);
 
-const { importItems, importTemplate } = useInventory();
+const { importItems, importTemplate, receiveTemplate, importReceipts } = useInventory();
 const notify = inject<(text: string, color?: string) => void>("inventoryNotify", () => {});
+const slug = computed(() => String(props.store.name ?? "store").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "store");
 
-const file = ref<File | File[] | null>(null);
-const selected = computed<File | null>(() => (Array.isArray(file.value) ? file.value[0] ?? null : file.value));
-const result = ref<Awaited<ReturnType<typeof importItems>> | null>(null);
-const busy = ref(false);
-const downloading = ref(false);
-const label: Record<string, string> = { ready: "Ready", added: "Added", skipped: "Skipped", error: "Needs fixing" };
+const downloadTemplate = () => (props.kind === "receipts" ? receiveTemplate(props.store._id) : importTemplate(props.store._id));
+const run = (file: File, commit: boolean) =>
+  (props.kind === "receipts" ? importReceipts(props.store._id, file, commit) : importItems(props.store._id, file, commit)) as Promise<TImportResult>;
 
-async function download() {
-  downloading.value = true;
-  try {
-    saveBlob(await importTemplate(), "inventory-import-template.xlsx");
-  } catch {
-    notify("Could not download the template.", "error");
-  } finally {
-    downloading.value = false;
-  }
+function finished(result: TImportResult) {
+  notify(props.kind === "receipts" ? `${result.ready} delivery line(s) received.` : `${result.ready} item(s) added.`);
+  emit("done");
 }
-
-async function run(commit: boolean) {
-  if (!selected.value) return;
-  busy.value = true;
-  try {
-    result.value = await importItems(props.store._id, selected.value, commit);
-    if (commit) {
-      notify(`${result.value.ready} item(s) added.`);
-      emit("done");
-    }
-  } catch (error: any) {
-    notify(error?.data?.message || "Could not read the file.", "error");
-  } finally {
-    busy.value = false;
-  }
-}
-
-watch(show, (open) => {
-  if (open) {
-    file.value = null;
-    result.value = null;
-  }
-});
 </script>

package/components/InventoryItemDetail.vue

@@ -114,7 +114,7 @@ function describe(t: TInventoryTransaction) {
       t.reference || "",
     );
   if (t.type === "adjust") parts.push(t.remarks || "");
-  if (t.type === "opening") parts.push(t.remarks || "");
+  if (t.type === "opening") parts.push(t.supplier || "", t.reference ? `PO ${t.reference}` : "", t.receivedBy ? `received by ${t.receivedBy}` : "", t.remarks || "");
   return parts.filter(Boolean).join(" · ");
 }
 

package/components/InventoryItemDialog.vue

@@ -35,11 +35,39 @@
               <InputLabel title="Unit price" class="mb-1" />
               <v-text-field v-model.number="f.unitCost" type="number" min="0" step="0.01" prefix="$" density="comfortable" :rules="[moneyRule]" hint="Price of one unit" persistent-hint />
             </v-col>
-            <v-col v-if="!item" cols="12" sm="4">
-              <InputLabel title="Current stock" class="mb-1" />
-              <v-text-field v-model.number="f.openingQty" type="number" min="0" density="comfortable" :rules="[wholeRule]" hint="Quantity in the store today" persistent-hint />
-            </v-col>
           </v-row>
+          <!-- Stock already on the shelf, recorded like a delivery (one "Opening stock" entry in the item's history). -->
+          <template v-if="!item">
+            <div class="text-subtitle-2 mt-4">Opening stock</div>
+            <div class="text-caption text-medium-emphasis mb-2">
+              Stock you already have. It is recorded like a delivery and shows in the item's history and the Purchases report as "Opening stock".
+              Supplier and PO no. are optional — old stock may have none. Leave the quantity at 0 if you have none yet.
+            </div>
+            <v-row dense>
+              <v-col cols="12" sm="4">
+                <InputLabel title="Quantity" class="mb-1" />
+                <v-text-field v-model.number="f.openingQty" type="number" min="0" density="comfortable" :rules="[wholeRule]" :suffix="f.unit || ''" hint="How many are in the store now" persistent-hint />
+              </v-col>
+              <v-col cols="12" sm="4">
+                <InputLabel title="Date received (as at)" class="mb-1" />
+                <v-text-field v-model="f.openingDate" type="date" :max="today" density="comfortable" :disabled="!f.openingQty" hint="Blank = today" persistent-hint />
+              </v-col>
+              <v-col cols="12" sm="4">
+                <InputLabel title="Received by" class="mb-1" />
+                <v-text-field v-model="f.openingReceivedBy" density="comfortable" maxlength="120" :disabled="!f.openingQty" placeholder="You" hint="Blank = you" persistent-hint />
+              </v-col>
+              <v-col cols="12" sm="6">
+                <InputLabel title="Supplier" class="mb-1" />
+                <v-text-field v-model="f.openingSupplier" density="comfortable" maxlength="200" :disabled="!f.openingQty" hint="Optional" persistent-hint />
+              </v-col>
+              <v-col cols="12" sm="6">
+                <InputLabel title="PO no." class="mb-1" />
+                <v-text-field v-model="f.openingReference" density="comfortable" maxlength="100" :disabled="!f.openingQty" hint="Optional" persistent-hint />
+              </v-col>
+            </v-row>
+            <InputLabel title="Remarks" class="mb-1 mt-2" />
+            <v-text-field v-model="f.openingRemarks" density="comfortable" maxlength="1000" :disabled="!f.openingQty" placeholder="e.g. counted during stock-take" />
+          </template>
           <InputLabel title="Description" class="mb-1 mt-2" />
           <v-textarea v-model="f.description" rows="2" auto-grow density="comfortable" placeholder="Size, model, where it is used" />
           <InputLabel title="Photo" class="mb-1" />
@@ -63,7 +91,7 @@
 </template>
 
 <script setup lang="ts">
-import useInventory from "../composables/useInventory";
+import useInventory, { pickedDate } from "../composables/useInventory";
 import useUtils from "../composables/useUtils";
 
 const show = defineModel<boolean>({ default: false });
@@ -83,7 +111,23 @@ const moneyRule = (v: any) => v === "" || v === null || Number(v) >= 0 || "Enter
 
 const form = ref();
 const saving = ref(false);
-const blank = () => ({ name: "", unit: "pcs", packing: "", code: "", category: "", reorderLevel: 0, unitCost: 0, openingQty: 0, description: "" });
+const blank = () => ({
+  name: "",
+  unit: "pcs",
+  packing: "",
+  code: "",
+  category: "",
+  reorderLevel: 0,
+  unitCost: 0,
+  openingQty: 0,
+  openingDate: "",
+  openingSupplier: "",
+  openingReference: "",
+  openingReceivedBy: "",
+  openingRemarks: "",
+  description: "",
+});
+const today = new Date().toLocaleDateString("en-CA");
 const f = reactive(blank());
 const photo = ref<string[]>([]);
 const inUse = ref(true);
@@ -116,7 +160,18 @@ async function save() {
       await updateItem(props.item._id, { ...body, status: inUse.value ? "active" : "inactive" });
       notify("Item saved.");
     } else {
-      await createItem(props.store._id, { ...body, openingQty: Number(f.openingQty || 0) });
+      const qty = Number(f.openingQty || 0);
+      const opening = qty
+        ? {
+            openingQty: qty,
+            openingDate: pickedDate(f.openingDate),
+            openingSupplier: f.openingSupplier,
+            openingReference: f.openingReference,
+            openingReceivedBy: f.openingReceivedBy,
+            openingRemarks: f.openingRemarks,
+          }
+        : { openingQty: 0 };
+      await createItem(props.store._id, { ...body, ...opening });
       notify("Item added.");
     }
     show.value = false;

package/components/InventoryReportsTab.vue

@@ -184,7 +184,7 @@ const help: Record<string, string> = {
   movement: "For each item: stock at the start of the month, what came in, what was issued and returned, count differences, and stock at the end.",
   usage: "Every recorded usage: where it was used, for which tenant, by whom, and the cost. Use this for tenant billing. Tick records and mark them checked once verified.",
   technicians: "For each person: stock they held at the start, took, used, returned, and hold at the end of the month.",
-  purchases: "Every delivery received, with totals by month and by supplier, to see how purchasing changes over time.",
+  purchases: "Every delivery received, and opening stock entered with new items (Type: Opening stock), with totals by month and by supplier.",
 };
 
 const headers: Record<string, any[]> = {
@@ -231,6 +231,7 @@ const headers: Record<string, any[]> = {
   ],
   purchases: [
     { title: "Date", key: "date" },
+    { title: "Type", key: "kind" },
     { title: "Supplier", key: "supplier" },
     { title: "PO No.", key: "reference" },
     { title: "Item", key: "itemName" },

package/components/InventoryStockTab.vue

@@ -10,9 +10,15 @@
     </v-row>
 
     <div class="d-flex flex-wrap ga-2 align-center mb-3">
-      <v-btn v-if="store.access.canManage && !storeEmpty" class="text-none screen-btn-primary" variant="flat" prepend-icon="mdi-truck-delivery-outline" @click="open('receive')">
-        Receive Stock
-      </v-btn>
+      <v-menu v-if="store.access.canManage && !storeEmpty">
+        <template #activator="{ props: menu }">
+          <v-btn v-bind="menu" class="text-none screen-btn-primary" variant="flat" prepend-icon="mdi-truck-delivery-outline" append-icon="mdi-chevron-down">Receive Stock</v-btn>
+        </template>
+        <v-list density="compact">
+          <v-list-item prepend-icon="mdi-truck-delivery-outline" title="Record a delivery" @click="open('receive')" />
+          <v-list-item prepend-icon="mdi-file-excel-outline" title="Import deliveries from Excel" @click="showReceiveImport = true" />
+        </v-list>
+      </v-menu>
       <v-btn v-if="store.access.canApprove && !storeEmpty" class="text-none screen-btn-primary" variant="flat" prepend-icon="mdi-hand-extended-outline" @click="open('issue')">
         Issue Stock
       </v-btn>
@@ -86,6 +92,7 @@
     <InventoryLinesDialog v-model="lines.show" :mode="lines.mode" :store="store" :site-id="siteId" :sites="sites" @done="done" />
     <InventoryItemDialog v-model="itemDialog.show" :store="store" :item="itemDialog.item" @done="done" />
     <InventoryImportDialog v-model="showImport" :store="store" @done="done" />
+    <InventoryImportDialog v-model="showReceiveImport" :store="store" kind="receipts" @done="done" />
     <InventoryLegacyImportDialog v-model="showLegacy" :store="store" @done="done" />
     <InventoryItemDetail v-model="detail.show" :store="store" :item="detail.item" @edit="editItem" @done="done" />
   </div>
@@ -167,6 +174,7 @@ function openItem(item: TInventoryItem) {
 }
 
 const showImport = ref(false);
+const showReceiveImport = ref(false);
 const showLegacy = ref(false);
 
 function done() {

package/components/InvitationForm.vue

@@ -59,7 +59,7 @@
                       <v-list-item-title class="text-wrap">
                         {{ noRolesText }}
                       </v-list-item-title>
-                      <NuxtLink v-if="rolesPageLink" :to="rolesPageLink">
+                      <NuxtLink v-if="rolesPageLink && !rolesError" :to="rolesPageLink">
                         Open Roles &amp; Permissions
                       </NuxtLink>
                     </v-list-item>
@@ -474,7 +474,7 @@ const { getInvitableRoles } = useRole();
  * templates are gone from any invitation that names an organisation - the
  * server refuses them there (`core roleInvitable`).
  */
-const { data: RolesData, refresh: refreshRoles } = await useLazyAsyncData(
+const { data: RolesData, refresh: refreshRoles, error: rolesError } = await useLazyAsyncData(
   "get-roles-by-type-" + props.org + "-" + props.app + "-" + fixedSite.value,
   () =>
     getInvitableRoles({
@@ -502,7 +502,9 @@ watchEffect(() => {
 const roleOptions = computed(() => inviteRoleOptions(roles.value));
 
 const noRolesText = computed(() =>
-  fixedSite.value
+  rolesError?.value
+    ? "The roles could not be loaded. You may not have access to this organisation's roles; refresh, or sign in again."
+    : fixedSite.value
     ? "No roles have been created for this site yet. Create one in Roles & Permissions first."
     : "No roles have been created yet. Create one in Roles & Permissions first."
 );

package/components/UnitMain.vue

@@ -37,9 +37,8 @@
                       v-bind="t"
                       class="ma-1 screen-icon-btn"
                       variant="flat"
-                      href="/files/unit-sample-data.xlsx"
-                      target="_blank"
-                      download
+                      :loading="templateDownloading"
+                      @click="downloadLiveTemplate"
                     >
                       <v-icon>mdi-download</v-icon>
                     </v-btn>
@@ -183,16 +182,25 @@
     :color="messageColor"
   />
 
-  <input
-    ref="fileInput"
-    type="file"
-    accept=".csv,.xlsx,.xls"
-    style="display: none"
-    @change="onFileSelected"
+  <ImportExcelDialog
+    v-model="showImport"
+    title="Import Units from Excel"
+    noun="units"
+    name-label="Unit"
+    fill-hint="One unit per row, e.g. Toilet Bowl, Sofa."
+    duplicate-note="Units already on the list are skipped and left unchanged."
+    template-file-name="units-import-template.xlsx"
+    :download-template="() => downloadTemplate('units', importQuery)"
+    :check="(file: File) => checkImport('units', file, importQuery)"
+    :commit="(file: File) => commitImport('units', file, importQuery)"
+    @done="getUnitsRefresh()"
+    @error="(text: string) => showMessage(text, 'error')"
   />
 </template>
 
 <script setup lang="ts">
+import useImportTemplates from "../composables/useImportTemplates";
+import { saveBlob } from "../composables/useInventory";
 import useUnits from "../composables/useUnits";
 import useUtils from "../composables/useUtils";
 
@@ -220,7 +228,6 @@ const {
   createUnit,
   updateUnit,
   deleteUnit,
-  uploadUnits,
   downloadUnits,
 } = useUnits();
 
@@ -271,7 +278,6 @@ const selectedUnit = ref<Record<string, any> | null>(null);
 const message = ref("");
 const messageSnackbar = ref(false);
 const messageColor = ref("");
-const fileInput = ref<HTMLInputElement | null>(null);
 
 const dialogShowMoreActions = ref(false);
 const dialogShowForm = ref(false);
@@ -341,30 +347,26 @@ async function handleDownloadExcel() {
 }
 
 function onImportData() {
-  fileInput.value?.click();
+  showImport.value = true;
 }
 
-async function onFileSelected(event: Event) {
-  const target = event.target as HTMLInputElement;
-  const file = target.files?.[0];
-
-  if (!file) return;
-
+// The template is made live from this property's own data (dropdowns, instructions, the property named inside).
+const { downloadTemplate, checkImport, commitImport } = useImportTemplates();
+const importQuery = computed(() => ({ site: String(props.site ?? ""), serviceType: props.serviceType || undefined }));
+const showImport = ref(false);
+const templateDownloading = ref(false);
+async function downloadLiveTemplate() {
+  templateDownloading.value = true;
   try {
-    submitting.value = true;
-
-    const response = await uploadUnits(file, props.site, props.serviceType);
-    showMessage(response?.message, "success");
-
-    await getUnitsRefresh();
-  } catch (err: any) {
-    showMessage(err?.data?.message, "error");
+    saveBlob(await downloadTemplate("units", importQuery.value), "units-import-template.xlsx");
+  } catch (error: any) {
+    showMessage(error?.data?.message || "Could not download the template.", "error");
   } finally {
-    submitting.value = false;
-    target.value = "";
+    templateDownloading.value = false;
   }
 }
 
+
 function onCreateUnit() {
   dialogMode.value = "add";
   editingUnit.value = {};

package/components/VehicleBulkAddForm.vue

@@ -284,6 +284,8 @@
 
 <script setup lang="ts">
 import useVehicle from "../composables/useVehicle";
+import useImportTemplates from "../composables/useImportTemplates";
+import { saveBlob } from "../composables/useInventory";
 import useBuilding from "../composables/useBuilding";
 import { errorConverter } from "../utils/data";
 // @ts-ignore - the country list the one-vehicle form's phone field uses.
@@ -320,6 +322,8 @@ import {
   mapUploadedGrid,
   vehicleBulkTemplateCsv,
   xlsxToGrid,
+  xlsxMeta,
+  templateRefusal,
 } from "../utils/vehicle-bulk-sheet";
 
 /**
@@ -348,6 +352,7 @@ const prop = defineProps({
 const emit = defineEmits(["back", "close", "added"]);
 
 const { addVehiclesBulk } = useVehicle();
+const { downloadTemplate: downloadLiveTemplate } = useImportTemplates();
 const { getBlocksSelection, getLevelsSelection, getUnitSelection } = useBuilding();
 
 type Option = { title: string; value: string };
@@ -1043,18 +1048,19 @@ function statusColour(status: BulkRowStatus) {
 
 /* --------------------------- template and file ---------------------------- */
 
-/** The blank sheet, for filling in somewhere else. Opens in Excel or Sheets. */
-function downloadTemplate() {
-  // A BOM, so Excel opens it as UTF-8 and a name with an accent survives.
-  const blob = new Blob(["", vehicleBulkTemplateCsv()], {
-    type: "text/csv;charset=utf-8;",
-  });
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement("a");
-  link.href = url;
-  link.download = "vehicle-whitelist-template.csv";
-  link.click();
-  URL.revokeObjectURL(url);
+/**
+ * The sheet to fill in somewhere else: an Excel file made live from this
+ * site's own blocks, levels and units, with them as dropdowns, an example row
+ * and an Instructions sheet. If the server cannot make it, the plain CSV
+ * headings are offered instead so the person is never stuck.
+ */
+async function downloadTemplate() {
+  try {
+    saveBlob(await downloadLiveTemplate("vehicles", { site: prop.site }), "vehicle-whitelist-template.xlsx");
+  } catch {
+    // A BOM, so Excel opens it as UTF-8 and a name with an accent survives.
+    saveBlob(new Blob(["", vehicleBulkTemplateCsv()], { type: "text/csv;charset=utf-8;" }), "vehicle-whitelist-template.csv");
+  }
 }
 
 /** The first row that is free to be written into. */
@@ -1083,9 +1089,15 @@ async function onFileChosen(event: Event) {
   uploading.value = true;
 
   try {
-    const grid = isWorkbookName(chosen.name)
-      ? await xlsxToGrid(await chosen.arrayBuffer())
-      : parsePastedGrid(await chosen.text());
+    const workbook = isWorkbookName(chosen.name) ? await chosen.arrayBuffer() : null;
+    if (workbook) {
+      const refusal = templateRefusal(await xlsxMeta(workbook), { kind: "vehicles", site: prop.site });
+      if (refusal) {
+        formError.value = refusal;
+        return;
+      }
+    }
+    const grid = workbook ? await xlsxToGrid(workbook) : parsePastedGrid(await chosen.text());
     const sheet = mapUploadedGrid(grid);
 
     if (!sheet.matchesTemplate) {
@@ -1117,7 +1129,9 @@ async function onFileChosen(event: Event) {
     moveTo(start, 0);
 
     resultNote.value =
-      `${sheet.rows.length} row(s) read from ${chosen.name}. Check anything ` +
+      `${sheet.rows.length} row(s) read from ${chosen.name}` +
+      (sheet.exampleRowIgnored ? " (the example row was left out)" : "") +
+      `. Check anything ` +
       `marked red - a block, level or unit that is not one of this site's own ` +
       `is left blank - then press Submit.`;
   } catch {

package/composables/useImportTemplates.ts

@@ -0,0 +1,24 @@
+import type { TImportResult } from "../utils/import-result";
+
+/**
+ * Excel templates made live from the property's own data (`/api/import-templates`),
+ * and the check-then-save import behind building units, areas and units.
+ * Vehicles and cameras only download their template here; their files are read
+ * on screen.
+ */
+export type TTemplateKind = "building-units" | "areas" | "units" | "vehicles" | "cameras";
+
+export default function useImportTemplates() {
+  const api = <T = any>(kind: TTemplateKind, path: string, options: Record<string, any> = {}) =>
+    useNuxtApp().$api<T>(`/api/import-templates/${kind}/${path}`, options);
+  const send = (kind: TTemplateKind, path: "check" | "commit", file: File, query: Record<string, string | undefined>) => {
+    const body = new FormData();
+    body.append("file", file);
+    return api<TImportResult>(kind, path, { method: "POST", body, query });
+  };
+  return {
+    downloadTemplate: (kind: TTemplateKind, query: { site: string; serviceType?: string }) => api<Blob>(kind, "template", { query, responseType: "blob" }),
+    checkImport: (kind: TTemplateKind, file: File, query: { site: string; serviceType?: string }) => send(kind, "check", file, query),
+    commitImport: (kind: TTemplateKind, file: File, query: { site: string; serviceType?: string }) => send(kind, "commit", file, query),
+  };
+}

package/composables/useInventory.ts

@@ -1,3 +1,5 @@
+import type { TImportResult } from "../utils/import-result";
+
 /**
  * Inventory API (`/api/inventory`). What a person may do in a store comes back
  * on the store itself (`store.access`), decided by the server — screens show
@@ -67,14 +69,19 @@ export default function useInventory() {
         `/stores/${store}/legacy-equipment/import`,
         { method: "POST", body: { serviceType, commit } },
       ),
-    importTemplate: () => api<Blob>("/import-template", { responseType: "blob" }),
+    /** The store's own item template: live dropdowns (units, packing, categories) and the store named inside. */
+    importTemplate: (store: string) => api<Blob>(`/stores/${store}/import-template`, { responseType: "blob" }),
     importItems: (store: string, file: File, commit: boolean) => {
       const body = new FormData();
       body.append("file", file);
-      return api<{ committed: boolean; ready: number; skipped: number; errors: number; rows: { row: number; name: string; status: string; message: string }[] }>(
-        `/stores/${store}/import`,
-        { method: "POST", body, query: { commit } },
-      );
+      return api<TImportResult>(`/stores/${store}/import`, { method: "POST", body, query: { commit } });
+    },
+    /** Bulk deliveries: the store's items as a dropdown. */
+    receiveTemplate: (store: string) => api<Blob>(`/stores/${store}/receive-template`, { responseType: "blob" }),
+    importReceipts: (store: string, file: File, commit: boolean) => {
+      const body = new FormData();
+      body.append("file", file);
+      return api<TImportResult>(`/stores/${store}/receive-import`, { method: "POST", body, query: { commit } });
     },
   };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.35.1-staging.425",
+  "version": "4.35.1-staging.427",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/types/inventory.d.ts

@@ -90,6 +90,8 @@ declare type TInventoryTransaction = {
   photos?: { before: string[]; after: string[]; other: string[] };
   remarks?: string;
   reportedBy?: string;
+  /** Opening stock: who received it, when not the person who entered it. */
+  receivedBy?: string;
   date: string;
   createdByName: string;
 };

package/utils/camera-csv.ts

@@ -103,6 +103,8 @@ function splitLine(line: string): string[] {
 /** A header cell, normalised to the sheet's snake_case spelling. */
 function normaliseColumn(value: string): string {
   return value
+    // "Camera Name *" in the Excel template is camera_name: the * only marks it required.
+    .replace(/\*/g, "")
     .trim()
     .toLowerCase()
     .replace(/^/, "")

package/utils/import-result.ts

@@ -0,0 +1,62 @@
+/**
+ * What an Excel import's check (or save) comes back with, and the plain words
+ * and error report built from it. Shared by every "Import from Excel" dialog.
+ */
+
+export type TImportIssue = { row: number; column: string; message: string };
+
+export type TImportRow = { row: number; name: string; status: "ready" | "added" | "skipped" | "error"; message: string };
+
+export type TImportResult = {
+  committed: boolean;
+  ready: number;
+  skipped: number;
+  errors: number;
+  exampleRowIgnored?: boolean;
+  deliveries?: number;
+  issues?: TImportIssue[];
+  rows: TImportRow[];
+};
+
+/** One sentence for the top of the preview. `noun` is plural, e.g. "items". */
+export function importSummary(result: TImportResult, noun = "rows"): string {
+  const parts: string[] = [];
+  if (result.committed) parts.push(`${result.ready} ${noun} saved.`);
+  else if (result.errors) parts.push(`${result.errors} row(s) need fixing — nothing will be saved until they are fixed.`);
+  else parts.push(`${result.ready} ${noun} ready to save.`);
+  if (!result.committed && result.errors && result.ready) parts.push(`${result.ready} other row(s) are fine.`);
+  if (result.skipped) parts.push(`${result.skipped} already in the system or repeated — they will be left unchanged.`);
+  if (result.exampleRowIgnored) parts.push("The example row was ignored.");
+  return parts.join(" ");
+}
+
+export const IMPORT_STATUS_LABEL: Record<TImportRow["status"], string> = {
+  ready: "Ready",
+  added: "Saved",
+  skipped: "Skipped",
+  error: "Needs fixing",
+};
+
+const csvCell = (v: unknown) => {
+  const s = String(v ?? "");
+  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+};
+
+/**
+ * The error report: one line per problem — the row number in the Excel file,
+ * the column, and what to fix. Rows with an error but no column-level issue
+ * are listed with their message. Opens in Excel.
+ */
+export function importErrorReportCsv(result: TImportResult): string {
+  const lines: string[][] = [["Row in your file", "Column", "What to fix", "Item"]];
+  const nameOf = new Map(result.rows.map((r) => [r.row, r.name]));
+  const covered = new Set<number>();
+  for (const i of result.issues ?? []) {
+    lines.push([String(i.row), i.column, i.message, nameOf.get(i.row) ?? ""]);
+    covered.add(i.row);
+  }
+  for (const r of result.rows) {
+    if (r.status === "error" && !covered.has(r.row)) lines.push([String(r.row), "", r.message, r.name]);
+  }
+  return "" + lines.map((l) => l.map(csvCell).join(",")).join("\r\n") + "\r\n";
+}

package/utils/vehicle-bulk-sheet.ts

@@ -97,6 +97,8 @@ export type UploadedSheet = {
   matchesTemplate: boolean;
   /** The heading line as the file spells it - for telling a person what it has. */
   header: string[];
+  /** A template example row was left in and was not read. */
+  exampleRowIgnored?: boolean;
 };
 
 /**
@@ -138,14 +140,16 @@ export function mapUploadedGrid(grid: string[][]): UploadedSheet {
   // Every line under the header is somebody's car. Nothing is dropped for
   // looking like something else - two people in one household can have the
   // same details but for the plate, and a repeated row is the person's to fix.
-  const rows = lines
-    .slice(1)
+  const body = lines.slice(1);
+  // The example row of a template the server made is marked beside it; it is nobody's car.
+  const rows = body
+    .filter((line) => !isExampleLine(line))
     .map((line) =>
       BULK_SHEET_HEADINGS.map((_, column) => String(line[column] ?? "").trim()),
     )
     .filter((line) => !isEmptyLine(line));
 
-  return { rows, matchesTemplate: true, header };
+  return { rows, matchesTemplate: true, header, exampleRowIgnored: body.some(isExampleLine) };
 }
 
 /**
@@ -385,3 +389,55 @@ export async function xlsxToGrid(data: ArrayBuffer | Uint8Array): Promise<string
 export function isWorkbookName(name: string): boolean {
   return /\.(xlsx|xlsm)$/i.test(String(name ?? ""));
 }
+
+/* ------------------------------ live templates ----------------------------- */
+
+/** Beside the example row of every template the server makes. */
+export const TEMPLATE_EXAMPLE_MARK = "Example – delete this row";
+
+/** Does this line carry the template's example-row mark? */
+export function isExampleLine(cells: string[]): boolean {
+  return (cells ?? []).some((cell) => String(cell ?? "").includes(TEMPLATE_EXAMPLE_MARK));
+}
+
+/**
+ * The hidden "_meta" sheet of a template the server made: which kind of
+ * template it is and the property it was made for (`kind`, `site`,
+ * `siteName`). Empty for any other workbook.
+ */
+export async function xlsxMeta(data: ArrayBuffer | Uint8Array): Promise<Record<string, string>> {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  const entries = readZipEntries(bytes);
+  const book = entries.get("xl/workbook.xml");
+  const rels = entries.get("xl/_rels/workbook.xml.rels");
+  if (!book || !rels) return {};
+  const sheet = (await readPart(bytes, book)).match(/<sheet\b[^>]*\bname="_meta"[^>]*>/)?.[0];
+  const rid = sheet?.match(/\br:id="([^"]+)"/)?.[1];
+  if (!rid) return {};
+  const relation = ((await readPart(bytes, rels)).match(/<Relationship\b[^>]*>/g) ?? []).find((tag) => tag.includes(` Id="${rid}"`));
+  const target = relation?.match(/\bTarget="([^"]+)"/)?.[1];
+  const part = target ? entries.get(target.startsWith("/") ? target.slice(1) : `xl/${target}`) : undefined;
+  if (!part) return {};
+  const sharedEntry = entries.get("xl/sharedStrings.xml");
+  const strings = sharedEntry ? sharedStringsOf(await readPart(bytes, sharedEntry)) : [];
+  const meta: Record<string, string> = {};
+  for (const line of sheetToGrid(await readPart(bytes, part), strings).slice(1)) {
+    if (line[0]) meta[String(line[0])] = String(line[1] ?? "");
+  }
+  return meta;
+}
+
+/**
+ * Why a template may not be used here, or "" when it may: a template made for
+ * another property, or a different kind of template. A workbook without the
+ * hidden sheet (an older template, a person's own file) is allowed.
+ */
+export function templateRefusal(meta: Record<string, string>, expected: { kind: string; site: string }): string {
+  if (meta.kind && meta.kind !== expected.kind) {
+    return "This is a different kind of template. Download the template on this screen and copy your rows into it.";
+  }
+  if (meta.site && expected.site && meta.site !== expected.site) {
+    return `This file was made for ${meta.siteName ? `"${meta.siteName}"` : "another property"}. Download the template on this screen and copy your rows into it.`;
+  }
+  return "";
+}