# _System_File Field Audit

This note documents which `_System_File` fields are part of the new runtime
model, which are compatibility-only, and which are currently redundant but must
remain for backward compatibility.

## Runtime-Critical Fields

- `Id`
- `ParentId`
- `ParentObjectApiName`
- `Name`
- `OriginalFileName`
- `Extension`
- `MimeType`
- `SizeBytes`
- `StorageProvider`
- `StorageBucket`
- `StorageKey`
- `Status`
- `SourceType`

These drive native upload/download/delete behavior in
[backend/internal/interfaces/rest/file_upload_handler.go](/Users/wq/ClaudeCodeProjects/MetaDrivenPlatform4AI/backend/internal/interfaces/rest/file_upload_handler.go:245)
and archived business-slot uploads in
[backend/internal/features/files/archived_order_service.go](/Users/wq/ClaudeCodeProjects/MetaDrivenPlatform4AI/backend/internal/features/files/archived_order_service.go:120).

## Business-Action Fields

- `AttachmentKind`
- `SlotKey`

These are only required for archived order/contract slot replacement logic in
[backend/internal/features/files/archived_order_service.go](/Users/wq/ClaudeCodeProjects/MetaDrivenPlatform4AI/backend/internal/features/files/archived_order_service.go:300).

## Compatibility Fields

- `StoragePath`
- `SourceContentDocumentId`
- `SourceContentVersionId`

`StoragePath` is still required because legacy compat rows may point to
`s3://bucket/key` or old `/sobjects/ContentVersion/<id>/VersionData` references.
The `SourceContent*` fields keep the latest-only ContentDocument projection
traceable and idempotent in
[backend/internal/bootstrap/content_compat_backfill.go](/Users/wq/ClaudeCodeProjects/MetaDrivenPlatform4AI/backend/internal/bootstrap/content_compat_backfill.go:76).

## Redundant But Not Safe To Remove Yet

- `StoragePath` for native rows
  Native rows currently mirror `StorageKey` into `StoragePath`. This is
  redundant for the new model, but it still protects old readers and mixed data.
- `Name` when equal to `OriginalFileName`
  Often identical today, but still useful if product naming diverges from the
  original upload filename later.
- `StorageBucket` on filesystem rows
  Operationally unused for local filesystem reads, but still part of the shared
  `_System_File` contract and needed on S3-backed rows.

## Known Data Hygiene Rules

- New native writes must persist `Status = Active` without embedded quotes.
- New native writes should persist a canonical `ParentObjectApiName`
  (`Quote`, `Order`, `Contract`, etc.) rather than preserving caller casing.
- New native writes should treat `StorageKey` as the primary locator and mirror
  it into `StoragePath` only for compatibility.