From 697af50963d83012dd49b1489ddf54d238762933 Mon Sep 17 00:00:00 2001 From: Hyungi Ahn Date: Wed, 1 Apr 2026 15:13:45 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=EC=97=90=20=EA=B0=9C=EB=B0=9C?= =?UTF-8?q?=20=EC=A3=BC=EC=9D=98=EC=82=AC=ED=95=AD=20=EC=B6=94=EA=B0=80=20?= =?UTF-8?q?=E2=80=94=20=EC=98=A4=EB=8A=98=20=EC=8B=A4=EC=88=98=20=EA=B8=B0?= =?UTF-8?q?=EB=A1=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - admin 계정 전용 테스트 금지 (권한 미들웨어 스킵 문제) - workers/sso_users department_id 불일치 주의 - const vs function 전역 스코프 충돌 - 캐시 버스팅 누락 방지 - nginx 프록시 경로 우선순위 Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index eb8b3a5..361a5ab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,6 +40,38 @@ git push && ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && ``` 상세: DEPLOY-GUIDE.md 참조. 아키텍처: ARCHITECTURE.md 참조. +## 개발 주의사항 — 실수 기록 + +### admin 계정으로만 테스트하지 말 것 +admin(role=admin/system)은 대부분의 권한 체크를 건너뜀. 반드시 **일반 사용자(role=user) 계정으로 테스트**할 것. +- `pagePermission.js`: admin은 L18에서 `return next()`로 미들웨어 전체 스킵 +- `tkfb-core.js initAuth()`: admin은 `accessibleKeys` 조회 자체를 안 함 +- **실제 사례 (2026-04-01)**: `getPool()` async 함수에 `await` 누락 → admin만 통과, 일반 사용자 전원 500 에러. admin 계정으로만 테스트하여 배포 전 미발견 + +### workers 테이블과 sso_users 테이블 불일치 +모든 사용자가 `workers` 테이블에 있지 않음 (생산지원팀 등 사무직). department_id 조회 시 반드시 **sso_users fallback** 사용: +```sql +COALESCE(w.department_id, su.department_id) AS department_id +``` +- `dashboardModel.js getUserInfo()` — 수정 완료 +- `pageAccessRoutes.js` 부서 조회 — 수정 완료 +- **신규 코드 작성 시**: workers JOIN 후 department_id 사용하면 동일 버그 재발 + +### 전역 스코프 const vs function 충돌 +`const`로 선언한 변수명과 다른 스크립트 파일의 `function` 선언이 같은 이름이면 `SyntaxError: Identifier already declared` 발생. 해당 스크립트 **전체**가 실행 안 됨. +- **실제 사례 (2026-04-01)**: `tkfb-core.js`에 `const escHtml = escapeHtml;` 추가 → 4개 JS 파일에서 `function escHtml()` 재선언 → 모바일 전체 미작동 +- **규칙**: 전역 alias 추가 시 `grep -r "function 함수명" --include="*.js"` 로 충돌 확인 필수 + +### 캐시 버스팅 누락 +JS/CSS 수정 후 HTML의 `?v=YYYYMMDDNN` 갱신을 빠뜨리면 브라우저 캐시로 구버전 실행됨. +- 특히 `tkfb-core.js`는 **35개 HTML**에서 참조 — 일괄 갱신 필수 +- `shared-bottom-nav.js`는 5개 HTML에서 참조 +- **규칙**: JS/CSS 수정 시 해당 파일을 참조하는 모든 HTML의 버전 갱신. `grep -r "파일명" --include="*.html"` 로 대상 확인 + +### nginx 프록시 경로 우선순위 +nginx location 블록은 **더 구체적인 경로가 먼저** 매칭됨. `/api/auth/`를 `/api/` 뒤에 넣으면 `/api/`가 먼저 잡힘. +- **실제 사례 (2026-04-01)**: `/api/auth/change-password` 요청이 system1-api로 라우팅되어 404. `/api/auth/` location을 `/api/` 앞에 추가하여 해결 + ## 멀티 에이전트 워크플로우 이 프로젝트는 Cowork(설계/검토) + Claude Code(코딩) 멀티 에이전트 방식을 지원한다. - **워크플로우 가이드**: `.cowork/WORKFLOW-GUIDE.md`