# 초대 코드 직접 입력 기능 구현 계획

**작성일**: 2025-11-24
**목적**: 폐쇄망 환경에서 이메일 링크를 사용할 수 없는 사용자를 위한 8자리 초대코드 직접 입력 기능 추가

---

## 📌 개요

### 배경
- 현재 초대 시스템은 이메일 링크 방식만 지원
- 폐쇄망 환경에서는 이메일 링크 클릭이 불가능
- 8자리 토큰(예: K7MNPQ2R)을 생성하고 있지만 직접 입력 UI가 없음

### 목표
1. 로그인 페이지에 "초대를 받으셨나요?" 링크 추가
2. 초대코드 직접 입력 페이지 생성
3. 기존 회원 로그인 시 자동으로 초대 확인 및 리다이렉트

---

## 🎯 구현 대상 사용자 플로우

### 신규 회원 (미가입자)
```
로그인 페이지 → "초대를 받으셨나요?" 클릭 → 초대코드 입력 → 검증 성공 → 회원가입 페이지
```

### 기존 회원 (ROLE_USER)
```
방법1: 로그인 페이지 → "초대를 받으셨나요?" 클릭 → 로그인 유도 → 로그인 → 자동 초대 확인 → 초대 수락 페이지
방법2: 로그인 페이지 → 로그인 → 자동 초대 확인 → 초대 수락 페이지
```

---

## 🛠 작업 목록

### 0. 마이페이지 초대 알림 (재방문 사용자 대응)

로그인 후 자동 리다이렉트를 놓친 사용자나, 페이지를 벗어났다가 다시 돌아온 사용자를 위해 마이페이지에서 초대 알림을 표시합니다.

#### 0.1 AccountController 수정
**파일**: `src/main/java/com/eactive/apim/portal/apps/user/controller/AccountController.java`

**GET /mypage 메서드 수정** (119-149라인):

```java
@GetMapping("/mypage")
public ModelAndView mypage() {
    ModelAndView mav = new ModelAndView();

    try {
        PortalAuthenticatedUser currentUser = SecurityUtil.getPortalAuthenticatedUser();
        PortalUserDTO user = userFacade.findById(currentUser.getId());

        // ===== 새로 추가: 초대 확인 로직 =====
        // ROLE_USER만 초대 확인 (법인 회원은 제외)
        if (currentUser.getRoleCode() == RoleCode.ROLE_USER) {
            Optional<UserInvitation> pendingInvitation =
                userInvitationRepository.findFirstByInvitationEmailAndStatus(
                    currentUser.getLoginId(), InvitationStatus.PENDING);

            if (pendingInvitation.isPresent()) {
                // 초대 정보를 모델에 추가
                mav.addObject("hasPendingInvitation", true);

                // 초대한 법인명 조회
                String orgId = pendingInvitation.get().getOrgId();
                Optional<PortalOrg> org = portalOrgRepository.findById(orgId);
                if (org.isPresent()) {
                    mav.addObject("invitationOrgName", org.get().getOrgName());
                }
            }
        }
        // ================================

        // 기존 로직
        mav.addObject("loginId", user.getLoginId());
        mav.addObject("userName", user.getUserName());
        mav.addObject("mobileNumber", user.getMobileNumber());
        mav.addObject("user", user);

        // ... 기존 코드 계속
    }
}
```

**추가 필드**:
```java
private final UserInvitationRepository userInvitationRepository;
private final PortalOrgRepository portalOrgRepository;
```

**예상 작업량**: 20-25줄 추가

---

#### 0.2 마이페이지 레이아웃 수정 (옵션 1: 공통 알림)
**파일**: `src/main/resources/templates/views/layout/kbank_mypage_layout.html`

**헤더 다음에 알림 배너 추가**:

```html
<header th:replace="fragment/kbank/header :: headerFragment"></header>

<!-- 초대 알림 배너 (모든 마이페이지에서 표시) -->
<div th:if="${hasPendingInvitation}" class="invitation-alert-banner">
    <div class="alert alert-info invitation-banner">
        <div class="invitation-content">
            <span class="icon">📩</span>
            <div class="message">
                <strong th:text="${invitationOrgName}">법인명</strong>에서 귀하를 법인회원으로 초대하였습니다.
            </div>
            <a th:href="@{/signup/decision_process}" class="btn btn-primary btn-sm">
                초대 확인하기
            </a>
        </div>
    </div>
</div>

<section layout:fragment="contentFragment">
</section>
```

**CSS 스타일**:
```css
.invitation-alert-banner {
    background: #e3f2fd;
    border-bottom: 2px solid #2196F3;
    padding: 15px 0;
}

.invitation-banner {
    max-width: 1200px;
    margin: 0 auto;
    display: flex;
    align-items: center;
    padding: 12px 20px;
    background: white;
    border-radius: 8px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.invitation-content {
    display: flex;
    align-items: center;
    gap: 15px;
    width: 100%;
}

.invitation-content .icon {
    font-size: 24px;
}

.invitation-content .message {
    flex: 1;
    font-size: 14px;
    color: #333;
}

.invitation-content .btn {
    white-space: nowrap;
}
```

**예상 작업량**: 50-60줄 (HTML + CSS)

---

#### 0.3 내 정보 관리 페이지 알림 (옵션 2: 페이지별 알림)
**파일**: `src/main/resources/templates/views/apps/mypage/updatePersonalUser.html`

**페이지 상단에 알림 추가** (8-10라인 다음):

```html
<div class="sub_title3">
    <h2 class="title">내 정보 관리</h2>
</div>

<!-- 초대 알림 -->
<div th:if="${hasPendingInvitation}" class="alert alert-info invitation-alert">
    <h4>📩 법인회원 초대</h4>
    <p>
        <strong th:text="${invitationOrgName}">법인명</strong>에서 귀하를 법인회원으로 초대하였습니다.
    </p>
    <div class="btn_wrap mt-3">
        <a th:href="@{/signup/decision_process}" class="common_btn_type_1">
            <span>초대 확인하기</span>
        </a>
    </div>
</div>

<div class="inner i_cs h_inner8">
    <!-- 기존 폼 내용 -->
</div>
```

**CSS 스타일**:
```css
.invitation-alert {
    background: #e3f2fd;
    border: 2px solid #2196F3;
    border-radius: 8px;
    padding: 20px;
    margin: 20px 0;
    text-align: center;
}

.invitation-alert h4 {
    color: #1976D2;
    margin-bottom: 10px;
    font-size: 18px;
}

.invitation-alert p {
    color: #333;
    margin-bottom: 15px;
    font-size: 14px;
}
```

**예상 작업량**: 40-50줄 (HTML + CSS)

---

#### 0.4 선택 기준

**옵션 1 (레이아웃 수정)** 추천:
- ✅ 모든 마이페이지에서 초대 알림 표시
- ✅ 일관된 UX
- ✅ 수정 파일 적음 (1개 레이아웃 파일)

**옵션 2 (개별 페이지 수정)**:
- ✅ 페이지별 커스터마이징 가능
- ❌ 여러 파일 수정 필요 (updatePersonalUser, updateCorporateUser, updateCorporateManager 등)
- ❌ 일부 페이지에서 놓칠 가능성

**권장**: 옵션 1 (레이아웃 수정)

---

#### 0.5 테스트 시나리오

**시나리오 1: 로그인 후 초대 자동 확인 놓침**
1. 로그인 시 초대 자동 리다이렉트 발생
2. 사용자가 뒤로가기나 다른 페이지 이동
3. 마이페이지 접속
4. 상단에 초대 알림 배너 표시 ✅
5. "초대 확인하기" 클릭 → /signup/decision_process 이동

**시나리오 2: 세션 만료 후 재로그인**
1. 로그인 세션 만료
2. 재로그인
3. 자동 리다이렉트 없음 (세션 초기화)
4. 마이페이지 접속
5. 초대 알림 표시 ✅

**시나리오 3: 초대 수락 후 알림 제거**
1. 마이페이지에서 초대 알림 확인
2. "초대 확인하기" 클릭 → 초대 수락
3. 마이페이지 재방문
4. 초대 알림 없음 ✅ (PENDING 상태 아님)

**시나리오 4: 법인 회원은 알림 표시 안 됨**
1. ROLE_CORP_USER로 로그인
2. 마이페이지 접속
3. 초대 알림 없음 ✅ (ROLE_USER만 표시)

---

### 1. 프론트엔드 (Thymeleaf Templates)

#### 1.1 로그인 페이지 수정
**파일**: `src/main/resources/templates/views/apps/login/login.html`

**수정 위치**: 53-73라인 `login_list` 영역

**작업 내용**:
```html
<li class="icon_invite">
    <img th:src="@{/img/icon/icon_login_invite.png}" alt="">
    <a th:href="@{/signup/invitation-code}">초대를 받으셨나요?</a>
</li>
<li>
    <span>|</span>
</li>
```

**예상 작업량**: 10줄 추가

---

#### 1.2 초대코드 입력 페이지 생성 (신규)
**파일**: `src/main/resources/templates/views/apps/register/invitationCodeInput.html`

**작업 내용**:
- 8자리 초대코드 입력 폼
- 대문자 자동 변환 (JavaScript)
- CSRF 토큰 포함
- 검증 실패 시 에러 메시지 표시

**UI 요구사항**:
- 입력 필드: 8자리 영문+숫자 (예: K7MNPQ2R)
- 실시간 대문자 변환
- 제출 버튼: "확인"
- 취소 버튼: "돌아가기" (로그인 페이지로)

**예상 작업량**: 100-120줄

**예시 구조**:
```html
<form th:action="@{/signup/invitation-code}" method="post">
    <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}"/>

    <div class="form_type_box">
        <div class="info1">
            <p class="title">초대코드</p>
            <div class="info_line">
                <input type="text" name="invitationCode"
                       maxlength="8"
                       placeholder="8자리 초대코드 입력 (예: K7MNPQ2R)"
                       pattern="[A-Z0-9]{8}"
                       required>
            </div>
        </div>
    </div>

    <div class="btn_login">
        <button type="submit">확인</button>
    </div>
</form>
```

**JavaScript 기능**:
- 자동 대문자 변환
- 8자리 제한
- 영문+숫자만 입력 허용

---

### 2. 백엔드 (Java Controller)

#### 2.1 UserRegisterController 수정
**파일**: `src/main/java/com/eactive/apim/portal/apps/user/controller/UserRegisterController.java`

**추가 엔드포인트**:

##### 2.1.1 GET /signup/invitation-code
```java
@GetMapping("/signup/invitation-code")
public String showInvitationCodeInput(HttpSession session, Model model) {
    // 초대코드 입력 페이지 표시
    return "apps/register/invitationCodeInput";
}
```

##### 2.1.2 POST /signup/invitation-code
```java
@PostMapping("/signup/invitation-code")
public String processInvitationCode(
        @RequestParam("invitationCode") String invitationCode,
        HttpSession session,
        RedirectAttributes redirectAttributes,
        Model model) {

    // 1. 입력값 검증 (8자리, 영문+숫자)
    if (!invitationCode.matches("[A-Z0-9]{8}")) {
        model.addAttribute("error", "올바른 형식의 초대코드를 입력해주세요.");
        return "apps/register/invitationCodeInput";
    }

    // 2. DB에서 토큰 조회
    Optional<UserInvitation> invitation =
        userInvitationRepository.findByToken(invitationCode);

    // 3. 유효성 검증
    if (!invitation.isPresent() ||
        invitation.get().getStatus() != UserInvitationEnums.InvitationStatus.PENDING) {
        model.addAttribute("error", "유효하지 않은 초대코드입니다.");
        return "apps/register/invitationCodeInput";
    }

    // 4. 만료 확인
    if (invitation.get().getExpiresOn().isBefore(LocalDateTime.now())) {
        model.addAttribute("error", "만료된 초대코드입니다.");
        return "apps/register/invitationCodeInput";
    }

    // 5. 사용자 존재 확인
    String email = invitation.get().getInvitationEmail();
    Optional<PortalUser> existingUser =
        portalUserRepository.findPortalUserByEmailAddr(email);

    if (existingUser.isPresent()) {
        // 기존 회원 → 로그인 유도
        session.setAttribute("invitationCodeForLogin", invitationCode);
        redirectAttributes.addFlashAttribute("message",
            "로그인하여 초대를 수락해주세요.");
        return "redirect:/login";
    } else {
        // 신규 회원 → 가입 페이지
        return "redirect:/signup/portalUser?invitation=" + invitationCode;
    }
}
```

**예상 작업량**: 50-60줄

---

#### 2.2 PortalAuthenticationSuccessHandler 수정
**파일**: `src/main/java/com/eactive/apim/portal/config/PortalAuthenticationSuccessHandler.java`

**수정 위치**: `onAuthenticationSuccess()` 메서드 (38-83라인)

**추가 로직**:
```java
@Override
public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response,
                                    Authentication authentication) throws IOException, ServletException {
    String username = request.getParameter("id");
    PortalUser user = portalUserRepository.findPortalUserByEmailAddr(username).orElse(null);

    // ... 기존 로직 (이메일 인증, 휴면 계정, 비밀번호 만료 체크)

    // ===== 새로 추가 =====
    // 초대 코드 자동 확인 (ROLE_USER 회원만)
    if (user.getRoleCode() == RoleCode.ROLE_USER) {
        Optional<UserInvitation> pendingInvitation =
            userInvitationRepository.findFirstByInvitationEmailAndStatus(
                username, InvitationStatus.PENDING);

        if (pendingInvitation.isPresent()) {
            // 초대가 있으면 자동으로 초대 수락 페이지로 리다이렉트
            response.sendRedirect(contextPath + "/signup/decision_process");
            return;
        }
    }
    // ==================

    // 기존 decisionToken 체크 로직
    String decisionToken = (String) request.getSession().getAttribute("decisionToken");
    if (decisionToken != null) {
        response.sendRedirect(contextPath + "/signup/decision_process");
    } else {
        response.sendRedirect(contextPath + "/");
    }
}
```

**추가 필드**:
```java
private final UserInvitationRepository userInvitationRepository;
```

**예상 작업량**: 15줄 추가

---

### 3. 보안 설정 (선택사항)

#### 3.1 PortalConfigSecurity 확인
**파일**: `src/main/java/com/eactive/apim/portal/config/PortalConfigSecurity.java`

**확인 사항**:
- `/signup/invitation-code` 경로가 인증 없이 접근 가능한지 확인
- CSRF 토큰이 적용되는지 확인

**예상 설정** (이미 `/signup/**`이 허용되어 있을 가능성 높음):
```java
.antMatchers("/signup/**").permitAll()
```

---

## 🔍 테스트 계획

### 단위 테스트

#### 3.1 Controller 테스트
```java
@SpringBootTest
@AutoConfigureMockMvc
class InvitationCodeInputTest extends BaseWebTest {

    @Test
    void testValidInvitationCode_NewUser() {
        // 신규 회원용 유효한 코드 입력 → 가입 페이지로 리다이렉트
    }

    @Test
    void testValidInvitationCode_ExistingUser() {
        // 기존 회원용 유효한 코드 입력 → 로그인 페이지로 리다이렉트
    }

    @Test
    void testInvalidInvitationCode() {
        // 존재하지 않는 코드 → 에러 메시지
    }

    @Test
    void testExpiredInvitationCode() {
        // 만료된 코드 → 에러 메시지
    }

    @Test
    void testAlreadyProcessedCode() {
        // 이미 처리된 코드(COMPLETED) → 에러 메시지
    }
}
```

#### 3.2 AuthenticationSuccessHandler 테스트
```java
@Test
void testAutoRedirectWithPendingInvitation() {
    // ROLE_USER 로그인 시 초대가 있으면 자동 리다이렉트
}

@Test
void testNoAutoRedirectForCorpUser() {
    // ROLE_CORP_USER는 자동 리다이렉트 안됨
}
```

### 통합 테스트 시나리오

#### 시나리오 1: 신규 회원 초대코드 입력
1. 로그인 페이지 접속
2. "초대를 받으셨나요?" 클릭
3. 초대코드 입력 (예: K7MNPQ2R)
4. 회원가입 페이지로 이동
5. 가입 완료

**예상 결과**: ROLE_CORP_USER로 가입 완료

---

#### 시나리오 2: 기존 회원 초대코드 입력 후 로그인
1. 로그인 페이지 접속
2. "초대를 받으셨나요?" 클릭
3. 초대코드 입력 (예: K7MNPQ2R)
4. "로그인하여 초대를 수락해주세요" 메시지
5. 로그인 페이지로 리다이렉트
6. 로그인
7. 자동으로 초대 수락 페이지로 이동
8. 약관 동의 후 수락
9. 로그아웃 후 재로그인

**예상 결과**: ROLE_USER → ROLE_CORP_USER 전환 완료

---

#### 시나리오 3: 기존 회원 직접 로그인 (초대 자동 확인)
1. 로그인 페이지 접속
2. 로그인 (초대받은 이메일로)
3. 자동으로 초대 수락 페이지로 리다이렉트
4. 약관 동의 후 수락

**예상 결과**: 초대 수락 완료

---

#### 시나리오 4: 유효하지 않은 초대코드
1. 초대코드 입력 페이지 접속
2. 존재하지 않는 코드 입력 (예: INVALID1)
3. "유효하지 않은 초대코드입니다" 에러 메시지
4. 입력 페이지 유지

**예상 결과**: 에러 메시지 표시, 재입력 가능

---

#### 시나리오 5: 만료된 초대코드
1. 초대코드 입력 페이지 접속
2. 7일 이상 경과한 코드 입력
3. "만료된 초대코드입니다" 에러 메시지

**예상 결과**: 에러 메시지 표시

---

## ⚠️ 주의사항 및 고려사항

### 보안
- [ ] CSRF 토큰 적용 확인
- [ ] SQL Injection 방지 (JPA 사용으로 기본 방어)
- [ ] **초대코드 Brute Force 공격 방지 (세션 기반 실패 횟수 제한)** - 아래 상세 구현 방법 참조
- [ ] 세션 하이재킹 방지 (기존 Spring Security로 대응)
- [ ] 이메일 형식 검증 (프론트엔드 + 백엔드 이중 검증) ✅ 구현 완료

### 사용성
- [ ] 입력 필드 자동 대문자 변환
- [ ] 8자리 제한 및 유효성 검증 (클라이언트 + 서버)
- [ ] 명확한 에러 메시지
- [ ] 모바일 반응형 디자인

### 우선순위 충돌 처리
`PortalAuthenticationSuccessHandler`에서 여러 조건 체크 순서:

1. 이메일 인증 필요 (`READY` 상태)
2. 휴면 계정 (`DORMANT` 상태)
3. 임시 비밀번호 로그인
4. 비밀번호 만료 (90일)
5. **→ [새로 추가] 초대 코드 확인** ← ROLE_USER만 해당
6. decisionToken 세션 체크
7. 일반 홈페이지

**결정**: 비밀번호 관련 체크 이후, 일반 홈 이동 전에 초대 확인

---

## 📊 작업 규모 요약

| 항목 | 파일 수 | 예상 코드량 | 난이도 | 예상 시간 |
|------|---------|------------|--------|----------|
| **마이페이지 초대 알림** | 2 | 70-85줄 | ⭐⭐ 보통 | 1시간 |
| HTML 수정 (로그인) | 1 | 10줄 | ⭐ 쉬움 | 15분 |
| HTML 신규 (초대코드 입력) | 1 | 100-120줄 | ⭐⭐ 보통 | 1-1.5시간 |
| Controller 수정 (UserRegister) | 1 | 50-60줄 | ⭐⭐ 보통 | 1시간 |
| Handler 수정 | 1 | 15줄 | ⭐⭐ 보통 | 30분 |
| 단위 테스트 | 2 | 100줄 | ⭐⭐ 보통 | 1시간 |
| 통합 테스트 | - | 수동 | ⭐⭐⭐ 중요 | 2-2.5시간 |

**총 예상 시간**: 6.5-8시간

---

## 📝 체크리스트

### 개발 전
- [ ] 기존 초대 플로우 완전 이해
- [ ] DB 스키마 확인 (UserInvitation 테이블)
- [ ] 기존 테스트 케이스 리뷰

### 개발 중
- [ ] **초대 만료일 동적 설정** 🔧 개선
  - [ ] DurationParser 유틸리티 클래스 생성
  - [ ] UserManFacade에 PortalPropertyService 의존성 추가
  - [ ] createInvitation() 메서드 수정 (동적 만료일)
  - [ ] PTL_PROPERTY 테이블에 설정 추가
- [ ] **중복 초대 방지 추가** ⚠️ 필수
  - [ ] UserInvitationRepository 메서드 추가
  - [ ] UserManFacade.sendInvitation()에 중복 체크 로직 추가
  - [ ] 같은 법인 중복 초대 차단
  - [ ] 만료된 초대 자동 취소 후 재생성
  - [ ] 다른 법인 중복 초대 차단 (비즈니스 정책 결정 필요)
- [ ] **마이페이지 초대 알림 추가** (재방문 사용자 대응)
  - [ ] AccountController에 초대 확인 로직 추가
  - [ ] kbank_mypage_layout.html에 알림 배너 추가
  - [ ] CSS 스타일 작성
- [ ] 로그인 페이지 "초대를 받으셨나요?" 링크 추가
- [ ] 초대코드 입력 페이지 생성
- [ ] UserRegisterController 엔드포인트 구현
  - [ ] GET /signup/invitation-code
  - [ ] POST /signup/invitation-code (Brute Force 방지 포함)
- [ ] AuthenticationSuccessHandler 수정 (자동 초대 확인)
- [ ] CSRF 토큰 적용 확인
- [ ] 에러 처리 구현

### 테스트
- [ ] 단위 테스트 작성 및 통과
- [ ] **초대 만료일 동적 설정 테스트** 🔧
  - [ ] 기본값 7일 테스트
  - [ ] 2시간 설정 테스트
  - [ ] 30분 설정 테스트
  - [ ] 14일 설정 테스트
  - [ ] 잘못된 형식 → 기본값 fallback 테스트
- [ ] **중복 초대 방지 테스트** ⚠️ 필수
  - [ ] 같은 법인 중복 초대 차단
  - [ ] 만료된 초대 재발송
  - [ ] 다른 법인 중복 초대 차단
  - [ ] 초대 수락 후 중복 차단
- [ ] **마이페이지 초대 알림 테스트**
  - [ ] 로그인 후 자동 확인 놓친 경우
  - [ ] 세션 만료 후 재로그인
  - [ ] 초대 수락 후 알림 제거 확인
  - [ ] 법인 회원은 알림 표시 안 됨
- [ ] 신규 회원 플로우 테스트
- [ ] 기존 회원 플로우 테스트
- [ ] 에러 케이스 테스트
- [ ] 만료된 코드 테스트
- [ ] Brute Force 방지 테스트 (5회 실패 시나리오)
- [ ] 우선순위 충돌 테스트

### 배포 전
- [ ] 코드 리뷰
- [ ] 통합 테스트 완료
- [ ] 로그 확인 (Hibernate SQL, 애플리케이션 로그)
- [ ] 스테이징 환경 배포 및 검증
- [ ] 운영 배포 계획 수립

---

## 🔗 관련 파일

### 주요 소스
- `UserRegisterController.java:149-191` - 기존 초대 처리 로직
- `UserManFacade.java:124-163` - 초대 생성 및 토큰 생성
- `PortalAuthenticationSuccessHandler.java:38-83` - 로그인 성공 처리
- `userDecisionProcess.html` - 초대 수락 페이지 (약관 포함)

### 참고 문서
- `kjb-docs/mermaid/invite-flow-integrated.mermaid` - 통합 플로우차트
- `kjb-docs/mermaid/invite-sequence.mermaid` - 시퀀스 다이어그램
- `CLAUDE.md` - 프로젝트 아키텍처

---

## 📅 일정 (예상)

| 단계 | 작업 내용 | 소요 시간 | 담당자 |
|------|----------|----------|--------|
| 0단계 | 마이페이지 초대 알림 구현 | 1시간 | - |
| 1단계 | HTML 작업 (로그인, 초대코드 입력) | 1.5시간 | - |
| 2단계 | Controller 구현 (Brute Force 방지 포함) | 1.5시간 | - |
| 3단계 | AuthenticationSuccessHandler 수정 | 0.5시간 | - |
| 4단계 | 단위 테스트 작성 | 1시간 | - |
| 5단계 | 통합 테스트 (수동) | 2.5시간 | - |
| 총 | | **8시간** | |

---

## 📌 Brute Force 방지 구현 (세션 기반)

### 개요
초대코드 입력 실패 시 세션 기반으로 실패 횟수를 추적하여, 일정 횟수 이상 실패 시 일시적으로 입력을 차단합니다.

### 구현 방법

#### 1. 세션 속성 정의
```java
// 세션에 저장할 키
public static final String INVITATION_CODE_FAILURE_COUNT = "invitationCodeFailureCount";
public static final String INVITATION_CODE_LOCKED_UNTIL = "invitationCodeLockedUntil";

// 설정값
public static final int MAX_FAILURE_COUNT = 5;  // 최대 실패 허용 횟수
public static final int LOCK_DURATION_MINUTES = 15;  // 차단 시간 (분)
```

#### 2. UserRegisterController 수정
**파일**: `UserRegisterController.java`

**POST /signup/invitation-code 메서드 수정**:

```java
@PostMapping("/signup/invitation-code")
public String processInvitationCode(
        @RequestParam("invitationCode") String invitationCode,
        HttpSession session,
        RedirectAttributes redirectAttributes,
        Model model) {

    // 1. 차단 상태 확인
    LocalDateTime lockedUntil = (LocalDateTime) session.getAttribute(INVITATION_CODE_LOCKED_UNTIL);
    if (lockedUntil != null && LocalDateTime.now().isBefore(lockedUntil)) {
        long minutesLeft = ChronoUnit.MINUTES.between(LocalDateTime.now(), lockedUntil);
        model.addAttribute("error",
            String.format("너무 많은 시도로 인해 %d분간 초대코드 입력이 차단되었습니다.", minutesLeft + 1));
        return "apps/register/invitationCodeInput";
    }

    // 2. 입력값 검증
    if (!invitationCode.matches("[A-Z0-9]{8}")) {
        incrementFailureCount(session);
        model.addAttribute("error", "올바른 형식의 초대코드를 입력해주세요.");
        return "apps/register/invitationCodeInput";
    }

    // 3. DB에서 토큰 조회 및 검증
    Optional<UserInvitation> invitation =
        userInvitationRepository.findByToken(invitationCode);

    if (!invitation.isPresent() ||
        invitation.get().getStatus() != UserInvitationEnums.InvitationStatus.PENDING ||
        invitation.get().getExpiresOn().isBefore(LocalDateTime.now())) {

        // 실패 처리
        int failureCount = incrementFailureCount(session);

        if (failureCount >= MAX_FAILURE_COUNT) {
            // 차단 처리
            LocalDateTime lockTime = LocalDateTime.now().plusMinutes(LOCK_DURATION_MINUTES);
            session.setAttribute(INVITATION_CODE_LOCKED_UNTIL, lockTime);
            model.addAttribute("error",
                "너무 많은 시도로 인해 15분간 초대코드 입력이 차단되었습니다.");
        } else {
            int remainingAttempts = MAX_FAILURE_COUNT - failureCount;
            model.addAttribute("error",
                String.format("유효하지 않은 초대코드입니다. (남은 시도: %d회)", remainingAttempts));
        }

        return "apps/register/invitationCodeInput";
    }

    // 4. 성공 시 실패 카운트 초기화
    session.removeAttribute(INVITATION_CODE_FAILURE_COUNT);
    session.removeAttribute(INVITATION_CODE_LOCKED_UNTIL);

    // 5. 기존 로직 (사용자 확인 및 리다이렉트)
    String email = invitation.get().getInvitationEmail();
    Optional<PortalUser> existingUser =
        portalUserRepository.findPortalUserByEmailAddr(email);

    if (existingUser.isPresent()) {
        session.setAttribute("invitationCodeForLogin", invitationCode);
        redirectAttributes.addFlashAttribute("message", "로그인하여 초대를 수락해주세요.");
        return "redirect:/login";
    } else {
        return "redirect:/signup/portalUser?invitation=" + invitationCode;
    }
}

// Helper 메서드
private int incrementFailureCount(HttpSession session) {
    Integer failureCount = (Integer) session.getAttribute(INVITATION_CODE_FAILURE_COUNT);
    if (failureCount == null) {
        failureCount = 0;
    }
    failureCount++;
    session.setAttribute(INVITATION_CODE_FAILURE_COUNT, failureCount);
    return failureCount;
}
```

#### 3. 프론트엔드 UI 개선
**invitationCodeInput.html에 추가**:

```html
<!-- 차단 상태 표시 -->
<div th:if="${error != null and error.contains('차단')}" class="alert alert-danger">
    <strong>⚠️ 보안 경고</strong>
    <p th:text="${error}"></p>
    <p>잠시 후 다시 시도해주세요.</p>
</div>

<!-- 일반 에러 표시 (남은 시도 횟수 포함) -->
<div th:if="${error != null and !error.contains('차단')}" class="alert alert-warning">
    <p th:text="${error}"></p>
</div>
```

#### 4. 장점
- ✅ **DB 사용 불필요**: 세션 메모리만 사용하여 간단하고 빠름
- ✅ **자동 만료**: 세션 타임아웃(15분) 시 자동으로 초기화
- ✅ **사용자별 독립적**: 각 세션마다 독립적으로 카운트
- ✅ **성능 영향 최소**: 추가 DB 쿼리 없음

#### 5. 주의사항
- 세션이 만료되면 실패 카운트도 초기화됨 (긍정적 효과)
- 다른 브라우저/디바이스에서는 별도 카운트 (IP 기반 차단 아님)
- 로그아웃 시 세션 초기화로 카운트 리셋 가능 (큰 문제 아님)

#### 6. 테스트 시나리오
```
시나리오 1: 5회 실패 후 차단
1. 잘못된 코드 입력 (1회) → "남은 시도: 4회"
2. 잘못된 코드 입력 (2회) → "남은 시도: 3회"
3. 잘못된 코드 입력 (3회) → "남은 시도: 2회"
4. 잘못된 코드 입력 (4회) → "남은 시도: 1회"
5. 잘못된 코드 입력 (5회) → "15분간 차단되었습니다"
6. 올바른 코드 입력 → 차단 메시지 표시, 입력 불가

시나리오 2: 차단 후 시간 경과
1. 5회 실패로 차단 상태
2. 15분 대기
3. 올바른 코드 입력 → 정상 처리

시나리오 3: 실패 후 성공
1. 잘못된 코드 입력 (2회) → "남은 시도: 3회"
2. 올바른 코드 입력 → 성공, 카운트 초기화
3. 다시 잘못된 코드 입력 → "남은 시도: 4회" (초기화됨)
```

---

## 📌 초대 만료일 동적 설정 (PortalProperty) 🔧 개선

### 현재 상황

**UserManFacade.createInvitation()** (149-150라인):
```java
// Set expiration date (e.g., 7 days from now)
newInvitation.setExpiresOn(LocalDateTime.now().plusDays(7));
```

**문제점**:
- 만료일이 하드코딩되어 있음 (7일 고정)
- 운영 중 변경 시 코드 수정 및 재배포 필요
- 환경별 다른 설정 불가

---

### 개선 방안: PTL_PROPERTY 테이블 활용

**PTL_PROPERTY 테이블**에서 초대 만료 기간을 읽어와 동적으로 설정합니다.

#### 1. 시간 표현 유틸리티 클래스 생성 (신규)

**파일**: `src/main/java/com/eactive/apim/portal/common/util/DurationParser.java`

```java
package com.eactive.apim.portal.common.util;

import java.time.Duration;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * 시간 표현 문자열을 Duration으로 파싱하는 유틸리티
 * 지원 형식: 5m (5분), 2h (2시간), 7d (7일)
 */
public class DurationParser {

    private static final Pattern DURATION_PATTERN = Pattern.compile("^(\\d+)([mhd])$");

    /**
     * 시간 표현 문자열을 Duration으로 변환
     *
     * @param durationStr 시간 문자열 (예: "5m", "2h", "7d")
     * @return Duration 객체
     * @throws IllegalArgumentException 형식이 올바르지 않을 경우
     */
    public static Duration parse(String durationStr) {
        if (durationStr == null || durationStr.trim().isEmpty()) {
            throw new IllegalArgumentException("Duration string cannot be null or empty");
        }

        String normalized = durationStr.trim().toLowerCase();
        Matcher matcher = DURATION_PATTERN.matcher(normalized);

        if (!matcher.matches()) {
            throw new IllegalArgumentException(
                "Invalid duration format: " + durationStr +
                ". Expected format: <number><unit> (e.g., 5m, 2h, 7d)"
            );
        }

        long value = Long.parseLong(matcher.group(1));
        String unit = matcher.group(2);

        switch (unit) {
            case "m":
                return Duration.ofMinutes(value);
            case "h":
                return Duration.ofHours(value);
            case "d":
                return Duration.ofDays(value);
            default:
                throw new IllegalArgumentException("Unsupported time unit: " + unit);
        }
    }

    /**
     * 시간 표현 문자열을 일(day) 단위로 변환
     *
     * @param durationStr 시간 문자열 (예: "5m", "2h", "7d")
     * @return 일(day) 단위 long 값
     */
    public static long parseToDays(String durationStr) {
        return parse(durationStr).toDays();
    }

    /**
     * 기본값을 제공하는 안전한 파싱
     *
     * @param durationStr 시간 문자열
     * @param defaultValue 파싱 실패 시 기본값
     * @return Duration 객체
     */
    public static Duration parseOrDefault(String durationStr, Duration defaultValue) {
        try {
            return parse(durationStr);
        } catch (Exception e) {
            return defaultValue;
        }
    }
}
```

**예상 작업량**: 70줄

---

#### 2. UserManFacade 수정

**파일**: `UserManFacade.java`

**변경 전** (149-150라인):
```java
// Set expiration date (e.g., 7 days from now)
newInvitation.setExpiresOn(LocalDateTime.now().plusDays(7));
```

**변경 후**:
```java
// ===== 새로 추가 =====
private final PortalPropertyService portalPropertyService;

public String createInvitation(PortalUser sender, String emailAddr) {
    UserInvitation newInvitation = new UserInvitation();
    newInvitation.setAdminId(sender.getId());
    newInvitation.setOrgId(sender.getPortalOrg().getId());
    newInvitation.setInvitationEmail(emailAddr);

    // Set additional required fields
    newInvitation.setInvitationDate(LocalDateTime.now());
    newInvitation.setStatus(InvitationStatus.PENDING);

    // Generate 8-character token
    String token = generateEightCharToken();
    newInvitation.setToken(token);

    // ===== 변경: 동적 만료일 설정 =====
    // PTL_PROPERTY에서 초대 만료 기간 조회
    Map<String, String> properties = portalPropertyService.getPortalPropertiesAsMap("Portal");
    String expirationDuration = properties.getOrDefault("invitation.expiration", "7d");

    // 시간 문자열 파싱 (예: "7d" → 7일, "2h" → 2시간, "30m" → 30분)
    Duration duration = DurationParser.parseOrDefault(expirationDuration, Duration.ofDays(7));

    // 만료일 설정
    newInvitation.setExpiresOn(LocalDateTime.now().plus(duration));
    // ================================

    // Save the invitation
    userInvitationRepository.save(newInvitation);
    return token;
}
```

**추가 필드**:
```java
private final PortalPropertyService portalPropertyService;
```

**예상 작업량**: 10줄 추가

---

### PTL_PROPERTY 테이블 설정

#### 데이터 삽입 SQL

```sql
-- 초대 만료 기간 설정 (기본값: 7일)
INSERT INTO PTL_PROPERTY (PROP_GROUP, PROP_KEY, PROP_VALUE, DESCRIPTION)
VALUES ('Portal', 'invitation.expiration', '7d', '초대 만료 기간 (형식: 숫자+단위, 예: 5m, 2h, 7d)');

-- 다른 예시들
-- 30분: '30m'
-- 2시간: '2h'
-- 14일: '14d'
```

#### 설정 예시

| PROP_GROUP | PROP_KEY | PROP_VALUE | 설명 |
|------------|----------|------------|------|
| Portal | invitation.expiration | 7d | 7일 후 만료 (기본값) |
| Portal | invitation.expiration | 2h | 2시간 후 만료 (테스트용) |
| Portal | invitation.expiration | 30m | 30분 후 만료 (데모용) |
| Portal | invitation.expiration | 14d | 14일 후 만료 (운영용) |

---

### 지원하는 시간 단위

| 단위 | 설명 | 예시 | 실제 기간 |
|------|------|------|----------|
| `m` | 분 (minutes) | `5m` | 5분 |
| `m` | 분 (minutes) | `30m` | 30분 |
| `h` | 시간 (hours) | `2h` | 2시간 |
| `h` | 시간 (hours) | `24h` | 24시간 (1일) |
| `d` | 일 (days) | `7d` | 7일 |
| `d` | 일 (days) | `30d` | 30일 |

**형식**: `<숫자><단위>` (예: `5m`, `2h`, `7d`)

---

### 에러 처리

#### 잘못된 형식 입력 시

```java
// PTL_PROPERTY에 잘못된 값이 있는 경우
// 예: "invalid", "7", "d7", "7dd"

Duration duration = DurationParser.parseOrDefault(expirationDuration, Duration.ofDays(7));
// → 파싱 실패 시 기본값 7일 사용
```

**로그 출력** (선택사항):
```java
try {
    duration = DurationParser.parse(expirationDuration);
} catch (IllegalArgumentException e) {
    log.warn("Invalid invitation expiration duration '{}', using default 7 days",
             expirationDuration, e);
    duration = Duration.ofDays(7);
}
```

---

### 테스트 시나리오

#### 테스트 1: 기본값 7일
```
PTL_PROPERTY: 설정 없음 또는 "7d"
초대 생성: 2025-11-24 10:00
만료일: 2025-12-01 10:00 (7일 후) ✅
```

#### 테스트 2: 2시간 (테스트용)
```
PTL_PROPERTY: "2h"
초대 생성: 2025-11-24 10:00
만료일: 2025-11-24 12:00 (2시간 후) ✅
```

#### 테스트 3: 30분 (데모용)
```
PTL_PROPERTY: "30m"
초대 생성: 2025-11-24 10:00
만료일: 2025-11-24 10:30 (30분 후) ✅
```

#### 테스트 4: 14일 (운영용)
```
PTL_PROPERTY: "14d"
초대 생성: 2025-11-24 10:00
만료일: 2025-12-08 10:00 (14일 후) ✅
```

#### 테스트 5: 잘못된 형식 → 기본값
```
PTL_PROPERTY: "invalid" 또는 빈 값
초대 생성: 2025-11-24 10:00
만료일: 2025-12-01 10:00 (기본 7일) ✅
로그: "Invalid invitation expiration duration 'invalid', using default 7 days"
```

---

### 장점

- ✅ **재배포 불필요**: DB 설정만 변경하면 즉시 적용
- ✅ **환경별 설정**: 개발/스테이징/운영 환경마다 다른 만료일 설정 가능
- ✅ **유연성**: 분/시간/일 단위 모두 지원
- ✅ **안전성**: 잘못된 설정 시 기본값(7일) 사용
- ✅ **가독성**: "7d"가 "7"보다 의미 명확

---

## 📌 중복 초대 방지 구현 ⚠️ 필수

### 현재 문제점

**UserManFacade.sendInvitation()** (91-132라인)에서:
- ✅ 이미 법인 회원인지 체크함 (108-110라인)
- ❌ **PENDING 상태의 초대가 이미 있는지 체크 안 함**

**결과**: 같은 이메일에 여러 번 초대 가능 → 중복 초대 생성 ❌

---

### 구현 방법

#### 1. UserManFacade.sendInvitation() 수정
**파일**: `src/main/java/com/eactive/apim/portal/apps/user/facade/UserManFacade.java`

**수정 위치**: 103-111라인 (기존 사용자 확인 로직 다음)

```java
public void sendInvitation(PortalUser sender, String emailAddr) {
    // 이메일 형식 검증
    if (emailAddr == null || emailAddr.trim().isEmpty()) {
        throw new IllegalArgumentException("이메일 주소를 입력해주세요.");
    }

    // 이메일 정규식 검증
    String emailPattern = "^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$";
    if (!emailAddr.matches(emailPattern)) {
        throw new IllegalArgumentException("올바른 이메일 형식을 입력해주세요.");
    }

    // 기존 사용자인지 확인
    Optional<PortalUser> existingUser = portalUserRepository.findPortalUserByEmailAddr(emailAddr);

    if (existingUser.isPresent()) {
        PortalUser user = existingUser.get();
        if (user.getPortalOrg() != null && !user.getRoleCode().equals(RoleCode.ROLE_USER)) {
            throw new IllegalArgumentException("기관에 등록된 이용자 입니다.");
        }
    }

    // ===== 새로 추가: 중복 초대 확인 =====
    // 1. 현재 법인의 PENDING 초대 확인
    Optional<UserInvitation> existingInvitation =
        userInvitationRepository.findFirstByInvitationEmailAndOrgIdAndStatus(
            emailAddr,
            sender.getPortalOrg().getId(),
            InvitationStatus.PENDING
        );

    if (existingInvitation.isPresent()) {
        UserInvitation invitation = existingInvitation.get();

        // 만료된 초대인 경우 → 기존 초대 취소 후 새로 생성
        if (invitation.getExpiresOn().isBefore(LocalDateTime.now())) {
            invitation.setStatus(InvitationStatus.CANCELED);
            userInvitationRepository.save(invitation);
            // 계속 진행하여 새 초대 생성
        } else {
            // 아직 유효한 초대가 있는 경우 → 에러
            throw new IllegalArgumentException(
                "이미 초대 중인 사용자입니다. 초대 만료일: " +
                invitation.getExpiresOn().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"))
            );
        }
    }

    // 2. 다른 법인의 PENDING 초대 확인 (선택사항)
    Optional<UserInvitation> otherOrgInvitation =
        userInvitationRepository.findFirstByInvitationEmailAndStatus(
            emailAddr,
            InvitationStatus.PENDING
        );

    if (otherOrgInvitation.isPresent() &&
        !otherOrgInvitation.get().getOrgId().equals(sender.getPortalOrg().getId())) {

        // 다른 법인에서 초대 중 → 경고 메시지 (선택사항)
        // 비즈니스 정책에 따라 차단 또는 허용
        throw new IllegalArgumentException(
            "해당 사용자는 다른 법인에서 초대 중입니다."
        );
    }
    // ====================================

    String token = createInvitation(sender, emailAddr);

    // ... 나머지 기존 로직
}
```

**예상 작업량**: 30-35줄 추가

---

#### 2. UserInvitationRepository 메서드 추가 (필요 시)

현재 `findFirstByInvitationEmailAndStatus` 메서드는 있지만,
**같은 법인 내 중복 체크**를 위해 새 메서드가 필요할 수 있습니다.

**파일**: `UserInvitationRepository.java`

```java
public interface UserInvitationRepository extends JpaRepository<UserInvitation, String> {

    // 기존 메서드
    Optional<UserInvitation> findFirstByInvitationEmailAndStatus(
        String invitationEmail,
        InvitationStatus status
    );

    // 새로 추가: 같은 법인 내 중복 체크
    Optional<UserInvitation> findFirstByInvitationEmailAndOrgIdAndStatus(
        String invitationEmail,
        String orgId,
        InvitationStatus status
    );
}
```

**예상 작업량**: 5줄 추가 (메서드 시그니처만)

---

### 중복 초대 시나리오 및 처리 방침

#### 시나리오 1: 같은 법인에서 중복 초대
```
상황: A법인 관리자가 user@example.com에게 초대
상태: PENDING (만료일: 2025-12-01)
재시도: A법인 관리자가 동일 이메일에 다시 초대 시도
결과: ❌ "이미 초대 중인 사용자입니다. 초대 만료일: 2025-12-01"
```

**정책**: 차단 (같은 법인 내 중복 초대 불가)

---

#### 시나리오 2: 같은 법인, 만료된 초대
```
상황: A법인 관리자가 user@example.com에게 초대
상태: PENDING (만료일: 2025-11-20, 이미 만료됨)
재시도: A법인 관리자가 동일 이메일에 다시 초대 시도
처리:
  1. 기존 초대 상태 → CANCELED
  2. 새로운 PENDING 초대 생성
  3. 새 토큰 발급
결과: ✅ 새 초대 이메일 발송
```

**정책**: 허용 (만료된 초대는 자동 취소 후 재생성)

---

#### 시나리오 3: 다른 법인에서 중복 초대 (비즈니스 정책 필요)

**옵션 A: 차단** (추천)
```
상황: A법인에서 user@example.com에게 초대 (PENDING)
재시도: B법인 관리자가 동일 이메일에 초대 시도
결과: ❌ "해당 사용자는 다른 법인에서 초대 중입니다."
```

**옵션 B: 허용**
```
상황: A법인에서 user@example.com에게 초대 (PENDING)
재시도: B법인 관리자가 동일 이메일에 초대 시도
결과: ✅ 두 초대 모두 PENDING 상태 유지
선택: 사용자가 먼저 수락한 초대로 가입
```

**권장**: 옵션 A (차단) - 사용자 혼란 방지

---

#### 시나리오 4: 초대 수락 후 다른 법인 초대
```
상황: user@example.com이 A법인 초대 수락 (ROLE_CORP_USER)
재시도: B법인 관리자가 동일 이메일에 초대 시도
결과: ❌ "기관에 등록된 이용자 입니다." (기존 로직)
```

**정책**: 차단 (이미 구현됨, 108-110라인)

---

### 프론트엔드 에러 메시지 처리

**파일**: `userList.html` (sendInvitation 함수, 223-235라인)

현재 에러 처리 코드:
```javascript
.fail(function (jqXHR, textStatus, errorThrown) {
    let errorMessage;

    try {
        const errorResponse = JSON.parse(jqXHR.responseText);
        errorMessage = errorResponse.msg || '이용자 초대 중 오류가 발생했습니다';
    } catch (e) {
        errorMessage = '이용자 초대 중 오류가 발생했습니다: ' + errorThrown;
    }
    customPopups.showAlert(errorMessage);
});
```

**변경 필요 없음**: 이미 서버 에러 메시지를 그대로 표시하므로 중복 초대 에러도 자동으로 표시됨 ✅

---

### 테스트 시나리오

#### 테스트 1: 같은 법인 중복 초대 차단
```
1. A법인 관리자 로그인
2. user@example.com에게 초대 발송 → 성공
3. 다시 user@example.com에게 초대 시도
4. 에러: "이미 초대 중인 사용자입니다. 초대 만료일: 2025-12-01"
5. 초대 목록에서 1개만 표시 ✅
```

#### 테스트 2: 만료된 초대 재발송
```
1. A법인 관리자 로그인
2. 만료된 초대 존재 (만료일: 2025-11-20)
3. user@example.com에게 다시 초대 시도
4. 성공: 기존 초대 CANCELED, 새 초대 PENDING
5. 새 토큰으로 이메일 발송 ✅
```

#### 테스트 3: 다른 법인 중복 초대 차단
```
1. A법인 관리자가 user@example.com에게 초대 (PENDING)
2. B법인 관리자 로그인
3. user@example.com에게 초대 시도
4. 에러: "해당 사용자는 다른 법인에서 초대 중입니다."
5. B법인 초대 목록에 표시 안 됨 ✅
```

#### 테스트 4: 초대 수락 후 중복 차단
```
1. user@example.com이 A법인 초대 수락 (ROLE_CORP_USER)
2. B법인 관리자가 user@example.com에게 초대 시도
3. 에러: "기관에 등록된 이용자 입니다." (기존 로직)
4. 초대 생성 안 됨 ✅
```

---

### 구현 우선순위

| 시나리오 | 우선순위 | 이유 |
|----------|---------|------|
| 같은 법인 중복 초대 차단 | 🔴 **필수** | 데이터 정합성 문제, 사용자 혼란 |
| 만료된 초대 재생성 | 🟡 **권장** | UX 개선 (수동 취소 불필요) |
| 다른 법인 중복 초대 차단 | 🟡 **권장** | 사용자 혼란 방지 |

---

## 📌 이메일 검증 구현 ✅ 완료

### 구현 내역

#### 1. 프론트엔드 (userList.html)
- ✅ `<input type="email">` 적용
- ✅ HTML5 pattern 속성 추가: `[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}`
- ✅ JavaScript 정규식 검증 추가

#### 2. 백엔드 (UserManRestController.java)
- ✅ 이메일 null/empty 체크
- ✅ 정규식 검증: `^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$`
- ✅ 검증 실패 시 400 에러 반환

#### 3. Facade (UserManFacade.java)
- ✅ 이메일 null/empty 체크
- ✅ 정규식 검증
- ✅ `IllegalArgumentException` 발생

### 적용된 파일
- `src/main/resources/templates/views/apps/users/userList.html`
- `src/main/java/com/eactive/apim/portal/apps/user/controller/UserManRestController.java`
- `src/main/java/com/eactive/apim/portal/apps/user/facade/UserManFacade.java`

---

## 📌 후속 작업 (선택사항)

1. ~~**Brute Force 방지**: 초대코드 입력 실패 횟수 제한~~ ✅ 상세 구현 계획 추가 (세션 기반)
2. ~~**이메일 검증**: 이메일 형식 검증~~ ✅ 구현 완료
3. ~~**중복 초대 방지**: PENDING 초대 중복 체크~~ ✅ 상세 구현 계획 추가
4. ~~**초대 만료일 동적 설정**: PTL_PROPERTY 기반 만료일 설정~~ ✅ 상세 구현 계획 추가
5. **관리자 알림**: 초대코드 입력 시도 로그 기록
6. **통계**: 초대코드 직접 입력 vs 이메일 링크 사용 비율 추적
7. **QR 코드**: 초대코드를 QR 코드로 제공 (모바일 스캔)
8. **초대 재발송**: 만료 전 초대 재발송 기능 (UI 버튼)
9. **만료일 연장**: 주 단위(w), 월 단위(M), 년 단위(y) 지원

---

**문서 버전**: 1.4
**최종 수정**: 2025-11-24
**작성자**: Claude Code
**변경 이력**:
- v1.4 (2025-11-24): 초대 만료일 동적 설정 (PTL_PROPERTY 기반, 시간 표현 파싱 유틸리티)
- v1.3 (2025-11-24): 중복 초대 방지 기능 추가 (4가지 시나리오 및 구현 방법)
- v1.2 (2025-11-24): 마이페이지 초대 알림 기능 추가 (재방문 사용자 대응), 작업 규모 재산정 (6→8시간)
- v1.1 (2025-11-24): Brute Force 방지 세션 기반 구현 방법 추가, 이메일 검증 구현 완료 표시
- v1.0 (2025-11-24): 초기 작성