feat(export): include visual evidence assets

Author: Данил

docs/config-registry.md

@@ -8,7 +8,7 @@ Current registry index:
 
 ```text
 https://raw.githubusercontent.com/nigdanil/AuditM-Field/main/public/config-registry/index.json
-````
+```
 
 Repository path:
 

docs/export-format.md

@@ -16,10 +16,41 @@ photos/
   <photoId>_<fileName>
 annotations/
   annotations.json
+  <photoId>.annotations.json
+rendered/
+  <photoId>.overlay.png
+  visual-evidence.warnings.json
+crops/
+  <photoId>/
+    <annotationId>.png
 ```
 
 ---
 
+## Source of truth
+
+Original photos are exported without drawn boxes.
+
+This is intentional.
+
+```text
+Original photo
++
+annotations.json
++
+overlay previews
++
+annotation crops
+```
+
+Original photos remain clean for OCR, CV, LLM and repeated processing.
+
+Overlay images are only visual evidence for humans and reports.
+
+Crops are useful for AI pipelines because they isolate each annotated area.
+
+---
+
 ## manifest.json
 
 The manifest describes the exported package.
@@ -30,7 +61,7 @@ Example:
 {
   "app": {
     "name": "AuditM-Field",
-    "packageFormatVersion": "1.0.0",
+    "packageFormatVersion": "1.1.0",
     "exportedAt": "2026-05-10T10:00:00.000Z"
   },
   "inspection": {
@@ -48,15 +79,20 @@ Example:
   },
   "counts": {
     "photos": 1,
-    "annotations": 2
+    "annotations": 2,
+    "renderedOverlays": 1,
+    "annotationCrops": 2
   },
   "files": {
     "manifest": "manifest.json",
     "config": "config.json",
     "inspection": "inspections/inspection_<id>.json",
     "photosMetadata": "photos/photos.metadata.json",
     "annotations": "annotations/annotations.json",
-    "photos": []
+    "photos": [],
+    "annotationsByPhoto": [],
+    "renderedOverlays": [],
+    "annotationCrops": []
   }
 }
 ```
@@ -110,6 +146,8 @@ createdAt
 
 Photo binary files are stored separately in the `photos/` folder.
 
+Original photo files are not modified and do not contain rendered annotation boxes.
+
 ---
 
 ## annotations/annotations.json
@@ -140,6 +178,80 @@ imported
 
 ---
 
+## annotations/<photoId>.annotations.json
+
+Contains annotations grouped by photo.
+
+This is useful for backend/n8n/AI workflows where a single photo and its annotations are processed together.
+
+---
+
+## rendered/<photoId>.overlay.png
+
+Human-readable visual preview.
+
+The overlay image contains:
+
+```text
+original photo
++ annotation boxes
++ annotation label
++ annotation source
+```
+
+Use this for:
+
+```text
+manual review
+reports
+emails
+n8n previews
+portfolio screenshots
+visual evidence
+```
+
+Do not use this as the only input for OCR/CV/LLM processing.
+
+---
+
+## crops/<photoId>/<annotationId>.png
+
+Cropped image regions generated from annotation geometry.
+
+Use this for:
+
+```text
+AI verification
+OCR on selected area
+classification
+brand/condition checks
+focused LLM vision prompts
+```
+
+---
+
+## rendered/visual-evidence.warnings.json
+
+Optional file.
+
+Created only when some annotations could not be rendered as overlay/crop because geometry could not be resolved.
+
+Example:
+
+```json
+{
+  "warnings": [
+    {
+      "id": "annotation-id",
+      "photoId": "photo-id",
+      "reason": "Annotation geometry could not be resolved."
+    }
+  ]
+}
+```
+
+---
+
 ## Import behavior
 
 ZIP import is idempotent:
@@ -152,14 +264,25 @@ annotations -> bulkPut
 
 Re-importing the same ZIP updates existing records by id.
 
+Visual evidence files are ignored during import because they can be generated again from original photos and annotations.
+
 ---
 
 ## Compatibility
 
 Current package format version:
 
 ```text
-1.0.0
+1.1.0
+```
+
+Version `1.0.0` packages remain compatible because import only requires:
+
+```text
+manifest.json
+config.json
+inspections/
+photos/
+annotations/
 ```
 
-Future versions should preserve backward compatibility where possible.

docs/github-pages.md

@@ -6,7 +6,7 @@ Repository:
 
 ```text
 https://github.com/nigdanil/AuditM-Field
-````
+```
 
 Public URL:
 

src/services/export/exportPackage.ts

@@ -6,12 +6,14 @@ import type { Inspection } from '../../entities/inspection/types';
 import type { PhotoRecord } from '../../entities/photo/types';
 import { db } from '../db/db';
 
+import { buildVisualEvidenceAssets } from './visualEvidence';
+
 type ExportPhotoMetadata = Omit<PhotoRecord, 'blob'>;
 
 export type ExportManifest = {
   app: {
     name: 'AuditM-Field';
-    packageFormatVersion: '1.0.0';
+    packageFormatVersion: '1.1.0';
     exportedAt: string;
   };
   inspection: {
@@ -32,6 +34,8 @@ export type ExportManifest = {
   counts: {
     photos: number;
     annotations: number;
+    renderedOverlays: number;
+    annotationCrops: number;
   };
   files: {
     manifest: string;
@@ -41,6 +45,8 @@ export type ExportManifest = {
     annotations: string;
     photos: string[];
     annotationsByPhoto: string[];
+    renderedOverlays: string[];
+    annotationCrops: string[];
   };
 };
 
@@ -150,12 +156,17 @@ function buildManifest(input: {
   annotations: ImageAnnotationRecord[];
   photoFilePaths: string[];
   annotationFilePaths: string[];
+  overlayFilePaths?: string[];
+  cropFilePaths?: string[];
   exportedAt: Date;
 }): ExportManifest {
+  const overlayFilePaths = input.overlayFilePaths ?? [];
+  const cropFilePaths = input.cropFilePaths ?? [];
+
   return {
     app: {
       name: 'AuditM-Field',
-      packageFormatVersion: '1.0.0',
+      packageFormatVersion: '1.1.0',
       exportedAt: input.exportedAt.toISOString(),
     },
     inspection: {
@@ -176,6 +187,8 @@ function buildManifest(input: {
     counts: {
       photos: input.photos.length,
       annotations: input.annotations.length,
+      renderedOverlays: overlayFilePaths.length,
+      annotationCrops: cropFilePaths.length,
     },
     files: {
       manifest: 'manifest.json',
@@ -185,6 +198,8 @@ function buildManifest(input: {
       annotations: 'annotations/annotations.json',
       photos: input.photoFilePaths,
       annotationsByPhoto: input.annotationFilePaths,
+      renderedOverlays: overlayFilePaths,
+      annotationCrops: cropFilePaths,
     },
   };
 }
@@ -276,6 +291,26 @@ export async function buildInspectionExportPackage(
     throw new Error('Add at least one photo before export.');
   }
 
+  const visualEvidence = await buildVisualEvidenceAssets({
+    photos: data.photos,
+    annotations: data.annotations,
+    config: activeConfig,
+  });
+
+  const manifest = buildManifest({
+    inspection: data.inspection,
+    config: activeConfig,
+    configSource: input.configSource,
+    configLoadedAt: input.configLoadedAt,
+    photos: data.photos,
+    annotations: data.annotations,
+    photoFilePaths: data.photoFilePaths,
+    annotationFilePaths: data.annotationFilePaths,
+    overlayFilePaths: visualEvidence.overlayFilePaths,
+    cropFilePaths: visualEvidence.cropFilePaths,
+    exportedAt: new Date(data.manifest.app.exportedAt),
+  });
+
   const zip = new JSZip();
   const inspectionJson = {
     ...data.inspection,
@@ -287,8 +322,10 @@ export async function buildInspectionExportPackage(
   const inspectionsFolder = zip.folder('inspections');
   const photosFolder = zip.folder('photos');
   const annotationsFolder = zip.folder('annotations');
+  const renderedFolder = zip.folder('rendered');
+  const cropsFolder = zip.folder('crops');
 
-  if (!inspectionsFolder || !photosFolder || !annotationsFolder) {
+  if (!inspectionsFolder || !photosFolder || !annotationsFolder || !renderedFolder || !cropsFolder) {
     throw new Error('Failed to create ZIP folder structure.');
   }
 
@@ -311,7 +348,20 @@ export async function buildInspectionExportPackage(
     annotationsFolder.file(`${photoId}.annotations.json`, toJsonBlobContent(photoAnnotations));
   });
 
-  zip.file('manifest.json', toJsonBlobContent(data.manifest));
+  visualEvidence.assets.forEach((asset) => {
+    zip.file(asset.path, asset.blob);
+  });
+
+  if (visualEvidence.skippedAnnotations.length > 0) {
+    zip.file(
+      'rendered/visual-evidence.warnings.json',
+      toJsonBlobContent({
+        warnings: visualEvidence.skippedAnnotations,
+      }),
+    );
+  }
+
+  zip.file('manifest.json', toJsonBlobContent(manifest));
 
   const blob = await zip.generateAsync({
     type: 'blob',
@@ -323,7 +373,7 @@ export async function buildInspectionExportPackage(
 
   return {
     blob,
-    manifest: data.manifest,
+    manifest,
     fileName: data.fileName,
   };
 }