Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 162 additions & 0 deletions docs/specs/018-text-length-grapheme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# 텍스트 길이 제한 기준 변경 (grapheme cluster)

## Status

| 날짜 | Status | 변경 내용 |
|------|--------|-----------|
| 2026-08-21 | Draft | 최초 작성 — QA 중 프론트 리포트(이모지 30자 입력이 15자에서 거절됨). 대상은 **운전 목표·후기 내용** 두 필드 |
| 2026-08-21 | Implemented | 구현 완료 — `@GraphemeSize`+`GraphemeSizeValidator` 신규(`global/common/validation`), 운전 목표·후기 내용에 적용, V26으로 두 컬럼 `TEXT` 확장. 미해결 질문 1·3은 **범위 밖 유지**, 2는 `×20`으로 구현(사후 조정 가능) |

## 배경 / 목적

프론트에서 다음 리포트가 올라왔다.

> 안드로이드와 iOS의 이모지 글자 처리 방식이 달라, 안드로이드에서 이모지를 30자로 처리해 전달해도 서버가 15자만 받는다. 서버에서 UTF-16 문자열 단위로 제한하면 안드로이드는 정상 처리할 수 없다. 서버 처리가 힘들다면 이모지 자체를 입력하지 못하도록 막아야 한다.

원인은 **서버·클라이언트가 "1자"를 서로 다른 단위로 세는 것**이다. 현재 운전 목표에는 길이 제한이 두 겹 걸려 있는데, 그 둘도 단위가 다르다.

| 위치 | 현재 | 세는 단위 |
|------|------|-----------|
| 요청 검증 | `@Size(max = 30)` | **UTF-16 code unit** (`String.length()`) |
| DB 컬럼 | `driving_goal VARCHAR(30)` | **코드포인트** (Postgres varchar는 문자 수) |
| iOS | `String.count` | **grapheme cluster** |
| 안드로이드 | `BreakIterator` 사용 시 | **grapheme cluster** |

`@Size`가 가장 빡빡해 DB에 닿기 전에 거절되므로 지금 DB 에러는 나지 않지만, 사용자가 화면에서 세는 수와 서버가 세는 수가 어긋난다.

| 입력 | UTF-16 | 코드포인트 | grapheme | 현재 한도(30)로 입력 가능한 개수 |
|------|--------|-----------|----------|--------------------------------|
| `가` | 1 | 1 | 1 | 30개 |
| 😀 | 2 | 1 | 1 | **15개** |
| ❤️ (변이선택자) | 2 | 2 | 1 | 15개 |
| 👍🏻 (피부톤) | 4 | 2 | 1 | **7개** |
| 👨‍👩‍👧‍👦 (ZWJ 가족) | 11 | 7 | 1 | **2개** |

**사용자가 보는 글자 수 = grapheme cluster**이므로, 서버도 grapheme으로 세도록 바꾼다. 그러면 iOS·안드로이드·서버 셋이 같은 수를 세게 된다.

프론트가 대안으로 제시한 **이모지 입력 차단은 채택하지 않는다.** "이모지"를 정확히 판별하는 규칙(변이선택자·ZWJ·국기·피부톤)이 까다로워 오탐이 생기고, 운전 목표·후기에 이모지를 쓰는 건 자연스러운 사용이라 UX 손해가 크다.

### 함께 정정할 오해

서버는 초과분을 **자르지 않는다.** 한도를 넘으면 `400 COMMON_400`으로 요청 전체를 거절한다(`GlobalExceptionHandler`의 `MethodArgumentNotValidException` 처리). "15자만 받고 자른다"는 리포트는 16번째 이모지부터 400이 나 저장이 안 된 것을 잘림으로 해석한 것으로 보인다. 이 동작(거절)은 이번 변경에서도 유지한다.

### 범위 밖

- **다른 텍스트 필드** — 후기 주의사항(제한 없음), 신고 상세·미방문 사유 직접입력(100), 최근검색 표시명(100), 코스명(255)·설명·주의사항. 같은 문제를 갖고 있지만 이번에는 **QA에서 실제로 걸린 두 필드만** 바꾼다. 새 애노테이션은 재사용 가능하게 만들어 두므로 이후 필드는 한 줄 교체로 확장한다.
- **클라이언트의 글자 수 카운터 구현** — 앱이 `BreakIterator`(안드로이드) / `String.count`(iOS)로 세도록 맞추는 건 앱 몫이다.
- **이모지 차단·필터링**.
- **초과 시 서버 truncate** — 잘라 저장하지 않는다(입력 단계에서 앱이 막는다).

## 요구사항

### 기능 요구사항

1. **grapheme 기준 검증**: 운전 목표(30)·후기 내용(150)의 길이를 **grapheme cluster 수**로 센다. 이모지 30개짜리 운전 목표는 종류와 무관하게 통과해야 한다.
2. **한도 초과는 거절**: 한도를 넘으면 저장하지 않고 `400 COMMON_400`으로 응답한다. 잘라서 저장하지 않는다.
3. **저장 실패 없음**: 검증을 통과한 값은 **반드시 DB에 저장된다.** grapheme 30자는 코드포인트로 210자(가족 이모지 30개)를 넘길 수 있어 현재 컬럼 폭으로는 들어가지 않는다 → 컬럼을 넓힌다.
4. **재사용 가능한 검증**: 다른 텍스트 필드도 애노테이션 한 줄로 같은 규칙을 적용할 수 있어야 한다.
5. **기존 데이터 유지**: 이미 저장된 값은 그대로 남는다. 현재 검증이 새 기준보다 빡빡했으므로 새 기준을 어기는 기존 데이터는 존재할 수 없다.

### 비기능 요구사항

- **저장 크기 상한**: grapheme cluster는 이론상 길이 제한이 없다(ZWJ·결합문자를 무한히 이을 수 있다). 컬럼을 `TEXT`로 여는 대신 **코드유닛 절대 상한을 함께 둔다** — `grapheme ≤ max` **AND** `UTF-16 code unit ≤ max × 20`. 정상 입력(가족 이모지 11 code unit)은 여유롭게 통과하고, 비정상적으로 부풀린 값만 막는다.
- 검증 실패 응답 형식은 기존 Bean Validation 응답과 동일하게 유지한다(필드명 → 메시지 맵).
- 인증 요구사항은 기존 엔드포인트와 동일(모두 JWT).

## API 명세

**엔드포인트·요청·응답 스키마 변경 없음.** 통과/거절 기준만 바뀐다.

| Method | Path | 대상 필드 | 한도 | 인증 |
|--------|------|-----------|------|------|
| PATCH | `/api/v1/members/me` | `drivingGoal` | 30 grapheme | JWT |
| POST | `/api/v1/members/me/onboarding` | `drivingGoal` | 30 grapheme | JWT |
| POST | `/api/v1/places/{placeId}/reviews` | `content` | 150 grapheme | JWT |
| PUT | `/api/v1/reviews/{reviewId}` | `content` | 150 grapheme | JWT |

변경 전후 동작 비교 (운전 목표에 😀 20개 = grapheme 20 / UTF-16 40):

```json
// Request PATCH /api/v1/members/me
{ "drivingGoal": "😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀😀" }

// 변경 전 Response (400)
{
"isSuccess": false,
"code": "COMMON_400",
"message": "입력값이 올바르지 않습니다.",
"data": { "drivingGoal": "크기가 0에서 30 사이여야 합니다" }
}

// 변경 후 Response (200)
{ "isSuccess": true, "code": "COMMON_200", "message": "요청에 성공했습니다.", "data": null }
```

한도 초과 시 응답(운전 목표 31 grapheme):

```json
{
"isSuccess": false,
"code": "COMMON_400",
"message": "입력값이 올바르지 않습니다.",
"data": { "drivingGoal": "30자 이하로 입력해주세요." }
}
```

Swagger `@Schema` 설명의 "최대 30자"·"150자 이하"는 **"이모지·자모 포함 사용자가 보는 글자 수 기준"**임을 명시하도록 문구를 보강한다.

## 도메인 모델

### 새 검증 애노테이션 (`global/common/validation`)

프로젝트 첫 커스텀 validator다. 특정 도메인에 속하지 않으므로 `global/common` 아래 `validation` 패키지를 새로 만든다(`form`·`pagination`과 같은 층).

| 구성요소 | 역할 |
|----------|------|
| `@GraphemeSize(max = N)` | 필드에 붙이는 제약. `null`은 통과(선택 입력 필드라 `@NotNull`과 조합해 쓴다) |
| `GraphemeSizeValidator` | `java.text.BreakIterator.getCharacterInstance()`로 경계를 세어 판정. 코드유닛 절대 상한(`max × 20`)을 함께 검사 |

- 로케일 무관하게 동작해야 하므로 `BreakIterator`는 **`Locale.ROOT`** 로 생성한다.
- 메시지 기본값은 `"{max}자 이하로 입력해주세요."` — 기존 Bean Validation 기본 메시지보다 사용자 노출에 적합하다.
- `@Size`는 이 두 필드에서 **제거**한다(둘을 함께 두면 더 빡빡한 `@Size`가 먼저 걸려 변경이 무의미해진다).

### 마이그레이션 V26

> V25(`member.course_tutorial_completed_at`)가 현재 최대 번호다.

| 테이블·컬럼 | 변경 | 이유 |
|-------------|------|------|
| `member.driving_goal` | `VARCHAR(30)` → `TEXT` | 30 grapheme이 코드포인트 30을 넘을 수 있다 |
| `review.content` | `VARCHAR(150)` → `TEXT` | 150 grapheme이 코드포인트 150을 넘을 수 있다 |

- **폭을 넓힌 `VARCHAR`가 아니라 `TEXT`인 이유**: grapheme 하나의 코드포인트 수에 상한이 없어 안전한 `VARCHAR(N)`을 고를 수 없다. 어떤 N을 잡아도 적법한 입력을 DB가 거절할 수 있다. 저장 크기는 위 비기능 요구사항의 **코드유닛 절대 상한**이 애플리케이션에서 책임진다. Postgres에서 `TEXT`와 `VARCHAR(N)`은 저장 방식·성능이 동일하다.
- 두 컬럼 모두 **확장 방향**이라 기존 데이터 손실·재작성이 없다. 인덱스도 걸려 있지 않다.
- 엔티티의 `@Column(length = ...)`도 함께 정리한다 — `Member.drivingGoal`, `Review.content`(`length = MAX_CONTENT_LENGTH` 제거, `columnDefinition = "text"`). `Review.MAX_CONTENT_LENGTH` 상수는 **grapheme 한도**로 의미가 바뀐 채 유지한다(`@GraphemeSize(max = Review.MAX_CONTENT_LENGTH)`).

## 완료 조건 (Acceptance Criteria)

- [x] 운전 목표에 😀 30개(UTF-16 60)를 보내면 `PATCH /api/v1/members/me`가 **200**이고, 마이페이지 조회에서 30개가 그대로 돌아온다.
- [x] 운전 목표에 👨‍👩‍👧‍👦 30개(코드포인트 210)를 보내면 **200**이고 값이 잘리지 않고 저장된다(컬럼 폭 확장 검증).
- [x] 운전 목표에 31 grapheme(예: 한글 31자, 😀 31개)을 보내면 **400 `COMMON_400`**이고, `data.drivingGoal`에 "30자 이하로 입력해주세요."가 담긴다.
- [x] 온보딩(`POST /api/v1/members/me/onboarding`)의 `drivingGoal`도 동일한 기준으로 동작한다.
- [x] 후기 내용에 😀 150개를 보내면 작성(`POST`)·수정(`PUT`) 모두 **200**이고, 151 grapheme은 **400**이다.
- [x] 한글·영문 기준 경계값이 그대로 유지된다 — 운전 목표 한글 30자 200 / 31자 400, 후기 내용 150자 200 / 151자 400.
- [x] `drivingGoal`·`content`가 `null`이거나 공백이면 기존 동작(목표 삭제 / 내용 없이 저장)이 유지된다.
- [x] 코드유닛 절대 상한을 넘는 입력(grapheme 1개를 결합문자로 부풀려 코드유닛 1,000개)은 **400**으로 거절된다.
- [x] `GraphemeSizeValidator` 단위 테스트가 위 표의 입력별 카운트(가/😀/❤️/👍🏻/👨‍👩‍👧‍👦)를 모두 1로 센다.
- [x] Flyway V26이 적용되고 기존 저장 값이 그대로 조회된다.
- [x] `./gradlew test` 통과.

## 구현 노트

- **`BreakIterator`가 이모지 시퀀스를 제대로 묶는지 먼저 확인했다.** JDK 버전에 따라 ZWJ·국기·피부톤을 쪼개는 구현이 있어 설계 전제였다. 프로젝트 툴체인인 **JDK 21.0.2**에서 한글·😀·❤️·👍🏻·👨‍👩‍👧‍👦·🇰🇷·👩‍💻·결합 악센트 모두 **1로 세는 것을 확인**했다(`Pattern`의 `\X`도 동일 결과라 대안으로 남겨둔다).
- 검증 순서는 **코드유닛 상한 → grapheme 카운트**다. 부풀린 입력을 경계 순회 전에 잘라내며, 정상 입력은 상한에 걸릴 수 없다.
- `BreakIterator`는 스레드 안전하지 않아 판정마다 새로 만든다. 로케일에 따라 경계 규칙이 흔들리지 않도록 `Locale.ROOT`로 고정했다.
- 상수 위치는 기존 관례를 따랐다 — 후기는 `Review.MAX_CONTENT_LENGTH`(의미만 grapheme으로 바뀜), 운전 목표는 새로 `Member.DRIVING_GOAL_MAX_LENGTH`를 두고 수정·온보딩 두 DTO가 공유한다.
- `OnboardingRequest.practiceTypes`의 `@Size(max = 3)`은 **그대로 둔다** — 컬렉션 개수 제한이라 문자 수와 무관하다.

## 미해결 질문

1. *(미해결)* **후기 주의사항(`caution`)** — 지금 길이 제한이 **아예 없다**(DTO 무제약 + `TEXT`). 이번에 함께 한도를 둘지, 아니면 무제한을 유지할지. 디자인에 정해진 글자 수가 있으면 알려주면 같이 반영한다.
2. *(`×20`으로 구현, 조정 가능)* **코드유닛 절대 상한 배수(`max × 20`)** — 가족 이모지가 11 code unit이라 20배면 충분한 여유지만, 더 조이거나(×12) 아예 두지 않는 선택도 가능하다. 이 값으로 확정할지 확인이 필요하다.
3. *(미해결)* **나머지 텍스트 필드 확장 시점** — 신고 상세·미방문 사유·최근검색 표시명·코스명/설명/주의사항을 언제 같은 기준으로 옮길지. 지금은 범위 밖으로 두었지만, 앱에서 이모지 입력이 가능한 필드가 더 있다면 QA에서 같은 리포트가 반복된다.
1 change: 1 addition & 0 deletions docs/specs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,4 @@
| [내 코스 관리](015-my-course-management.md) | 내가 등록한 코스 상태별 목록·삭제(수정은 범위 밖) | Implemented |
| [코스 승인](016-course-approval.md) | 승인 상태 변경(임시로 로그인 사용자 전체, 추후 관리자 전용) | Implemented |
| [코스 등록 튜토리얼](017-course-tutorial.md) | 코스 등록 튜토리얼 완료 저장·로그인 응답으로 완료 여부 전달 | Implemented |
| [텍스트 길이 기준 변경](018-text-length-grapheme.md) | 운전 목표·후기 내용 길이를 grapheme cluster로 계산(이모지 글자 수 불일치 해소) | Implemented |
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
package cmc.rodi.domain.member.dto;

import cmc.rodi.domain.member.entity.Member;
import cmc.rodi.global.common.validation.GraphemeSize;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Size;

/**
* 회원 부분 수정 요청(마이페이지). 현재 수정 가능 필드는 운전 목표뿐이다. 빈 문자열/null이면 목표를 지운다(빈값 허용). 향후 수정 필드가 늘면 여기에 추가한다.
*/
public record MemberUpdateRequest(
@Schema(description = "운전 목표(최대 30자, 빈값이면 목표 삭제)", example = "골목길에 익숙해지기") @Size(max = 30)
@Schema(
description = "운전 목표(빈값이면 목표 삭제). 최대 30자 — 이모지·자모 포함 사용자가 보는 글자 수 기준",
example = "골목길에 익숙해지기")
@GraphemeSize(max = Member.DRIVING_GOAL_MAX_LENGTH)
String drivingGoal) {}
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,13 @@
import cmc.rodi.domain.member.entity.CarType;
import cmc.rodi.domain.member.entity.DrivingPeriod;
import cmc.rodi.domain.member.entity.Level;
import cmc.rodi.domain.member.entity.Member;
import cmc.rodi.domain.member.entity.PracticeType;
import cmc.rodi.domain.member.entity.RecentFrequency;
import cmc.rodi.domain.member.entity.RoadExperience;
import cmc.rodi.domain.member.entity.SoloDrivingRange;
import cmc.rodi.domain.member.entity.SoloParkingLevel;
import cmc.rodi.global.common.validation.GraphemeSize;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
Expand All @@ -29,4 +31,6 @@ public record OnboardingRequest(
@Schema(description = "선호 연습유형(1~3순위, 순서=우선순위). 선택") @Size(max = 3)
List<PracticeType> practiceTypes,
@Schema(description = "차종. 선택") CarType carType,
@Schema(description = "운전 목표(최대 30자). 선택") @Size(max = 30) String drivingGoal) {}
@Schema(description = "운전 목표(선택). 최대 30자 — 이모지·자모 포함 사용자가 보는 글자 수 기준")
@GraphemeSize(max = Member.DRIVING_GOAL_MAX_LENGTH)
String drivingGoal) {}
12 changes: 10 additions & 2 deletions src/main/java/cmc/rodi/domain/member/entity/Member.java
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@
@Table(name = "member")
public class Member extends BaseEntity {

/** 운전 목표 최대 길이(사용자가 보는 글자 수 = grapheme cluster). */
public static final int DRIVING_GOAL_MAX_LENGTH = 30;

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
Expand All @@ -42,8 +45,13 @@ public class Member extends BaseEntity {
@Column(length = 20)
private Level level;

/** 운전 목표(마이페이지 노출). 온보딩 추가 정보라 선택(NULL 가능). */
@Column(name = "driving_goal", length = 30)
/**
* 운전 목표(마이페이지 노출). 온보딩 추가 정보라 선택(NULL 가능).
*
* <p>길이 제한은 <b>grapheme cluster 기준</b>이라 컬럼 폭으로 강제할 수 없다(스펙 018) — 30자여도 코드포인트로는 210자를 넘길 수 있어
* {@code text}로 두고 {@code @GraphemeSize}가 책임진다.
*/
@Column(name = "driving_goal", columnDefinition = "text")
private String drivingGoal;

/** 누적 인정 주행거리(m). 레벨 승급 기준이며 <b>차감되지 않는다</b> — 연습기록을 지워도 그대로다(스펙 012). */
Expand Down
8 changes: 5 additions & 3 deletions src/main/java/cmc/rodi/domain/review/dto/ReviewRequest.java
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
import cmc.rodi.domain.review.entity.Difficulty;
import cmc.rodi.domain.review.entity.PracticeMethod;
import cmc.rodi.domain.review.entity.Review;
import cmc.rodi.global.common.validation.GraphemeSize;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

/**
* 후기 작성·수정 공용 요청. 수정은 전체 교체(PUT)라 작성과 같은 바디를 쓴다. 작성 당시 회원 레벨은 서버가 채우므로 요청에 없다.
Expand All @@ -22,9 +22,11 @@ public record ReviewRequest(
@Schema(description = "혼잡도") @NotNull Congestion congestion,
@Schema(description = "연습 방법") @NotNull PracticeMethod practiceMethod,
@Schema(
description = "후기 내용(선택, 150자 이하). 공백만 보내면 없는 것으로 저장된다",
description =
"후기 내용(선택, 150자 이하 — 이모지·자모 포함 사용자가 보는 글자 수 기준)."
+ " 공백만 보내면 없는 것으로 저장된다",
example = "차선이 넓고 신호가 단순해서 처음 도로 나갈 때 딱이었어요.")
@Size(max = Review.MAX_CONTENT_LENGTH)
@GraphemeSize(max = Review.MAX_CONTENT_LENGTH)
String content,
@Schema(description = "주의사항(선택, 길이 제한 없음)", example = "주말 오후엔 자전거 통행이 많습니다.")
String caution) {}
10 changes: 8 additions & 2 deletions src/main/java/cmc/rodi/domain/review/entity/Review.java
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
@Table(name = "review")
public class Review extends BaseEntity {

/** 후기 내용 최대 길이(사용자가 보는 글자 수 = grapheme cluster, 스펙 018). */
public static final int MAX_CONTENT_LENGTH = 150;

@Id
Expand Down Expand Up @@ -63,8 +64,13 @@ public class Review extends BaseEntity {
@Column(name = "practice_method", nullable = false, length = 20)
private PracticeMethod practiceMethod;

/** 후기 내용(선택). 글 없이 평가만 남길 수 있다 — 빈 문자열은 저장하지 않고 null로 정규화한다. */
@Column(length = MAX_CONTENT_LENGTH)
/**
* 후기 내용(선택). 글 없이 평가만 남길 수 있다 — 빈 문자열은 저장하지 않고 null로 정규화한다.
*
* <p>길이 제한은 <b>grapheme cluster 기준</b>이라 컬럼 폭으로 강제할 수 없다(스펙 018) — 150자여도 코드포인트로는 그보다 길어질 수 있어
* {@code text}로 두고 {@code @GraphemeSize}가 책임진다.
*/
@Column(columnDefinition = "text")
private String content;

/** 주의사항(선택, 길이 제한 없음). */
Expand Down
Loading
Loading