# SAM ERP Frontend Documentation

> **프로젝트**: SAM ERP Next.js 프론트엔드
> **최종 갱신**: 2026-03-18
> **현재 문서 버전**: v1 (운영 중) / v2 (설계 중)

---

## 문서 구조

```
frontend/
├── _index.md              ← 현재 문서 (목록 + 버전 관리)
├── v1/                    ← 현재 활성 버전 (운영 중)
│   ├── 01 ~ 09            ← 프론트엔드 아키텍처/가이드
│   ├── 10                 ← API 연동 스펙
│   └── 11                 ← 브라우저 네비게이션 규칙 (AI/자동화)
├── v2/                    ← 차기 버전 (동적 멀티테넌트, 설계 중)
│   └── 01                 ← 동적 멀티테넌트 페이지 시스템 설계
└── api-specs/             ← (레거시, v1/10으로 이관됨)
```

---

## 문서 목록 및 버전 현황

| # | 문서 | 버전 | 최종 수정 | 담당 | 대상 | 설명 |
|---|------|------|----------|------|------|------|
| 00 | [onboarding](v1/00-onboarding.md) | 1.0.0 | 2026-03-20 | Frontend | 전체 | 신규 합류자 온보딩 (시스템 개요, 도메인 맵, 읽기 순서) |
| 01 | [architecture](v1/01-architecture.md) | 1.0.0 | 2026-03-09 | Frontend | 전체 | 프로젝트 구조, 기술 스택, 디렉토리 설계 |
| 02 | [api-pattern](v1/02-api-pattern.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | API 통신 패턴 (프록시, Server Action, buildApiUrl) |
| 03 | [component-design](v1/03-component-design.md) | 1.0.0 | 2026-03-09 | Frontend | FE/기획 | 컴포넌트 계층 (atoms → templates), 페이지 유형 |
| 04 | [common-components](v1/04-common-components.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 공통 컴포넌트 사용법 (UniversalListPage 등) |
| 05 | [form-pattern](v1/05-form-pattern.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 폼 패턴 (Zod, FormField, react-hook-form) |
| 06 | [styling-guide](v1/06-styling-guide.md) | 1.0.0 | 2026-03-09 | Frontend | FE/디자인 | CSS 규칙 (Tailwind, shadcn/ui, 색상 시스템) |
| 07 | [auth-flow](v1/07-auth-flow.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | 인증 흐름 (HttpOnly cookie, 토큰 갱신) |
| 08 | [dashboard-system](v1/08-dashboard-system.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | CEO 대시보드 아키텍처 (invalidation, hooks) |
| 09 | [conventions](v1/09-conventions.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 네이밍, import, 파일 배치, Git 규칙 |
| 10 | [document-api-integration](v1/10-document-api-integration.md) | 1.0.0 | 2026-02-05 | API Team | FE/BE | 문서 관리 API 연동 (검사 성적서 resolve/upsert) |
| 11 | [browser-navigation-rules](v1/11-browser-navigation-rules.md) | 1.0.0 | 2026-03-10 | Frontend | AI/QA | 브라우저 네비게이션 규칙 (URL 추측 금지, 메뉴 클릭 필수) |
| 12 | [permission-whitelist](v1/12-permission-whitelist.md) | 1.0.0 | 2026-03-20 | Frontend | FE/BE | 권한 기반 페이지 접근 제어 (화이트리스트, 바이패스, 모듈 역할 분담) |

### v2 — 동적 멀티테넌트 시스템 (설계 중)

| # | 문서 | 버전 | 최종 수정 | 담당 | 대상 | 설명 |
|---|------|------|----------|------|------|------|
| 01 | [dynamic-multi-tenant-page-system](v2/01-dynamic-multi-tenant-page-system.md) | 1.3.0 | 2026-03-18 | FE/BE | 전체 | 동적 멀티테넌트 페이지 시스템 설계 (17개 규칙, JSON config, 동적 라우팅, 권한 통합, 테넌트 분류, 선결과제) |

> **v2 상태**: 초안 — 백엔드 회의 후 협의 항목 확정 예정

### 대상 범례
- **FE**: 프론트엔드 개발자
- **BE**: 백엔드 개발자
- **기획**: 기획자/PM
- **디자인**: 디자이너
- **전체**: 모든 역할

---

## 버전 변경 이력

### v2 (2026-03-11 ~)

| 날짜 | 문서 | 변경 | 버전 |
|------|------|------|------|
| 2026-03-11 | 01 | 동적 멀티테넌트 페이지 시스템 설계 초안 작성 | 1.1.0 |
| 2026-03-18 | 01 | JSONB 저장 확정, 테넌트 분류(3종), 선결과제 4개, 의존성 위반 목록 추가 | 1.3.0 |

### v1 (2026-03-09 ~)

| 날짜 | 문서 | 변경 | 버전 |
|------|------|------|------|
| 2026-03-09 | 01~09 | 초기 작성 | 1.0.0 |
| 2026-02-05 | 10 | 문서 API 연동 가이드 작성 (api-specs에서 이관) | 1.0.0 |
| 2026-03-10 | 11 | 브라우저 네비게이션 규칙 추가 (AI/E2E URL 추측 금지) | 1.0.0 |
| 2026-03-20 | 12 | 권한 기반 페이지 접근 제어 — PermissionGate 화이트리스트 전환, 바이패스 경로, 모듈 시스템 역할 분담 | 1.0.0 |
| 2026-03-20 | 00 | 신규 합류자 온보딩 가이드 — 시스템 개요, 테넌트 구조, 도메인 맵, 상태관리, 라우팅 패턴, 읽기 순서 | 1.0.0 |

---

## 버전 관리 규칙

### 문서 버전 (Semantic Versioning)

```
MAJOR.MINOR.PATCH

MAJOR: 문서 구조 변경, 기존 내용 대폭 수정
MINOR: 새로운 섹션 추가, 기존 내용 보완
PATCH: 오탈자, 코드 예시 수정, 사소한 수정
```

### 업데이트 절차

1. 해당 문서 내용 수정
2. 문서 상단 `버전`과 `최종 수정` 날짜 갱신
3. 이 `_index.md`의 문서 목록 테이블 버전/날짜 갱신
4. 변경 이력 테이블에 행 추가

### 새 문서 추가 시

1. `v1/` 폴더에 `{번호}-{주제}.md` 형식으로 생성
2. 문서 상단에 버전/날짜/대상 헤더 포함
3. `_index.md` 문서 목록 테이블에 행 추가

---

## 빠른 참고

| 할 일 | 읽을 문서 |
|-------|----------|
| **프로젝트에 처음 합류** | **v1/00-onboarding (여기서 시작)** |
| 프로젝트 전체 구조 이해 | v1/01-architecture |
| API 호출 방법 알기 | v1/02-api-pattern |
| 새 리스트 페이지 만들기 | v1/03-component-design → v1/04-common-components |
| 새 폼 페이지 만들기 | v1/05-form-pattern |
| 디자인/스타일 규칙 확인 | v1/06-styling-guide |
| 인증 동작 이해 | v1/07-auth-flow |
| 대시보드 연동 작업 | v1/08-dashboard-system |
| 코딩 컨벤션 확인 | v1/09-conventions |
| 문서 관리 API 연동 | v1/10-document-api-integration |
| AI/E2E 페이지 이동 규칙 | v1/11-browser-navigation-rules |
| 권한 기반 접근 제어 이해 | v1/12-permission-whitelist |
| **동적 멀티테넌트 설계** | **v2/01-dynamic-multi-tenant-page-system** |
