refactor: DB 제거 → 단일 hackathon.json (JSON only)
DB(sqlite + WAL) 제거. 모든 state를 단일 JSON 파일로 통합. 일회용/내부용이라 유지보수성/확장성보다 단순성 우선. 변경: - app.py: sqlite3 import 제거. load_data/save_data + threading.RLock + atomic write - votes: list of dict - titles, tie_breaks, settings: dict - people: roster (assign_teams가 채움) - 누락 키 자동 보강 - assign_teams.py: hackathon.json 단일 출력. 기존 votes/titles 보존 - Dockerfile/compose: votes.db volume 제거. hackathon.json read-write mount - tests/e2e.py: 12개 (12/12 통과). load/save/insert_vote/clear_votes/atomic 추가 - README: 새 데이터 구조 문서화 - roster.json/participants.json 제거 (hackathon.json으로 통합) 호스트 편집 워크플로: - jq/vi로 hackathon.json 직접 편집 - 앱 매 요청 reload — 컨테이너 재시작 불필요 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
115
README.md
115
README.md
@@ -1,82 +1,87 @@
|
||||
# 해커톤 투표
|
||||
|
||||
35명 / 7팀 / 3분야 (재미·완성도·실용성) 투표 앱. 본인 팀 제외 투표.
|
||||
35명 (34명 참가 + 1명 진행요원) / 7팀 / 3분야 (재미·완성도·실용성) 투표 앱.
|
||||
**DB 없이 단일 JSON 파일** (`hackathon.json`)에 모든 데이터.
|
||||
|
||||
## 흐름
|
||||
|
||||
1. `assign_teams.py` 실행 → `participants.json` 생성 (이름→팀 매핑)
|
||||
2. `app.py` 실행 → 참가자가 본인 이름 선택 → 자동 본인 팀 매핑 → 다른 6팀에 3분야 투표
|
||||
3. 어드민 페이지에서 분야별 1위와 2위 차이만 공개 (하위 표수는 expander 내부)
|
||||
1. `assign_teams.py` 실행 → `hackathon.json` 생성 (people 배정)
|
||||
2. `app.py` 실행 → 본인 이름 + 사번 입력 → 다른 6팀에 3분야 투표
|
||||
3. 어드민에서 마감 → 시상식 reveal
|
||||
4. 결과 자동 archive (`results_<ts>.json`)
|
||||
|
||||
## 실행 — Docker (권장)
|
||||
## 실행 — Docker
|
||||
|
||||
```bash
|
||||
# 1. 팀 배정 (호스트에서 1회, participants.json 생성)
|
||||
# 1. 팀 배정 (호스트에서 1회)
|
||||
python3 assign_teams.py
|
||||
|
||||
# 2. .env 작성 (1회)
|
||||
# 2. .env (1회)
|
||||
cp .env.example .env
|
||||
# .env 파일을 열어 ADMIN_TOKEN을 강한 랜덤 토큰으로 변경
|
||||
# ADMIN_TOKEN을 강한 토큰으로 변경
|
||||
# 빠르게: python3 -c "import secrets; print(secrets.token_urlsafe(16))"
|
||||
|
||||
# 3. 컨테이너 실행
|
||||
# 3. 컨테이너
|
||||
docker compose up -d --build
|
||||
|
||||
# 로그
|
||||
docker compose logs -f
|
||||
|
||||
# 종료
|
||||
docker compose down
|
||||
|
||||
# DB 영속 데이터까지 삭제
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
`.env`는 git ignore. token 노출 방지.
|
||||
|
||||
- 투표 DB는 docker volume `vote-data`에 영속 → 컨테이너 재시작해도 유지
|
||||
- `participants.json`은 호스트→컨테이너 read-only mount → 재배정 시 호스트에서 변경하고 컨테이너만 재시작
|
||||
|
||||
## 실행 — 로컬 (Docker 없이)
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
python3 assign_teams.py
|
||||
export ADMIN_TOKEN="강한-토큰-아무거나"
|
||||
streamlit run app.py --server.address 0.0.0.0 --server.port 8501
|
||||
```
|
||||
|
||||
## URL
|
||||
|
||||
- 참가자: `http://<홈서버-IP>:8501/`
|
||||
- 진행자: `http://<홈서버-IP>:8501/?mode=admin&token=<ADMIN_TOKEN>`
|
||||
- 투표: `http://<서버>:8501/`
|
||||
- 어드민: `http://<서버>:8501/?mode=admin&token=<TOKEN>`
|
||||
- 시상식: `http://<서버>:8501/?mode=ceremony&token=<TOKEN>`
|
||||
|
||||
## 흐름
|
||||
## 데이터 파일 — `hackathon.json`
|
||||
|
||||
1. 참가자 — 이름 입력 → 본인 팀 선택 → 본인 팀 빼고 3분야 라디오 → 제출
|
||||
2. 중복 방지 — 같은 이름은 한 번만 투표 가능 (UNIQUE 제약)
|
||||
3. 진행자 — 어드민 페이지에서 분야별 집계 확인
|
||||
4. 시상식 — 어드민 페이지 하단 "시상식 발표용" 박스 복사 (1위와 2위 차이만 표시, 하위 팀 표수 비공개)
|
||||
```json
|
||||
{
|
||||
"people": [
|
||||
{"name": "홍길동", "team": "팀1", "dept": "MLOps Data", "senior": true, "notes": ""},
|
||||
...
|
||||
],
|
||||
"settings": {"voting_open": true},
|
||||
"titles": {"팀1": "Slack 자동 분류기"},
|
||||
"tie_breaks": {
|
||||
"utility_team": {"winner_team": "팀1", "method": "random", "decided_at": "..."}
|
||||
},
|
||||
"votes": [
|
||||
{"voter_name": "...", "employee_id": "...", "voter_team": "...", "fun_team": "...",
|
||||
"polish_team": "...", "utility_team": "...", "created_at": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 데이터
|
||||
- 호스트에서 직접 편집 가능 (jq, vi 등). 앱이 매 요청 reload — 핫리로드.
|
||||
- 단일 파일 read-write mount. atomic write (tmp + rename).
|
||||
- 행사 전 명단 변경: `people[*].team` 값만 바꾸면 즉시 반영.
|
||||
- `assign_teams.py` 재실행 시 `people`만 갱신. votes/titles/tie_breaks 보존.
|
||||
|
||||
- `roster.json` — **단일 명단 파일** (`assign_teams.py` 산출물). 호스트에서 직접 편집 가능, 앱이 매 요청 reload.
|
||||
```json
|
||||
{
|
||||
"people": [
|
||||
{"name": "홍길동", "team": "팀1", "dept": "MLOps Data", "senior": true, "notes": ""},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
- 사람을 다른 팀으로 옮기기: `team` 값만 변경
|
||||
- 사람 추가/제거: 객체 추가/삭제
|
||||
- 변경 후 컨테이너 재시작 불필요 (핫리로드)
|
||||
- `participants.json` — legacy 형식 (이름→팀 string). roster.json 없으면 fallback.
|
||||
- `votes.db` (sqlite, WAL) — `votes`, `team_titles`, `tie_breaks`, `settings` 테이블
|
||||
## 운영 흐름
|
||||
|
||||
## 운영 팁
|
||||
1. 투표 시작 (기본 open)
|
||||
2. 모두 투표 → 어드민 "🛑 투표 마감"
|
||||
3. 동률 있으면 어드민에서 추첨/선택
|
||||
4. "팀별 결과물 제목" 입력 (또는 발표 직후)
|
||||
5. ceremony URL 띄움 → 시상 진행
|
||||
|
||||
- 행사 끝나면 `votes.db` 백업 후 보관 또는 삭제
|
||||
- 부정 투표 의심 시 어드민 → 위험 작업 → 전체 삭제 후 재투표 진행 가능
|
||||
- ADMIN_TOKEN은 `change-me` 기본값 — 반드시 변경
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
docker cp tests/e2e.py hackathon-vote:/tmp/e2e.py
|
||||
docker exec hackathon-vote python3 /tmp/e2e.py
|
||||
```
|
||||
|
||||
12개 시나리오 검증 (로드, 마감 토글, winner, priority, 동률, 추첨, UNIQUE, 제목, archive, atomic, clear).
|
||||
|
||||
## 시상 매핑
|
||||
|
||||
| 상 | 상품 | 평가 |
|
||||
|---|---|---|
|
||||
| 🛠 실용성상 | 팜레스트 5개 (최고가) | 실제 쓸 만함 |
|
||||
| 🏆 완성도상 | 양우산 5개 | 동작 / 시연 안정성 |
|
||||
| 🎉 재미상 | 손선풍기 5개 | 발표장 임팩트 |
|
||||
|
||||
수상 우선순위: 실용성 > 완성도 > 재미. 발표 순서: 재미 → 완성도 → 실용성 (긴장감).
|
||||
|
||||
Reference in New Issue
Block a user