1) 개발 환경 및 기술 스택
계층별로 언어·프레임워크·패키지 관리자를 고정한다. 전체 시스템 구성도는 6장 1)절 시스템 구성도를 본다 — 여기는 개발자가 로컬에서 무엇을 설치·실행하는가를 정리한다.
| 계층 | 언어·프레임워크 | 패키지 관리 | 로컬 실행·테스트 |
|---|---|---|---|
앱 (flutter/) | Flutter · Dart, 상태 관리는 Riverpod, 라우팅은 go_router | pubspec.yaml | flutter analyze (0건이어야 함) · flutter test |
웹 (www/) | Next.js 16(App Router) · React 19 · TypeScript 5 · Tailwind CSS 4 | npm | npm run dev · npm test(Vitest) |
백엔드 API (fastapi/) | Python 3.14 · FastAPI · SQLAlchemy(동기) · Alembic | uv | pytest -q · alembic upgrade head && alembic check |
AI 에이전트 (agent/) | Python 3.12(시스템 3.14와 별도 고정) · PyTorch · Transformers 5 | uv | uv run pytest tests/ -q |
| DB | PostgreSQL 18 + pgvector 확장 | — | 로컬은 Docker 컨테이너 또는 네이티브 설치 |
| 문서 사이트(이 제안서) | Jekyll(Just the Docs 테마) | Bundler(RubyGems) | bundle exec jekyll serve |
백엔드는 바운디드 컨텍스트 구조다. app/<컨텍스트>/{domain,application, adapter,dependencies}로 계층을 나누고(컨텍스트: 사용자·카드·영상분석·매칭·평가), 컨텍스트끼리는 직접 임포트하지 않는다 — 남의 테이블이 필요하면 문자열 참조로 건다. 이 경계를 tests/test_architecture.py가 코드로 강제한다.
AI 에이전트는 시스템 Python(3.14)과 별도의 3.12 환경을 쓴다 — 판정 모델 (Transformers 5.x + EXAONE)이 요구하는 버전이 시스템 버전과 달라서다. 개발 GPU는 RTX 3050 8GB이고, 포즈 추정기와 판정 모델을 동시에 올릴 수 없어 순차 적재한다(6장 3)절). 평가·운영용 GPU는 AWS g4dn.xlarge를 쓴다.
배포 인프라는 AWS ap-northeast-2 단일 EC2 인스턴스 위에 k3s(단일 노드 쿠버네티스)로 백엔드 API를, 같은 인스턴스에 PostgreSQL을 직접 올린다. 앞단은 nginx + Let’s Encrypt로 TLS를 종단한다. main에 백엔드 변경이 들어가면 GitHub Actions가 이미지를 빌드해 Docker Hub에 올리고, 서버가 폴링해 재배포한다(CD). 웹은 Vercel에, 이 문서 사이트는 GitHub Pages에 각각 정적 배포한다. 영상 원본·리포트 산출물은 AWS S3에 둔다.
2) 주요 기능 구현 방안
5장 기능 요구사항(SFR)을 어떤 방식으로 구현하는지 기능 단위로 요약한다. 설계 근거·상세는 6장을, 요구사항 전문은 5장을 본다.
| 기능 | 핵심 구현 방식 | 상세 설계 |
|---|---|---|
| 영상 업로드 (SFR-001) | 클라이언트가 API에서 사전 서명 URL을 받아 객체 저장소(S3)에 직접 업로드한다 — 원본이 API 서버를 거치지 않는다(PER-002) | 6장 1)절 |
| 영상 분석 (SFR-002·003) | 업로드 등록 시 분석 작업을 큐에 적재하고, 별도 GPU 워커가 폴링해 가져간다. 측정(포즈·수치)은 결정론적 코드, 판정 근거 문장만 언어 모델이 쓴다 — 모델이 점수를 생성하지 않는다 | 6장 3)·4)절 |
| 호칭 부여 (SFR-004) | 지표 조건을 title_criteria에 행 단위로 정의하고, 절대 기준으로만 판정한다(상대 비교 없음) | 부록 D |
| 성향 유사도 (SFR-005) | 지표 묶음을 특징 벡터로 만들어 pgvector에 색인하고 코사인 유사도로 검색한다 | 부록 D.4 |
| 적합도 산출 (SFR-006) | 지원 건마다 수준·역할·성향 세 축을 각각 계산해 단일 점수로 합치지 않는다 | 5장 2절 |
| 매칭 추천 (SFR-007) | 후보 추천에 사유를 함께 저장한다(recommendation.reason NOT NULL) — 근거 없는 추천을 남기지 않는다 | 부록 D.5 |
| 상호 평가 (SFR-008) | 자유 서술·점수 대신 선택형 항목(review_option)으로 받고, 불참·신고는 평가와 분리된 별도 기록(no_show·report)으로 남긴다 | 부록 D |
| 카드 공유 (SFR-009) | 인증 없이 열리는 공개 링크를 96비트 무작위 슬러그로 발급한다. 카드에는 수치 능력치를 두지 않고, 수치는 리포트 경로로만 조회한다 | 5장 2절(SEC-005) |
| 경기 등록·매칭 (SFR-010) | 경기에 필요 포지션·인원을 행 단위(match_position_need)로 등록하고, 지원(match_application)은 팀·본인 수락 시각을 각각 가져 매칭 확정을 사람이 하게 한다 | 부록 D |
공통 원칙으로 모든 화면·API가 스텁(가짜 응답) → 실제 백엔드로 교체 가능한 구조로 시작한다 — 웹·앱은 리포지토리 인터페이스만 알고 구현체(Mock/API)를 provider 한 곳에서만 교체하므로, 백엔드가 늦게 붙어도 화면 개발이 막히지 않는다.
3) 조직 구성 및 역할 분담
조직 구조
4인이 역할별로 완전히 분리된 영역을 각자 맡고, PM이 통합을 담당하는 단일 계층 구조다. 기획·디자인·개발을 겸하는 소규모 팀 특성상 별도의 리뷰어 직책을 두지 않고, main 통합 시점의 병합 확인(빌드·테스트 통과)이 실질적인 검토 관문 역할을 한다.
| 역할 | 담당 | 책임 범위 | 소유 코드 영역 |
|---|---|---|---|
| PM | 박민호 | 요구사항·일정 관리, 스프린트 진행, QA 총괄, main 브랜치 통합 | jekyll/(제안서 문서), 미결 항목 운영 |
| 프론트·웹 | 백성검 | Flutter 앱 UI/UX, 웹 페이지, 화면 구현 | flutter/ · www/ |
| 백엔드·파이프라인 | 정어진 | DB·API 설계, 영상 수집·전처리, 배포 | fastapi/ |
| AI 에이전트 | 정상호 | 루브릭 기반 실력 검증, 판정 근거 생성 | agent/ |
전체 진행 일정과 스프린트별 담당 태스크는 아래 4)절을 본다.
협업 원칙
- 사람마다 자기 브랜치(
min·paik·jin·ho)에서 작업하고,main에는 직접 커밋하지 않는다. PM이 각 브랜치를main에 병합하고, 필요하면main을 다시 각 브랜치로 되병합(sync)해 서로의 작업을 흘려보낸다. - 남의 코드 영역을 고쳐야 하면 그 영역의 진입점 문서부터 읽는다 — 각 폴더(
fastapi/·www/·flutter/·agent/)에 관례·테스트 구조를 적은 안내 문서를 둔다. - 스키마·API 계약을 바꾸는 변경은 사전에 공유한다. 클라이언트(앱·웹)가 뒤따라 고쳐야 하기 때문이다.
- 팀원 사이 요청·결정은 미결 항목 페이지에 모은다. 데일리 스탠드업을 대신해 비동기로 담당자·기한과 함께 쌓이고, 처리되면 해소 표시를 남겨 같은 조사를 반복하지 않는다.
4) 단계별 개발 일정
애자일 스크럼 방식으로 진행한다. 전체 개발 기간(2026.08.20 ~ 2026.10.27, 10주)을 2주 단위 스프린트 5회로 나누고, 스프린트마다 스프린트 계획 → 데일리 스탠드업 → 스프린트 리뷰 → 회고를 반복한다.
팀 역할 (2026.08.26 재배정)
- 박민호 — PM (요구사항/일정 관리, 스프린트 진행, QA 총괄)
- 백성검 — 프론트·웹 (Flutter 앱 UI/UX, 화면 구현, 웹 페이지)
- 정어진 — 백엔드·파이프라인 (DB·API, 영상 수집·전처리, 분석 파이프라인, 배포)
- 정상호 — AI 에이전트 개발 (루브릭 기반 실력 검증, 근거 생성)
스프린트 로드맵
| Sprint | 기간 | 목표 | 박민호(PM) | 백성검(프론트·웹) | 정어진(백엔드·파이프라인) | 정상호(에이전트) |
|---|---|---|---|---|---|---|
| 1 | 08.20 ~ 08.31 | 요구사항 확정, 개발환경 구축 | 요구사항/일정 확정, 백로그 작성 | 프로젝트 초기 셋업, 화면 설계 | DB 스키마 설계, 데이터 수집 방안 | 에이전트 아키텍처 리서치 |
| 2 | 09.01 ~ 09.14 | 핵심 기능 프로토타입 | 스프린트 진행, 중간 점검 | 로그인/선수 카드 화면 구현 | API 규격 확정, 영상 전처리 파이프라인 구축 | 루브릭 기반 실력 검증 로직 프로토타입 |
| 3 | 09.15 ~ 09.28 | 기능 고도화 | 진행 점검, 리스크 관리 | 매칭/구인 플로우 구현 | 영상 분석 모델 연동, 벡터 저장·검색 | 채점 시스템 신뢰성 강화(fps 불변성 개선, 임계값 출처 조사) |
| 4 | 09.29 ~ 10.12 | 통합 및 테스트 | 통합 테스트 총괄, QA | 화면 통합, 버그 수정 | 파이프라인 성능 튜닝, 추천 API 정확도 검증(Hit Rate/Recall) | 채점 검증 결과 반영·통합 테스트 지원(골든셋 확보 시 QWK·MAE 측정) |
| 5 | 10.13 ~ 10.27 | 마무리 및 배포 준비 | 최종 점검, 발표 준비 | 앱 배포 빌드, 웹 페이지 마감 | 운영 환경 배포 | 최종 검증 및 튜닝 |
백엔드와 파이프라인이 정어진 한 사람에게 묶여 있다. API 규격과 색인 스키마가 각각 백성검·정상호의 착수 조건이므로, 이 영역은 구현보다 규격을 먼저 낸다.