React 19 + PWA 기반 동아리 전용 그룹웨어
yANUs는 동아리 운영에 필요한 모든 기능을 하나로 묶은 그룹웨어입니다. 출퇴근 관리, 팀 채팅, 일정 관리, 파일 공유, AI 어시스턴트를 웹/모바일 어디서든 사용할 수 있습니다.
- PWA 지원 — 모바일 홈 화면에 앱처럼 설치 가능
- 다크 테마 기본 적용
- FSD(Feature-Sliced Design) 아키텍처 기반 구조화
| 기능 | 설명 |
|---|---|
| 대시보드 | 오늘의 일정·채팅·출퇴근 현황을 한눈에 확인 |
| 업무 채팅 | 실시간 채널 및 다이렉트 메시지 |
| 캘린더 | FullCalendar 기반 일정 관리 |
| 출퇴근 | 출근·퇴근 기록, 근무 시간 시각화, 개인 근무 요일 설정 |
| 파일 드라이브 | 팀 파일·폴더 공유 |
| AI 챗봇 | 파일 드라이브 기반 질의응답 (Ollama 호환 API) |
| Sticky 위젯 | 모든 화면 우측 하단에서 채팅·챗봇 바로 접근 |
| 분류 | 기술 |
|---|---|
| UI | React 19 |
| 언어 | TypeScript 5 |
| 번들러 | Vite 7 |
| 라우팅 | React Router v7 |
| 캘린더 | FullCalendar 6 |
| 애니메이션 | Framer Motion 12 |
| 아이콘 | Lucide React |
| 마크다운 | react-markdown |
| 스타일 | CSS (레이어별 모듈) |
| PWA | vite-plugin-pwa |
| 테스트 | Vitest + React Testing Library |
| 배포 | Vercel |
이 프로젝트는 FSD(Feature-Sliced Design) 패턴을 따릅니다. UI 중심이 아닌 기능 중심으로 코드를 분리하여 유지보수성과 확장성을 높입니다.
app
└─ Providers, Router 초기화
pages
└─ 라우트 단위 화면 (비즈니스 로직 없음)
widgets
└─ 화면을 구성하는 독립적인 블록
features
└─ 실제 기능 로직, 상태 관리, API 호출
entities
└─ 도메인 모델, 타입 정의
shared
└─ 공통 UI, API 클라이언트, 유틸 함수
- 상위 레이어만 하위 레이어를 import할 수 있습니다.
pages→widgets→features→entities→shared- 동일 레이어 간 직접 의존 금지, 순환 참조 금지
src/
├── app/
│ ├── providers.tsx # 전역 Provider 조합
│ ├── router.tsx # BrowserRouter + Routes
│ └── index.ts
│
├── pages/
│ ├── dashboard/ # 대시보드
│ ├── chat/ # 채팅
│ ├── calendar/ # 캘린더
│ ├── attendance/ # 출퇴근
│ ├── drive/ # 파일 드라이브
│ ├── ai-chat/ # AI 챗봇
│ ├── members/ # 멤버 목록
│ └── settings/ # 설정
│
├── widgets/
│ ├── Layout/ # 전체 레이아웃 (사이드바, GNB)
│ └── StickyChatWidget/ # 우측 하단 Sticky 위젯
│
├── features/
│ ├── auth/model/ # 앱 전역 사용자 상태 (AppProvider)
│ ├── chat/model/ # 채팅 상태 (ChatProvider)
│ ├── calendar/model/ # 캘린더 이벤트 상태 (EventsProvider)
│ ├── tasks/model/ # 할일 상태 (TasksProvider)
│ ├── attendance/
│ │ ├── model/ # useWorkSession 훅 (출퇴근 로직)
│ │ └── ui/ # AnimatedClockRing, ClockTimePicker 등
│ └── ai-chat/api/ # aiClient (Ollama API 통신 추상화)
│
├── entities/
│ ├── user/model/types.ts
│ ├── message/model/types.ts
│ ├── task/model/types.ts
│ └── event/model/types.ts
│
├── shared/
│ ├── api/baseClient.ts # fetch 추상화, ApiError 처리
│ ├── lib/date.ts # 날짜 유틸 함수
│ └── ui/TimeInput/ # 공통 시간 입력 컴포넌트
│
└── test/setup.ts # Vitest 전역 설정
- Node.js 20+
- npm
# 의존성 설치
npm install
# 개발 서버 실행 (http://localhost:5173)
npm run dev
# 프로덕션 빌드
npm run build
# 빌드 결과 미리보기
npm run preview프로젝트 루트에 .env 파일을 생성하고 아래 변수를 설정합니다.
# AI 챗봇 API 서버 주소 (Ollama 호환 서버)
VITE_AI_API_URL=http://localhost:11434
# 사용할 AI 모델명
VITE_AI_API_MODEL=llama3.1
# 백엔드 API Base URL
VITE_API_BASE_URL=http://localhost:8080
# true 설정 시 Mock API 사용 (백엔드 없이 개발 가능)
VITE_USE_MOCK=true
VITE_AI_API_URL을 설정하지 않으면 AI 챗봇은 설정 안내 메시지를 표시합니다.
이 프로젝트는 TDD(Test-Driven Development) 방식으로 개발됩니다. 기능 코드 작성 전 반드시 테스트를 먼저 작성합니다.
# 테스트 실행 (watch 모드)
npm run test
# 테스트 단일 실행 (CI용)
npm run test:run- 117개 테스트, 14개 테스트 파일
- 단위 테스트: 각 feature/shared 레이어 로직
- 컴포넌트 테스트: React Testing Library
features/ai-chat/api/ — aiClient 통신 로직
features/attendance/model/ — useWorkSession 훅
features/auth/model/ — AppProvider 상태
features/chat/model/ — ChatProvider 상태
features/calendar/model/ — EventsProvider 상태
features/tasks/model/ — TasksProvider 상태
widgets/Layout/ — 레이아웃 렌더링
widgets/StickyChatWidget/ — Sticky 위젯 동작
shared/lib/ — 날짜 유틸 함수
app/ — Provider 조합
develop, main 브랜치 push 및 PR 시 자동 실행됩니다.
테스트 실행 (npm run test:run)
↓
빌드 검증 (npm run build)
| 브랜치 | 배포 환경 |
|---|---|
develop |
Preview |
main |
Production |
Vercel 배포는
VERCEL_TOKENsecret 설정 시 활성화됩니다. secret이 없으면 CD 잡은 자동으로 건너뜁니다.
GitHub Flow 기반으로 운영됩니다.
main ← 프로덕션 (Vercel 자동 배포)
└─ develop ← 통합 개발 (PR 후 main에 머지)
├─ feature/<scope>-<작업명>
├─ fix/<scope>-<버그명>
└─ hotfix/<이슈명> ← main에서 분기
AngularJS Commit Convention을 따릅니다.
<type>(<scope>): <한글 설명>
feat(dashboard): 출퇴근 상태 카드 추가
fix(auth): 로그인 리다이렉트 버그 수정
test(ai-chat): aiClient 에러 케이스 테스트 추가
| type | 설명 |
|---|---|
feat |
새 기능 |
fix |
버그 수정 |
test |
테스트 추가·수정 |
refactor |
리팩토링 |
chore |
빌드·설정 변경 |
docs |
문서 수정 |