Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
96f8127
chore: Flutter 앱을 apps/mobile로 이동
beomq Nov 2, 2026
07371bd
chore: 앱 뼈대와 작업 규칙 추가
beomq Nov 2, 2026
e52ba32
chore: 앱 디자인 토큰 파일 추가와 getIt 위치 정리
beomq Nov 2, 2026
58f78e9
chore: 웹(React + TypeScript + Vite) 초기 세팅
beomq Nov 2, 2026
6438ad3
docs: 작업 흐름·앱/웹 구조·디자인 토큰 규칙 문서화
beomq Nov 2, 2026
839da26
docs: PR 체크리스트와 템플릿 체크박스 추가
beomq Nov 2, 2026
0b1b6c1
docs: 그림으로 보는 전체 구조 문서 추가
beomq Nov 2, 2026
ec71c73
fix: 웹 env를 shared/config로 옮기고 빌드 시 환경값을 검사
beomq Nov 2, 2026
e24e5e3
docs: squash 제목 규칙과 getIt 위치·토큰 예외·사전 공유 순서 정정
beomq Nov 2, 2026
009de13
feat: Android·iOS dev/prod 네이티브 flavor 추가
beomq Nov 2, 2026
bb21a29
chore: import 방향 규칙을 린트로 강제
beomq Nov 2, 2026
0faf87e
chore: GitHub Actions PR 검사 추가
beomq Nov 2, 2026
28ff603
docs: AGENTS.md를 색인으로 줄이고 flavor·린트·CI를 반영
beomq Nov 2, 2026
e07e3aa
docs: flavor 사용법을 문서에 추가하고 오래된 CI 표기 정정
beomq Nov 2, 2026
9a9db85
chore: env 테스트 이름을 한국어 문장으로 맞춤
beomq Nov 2, 2026
22cabea
fix: import 검사기가 문서 2절의 방향 규칙을 모두 검사하도록 보완
beomq Nov 3, 2026
e2fd440
docs: Xcode 직접 빌드 때 flavor가 정해지는 방식 정정
beomq Nov 3, 2026
1fffdf2
fix: 기본 글자색이 textPrimary 토큰을 따르도록 연결
beomq Nov 3, 2026
b70208f
fix: import 검사기가 조건부·여러 줄 import와 models의 flutter import까지 검사
beomq Nov 3, 2026
0622b6d
refactor: AppEnv의 flavor 매핑을 분리해 prod 경로도 테스트
beomq Nov 3, 2026
de04fef
feat: 웹에 없는 경로 안내 페이지 추가
beomq Nov 3, 2026
f9e8102
docs: 검증 명령을 CI와 맞추고 토큰 단계 추가 규칙 정리
beomq Nov 3, 2026
c7b2ccf
refactor: import 검사기가 정규식 대신 Dart 파서로 지시문을 읽도록 변경
beomq Nov 3, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
## 변경

<!-- 무엇을 왜 바꿨는지. Jira: JECT-000 -->

## 검증

<!-- 기기·브라우저, 시나리오, 결과를 한 줄씩 -->

## UI 캡처

<!-- 화면이 바뀌었으면 앱(바꾼 플랫폼)·웹(모바일 폭) 캡처. 없으면 "해당 없음" -->

## 호환성·주의

<!-- API 계약 / bridge 버전 / 구버전 앱 영향 / 공통 변경(DI·모델·라우팅·네이티브·bridge·토큰·의존성) 사전 공유 여부 -->

## 리뷰 순서

<!-- 1. 진입점 → 2. 상태·요청 → 3. 실패 방어 → 4. 테스트 순으로 읽을 파일 경로 -->

## 새 문구

<!-- 이 PR에서 추가·변경한 사용자 문구를 모아 적는다 (톤·용어 확인용). 없으면 "해당 없음" -->

## 작성자 체크 (docs/pr-checklist.md A절)

- [ ] A1 형식: 브랜치·커밋·PR 제목 규칙, PR 하나 = Task 하나
- [ ] A2 자동 검증: 앱 format·analyze·check_imports·test / 웹 format·lint·typecheck·test·build·build:dev 전부 통과 (앱·웹 파일이 바뀐 PR이면 CI도 같은 검사)
- [ ] A3 구조: 파일이 규칙 위치에 있고, features→app·다른 기능 내부 import 없음, 미래용 코드 없음
- [ ] A4 명령: 쓰기 요청은 버튼→ViewModel, 중복 실행 방지, 서버 판단을 화면에서 확정하지 않음 (해당 시)
- [ ] A5 화면 상태: 로딩·빈·실패·정상 전부 있고 공통 위젯 사용 (해당 시)
- [ ] A6 토큰: hex·`Colors.*`·숫자 크기 없음. 토큰 변경은 앱·웹·문서 함께
- [ ] A7 재사용: 공통 위젯이 있으면 그것을 씀
- [ ] A8 문구: 오류 문구 "무엇이+어떻게", 버튼은 동사, 용어 통일, 탭 영역 44
- [ ] A9 데이터: 토큰·개인정보가 로그·URL·분석·prefs에 없음. env·routes 한 곳
- [ ] A10 테스트: 같은 경로, 4케이스, 뒤집으면 실패, 문구 고정·고정 sleep 없음
- [ ] A11 생성 파일·lock 같이 커밋 (해당 시)
- [ ] A12 수동 확인: 시나리오 실행, 캡처 첨부
- [ ] A13 사전 공유 (공통 변경 시)

## 리뷰어 체크 (docs/pr-checklist.md B절)

- [ ] B1 진입점 → B2 상태·요청 → B3 실패 방어 → B4 테스트 순으로 읽음
- [ ] B5 일관성: 기존 비슷한 화면과 여백·빈 화면·문구 톤이 같음
- [ ] B6 범위: 관계없는 변경이 섞이지 않음
- [ ] 코멘트는 `[must]`/`[nit]` 접두사와 근거 절 번호
46 changes: 46 additions & 0 deletions .github/workflows/mobile.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: mobile

on:
pull_request:
paths:
- "apps/mobile/**"
- ".github/workflows/mobile.yml"
push:
branches: [main, develop]
paths:
- "apps/mobile/**"
- ".github/workflows/mobile.yml"

concurrency:
group: mobile-${{ github.ref }}
cancel-in-progress: true

jobs:
check:
runs-on: ubuntu-latest
defaults:
run:
working-directory: apps/mobile
steps:
- uses: actions/checkout@v5

- name: Flutter 버전을 .fvmrc에서 읽기
id: fvmrc
run: echo "version=$(jq -r .flutter .fvmrc)" >> "$GITHUB_OUTPUT"

- uses: subosito/flutter-action@v2
with:
flutter-version: ${{ steps.fvmrc.outputs.version }}
channel: stable
cache: true

- run: flutter pub get
- run: dart format --set-exit-if-changed --output=none lib test tool
- run: flutter analyze
- run: dart run tool/check_imports.dart
- run: flutter test

- name: 생성 파일이 최신인지 (build_runner 후 diff 없어야 함)
run: |
dart run build_runner build --delete-conflicting-outputs
git diff --exit-code
43 changes: 43 additions & 0 deletions .github/workflows/web.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: web

on:
pull_request:
paths:
- "apps/web/**"
- ".github/workflows/web.yml"
push:
branches: [main, develop]
paths:
- "apps/web/**"
- ".github/workflows/web.yml"

concurrency:
group: web-${{ github.ref }}
cancel-in-progress: true

jobs:
check:
runs-on: ubuntu-latest
defaults:
run:
working-directory: apps/web
steps:
- uses: actions/checkout@v5

- uses: pnpm/action-setup@v4
with:
package_json_file: apps/web/package.json

- uses: actions/setup-node@v4
with:
node-version-file: apps/web/.nvmrc
cache: pnpm
cache-dependency-path: apps/web/pnpm-lock.yaml

- run: pnpm install --frozen-lockfile
- run: pnpm format:check
- run: pnpm lint
- run: pnpm typecheck
- run: pnpm test
- run: pnpm build
- run: pnpm build:dev
51 changes: 2 additions & 49 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,51 +1,4 @@
# Miscellaneous
*.class
*.log
*.pyc
*.swp
.DS_Store
.atom/
.build/
.buildlog/
.history
.svn/
.swiftpm/
migrate_working_dir/

# IntelliJ related
*.iml
*.ipr
*.iws
.idea/

# The .vscode folder contains launch configuration and tasks you configure in
# VS Code which you may wish to be included in version control, so this line
# is commented out by default.
#.vscode/

# Flutter/Dart/Pub related
**/doc/api/
**/ios/Flutter/.last_build_id
.dart_tool/
.flutter-plugins-dependencies
.pub-cache/
.pub/
/build/
/coverage/

# Symbolication related
app.*.symbols

# Obfuscation related
app.*.map.json

# Android Studio will place build artifacts here
/android/app/debug
/android/app/profile
/android/app/release

# Widget Preview related
.widget_preview/

# FVM Version Cache
.fvm/
*.iml
.omo/
59 changes: 59 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# highfive-5th-Client 작업 규칙

사람과 코딩 에이전트가 같이 보는 입구다. 여기에는 **항상 지킬 것**과 문서 지도만 두고, 규칙의 본문은 `docs/` 한 곳에만 둔다. 규칙을 바꿀 때는 `docs/`를 고치고 여기는 링크만 유지한다.

| 알고 싶은 것 | 문서 |
| --- | --- |
| 전체를 그림으로 한 번에 (처음 읽을 때) | [docs/overview.md](./docs/overview.md) |
| 일을 어떤 순서로 하나 (Jira → 브랜치 → 구현 순서 → 검증 → PR → 리뷰 → 릴리스) | [docs/workflow.md](./docs/workflow.md) |
| 앱 폴더에 어떤 파일이 들어가고 누가 누구를 import하나, dev/prod flavor | [docs/mobile-architecture.md](./docs/mobile-architecture.md) |
| 웹 폴더 구조·의존성·bridge·환경 | [docs/web-architecture.md](./docs/web-architecture.md) |
| 색·간격·글자 크기 값과 바꾸는 절차 | [docs/design-tokens.md](./docs/design-tokens.md) |
| PR 올리기 전·리뷰할 때 무엇을 왜 보나 | [docs/pr-checklist.md](./docs/pr-checklist.md) |

## 저장소와 명령

```
apps/mobile/ Flutter 앱. 명령은 이 폴더에서 `fvm flutter ...`
apps/web/ React + TypeScript + Vite. 명령은 이 폴더에서 `pnpm ...`
docs/ 규칙 문서. BE API 명세는 docs/api/ 에 둔다
.github/ PR 템플릿, CI (mobile.yml · web.yml — 앱·웹 파일이 바뀐 PR마다 아래 검증을 돌린다)
```

| | 앱 (`apps/mobile`) | 웹 (`apps/web`) |
| --- | --- | --- |
| 설치 | `fvm install && fvm flutter pub get` | `corepack enable && pnpm install` |
| 실행 | `fvm flutter run --flavor dev` (`prod`) | `pnpm dev` |
| 포맷 고치기 | `fvm dart format lib test tool` | `pnpm format` |
| 포맷 검사 (CI와 같음) | `fvm dart format --set-exit-if-changed --output=none lib test tool` | `pnpm format:check` |
| 분석·린트 | `fvm flutter analyze && fvm dart run tool/check_imports.dart` | `pnpm lint && pnpm typecheck` |
| 테스트 | `fvm flutter test` | `pnpm test` |
| 빌드 | `fvm flutter build apk\|ipa --flavor prod` | `pnpm build` (prod) / `pnpm build:dev` |
| 코드 생성 | `fvm dart run build_runner build --delete-conflicting-outputs` | - |

Flutter 버전은 `apps/mobile/.fvmrc`, Node는 `apps/web/.nvmrc`·`packageManager`로 고정한다. CI도 같은 파일을 읽는다. 한글 경로에서 `flutter analyze`가 크래시하면 영문 경로에 복사해서 돌린다.

## 항상 지킬 것

1. feature-first. 실제 구현하는 기능부터 만들고 빈 폴더·UseCase·미래용 인터페이스를 미리 만들지 않는다. → [mobile 1절](./docs/mobile-architecture.md#1-폴더와-들어가는-파일)
2. import는 `app → features → core/shared` 한 방향. 웹은 ESLint, 앱은 `tool/check_imports.dart`가 막는다. → [mobile 2절](./docs/mobile-architecture.md#2-의존성-방향) · [web 2절](./docs/web-architecture.md#2-의존성-방향)
3. View는 표시·입력·이동, ViewModel은 상태·명령, Repository는 변환·캐시, Service는 호출만. `getIt`은 `app/di.dart`와 연결 Provider에서만. → [mobile 3절](./docs/mobile-architecture.md#3-계층-책임)
4. 신청·예매·결제 같은 쓰기 명령은 버튼 → ViewModel 메서드로만, 중복 실행을 막고, 권한·재고·가격은 서버가 최종 판단. → [mobile 4절](./docs/mobile-architecture.md#4-상태를-어디에-두는가)
5. 로그아웃·계정 전환 시 세션·캐시·소켓·보안 저장소를 정리하고 이전 세션의 늦은 응답은 버린다. → [mobile 4절](./docs/mobile-architecture.md#4-상태를-어디에-두는가)
6. 토큰·개인정보는 로그·URL·prefs·분석 이벤트에 넣지 않는다. 인증 정보는 `FlutterSecureStorage`에만. → [checklist A9](./docs/pr-checklist.md#a9-데이터보안설정-위치)
7. 색·간격·모서리·글자 크기는 토큰만 쓴다. 토큰 변경은 앱·웹·문서를 한 PR에서. → [design-tokens](./docs/design-tokens.md)
8. 환경값은 앱 `app/env.dart`, 웹 `shared/config/env.ts`에서만 읽는다. 경로 문자열은 `AppRoutes`/`routes.ts`에만. 앱 명령에는 항상 `--flavor dev|prod`를 붙인다. → [mobile 10절](./docs/mobile-architecture.md#10-환경flavor)
9. 생성 파일(`*.g.dart`, `*.freezed.dart`)은 손대지 않고 커밋한다. `any`, `// ignore:`, `eslint-disable`로 오류를 숨기지 않는다.
10. 테스트는 앱 `test/`에 `lib/` 미러, 웹은 파일 옆. 문구 고정·고정 sleep 금지. → [checklist A10](./docs/pr-checklist.md#a10-테스트)
11. PR 전 로컬 검증 전부 통과 + 체크리스트. DI·모델·라우팅·네이티브·bridge·토큰·의존성 변경은 PR 전에 상대에게 한 줄 알린다. → [workflow 4·5절](./docs/workflow.md#4-로컬-검증-pr-전-필수)

## Git

브랜치 `feat/JECT-123-login` · 커밋 `feat(JECT-123): 한글 요약` · PR `[JECT-123] 요약` · 기능 → `develop` squash(제목은 커밋 규칙으로) · `develop` → `main` merge. 자세히 [workflow 2절](./docs/workflow.md#2-브랜치에서-머지까지). `develop` 브랜치는 아직 없다.

## 아직 안 한 것

- Shorebird, Fastlane, 스토어 배포, 실기기 서명
- 토큰 갱신·세션 복원·WebView bridge, `shared/widgets`(Loading/Error/Empty), `core/error`
- 웹 서버 데이터 라이브러리(TanStack Query) 도입 여부, 웹 호스팅
- `develop` 브랜치, `docs/api/`, `docs/releases.md`
43 changes: 40 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,46 @@
# highfive-5th-Client

Flutter 3.47.9 (fvm) 기반 클라이언트입니다.
highfive 5기 클라이언트 저장소. 앱(Flutter)과 웹(React + TypeScript + Vite)을 같은 저장소에서 관리한다.

```
apps/mobile Flutter 앱 (Flutter 3.47.9, fvm)
apps/web 공개 웹·관객용 모바일 웹 (Node 24, pnpm)
docs/ 작업 흐름·구조·디자인 토큰 규칙
```

처음이면 [docs/overview.md](./docs/overview.md)(그림으로 보는 전체 구조)부터, 작업 규칙은 [AGENTS.md](./AGENTS.md)에서 시작한다.

## 앱 실행

```bash
fvm install
cd apps/mobile
fvm install # .fvmrc 버전 설치
fvm flutter pub get
fvm flutter run
fvm flutter run --flavor dev # dev / prod 두 앱이 나란히 설치된다
```

PR 전 검증 (CI도 같은 명령):

```bash
fvm dart format --set-exit-if-changed lib test tool
fvm flutter analyze
fvm dart run tool/check_imports.dart
fvm flutter test
# 생성 파일이 최신인지: 커밋한 뒤 작업 트리가 깨끗할 때 실행해서 diff가 없어야 한다
fvm dart run build_runner build --delete-conflicting-outputs && git diff --exit-code
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

## 웹 실행

```bash
cd apps/web
corepack enable # pnpm 버전은 package.json의 packageManager를 따른다
pnpm install
pnpm dev
```

PR 전 검증 (CI도 같은 명령):

```bash
pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm build:dev
```
34 changes: 0 additions & 34 deletions analysis_options.yaml

This file was deleted.

File renamed without changes.
51 changes: 51 additions & 0 deletions apps/mobile/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Miscellaneous
*.class
*.log
*.pyc
*.swp
.DS_Store
.atom/
.build/
.buildlog/
.history
.svn/
.swiftpm/
migrate_working_dir/

# IntelliJ related
*.iml
*.ipr
*.iws
.idea/

# The .vscode folder contains launch configuration and tasks you configure in
# VS Code which you may wish to be included in version control, so this line
# is commented out by default.
#.vscode/

# Flutter/Dart/Pub related
**/doc/api/
**/ios/Flutter/.last_build_id
.dart_tool/
.flutter-plugins-dependencies
.pub-cache/
.pub/
/build/
/coverage/

# Symbolication related
app.*.symbols

# Obfuscation related
app.*.map.json

# Android Studio will place build artifacts here
/android/app/debug
/android/app/profile
/android/app/release

# Widget Preview related
.widget_preview/

# FVM Version Cache
.fvm/
File renamed without changes.
Loading
Loading