Skip to content

Commit 5f221ce

Browse files
sounmindclaude
andcommitted
docs: README에 매칭 알고리즘 섹션 추가
- 핵심 원칙 (2인 1조, 중복 방지, 공정한 무작위) - Mermaid 플로우차트로 매칭 과정 시각화 - 짝수/홀수 인원 예시 - 중복 방지 로직 설명 (최근 4회 이력 확인) Closes #8 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 65b7e7c commit 5f221ce

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

README.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,80 @@ gh workflow run match.yml
113113
5. Discord Webhook으로 결과 발표
114114
6. 자동 PR 생성 (`chore/update-match-history-YYYY-MM-DD`)
115115

116+
## 매칭 알고리즘
117+
118+
### 핵심 원칙
119+
120+
| 원칙 | 설명 |
121+
|-----|------|
122+
| **2인 1조** | 기본적으로 2명씩 매칭 |
123+
| **중복 방지** | 최근 4회 이력 내 같은 조합 불가 |
124+
| **공정한 무작위** | 모든 참여자에게 동등한 매칭 기회 |
125+
126+
### 매칭 과정
127+
128+
```mermaid
129+
flowchart TD
130+
A[참여자 목록] --> B[무작위 셔플]
131+
B --> C{홀수 인원?}
132+
C -->|Yes| D[1명 랜덤 선택 후 별도 보관]
133+
C -->|No| E[2명씩 매칭 시작]
134+
D --> E
135+
136+
E --> F{최근 4회 이력에<br/>같은 조합 있음?}
137+
F -->|Yes| G[재셔플]
138+
G --> F
139+
F -->|No| H[매칭 확정]
140+
H --> I{남은 인원 있음?}
141+
I -->|Yes| E
142+
I -->|No| J{홀수였음?}
143+
144+
J -->|Yes| K[보관된 1명을<br/>랜덤 조에 추가]
145+
J -->|No| L[매칭 완료]
146+
K --> L
147+
```
148+
149+
### 예시
150+
151+
**짝수 인원 (6명)**
152+
```
153+
참여자: A, B, C, D, E, F
154+
↓ 셔플
155+
결과: [A-D] [B-F] [C-E]
156+
(2인조 × 3)
157+
```
158+
159+
**홀수 인원 (5명)**
160+
```
161+
참여자: A, B, C, D, E
162+
↓ C를 랜덤 선택 후 보관
163+
↓ 나머지 4명 매칭
164+
중간: [A-E] [B-D]
165+
↓ C를 랜덤 조에 추가
166+
결과: [A-E-C] [B-D]
167+
(3인조 × 1, 2인조 × 1)
168+
```
169+
170+
### 중복 방지
171+
172+
최근 **4회** 매칭 이력을 확인하여 같은 조합이 반복되지 않도록 합니다.
173+
174+
```json
175+
// history.json 예시
176+
{
177+
"matches": [
178+
{ "date": "2024-01-01", "pairs": [["A","B"], ["C","D"]] },
179+
{ "date": "2024-01-15", "pairs": [["A","C"], ["B","D"]] },
180+
{ "date": "2024-01-29", "pairs": [["A","D"], ["B","C"]] },
181+
{ "date": "2024-02-12", "pairs": [["A","B"], ["C","D"]] }
182+
]
183+
}
184+
```
185+
186+
위 이력 기준:
187+
- 불가능한 조합: `A-B`, `C-D`, `A-C`, `B-D`, `A-D`, `B-C`
188+
- 4회 이전 이력은 다시 매칭 가능
189+
116190
## 개발
117191

118192
```bash

0 commit comments

Comments
 (0)