From 48e2dfaf38e84a146c04339dcc629ead8e902955 Mon Sep 17 00:00:00 2001
From: kjh2064 <kjh2064@gmail.com>
Date: Sat, 4 Jul 2026 02:48:15 +0900
Subject: [PATCH] docs: add development standards and guidelines (2026-07)

- Input validation pattern: client + server dual validation
- Korean phone number handling: supported formats and regex
- Message content length limits: 10-5000 characters
- DTO and DataAnnotations rules
- Telegram notification integration pattern
- On-site validation checklist for new forms

Establishes development standards for all future features.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index e855224..5face9f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,141 @@
 
 이 파일은 실행 절차, 서버 메모, 과거 이력만 둔다. 아키텍처/UX/콤보 기준은 위 문서를 따른다.
 
+## 🎯 **개발 핵심 지침 (Development Standards 2026-07)**
+
+### 입력 검증 패턴 (Validation Pattern)
+
+**원칙: 클라이언트 + 서버 이중 검증**
+
+#### 1. 클라이언트 (프론트엔드)
+- ✅ 실시간 마스킹 (사용자 입력하면서 자동 포맷팅)
+- ✅ 실시간 피드백 (에러 메시지 즉시 표시)
+- ✅ 유효성 검사 후 제출 차단
+- ✅ 문자 카운터 (예: "현재: 50/5000")
+
+**예시: 전화번호**
+```javascript
+// 입력: 01012345678 → 표시: 010-1234-5678
+// 정규식: ^(0(2|3[1-3]|4[1-4]|...|70|50[5-9])\d{7,8}|0\d{9,10})$
+```
+
+#### 2. 서버 (백엔드)
+- ✅ DTO 어노테이션 (DataAnnotations)
+- ✅ 서비스 로직 검증 (명확한 에러 메시지)
+- ✅ 데이터베이스 제약 조건
+
+**패턴: InquiryService.cs**
+```csharp
+// 1. DTO 레벨
+public class SubmitInquiryDto
+{
+    [Required]
+    [StringLength(100)]
+    public string Name { get; set; }
+
+    [Required]
+    [RegularExpression(@"^(0(2|3[1-3]|...")]
+    public string Phone { get; set; }
+
+    [StringLength(5000, MinimumLength = 10)]
+    public string Message { get; set; }
+}
+
+// 2. 서비스 로직
+public async Task<int> SubmitAsync(...)
+{
+    if (string.IsNullOrWhiteSpace(message))
+        throw new ValidationException("문의 내용을 입력하세요.");
+
+    var trimmedMessage = message.Trim();
+    if (trimmedMessage.Length < 10)
+        throw new ValidationException("문의 내용은 최소 10자 이상이어야 합니다.");
+}
+```
+
+### 한국 전화번호 처리 표준
+
+**지원 형식:**
+- 고정전화: `02-123-4567`, `031-1234-5678`
+- 휴대폰: `010-1234-5678`, `011-1234-5678`
+- VoIP: `070-1234-5678`, `0505-1234-5678`
+
+**포맷팅 규칙:**
+- 2-3자리 국번 + 3-4자리 국번 뒤 + 4자리 번호
+- 고정전화(10자): `XXXX-XXX-XXXX` (4-3-3)
+- 휴대폰(11자): `XXX-XXXX-XXXX` (3-4-4)
+
+**정규식:**
+```csharp
+private static readonly Regex PhoneRegex = new(
+    @"^(0(?:2|3[1-3]|4[1-4]|5[1-5]|6[1-4]|70|50[5-9]|[7-9](?:\d{1,2})?)\d{7,8}|0\d{9,10})$");
+```
+
+### 메시지 내용 길이 제한 표준
+
+**규칙:**
+- 최소: 10자 (너무 짧은 내용 방지)
+- 최대: 5000자 (DB 및 성능)
+
+**적용:**
+- 프론트엔드: `<textarea maxlength="5000">`, 실시간 카운터
+- 백엔드: `[StringLength(5000, MinimumLength = 10)]`
+- 서비스: 길이 검증 + 명확한 에러 메시지
+
+### DTO 및 데이터 어노테이션 규칙
+
+**필수 어노테이션:**
+```csharp
+using System.ComponentModel.DataAnnotations;
+
+public class SubmitInquiryDto
+{
+    [Required(ErrorMessage = "이름을 입력하세요.")]
+    [StringLength(100, ErrorMessage = "이름은 최대 100자입니다.")]
+    public string Name { get; set; }
+
+    [Required]
+    [RegularExpression(pattern, ErrorMessage = "올바른 형식이 아닙니다.")]
+    public string Phone { get; set; }
+
+    [StringLength(5000, MinimumLength = 10)]
+    public string Message { get; set; }
+}
+```
+
+**원칙:**
+- DTO는 기본 데이터 검증만 담당 (필수, 길이, 형식)
+- 복잡한 검증은 서비스 로직에서 처리
+- 모든 에러 메시지는 사용자 친화적
+
+### Telegram 알림 통합 패턴
+
+**구현 단계:**
+1. DTO에 검증 어노테이션 추가
+2. 서비스에서 비즈니스 로직 검증
+3. 데이터 저장 후 비동기 알림 발송
+4. 알림 실패해도 저장 데이터는 유지
+
+**예시: Contact.cshtml.cs**
+```csharp
+await _inquiryService.SubmitAsync(...);  // await로 완료 대기
+// 서비스 내부에서 TelegramInquiryNotificationService 호출
+```
+
+### 현장 검증 체크리스트
+
+새 폼/페이지 추가 시:
+
+- [ ] 클라이언트 검증: 실시간 마스킹 & 피드백
+- [ ] DTO: DataAnnotations 어노테이션 완성
+- [ ] 서버 검증: 서비스에 명확한 메시지 추가
+- [ ] 길이 제한: 적절한 Min/Max 설정
+- [ ] Telegram 알림: 서비스에 통지 로직 추가
+- [ ] 테스트: 유효/무효 데이터 모두 테스트
+- [ ] 로그: 제출 성공/실패 모두 기록
+
+---
+
 ## Gitea Token Rule
 
 - `GITEA_TOKEN_TAXBAIK`만 사용한다.