ulitka/WIP.md

WIP — вложения (2026-10-02)

Сделано за сегодня: модуль file (хранение файлов), модуль issue-attachment (вложения задач) и вложения в комментариях. Всё в ветке feature/attachments (не запушена), миграции к БД не применялись.

Архитектура

Метаданные файла хранятся отдельно от того, к чему файл прикреплён:

file  ←──  issue_attachment    (issueId, fileId)    — модуль issue-attachment
      ←──  comment_attachment  (commentId, fileId)  — модуль comment

• file ничего не знает о владельцах. Новый владелец = своя таблица связей
  • регистрация в FileOwnerRegistry; сам file при этом не меняется.
• Удаление задачи/комментария удаляет связи каскадом в БД, а файл без единой связи (сирота) удаляет GC.
• Флоу для клиента в два шага: загрузить файл → прикрепить по fileId.

Почему не полиморфная связь ownerType + ownerId: нет FK, нет каскадов, разные типы ключей (Issue.id — Int, остальные — uuid).

Миграции

Миграция	Что
20261002045355_file	таблица file
20261002050156_issue_attachment	таблица issue_attachment
20261002060755_comment_attachment	таблица comment_attachment

Собраны через prisma migrate diff без подключения к БД. Применятся при деплое (prisma migrate deploy в CMD Dockerfile).

Модуль file — src/modules/file/

API

Метод	Путь	Что
POST	/api/files	загрузка, multipart, поле file → FileDto
GET	/api/files/:id/download	скачивание (поток)
DELETE	/api/files/:id	удалить файл (только загрузивший), 204

FileDto: { id, fileName, mimeType, size, uploaderId, createdAt }. storageKey наружу не отдаётся.

Устройство

• domain:
  • StoredFile — не File, чтобы не путать с глобальным Web API File;
  • VO FileName: убирает путь и управляющие символы, обрезает до 255 с сохранением расширения;
  • порты IFileStorage, IFileTypeDetector.
• application:
  • use-case'ы upload / download / delete / get-files;
  • FileAccessService, FileOwnerRegistry, FileGcService.
• infrastructure:
  • FilePrismaRepository;
  • хранилища LocalFileStorage (dev/тесты) и S3FileStorage (S3 / RustFS / MinIO), выбираются в file-storage.factory.ts;
  • FileTypeDetector на file-type.
• presentation: FileController, хелпер contentDisposition (RFC 5987, кириллица), GraphQL-тип File.

Загрузка

• multer пишет во временный файл (os.tmpdir()), а не в память. Лимит — FILE_MAX_SIZE_MB, при превышении Nest отвечает 413.
• defParamCharset: 'utf8' — иначе multer ломает кириллицу в именах файлов.
• MIME определяется по содержимому (magic bytes). Нераспознанное (HTML, SVG, текст) сохраняется как application/octet-stream.
• Ключ в хранилище — files/{randomUUID}. Имя от пользователя в ключ не попадает.
• Порядок записи: объект → строка в БД. Если запись строки упала, объект удаляется сразу.

Скачивание и безопасность

• Inline отдаются только image/png|jpeg|gif|webp, всё остальное — как attachment. Плюс X-Content-Type-Options: nosniff — защита от stored XSS.
• Файл виден загрузившему и всем, кому виден хоть один его владелец (задача, комментарий). Иначе 404, чтобы не раскрывать существование файла.
• TransformResponseInterceptor пропускает StreamableFile. Без этого обёртка {data, code} ломала скачивание.

Прикрепление (для модулей-владельцев)

• FileAccessService.getAttachableFile(id, userId): прикрепить можно только свой файл. Невидимый файл → 404, чужой → 403. Иначе файл, увиденный через одну задачу, можно было бы перенести в другую.
• GetFilesUseCase — метаданные файлов по id, для раскрытия связей в DTO.

GC файлов-сирот

• FileGcService, @Cron(EVERY_HOUR). Подключён ScheduleModule в app.module.ts.
• Удаляет файлы старше FILE_ORPHAN_TTL_HOURS (по умолчанию 24), на которые не ссылается ни один зарегистрированный владелец.
• Порядок удаления: объект → строка. Удаление объекта идемпотентно, поэтому при сбое следующий запуск доделает работу. Тот же порядок в DeleteFileUseCase.
• Безопасен при нескольких инстансах приложения.

⚠️ Новый владелец файлов обязан зарегистрироваться в FileOwnerRegistry (onModuleInit), иначе GC удалит его файлы как сирот.

Модуль issue-attachment — src/modules/issue-attachment/

Отдельный модуль, как comment: зависит от issue, а issue о нём не знает. Иначе получался бы цикл issue ↔ attachment.

API

Метод	Путь	Что
GET	/api/issues/:issueId/attachments	список → IssueAttachmentDto[]
POST	/api/issues/:issueId/attachments	{ fileId } → IssueAttachmentDto
DELETE	/api/issues/:issueId/attachments/:fileId	открепить, 204 (файл удалит GC)

IssueAttachmentDto: { issueId, file: FileDto, attachedAt }.

GraphQL: поле IssueDetail.attachments. Его добавляет IssueAttachmentResolver через @ResolveField, issue-модуль не тронут. В списке задач (Issue) этого поля нет, чтобы не было N+1.

Правила

• Прикреплять и откреплять может любой, кому видна задача (то же правило, что для правки задачи), но прикрепить можно только свой файл.
• Повторное прикрепление идемпотентно (upsert).
• Если задачу или файл удалили между проверкой и вставкой (FK violation), ответ 404.
• IssueAttachmentFileOwnerService регистрируется в реестре. Видимость файла проверяется через IIssueRepository.findById, поэтому правило «reporter/assignee» живёт в одном месте.

Вложения в комментариях — модуль comment

Вложения — часть агрегата Comment (fileIds). Отдельных эндпоинтов нет:

POST  /api/issues/:issueId/comments  { "content": "...", "fileIds": ["…"] }
PATCH /api/comments/:id              { "content": "...", "fileIds": [...] }

• Ответы. CommentDto.attachments: FileDto[] — в create, update, списке и SSE-событиях.
• Правка. fileIds при update задаёт набор целиком; не передан — вложения не меняются.
  • Синхронизация связей идёт в одной транзакции с правкой текста.
  • Изменение только набора файлов тоже считается правкой (editedAt, comment.updated).
  • Проверяются только добавленные файлы.
• Ограничения: максимум Comment.MAX_ATTACHMENTS = 10, дубли убираются.
• Порядок — по времени загрузки. id файлов — uuid v7, поэтому сортировка по строке совпадает с порядком загрузки.
• Мягкое удаление комментария снимает связи, файлы забирает GC. В ответе у удалённого комментария attachments: [].
• CommentAttachmentFileOwnerService регистрируется в реестре. Файл виден тем, кому видна задача неудалённого комментария с этим файлом.
• CommentAuthorExpanderService переименован в CommentExpanderService: он раскрывает и авторов, и файлы (параллельно).

Прочие изменения

• Зависимости: @aws-sdk/client-s3, file-type, @nestjs/schedule; dev — @types/multer.
• tsconfig.json: multer добавлен в types, иначе не виден Express.Multer.File.
• .gitignore / .dockerignore: добавлен /storage — каталог локального хранилища.

Переменные окружения

FILE_STORAGE=s3                # local (по умолчанию) | s3
FILE_STORAGE_LOCAL_DIR=./storage
FILE_MAX_SIZE_MB=25
FILE_ORPHAN_TTL_HOURS=24

S3_ENDPOINT=http://rustfs:9000 # для AWS можно не задавать
S3_REGION=us-east-1
S3_BUCKET=ulitka
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=true       # для RustFS/MinIO

В .env были закомментированы RUSTFS_*. Адаптер использует общие S3_*.

Проверено

• 154 unit-теста проходят. Типы, линтер и сборка чистые.
• Приложение стартует, DI резолвится, новые маршруты без сессии отвечают 401. В schema.gql появились File, IssueAttachment, IssueDetail.attachments.
• Не проверено: сценарий целиком с авторизацией, реальной БД и S3 (upload → attach → download → GC).

TODO / открытые вопросы

• Перед деплоем: создать бакет в RustFS (приложение его не создаёт), прописать FILE_STORAGE=s3 и S3_* на сервере.
• Прогнать e2e: загрузка → прикрепление → скачивание другим участником → открепление → GC.
• Влить feature/attachments в main. Push в main запускает деплой — сначала бакет и переменные окружения.
• Лимит числа вложений у задачи (у комментария — 10).
• SSE-события для вложений задачи (по образцу CommentEventsService).
• Комментарий только с файлами, без текста? Сейчас текст обязателен.
• Вложения комментариев в GraphQL — когда появятся комментарии в GraphQL.
• GC при большом числе файлов: сейчас каждый запуск проходит по всем старым файлам. При сотнях тысяч файлов — переписать на NOT EXISTS.
• Маловероятная гонка: прикрепление файла, загруженного больше 24 ч назад, ровно в момент прохода GC может его потерять.
• Позже: отдавать скачивание redirect'ом на presigned GET вместо стрима через Node.