repository
repository는 파일 업로드, 다운로드, 삭제, 파일 메타데이터 관리를 담당하는 모듈입니다. 저장소 정의는 JSON 계약으로 관리하고, 메타데이터 저장/조회는 dbclient 계약과 연계합니다.
책임 범위
- 저장소 계약을 읽어 파일 저장 위치와 다운로드 URL 정책을 결정합니다.
- 단일/다중 파일 업로드, 다운로드, 삭제, 저장소 조회 API를 제공합니다.
- 파일 메타데이터를
DatabaseContractPath의dbclient계약으로 저장하고 조회합니다. - 다른 모듈이 MediatR 이벤트로 파일 저장소 기능을 사용할 수 있도록
repository.Events.RepositoryRequest를 제공합니다. - 다운로드 응답에
XFrameOptions,ContentSecurityPolicy같은 보안 헤더를 적용합니다.
주요 API
| 메서드 | 경로 | 용도 |
|---|---|---|
GET | /repository/api/storage/refresh | 저장소 계약 캐시를 갱신합니다. |
GET | /repository/api/storage/action-handler | 저장소 action 요청을 처리합니다. |
GET | /repository/api/storage/get-repository | 저장소 정의를 조회합니다. |
POST | /repository/api/storage/upload-file | 단일 파일을 업로드합니다. |
POST | /repository/api/storage/upload-files | 여러 파일을 업로드합니다. |
POST | /repository/api/storage/download-file | 파일을 다운로드합니다. |
GET | /repository/api/storage/http-download-file | HTTP 경로 기반 다운로드를 처리합니다. |
GET | /repository/api/storage/virtual-download-file | 가상 경로 다운로드를 처리합니다. |
GET | /repository/api/storage/virtual-delete-file | 가상 경로 파일을 삭제합니다. |
POST | /repository/api/storage/remove-item | 단일 항목을 삭제합니다. |
POST | /repository/api/storage/remove-items | 여러 항목을 삭제합니다. |
핵심 구현
Areas/repository/Controllers/StorageController.cs: 저장소 API 진입점입니다.Extensions: 저장소 provider, 경로 계산, 모듈 API 호출 보조 기능입니다.Services/StorageProviderFactory.cs: 저장소 구현을 선택합니다.Contracts/repository: 저장소 선언 JSON 계약입니다.Contracts/dbclient,Contracts/transact: 파일 메타데이터 조작을 위한 보조 계약입니다.
계약과 설정
저장소 선언 계약은 기본적으로 다음 위치에 둡니다.
contracts/repository/{ApplicationID}/...
주요 설정은 다음과 같습니다.
| 설정 | 설명 |
|---|---|
FileServerUrl | 외부 다운로드 URL의 기준 주소입니다. |
ContractBasePath | 저장소 JSON 계약 루트입니다. |
DatabaseContractPath | 파일 메타데이터를 저장/조회할 dbclient 계약 루트입니다. |
ModuleBasePath | repository 모듈 파일 기준 경로입니다. |
SubscribeAction | 기본 수신 이벤트는 repository.Events.RepositoryRequest입니다. |
XFrameOptions | 다운로드 응답의 frame 허용 정책입니다. |
ContentSecurityPolicy | 다운로드 응답의 frame-ancestors 정책입니다. |
실행 흐름
- 모듈 초기화 시
ContractBasePath의 저장소 JSON 계약을 로드합니다. - 업로드 요청이 들어오면 저장소 ID와 업무 키를 기준으로 실제 파일 경로를 계산합니다.
- 파일 저장 후
DatabaseContractPath의 dbclient 계약으로 메타데이터를 기록합니다. - 다운로드 요청은 저장소 계약과 메타데이터를 확인한 뒤 보안 헤더를 포함해 파일을 반환합니다.
- 계약 변경 시
/repository/api/storage/refresh또는 파일 감시로 매핑을 갱신합니다.
운영 주의사항
- 업로드 가능한 경로와 다운로드 URL은 저장소 계약에서 명확히 제한합니다.
- 파일 메타데이터와 실제 파일 저장소가 불일치하지 않도록 삭제/이관 작업은 repository API를 통해 수행합니다.
XFrameOptions,ContentSecurityPolicy는 화면 내 iframe 다운로드나 미리보기 요구사항과 보안 정책을 함께 고려해 설정합니다.LoadPassAssemblyPath에 OS별 SkiaSharp native library가 포함되므로 배포 대상 OS에서 파일이 누락되지 않게 확인합니다.