soccerhelper

아마추어 축구팀의 팀원·일정·참석·라인업·모집·경기 기록을 하나의 흐름으로 관리하는 웹·모바일 MVP입니다.

전형주 포트폴리오 · 제품 요구사항 · 로드맵 · 변경 이력

구분	내용
해결하려는 문제	메신저·스프레드시트·메모에 흩어진 경기 준비와 기록을 같은 데이터로 연결
주요 사용자	팀 운영자, 팀원, 모집글을 확인하는 참가자
제품 단계	웹·모바일 MVP 개발 및 배포 준비; 운영 규모·사용자 수·정식 출시를 성과로 주장하지 않음
기술	Next.js, Expo/React Native, TypeScript, Supabase, pnpm workspace
코드 검토 시작점	apps/web → supabase/migrations → apps/mobile → scripts·tests·reports

1. 제품 흐름과 구현 범위

팀 생성·가입 → 경기 일정 → 참석 확인 → 모집 → 스쿼드·라인업 → 라이브 스코어·결과 기록 순서로 설계했습니다.

영역	저장소가 다루는 기능
계정	이메일 가입·로그인, Google OAuth, 프로필의 포지션·레벨·지역
팀	팀 생성, 초대코드 가입, 멤버 목록, owner/admin/member 역할
경기	일정·장소·정원·포맷, 참석 상태, 라인업·라이브 스코어
모집	모집글 생성·목록·상세, 모집 상태 필터, 운영자 제어
스쿼드	팀별 포지션·레벨 override, 편집, 스키마 미적용 시 조회 전용 fallback
데이터 동기화	경기·참석·기록의 Supabase Realtime 반영
접근 제어	Supabase RLS, 팀 권한 정책과 과도 권한·재귀 정책 보완 migration

위 표는 구현·설계 범위를 안내합니다. 각 기능의 최신 작동 여부는 해당 revision에서 별도로 재현해야 하며, 기능 목록 자체가 운영 검증 결과는 아닙니다.

2. 구조와 읽는 순서

경로	역할	검토 포인트
apps/web/	Next.js 웹 앱	운영 흐름, 화면 상태, 입력·권한·오류 처리
apps/mobile/	Expo/React Native 앱	모바일 진입점, 화면과 인증 흐름
packages/shared/	workspace 공유 코드	웹·모바일 간 공유 경계
supabase/migrations/	DB 스키마·RLS 변경	역할과 데이터 접근 조건, 적용 순서
supabase/manual/	수동 운영 SQL	운영 대상·부작용 확인 후 사용
scripts/, tests/	QA·운영 명령과 테스트	실행 전제, 실제 검사 대상, 실패 처리
reports/, output/	보고서·산출물	생성일·commit·명령·환경이 맞는지 확인
spec/	제품·배포·베타 운영 문서	요구사항부터 인수인계까지
docs/, ROADMAP.md, review_smart_lineup.md	설계·진행·검토 기록	구현 코드와 문서의 일치 여부

AGENTS.md, MEMORY.md, SOUL.md, USER.md, memory/, skills/는 기존 개발 보조 맥락이며 제품 진입점이 아닙니다. .vscode/는 편집기 설정입니다. workspace·빌드·문서 링크를 유지하기 위해 소스 경로를 임의로 옮기지 않았습니다.

3. 로컬 개발 시작

필요한 것은 Node.js 환경, pnpm 9.15.0(package.json), 별도의 개발용 Supabase 프로젝트입니다. DB·OAuth·지도/주소 연동에 필요한 설정은 환경 변수 매트릭스를 먼저 확인합니다.

git clone https://github.com/Alpenj/soccerhelper.git
cd soccerhelper
pnpm --version
pnpm install --frozen-lockfile

환경 파일은 기존 파일이 없는 경우에만 예시를 복사해 작성합니다.

대상	예시 파일	로컬 파일
웹	apps/web/.env.local.example	apps/web/.env.local
모바일	apps/mobile/.env.example	apps/mobile/.env

웹 예시에는 NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, KAKAO_REST_API_KEY, JUSO_CONFM_KEY가 있습니다. 실제 값은 이 README에 넣지 않습니다. 운영 데이터베이스와 분리한 개발 DB에서 migrations와 인증 설정을 확인한 뒤 실행합니다.

# 서로 다른 터미널에서 필요한 앱만 실행
pnpm dev:web
pnpm dev:mobile

전체 저장소의 package.json에 있는 private: true는 패키지 게시 설정입니다. GitHub 저장소 공개 여부와는 다른 항목입니다.

4. 품질 검증과 한계

package.json에 정의된 명령은 다음과 같습니다. 명령이 있다는 것과 검사가 통과했다는 것을 구분합니다.

목적	명령
타입 검사	pnpm typecheck
lint	pnpm lint
환경 설정 검사	pnpm ops:check-env
단위·통합·안정성	pnpm qa:phase1:unit, pnpm qa:phase2:integration, pnpm qa:phase3:stability
성능·보안·접근성	pnpm qa:phase4:perf, pnpm qa:phase5:security, pnpm qa:phase5:a11y
요구사항 추적·전체 QA	pnpm qa:rtm, pnpm qa:all
웹 빌드	pnpm --filter web build

모바일 화면의 기존 E2E 진입점:

cd apps/web
pnpm exec playwright test tests/e2e/mobile-smoke.spec.mjs --config=playwright.config.mjs

브라우저·테스트용 계정·서버 등 실행 전제는 설정 파일과 테스트를 확인합니다. 환경 구성이 필요한 모든 QA를 채용 검토자에게 필수 작업으로 요구하지 않습니다. 코드·migration·보고서만으로도 검토를 시작할 수 있습니다.

기존 README에는 웹 빌드 통과와 모바일 주요 상호작용 점검, 그리고 any·hooks 관련 lint 부채가 기록돼 있었습니다. 이 문서 정리에서는 재실행하지 않았으므로 최신 통과 상태로 갱신하지 않았습니다. 보고서는 해당 commit·환경·검사 범위와 함께 읽습니다. 베타 운영 시간 절감·이용자 수 같은 효과는 측정 기록이 생긴 뒤 추가합니다.

5. 배포·베타 운영 자료

단계	문서·자료
제품과 실행 계획	PRD, PLAYBOOK, TICKETS, 개발 프롬프트 기록
환경 분리	PRODUCTION_ENV_MATRIX — 개발/운영 DB와 배포 플랫폼 Secret 분리
인증	GOOGLE_OAUTH_PRODUCTION_CHECKLIST — 도메인·callback·redirect 설정
베타 점검	BETA_OPERATIONS_CHECKLIST
모집·피드백	모집 문구, 피드백 양식
앱 배포	BETA_APP_DISTRIBUTION_PLAYBOOK — APK/TestFlight 준비
용량·운영	DB_CAPACITY_PLAN, 운영 SQL

웹은 apps/web, 모바일은 apps/mobile/app.json·eas.json을 기준으로 별도로 배포합니다. DB에는 003_fix_team_rls_logic.sql, 005_team_members_squad_fields.sql, 007_security_advisor_policy_hardening.sql, 008_capacity_index_and_archiving.sql을 포함한 migration 적용 순서를 확인합니다. 운영 DB 변경이나 아카이브는 README 열람만으로 실행하지 않습니다.

기존 베타 계획은 1020명·12주 운영 → Critical/High 이슈 검토 → 종료 기준 충족 후 다음 단계입니다. 이는 계획이지 실제 운영 실적이 아닙니다. DB 모니터링·아카이브·p95 추적도 같은 원칙으로 기록합니다.

6. 기여와 공개 기준

개인 기여는 commit과 연결된 요구사항·수정 코드·테스트로 확인합니다. 문서 작성, 생성된 코드 초안, 실제 구현과 운영 검증을 한 항목으로 뭉뚱그리지 않습니다.

연락·경력은 포트폴리오에서 확인할 수 있습니다. 비밀키, 실제 계정, 운영 DB 데이터, 사용자 개인정보는 예시나 보고서에 추가하지 않습니다. 기존 파일·이력 전체의 보안 감사가 완료됐다는 의미는 아닙니다.

문서 구조 점검: 2026-09-05. 소스·DB·의존성·배포 설정은 변경하지 않았습니다.