151 lines
8.5 KiB
Markdown
151 lines
8.5 KiB
Markdown
# Frontend 개발 가이드 (외부 업체용)
|
|
|
|
이 프로젝트의 프론트엔드는 개발 완료 후 **인터넷이 차단된 환경(폐쇄망)** 에 반영됩니다. 반영 과정에서 빌드 실패나 버전 불일치가 생기지 않도록, 개발 중 아래 규칙을 지켜 주세요.
|
|
|
|
> 문의: **[담당자 이름 / 연락처 기입]**
|
|
|
|
---
|
|
|
|
## 1. 개발 환경
|
|
|
|
| 항목 | 버전 | 비고 |
|
|
|---|---|---|
|
|
| Node.js | `22.23.4` | 루트 `.nvmrc` 참고. 다른 버전으로 빌드하지 마세요. |
|
|
| 패키지 매니저 | `pnpm 10.12.1` | `npm`, `yarn`은 사용 불가 (루트 `preinstall`에서 차단됨) |
|
|
|
|
```bash
|
|
nvm use # .nvmrc 기준 Node 선택
|
|
corepack enable
|
|
pnpm install
|
|
```
|
|
|
|
- `pnpm-lock.yaml`은 저장소에 포함하지 않습니다(`.gitignore` 대상). 커밋 대상이 아니므로 `git status`에 나타나도 올리지 마세요.
|
|
- Node, pnpm 버전을 임의로 올리지 마세요. 버전 변경은 담당자와 협의 후 진행합니다.
|
|
|
|
---
|
|
|
|
## 2. 의존성(패키지) 규칙
|
|
|
|
폐쇄망에서는 npm 공식 저장소가 아닌 사내 저장소를 거쳐 패키지를 받습니다. 아래에 해당하는 패키지는 설치가 실패할 수 있습니다.
|
|
|
|
### 반드시 지킬 것
|
|
- 패키지는 **작업 중인 앱의 `package.json`**(`apps/<앱>/package.json`)에만 추가하세요. 다른 앱이나 루트 `package.json`은 수정하지 않습니다.
|
|
- 새 패키지는 `pnpm add -E <패키지>`로 **정확한 버전**을 지정해 추가하는 것을 권장합니다. 폐쇄망에 반영할 때 담당자가 `package.json`을 기준으로 버전을 확정하므로, `latest`나 넓은 범위(`*`)는 피하세요.
|
|
|
|
### 사용하면 안 되는 형태
|
|
| 금지 | 이유 |
|
|
|---|---|
|
|
| git 주소·tarball URL 의존성 (`github:...`, `https://...tgz`) | 폐쇄망에서 받을 수 없음 |
|
|
| 설치 중(`postinstall`) 인터넷에서 바이너리를 내려받는 패키지 (예: Puppeteer, Playwright 브라우저 다운로드 등) | 설치 단계에서 실패 |
|
|
| 빌드 시 외부 사이트에서 폰트·리소스를 받는 방식 (예: `next/font/google`) | 빌드 실패 |
|
|
|
|
### 새 패키지를 추가할 때
|
|
PR 설명에 **패키지명, 버전, 추가 이유, 라이선스**를 적어 주세요. 네이티브 모듈(C/C++ 빌드가 필요한 패키지)은 반입 전에 별도 확인이 필요하므로 **미리 담당자에게 알려 주세요.**
|
|
|
|
---
|
|
|
|
## 3. 외부 인터넷 접근 금지
|
|
|
|
운영 환경은 외부 인터넷에 연결되지 않습니다. 화면이 동작하는 데 필요한 모든 리소스는 **프로젝트 안에 포함**되어야 합니다.
|
|
|
|
- 폰트: `next/font/local` 또는 `public/`에 포함. Google Fonts, CDN 폰트 사용 금지
|
|
- 스크립트·스타일: CDN `<script src="https://...">`, `<link href="https://...">` 사용 금지
|
|
- 이미지·아이콘: 외부 URL 대신 프로젝트에 포함 (`public/` 또는 import)
|
|
- 분석·광고·SNS 위젯, 외부 SaaS 호출 코드(예: 오류 수집, 지도 타일 서버 등)는 추가 전에 담당자와 협의
|
|
- 코드에 `http://`, `https://` 주소나 IP를 직접 쓰지 마세요. 아래 4장의 환경변수를 사용합니다.
|
|
|
|
---
|
|
|
|
## 4. 환경변수 · 설정값
|
|
|
|
환경(개발/운영)마다 주소 등의 값이 다르므로, **코드에 값을 직접 쓰지 않습니다.**
|
|
|
|
### 규칙
|
|
1. 환경변수는 각 앱의 `src/shared/config/env.ts`에서만 읽습니다. (예: `apps/st/src/shared/config/env.ts`) 컴포넌트에서 `process.env.XXX`를 직접 쓰지 마세요.
|
|
2. 새 환경변수를 추가하면 **`env.ts`와 해당 앱의 `.env.example`을 같이 수정**하세요.
|
|
3. 브라우저에서 읽는 값은 `NEXT_PUBLIC_` 접두사가 필요하고, 서버에서만 쓰는 값(`SERVER_API_URL` 등)에는 붙이지 않습니다.
|
|
4. 비밀값(토큰, 비밀번호, API 키)은 **저장소에 커밋하지 마세요.** `.env.example`에는 예시 값만 적습니다.
|
|
5. 새 환경변수를 추가하면 **PR 설명에 키 이름, 용도, 개발용 예시 값**을 적어 주세요. 운영 환경의 값은 담당자가 설정합니다.
|
|
|
|
### 예시
|
|
|
|
```ts
|
|
// apps/st/src/shared/config/env.ts
|
|
export const ST_SERVICE_URL =
|
|
process.env.NEXT_PUBLIC_ST_SERVICE_URL || "http://localhost:8080";
|
|
```
|
|
|
|
```bash
|
|
# apps/st/.env.example
|
|
NEXT_PUBLIC_ST_SERVICE_URL=http://localhost:8080
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 저장소 · 브랜치 규칙
|
|
|
|
- 각 업체/앱은 지정된 작업 브랜치(`iipbs/<앱>/<이름>` 형태)에서 작업하고, 점검을 통과한 변경을 `main`에 반영하세요. 기존 브랜치 이름 규칙을 따릅니다.
|
|
- `main`에 직접 push할 수 있습니다. 단, `main` 반영 전에 빌드로 유효성을 검증하므로 **6장 자체 점검을 통과한 뒤에만 push**하세요. 빌드가 실패하는 커밋을 `main`에 올리면 반영이 막힙니다.
|
|
- 팀·업체가 함께 쓰는 브랜치이므로 push 전에 `git pull --rebase origin main`으로 최신 상태를 받고, `force push`는 하지 마세요.
|
|
- 수정 가능한 범위는 아래 표를 따르세요.
|
|
- 빌드 산출물과 로컬 파일(`.next`, `node_modules`, `*.tsbuildinfo`, 개인 `.env`)은 커밋하지 않습니다.
|
|
|
|
### 수정 가능 영역 구분
|
|
|
|
| 영역 | 경로 | 수정 규칙 |
|
|
|---|---|---|
|
|
| 주관사 관리 앱 | `apps/cs`, `apps/st`, `apps/as`, `apps/cm` | **수정 금지** (수정이 필요하면 요청) |
|
|
| 주관사 관리 공통 모듈 | `apps/common`, `packages/common/types`, `assets`, `auth`, `components`, `config`, `network` | **수정 금지** (수정이 필요하면 요청) |
|
|
| 업체 담당 앱 / 패키지 | 그 외 `apps/*`, `packages/*` (예: `dm`, `fo`, `sn`, `wr`) | **본인이 담당하는 앱·패키지만** 수정 |
|
|
| 루트 설정 | `package.json`, `turbo.json`, `tsconfig.base.json`, `eslint.config.mjs`, `tailwind.config.preset.ts` | 수정 금지 |
|
|
|
|
- 공통 모듈은 여러 앱이 함께 사용하므로, 변경하면 다른 업체의 앱도 영향을 받습니다. 공통 컴포넌트나 API 클라이언트에 기능 추가·수정이 필요하면 **이유와 원하는 동작을 담당자에게 요청**해 주세요.
|
|
- 다른 업체가 담당하는 앱 폴더는 수정하지 마세요. 충돌과 반입 지연의 원인이 됩니다.
|
|
- 공통 모듈의 기능을 쓰는 것(import)은 자유롭게 가능합니다.
|
|
|
|
---
|
|
|
|
## 6. 커밋 전 확인 (자체 점검)
|
|
|
|
작업 앱 기준(예: `st`)으로 다음을 통과해야 합니다.
|
|
|
|
```bash
|
|
pnpm install # 의존성 설치
|
|
pnpm build:st # 해당 앱 빌드 (앱 이름에 맞게 변경)
|
|
pnpm --filter st lint # 해당 앱 린트 (앱 이름에 맞게 변경)
|
|
```
|
|
|
|
앱별 빌드 명령: `build:as`, `build:cm`, `build:cs`, `build:sn`, `build:wr`, `build:fo`, `build:dm`, `build:st`
|
|
|
|
---
|
|
|
|
## 7. PR 체크리스트
|
|
|
|
PR 설명에 아래 항목을 확인해 체크해 주세요.
|
|
|
|
- [ ] Node `22.23.4` / pnpm `10.12.1`로 빌드했다
|
|
- [ ] `pnpm install`과 해당 앱 빌드가 성공했다
|
|
- [ ] 패키지를 추가·변경했다면 해당 앱 `package.json`에 정확한 버전으로 반영했고, PR에 패키지명·버전·사유·라이선스를 적었다
|
|
- [ ] git/URL 의존성, 설치 시 인터넷 다운로드가 필요한 패키지를 쓰지 않았다
|
|
- [ ] 외부 CDN, 외부 폰트, 외부 URL 리소스를 쓰지 않았다
|
|
- [ ] 주소·IP를 코드에 직접 쓰지 않고 `env.ts`의 환경변수를 사용했다
|
|
- [ ] 새 환경변수를 추가했다면 `env.ts`, `.env.example`에 반영하고 PR에 키 이름·용도를 적었다
|
|
- [ ] 비밀값(토큰, 비밀번호)을 커밋하지 않았다
|
|
- [ ] 본인이 담당하는 앱·패키지만 수정했다 (주관사 관리 앱·공통 모듈, 루트 설정, 타 업체 앱은 수정하지 않았다)
|
|
|
|
---
|
|
|
|
## 8. 자주 묻는 질문
|
|
|
|
**Q. `pnpm-lock.yaml`이 `git status`에 보이는데 커밋해야 하나요?**
|
|
A. 아니요. lock 파일은 저장소에서 제외되는 파일이라 올리지 않습니다. 폐쇄망에 반영할 때 사용하는 lock은 담당자가 별도로 관리합니다. 대신 패키지를 추가·변경했다면 PR에 알려 주세요.
|
|
|
|
**Q. 폰트/아이콘을 외부 주소로 쓰고 싶어요.**
|
|
A. 파일을 내려받아 프로젝트(`public/` 등)에 포함하세요. 라이선스상 재배포가 가능한지 확인이 필요합니다.
|
|
|
|
**Q. 개발 서버 주소가 다른데 어떻게 바꾸나요?**
|
|
A. 코드가 아니라 본인의 `.env` 파일(커밋하지 않음)에서 값을 바꾸세요. 4장을 참고하세요.
|
|
|
|
**Q. 이 패키지를 써도 되는지 모르겠어요.**
|
|
A. 2장의 금지 목록에 해당하는지 확인하고, 애매하면 추가 전에 담당자에게 문의하세요.
|