ERP-node/docs/메일발송_기능_사용_가이드.md

# 메일 발송 기능 사용 가이드

## 개요

노드 기반 제어관리 시스템을 통해 메일을 발송하는 방법을 설명합니다.
화면에서 데이터를 선택하고, 수신자를 지정하여 템플릿 기반의 메일을 발송할 수 있습니다.

---

## 1. 사전 준비

### 1.1 메일 계정 등록

메일 발송을 위해 먼저 SMTP 계정을 등록해야 합니다.

1. **관리자** > **메일관리** > **계정관리** 이동
2. **새 계정 추가** 클릭
3. SMTP 정보 입력:
   - 계정명: 식별용 이름 (예: "회사 공식 메일")
   - 이메일: 발신자 이메일 주소
   - SMTP 호스트: 메일 서버 주소 (예: smtp.gmail.com)
   - SMTP 포트: 포트 번호 (예: 587)
   - 보안: TLS/SSL 선택
   - 사용자명/비밀번호: SMTP 인증 정보
4. **저장** 후 **테스트 발송**으로 동작 확인

---

## 2. 제어관리 설정

### 2.1 메일 발송 플로우 생성

**관리자** > **제어관리** > **플로우 관리**에서 새 플로우를 생성합니다.

#### 기본 구조

```
[테이블 소스] → [메일 발송]
```

#### 노드 구성

1. **테이블 소스 노드** 추가

   - 데이터 소스: **컨텍스트 데이터** (화면에서 선택한 데이터 사용)
   - 또는 **테이블 전체 데이터** (주의: 전체 데이터 건수만큼 메일 발송)

2. **메일 발송 노드** 추가

   - 노드 팔레트 > 외부 실행 > **메일 발송** 드래그

3. 두 노드 연결 (테이블 소스 → 메일 발송)

---

### 2.2 메일 발송 노드 설정

메일 발송 노드를 클릭하면 우측에 속성 패널이 표시됩니다.

#### 계정 탭

| 설정           | 설명                                |
| -------------- | ----------------------------------- |
| 발송 계정 선택 | 사전에 등록한 메일 계정 선택 (필수) |

#### 메일 탭

| 설정                 | 설명                                             |
| -------------------- | ------------------------------------------------ |
| 수신자 컴포넌트 사용 | 체크 시 화면의 수신자 선택 컴포넌트 값 자동 사용 |
| 수신자 필드명        | 수신자 변수명 (기본: mailTo)                     |
| 참조 필드명          | 참조 변수명 (기본: mailCc)                       |
| 수신자 (To)          | 직접 입력 또는 변수 사용 (예: `{{email}}`)       |
| 참조 (CC)            | 참조 수신자                                      |
| 숨은 참조 (BCC)      | 숨은 참조 수신자                                 |
| 우선순위             | 높음 / 보통 / 낮음                               |

#### 본문 탭

| 설정      | 설명                             |
| --------- | -------------------------------- |
| 제목      | 메일 제목 (변수 사용 가능)       |
| 본문 형식 | 텍스트 (변수 태그 에디터) / HTML |
| 본문 내용 | 메일 본문 (변수 사용 가능)       |

#### 옵션 탭

| 설정        | 설명                |
| ----------- | ------------------- |
| 타임아웃    | 발송 제한 시간 (ms) |
| 재시도 횟수 | 실패 시 재시도 횟수 |

---

### 2.3 변수 사용 방법

메일 제목과 본문에서 `{{변수명}}` 형식으로 데이터 필드를 참조할 수 있습니다.

#### 텍스트 모드 (변수 태그 에디터)

1. 본문 형식을 **텍스트 (변수 태그 에디터)** 선택
2. 에디터에서 `@` 또는 `/` 키 입력
3. 변수 목록에서 원하는 변수 선택
4. 선택된 변수는 파란색 태그로 표시

#### HTML 모드 (직접 입력)

```html
<h1>주문 확인</h1>
<p>안녕하세요 {{customerName}}님,</p>
<p>주문번호 {{orderNo}}의 주문이 완료되었습니다.</p>
<p>금액: {{totalAmount}}원</p>
```

#### 사용 가능한 변수

| 변수             | 설명                     |
| ---------------- | ------------------------ |
| `{{timestamp}}`  | 메일 발송 시점           |
| `{{sourceData}}` | 전체 소스 데이터 (JSON)  |
| `{{필드명}}`     | 테이블 소스의 각 컬럼 값 |

---

## 3. 화면 구성

### 3.1 기본 구조

메일 발송 화면은 보통 다음과 같이 구성합니다:

```
[부모 화면: 데이터 목록]
    ↓ (모달 열기 버튼)
[모달: 수신자 입력 + 발송 버튼]
```

### 3.2 수신자 선택 컴포넌트 배치

1. **화면관리**에서 모달 화면 편집
2. 컴포넌트 팔레트 > **메일 수신자 선택** 드래그
3. 컴포넌트 설정:
   - 수신자 필드명: `mailTo` (메일 발송 노드와 일치)
   - 참조 필드명: `mailCc` (메일 발송 노드와 일치)

#### 수신자 선택 기능

- **내부 사용자**: 회사 직원 목록에서 검색/선택
- **외부 이메일**: 직접 이메일 주소 입력
- 여러 명 선택 가능 (쉼표로 구분)

### 3.3 발송 버튼 설정

1. **버튼** 컴포넌트 추가
2. 버튼 설정:
   - 액션 타입: **제어 실행**
   - 플로우 선택: 생성한 메일 발송 플로우
   - 데이터 소스: **자동** 또는 **폼 + 테이블 선택**

---

## 4. 전체 흐름 예시

### 4.1 시나리오: 선택한 주문 건에 대해 고객에게 메일 발송

#### Step 1: 제어관리 플로우 생성

```
[테이블 소스: 컨텍스트 데이터]
    ↓
[메일 발송]
    - 계정: 회사 공식 메일
    - 수신자 컴포넌트 사용: 체크
    - 제목: [주문확인] {{orderNo}} 주문이 완료되었습니다
    - 본문:
        안녕하세요 {{customerName}}님,

        주문번호 {{orderNo}}의 주문이 정상 처리되었습니다.

        - 상품명: {{productName}}
        - 수량: {{quantity}}
        - 금액: {{totalAmount}}원

        감사합니다.
```

#### Step 2: 부모 화면 (주문 목록)

- 주문 데이터 테이블
- "메일 발송" 버튼
  - 액션: 모달 열기
  - 모달 화면: 메일 발송 모달
  - 선택된 데이터 전달: 체크

#### Step 3: 모달 화면 (메일 발송)

- 메일 수신자 선택 컴포넌트
  - 수신자 (To) 입력
  - 참조 (CC) 입력
- "발송" 버튼
  - 액션: 제어 실행
  - 플로우: 메일 발송 플로우

#### Step 4: 실행 흐름

1. 사용자가 주문 목록에서 주문 선택
2. "메일 발송" 버튼 클릭 → 모달 열림
3. 수신자/참조 입력
4. "발송" 버튼 클릭
5. 제어 실행:
   - 부모 화면 데이터 (orderNo, customerName 등) + 모달 폼 데이터 (mailTo, mailCc) 병합
   - 변수 치환 후 메일 발송

---

## 5. 데이터 소스별 동작

### 5.1 컨텍스트 데이터 (권장)

- 화면에서 **선택한 데이터**만 사용
- 선택한 건수만큼 메일 발송

| 선택 건수 | 메일 발송 수 |
| --------- | ------------ |
| 1건       | 1통          |
| 5건       | 5통          |
| 10건      | 10통         |

### 5.2 테이블 전체 데이터 (주의)

- 테이블의 **모든 데이터** 사용
- 전체 건수만큼 메일 발송

| 테이블 데이터 | 메일 발송 수 |
| ------------- | ------------ |
| 100건         | 100통        |
| 1000건        | 1000통       |

**주의사항:**

- 대량 발송 시 SMTP 서버 rate limit 주의
- 테스트 시 반드시 데이터 건수 확인

---

## 6. 문제 해결

### 6.1 메일이 발송되지 않음

1. **계정 설정 확인**: 메일관리 > 계정관리에서 테스트 발송 확인
2. **수신자 확인**: 수신자 이메일 주소가 올바른지 확인
3. **플로우 연결 확인**: 테이블 소스 → 메일 발송 노드가 연결되어 있는지 확인

### 6.2 변수가 치환되지 않음

1. **변수명 확인**: `{{변수명}}`에서 변수명이 테이블 컬럼명과 일치하는지 확인
2. **데이터 소스 확인**: 테이블 소스 노드가 올바른 데이터를 가져오는지 확인
3. **데이터 전달 확인**: 부모 화면 → 모달로 데이터가 전달되는지 확인

### 6.3 수신자 컴포넌트 값이 전달되지 않음

1. **필드명 일치 확인**:
   - 수신자 컴포넌트의 필드명과 메일 발송 노드의 필드명이 일치해야 함
   - 기본값: `mailTo`, `mailCc`
2. **수신자 컴포넌트 사용 체크**: 메일 발송 노드에서 "수신자 컴포넌트 사용" 활성화

### 6.4 부모 화면 데이터가 메일에 포함되지 않음

1. **모달 열기 설정 확인**: "선택된 데이터 전달" 옵션 활성화
2. **데이터 소스 설정 확인**: 발송 버튼의 데이터 소스가 "자동" 또는 "폼 + 테이블 선택"인지 확인

---

## 7. 고급 기능

### 7.1 조건부 메일 발송

조건 분기 노드를 사용하여 특정 조건에서만 메일을 발송할 수 있습니다.

```
[테이블 소스]
    ↓
[조건 분기: status === 'approved']
    ↓ (true)
[메일 발송: 승인 알림]
```

### 7.2 다중 수신자 처리

수신자 필드에 쉼표로 구분하여 여러 명에게 동시 발송:

```
{{managerEmail}}, {{teamLeadEmail}}, external@example.com
```

### 7.3 HTML 템플릿 활용

본문 형식을 HTML로 설정하면 풍부한 형식의 메일을 보낼 수 있습니다:

```html
<!DOCTYPE html>
<html>
  <head>
    <style>
      .header {
        background: #4a90d9;
        color: white;
        padding: 20px;
      }
      .content {
        padding: 20px;
      }
      .footer {
        background: #f5f5f5;
        padding: 10px;
        font-size: 12px;
      }
    </style>
  </head>
  <body>
    <div class="header">
      <h1>주문 확인</h1>
    </div>
    <div class="content">
      <p>안녕하세요 <strong>{{customerName}}</strong>님,</p>
      <p>주문번호 <strong>{{orderNo}}</strong>의 주문이 완료되었습니다.</p>
      <table>
        <tr>
          <td>상품명</td>
          <td>{{productName}}</td>
        </tr>
        <tr>
          <td>금액</td>
          <td>{{totalAmount}}원</td>
        </tr>
      </table>
    </div>
    <div class="footer">본 메일은 자동 발송되었습니다.</div>
  </body>
</html>
```

---

## 8. 체크리스트

메일 발송 기능 구현 시 확인 사항:

- [ ] 메일 계정이 등록되어 있는가?
- [ ] 메일 계정 테스트 발송이 성공하는가?
- [ ] 제어관리에 메일 발송 플로우가 생성되어 있는가?
- [ ] 테이블 소스 노드의 데이터 소스가 올바르게 설정되어 있는가?
- [ ] 메일 발송 노드에서 계정이 선택되어 있는가?
- [ ] 수신자 컴포넌트 사용 시 필드명이 일치하는가?
- [ ] 변수명이 테이블 컬럼명과 일치하는가?
- [ ] 부모 화면에서 모달로 데이터가 전달되는가?
- [ ] 발송 버튼의 데이터 소스가 올바르게 설정되어 있는가?