시스템 설계

본 장은 제 2 장의 요구사항을 구현하기 위한 시스템 구조를 기술한다. 에이전트 계층의 내부 설계는 제 4 장에서 별도로 다룬다.

1) 시스템 구성

계층 구성

계층	역할
클라이언트	공고 탐색·지원·영상 업로드, 운영자의 공고 등록과 참여자 확정
API 서버	인증, 상태 전이, 유효성 검증, 에이전트 호출과 결과 검증
에이전트 계층	영상 분석·매칭·검증 (4장)
데이터 저장소	사용자·경기·지원·기록·스탯, 영상 장면 색인
외부 서비스	알림 발송, 지도·좌표 조회, 영상 저장소

요청 흐름

운영자가 후보 목록을 여는 경우를 예로 들면 다음 순서를 따른다.

클라이언트가 API 서버에 후보 목록을 요청한다.
서버가 공고 조건과 지원자 정보를 조회하고, 순위 요소를 수치화한다.
서버가 매칭 에이전트를 호출한다.
서버가 응답의 형식과 값의 범위를 검증한다.
검증을 통과한 결과만 클라이언트에 전달한다.

에이전트 호출은 서버를 통한다

클라이언트가 모델을 직접 호출하지 않는다. 이유는 두 가지다. 첫째, 인증 정보가 클라이언트에 놓이면 유출을 막을 방법이 없다. 둘째, 모델 응답을 서버가 검증하지 않고 화면에 그대로 쓰면 순위·스탯 같은 값이 검증 없이 반영된다. 4장에서 모델 응답을 서버 검증 뒤에만 반영하도록 설계한 것이 이 구조를 전제로 한다.

2) 기술 스택

선정 기준

기준	내용
개발 기간	10주 안에 4명이 완주 가능한가
숙련도	팀이 이미 다뤄 본 기술인가
요구사항 적합성	영상 저장·처리, 위치 계산, 알림, 에이전트 호출을 무리 없이 다루는가

10주라는 기간에서는 학습 비용이 가장 큰 위험이다. 새 기술을 도입할 근거가 요구사항에서 나오지 않는다면 익숙한 쪽을 택한다.

확정 스택

인프라와 저장소 계층은 스프린트 1 1주차(2026-08-21)에 확정했다. 담당은 정어진이다.

영역	확정	선정 근거
클라우드	AWS	계정과 IAM 사용자를 확보하고 데이터베이스 인스턴스까지 띄운 상태에서 시작한다. 다른 사업자로 옮길 근거가 요구사항에서 나오지 않았다
데이터 저장소	Aurora Serverless v2 · PostgreSQL 17	위 세 가지 검토 사항(좌표 거리 계산·이력 조회·장면 색인 검색)을 한 엔진이 감당한다. 용량이 부하를 따라 오르내려 개발 단계의 유휴 비용이 낮다
용량 범위	0~4 ACU	시험 전까지 실사용 부하가 없다. 상한 4 ACU는 시험 단계에서 재검토한다
벡터 검색	`pgvector`	별도 벡터 데이터베이스를 두지 않는다. 아래 참조

벡터를 관계형 데이터와 같은 저장소에 두는 이유는 이 사업의 검증 규칙 때문이다. 제 6 장의 판정은 근거 장면 없이 저장될 수 없고, 그 제약은 3절의 데이터 모델에서 검증 판정 → 장면 색인 참조로 표현된다. 색인이 별도 벡터 저장소에 있으면 이 참조를 외래 키로 걸 수 없어, 무결성을 애플리케이션 코드가 떠안게 된다. 같은 저장소에 두면 판정과 근거를 한 트랜잭션에서 쓰고 제약으로 강제할 수 있다. 저장소를 하나로 줄이는 편이 10주 일정에서 운영 부담도 작다.

색인 종류와 파라미터(HNSW·IVFFlat 등)는 색인 규모가 나오기 전에는 고를 수 없으므로 측정 후 결정한다.

접속 설정의 키 이름은 리포의 .env.example에 있다. 실제 값은 커밋하지 않는다.

검토 영역

아래 세 영역은 아직 확정하지 않았다.

영역	검토 사항
클라이언트	경기 직전 사용이 많아 모바일 접근성이 중요하다. 영상 업로드도 단말에서 이뤄진다
API 서버	에이전트 호출이 수 초 걸리므로 그동안 다른 요청을 막지 않아야 한다
알림	확정·마감·색인 완료 발송 경로가 필요하다

〔확인 필요: 클라이언트·API 서버·알림 기술 확정〕 확정되면 위 표와 같은 형식으로 선정 근거와 함께 이 절에 옮긴다.

영상 처리 도구도 미확정이다. 자세 추정 도구의 후보 비교는 제 8 장 주차별 표의 1주차 작업(정어진)이며, 이 도구가 넘겨줄 프레임 추출 설계는 제 4 장 2절에 있다.

종목 추가는 코드 변경 없이

제 2 장의 NFR-05를 만족하려면 종목별 포지션과 스탯 항목이 코드에 박혀 있으면 안 된다. 종목이 늘어날 때마다 배포가 필요해지기 때문이다. 이 값들은 데이터로 정의하고, 코드는 정의를 읽어 동작하도록 설계한다. 이 결정이 데이터 모델에 그대로 반영된다.

3) 데이터 모델

주요 엔터티

엔터티	설명
사용자	계정 정보. 역할은 여기에 두지 않는다
팀	경기를 주최하는 단위
구장	장소와 좌표. 거리 계산의 기준
공고	종목·일시·구장·포지션별 모집 인원·요구 실력대·상태
지원	공고에 대한 지원 기록
참여	확정된 참여자와 그 경기에서의 역할
경기 기록	종료된 경기의 참여 결과
영상	경기 영상 파일과 처리 상태
장면 색인	시각 구간, 상황 요약, 플레이 이벤트, 인물과 식별 신뢰도
검증 판정	판정 결과와 근거가 된 장면
스탯 정의	종목·포지션별 스탯 항목의 정의
스탯	사용자별 현재 스탯 값
스탯 변동	스탯이 바뀐 이력과 그 근거
신뢰도	검증 이력에서 산출한 지표
노쇼 이력	사전 취소·지각 취소·노쇼 구분 기록

설계상 주의한 지점

역할은 사용자가 아니라 참여에 붙는다. 2장에서 정의한 대로 한 사람이 경기에 따라 운영자이기도 용병이기도 하다. 역할을 계정 속성으로 두면 이 경우를 표현할 수 없다.

스탯 항목은 데이터다. 스탯 정의를 별도 엔터티로 두어 종목 추가 시 코드를 고치지 않는다. 스탯 값은 정의를 참조하는 형태로 저장한다.

스탯은 현재값과 변동 이력을 분리한다. 제 6 장의 검증 보정은 기존 값을 덮어쓰는 동작이다. 이력이 없으면 왜 그 값이 됐는지 설명할 수 없고, 잘못된 보정을 되돌릴 수도 없다. 변동마다 근거가 된 경기와 검증 결과를 함께 남긴다.

판정은 근거 장면과 함께 저장한다. 제 6 장의 검증은 근거 없이 성립하지 않는다. 판정 레코드가 근거 장면을 참조하지 않으면 저장 단계에서 거부한다. 이용자가 이의를 제기했을 때 무엇을 보고 판정했는지 되짚을 수 있어야 한다.

4) 화면 설계

주요 화면

화면	사용자	내용
공고 목록	용병	조건에 맞는 공고 탐색
공고 상세	용병	조건 확인과 지원
공고 등록	운영자	모집 조건 입력
후보 추천	운영자	순위·근거·신뢰도 등급 확인
참여자 확정	운영자	확정과 대기자 관리
선수 프로필	공통	스탯 카드, 신뢰도, 근거 장면 연결
영상 업로드	운영자	경기 영상 등록과 색인 진행 상태 확인
근거 확인	공통	스탯 항목별 근거 장면과 재생 위치
내 경기	공통	예정·종료 경기와 처리할 일

화면 흐름

운영자 — 공고 등록 → (마감) → 후보 추천 → 참여자 확정 → (경기 종료) → 기록 입력 → 영상 업로드
용병 — 공고 목록 → 공고 상세 → 지원 → (확정 알림) → (경기 종료) → (색인 완료 알림) → 프로필에서 스탯과 근거 확인

두 흐름 모두 경기 종료 뒤 영상으로 수렴한다. 영상이 색인돼야 검증이 돌고, 검증이 돌아야 다음 매칭의 순위가 정확해진다.

표시 원칙

화면 설계에서 지켜야 할 네 가지는 앞 장의 설계 판단에서 나온다.

원칙	근거
미검증 스탯은 확정값과 구분해 표시한다	6장 — 자기 신고값을 검증된 값처럼 보이게 하지 않는다
검증된 스탯에는 근거 장면을 연결한다	6장 — 판정은 출처와 함께여야 확인 가능하다
조건이 완화된 추천은 완화 사실을 함께 표시한다	5장 — 무엇을 양보했는지 운영자가 알아야 한다
신뢰도와 실력은 분리해 표시한다	6장 — 신뢰도는 실력이 높다는 뜻이 아니다

〔확인 필요: 화면별 상세 설계와 시안〕