Feature #1290
openFeature #1226: [MDGU] 학사관리 시스템 v1 개발 (8주, 2026-11-05 시작)
Feature #1229: [MDGU-12] 첨부·Excel (김예주)
[MDGU-12-01] 증빙 파일 업로드·암호화 저장·접근통제·다운로드 이력
0%
Description
목적¶
지원자·학생 증빙 파일을 안전하게 저장하고 인가된 사용자만 받을 수 있게 하며 다운로드 이력을 남깁니다. (FR-FILE-001, NFR-SEC-004, 010)
쉬운 설명¶
증빙 파일을 업로드하면 암호화해서 저장하고, 권한 있는 사람만 다운로드하며 다운로드 이력을 남깁니다.
기술 스택¶
Django 파일 업로드 검증(확장자·MIME·크기), 02-03 암호화, 보호된 다운로드 뷰(Nginx 공개 alias 금지), 02-05 감사 로그.
예상 결과(산출물)¶
files 앱의 Attachment 모델, 업로드·다운로드 뷰, 접근통제, 이력, 테스트.
개발 작업 상세¶
- 업로드 검증(확장자·MIME·용량·파일명 정규화)을 구현한다.
- 민감 첨부는 저장 시 암호화하고 키는 분리한다(02-03).
- 다운로드는 인가 검증 후 보호 경로로 제공하고 공개 media URL은 쓰지 않는다.
- 다운로드 이력을 감사 로그에 남긴다.
- 06-03(지원 첨부)과 문자열 FK로 연결한다.
- 테스트: 무권한 다운로드 차단, 악성 파일명·확장자.
완료 기준¶
- 무권한 직접 URL 다운로드가 차단된다.
- 다운로드 이력이 남는다.
충돌 방지(소유 범위)¶
files/ 앱은 김예주 소유. 06-03은 files 모델을 문자열 FK로만 참조합니다.
선행·후행·위험¶
선행: 02-03 암호화·키 관리 구현(김예주, 11/19 종료) / 02-04 역할·권한(RBAC) 구현(김예주, 11/24 종료)
후행: 02-06 보안 점검·자동 테스트 모음 정리(김예주) / 12-02 Excel 가져오기·내보내기(오류 행 검증)(김예주) / 14-02 이관 스크립트(합성 데이터 리허설용)(서현)
결과 확인 방법¶
"완료 기준"의 각 항목을 화면 또는 명령으로 직접 확인합니다.
- 무권한 직접 URL 다운로드가 차단된다.
- 다운로드 이력이 남는다.
- pytest가 모두 통과한다.
- 확인 결과(화면 캡처 또는 명령 출력 요약)를 일감 메모에 남긴다.
갱신 사항 (2026-11-04)¶
- ERD 검수 반영: 보호 파일에 원본 파일명(암호화), 콘텐츠 유형, 크기, 해시를 추가하고, 지원자 증빙용 applicant_attachment를 함께 구현한다. 다운로드 이력은 감사 로그 이벤트(file.download)로 기록한다.
시작 전 준비¶
- 선행 일감의 결과물(문서·코드)을 먼저 읽고 약속된 이름·구조를 확인한다.
- 저장소를 최신으로 맞춘다: git switch main 후 git pull --ff-only origin main
- 저장소 README 8번과 팀 로컬 세팅 안내 순서대로 환경을 준비한다. 보통 py -3.12 -m venv .venv, 가상환경 켜기, python -m pip install -r requirements-dev.txt, Windows에 설치한 PostgreSQL 18에서 개인 로컬 DB(university_dev) 생성, .env.local 설정(DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT), python manage.py check, python manage.py migrate 순서이다. 최초 실행에 makemigrations는 필요 없고, .env.local과 비밀번호는 공유·커밋하지 않는다.
- #1226의 폴더 소유 표에서 내가 고칠 수 있는 폴더를 확인한다.
작업 진행 순서¶
- 브랜치를 만든다: git switch -c feature/1290-<짧은영문설명>
- "개발 작업 상세"의 번호 순서대로 한 단계씩 구현하고, 단계마다 pytest로 확인한다.
- 모델을 바꾸면 python manage.py makemigrations, 그다음 python manage.py migrate를 실행한다.
- 화면은 python manage.py runserver로 실행해 직접 열어 보고 "완료 기준"과 하나씩 대조한다.
- git add, git commit, git push 후 PR을 만든다. PR 템플릿의 체크리스트를 채우고 폴더 소유자의 리뷰를 받는다.
- 병합 후 이 일감 메모에 PR 링크와 확인 결과를 적고 상태와 진행률을 갱신한다.
막힐 때 확인¶
파일을 공개 주소(static)에 두지 마세요. 파일 크기·형식 제한도 확인하세요.
그래도 해결되지 않으면 일감 메모에 "무엇을 했고, 어떤 오류가 났는지"를 붙여 담당 분류 소유자 또는 팀장에게 질문하세요.
용어 풀이¶
- FK(외래 키): 한 테이블의 값이 다른 테이블의 어떤 행을 가리키게 하는 연결 값입니다. 학생이 소속 학과를 가리키는 것이 예입니다. 앱 사이에는 "앱이름.모델" 문자열로 적어 앱 간 직접 import를 피합니다.
- 감사 로그: 누가 언제 무엇을 했는지 남기는 변경 불가 기록입니다. 문제가 생겼을 때 추적하는 근거가 됩니다.
- 암호화·키 관리: 데이터를 열쇠(키) 없이는 읽을 수 없게 바꾸는 일과, 그 키를 안전하게 보관·교체하는 일입니다. 키는 코드와 따로 보관합니다.
- Nginx: 웹 요청을 받아 앱(Gunicorn)이나 정적 파일로 전달하고 HTTPS를 처리하는 웹 서버입니다.