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>
docs(CLAUDE.md): 부정확 정보 정리 — README 신뢰 주장 제거 + graphify 섹션 현실 반영
2026-05-15 15:35:02 +09:00 · 2026-05-15 15:31:28 +09:00
2 changed files with 151 additions and 40 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 > 루트 `AGENTS.md` 는 `@CLAUDE.md` 한 줄짜리 alias. Codex 등 다른 코딩 에이전트도 이 문서를 그대로 따른다.

-> The repository README.md is unusually thorough. Treat it as authoritative for stack, directory layout, env vars, routes, and troubleshooting — this file only highlights what's non-obvious or easy to get wrong.
+> `README.md` 는 사실상 `create-next-app` 보일러플레이트 그대로다 — 신뢰하지 말 것. 스택·디렉토리·env·라우팅·트러블슈팅의 단일 진실 공급원은 이 파일과 `docs/` PDF 들이다.

 ## Project at a glance

@ -100,22 +100,10 @@ Atoms live under `src/store/` and are split by domain (`canvasAtom`, `roofAtom`,
 - Skill 진입점: 각 디렉토리의 `SKILL.md` 가 인덱스, 룰은 `rules/` 하위 토픽별 파일.
 - 이 문서들은 git 추적 대상이므로 변경하면 PR 에 함께 올릴 것.

-## graphify
+## graphify (선택)

-A persistent knowledge graph of `src/` lives at `graphify-out/` (built by `/graphify src`). Prefer it over grep for architectural questions.
+`src/` 지식 그래프를 `graphify-out/` 에 캐싱해두면 cross-module 질문(A 가 B 에 어떻게 연결되는가, X 의 의존성 등)을 grep 보다 빠르게 답할 수 있다. 캐시는 로컬 전용이며 git 추적 대상이 아니다.

-> `graphify-out/` 는 **로컬 캐시**라 git 추적 대상이 아님(`.gitignore`). 새 클론·워크트리에서 비어 있으면 `graphify update .` 로 incremental 빌드, 아예 없으면 `/graphify src` 로 풀 빌드.
-
-**When to consult it**
- Before answering "how does X relate to Y", "what depends on Z", or any cross-module question, read `graphify-out/GRAPH_REPORT.md` (god nodes, surprising connections) and use `graphify query "..."` / `graphify path "A" "B"` / `graphify explain "..."` — these traverse EXTRACTED + INFERRED edges instead of scanning files.
- If `graphify-out/wiki/index.md` exists, prefer it over raw file reads.
- The PreToolUse hook in `.claude/settings.json` will remind you when you reach for `grep` / `rg` / `find`.
-
-**Keeping it fresh — auto-update is wired up**
-1. **In-session (you, Claude)**: after any batch of `Edit` / `Write` on files under `src/`, run `graphify update .` to incrementally re-extract changed files. AST-only, no LLM cost, takes a few seconds. Do this *before* answering follow-up architectural questions on the changed code, otherwise the graph is stale.
-2. **At commit (automatic)**: a `post-commit` git hook (installed via `graphify hook install`, lives in the main repo's `.git/hooks/`, shared across worktrees) re-runs AST extraction on changed code files after every commit. Combined with the "commit in meaningful units" rule above, the graph stays current with minimal effort.
-3. **Doc / image changes**: the post-commit hook ignores non-code files. Run `graphify update .` manually after touching docs that affect the graph (rare — this project's graph is code-only).
-
-**Don't**
- Don't rebuild the whole graph (`/graphify src` from scratch) unless `graph.json` is missing or corrupt — `graphify update .` is strictly faster and preserves cached analysis.
- Don't trust `INFERRED` edges blindly — the AST extractor marks JS import-derived `calls` edges as INFERRED. Verify with the actual source when the answer hinges on call semantics (see useMessage trace example).
+- 부재 시(현재 워크트리 포함): `/graphify src` 로 풀 빌드, 이후엔 `graphify update .` 로 incremental.
+- `src/` 편집 후 architectural 질문에 답하기 전에 `graphify update .` 1회 실행 (AST-only, 수 초).
+- JS import-기반 `calls` edge 는 INFERRED 로 마크됨 — 호출 의미가 답의 핵심이면 소스로 한 번 더 확인.
--- a/README.md
+++ b/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/` 삭제 후 재시작.