diff --git a/AGENTS.md b/AGENTS.md index bd4e1fa..0f85ac1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -252,6 +252,10 @@ When implementation is complete, report in Korean: - Multipart filenames, including non-ASCII names, are sent unchanged in the quoted `filename` parameter as raw UTF-8. No ASCII fallback or `filename*` parameter is added; CR/LF rejection and quote/backslash escaping still apply. - `JsonUtil` requires the consumer's explicit `ObjectMapper`; shared date/time helpers define KST as `Asia/Seoul` and also expose UTC semantics. +### Project Instruction Budget + +- Keep `.agent/project.md` at or below 9 KiB (9,216 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schema details, query or procedure inventories, API examples, and migration history to linked project documentation, and keep concise read-routing instructions here. + ### Upgrade and Verification - Review KriCommon release notes, README changes, configuration defaults, auto-configuration conditions, and affected public APIs before upgrading. diff --git a/src/main/java/com/kri/notihub/server/common/enums/PhoneVerificationStatus.java b/src/main/java/com/kri/notihub/server/common/enums/PhoneVerificationStatus.java new file mode 100644 index 0000000..bdabd18 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/common/enums/PhoneVerificationStatus.java @@ -0,0 +1,15 @@ +package com.kri.notihub.server.common.enums; + +import com.kri.common.feature.enums.CodeEnum; +import lombok.Getter; +import lombok.RequiredArgsConstructor; + +@Getter +@RequiredArgsConstructor +public enum PhoneVerificationStatus implements CodeEnum { + + PENDING((short) 0), + VERIFIED((short) 1); + + private final Short code; +} diff --git a/src/main/java/com/kri/notihub/server/common/enums/TemplatePurpose.java b/src/main/java/com/kri/notihub/server/common/enums/TemplatePurpose.java new file mode 100644 index 0000000..f4afeb4 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/common/enums/TemplatePurpose.java @@ -0,0 +1,30 @@ +package com.kri.notihub.server.common.enums; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; +import com.kri.common.feature.enums.CodeEnum; +import lombok.Getter; +import lombok.RequiredArgsConstructor; + +@Getter(onMethod_ = @JsonValue) +@RequiredArgsConstructor +public enum TemplatePurpose implements CodeEnum { + + NORMAL((short) 0), + PHONE_VERIFICATION((short) 1); + + private final Short code; + + @JsonCreator(mode = JsonCreator.Mode.DELEGATING) + public static TemplatePurpose fromCode(Short code) { + if (code == null) { + return null; + } + for (TemplatePurpose purpose : values()) { + if (purpose.code.equals(code)) { + return purpose; + } + } + throw new IllegalArgumentException("Unknown TemplatePurpose code: " + code); + } +} diff --git a/src/main/java/com/kri/notihub/server/config/PhoneVerificationProperties.java b/src/main/java/com/kri/notihub/server/config/PhoneVerificationProperties.java new file mode 100644 index 0000000..fe390b9 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/config/PhoneVerificationProperties.java @@ -0,0 +1,43 @@ +package com.kri.notihub.server.config; + +import jakarta.annotation.PostConstruct; +import jakarta.validation.constraints.Min; +import jakarta.validation.constraints.NotBlank; +import lombok.Getter; +import lombok.Setter; +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.stereotype.Component; +import org.springframework.validation.annotation.Validated; + +@Getter +@Setter +@Validated +@Component +@ConfigurationProperties(prefix = "kri.sms.verification") +public class PhoneVerificationProperties { + + public static final String CODE_PLACEHOLDER = "#{verificationCode}"; + + @Min(1) + private int expireMinutes = 5; + + @Min(1) + private int maxAttempts = 5; + + @NotBlank + private String messageTemplate = "인증번호는 [#{verificationCode}] 입니다."; + + @PostConstruct + void validateMessageTemplate() { + int first = messageTemplate.indexOf(CODE_PLACEHOLDER); + int last = messageTemplate.lastIndexOf(CODE_PLACEHOLDER); + if (first < 0 || first != last) { + throw new IllegalStateException( + "kri.sms.verification.message-template must contain #{verificationCode} exactly once"); + } + } + + public String renderMessage(String verificationCode) { + return messageTemplate.replace(CODE_PLACEHOLDER, verificationCode); + } +} diff --git a/src/main/java/com/kri/notihub/server/controller/PhoneVerificationController.java b/src/main/java/com/kri/notihub/server/controller/PhoneVerificationController.java new file mode 100644 index 0000000..f243a67 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/controller/PhoneVerificationController.java @@ -0,0 +1,30 @@ +package com.kri.notihub.server.controller; + +import com.kri.notihub.server.dto.verification.PhoneVerificationRequestDto; +import com.kri.notihub.server.dto.verification.PhoneVerificationResponseDto; +import com.kri.notihub.server.service.PhoneVerificationService; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.tags.Tag; +import jakarta.validation.Valid; +import lombok.RequiredArgsConstructor; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +@RestController +@RequestMapping("/api/v1/phone-verifications") +@RequiredArgsConstructor +@Tag(name = "Phone Verification", description = "휴대전화번호 인증 API") +public class PhoneVerificationController { + + private final PhoneVerificationService phoneVerificationService; + + @Operation(summary = "휴대전화번호 인증") + @PostMapping("/verify") + public PhoneVerificationResponseDto verify( + @Valid @RequestBody PhoneVerificationRequestDto request + ) { + return phoneVerificationService.verify(request); + } +} diff --git a/src/main/java/com/kri/notihub/server/controller/SendEmailController.java b/src/main/java/com/kri/notihub/server/controller/SendEmailController.java index 03bc89a..4ea957a 100644 --- a/src/main/java/com/kri/notihub/server/controller/SendEmailController.java +++ b/src/main/java/com/kri/notihub/server/controller/SendEmailController.java @@ -6,6 +6,7 @@ import com.kri.notihub.server.dto.send.BulkSendResponseDto; import com.kri.notihub.server.dto.send.EmailPollQueueResponseDto; import com.kri.notihub.server.dto.send.SendRequestBulkDto; import com.kri.notihub.server.dto.send.SendRequestSingleDto; +import com.kri.notihub.server.dto.send.SendSingleResponseDto; import com.kri.notihub.server.service.EmailResultPoller; import com.kri.notihub.server.service.SendEmailService; import io.swagger.v3.oas.annotations.Operation; @@ -43,11 +44,11 @@ public class SendEmailController { @Operation(summary = "이메일 단건 발송") @PostMapping("/single") - public void sendSingle( + public SendSingleResponseDto sendSingle( @Valid @RequestBody SendRequestSingleDto req, RequestUserContext ctx ) { - sendEmailService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); + return sendEmailService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); } @Operation(summary = "bulkSendKey 기반 이메일 벌크 발송") diff --git a/src/main/java/com/kri/notihub/server/controller/SendKkoAtController.java b/src/main/java/com/kri/notihub/server/controller/SendKkoAtController.java index 753589c..6b5023b 100644 --- a/src/main/java/com/kri/notihub/server/controller/SendKkoAtController.java +++ b/src/main/java/com/kri/notihub/server/controller/SendKkoAtController.java @@ -6,6 +6,7 @@ import com.kri.notihub.server.dto.send.BulkSendCreateRequestDto; import com.kri.notihub.server.dto.send.BulkSendResponseDto; import com.kri.notihub.server.dto.send.SendRequestBulkDto; import com.kri.notihub.server.dto.send.SendRequestSingleDto; +import com.kri.notihub.server.dto.send.SendSingleResponseDto; import com.kri.notihub.server.service.BizppurioSendCursorStore; import com.kri.notihub.server.service.SendKkoAtService; import io.swagger.v3.oas.annotations.Operation; @@ -41,11 +42,11 @@ public class SendKkoAtController { @Operation(summary = "알림톡 단건 발송") @PostMapping("/single") - public void sendSingle( + public SendSingleResponseDto sendSingle( @Valid @RequestBody SendRequestSingleDto req, RequestUserContext ctx ) { - sendKKoAtService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); + return sendKKoAtService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); } @Operation(summary = "bulkSendKey 기반 알림톡 벌크 발송") diff --git a/src/main/java/com/kri/notihub/server/controller/SendSmsController.java b/src/main/java/com/kri/notihub/server/controller/SendSmsController.java index a80b76b..c2b7ef8 100644 --- a/src/main/java/com/kri/notihub/server/controller/SendSmsController.java +++ b/src/main/java/com/kri/notihub/server/controller/SendSmsController.java @@ -5,6 +5,7 @@ import com.kri.notihub.server.dto.send.BulkSendCreateRequestDto; import com.kri.notihub.server.dto.send.BulkSendResponseDto; import com.kri.notihub.server.dto.send.SendRequestBulkDto; import com.kri.notihub.server.dto.send.SendRequestSingleDto; +import com.kri.notihub.server.dto.send.SendSingleResponseDto; import com.kri.notihub.server.dto.send.BizppurioCursorResponseDto; import com.kri.notihub.server.service.SendSmsService; import com.kri.notihub.server.service.BizppurioSendCursorStore; @@ -42,11 +43,11 @@ public class SendSmsController { @Operation(summary = "문자 단건 발송") @PostMapping("/single") - public void sendSingle( + public SendSingleResponseDto sendSingle( @Valid @RequestBody SendRequestSingleDto req, RequestUserContext ctx ) { - sendSmsService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); + return sendSmsService.doSendSingle(req, ctx.getUserCmpn(), ctx.getUserId()); } @Operation(summary = "bulkSendKey 기반 문자 벌크 발송") diff --git a/src/main/java/com/kri/notihub/server/dto/send/SendSingleResponseDto.java b/src/main/java/com/kri/notihub/server/dto/send/SendSingleResponseDto.java new file mode 100644 index 0000000..6279af8 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/dto/send/SendSingleResponseDto.java @@ -0,0 +1,33 @@ +package com.kri.notihub.server.dto.send; + +import io.swagger.v3.oas.annotations.media.Schema; +import java.util.Map; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Getter; +import lombok.NoArgsConstructor; + +@Getter +@Builder +@NoArgsConstructor +@AllArgsConstructor +@Schema(description = "단건 발송 접수 결과") +public class SendSingleResponseDto { + + public static final String VERIFICATION_ID_KEY = "verificationId"; + public static final String EXPIRE_DT_KEY = "expireDt"; + + @Schema(description = "발송 고유 키") + private String cmid; + + @Builder.Default + @Schema(description = "템플릿 목적별 추가 응답 정보") + private Map data = Map.of(); + + public static SendSingleResponseDto of(String cmid, Map data) { + return SendSingleResponseDto.builder() + .cmid(cmid) + .data(data == null ? Map.of() : Map.copyOf(data)) + .build(); + } +} diff --git a/src/main/java/com/kri/notihub/server/dto/template/TemplateBasicDto.java b/src/main/java/com/kri/notihub/server/dto/template/TemplateBasicDto.java index 4a0cb25..47a86d9 100644 --- a/src/main/java/com/kri/notihub/server/dto/template/TemplateBasicDto.java +++ b/src/main/java/com/kri/notihub/server/dto/template/TemplateBasicDto.java @@ -2,6 +2,7 @@ package com.kri.notihub.server.dto.template; import com.fasterxml.jackson.annotation.JsonProperty; import com.kri.notihub.server.common.enums.SendType; +import com.kri.notihub.server.common.enums.TemplatePurpose; import io.swagger.v3.oas.annotations.media.Schema; import jakarta.persistence.Column; import jakarta.validation.constraints.Email; @@ -30,6 +31,9 @@ public class TemplateBasicDto { @Schema(description = "템플릿 타입") private SendType tmplatTy; + @Schema(description = "템플릿 목적 (0: 일반, 1: 휴대전화번호 인증)") + private TemplatePurpose tmplatPurpose; + @Size(max = 32) @NotBlank @Schema(description = "템플릿 명") diff --git a/src/main/java/com/kri/notihub/server/dto/template/TemplateDto.java b/src/main/java/com/kri/notihub/server/dto/template/TemplateDto.java index ab1fe7b..179504f 100644 --- a/src/main/java/com/kri/notihub/server/dto/template/TemplateDto.java +++ b/src/main/java/com/kri/notihub/server/dto/template/TemplateDto.java @@ -2,6 +2,7 @@ package com.kri.notihub.server.dto.template; import com.fasterxml.jackson.annotation.JsonProperty; import com.kri.notihub.server.common.enums.SendType; +import com.kri.notihub.server.common.enums.TemplatePurpose; import com.kri.notihub.server.persistence.entity.TTmplatEntity; import io.swagger.v3.oas.annotations.media.Schema; import jakarta.validation.constraints.NotNull; @@ -48,6 +49,7 @@ public class TemplateDto extends TemplateBasicDto { .tmplatIdx(entity.getTmplatIdx()) .itrntPrjctCd(entity.getItrntPrjctCd()) .tmplatTy(SendType.fromCode(entity.getTmplatTy())) + .tmplatPurpose(TemplatePurpose.fromCode(entity.getTmplatPurpose())) .tmplatNm(entity.getTmplatNm()) .tmplatTitle(entity.getTmplatTitle()) .tmplatBody(entity.getTmplatBody()) diff --git a/src/main/java/com/kri/notihub/server/dto/template/TemplateSummaryDto.java b/src/main/java/com/kri/notihub/server/dto/template/TemplateSummaryDto.java index 94b1e91..7613b75 100644 --- a/src/main/java/com/kri/notihub/server/dto/template/TemplateSummaryDto.java +++ b/src/main/java/com/kri/notihub/server/dto/template/TemplateSummaryDto.java @@ -1,5 +1,6 @@ package com.kri.notihub.server.dto.template; +import com.kri.notihub.server.common.enums.TemplatePurpose; import com.kri.notihub.server.persistence.entity.TTmplatEntity; import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; @@ -22,10 +23,14 @@ public class TemplateSummaryDto { @Schema(description = "템플릿 명") private String tmplatNm; + @Schema(description = "템플릿 목적") + private TemplatePurpose tmplatPurpose; + public static TemplateSummaryDto from(TTmplatEntity entity) { return TemplateSummaryDto.builder() .tmplatIdx(entity.getTmplatIdx()) .tmplatNm(entity.getTmplatNm()) + .tmplatPurpose(TemplatePurpose.fromCode(entity.getTmplatPurpose())) .build(); } } diff --git a/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationRequestDto.java b/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationRequestDto.java new file mode 100644 index 0000000..9639ef8 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationRequestDto.java @@ -0,0 +1,32 @@ +package com.kri.notihub.server.dto.verification; + +import io.swagger.v3.oas.annotations.media.Schema; +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.Pattern; +import jakarta.validation.constraints.Size; +import lombok.Getter; +import lombok.Setter; + +@Getter +@Setter +@Schema(description = "휴대전화번호 인증 요청") +public class PhoneVerificationRequestDto { + + @NotBlank + @Pattern( + regexp = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", + message = "verificationId는 UUID 형식이어야 합니다." + ) + @Schema(description = "인증 발급 UUID") + private String verificationId; + + @NotBlank + @Size(max = 16) + @Schema(description = "인증 대상 휴대전화번호") + private String sendTel; + + @NotBlank + @Pattern(regexp = "^[0-9]{6}$", message = "verificationCode는 숫자 6자리여야 합니다.") + @Schema(description = "6자리 인증번호") + private String verificationCode; +} diff --git a/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationResponseDto.java b/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationResponseDto.java new file mode 100644 index 0000000..07be8e9 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/dto/verification/PhoneVerificationResponseDto.java @@ -0,0 +1,40 @@ +package com.kri.notihub.server.dto.verification; + +import com.fasterxml.jackson.annotation.JsonFormat; +import io.swagger.v3.oas.annotations.media.Schema; +import java.time.LocalDateTime; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Getter; +import lombok.NoArgsConstructor; + +@Getter +@Builder +@NoArgsConstructor +@AllArgsConstructor +@Schema(description = "휴대전화번호 인증 결과") +public class PhoneVerificationResponseDto { + + private String verificationId; + + private String sendTel; + + private boolean verified; + + @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") + private LocalDateTime verifiedDt; + + public static PhoneVerificationResponseDto of( + String verificationId, + String sendTel, + boolean verified, + LocalDateTime verifiedDt + ) { + return PhoneVerificationResponseDto.builder() + .verificationId(verificationId) + .sendTel(sendTel) + .verified(verified) + .verifiedDt(verifiedDt) + .build(); + } +} diff --git a/src/main/java/com/kri/notihub/server/persistence/entity/TPhoneVerificationEntity.java b/src/main/java/com/kri/notihub/server/persistence/entity/TPhoneVerificationEntity.java new file mode 100644 index 0000000..2649b08 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/persistence/entity/TPhoneVerificationEntity.java @@ -0,0 +1,71 @@ +package com.kri.notihub.server.persistence.entity; + +import com.kri.notihub.server.common.enums.PhoneVerificationStatus; +import jakarta.persistence.Column; +import jakarta.persistence.Entity; +import jakarta.persistence.Id; +import jakarta.persistence.Table; +import jakarta.validation.constraints.NotNull; +import jakarta.validation.constraints.Size; +import java.time.LocalDateTime; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Getter; +import lombok.NoArgsConstructor; + +@Getter +@Builder +@Entity +@Table(name = "t_phone_verification") +@NoArgsConstructor +@AllArgsConstructor +public class TPhoneVerificationEntity { + + @Id + @Size(max = 36) + @Column(name = "verification_id", nullable = false, length = 36) + private String verificationId; + + @NotNull + @Size(max = 32) + @Column(name = "cmid", nullable = false, length = 32, unique = true) + private String cmid; + + @NotNull + @Size(min = 6, max = 6) + @Column(name = "verification_code", nullable = false, length = 6) + private String verificationCode; + + @NotNull + @Size(max = 16) + @Column(name = "send_tel", nullable = false, length = 16) + private String sendTel; + + @NotNull + @Column(name = "status", nullable = false) + private Short status; + + @NotNull + @Column(name = "attempt_count", nullable = false) + private Short attemptCount; + + @NotNull + @Column(name = "reg_dt", nullable = false) + private LocalDateTime regDt; + + @NotNull + @Column(name = "expire_dt", nullable = false) + private LocalDateTime expireDt; + + @Column(name = "verified_dt") + private LocalDateTime verifiedDt; + + public void markVerified(LocalDateTime verifiedDt) { + this.status = PhoneVerificationStatus.VERIFIED.getCode(); + this.verifiedDt = verifiedDt; + } + + public void increaseAttemptCount() { + this.attemptCount = (short) (attemptCount + 1); + } +} diff --git a/src/main/java/com/kri/notihub/server/persistence/entity/TTmplatEntity.java b/src/main/java/com/kri/notihub/server/persistence/entity/TTmplatEntity.java index edf4474..fa4ba27 100644 --- a/src/main/java/com/kri/notihub/server/persistence/entity/TTmplatEntity.java +++ b/src/main/java/com/kri/notihub/server/persistence/entity/TTmplatEntity.java @@ -41,6 +41,11 @@ public class TTmplatEntity { @Column(name = "tmplat_ty", nullable = false) private Short tmplatTy; + @NotNull + @ColumnDefault("0") + @Column(name = "tmplat_purpose", nullable = false) + private Short tmplatPurpose; + @Size(max = 32) @NotNull @Column(name = "tmplat_nm", nullable = false, length = 32) @@ -121,6 +126,7 @@ public class TTmplatEntity { return TTmplatEntity.builder() .itrntPrjctCd(itrntPrjctCd) .tmplatTy(template.getTmplatTy().getCode()) + .tmplatPurpose(template.getTmplatPurpose().getCode()) .tmplatNm(template.getTmplatNm()) .tmplatTitle(template.getTmplatTitle()) .tmplatBody(template.getTmplatBody()) @@ -141,6 +147,7 @@ public class TTmplatEntity { public void updateFrom(TemplateBasicDto template, String modUser, LocalDateTime modDt) { // 기본 정보 갱신 this.tmplatTy = template.getTmplatTy().getCode(); + this.tmplatPurpose = template.getTmplatPurpose().getCode(); this.tmplatNm = template.getTmplatNm(); this.tmplatTitle = template.getTmplatTitle(); this.tmplatBody = template.getTmplatBody(); diff --git a/src/main/java/com/kri/notihub/server/persistence/repository/PhoneVerificationRepository.java b/src/main/java/com/kri/notihub/server/persistence/repository/PhoneVerificationRepository.java new file mode 100644 index 0000000..59300d1 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/persistence/repository/PhoneVerificationRepository.java @@ -0,0 +1,22 @@ +package com.kri.notihub.server.persistence.repository; + +import com.kri.notihub.server.persistence.entity.TPhoneVerificationEntity; +import jakarta.persistence.LockModeType; +import java.time.LocalDateTime; +import java.util.Optional; +import org.springframework.data.jpa.repository.JpaRepository; +import org.springframework.data.jpa.repository.Lock; +import org.springframework.data.jpa.repository.Modifying; +import org.springframework.data.jpa.repository.Query; + +public interface PhoneVerificationRepository + extends JpaRepository { + + @Lock(LockModeType.PESSIMISTIC_WRITE) + @Query("select v from TPhoneVerificationEntity v where v.verificationId = :verificationId") + Optional findByVerificationIdForUpdate(String verificationId); + + @Modifying(clearAutomatically = true, flushAutomatically = true) + @Query("delete from TPhoneVerificationEntity v where v.expireDt <= :now") + int deleteExpired(LocalDateTime now); +} diff --git a/src/main/java/com/kri/notihub/server/scheduler/PhoneVerificationCleanupScheduler.java b/src/main/java/com/kri/notihub/server/scheduler/PhoneVerificationCleanupScheduler.java new file mode 100644 index 0000000..aa43b16 --- /dev/null +++ b/src/main/java/com/kri/notihub/server/scheduler/PhoneVerificationCleanupScheduler.java @@ -0,0 +1,23 @@ +package com.kri.notihub.server.scheduler; + +import com.kri.notihub.server.service.PhoneVerificationService; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Component; + +@Slf4j +@Component +@RequiredArgsConstructor +public class PhoneVerificationCleanupScheduler { + + private final PhoneVerificationService phoneVerificationService; + + @Scheduled(cron = "${kri.sms.verification.cleanup-cron:0 0 * * * *}") + public void cleanupExpired() { + int deletedCount = phoneVerificationService.cleanupExpired(); + if (deletedCount > 0) { + log.info("[PhoneVerificationCleanup] 만료 인증정보 삭제 건수={}", deletedCount); + } + } +} diff --git a/src/main/java/com/kri/notihub/server/service/AbstractBizppurioSendService.java b/src/main/java/com/kri/notihub/server/service/AbstractBizppurioSendService.java index 932fe81..58d08ff 100644 --- a/src/main/java/com/kri/notihub/server/service/AbstractBizppurioSendService.java +++ b/src/main/java/com/kri/notihub/server/service/AbstractBizppurioSendService.java @@ -29,9 +29,11 @@ public abstract class AbstractBizppurioSendService extends AbstractSendService { BulkSendRepository bulkSendRepository, BizMsgRepository bizMsgRepository, SendRepository sendRepository, - TemplateService templateService + TemplateService templateService, + PhoneVerificationService phoneVerificationService ) { - super(sendBulkJdbcWriter, templateRepository, bulkSendRepository, sendRepository, templateService); + super(sendBulkJdbcWriter, templateRepository, bulkSendRepository, sendRepository, templateService, + phoneVerificationService); this.bizMsgBulkJdbcWriter = bizMsgBulkJdbcWriter; this.bizMsgRepository = bizMsgRepository; } diff --git a/src/main/java/com/kri/notihub/server/service/AbstractPringoSendService.java b/src/main/java/com/kri/notihub/server/service/AbstractPringoSendService.java index 3bac341..e6e4e02 100644 --- a/src/main/java/com/kri/notihub/server/service/AbstractPringoSendService.java +++ b/src/main/java/com/kri/notihub/server/service/AbstractPringoSendService.java @@ -43,9 +43,11 @@ public abstract class AbstractPringoSendService extends AbstractSendService { PringoApiClient pringoApiClient, EmailResultPoller emailResultPoller, EmailBodyRenderer emailBodyRenderer, - EmailAttachmentService emailAttachmentService + EmailAttachmentService emailAttachmentService, + PhoneVerificationService phoneVerificationService ) { - super(sendBulkJdbcWriter, templateRepository, bulkSendRepository, sendRepository, templateService); + super(sendBulkJdbcWriter, templateRepository, bulkSendRepository, sendRepository, templateService, + phoneVerificationService); this.pringoApiClient = pringoApiClient; this.emailResultPoller = emailResultPoller; this.emailBodyRenderer = emailBodyRenderer; diff --git a/src/main/java/com/kri/notihub/server/service/AbstractSendService.java b/src/main/java/com/kri/notihub/server/service/AbstractSendService.java index c93f458..f79dc1b 100644 --- a/src/main/java/com/kri/notihub/server/service/AbstractSendService.java +++ b/src/main/java/com/kri/notihub/server/service/AbstractSendService.java @@ -1,5 +1,6 @@ package com.kri.notihub.server.service; +import static com.kri.notihub.server.common.util.TemplateContentSanitizer.determineSms; import static org.apache.commons.lang3.StringUtils.firstNonBlank; import com.kri.common.feature.datetime.DateTimeUtil; @@ -8,12 +9,14 @@ import com.kri.notihub.server.common.consts.NotihubConst; import com.kri.notihub.server.common.enums.ChannelType; import com.kri.notihub.server.common.enums.SendStatusType; import com.kri.notihub.server.common.enums.SendType; +import com.kri.notihub.server.common.enums.TemplatePurpose; import com.kri.notihub.server.dto.send.BulkSendCreateRequestDto; import com.kri.notihub.server.dto.send.BulkSendResponseDto; import com.kri.notihub.server.dto.send.DestInfoDto; import com.kri.notihub.server.dto.send.SendInternalResultDto; import com.kri.notihub.server.dto.send.SendRequestBulkDto; import com.kri.notihub.server.dto.send.SendRequestSingleDto; +import com.kri.notihub.server.dto.send.SendSingleResponseDto; import com.kri.notihub.server.dto.template.TemplateDto; import com.kri.notihub.server.persistence.entity.TBulkSendEntity; import com.kri.notihub.server.persistence.entity.TSendEntity; @@ -22,6 +25,7 @@ import com.kri.notihub.server.persistence.repository.BulkSendRepository; import com.kri.notihub.server.persistence.repository.SendRepository; import com.kri.notihub.server.persistence.repository.TemplateRepository; import java.time.LocalDateTime; +import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.List; import java.util.Map; @@ -33,11 +37,15 @@ import lombok.RequiredArgsConstructor; @RequiredArgsConstructor public abstract class AbstractSendService { + private static final DateTimeFormatter RESPONSE_DATE_TIME_FORMATTER = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + protected final SendBulkJdbcWriter sendBulkJdbcWriter; protected final TemplateRepository templateRepository; protected final BulkSendRepository bulkSendRepository; protected final SendRepository sendRepository; protected final TemplateService templateService; + protected final PhoneVerificationService phoneVerificationService; public String issueBulkKey(BulkSendCreateRequestDto req) { LocalDateTime now = DateTimeUtil.nowKstLocalDateTime(); @@ -62,6 +70,7 @@ public abstract class AbstractSendService { TemplateDto tmplat = templateService.getTemplate(req.getTmplatIdx()); validateTemplateType(tmplat); + validateBulkTemplatePurpose(tmplat); TBulkSendEntity bulk = TBulkSendEntity.from(req, now); TBulkSendEntity saved = bulkSendRepository.save(bulk); @@ -76,10 +85,15 @@ public abstract class AbstractSendService { return; } + if (tmplat.getTmplatTy() == null) { + throw BusinessException.badRequest("WRONG_TEMPLATE_TYPE", "템플릿 타입이 없습니다.") + .with("tmplatIdx", tmplat.getTmplatIdx()); + } + int tmplatTy = tmplat.getTmplatTy().getCode() / 10; int required = requiredType.getCode(); - if (tmplat.getTmplatTy() == null || tmplatTy != required) { + if (tmplatTy != required) { throw BusinessException.badRequest("WRONG_TEMPLATE_TYPE", "템플릿 타입이 잘 못 됐습니다.") .with("tmplatIdx", tmplat.getTmplatIdx()) .with("required", requiredType) @@ -87,7 +101,11 @@ public abstract class AbstractSendService { } } - public void doSendSingle(SendRequestSingleDto req, String regCmpn, String regUser) { + public SendSingleResponseDto doSendSingle( + SendRequestSingleDto req, + String regCmpn, + String regUser + ) { LocalDateTime now = DateTimeUtil.nowKstLocalDateTime(); if (req == null || req.getDestInfo() == null) { @@ -107,6 +125,7 @@ public abstract class AbstractSendService { TemplateDto tmplat = templateService.getTemplate(req.getTmplatIdx()); validateTemplateType(tmplat); + validateSingleTemplatePurpose(tmplat, req); LocalDateTime sendDt = req.getSendDt() != null ? req.getSendDt() : now; String sendTel = firstNonBlank(req.getSendTel(), tmplat.getSendTel()); @@ -134,11 +153,19 @@ public abstract class AbstractSendService { String msgTitle = replacePlaceholder(tmplat.getTmplatTitle(), dest.getMsgParam()); String msgBody = renderMessageBody(tmplat.getTmplatBody(), dest.getMsgParam()); + PhoneVerificationIssue verificationIssue = null; + + if (tmplat.getTmplatPurpose() == TemplatePurpose.PHONE_VERIFICATION) { + verificationIssue = phoneVerificationService.issue(dest.getDestTel(), now); + msgBody = msgBody + "\n" + verificationIssue.message(); + } + + SendType effectiveSendType = resolveSendType(tmplat, msgTitle, msgBody); SendInternalResultDto sendResult = doSendInternal( req.getResve(), null, - tmplat.getTmplatTy(), + effectiveSendType, tmplat.getTmplatIdx(), tmplat.getAtchFl(), sendFrom, @@ -152,6 +179,10 @@ public abstract class AbstractSendService { req.setSendTel(sendTel); req.setSendNm(sendNm); + if (verificationIssue != null) { + phoneVerificationService.persist(verificationIssue, sendResult.getCmid()); + } + List sendInfo = new ArrayList<>(List.of( TSendEntity.from( req, @@ -171,6 +202,17 @@ public abstract class AbstractSendService { sendRepository.flush(); afterPersistSendEntities(sendInfo); + + Map responseData = verificationIssue == null + ? Map.of() + : Map.of( + SendSingleResponseDto.VERIFICATION_ID_KEY, + verificationIssue.verificationId(), + SendSingleResponseDto.EXPIRE_DT_KEY, + verificationIssue.expireDt().format(RESPONSE_DATE_TIME_FORMATTER) + ); + + return SendSingleResponseDto.of(sendResult.getCmid(), responseData); } public BulkSendResponseDto doSendBulk(SendRequestBulkDto req) { @@ -199,6 +241,7 @@ public abstract class AbstractSendService { TemplateDto tmplat = templateService.getTemplate(bulk.getTmplatIdx()); validateTemplateType(tmplat); + validateBulkTemplatePurpose(tmplat); Boolean isResve = bulk.getResve(); LocalDateTime sendDt = bulk.getSendDt() != null ? bulk.getSendDt() : now; @@ -326,6 +369,42 @@ public abstract class AbstractSendService { return replacePlaceholder(body, msgParam); } + private void validateSingleTemplatePurpose(TemplateDto tmplat, SendRequestSingleDto req) { + if (tmplat.getTmplatPurpose() != TemplatePurpose.PHONE_VERIFICATION) { + return; + } + + if (getChannelType() != ChannelType.SMS) { + throw BusinessException.badRequest( + "PHONE_VERIFICATION_SMS_ONLY", + "휴대전화번호 인증 템플릿은 문자 발송에서만 사용할 수 있습니다." + ); + } + + if (Boolean.TRUE.equals(req.getResve())) { + throw BusinessException.badRequest( + "PHONE_VERIFICATION_IMMEDIATE_ONLY", + "휴대전화번호 인증 문자는 즉시 발송만 사용할 수 있습니다." + ); + } + } + + private SendType resolveSendType(TemplateDto tmplat, String msgTitle, String msgBody) { + if (NotihubConst.SMS_TYPE_CODE_LIST.contains(tmplat.getTmplatTy().getCode())) { + return determineSms(msgTitle, msgBody); + } + return tmplat.getTmplatTy(); + } + + private void validateBulkTemplatePurpose(TemplateDto tmplat) { + if (tmplat.getTmplatPurpose() == TemplatePurpose.PHONE_VERIFICATION) { + throw BusinessException.badRequest( + "PHONE_VERIFICATION_SINGLE_ONLY", + "휴대전화번호 인증 템플릿은 단건 발송만 사용할 수 있습니다." + ); + } + } + /** * 자식 클래스가 구현: 실제 발송 수행 */ diff --git a/src/main/java/com/kri/notihub/server/service/PhoneVerificationIssue.java b/src/main/java/com/kri/notihub/server/service/PhoneVerificationIssue.java new file mode 100644 index 0000000..10e465a --- /dev/null +++ b/src/main/java/com/kri/notihub/server/service/PhoneVerificationIssue.java @@ -0,0 +1,13 @@ +package com.kri.notihub.server.service; + +import java.time.LocalDateTime; + +record PhoneVerificationIssue( + String verificationId, + String verificationCode, + String sendTel, + String message, + LocalDateTime regDt, + LocalDateTime expireDt +) { +} diff --git a/src/main/java/com/kri/notihub/server/service/PhoneVerificationService.java b/src/main/java/com/kri/notihub/server/service/PhoneVerificationService.java new file mode 100644 index 0000000..a46ac7b --- /dev/null +++ b/src/main/java/com/kri/notihub/server/service/PhoneVerificationService.java @@ -0,0 +1,123 @@ +package com.kri.notihub.server.service; + +import com.kri.common.feature.datetime.DateTimeUtil; +import com.kri.common.feature.web.BusinessException; +import com.kri.notihub.server.common.enums.PhoneVerificationStatus; +import com.kri.notihub.server.config.PhoneVerificationProperties; +import com.kri.notihub.server.dto.verification.PhoneVerificationRequestDto; +import com.kri.notihub.server.dto.verification.PhoneVerificationResponseDto; +import com.kri.notihub.server.persistence.entity.TPhoneVerificationEntity; +import com.kri.notihub.server.persistence.repository.PhoneVerificationRepository; +import java.security.SecureRandom; +import java.time.LocalDateTime; +import java.util.UUID; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; + +@Service +@RequiredArgsConstructor +public class PhoneVerificationService { + + private static final String PHONE_PATTERN = "^[0-9]{10,16}$"; + + private final PhoneVerificationRepository phoneVerificationRepository; + private final PhoneVerificationProperties properties; + private final SecureRandom secureRandom = new SecureRandom(); + + PhoneVerificationIssue issue(String sendTel, LocalDateTime now) { + String normalizedTel = normalizePhoneNumber(sendTel); + String verificationCode = String.format("%06d", secureRandom.nextInt(1_000_000)); + + return new PhoneVerificationIssue( + UUID.randomUUID().toString(), + verificationCode, + normalizedTel, + properties.renderMessage(verificationCode), + now, + now.plusMinutes(properties.getExpireMinutes()) + ); + } + + void persist(PhoneVerificationIssue issue, String cmid) { + phoneVerificationRepository.save( + TPhoneVerificationEntity.builder() + .verificationId(issue.verificationId()) + .cmid(cmid) + .verificationCode(issue.verificationCode()) + .sendTel(issue.sendTel()) + .status(PhoneVerificationStatus.PENDING.getCode()) + .attemptCount((short) 0) + .regDt(issue.regDt()) + .expireDt(issue.expireDt()) + .build() + ); + } + + @Transactional + public PhoneVerificationResponseDto verify(PhoneVerificationRequestDto request) { + String normalizedTel = normalizePhoneNumber(request.getSendTel()); + LocalDateTime now = DateTimeUtil.nowKstLocalDateTime(); + + TPhoneVerificationEntity entity = phoneVerificationRepository + .findByVerificationIdForUpdate(request.getVerificationId()) + .orElse(null); + + if (entity == null || !now.isBefore(entity.getExpireDt())) { + return failed(request.getVerificationId(), normalizedTel); + } + + boolean matches = entity.getSendTel().equals(normalizedTel) + && entity.getVerificationCode().equals(request.getVerificationCode()); + + if (entity.getStatus().equals(PhoneVerificationStatus.VERIFIED.getCode())) { + return PhoneVerificationResponseDto.of( + request.getVerificationId(), + normalizedTel, + matches, + matches ? entity.getVerifiedDt() : null + ); + } + + if (entity.getAttemptCount() >= properties.getMaxAttempts()) { + return failed(request.getVerificationId(), normalizedTel); + } + + if (!matches) { + entity.increaseAttemptCount(); + return failed(request.getVerificationId(), normalizedTel); + } + + entity.markVerified(now); + return PhoneVerificationResponseDto.of( + request.getVerificationId(), + normalizedTel, + true, + now + ); + } + + @Transactional + public int cleanupExpired() { + return phoneVerificationRepository.deleteExpired(DateTimeUtil.nowKstLocalDateTime()); + } + + String normalizePhoneNumber(String sendTel) { + if (sendTel == null) { + throw BusinessException.badRequest("PHONE_VERIFICATION_TEL_INVALID", "휴대전화번호는 필수입니다."); + } + + String normalized = sendTel.replace("-", "").replace(" ", ""); + if (!normalized.matches(PHONE_PATTERN)) { + throw BusinessException.badRequest( + "PHONE_VERIFICATION_TEL_INVALID", + "휴대전화번호 형식이 올바르지 않습니다." + ); + } + return normalized; + } + + private PhoneVerificationResponseDto failed(String verificationId, String sendTel) { + return PhoneVerificationResponseDto.of(verificationId, sendTel, false, null); + } +} diff --git a/src/main/java/com/kri/notihub/server/service/SendEmailService.java b/src/main/java/com/kri/notihub/server/service/SendEmailService.java index ff93b6e..3d79bbc 100644 --- a/src/main/java/com/kri/notihub/server/service/SendEmailService.java +++ b/src/main/java/com/kri/notihub/server/service/SendEmailService.java @@ -22,10 +22,12 @@ public class SendEmailService extends AbstractPringoSendService { PringoApiClient pringoApiClient, EmailResultPoller emailResultPoller, EmailBodyRenderer emailBodyRenderer, - EmailAttachmentService emailAttachmentService + EmailAttachmentService emailAttachmentService, + PhoneVerificationService phoneVerificationService ) { super(sendBulkJdbcWriter, templateRepository, bulkSendRepository, sendRepository, templateService, - pringoApiClient, emailResultPoller, emailBodyRenderer, emailAttachmentService); + pringoApiClient, emailResultPoller, emailBodyRenderer, emailAttachmentService, + phoneVerificationService); } @Override diff --git a/src/main/java/com/kri/notihub/server/service/SendKkoAtService.java b/src/main/java/com/kri/notihub/server/service/SendKkoAtService.java index 7270f68..c44ec0b 100644 --- a/src/main/java/com/kri/notihub/server/service/SendKkoAtService.java +++ b/src/main/java/com/kri/notihub/server/service/SendKkoAtService.java @@ -23,9 +23,11 @@ public class SendKkoAtService extends AbstractBizppurioSendService { BulkSendRepository bulkSendRepository, BizMsgRepository bizMsgRepository, SendRepository sendRepository, - TemplateService templateService + TemplateService templateService, + PhoneVerificationService phoneVerificationService ) { - super(sendBulkJdbcWriter, bizMsgBulkJdbcWriter,templateRepository, bulkSendRepository, bizMsgRepository, sendRepository, templateService); + super(sendBulkJdbcWriter, bizMsgBulkJdbcWriter, templateRepository, bulkSendRepository, + bizMsgRepository, sendRepository, templateService, phoneVerificationService); } @Override diff --git a/src/main/java/com/kri/notihub/server/service/SendSmsService.java b/src/main/java/com/kri/notihub/server/service/SendSmsService.java index 752f129..244ea37 100644 --- a/src/main/java/com/kri/notihub/server/service/SendSmsService.java +++ b/src/main/java/com/kri/notihub/server/service/SendSmsService.java @@ -10,8 +10,11 @@ import com.kri.notihub.server.persistence.repository.BizMsgRepository; import com.kri.notihub.server.persistence.repository.BulkSendRepository; import com.kri.notihub.server.persistence.repository.SendRepository; import com.kri.notihub.server.persistence.repository.TemplateRepository; +import com.kri.notihub.server.dto.send.SendRequestSingleDto; +import com.kri.notihub.server.dto.send.SendSingleResponseDto; import java.util.List; import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; @Service public class SendSmsService extends AbstractBizppurioSendService { @@ -23,9 +26,21 @@ public class SendSmsService extends AbstractBizppurioSendService { BulkSendRepository bulkSendRepository, BizMsgRepository bizMsgRepository, SendRepository sendRepository, - TemplateService templateService + TemplateService templateService, + PhoneVerificationService phoneVerificationService ) { - super(sendBulkJdbcWriter, bizMsgBulkJdbcWriter,templateRepository, bulkSendRepository, bizMsgRepository, sendRepository, templateService); + super(sendBulkJdbcWriter, bizMsgBulkJdbcWriter, templateRepository, bulkSendRepository, + bizMsgRepository, sendRepository, templateService, phoneVerificationService); + } + + @Override + @Transactional + public SendSingleResponseDto doSendSingle( + SendRequestSingleDto req, + String regCmpn, + String regUser + ) { + return super.doSendSingle(req, regCmpn, regUser); } @Override diff --git a/src/main/java/com/kri/notihub/server/service/TemplateService.java b/src/main/java/com/kri/notihub/server/service/TemplateService.java index 2305ec9..ca2e164 100644 --- a/src/main/java/com/kri/notihub/server/service/TemplateService.java +++ b/src/main/java/com/kri/notihub/server/service/TemplateService.java @@ -7,6 +7,7 @@ import com.kri.notihub.server.common.consts.NotihubConst; import com.kri.notihub.server.common.enums.ChannelType; import com.kri.notihub.server.common.enums.SendType; import com.kri.notihub.server.common.enums.TemplateEventType; +import com.kri.notihub.server.common.enums.TemplatePurpose; import com.kri.notihub.server.common.util.TemplateContentSanitizer; import com.kri.notihub.server.dto.email.EmailAttachmentDto; import com.kri.notihub.server.dto.template.TemplateBasicDto; @@ -125,6 +126,10 @@ public class TemplateService { .with("tmplatIdx", tmplatIdx) ); + if (template.getTmplatPurpose() == null) { + template.setTmplatPurpose(TemplatePurpose.fromCode(entity.getTmplatPurpose())); + } + validateBySendType(template); boolean attachmentChanged = hasAttachments(files) || hasDeleteFileNames(deleteFileNames); @@ -211,6 +216,10 @@ public class TemplateService { private void validateBySendType(TemplateBasicDto template) { //공통 검증 + if (template.getTmplatPurpose() == null) { + template.setTmplatPurpose(TemplatePurpose.NORMAL); + } + if (template.getTmplatTy() == null) { throw BusinessException.badRequest("NULL TYPE", "템플릿 타입은 필수입니다."); } @@ -237,6 +246,14 @@ public class TemplateService { } Short ty = template.getTmplatTy().getCode(); + if (template.getTmplatPurpose() == TemplatePurpose.PHONE_VERIFICATION + && !NotihubConst.SMS_TYPE_CODE_LIST.contains(ty)) { + throw BusinessException.badRequest( + "PHONE_VERIFICATION_SMS_ONLY", + "휴대전화번호 인증 템플릿은 SMS 또는 LMS/MMS 타입만 사용할 수 있습니다." + ); + } + if (NotihubConst.EMAIL_TYPE_CODE_LIST.contains(ty)) { if (StringUtil.isNullOrBlank(template.getSendEml())) { throw BusinessException.badRequest("EMPTY_EMAIL", "이메일은 필수입니다."); diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 146292a..4936593 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -62,6 +62,11 @@ kri: result-sync: fixed-delay-ms: 10000 batch-size: 1000 + verification: + expire-minutes: 5 + max-attempts: 5 + message-template: "인증번호는 [#{verificationCode}] 입니다." + cleanup-cron: "0 0 * * * *" auth: apikey: