40227-vm/backend/docs/file.md

File Backend

Purpose

The file slice handles binary file upload and download. Uploaded files are stored either on local disk (development) or in Google Cloud Storage (production), selected at request time. The file table records file metadata (name, URLs, owning relation) and is written indirectly by the file DAL when entity relations are persisted, not by the upload endpoint itself.

Upload client contract

When a typed frontend upload client is built, it follows the same multipart contract the reference frontend used (preserved here so it isn't lost):

1. Generate a unique filename: ${uuid}.${ext} (extension from the picked file).
2. POST /api/file/upload/:table/:field as multipart/form-data with fields file (the binary) and filename (the generated name).
3. The stored privateUrl is ${table}/${field}/${filename}; the playable/ download URL is ${API_BASE_URL}/file/download?privateUrl=<privateUrl> (works for both the local-disk dev backend and the GCloud prod backend).

Downloads are JWT-only by customer decision. The standalone /file/upload/:table/:field path can therefore serve uploaded logos/avatars/files even when it does not create a tracked file row.

Slice Files (by layer)

• Route: src/routes/file.ts (thin wiring; GET /download, POST /upload/:table/:field).
• Controller: src/api/controllers/file.controller.ts (custom — download and upload). download calls assertCanDownloadFile before serving.
• Service (BLL): src/services/file.ts (uploadLocal, downloadLocal, uploadGCloud, downloadGCloud, deleteGCloud, initGCloud) for the storage I/O, plus src/services/file-access.ts (assertCanDownloadFile) for download authorization. Both upload and download require JWT; local handlers reject path traversal. Download no longer enforces per-file tenant ownership.
• Repository (DAL): src/db/api/file.ts (FileDBApi — replaceRelationFiles, _addFiles, _removeLegacyFiles); persists/removes file rows for entity relations. Note: this DAL imports @/services/file to call deleteGCloud (see Behavior / Notes).
• Model: src/db/models/file.ts.
• Shared used: api/http/request.ts (paramStr), middlewares/upload.ts (processFile multer wrapper), shared/config.ts (config.uploadDir, config.gcloud.bucket, config.gcloud.hash), shared/errors/validation.ts (ValidationError, in the DAL).

API

• GET /api/file/download?privateUrl=<path> -> downloads the file. Requires JWT authentication (passport.authenticate('jwt')). assertCanDownloadFile verifies that a current user exists, then the controller dispatches to downloadGCloud when NODE_ENV === 'production' or NEXT_PUBLIC_BACK_API is set, otherwise downloadLocal.
  • Local: missing privateUrl -> 404; a privateUrl that escapes the upload dir (path traversal via ..) -> 403 (resolveWithinUploadDir); otherwise streams via res.download from config.uploadDir.
  • GCloud: serves ${hash}/${privateUrl} from the bucket; file missing or error -> 404 { message }.
• POST /api/file/upload/:table/:field -> uploads a single file. Requires JWT authentication (passport.authenticate('jwt')). The folder is computed as :table/:field. Dispatches to uploadGCloud when NODE_ENV === 'production' or NEXT_PUBLIC_BACK_API is set, otherwise uploadLocal. The multipart form field name is file; the destination filename is taken from the request body field filename.
  • Local: no req.currentUser -> 403; missing file -> 400; missing filename -> 500; success -> 200 (empty body). Errors -> 500 with the stringified error.
  • GCloud: missing file -> 400 { message }; success -> 200 { message, url } where url is the public storage.googleapis.com URL; errors -> 500 { message }.

Access Rules

• Upload requires a valid JWT (route-level passport auth). The local upload path additionally rejects when req.currentUser is absent (403) and when an entity validation is supplied (403); the controller calls uploadLocal with entity: null, so the entity branch is not exercised from this endpoint.
• Download requires a valid JWT and performs no per-file ownership check; access is governed by authentication plus knowledge of the privateUrl.

Tenant Scope

None enforced in this slice. Neither upload nor download filters by organization; files are keyed by the :table/:field folder, the filename, and (for GCloud) the configured hash prefix. The file model has no organizationId column.

Data Contract

file model columns: id (UUID, PK), belongsTo (string, nullable), belongsToId (UUID, nullable), belongsToColumn (string, nullable), name (string, required, non-empty), sizeInBytes (integer, nullable), privateUrl (string, nullable), publicUrl (string, required, non-empty), createdAt, updatedAt, deletedAt (paranoid soft delete), createdById (UUID, nullable), updatedById (UUID, nullable). Associations: belongsTo users as createdBy and updatedBy.

In the DAL (replaceRelationFiles / _addFiles), each new file requires name and publicUrl, otherwise ValidationError('iam.errors.fileNameRequired') is raised.

Behavior / Notes

• Storage backend is chosen per request from NODE_ENV / NEXT_PUBLIC_BACK_API: GCloud in production, local disk otherwise.
• The upload middleware (src/middlewares/upload.ts) uses multer memory storage with a 10 MB file size limit on the field named file. The controller passes maxFileSize: 10 * 1024 * 1024 to uploadLocal, though that value is not consulted by uploadLocal (the limit comes from multer).
• services/file.ts still operates directly on Express Request/Response (streaming upload/download). This is a documented architecture exception: the import-boundaries test (src/shared/architecture/import-boundaries.test.ts) allows the BLL→HTTP dependency only for services/file.ts and services/auth.ts.
• src/db/api/file.ts imports @/services/file (calling deleteGCloud when removing legacy files), which is a DAL→BLL dependency. The same import-boundaries test keeps this as an exact allowlisted exception; any additional DAL→BLL import fails the architecture test.
• FileDBApi.replaceRelationFiles syncs a relation's files: it deletes existing file rows not present in the input (removing the GCloud object first when privateUrl is set) and creates rows for inputs marked new.

Tests

No dedicated file unit/e2e test exists. The architecture test src/shared/architecture/import-boundaries.test.ts references this slice by name in its exact BLL→HTTP and DAL→BLL exception allowlists.

Related

• search.md (the other backend infrastructure slice).
• Architecture contract: backend/docs/backend-architecture.md.