ONAANDALL/frontend

Fork 0

Files

T

jcchoi a22da07a16 가이드 추가

2026-11-09 13:47:14 +09:00

8.5 KiB

Raw Blame History

Frontend 개발 가이드 (외부 업체용)

이 프로젝트의 프론트엔드는 개발 완료 후 인터넷이 차단된 환경(폐쇄망) 에 반영됩니다. 반영 과정에서 빌드 실패나 버전 불일치가 생기지 않도록, 개발 중 아래 규칙을 지켜 주세요.

문의: [담당자 이름 / 연락처 기입]

1. 개발 환경

항목	버전	비고
Node.js	`22.23.4`	루트 `.nvmrc` 참고. 다른 버전으로 빌드하지 마세요.
패키지 매니저	`pnpm 10.12.1`	`npm`, `yarn`은 사용 불가 (루트 `preinstall`에서 차단됨)

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. 환경변수 · 설정값

환경(개발/운영)마다 주소 등의 값이 다르므로, 코드에 값을 직접 쓰지 않습니다.

규칙

환경변수는 각 앱의 src/shared/config/env.ts에서만 읽습니다. (예: apps/st/src/shared/config/env.ts) 컴포넌트에서 process.env.XXX를 직접 쓰지 마세요.
새 환경변수를 추가하면 env.ts와 해당 앱의 .env.example을 같이 수정하세요.
브라우저에서 읽는 값은 NEXT_PUBLIC_ 접두사가 필요하고, 서버에서만 쓰는 값(SERVER_API_URL 등)에는 붙이지 않습니다.
비밀값(토큰, 비밀번호, API 키)은 저장소에 커밋하지 마세요. .env.example에는 예시 값만 적습니다.
새 환경변수를 추가하면 PR 설명에 키 이름, 용도, 개발용 예시 값을 적어 주세요. 운영 환경의 값은 담당자가 설정합니다.

예시

// apps/st/src/shared/config/env.ts
export const ST_SERVICE_URL =
    process.env.NEXT_PUBLIC_ST_SERVICE_URL || "http://localhost:8080";

# 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)으로 다음을 통과해야 합니다.

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장의 금지 목록에 해당하는지 확인하고, 애매하면 추가 전에 담당자에게 문의하세요.

8.5 KiB Raw Blame History