# Cursor 작업 첨부파일 보관소

Python 3.10 이상, Cursor가 필요합니다. 처음 패키지 설치에만 인터넷이 필요합니다.
app.py가 있는 storage-lab 폴더를 File → Open Folder로 열고 Terminal → New Terminal에서 실행하세요.

```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py
```

py가 없으면 python --version을 확인하고 첫 명령의 py를 python으로 바꾸세요.
가상환경 활성화는 필요하지 않습니다. http://127.0.0.1:5000 에 접속합니다.
localhost 대신 위 주소를 사용하세요. 종료는 Ctrl+C, 재실행은 마지막 명령입니다.
앱은 단일 프로세스·단일 요청 스레드로 실행합니다. 두 서버를 동시에 실행하지 마세요.

## 파일과 정책

- storage/: 첨부파일 본문. 원본 파일명 대신 UUID 기반 저장 키를 사용합니다.
- data/db.json: TinyDB 작업과 첨부 메타데이터. 파일 본문은 포함하지 않습니다.
- sample-jobs.json: 최초 DB 생성 때만 가져오는 작업 3개.
- app.py의 FILE_LIMIT: 5MiB, TOTAL_LIMIT: 10MiB, ALLOWED: pdf/png/jpg/txt/csv.
- 총량은 storage 폴더의 실제 파일 크기로 계산합니다. DB 파일·실습 샘플·가상환경은 이 교육용 한도에 포함하지 않습니다.
- MiB는 1,048,576바이트입니다. 클라우드 요금표의 GB와 단위가 다를 수 있습니다.

## 확인 순서

작업 선택 → 파일 첨부 → storage/와 data/db.json 비교 → 다운로드 후 원본과 비교 → 서버 재시작 후 목록과 파일 확인.
같은 이름의 파일을 두 번 첨부해도 별도로 보관됩니다. 삭제 전 확인하며 삭제한 파일은 복구하지 않습니다.

### 용량 초과 실습

서버 실행 전 아래 명령으로 각각 4MiB인 텍스트 파일 3개를 만드세요. 기존 샘플은 덮어쓰지 않습니다.

```powershell
.\.venv\Scripts\python.exe make_samples.py
```

1. 기존 첨부파일이 없는 상태에서 서버를 실행합니다.
2. quota-samples/sample-1.txt와 sample-2.txt를 첨부하면 사용량은 8MiB입니다.
3. sample-3.txt를 첨부하면 총 10MiB 초과로 거부됩니다. 사용량은 8MiB입니다.
4. 첫 파일을 삭제하면 4MiB입니다. 세 번째를 다시 첨부하면 8MiB로 성공합니다.
5. 삭제 질문을 취소하면 파일과 용량이 그대로인지 확인합니다.

## 실패를 숨기지 않기

- 빈 파일·허용하지 않는 확장자는 400, 개별 크기 초과는 413, 총량 초과는 409입니다.
- 저장 실패는 성공으로 표시하지 않습니다. 새 파일은 가능한 범위에서 정리합니다.
- 삭제는 실제 파일을 먼저 지우고 DB 기록을 정리합니다. DB 정리가 실패하면 다시 삭제를 눌러 남은 기록을 정리할 수 있습니다.
- 실제 파일이 이미 없으면 다운로드는 404이며 남은 기록은 삭제할 수 있습니다.
- DB 파일이 깨지면 자동 초기화하지 않습니다. 종료 후 백업하고 내용을 확인하세요.
- JSON 쓰기는 임시 파일을 완성한 뒤 교체합니다. 파일 본문과 DB가 하나의 트랜잭션으로 묶이는 것은 아닙니다. 비정상 종료 후 고아 파일은 자동 정리하지 않습니다.
- 실행 중 storage/나 DB를 직접 편집하지 마세요. 용량 확인은 읽기로만 합니다.

## 실습 범위

로컬 개인 실습입니다. 로그인·사용자별 권한·자동 삭제·백업·S3·CDN·서명 URL은 구현하지 않습니다.
확장자 제한은 파일 내용 검사나 악성 파일 검사가 아닙니다. 첨부파일은 미리보기하지 않고 다운로드로만 전달합니다.
실제 서비스에는 사용자별 권한, 동시 업로드 제어, 보관·복구 정책과 비용 감시가 별도로 필요합니다.

포트가 이미 사용 중이면 이전 실습 서버를 그 터미널에서 Ctrl+C로 종료하세요.
모듈을 찾지 못하면 설치·실행 모두 .venv의 Python으로 했는지 확인하세요.
교육 사이트에 코드를 올리는 것만으로 Python 서버가 배포되지는 않습니다.