AICS Team Project Client

KD/AICS 강의의 팀 프로젝트 운영을 돕는 클라이언트입니다. 첫 앱은 OOP 강의용 apps/oop입니다. 다른 강의 앱은 실제 요구가 생길 때 apps/{course} 아래에 추가합니다.

서비스 범위

이 저장소는 LMS를 대체하지 않습니다. 강의 안에서 팀 프로젝트를 운영하는 데 필요한 흐름만 다룹니다.

Course → Section → Team → Project → Milestone → Submission → Review

저장소 구조

apps/
  oop/
packages/
  core/
  api-client/
  design-system/
configs/
  typescript/
.agent/

시작하기

Node.js 22 이상과 pnpm 10을 사용합니다.

pnpm install
pnpm dev

검증

pnpm lint
pnpm build

OOP 배포

OOP 프론트엔드는 Cloudflare Pages에 배포합니다. 운영 빌드는 apps/oop/.env.production에 설정한 VITE_API_BASE_URL을 사용합니다.

pnpm --filter @aics/oop run deploy

배포 계정은 KGU 팀 프로젝트 Cloudflare 계정 a6b2c7849807daa1d50fd035cb3e3e15만 사용합니다. 로컬에서는 Wrangler의 kgu-oop 프로필로 로그인해야 합니다.

Pages 프로젝트 이름은 aics-oop, 운영 브랜치는 main입니다. 커스텀 도메인은 team-project.kgudevelopers.monster를 사용하며, DNS 제공자에서 아래 CNAME을 등록합니다. Cloudflare Pages의 Custom domains에 도메인을 먼저 추가한 뒤 DNS를 설정해야 합니다.

Type: CNAME
Name: team-project
Target: aics-oop.pages.dev

백엔드 CORS 허용 목록에는 아래 운영 Origin을 추가해야 합니다.

https://team-project.kgudevelopers.monster

기존 Workers Static Assets 배포는 롤백용으로 유지합니다.

pnpm --filter @aics/oop run deploy:worker:dry-run
pnpm --filter @aics/oop run deploy:worker

Pages는 최상위 404.html이 없는 정적 앱을 SPA로 처리합니다. TanStack Router 경로에 직접 접속해도 index.html을 반환합니다. Workers 롤백 배포에서는 apps/oop/wrangler.worker.jsonc의 SPA fallback 설정을 사용합니다.

학생 공통 푸터의 문의하기 링크는 공개 빌드 설정 VITE_OPEN_CHAT_URL로 재정의할 수 있습니다. 설정이 없으면 확인된 카카오 오픈채팅 URL을 기본으로 사용하며, 빈 값 또는 잘못된 URL을 명시하면 비활성 텍스트만 표시합니다. 이 값은 브라우저에 공개되므로 비밀이나 자격 증명을 넣지 않습니다.

작업 규칙

• 작업 계획은 Notion 티켓을 기준으로 합니다.
• 브랜치 이름은 <type>/KD3-<number> 형식입니다. 예: chore/KD3-129
• PR 제목은 [KD3-<number>] 작업명 형식입니다.

개발 API 모드

기본 pnpm dev는 MSW 데모 모드입니다. 실서버 연결은 apps/oop/.env.local에 VITE_ENABLE_MSW=false, VITE_API_BASE_URL= (빈 값), VITE_API_PROXY_TARGET=<개발 API origin>을 지정하고 재시작합니다. Vite는 개발 중에만 API 요청을 프록시합니다. 운영 빌드는 .env.production에 지정된 API 서버를 직접 호출합니다. 실서버 검증은 백엔드 CORS가 허용한 http://localhost:5173에서 진행합니다. 로그인/갱신 응답의 역할과 /users/me로 세션을 복원하며 토큰은 HttpOnly 쿠키로 관리합니다. 실서버 모드는 아직 전환되지 않은 화면 API까지 지원한다는 의미가 아닙니다. 운영 화면과 API의 호스트가 다르므로 백엔드와 CSRF 토큰 전달 계약을 확인해야 합니다. 운영 도메인의 로그인·갱신·로그아웃은 별도 검증이 필요합니다. MSW의 기존 화면 fixture 문맥 보충은 mocks/resolveDemoCurrentUser에 한정되며 실서버 데이터에는 적용되지 않습니다.

/users/me.globalRole은 ADMIN | USER이고 로그인·갱신의 role은 ADMIN | STUDENT | ASSISTANT입니다. 정상 조교는 USER + ASSISTANT이므로 로그인 역할을 보존하되 두 응답의 조합이 모순되면 세션 복원을 거부합니다. 이 계약은 서버 역할 계산, /users/me 구현, 2026-09-05 성공 배포를 기준으로 합니다. 배포 이력은 현재 서버의 가용성이나 실제 계정 검증을 대신하지 않습니다.

MSW는 새 탭에서도 세션을 복원할 수 있도록 데모 계정 ID와 토큰 세대 번호만 localStorage에 공유합니다. 실제 인증 토큰은 저장하지 않습니다.