# WACE ERP Backend - 분석 문서 인덱스

> **분석 완료일**: 2026-02-06  
> **분석자**: Backend Specialist

---

## 📚 문서 목록

### 1. 📖 상세 분석 문서
**파일**: `backend-architecture-detailed-analysis.md`  
**내용**: 백엔드 전체 아키텍처 상세 분석 (16개 섹션)

- 전체 개요 및 기술 스택
- 디렉토리 구조
- 미들웨어 스택 구성
- 인증/인가 시스템 (JWT, 3단계 권한)
- 멀티테넌시 구현 방식
- API 라우트 전체 목록
- 비즈니스 도메인별 모듈 (8개 도메인)
- 데이터베이스 접근 방식 (Raw Query)
- 외부 시스템 연동 (DB/REST API)
- 배치/스케줄 처리 (node-cron)
- 파일 처리 (multer)
- 에러 핸들링
- 로깅 시스템 (Winston)
- 보안 및 권한 관리
- 성능 최적화

**특징**: 워크플로우 문서에 통합하기 위한 완전한 아키텍처 분석

---

### 2. 📄 요약 문서
**파일**: `backend-architecture-summary.md`  
**내용**: 백엔드 아키텍처 핵심 요약 (16개 섹션 압축)

- 기술 스택 요약
- 계층 구조 다이어그램
- 디렉토리 구조
- 미들웨어 스택 순서
- 인증/인가 흐름도
- 멀티테넌시 핵심 원칙
- API 라우트 카테고리별 정리
- 비즈니스 도메인 8개 요약
- 데이터베이스 접근 패턴
- 외부 연동 아키텍처
- 배치 스케줄러 시스템
- 파일 처리 흐름
- 보안 정책
- 에러 핸들링 전략
- 로깅 구조
- 성능 최적화 전략
- **핵심 체크리스트** (개발 시 필수 규칙 8개)

**특징**: 빠른 참조를 위한 간결한 요약

---

### 3. 🔗 API 라우트 완전 매핑
**파일**: `backend-api-route-mapping.md`  
**내용**: 프론트엔드 개발자용 API 엔드포인트 전체 목록 (200+개)

#### 포함된 API 카테고리
1. 인증 API (7개)
2. 관리자 API (15개)
3. 테이블 관리 API (30개)
4. 화면 관리 API (10개)
5. 플로우 API (15개)
6. 데이터플로우 API (10개)
7. 외부 연동 API (15개)
8. 배치 API (10개)
9. 메일 API (5개)
10. 파일 API (5개)
11. 대시보드 API (5개)
12. 공통코드 API (3개)
13. 다국어 API (3개)
14. 회사 관리 API (4개)
15. 부서 API (2개)
16. 권한 그룹 API (2개)
17. DDL 실행 API (1개)
18. 외부 API 프록시 (2개)
19. 디지털 트윈 API (3개)
20. 3D 필드 API (2개)
21. 스케줄 API (1개)
22. 채번 규칙 API (3개)
23. 엔티티 검색 API (2개)
24. To-Do API (3개)
25. 예약 요청 API (2개)
26. 리스크/알림 API (2개)
27. 헬스 체크 (1개)

#### 각 API 정보 포함
- HTTP 메서드
- 엔드포인트 경로
- 필요 권한 (공개/인증/관리자/슈퍼관리자)
- 기능 설명
- Request Body/Query Params
- Response 형식

#### 추가 정보
- Base URL (개발/운영)
- 공통 헤더 (Authorization)
- 응답 형식 (성공/에러)
- 에러 코드 목록

**특징**: 프론트엔드에서 API 호출 시 즉시 참조 가능

---

### 4. 📊 JSON 응답 요약
**파일**: `backend-analysis-response.json`  
**내용**: 구조화된 JSON 형식의 분석 결과

```json
{
  "status": "success",
  "confidence": "high",
  "result": {
    "summary": "...",
    "details": "...",
    "files_affected": [...],
    "key_findings": {
      "architecture_pattern": "...",
      "tech_stack": {...},
      "middleware_stack": [...],
      "authentication_flow": {...},
      "permission_levels": {...},
      "multi_tenancy": {...},
      "business_domains": {...},
      "database_access": {...},
      "security": {...},
      "performance_optimization": {...}
    },
    "critical_rules": [...]
  }
}
```

**특징**: 프로그래밍 방식으로 분석 결과 활용 가능

---

## 🎯 핵심 요약

### 아키텍처
- **패턴**: Layered Architecture (Controller → Service → Database)
- **언어**: TypeScript (Strict Mode)
- **프레임워크**: Express.js
- **데이터베이스**: PostgreSQL (Raw Query, Connection Pool)
- **인증**: JWT (24시간 만료, 자동 갱신)

### 멀티테넌시
```typescript
// ✅ 핵심 원칙
const companyCode = req.user!.companyCode; // JWT에서 추출

if (companyCode === "*") {
  // 슈퍼관리자: 모든 데이터
  query = "SELECT * FROM table ORDER BY company_code";
} else {
  // 일반 사용자: 자기 회사만 + 슈퍼관리자 숨김
  query = "SELECT * FROM table WHERE company_code = $1 AND company_code != '*'";
  params = [companyCode];
}
```

### 권한 체계 (3단계)
1. **SUPER_ADMIN** (`company_code = "*"`)
   - 전체 회사 데이터 접근
   - DDL 실행, 회사 생성/삭제

2. **COMPANY_ADMIN** (`company_code = "ILSHIN"`)
   - 자기 회사 데이터만 접근
   - 사용자/설정 관리

3. **USER** (`company_code = "ILSHIN"`)
   - 자기 회사 데이터만 접근
   - 읽기/쓰기만

### 주요 도메인 (8개)
1. **관리자** - 사용자/메뉴/권한
2. **테이블/화면** - 메타데이터, 동적 화면
3. **플로우** - 워크플로우 엔진
4. **데이터플로우** - ERD, 관계도
5. **외부 연동** - 외부 DB/REST API
6. **배치** - Cron 스케줄러
7. **메일** - 발송/수신
8. **파일** - 업로드/다운로드

### API 통계
- **총 라우트**: 70+개
- **총 API**: 200+개
- **컨트롤러**: 70+개
- **서비스**: 80+개
- **미들웨어**: 4개

---

## 🚨 개발 시 필수 규칙

✅ **모든 쿼리에 `company_code` 필터 추가**  
✅ **JWT 토큰에서 `company_code` 추출 (클라이언트 신뢰 금지)**  
✅ **Parameterized Query 사용 (SQL Injection 방지)**  
✅ **슈퍼관리자 데이터 숨김 (`company_code != '*'`)**  
✅ **비밀번호는 bcrypt, 민감정보는 AES-256**  
✅ **에러 핸들링 try/catch 필수**  
✅ **트랜잭션이 필요한 경우 `transaction()` 사용**  
✅ **파일 업로드는 회사별 디렉토리 분리**

---

## 📁 문서 위치

```
ERP-node/docs/
├── backend-architecture-detailed-analysis.md  (상세 분석, 16개 섹션)
├── backend-architecture-summary.md            (요약, 간결한 참조)
├── backend-api-route-mapping.md               (API 200+개 전체 매핑)
└── backend-analysis-response.json             (JSON 구조화 데이터)
```

---

## 🔍 문서 사용 가이드

### 처음 백엔드를 이해하려면
→ `backend-architecture-summary.md` 읽기 (20분)

### 특정 기능을 구현하려면
→ `backend-architecture-detailed-analysis.md`에서 해당 도메인 섹션 참조

### API를 호출하려면
→ `backend-api-route-mapping.md`에서 엔드포인트 검색

### 워크플로우 문서에 통합하려면
→ `backend-architecture-detailed-analysis.md` 전체 복사

### 프로그래밍 방식으로 활용하려면
→ `backend-analysis-response.json` 파싱

---

**문서 버전**: 1.0  
**마지막 업데이트**: 2026-02-06  
**다음 업데이트 예정**: 신규 API 추가 시
