별칭 검색 규칙 통일 — "앞부분만" 규칙 폐지와 푸쉬→푸시 별칭 41개 (2026-09-02)

• 기간: 2026-09-02 (세션 1개, 3feaf604-f4c8-4a2d-a319-21b18878f081). 오너 지시: "'푸쉬'라고 적힌 종목 별칭에 '푸시'도 일괄 추가" → 별칭 앞부분 규칙 설명에 "이거는 너무 이상한 규칙인데? 별칭도 똑같이 검색할 수 있어야지"
• 랜딩: PR #1141(Phase 1~2, c939c137). 마이그레이션 20260902236000_push_alias_variants_v1(데이터 1건). Production 반영은 릴리스 PR로 — 그 전까지 [스테이징]
• 설계서: 이슈 #1140 본문(예상 효과·개선사항 포함)
• 정본: exerciseSynonymSearch.ts(filter·matcher·diagnose) · 계약 exercise-search.md §6·매칭 규칙
• 도구: Production 예행 = Management API로 DO 블록 끝 raise 롤백(40건 추가·누락 0)
• 게이트: aliasSearchRule1140.test.mjs 4건 · 08-25 ov 테스트 교체 · 검색 확인 상자 테스트 갱신 · 마이그레이션 postcheck(대상만 단언)
• 버그리포트: 없음(규칙 변경 + 데이터 보강)
• 계약: exercise-search.md §6·"매칭 규칙" — alias도 표기와 같은 규칙

Phase 현황

Phase	내용	상태
Phase 1	별칭 매칭 = 표기와 동일(토큰 AND 부분 문자열), near-miss 안내 제거, 계약·테스트 갱신	✅ PR #1141
Phase 2	푸쉬→푸시 별칭 일괄 추가 마이그레이션(멱등, postcheck)	✅ PR #1141, Production dry-run 40건
Phase 3	로컬 게이트 → CI 1회 → 랜딩 잠금 verify → 머지 → 릴리스로 Production	✅ 머지(c939c137) · 릴리스 대기 [스테이징]

1. 배경

유저가 앱 검색에 '푸시업'이라고 치면 '푸쉬업' 하나만 나왔다. 정식 카탈로그는 '푸쉬' 표기를 쓰고, '푸시' 별칭은 푸쉬업·중량 푸쉬업 2개에만 있었다. 별칭을 더 넣으면 될 것 같지만, 별칭은 "검색어가 별칭의 앞부분일 때만" 맞는 규칙(2026-08-25)이라 '디클라인 푸시업' 별칭은 '푸시업' 검색에 걸리지 않는다.

2. 문제 제기

별칭의 앞부분-전용 규칙이 철자 변형을 못 받는다

08-25 규칙의 취지는 "별칭은 화면에 없으니 중간 일치는 이유를 알 수 없는 노이즈"('ov' → "Barbell Bent Over Row"로 바벨 로우가 뜸)였다. 그러나 철자 변형(푸쉬/푸시)은 별칭 데이터가 담당한다는 같은 계약 아래서, 이름 중간의 변형은 별칭으로 표현할 방법이 없었다 — 41개 종목 중 별칭으로 효과를 볼 수 있는 것은 이름이 '푸쉬'로 시작하는 3개뿐.

3. 해결 방안

원칙 (오너 결정, 2026-09-02)

• D1 별칭도 표기와 똑같이 검색. 'ov' 노이즈는 수용 — "어차피 이제 렌더 30개만 해서 버벅임 없으니까 그 규칙은 그냥 지워도 될듯"(창 렌더 #1056).

접근

대안	판단
검색 엔진에서 '쉬'='시' 동일 취급	기각 — 데이터 없이 되지만 다른 단어(쉬림프 등)까지 영향, 규칙이 늘어남
41개 종목에 '푸시…' 표기(동등 이름) 추가	기각 — 관리자 표기 카드가 41곳 늘고, 표기는 "다른 이름"용이지 철자 변형용이 아님
별칭 규칙을 표기와 통일 + '푸시' 별칭 41개	채택 — 철자 변형은 별칭 데이터가 담당한다는 계약을 지키면서 검색 누락 해소

4. 적용한 내용

Phase 1 — 별칭 매칭 통일 (#1141)

• filterExerciseSynonymRows·createExerciseSynonymMatcher·diagnoseExerciseSynonymSearch 3곳의 별칭 판정을 queryTokens.every(token => term.includes(token))로. "표기 매칭 우선 시 별칭 행 숨김"은 그대로.
• near-miss(prefixOnlyMisses) 개념 제거 — 타입·관리자 검색 확인 상자의 "별칭은 처음부터 일치할 때만… 표기로 승격" 안내 삭제.
• 계약 문서 §6·"매칭 규칙" 갱신. 08-25 'ov' 테스트를 새 규칙으로 교체, aliasSearchRule1140.test.mjs 4건(뒷부분 일치·어순 자유·'ov' 허용·표기 우선 숨김 유지·검색 확인 근거 별칭).

Phase 2 — 데이터 (#1141)

• 정식 종목 대표 표기 이름에 '푸쉬'가 든 행에 replace(name_ko,'푸쉬','푸시')를 array_append(이미 있으면 건너뜀). postcheck는 그 대상만 단언(전역 불변식 아님 — [[migration-postcheck-invariant-hazard]] 교훈).

주요 결정과 그 근거

• 3곳을 같은 식으로 고친 이유: 피커·관리자 표·검색 확인 상자가 같은 엔진을 쓰므로 한 곳만 바꾸면 "확인 상자는 나온다는데 검색엔 안 나온다"가 생긴다(재구현 금지 가드 테스트가 이를 잠근다).

작업 중 드러난 것

• 임시 마이그레이션 번호 20260902235900이 main의 그룹 UGC 안전 트랙(#1137)과 충돌 — 다른 세션이 큰 임시 번호를 그대로 랜딩했다. 임시 번호는 migrations:check로 꼬리를 먼저 보고 그 뒤로.
• check:deployment는 임시 번호라도 EXPECTED_LATEST_MIGRATION과 일치를 요구한다 — 로컬 게이트 전에 migrations:renumber(잠금 안에서)를 돌려야 통과.

5. 적용 결과

항목	결과
'푸시업' 검색 결과(엔진 시뮬레이션)	1개 → 푸쉬업 계열 25개(릴리스 후 Production 반영)
'푸시' 별칭 보유 종목	2 → 42(dry-run 40건 추가 + 기존 2)
유닛 테스트	2,347 → 2,361 (전부 green)
Production 반영	릴리스 PR 머지 시 — 미반영 상태로 [스테이징]

6. 이번 개선으로 향상된 것

철자 변형이 이름 어디에 있어도 검색된다

'푸시업'·'푸시다운'·'푸시프레스'를 치면 해당 계열이 전부 나온다. 별칭 규칙이 표기와 하나가 되어 "왜 이건 되고 저건 안 되지"가 사라진다.

남은 것

• 릴리스 PR 머지 → Production 반영 → 이슈 [반영완료].
• 다른 철자 변형(예: 데드리프트/데드 리프트는 접기로 이미 동일)은 보고 시 별칭 데이터로.