From 909eb583071a7eb552cc6bfd7e9ecbfbe2b55dea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 11 Mar 2026 11:05:53 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20PDF=20=ED=8F=B0=ED=8A=B8=20?= =?UTF-8?q?=EC=A0=95=EC=B1=85=20=ED=95=84=EC=88=98=20=EA=B7=9C=EC=B9=99=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 1090 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1090 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..94dd400 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,1090 @@ +# Claude Code 전역 설정 + +> 이 파일은 모든 프로젝트에 적용되는 전역 규칙입니다. + +## 메모리 + +### sam설명 +SAM 프로젝트의 기술적 개요 문서입니다. 이 문서를 참조하면 SAM 프로젝트가 무엇인지 이해할 수 있습니다. + +**파일 경로**: `/home/aweso/sam/docs/SAM_PROJECT_OVERVIEW_FOR_AI.md` + +**핵심 요약**: +- **회사**: 주일/경동 (블라인드/스크린 제조업체) +- **프로젝트**: SAM (Smart Automation Management) - 차세대 ERP/MES 통합 시스템 +- **기술 스택**: Laravel 12 + HTMX + Tailwind CSS + MySQL 8.0 (PHP 8.4) +- **아키텍처**: Multi-tenant (tenant_id 기반 데이터 격리) +- **레거시**: 5130.co.kr (PHP 기반) → SAM으로 마이그레이션 중 + +**사용자가 'sam설명'이라고 말하면**: +1. 위 경로의 `SAM_PROJECT_OVERVIEW_FOR_AI.md` 파일을 읽어서 전체 내용을 파악하세요 +2. SAM 프로젝트의 비즈니스 도메인, 기술 스택, 현재 작업 현황을 이해한 상태로 작업하세요 + +--- + +## Git 커밋 규칙 (최우선 필수 규칙) + +> **경고: 이 규칙은 절대 누락되어서는 안 됩니다!** +> **기준 문서**: `sam/docs/standards/git-conventions.md` + +### 필수 수행 절차 + +**모든 코드 작업 완료 후 반드시 다음을 수행:** + +1. 변경된 파일이 있는 Git 저장소로 이동 +2. `git status`로 변경사항 확인 +3. `git add <파일들>` 로 스테이징 +4. `git commit -m "type: [scope] 작업내용"` 로 커밋 + +### 커밋 메시지 형식 (필수) + +``` +type: [scope] 작업내용 + +- 세부항목 (생략가능) +- 세부항목 2 + +Issue: URL (생략가능) +``` + +**예시:** +```bash +feat: [calendar] 달력 기능 개선 + +- 클릭시 오류 기능 개선 +- 색상 변경 +``` + +```bash +fix: [auth] 로그인 시 세션 만료 오류 수정 +``` + +### Commit Types + +| Type | 설명 | 예시 | +|------|------|------| +| `feat` | 새로운 기능 추가 | `feat: [file] 파일 업로드 기능 추가` | +| `fix` | 버그 수정 | `fix: [auth] 세션 만료 오류 수정` | +| `chore` | 설정, 빌드 등 변경 | `chore: composer 패키지 업데이트` | +| `refactor` | 프로덕션 코드 리팩토링 | `refactor: [user] 서비스 메서드 분리` | +| `style` | 포맷/코딩 스타일 수정 | `style: Pint 포맷팅 적용` | +| `test` | 테스트 추가/수정 | `test: Product API 테스트 추가` | +| `docs` | 문서 변경 | `docs: API 문서 업데이트` | + +### Claude 서명 제외 (필수) + +``` +❌ Co-Authored-By: Claude — 포함 금지 +❌ 🤖 Generated with Claude Code — 포함 금지 +``` + +- Git hooks로 자동 제거됨 +- 간결하고 명확한 한글 커밋 메시지만 유지 + +### 푸시 정책 + +#### MNG 자동 푸시 (커밋 즉시 배포) + +> **MNG 프로젝트는 커밋 후 자동으로 개발+운영 서버에 배포한다.** 트리거 워드 불필요. + +**커밋 완료 후 자동 실행 절차:** + +1. `git push origin develop` (개발 서버 배포) +2. `git checkout main && git pull origin main` (최신화) +3. `git cherry-pick <방금_커밋_해시>` (운영 반영) +4. `git push origin main` (운영 서버 배포) +5. `git checkout develop` (작업 브랜치 복귀) + +```bash +# MNG 커밋 후 자동 실행 예시 +cd /home/aweso/sam/mng +git push origin develop +git checkout main && git pull origin main +git cherry-pick abc1234 +git push origin main +git checkout develop +``` + +> **충돌 발생 시**: 사용자에게 알리고 해결 지원 (자동 중단하지 않음) +> **여러 커밋 연속 시**: 마지막 커밋 후 한 번만 실행 (중간 커밋에서는 생략 가능) + +#### API / React 푸시 (트리거 워드 기반) + +> API, React는 기존대로 **사용자가 트리거 워드를 말할 때만** 푸시 실행. + +#### 트리거: "개발서버 푸시" + +사용자가 **"개발서버 푸시"**라고 말하면 다음을 자동 실행: + +1. 각 프로젝트(`api`, `mng`, `react`)에서 `git status` 확인 +2. 커밋되지 않은 변경사항이 있으면 커밋 규칙에 따라 커밋 +3. 현재 브랜치가 `develop`인지 확인 (아니면 `develop`으로 전환) +4. `git push origin develop` 실행 (변경사항 있는 프로젝트만) +5. 결과 요약 출력 + +```bash +# 변경사항 있는 프로젝트만 실행 +cd /home/aweso/sam/api && git push origin develop +cd /home/aweso/sam/mng && git push origin develop +cd /home/aweso/sam/react && git push origin develop +``` + +> Jenkins가 Gitea Webhook으로 개발 서버에 자동 배포한다. + +#### 트리거: "운영서버 푸시" + +사용자가 **"운영서버 푸시"**라고 말하면 다음을 자동 실행: + +> **전제**: develop의 변경사항이 개발 서버에서 테스트 완료된 상태 +> **방식**: **cherry-pick** — 이번 세션에서 작업한 커밋만 골라서 main에 반영 (develop 전체 머지 금지) + +1. 각 프로젝트에서 develop에 미푸시 커밋 확인 → 있으면 먼저 `git push origin develop` +2. **체리픽 대상 커밋 식별** — 이번 세션에서 작업한 커밋 해시 목록을 `git log --oneline`으로 확인하여 사용자에게 표시 +3. 사용자에게 체리픽 대상 커밋 목록을 보여주고 **확인** 받기 +4. `git checkout main` (모든 프로젝트 운영 브랜치: `main`) +5. `git pull origin main` — **최신화 (충돌 방지 핵심 단계)** +6. `git cherry-pick ...` — 확인받은 커밋만 순서대로 적용 +7. 충돌 발생 시 → 사용자에게 알리고 해결 지원 +8. `git push origin main` — Jenkins가 운영 서버에 자동 배포 +9. `git checkout develop` — 작업 브랜치로 복귀 +10. 결과 요약 출력 (체리픽한 커밋 목록 포함) + +```bash +# 예시: mng에서 이번 세션 커밋 2개만 체리픽 +cd /home/aweso/sam/mng + +# 1. develop 미푸시 확인 +git push origin develop + +# 2. 체리픽 대상 확인 (사용자 승인) +git log --oneline # → abc1234, def5678 + +# 3. main 전환 및 최신화 +git checkout main && git pull origin main + +# 4. 선택한 커밋만 체리픽 (시간순 — 오래된 것부터) +git cherry-pick abc1234 def5678 + +# 5. 푸시 및 복귀 +git push origin main +git checkout develop +``` + +> **merge와의 차이**: `git merge develop`은 develop의 모든 커밋을 main에 반영하지만, `git cherry-pick`은 지정한 커밋만 반영한다. 다른 개발자의 미검증 커밋이 운영에 올라가는 문제를 방지한다. +> **주의**: cherry-pick 후 develop에 main을 머지하지 않는다. 동일 변경이 이미 develop에 존재하므로 불필요하다. + +#### 운영서버 푸시 대상 프로젝트 (2026-02-27~) + +| 프로젝트 | 개발서버 푸시 | 운영서버 푸시 | 비고 | +|----------|:----------:|:----------:|------| +| **MNG** | ✅ | ✅ | | +| **API** | ✅ | ✅ | 2026-02-27부터 허용 | +| **React** | ✅ | ❌ 중지 | 개발 완료 시점에 배포 예정 | + +> "운영서버 푸시" 트리거 시 **MNG + API**만 cherry-pick → main push 실행. React는 develop push만 수행. + +#### 푸시 대상 자동 판별 + +| 조건 | 동작 | +|------|------| +| 현재 작업 디렉토리가 특정 프로젝트 | 해당 프로젝트만 푸시 | +| `sam/` 루트이거나 명시 없음 | 3개 프로젝트 모두 확인 후 변경사항 있는 것만 푸시 | +| 사용자가 프로젝트 지정 ("api 개발서버 푸시") | 지정된 프로젝트만 푸시 | + +### Claude Code 설정 파일도 커밋 대상 + +다음 파일들이 변경되면 반드시 커밋: + +| 파일/폴더 | 설명 | 커밋 예시 | +|-----------|------|----------| +| `CLAUDE.md` | 프로젝트 설정 | `docs: CLAUDE.md 규칙 업데이트` | +| `claudedocs/` | Claude 관련 문서 | `docs: 기능 분석 문서 추가` | +| `.claude/settings.json` | Claude 설정 | `chore: Claude 설정 변경` | +| `agents/`, `skills/` | 커스텀 에이전트/스킬 | `feat: [claude] 새 스킬 추가` | + +### 커밋 전 체크리스트 + +- [ ] `./vendor/bin/pint` 실행 (코드 포맷팅, 해당 시) +- [ ] `git diff`로 변경사항 검토 +- [ ] 불필요한 파일 제외 (.env, node_modules 등) +- [ ] 변경된 파일이 있는 저장소에서 git add → git commit +- [ ] CLAUDE.md, claudedocs/, agents/, skills/ 변경 확인 → git commit +- [ ] 커밋 메시지: `type: [scope] 한글 작업내용` 형식 준수 +- [ ] Co-Authored-By 서명 미포함 확인 + +--- + +## 주요 프로젝트 경로 + +| 경로 | 설명 | Git 저장소 | +|------|------|-----------| +| `/home/aweso/sam/mng` | 관리자 웹 (Laravel) | 독립 저장소 | +| `/home/aweso/sam/api` | API 서버 (Laravel) | 독립 저장소 | +| `/home/aweso/sam/react` | 프론트엔드 (Next.js) | 독립 저장소 | + +**각 폴더는 독립적인 Git 저장소입니다. 해당 폴더에서 git 명령을 실행해야 합니다.** + +> **서버 경로 참고**: +> - 개발/운영 서버 모두 `/home/webservice/` 하위에 동일한 구조로 배치 +> - 서버: `/home/webservice/api`, `/home/webservice/mng`, `/home/webservice/react`, `/home/webservice/sales` + +--- + +## 서버 접근 정책 (3단계 분류) + +> **2026-02-21 사고 교훈**: Claude가 서버에 SSH로 접속하여 **설정을 변경**한 결과 502 Bad Gateway 발생. +> → 교훈: **읽기는 허용, 변경은 확인 후, 위험 작업은 금지** + +### 핵심 원칙 + +서버 접근을 **3단계**로 분류하여 관리한다: + +| 단계 | 분류 | 정책 | +|------|------|------| +| 🟢 Level 1 | 읽기 전용 (진단/조회) | **자유 허용** — 사용자 요청 시 즉시 실행 | +| 🟡 Level 2 | 경미한 변경 | **사용자 확인 후 실행** — 실행 전 명령어를 보여주고 승인받기 | +| 🔴 Level 3 | 위험한 변경 | **절대 금지** — 안내만 제공 | + +### 🟢 Level 1: 읽기 전용 (자유 허용) + +사용자가 서버 진단/조회를 요청하면 **즉시 SSH 접속하여 실행** 가능: + +``` +✅ ls, cat, head, tail, less — 파일/디렉토리 조회 +✅ ps aux, top, htop — 프로세스 확인 +✅ df -h, free -m — 디스크/메모리 확인 +✅ git status, git log, git diff — Git 상태 조회 +✅ stat, id, whoami — 권한/소유자 확인 +✅ nginx -t, php -v — 설정 검증 (변경 아닌 테스트만) +✅ tail -f /var/log/*.log — 로그 조회 +✅ systemctl status — 서비스 상태 조회 +✅ crontab -l — 크론 작업 조회 +``` + +### 🟡 Level 2: 경미한 변경 (확인 후 실행) + +실행 전 **명령어를 사용자에게 보여주고 승인**받은 후 실행: + +``` +⚠️ git pull — 코드 업데이트 +⚠️ composer install — 의존성 설치 +⚠️ php artisan migrate — DB 마이그레이션 +⚠️ php artisan config:clear, cache:clear — 캐시 초기화 +⚠️ chmod, chown — 파일 권한 변경 (소규모) +⚠️ systemctl restart — 서비스 재시작 +⚠️ npm install — 패키지 설치 +``` + +**실행 절차:** +1. 실행할 명령어를 먼저 사용자에게 표시 +2. 사용자 승인 확인 +3. 승인 후 실행 + +### 🔴 Level 3: 위험한 변경 (절대 금지 — 안내만) + +Claude가 **절대 직접 실행하지 않으며**, 사용자에게 명령어를 안내만 제공: + +``` +❌ rm -rf, 대량 파일 삭제 +❌ nginx/apache 설정 파일 직접 수정 +❌ /etc/ 하위 시스템 설정 변경 +❌ 서버에서 npm run build (메모리 부족 위험) +❌ DB 직접 수정 (DROP, TRUNCATE, 대량 UPDATE/DELETE) +❌ 방화벽(iptables, ufw) 규칙 변경 +❌ 사용자 계정 생성/삭제/비밀번호 변경 +❌ scp, rsync로 대량 파일 전송 +❌ 프로세스 강제 종료 (kill -9) +❌ 서버 재부팅 +``` + +### 서버 접속 정보 + +| 서버 | 호스트 | 계정 | SSH 접근 | 역할 | +|------|--------|------|---------|------| +| 개발 서버 (sam-dev) | `114.203.209.83` | `pro`, `hskwon` | **Claude 가능** | 개발/스테이징 + Gitea | +| 운영 서버 | (비공개) | 별도 계정 | **Claude 불가** — 개발팀장만 접근 | 정식 서비스 | + +> **참고**: Jenkins는 CI/CD 서버(`110.10.147.46:8080`, ci.sam.it.kr)에서 운영한다. Gitea는 개발 서버(`114.203.209.83:3000`)와 CI/CD 서버(`110.10.147.46:3000`, git.sam.it.kr) 양쪽에 있다. + +> **운영 서버 정책**: Claude는 운영 서버에 SSH 접속할 수 없다. IP 접근이 제한되어 있으며 개발팀장만 접근 가능하다. 운영 배포는 `git push origin main` → Jenkins 자동 배포로만 이루어지며, 운영 서버 상태 확인이 필요하면 사용자(개발팀장)에게 요청한다. + +### 배포 흐름 (Jenkins CI/CD) + +``` +Claude 역할 Jenkins (자동) 운영 서버 +┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ 코드 작성/수정 │ │ │ │ │ +│ git add / commit │ │ │ │ │ +│ │─push──→ │ Gitea Webhook │ │ │ +│ │(사용자) │ → Jenkins 빌드 │ │ │ +│ │ │ → Lint/Test │ │ │ +│ │ │ → SSH Deploy ────│──→ │ git pull │ +│ │ │ │ │ composer │ +│ 서버 진단 (L1) │ │ │ │ migrate │ +│ 서버 변경 (L2) │─확인──→ │ │ │ │ +│ 위험 작업 (L3) │─안내──→ │ │ │ (팀장 직접) │ +└───────────────────┘ └──────────────────┘ └──────────────┘ +``` + +> **브랜치 전략**: `develop` → 개발 서버 (자동 배포), `main` → 운영 서버 (PR 머지 + 팀장 승인) + +### 체크리스트 (서버 작업 시) + +- [ ] Level 1 (읽기): 사용자 요청 시 즉시 실행 +- [ ] Level 2 (변경): 명령어를 보여주고 승인 후 실행 +- [ ] Level 3 (위험): 절대 직접 실행하지 않고 안내만 제공 +- [ ] 사고 방지: 설정 파일 수정, 서비스 중단 가능성 있는 작업은 Level 3 + +--- + +## PDF 생성 시 폰트 정책 (필수 규칙) + +> **경고: PDF를 생성하는 코드를 작성/수정할 때 반드시 이 정책을 따르세요!** +> **정책 문서**: `/home/aweso/sam/docs/dev/standards/pdf-font-policy.md` + +### 배경 + +운영서버에서 DomPDF로 PDF 생성 시 한글 깨짐(???) 및 폰트 권한 오류가 반복 발생. 구글 폰트 외부 로드, 시스템 폰트 의존, vendor/ 캐시 권한 문제가 원인이었다. 프로젝트에 폰트를 번들링하여 모든 환경에서 동일하게 동작하도록 정책을 수립했다. + +### 필수 준수 사항 + +``` +❌ 구글 폰트(@import, ) 사용 금지 +❌ isRemoteEnabled 옵션 사용 금지 +❌ font-family에 시스템 전용 폰트(Malgun Gothic 등) 단독 사용 금지 +❌ font-weight: 800 이상 사용 금지 (NanumGothic은 normal/bold만 존재) +✅ font-family: 'NanumGothic', 'Malgun Gothic', sans-serif 사용 +✅ ensureKoreanFont() 호출 후 PDF 생성 +✅ 폰트 원본은 resources/fonts/에 프로젝트와 함께 배포 +✅ config/dompdf.php의 enable_font_subsetting: true (경량화) +``` + +### 작업 전 체크리스트 + +- [ ] 정책 문서(`sam/docs/dev/standards/pdf-font-policy.md`) 읽기 +- [ ] PDF Blade 뷰에 외부 폰트 URL 미포함 +- [ ] `ensureKoreanFont()` 패턴 적용 +- [ ] `font-weight`는 `normal`/`bold`만 사용 + +--- + +## React 빌드/배포 정책 (필수 규칙) + +> **경고: React(Next.js) 빌드를 운영 서버에서 직접 실행하지 않는다!** + +### 배경 + +개발 서버(2코어, 3.8GB RAM + Swap 4GB)에서 Jenkins가 React 빌드를 수행한다. +Jenkins 빌드 실패 시 로컬(WSL)에서 빌드 후 결과물을 서버에 배포한다(fallback). + +### 금지 사항 + +``` +❌ 운영 서버에서 npm run build 실행 금지 +❌ 서버 SSH 접속 후 빌드 명령 실행 금지 +❌ Claude가 직접 npm run build 실행 금지 (로컬 포함) +``` + +### 빌드/배포 방법 (Jenkins 자동화) + +``` +Claude 역할 Jenkins (자동) 운영 서버 +┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ 코드 작성/수정 │ │ Checkout │ │ │ +│ git commit │─push──→ │ Install + Lint │ │ │ +│ │(사용자) │ Build (Next.js) │ │ │ +│ │ │ Package (tar.gz) │──scp→ │ 압축 해제 │ +│ │ │ │ │ node 재시작 │ +└─────────────────┘ └──────────────────┘ └──────────────┘ +``` + +> **Fallback**: Jenkins 빌드 실패(OOM) 시 로컬에서 `react/deploy.sh`로 수동 배포 + +### 빌드가 필요한 상황 + +사용자에게 다음과 같이 안내한다: + +``` +React 코드가 변경되었습니다. git push 후 Jenkins가 자동 배포합니다. +(Jenkins 실패 시 로컬에서 deploy.sh로 수동 배포해주세요.) +``` + +--- + +## 데이터베이스 아키텍처 (필수 규칙) + +> **경고: 이 규칙을 반드시 준수하세요!** + +### 핵심 원칙 + +**모든 데이터베이스 관련 파일은 API 프로젝트에서만 관리합니다.** + +| 항목 | API (`/home/aweso/sam/api`) | MNG (`/home/aweso/sam/mng`) | +|------|----------------------------|----------------------------| +| 마이그레이션 | ✅ 여기에 생성 | ❌ 생성 금지 | +| 시더 | ✅ 여기에 생성 | ⚠️ MNG 전용만 허용 | +| 팩토리 | ✅ 여기에 생성 | ❌ 생성 금지 | + +### 금지 사항 + +``` +❌ /home/aweso/sam/mng/database/migrations/ 에 파일 생성 금지 +❌ MNG에서 테이블 생성/수정 마이그레이션 작성 금지 +``` + +### 허용 사항 + +``` +✅ /home/aweso/sam/api/database/migrations/ 에 모든 마이그레이션 생성 +✅ MNG에서는 MngMenuSeeder 같은 MNG 전용 시더만 허용 +``` + +### 마이그레이션 실행 + +```bash +# 로컬: 마이그레이션은 반드시 API 컨테이너에서 실행 +docker exec sam-api-1 php artisan migrate + +# 개발 서버: Docker 없음, 직접 실행 +cd /home/webservice/api && php artisan migrate + +# 운영 서버: --force 플래그 필수 (production 환경) +cd /home/webservice/api && php artisan migrate --force + +# MNG에서 마이그레이션 실행 금지 (로컬/서버 모두) +``` + +### DB 환경 분리 + +| 환경 | DB명 | 호스트 | 용도 | +|------|------|--------|------| +| 로컬 (Docker) | `samdb` | `sam-mysql-1:3306` | 개발/테스트 | +| 개발 서버 | `samdb` | `localhost` | 스테이징 | +| 운영 서버 | `sam_prod` | `localhost` | 정식 서비스 | +| 통계 DB | `sam_stat` | 동일 서버 | StatMonitorService 전용 | + +> **참고**: `sam_stat`은 API/MNG 모두 `config/database.php`의 별도 connection으로 접속한다. + +### 이유 + +- MNG: 프론트엔드/관리자 화면 담당 (컨트롤러, 뷰, 라우트) +- API: 백엔드/데이터베이스 담당 (마이그레이션, 모델 정의, API) +- 단일 DB를 두 프로젝트가 공유하므로 마이그레이션은 한 곳에서만 관리 + +### 테이블 생성/수정 시 options JSON 컬럼 정책 (필수) + +> **경고: 테이블 생성/수정, 마이그레이션 작성, 모델 생성 시 반드시 아래 정책 문서를 먼저 읽고 준수하세요!** +> **정책 문서**: `/home/aweso/sam/docs/standards/options-column-policy.md` + +**핵심 원칙**: FK/조인키만 전용 컬럼, 나머지 속성은 `options` JSON에 저장 + +| 전용 컬럼 (일반 컬럼) | options JSON | +|---|---| +| FK/조인키 (다른 테이블 참조) | 테넌트별로 다를 수 있는 확장 속성 | +| WHERE/ORDER BY 자주 사용 필드 | 선택적(nullable) 부가 정보 | +| UNIQUE 제약 필드 | 구조가 유동적인 데이터 | +| INDEX 필요한 고빈도 조회 필드 | 드롭다운 선택지 목록 | +| 집계(SUM/AVG) 대상 | 이력/스냅샷성 데이터 | + +**필수 준수 사항**: + +``` +✅ 모든 비즈니스 테이블에 $table->json('options')->nullable() 포함 +✅ 모델 cast: 'options' => 'array' (❌ 'json' 금지) +✅ 모델에 getOption() / setOption() 헬퍼 메서드 추가 +✅ options 키 3개 이상 시 OPTION_* 상수 정의 +✅ options 수정 시 setOption() 사용 (전체 덮어쓰기 금지) +✅ API 응답 노출 시 accessor + $appends 추가 +``` + +**작업 전 체크리스트**: +- [ ] 정책 문서(`docs/standards/options-column-policy.md`) 읽기 +- [ ] 새 필드가 전용 컬럼인지 options인지 판단 (판단 흐름도 참고) +- [ ] 마이그레이션에 `options` JSON 컬럼 포함 확인 +- [ ] 모델에 `'options' => 'array'` cast + 헬퍼 메서드 포함 확인 + +--- + +## 메뉴 관리 규칙 (필수) + +> **경고: 메뉴 시더(Seeder)를 절대 실행하지 마세요!** + +### 배경 + +메뉴 시더 실행 시 부서별 권한 설정(permission_overrides)이 초기화되는 문제가 반복 발생합니다. +메뉴 ID가 변경되면 기존 부서-메뉴 권한 매핑이 깨지기 때문입니다. + +### 금지 사항 + +``` +❌ php artisan db:seed --class=MngMenuSeeder 실행 금지 +❌ php artisan db:seed --class=*MenuSeeder 실행 금지 +❌ 메뉴 시더 파일 생성 금지 +❌ 메뉴 데이터를 일괄 삭제 후 재생성하는 방식 금지 +``` + +### 메뉴 변경 시 올바른 절차 + +메뉴 추가/수정/삭제/이동이 필요할 때는 **사용자에게 수동 실행 안내**를 제공합니다: + +1. **tinker 명령어를 안내** (사용자가 직접 실행) +2. **또는 SQL 쿼리를 안내** (사용자가 phpMyAdmin 등에서 직접 실행) +3. **절대 시더를 만들어 실행하지 않음** + +### 안내 예시 + +``` +메뉴를 추가하려면 아래 명령을 서버에서 실행해 주세요: + +# 개발 서버 +ssh pro@114.203.209.83 "cd /home/webservice/mng && php artisan tinker --execute=\" +App\\Models\\Commons\\Menu::create([ + 'tenant_id' => 1, + 'parent_id' => <부모ID>, + 'name' => '새 메뉴', + 'url' => '/new-menu', + 'icon' => 'icon-name', + 'sort_order' => 1, + 'is_active' => true, +]); +\"" + +# 운영 서버 (동일 경로, 서버 주소만 변경) +ssh <운영계정>@<운영서버IP> "cd /home/webservice/mng && php artisan tinker --execute=\"...동일...\"" +``` + +### 체크리스트 (메뉴 변경 요청 시) + +- [ ] 시더 파일 생성하지 않음 +- [ ] 시더 실행하지 않음 +- [ ] tinker 또는 SQL로 개별 레코드만 수정 +- [ ] 변경 후 부서 권한 설정이 유지되는지 확인 + +--- + +## 실행 환경 (필수 인지) + +> **중요: 로컬 / 개발 서버 / 운영 서버의 환경이 다릅니다!** + +### 환경 비교 (3-Tier) + +| 항목 | 로컬 (WSL) | 개발 서버 | 운영 서버 | +|------|-----------|----------|----------| +| **구성 방식** | Docker 컨테이너 | Bare-metal (네이티브) | Bare-metal (네이티브) | +| **PHP** | 컨테이너 내부 (8.4) | 직접 설치 (8.4) | 직접 설치 (8.4) | +| **MySQL** | 컨테이너 (sam-mysql-1) | 직접 설치 (8.4) | 직접 설치 (8.4) | +| **Nginx** | 컨테이너 (sam-nginx-1) | 직접 설치 | 직접 설치 | +| **명령 실행** | `docker exec` 필요 | 직접 실행 | 직접 실행 | +| **서버 IP** | localhost | `114.203.209.83` | (신규, 미확정) | +| **추가 서비스** | — | Gitea | — | +| **DB** | `samdb` | `samdb` | `sam_prod` | + +> **배경**: 서버는 Docker가 무거워서 PHP, Nginx, MySQL 등을 네이티브로 설치하여 운영한다. + +### 로컬 환경 (Docker) + +PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있다. +로컬 PC(WSL)에는 이런 도구들이 없으므로, 반드시 Docker 컨테이너를 통해 실행한다. + +``` +로컬 PC (WSL) +└── Docker + ├── sam-mng-1 ← PHP + Laravel (MNG 앱) + ├── sam-api-1 ← PHP + Laravel (API 앱) + ├── sam-mysql-1 ← MySQL DB + └── sam-nginx-1 ← Nginx 웹서버 +``` + +### 서버 환경 (Bare-metal — 개발/운영 동일 구조) + +서버에는 Docker가 없다. PHP 8.4, Nginx, MySQL 8.4이 직접 설치되어 있다. + +``` +개발 서버 (114.203.209.83) 운영 서버 (신규) +├── Nginx ├── Nginx +├── PHP-FPM (3 pools) ├── PHP-FPM (3 pools) +│ ├── api.sock │ ├── api.sock +│ ├── mng.sock │ ├── mng.sock +│ └── sales.sock │ └── sales.sock +├── MySQL 8.4 (samdb) ├── MySQL 8.4 (sam_prod) +├── Supervisor ├── Supervisor +│ ├── sam-api-worker (x1) │ ├── sam-api-worker (x1) +│ ├── sam-mng-worker (x2) │ ├── sam-mng-worker (x2) +│ └── sam-api-scheduler │ └── sam-api-scheduler +├── Node.js (React SSR :3001) ├── Node.js (React SSR :3000) +├── Gitea (:3000) │ +├── /home/webservice/api ├── /home/webservice/api +├── /home/webservice/mng ├── /home/webservice/mng +├── /home/webservice/react ├── /home/webservice/react +└── /home/webservice/sales └── /home/webservice/sales +``` + +### 도메인 매핑 + +| 서비스 | 로컬 (Docker) | 개발 서버 | 운영 서버 | +|--------|--------------|----------|----------| +| React (사용자) | `dev.sam.kr` | `dev.codebridge-x.com` | `codebridge-x.com` | +| API | `api.sam.kr` | `api.dev.codebridge-x.com` | `api.codebridge-x.com` | +| MNG (관리자) | `mng.sam.kr` | `admin.codebridge-x.com` | `mng.codebridge-x.com` | +| Sales | `sales.sam.kr` | `sales.dev.codebridge-x.com` | `sales.codebridge-x.com` | +| 5130 (레거시) | `5130.sam.kr` | — | — | + +### 명령어 비교 (로컬 vs 개발 vs 운영) + +| 작업 | 로컬 (Docker) | 개발/운영 서버 (네이티브) | +|------|--------------|-------------------------| +| artisan 실행 | `docker exec sam-api-1 php artisan <명령>` | `cd /home/webservice/api && php artisan <명령>` | +| composer 실행 | `docker exec sam-api-1 composer install` | `cd /home/webservice/api && composer install` | +| 마이그레이션 | `docker exec sam-api-1 php artisan migrate` | 개발: `php artisan migrate` / 운영: `php artisan migrate --force` | +| 캐시 클리어 | `docker exec sam-mng-1 php artisan cache:clear` | `cd /home/webservice/mng && php artisan cache:clear` | +| Queue 재시작 | — | `sudo supervisorctl restart sam-api-worker:*` | + +### 로컬 Docker 명령어 패턴 + +```bash +# MNG 앱에서 artisan 명령 실행 +docker exec sam-mng-1 php artisan <명령어> + +# API 앱에서 artisan 명령 실행 +docker exec sam-api-1 php artisan <명령어> + +# 예시: 시더 실행 +docker exec sam-mng-1 php artisan db:seed --class=MngMenuSeeder + +# 예시: 마이그레이션 실행 (API에서만!) +docker exec sam-api-1 php artisan migrate + +# 예시: 캐시 클리어 +docker exec sam-mng-1 php artisan cache:clear +``` + +### 체크리스트 (명령 실행 시) + +- [ ] **로컬**: `php artisan` → `docker exec sam-mng-1 php artisan` 또는 `sam-api-1` 사용 +- [ ] **로컬**: `composer` → `docker exec sam-mng-1 composer` 또는 `sam-api-1` 사용 +- [ ] **서버**: `php artisan`, `composer` 직접 실행 (Docker 없음) +- [ ] **운영 서버 마이그레이션**: `--force` 플래그 필수 +- [ ] **마이그레이션은 반드시 API에서 실행** (로컬: `docker exec sam-api-1`, 서버: 직접) + +--- + +## 공동 개발 워크플로우 (필수) + +> **중요: 코드를 pull 받은 후 반드시 필요한 명령을 실행하세요!** + +### 브랜치 전략 + +| 브랜치 | 배포 대상 | 트리거 워드 | Jenkins 배포 | +|--------|----------|------------|-------------| +| `feature/*` | — | — | — | +| `develop` | 개발 서버 (`dev.codebridge-x.com`) | **"개발서버 푸시"** | Push 시 자동 | +| `main` | 운영 서버 (`codebridge-x.com`) | **"운영서버 푸시"** | Push 시 자동 | + +``` +로컬 작업 → develop push → 개발 서버 테스트 → main merge+push → 운영 서버 + ("개발서버 푸시") ("운영서버 푸시") +``` + +### 브랜치 동기화 규칙 (필수) + +> **cherry-pick 방식에서는 develop→main 자동 동기화가 불필요하다.** +> main에 직접 변경이 발생한 경우에만 develop에 동기화한다. + +| 상황 | 조치 | +|------|------| +| "운영서버 푸시" 완료 후 | 동기화 불필요 (cherry-pick은 develop에 이미 존재하는 커밋) | +| main에 **직접** 변경 발생 시 (hotfix 등) | develop에서 `git merge main` 실행 | +| develop에서 새 작업 시작 전 | `git pull origin develop`으로 최신화 확인 | + +``` +develop ──작업──→ develop push (개발서버) + │ + └── cherry-pick 선택 커밋 ──→ main push (운영서버) +``` + +### 로컬 환경 (Docker) 업데이트 + +```bash +# 1. 코드 받기 (WSL에서 실행) +cd /home/aweso/sam/api +git pull + +cd /home/aweso/sam/mng +git pull + +# 2. 의존성 업데이트 (composer.json 변경 시) +docker exec sam-api-1 composer install +docker exec sam-mng-1 composer install + +# 3. DB 마이그레이션 (API에서만!) +docker exec sam-api-1 php artisan migrate + +# 4. 캐시 클리어 (설정 변경 시) +docker exec sam-api-1 php artisan config:clear +docker exec sam-mng-1 php artisan config:clear +``` + +### 개발 서버 업데이트 (자동) + +> `develop` 브랜치에 Push 시 Gitea Webhook → Jenkins가 자동으로 배포한다. +> 수동 배포가 필요한 경우: + +```bash +# API 프로젝트 +cd /home/webservice/api +git pull origin develop +composer install +php artisan migrate +php artisan config:clear + +# MNG 프로젝트 (마이그레이션 없음) +cd /home/webservice/mng +git pull origin develop +composer install +php artisan config:clear +``` + +### 운영 서버 배포 (Jenkins 자동화) + +> `main` 브랜치에 PR 머지 시 Jenkins가 자동으로 배포한다. +> 수동 배포는 **비상 절차**로만 사용한다. + +```bash +# 비상 수동 배포 (Jenkins 장애 시에만) +# API 프로젝트 +cd /home/webservice/api +git pull origin main +composer install --no-dev --optimize-autoloader +php artisan migrate --force +php artisan config:clear && php artisan cache:clear && php artisan route:cache && php artisan view:cache +sudo supervisorctl restart sam-api-worker:* + +# MNG 프로젝트 +cd /home/webservice/mng +git pull origin master +composer install --no-dev --optimize-autoloader +php artisan config:clear && php artisan cache:clear && php artisan view:cache +sudo supervisorctl restart sam-mng-worker:* +``` + +### 요약 표 + +| 작업 | 로컬 (Docker) | 개발 서버 | 운영 서버 | +|------|--------------|----------|----------| +| 배포 방식 | 수동 | Jenkins 자동 (develop push) | Jenkins 자동 (main push) | +| git pull | WSL에서 직접 | Jenkins 자동 | Jenkins 자동 | +| composer install | `docker exec sam-api-1 composer install` | Jenkins 자동 | `--no-dev --optimize-autoloader` | +| migrate | `docker exec sam-api-1 php artisan migrate` | Jenkins 자동 | `--force` 플래그 포함 | +| config:clear | `docker exec sam-api-1 php artisan config:clear` | Jenkins 자동 | `route:cache` + `view:cache` 포함 | + +### 체크리스트 (pull 후) + +- [ ] API: `git pull` → `composer install` → `php artisan migrate` → `config:clear` +- [ ] MNG: `git pull` → `composer install` → `config:clear` (마이그레이션 없음) +- [ ] 운영 배포: `main`에 PR 머지 → Jenkins 자동 처리 (수동 금지) + +--- + +## 사용 가능한 Agents + +`~/.claude/agents/` 폴더에 있는 에이전트들: + +### 코드 품질 & 개발 + +| Agent | 모델 | 설명 | 출처 | +|-------|------|------|------| +| `code-reviewer` | sonnet | 코드 리뷰 (품질/보안/유지보수성), 메모리 학습 지원 | 공식 문서 패턴 | +| `debugger` | sonnet | 에러/테스트 실패 근본 원인 분석 및 수정 | 공식 문서 패턴 | +| `test-runner` | haiku | 테스트 실행 및 결과 분석/요약 | 커뮤니티 인기 | +| `security-auditor` | sonnet | OWASP Top 10 기반 보안 취약점 감사 | 커뮤니티 인기 | +| `performance-optimizer` | sonnet | N+1 쿼리, 알고리즘, 캐싱 최적화 | 커뮤니티 인기 | +| `refactoring-agent` | sonnet | 코드 구조 개선, SOLID 원칙, DRY 위반 제거 | 커뮤니티 인기 | +| `laravel-expert` | sonnet | Laravel 전문가 (SAM 프로젝트 환경 인지) | 커스텀 | + +### 워크플로우 & 문서 + +| Agent | 모델 | 설명 | 출처 | +|-------|------|------|------| +| `git-manager` | haiku | Git 브랜치/커밋/머지/PR 관리 | 커뮤니티 인기 | +| `doc-writer` | haiku | API 문서, README, 기술 가이드 작성 | 커뮤니티 인기 | +| `research-agent` | sonnet | 웹 리서치 및 자료 조사 | 기존 | +| `organizer-agent` | - | 프로젝트 구조화 및 정리 | 기존 | +| `proposal-agent` | - | 제안서 작성 | 기존 | + +--- + +## 사용 가능한 Skills + +`~/.claude/skills/` 폴더에 있는 스킬들 (슬래시 명령어로 사용): + +### 문서/프레젠테이션 + +| Skill | 설명 | +|-------|------| +| `pptx-skill` | PowerPoint 생성 | +| `ppt-auto-generator` | 마크다운/텍스트에서 PPT 생성 | +| `pdf-template-skill` | PDF 템플릿 분석/생성 | +| `text-analyzer-skill` | 텍스트 분석 및 PDF 구조 매핑 | +| `proposal-skill` | 제안서 생성 | +| `storyboard-generator` | 스토리보드 생성 | +| `design-skill` | 프레젠테이션 HTML 디자인 | + +### 코드 분석/시각화 + +| Skill | 설명 | +|-------|------| +| `code-flow-web-report` | 웹 앱 런타임 흐름 시각화 리포트 | +| `code-flow-web-doc-generator` | 소스 코드 호출/데이터 흐름 다이어그램 HTML 생성 | +| `codebase-analysis-web-report` | 코드베이스 아키텍처 인터랙티브 HTML 리포트 | +| `uml-generator` | UML 다이어그램 생성 | + +### 코드 품질 (levnikolaevich/claude-code-skills) + +| Skill | 설명 | 출처 | +|-------|------|------| +| `code-bug-finder` | 버그 자동 탐지 및 보고서 생성 | 기존 | +| `code-refactoring` | 리팩토링 권장사항/성능 분석/코드 패치 | 기존 | +| `code-commenter` | 소스 코드에 이해하기 쉬운 주석 추가 | 기존 | +| `async-await-keyword-fixer` | JS/TS 누락된 async/await 수정 | 기존 | +| `code-quality-checker` | DRY/KISS/YAGNI 위반 탐지 | levnikolaevich | +| `code-quality-auditor` | 코드 복잡도, 매직넘버 분석 | levnikolaevich | +| `code-principles-auditor` | DRY/KISS/YAGNI, TODO, DI 패턴 검사 | levnikolaevich | +| `dead-code-auditor` | 미사용 코드 탐지 | levnikolaevich | +| `build-auditor` | 컴파일러/타입 에러 검사 | levnikolaevich | +| `concurrency-auditor` | 레이스 컨디션 탐지 | levnikolaevich | +| `layer-boundary-auditor` | 레이어 위반, I/O 격리 검사 | levnikolaevich | +| `observability-auditor` | 로깅, 메트릭 적절성 검사 | levnikolaevich | +| `query-efficiency-auditor` | DB 쿼리 효율성 분석 | levnikolaevich | +| `dependencies-auditor` | 오래된 패키지, CVE 취약점 검사 | levnikolaevich | +| `regression-checker` | 기존 테스트 실행으로 사이드이펙트 탐지 | levnikolaevich | +| `story-quality-gate` | 코드리뷰 + 테스트 2단계 품질 검증 | levnikolaevich | + +### 테스트/커버리지 + +| Skill | 설명 | 출처 | +|-------|------|------| +| `app-comprehensive-test-generator` | 테스트 시나리오 생성/실행, QA 리포트 | 기존 | +| `coverage-improvement-planner` | 테스트 커버리지 분석 및 개선 계획 | 기존 | +| `test-coverage-auditor` | 테스트 커버리지 측정/분석 | levnikolaevich | +| `test-isolation-auditor` | 테스트 독립성/격리 검사 | levnikolaevich | +| `webapp-testing` | Playwright 기반 웹 앱 UI 테스트 | anthropics 공식 | + +### 보안 (Trail of Bits) + +| Skill | 설명 | 출처 | +|-------|------|------| +| `security-auditor` | 시크릿 노출, Injection, XSS 탐지 | levnikolaevich | +| `static-analysis` | CodeQL/Semgrep/SARIF 정적 분석 (3개 하위 스킬) | Trail of Bits | +| `insecure-defaults` | 위험한 기본 설정, 하드코딩 자격증명 탐지 | Trail of Bits | +| `sharp-edges` | 에러 유발 API, 위험한 디자인 패턴 탐지 | Trail of Bits | +| `differential-review` | 보안 중심 코드 변경 리뷰 | Trail of Bits | + +### 디버깅/로깅 + +| Skill | 설명 | +|-------|------| +| `system-debug-logger` | 에러/예외 자동 캡처 디버그 로깅 | +| `node-debug-logging-middleware` | Node.js Express/Koa 디버깅 로그 미들웨어 | + +### 프론트엔드/UI + +| Skill | 설명 | 출처 | +|-------|------|------| +| `frontend-design` | 프론트엔드 디자인 품질 향상 (AI slop 방지) | anthropics 공식 | +| `flutter-ux-hardening` | Flutter 앱 UI/UX 강화 | 기존 | +| `웹문서` | SAM 프로젝트 웹문서 디자인 표준 | 기존 | + +### 유틸리티 + +| Skill | 설명 | +|-------|------| +| `svg-precision` | SVG 결정론적 생성, 검증(validate), PNG 렌더링. 다이어그램/차트/아이콘에 사용 | +| `duplicate-file-cleaner` | 중복 이미지/미디어 파일 정리 | +| `npm-release-manager` | NPM 패키지 배포 자동화 | + +**사용 방법**: `/skill-name` 형식으로 호출 (예: `/code-quality-checker`) + +--- + +## 문서 작성 규칙 (개발팀 협약 - 필수 준수) + +> **경고: 개발자들이 `sam/docs`의 문서 작성 기법을 준용하기로 협약했습니다. 모든 문서 작성 시 반드시 따르세요!** + +### 참조 경로 + +- **인덱스**: `/home/aweso/sam/docs/INDEX.md` (전체 문서 목록 및 폴더 구조) +- **작업 전 확인**: 작업 유형에 맞는 문서를 `INDEX.md`에서 찾아 먼저 읽고 시작 + +### 폴더 선택 기준 (의미 기반 분류) + +| 폴더 | 질문 | 설명 | +|------|------|------| +| `plans/` | "무슨 작업을 할 것인가?" | 임시 개발 계획 (완료 후 삭제) | +| `standards/` | "어떻게 코드를 작성할 것인가?" | 코딩 컨벤션, 스타일 가이드 | +| `architecture/` | "왜 이렇게 설계하는가?" | 시스템 설계, 아키텍처 결정 | +| `rules/` | "무엇이 유효한 데이터인가?" | 비즈니스 규칙, 검증 규칙 | +| `specs/` | "무엇을 구현할 것인가?" | 기술 스펙, DB 스키마 | +| `guides/` | "어떻게 구현할 것인가?" | 단계별 구현 매뉴얼 | +| `features/` | 기능별 상세 | 기능 단위 심층 문서 | +| `changes/` | "무엇이 변경되었는가?" | 완료된 변경 이력 | + +### 파일명 규칙 + +- **일반 문서**: `kebab-case.md` (소문자 + 하이픈) 예: `api-rules.md`, `item-policy.md` +- **변경 이력**: `YYYYMMDD_short_description.md` 예: `20260109_handover_report_api.md` +- **폴더 인덱스**: `README.md` (대문자) +- **크기 목표**: 10KB 이하 +- **새 문서 작성 시**: 반드시 `docs/INDEX.md`에 추가 + +### 문서 구조 템플릿 + +#### 정책/규칙 문서 (`rules/`, `standards/`) + +```markdown +# 제목 + +> **작성일**: YYYY-MM-DD +> **상태**: 설계 확정 + +--- + +## 1. 개요 +### 1.1 목적 +### 1.2 핵심 원칙 + +--- + +## 2. 테이블 구조 (해당 시) +### 2.1 ERD 개요 + +--- + +## N. 비즈니스 규칙 +### N.1 검증 규칙 + +--- + +## N. API 엔드포인트 + +--- + +## 관련 문서 + +--- + +**최종 업데이트**: YYYY-MM-DD +``` + +#### 변경 이력 문서 (`changes/`) + +```markdown +# 변경 내용 요약 + +**날짜:** YYYY-MM-DD +**작업자:** Claude Code + +## 변경 개요 + +## 수정된 파일 +| 파일 | 변경 내용 | +|------|----------| + +## 상세 변경 사항 + +## 테스트 체크리스트 +- [x] 완료 항목 +- [ ] 미완료 항목 + +## 관련 문서 +``` + +### 작성 스타일 규칙 + +| 항목 | 규칙 | +|------|------| +| **언어** | 한글 기본, 코드/경로/기술 식별자만 영어 | +| **어조** | 서술형 ("X를 해야 한다" 아닌 "X 한다") | +| **경고** | `> **경고: ...**` 블록인용 형식 | +| **금지/필수** | `❌` 금지, `✅` 필수 접두사 | +| **우선순위** | `🔴 필수`, `🟡 중요`, `🟢 권장` | +| **섹션 번호** | `## 1.`, `### 1.1` 번호 매기기 | +| **규칙 번호** | R1, R2, R3... 순차 라벨 | +| **코드 블록** | 반드시 언어 지정 (```php, ```bash, ```json, ```sql) | +| **인라인 코드** | 파일 경로, 메서드명, 변수명, 컬럼명에 백틱 | +| **다이어그램** | `┌─┐│└─┘` 박스 문자, `→` 화살표 사용 | +| **구분선** | `---` 주요 섹션 사이마다 | +| **테이블** | API: `| Method | Path | 설명 |`, 필드: `| 필드 | 타입 | 설명 |` | + +### plans/ 워크플로우 + +1. 개발 계획 문서를 `plans/`에 작성 +2. 작업 진행 +3. 완료 후 결과물을 해당 폴더(`features/`, `changes/` 등)에 정리 +4. plan 문서 삭제 + +### 체크리스트 (문서 작성 시) + +- [ ] 적절한 폴더에 배치 (위 폴더 선택 기준 참고) +- [ ] `kebab-case.md` 파일명 사용 +- [ ] 문서 구조 템플릿 준수 +- [ ] 한글 기본, 기술 용어만 영어 +- [ ] 코드 블록에 언어 지정 +- [ ] `docs/INDEX.md`에 새 문서 등록 +- [ ] 10KB 이하 크기 유지 + +--- + +## PPT / 프레젠테이션 제작 규칙 (필수 준수) + +> **경고: 모든 프레젠테이션 및 문서 제작 시 반드시 따르세요!** + +### 회사 정보 + +| 항목 | 값 | +|------|------| +| **공식 회사명** | **(주)코드브릿지엑스** | +| **서비스명** | **SAM** (Smart Automation Management) | +| **푸터 표기 예시** | `SAM 서비스 요금 안내 | (주)코드브릿지엑스` | + +### 금지 사항 + +``` +❌ "주일/경동" — 문서, 슬라이드, 푸터 어디에도 사용 금지 +❌ "주일", "경동" 단독 사용 금지 +❌ 내부 제조사(주일/경동) 이름을 외부 문서에 노출 금지 +``` + +> **배경**: 주일/경동은 SAM을 기반으로 만든 내부 제조업체 이름이며, 대외 문서에 노출되어서는 안 된다. +> 모든 대외 문서의 회사명은 **(주)코드브릿지엑스**를 사용한다. + +### SAM BI (Brand Identity) 이미지 + +**프로젝트 내 경로**: `/home/aweso/sam/docs/assets/bi/` + +| 파일 | 용도 | 배경 | +|------|------|------| +| `sam_bi_black.png` | 밝은 배경 슬라이드 | 투명 배경, 검정 로고 | +| `sam_bi_white.png` | 다크 배경 슬라이드 | 투명 배경, 흰색 로고 | +| `sam_bi_blue.png` | 청색 테마 슬라이드 | 투명 배경, 파란 로고 | +| `sam_bi_green.png` | 녹색 테마 슬라이드 | 녹색 배경, 흰색 로고 | +| `sam_bi_red.png` | 적색/대외비 슬라이드 | 적색 배경, 흰색 로고 | +| `sam_bi_orange.png` | 주황 포인트 슬라이드 | 주황 배경, 흰색 로고 | +| `sam_bi_purple.png` | 보라 테마 슬라이드 | 보라 배경, 흰색 로고 | + +### PPT 슬라이드 제작 시 적용 규칙 + +1. **표지(slide-01)에 BI 로고 필수** — 배경색에 맞는 BI 이미지 사용 +2. **푸터에 회사명**: `(주)코드브릿지엑스` (주일/경동 절대 금지) +3. **BI 로고 + "SAM" 텍스트** 조합 사용 권장 +4. **배경색별 BI 선택**: + - 다크 배경 → `sam_bi_white.png` + - 밝은 배경 → `sam_bi_black.png` + - 테마 컬러 배경 → 해당 색상 BI (green, blue, red 등) + +### 체크리스트 (PPT 제작 시) + +- [ ] 회사명: (주)코드브릿지엑스 사용 +- [ ] "주일/경동" 미포함 확인 +- [ ] 표지에 SAM BI 로고 포함 +- [ ] 푸터에 (주)코드브릿지엑스 표기 +- [ ] 배경색에 맞는 BI 색상 선택