---
spec: agent-feature
status: in-progress
owner: feature-pipeline-agent
related-routes:
files:
  - src/api/v2/projects/files/files.routes.ts
  - src/api/v2/projects/files/files.controller.ts
  - src/services/files.service.ts
---

# agent-feature

## Goal

Add a read-only API2 endpoint GET /api/v2/projects/{projectId}/files/biggest that returns
the full file metadata for the largest non-soft-deleted file (by FileSizeBytes) in a project,
returning 200 with null body when none exist and 404 when the project does not exist. Backed
by a new fn_GetBiggestFile function; no schema changes.


## Behavior changes

- GET /api/v2/projects/{projectId}/files/biggest

## Acceptance criteria

- [ ] The behavior described above is implemented on the listed files.
- [ ] Existing behavior is unchanged when the new feature is not exercised.
- [ ] Unit and (where observable) e2e tests cover the new behavior.

## Out of scope

- Returning a ranked/sorted list of files by size (only the single biggest is returned).
- Filtering biggest-file selection by file type, extension, or other attributes.
- Any changes to API1 services (hc-project, hc-iam, hc-bpm, hc-notification).
- Including BatchFile or UserFile rows; only xyz.FileReference is considered.

## Notes / open questions

- Generated by the feature pipeline from the approved architect plan. If any
  acceptance criterion is ambiguous, ask the human before implementing.

## Decisions

- The spec's `files:` frontmatter names `src/api/v2/projects/files/{files.routes,files.controller}.ts`
  and `src/services/files.service.ts`, but those paths do not exist. The established resource in this
  repo is `projectfiles` (`src/api/v2/projects/projectfiles/*` mounted at `/:projectId/files`,
  `src/services/projectfiles.service.ts`). Implemented the endpoint there to follow the actual
  convention rather than create a parallel `files/` tree.
- Route registered as `GET /biggest` **before** `GET /:fileReferenceId` so the literal path is not
  captured as a `fileReferenceId` UUID param.
- Response shape mirrors the list endpoint's per-item metadata (no `downloadUrl`/`CloudStoragePath`),
  matching "full file metadata" for a read-only endpoint.
- 200-with-null vs 404 distinction: service returns `null` when `fn_GetBiggestFile` yields 0 rows
  (project exists, no files) → controller responds `200 null`; a DB error containing
  "No project found for ProjectId" maps to `NotFoundError` → `404`, mirroring `createProjectFile`.
- `fn_GetBiggestFile` is a new DB function. DB function definitions are NOT housed in this repo
  (the e2e dump only seeds data), so creating the function is a separate DB-migration change. The
  e2e happy-path/empty/404 cases depend on that function existing in the seeded test DB.
- Could not run `tsc`/unit/e2e locally: `node_modules` is not installed and per task constraints no
  toolchain was installed. The CI pipeline runs the suite.