[graduta]

I have a JIRA ticket

• branch and/or PR name(s) include(s) JIRA ID
• issue has "Fix version" assigned
• issue "Status" is set to "In review"
• PR labels are selected

Part of a stack of PRs documenting the HTTP API (O2B-1623). This PR is stacked on the previous one of the stack (its base is the branch of that PR): GitHub retargets it to main once the PRs below are merged.

Notable changes for users:

• The POST /api/attachments and GET /api/attachments/{attachmentId} endpoints are now documented at /api-docs (the POST is flagged x-llm-exclude). The documentation of the generator now supports multipart/form-data bodies and file downloads, so the curl examples contain the -F fields and -OJ.
• GET /api/attachments/{attachmentId} now answers with the status 404 (it answered 400 with a body saying 404) when the attachment does not exist.
• POST /api/attachments now rejects (400) a request without any file instead of crashing with a generic server error.
• The attachments of a log no longer contain createdAt and updatedAt (nothing used them; breaking for any external client reading them). The response of POST /api/attachments is the row of the database as it is and is not affected.

Notable changes for developers:

• The attachment use cases are migrated to an AttachmentService (getOneOrFail, create) on small functions; lib/usecases/attachment is removed.
• The 404 of an unknown attachment now uses the standard error format (title: Not found and a detail), and the creation response no longer contains createdAt and updatedAt.
• Checked the chain of the endpoints: all files have their license header, and the frontend only reads the id, the file name, the original name, the mime type and the size of an attachment.
• The attachments are still read and created through use cases (lib/usecases/attachment: CreateAttachmentUseCase, GetAttachmentUseCase, plus GetAllLogAttachmentsUseCase and GetLogAttachmentUseCase for the logs endpoints). They are not migrated here: to be decided with the team (small: two use cases for this router, the two others belong to the logs router).
• Bugs found and fixed with API tests: the 400 sent for an unknown attachment, and the TypeError for an upload without file (the file middleware gives an empty list, which passed the xor('file', 'files') check: files must now contain at least one file).
• AttachmentAdapter.toEntity (only used for the attachments of logs) no longer returns createdAt / updatedAt, and the Attachment typedef is updated.
• Documentation of the handlers (the file one described the search of the attachments of a log) and name of a DTO (GetAttachmentDto.js exported GetLogAttachmentDto).
• Not changed, to be discussed: POST /api/attachments returns the raw row (with the path of the file on the server and ISO dates) instead of the entity, only the first file of a request is stored (the others are written on the server and never referenced) and log is optional.

Changes made to the database:

• None

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.55556% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 42.53%. Comparing base (9730487) to head (cdcaebe).

Files with missing lines	Patch %	Lines
lib/server/controllers/attachments.controller.js	91.66%	1 Missing ⚠️
lib/server/services/attachment/getAttachment.js	85.71%	1 Missing ⚠️

Additional details and impacted files

@@                              Coverage Diff                              @@
##           feature/O2B-1623/docs-eos-report-endpoint    #2281      +/-   ##
=============================================================================
- Coverage                                      46.65%   42.53%   -4.12%     
=============================================================================
  Files                                           1063     1064       +1     
  Lines                                          17439    17453      +14     
  Branches                                        3176     3178       +2     
=============================================================================
- Hits                                            8136     7424     -712     
- Misses                                          9303    10029     +726     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.