docs(README): create-next-app 보일러플레이트 → 실제 프로젝트 문서로 교체
- Stack / Scripts / Env / Routes / Source Layout / Deployment / Conventions / Troubleshooting 섹션을 현재 코드 상태(package.json, next.config.mjs, .env.*, ecosystem 파일) 기반으로 작성 - CLAUDE.md (gotcha 위주) 와 역할 분담: README 는 stack·디렉토리·env·배포 같은 기본 정보 담당 - docs/ PDF 와 .agents/skills/ 참조 인덱스 포함 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
sangwook yoo
parent
899b150ba8
commit
0211c57103
167
README.md
167
README.md
@ -1,38 +1,161 @@
|
||||
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
|
||||
# Q.CAST Front
|
||||
|
||||
### Getting Started
|
||||
Q.CELLS 일본 시장 대상 태양광 패널 레이아웃 설계 · 견적 · 관리 프론트엔드. Next.js 14 App Router 기반.
|
||||
|
||||
First, run the development server:
|
||||
자세한 작업 규약 · 비명시적 패턴 · gotcha 는 [`CLAUDE.md`](./CLAUDE.md) 와 [`docs/`](./docs) PDF 들을 참조한다.
|
||||
|
||||
## Stack
|
||||
|
||||
- **Framework**: Next.js 14.2.28 (App Router, `reactStrictMode: false`)
|
||||
- **Language**: JavaScript + TypeScript (`allowJs: true`, `strict: false`)
|
||||
- **Canvas**: Fabric.js 5.5.2 (커스텀 확장 — `src/components/fabric/`, `src/util/fabric-extensions.js`)
|
||||
- **State**: Recoil 0.7.7 (도메인별 atom — `src/store/`)
|
||||
- **Session/Auth**: iron-session 8 (쿠키 기반)
|
||||
- **Data fetching**: axios 1.7 + SWR 2.3
|
||||
- **i18n**: next-international (ja / ko — `src/locales/`)
|
||||
- **UI**: react-responsive-modal, react-select, react-datepicker, ag-grid-react, sweetalert2, react-icons, framer-motion, tailwindcss + sass
|
||||
- **PDF/이미지**: jimp, sharp, convertapi
|
||||
- **DB 클라이언트**: mssql (서버 사이드), sqlite/sqlite3 (로컬 캐시)
|
||||
- **AWS**: `@aws-sdk/client-s3`
|
||||
- **Geo**: `@turf/turf`, mathjs, big.js
|
||||
- **Path alias**: `@/* → ./src/*`
|
||||
|
||||
## Getting Started
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# or
|
||||
yarn dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
bun dev
|
||||
yarn install
|
||||
yarn dev # .env.localhost 사용, http://localhost:3000
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
`.env.localhost` 가 워크트리에 있어야 한다(실제 시크릿 포함). 새 머신에서는 팀에서 받아 배치할 것.
|
||||
|
||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
||||
HTTPS 가 필요하면 `./certificates/key.pem`, `cert.pem` 을 준비한 뒤 `yarn serve` (HTTP 3000 + HTTPS 3001).
|
||||
|
||||
This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
|
||||
## Scripts
|
||||
|
||||
## Learn More
|
||||
모든 스크립트는 `env-cmd` 로 `.env.<mode>` 를 주입한다. **테스트 러너는 별도로 wiring 되어 있지 않다.**
|
||||
|
||||
To learn more about Next.js, take a look at the following resources:
|
||||
| Script | 설명 |
|
||||
| --- | --- |
|
||||
| `yarn dev` | 로컬 개발 (`.env.localhost`) |
|
||||
| `yarn dev:log` | dev + stdout 을 `dev.log` 로 미러링 |
|
||||
| `yarn dev:local-api` | API 를 `http://localhost:8080` 으로 고정 |
|
||||
| `yarn local:dev` | `.env.local.dev` 모드 (로컬에서 dev 서버 환경 흉내) |
|
||||
| `yarn build` | 프로덕션 빌드 (`.env.production`) |
|
||||
| `yarn build:dev` | dev 빌드 (`.env.development`) |
|
||||
| `yarn build:local.dev` | local.dev 빌드 |
|
||||
| `yarn start:cluster1` | `next start -p 5000` (PM2 prd1) |
|
||||
| `yarn start:cluster2` | `next start -p 5001` (PM2 prd2) |
|
||||
| `yarn start:dev` | `next start -p 5010` (PM2 dev) |
|
||||
| `yarn serve` | `server.js` — HTTP 3000 + HTTPS 3001 (certificates 필요) |
|
||||
| `yarn lint` | `next lint` — 완료 전 필수 |
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
||||
## Environment Variables
|
||||
|
||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
|
||||
각 모드별 `.env.<mode>` 파일에 정의. 키 목록(전체 값은 절대 공개 채널에 노출 금지):
|
||||
|
||||
## Deploy on Vercel
|
||||
| Key | 용도 |
|
||||
| --- | --- |
|
||||
| `NEXT_PUBLIC_RUN_MODE` | `src/config/config.export.js` 가 어떤 config 를 로드할지 결정 (`local` / `local.dev` / `development` / `production`) |
|
||||
| `NEXT_PUBLIC_API_SERVER_PATH` | 백엔드 API base URL |
|
||||
| `NEXT_PUBLIC_HOST_URL` | 프론트엔드 호스트 (자기 자신) |
|
||||
| `NEXT_PUBLIC_API_HOST_URL` | API 호스트 |
|
||||
| `SESSION_SECRET` | iron-session 쿠키 서명 키 — **32 byte 이상 필수** |
|
||||
| `NEXT_PUBLIC_CONVERTER_DWG_API_URL` | DWG → SVG 변환 서비스 |
|
||||
| `NEXT_PUBLIC_CONVERTER_DXF_API_URL` | DXF → SVG 변환 서비스 |
|
||||
| `NEXT_PUBLIC_Q_ORDER_AUTO_LOGIN_URL` | Q-Order autoLogin 진입점 |
|
||||
| `NEXT_PUBLIC_Q_MUSUBI_AUTO_LOGIN_URL` | Q-Musubi autoLogin 진입점 |
|
||||
| `NEXT_PUBLIC_AWS_S3_BASE_URL` | S3 정적 자산 base URL |
|
||||
| `NEXT_PUBLIC_ENABLE_LOGGING` | `true` 일 때만 `src/util/logger.js` 와 `debugCapture.js` 가 실제로 출력 |
|
||||
| `AWS_REGION`, `AMPLIFY_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_PROFILE` | S3 업로드 (서버 전용 — `.env.localhost` 등에만) |
|
||||
|
||||
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
||||
`.env.*` 자체는 git 추적 대상이고 시크릿을 포함한다. 머신별 오버라이드는 `.env.*.local` (`gitignore` 됨) 에 둘 것.
|
||||
|
||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
|
||||
## Routes (App Router)
|
||||
|
||||
deploy test
|
||||
```
|
||||
src/app/
|
||||
api/ # Next.js Route Handlers (S3, debug, 이미지 등)
|
||||
community/ # 커뮤니티
|
||||
floor-plan/ # 도면 캔버스 — 본 앱의 핵심
|
||||
estimate/ # 견적 화면
|
||||
simulator/ # 시뮬레이터
|
||||
page.jsx # 도면 에디터 진입점
|
||||
join/ # 회원가입
|
||||
login/ # 로그인
|
||||
management/ # 관리자
|
||||
image/ # 이미지 관리
|
||||
stuff/ # 자재/제품 관리
|
||||
layout.js # 루트 레이아웃 — 세션 체크 후 비로그인 시 /login 으로 리다이렉트
|
||||
page.js # 홈
|
||||
```
|
||||
|
||||
세션이 없는 상태로 `/login` 외 경로 접근 시 루트 레이아웃이 강제 리다이렉트한다. `src/middleware.js` 는 `x-pathname` 헤더를 주입해 루트 레이아웃이 현재 경로에 따라 분기할 수 있게 한다.
|
||||
|
||||
## Source Layout
|
||||
|
||||
```
|
||||
src/
|
||||
app/ # App Router 라우트 + 글로벌 Provider 들
|
||||
common/ # 공용 유틸 / 모듈
|
||||
components/ # 도메인별 UI 컴포넌트
|
||||
fabric/ # QLine, QPolygon — Fabric.js 확장 클래스
|
||||
floor-plan/ # 캔버스 툴 모달 (roofShape, placementShape, panelBatch …)
|
||||
estimate/, management/, simulator/, ui/, …
|
||||
config/ # 모드별 런타임 config (config.export.js 가 분기)
|
||||
hooks/ # 도메인별 hook (roofcover, surface, module, object, option …)
|
||||
lib/ # 세션, 캔버스 저장/복원, 파일/이미지 액션
|
||||
locales/ # ja.json, ko.json
|
||||
middleware.js # x-pathname 주입
|
||||
models/ # 도메인 모델
|
||||
store/ # Recoil atom (canvas, roof, estimate, modal, menu, setting …)
|
||||
styles/ # sass entry (includePaths)
|
||||
util/ # logger, debugCapture, fabric-extensions, canvas-util …
|
||||
```
|
||||
|
||||
## Deployment (PM2)
|
||||
|
||||
`*.ecosystem.config.js` + `startscript*.js` 조합으로 실행. `startscript` 가 `child_process.exec` 로 yarn 스크립트를 호출한다.
|
||||
|
||||
| File | 용도 | Port |
|
||||
| --- | --- | --- |
|
||||
| `ecosystem.config.js` | 프로덕션 클러스터 (instances: 2) | — |
|
||||
| `prd1.ecosystem.config.js` | 프로덕션 #1 (fork) | 5000 |
|
||||
| `prd2.ecosystem.config.js` | 프로덕션 #2 (fork) | 5001 |
|
||||
| `dev.ecosystem.config.js` | dev 서버 | 5010 |
|
||||
| `dev.local.ecosystem.config.js` | local.dev 모드 dev 서버 | — |
|
||||
|
||||
## Conventions
|
||||
|
||||
상세 사항은 `CLAUDE.md` 와 `docs/Qcast coding convention.pdf`, `docs/Qcast development guilde.pdf` 참조. 핵심만 옮기면:
|
||||
|
||||
- **Prettier**: single quote, **no semicolons**, tabWidth 2, printWidth 150, trailingComma `all`. 완료 전 `yarn lint`.
|
||||
- **No raw `alert()`** — `useSwal` / `useMessage` + `sweetalert2` 만 사용. `docs/메세지 처리 가이드.pdf`.
|
||||
- **Path alias** `@/...` 우선, `../../..` 체인 지양.
|
||||
- **로깅** — `console.log` 직접 사용 금지. `src/util/logger.js` 사용 (`NEXT_PUBLIC_ENABLE_LOGGING=true` 일 때만 출력).
|
||||
- **Commit message** — `.gitmessage.txt` 형식 (`[일감번호] : [제목]`) 또는 최근 브랜치 스타일 `[2204] <제목> — <상세>`. Prefix 만 영문, 본문은 한국어.
|
||||
- **i18n** — UI 텍스트는 `src/locales/{ja,ko}.json` 에 키 추가 후 `useI18n` 으로 접근.
|
||||
|
||||
## Documentation
|
||||
|
||||
| File | 내용 |
|
||||
| --- | --- |
|
||||
| `CLAUDE.md` | 에이전트(Claude / Codex) 작업 규약 + 비명시적 패턴 · gotcha |
|
||||
| `docs/Canvas Status.md` | 캔버스 기능 상태 · 타겟별 컨텍스트 메뉴 인벤토리 |
|
||||
| `docs/Qcast coding convention.pdf` | 전체 코딩 컨벤션 |
|
||||
| `docs/Qcast development guilde.pdf` | 개발 가이드 |
|
||||
| `docs/메세지 처리 가이드.pdf` | 모달 / 알럿 메시지 규칙 |
|
||||
| `docs/git commit message Convention.pdf` | 커밋 메시지 컨벤션 |
|
||||
| `docs/Nextjs 14 컴포넌트에 대해서….pdf` | App Router 서버/클라이언트 컴포넌트 노트 |
|
||||
| `docs/dictionary.txt` | 도메인 용어집 (지붕 / 패널 용어 JP/KR) |
|
||||
| `docs/diagrams/` | 아키텍처 다이어그램 |
|
||||
| `.agents/skills/{next-best-practices,vercel-react-best-practices}/` | Next/React 패턴 결정 시 우선 참조 (총 95개 룰 .md) |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **빌드 시 `Module not found: fs` / `canvas`** — `next.config.mjs` 의 webpack externals 에 추가. node-only deps 는 클라이언트 번들에서 제외해야 한다.
|
||||
- **세션이 즉시 풀림** — `SESSION_SECRET` 이 32 byte 미만이면 iron-session 이 거부한다. `.env.<mode>` 확인.
|
||||
- **플랜 로드 시 `InvalidStateError`** — `src/lib/canvas.js` / `src/util/canvas-util.js` 의 3-layer guard (entry/cache/save) 와 `SizeSetting` 의 0-area guard 로 차단된다. 가드 약화 금지 — 손상된 플랜은 정상 데이터로 교체할 것.
|
||||
- **App Router 캐시로 인한 stale plan/estimate** — `next.config.mjs` 의 `experimental.staleTimes` 가 의도적으로 모두 `0`. 다시 켜지 말 것.
|
||||
- **HTTPS dev 실패** — `./certificates/key.pem`, `cert.pem` 부재. gitignore 대상이라 팀에서 받아 배치해야 한다.
|
||||
- **dev 서버에서만 한글/일본어 폰트 깨짐** — `next/font` 캐시 문제일 가능성. `.next/` 삭제 후 재시작.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user