diff --git a/.claude/WORKFLOW-GUIDE.md b/.claude/WORKFLOW-GUIDE.md new file mode 100644 index 0000000..cb23489 --- /dev/null +++ b/.claude/WORKFLOW-GUIDE.md @@ -0,0 +1,92 @@ +# Claude Code 워크플로우 가이드 — TK Factory Services + +## 1. CLAUDE.md 활용 +- 프로젝트 루트의 `CLAUDE.md`가 매 세션 자동 로드 → 프로젝트 컨텍스트 즉시 파악 +- 서비스별 CLAUDE.md 추가 가능 (예: `system1-factory/CLAUDE.md`) → 해당 디렉토리 작업 시 추가 로드 +- git으로 관리되므로 팀원 간 공유 가능 + +## 2. 슬래시 커맨드 (.claude/commands/) + +| 커맨드 | 설명 | 사용 예 | +|--------|------|---------| +| `/deploy` | 원클릭 NAS 배포 | `/deploy system1-web` | +| `/check-deploy` | NAS 서비스 상태 점검 | `/check-deploy` | +| `/cache-bust` | 변경된 JS/CSS 캐시 버스팅 일괄 갱신 | `/cache-bust` | +| `/add-page` | System1 새 HTML 페이지 스캐폴드 | `/add-page consumable/stock 소모품 재고` | +| `/add-api` | System1 새 API 엔드포인트 스캐폴드 | `/add-api consumable-stock` | + +커스텀 추가: `.claude/commands/`에 `.md` 파일 추가하면 자동 인식. + +## 3. Plan 모드 활용 + +적합한 작업: +- 여러 서비스에 걸친 기능 추가 (예: 새 마이크로서비스) +- DB 스키마 변경 + API + 프론트엔드 동시 수정 +- 대규모 리팩터링 (30+ 파일 변경) + +사용법: +1. `/plan`으로 Plan 모드 진입 +2. Claude가 코드 탐색 → 구현 계획 작성 +3. 계획 검토 · 수정 → 승인 +4. 자동 실행 + +## 4. 서브에이전트 활용 패턴 + +| 에이전트 | 용도 | 예시 | +|----------|------|------| +| Explore | 코드베이스 탐색 | "system1과 system2에서 인증 처리 방식 비교해줘" | +| Plan | 구현 설계 | "tkeg에 새 모듈 추가 계획 세워줘" | + +- 독립적 탐색은 병렬 실행 가능 (최대 3개) +- 넓은 범위 검색에 유용 (단순 파일 찾기는 직접 검색이 빠름) + +## 5. 검증 피드백 루프 (Boris Cherny 패턴) + +코드 변경 후 검증 사이클: +1. **빌드 확인** → `docker compose build <서비스>` +2. **배포** → `/deploy <서비스>` +3. **health check** → 자동 실행 (deploy에 포함) +4. **수동 확인** → 브라우저에서 모바일 + 데스크탑 테스트 + +## 6. 효율적 작업 패턴 + +### 프론트엔드 수정 (Vanilla JS 서비스) +1. HTML/JS/CSS 수정 +2. `/cache-bust`로 캐시 버스팅 갱신 +3. `git commit` + `/deploy system1-web` + +### API 수정 (Node.js 서비스) +1. model → controller → route 수정 +2. `git commit` + `/deploy system1-api` +3. `curl`로 API 테스트 + +### tkeg 수정 (React + FastAPI) +1. 프론트: `npm run build` (Vite 자동 해시, 캐시 버스팅 불필요) +2. 백엔드: FastAPI 코드 수정 +3. `git commit` + `/deploy tkeg-api tkeg-web` + +### 여러 서비스 동시 수정 +1. `/plan`으로 계획 수립 +2. 변경 실행 +3. 영향받는 서비스 모두 재배포: `/deploy system1-api system1-web system2-api` + +## 7. 자주 쓰는 디버깅 명령 + +```bash +# DB 접속 (NAS) +ssh hyungi@100.71.132.52 "docker exec tk-mariadb mysql -uhyungi_user -p'hyung-ddfdf3-D341@' hyungi" + +# 로그 확인 (NAS) +ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose logs -f --tail=50 <서비스>" + +# 컨테이너 상태 (NAS) +ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose ps" + +# PostgreSQL 접속 (tkeg) +ssh hyungi@100.71.132.52 "docker exec tk-tkeg-postgres psql -U tkbom_user -d tk_bom" +``` + +## 8. 팁 +- **작은 단위로 커밋**: 서비스별로 나눠서 커밋하면 롤백이 쉬움 +- **CLAUDE.md 업데이트**: 새 서비스 추가 시 서비스 맵 테이블 갱신 +- **메모리 활용**: 반복되는 피드백은 Claude가 자동 저장 → 다음 세션에도 적용 diff --git a/.claude/commands/add-api.md b/.claude/commands/add-api.md new file mode 100644 index 0000000..26b94ea --- /dev/null +++ b/.claude/commands/add-api.md @@ -0,0 +1,30 @@ +System1(system1-factory) 새 API 엔드포인트를 생성합니다. + +인자: $ARGUMENTS (예: "consumable-stock 소모품 재고" 또는 리소스명) + +절차: +1. 기존 패턴 확인: + - system1-factory/api/ 아래 기존 model, controller, route 파일 하나씩 읽어 패턴 파악 + +2. Model 생성 (`api/models/<리소스>.js`): + - Knex 기반 DB 쿼리 패턴 + - CRUD 기본 메서드: getAll, getById, create, update, delete + +3. Controller 생성 (`api/controllers/<리소스>Controller.js`): + - responseFormatter (res.success, res.error, res.paginated) 사용 + - try/catch + 에러 핸들링 패턴 + - 페이지네이션 지원 (GET list) + +4. Route 생성 (`api/routes/<리소스>Routes.js`): + - Express Router + - auth 미들웨어 적용 + - RESTful 패턴: GET /, GET /:id, POST /, PUT /:id, DELETE /:id + +5. 라우트 등록: + - `api/config/routes.js` (또는 app.js/server.js)에 새 라우트 추가 + +6. 생성된 파일 목록 + API 엔드포인트 정리 보고 + +주의: +- 다른 서비스(system2, tkpurchase 등)의 API 추가 시 해당 서비스의 패턴을 먼저 확인 +- System3, tkeg는 FastAPI 패턴 (Python) diff --git a/.claude/commands/add-page.md b/.claude/commands/add-page.md new file mode 100644 index 0000000..417772e --- /dev/null +++ b/.claude/commands/add-page.md @@ -0,0 +1,25 @@ +System1(system1-factory) 새 HTML 페이지를 생성합니다. + +인자: $ARGUMENTS (예: "consumable/stock 소모품 재고 관리") +→ 경로와 페이지 제목을 파싱 + +절차: +1. 기존 페이지를 템플릿으로 사용: + - system1-factory/web/ 아래 비슷한 기능의 기존 HTML 페이지를 찾아 참조 + - 공통 구조: 헤더(nav), 사이드네비, 메인 콘텐츠 영역 + +2. 새 HTML 파일 생성 (`system1-factory/web/<경로>.html`): + - 공통 CSS: tkfb.css, Tailwind CDN, Font Awesome + - 공통 JS: tkfb-core.js, api-base.js + - 페이지 제목, 설명 커스터마이즈 + - 사이드네비에 현재 페이지 active 표시 + +3. 대응 JS 컨트롤러 파일 생성 (필요 시): + - `system1-factory/web/js/<경로>.js` + - 기존 JS 패턴 따르기 (DOMContentLoaded, API 호출 등) + +4. 생성된 파일 목록 보고 + 캐시 버스팅 안내 + +주의: +- 다른 서비스(system2, system3 등)에 페이지 추가 시 해당 서비스의 패턴을 먼저 확인 +- HTML의 script/link 태그에 ?v= 버전 포함 diff --git a/.claude/commands/cache-bust.md b/.claude/commands/cache-bust.md new file mode 100644 index 0000000..6656071 --- /dev/null +++ b/.claude/commands/cache-bust.md @@ -0,0 +1,20 @@ +커밋 전 변경된 JS/CSS 파일에 대해 캐시 버스팅 버전을 갱신합니다. + +절차: +1. `git diff --name-only HEAD`로 아직 커밋 안 된 변경사항 중 .js, .css 파일 목록 추출 + - staged + unstaged 모두 포함: `git diff --name-only HEAD` + `git diff --name-only --cached` + - untracked 파일도 포함: `git ls-files --others --exclude-standard -- '*.js' '*.css'` + +2. 각 변경된 JS/CSS 파일에 대해: + - 해당 파일을 참조하는 HTML 파일을 grep으로 검색 (같은 서비스 디렉토리 내) + - `