건강한 각성을 위한 나만의 카페인 기록장 "당신의 커피 마감시간을 알려드립니다"
개인별 카페인 섭취량과 컨디션을 기록해, 지금 커피를 마셔도 되는지를 알려주는 웹 서비스입니다.
"카페인은 6시간 전까지만" — 이 조언은 모든 사람에게 똑같이 적용되지 않습니다.
같은 200mg을 마셔도 어떤 사람은 멀쩡히 자고, 어떤 사람은 새벽까지 뒤척입니다. 실제 연구에서도 개인별 카페인 반응 차이가 극단적으로 크다는 점이 확인되었고, 개인화 모델이 집단 평균 모델보다 유의미하게 정확한 예측을 보였습니다.
Caffeine Diary는 사용자의 섭취 기록 + 다음날 수면 피드백을 누적해, 그 사람만의 카페인 임계치를 추정합니다. 쓰면 쓸수록 정확해지는 마감시간을 제공하는 것이 목표입니다.
| 기능 | 설명 |
|---|---|
| 📖 카페인 다이어리 | 버튼 한 번으로 섭취 기록. 음료 종류별 카페인량 자동 계산 |
| ⏰ 오늘의 커피 마감시간 | 목표 취침시각 기준, 언제까지 마셔도 되는지 실시간 계산 |
| 🌙 밤샘모드 | 목표 시각까지 각성을 유지하기 위한 카페인 섭취 스케줄 추천 |
1단계 — 집단 평균 PK 모델
1구획 약동학 모델로 혈중 카페인 농도를 예측합니다.
C(t) = D · exp(-kₑ·t)
여러 잔을 마신 경우 선형 중첩(superposition)으로 합산합니다.
2단계 — 개인화
기록이 쌓일수록 집단 평균 임계치에서 개인 추정치 쪽으로 가중치가 이동합니다.
w = n / (n + n₀)
기록 수 n이 늘어날수록 개인 추정치의 비중이 커지는 구조입니다.
⚠️ 위 가중치 식은 Liu et al. (2017)의 확장 칼만 필터 기반 베이지안 축소추정 개념을 단순화한 근사이며, 논문에서 직접 인용한 수식이 아닙니다. 마감시각 역산 로직 또한 논문의 약동학 곡선을 본 프로젝트에서 응용·확장한 것입니다.
- Ramakrishnan, S. et al. (2014). Dose-dependent model of caffeine effects on human vigilance during total sleep deprivation. J Theor Biol, 358:11–24. 🔗
- Liu, J. et al. (2017). Real-time individualization of the unified model of performance. J Sleep Res, 26:820–831. 🔗
- Vital-Lopez, F. G. et al. (2018). J Sleep Research, 27:e12711.
- 2B-Alert App 검증 연구 (2023)
| 구분 | 사용 기술 |
|---|---|
| Backend | Django, Django REST Framework |
| Frontend | HTML, CSS, Vanilla JavaScript, Chart.js |
| Database | MySQL |
| Infra | AWS EC2, Docker, Nginx, Gunicorn |
| CI/CD | GitHub Actions |
| Auth | Django Session Authentication |
프론트·백엔드가 동일 도메인에서 서빙되는 구조이므로 JWT 대신 세션 인증을 채택했습니다.
| 모델 | 역할 |
|---|---|
Drink |
음료 마스터 테이블 (종류별 기본 카페인량) |
UserProfile |
사용자 상수 + 개인화 파라미터 (목표 취침시각, 추정 임계치 등) |
CaffeineLog |
섭취 이벤트 단위 기록 |
DailyLog |
하루 단위 수면 설문 결과 |
AllNightSession |
밤샘모드 세션 상태 |
설계 원칙
- 섭취 단위 데이터(
CaffeineLog)와 하루 단위 데이터(DailyLog)는 별도 모델로 분리 - 하루 경계는 05:00 기준 (새벽 시간대 섭취를 전날 기록으로 처리)
- 밤샘한 날은 수면 설문을 건너뜀
- 밤샘모드 스케줄은 화면 표시용으로만 계산, DB에 저장하지 않음
- Python 3.x
- MySQL
- Docker (선택)
# 1. 클론
git clone https://github.com/{ORG}/{REPO}.git
cd {REPO}
# 2. 가상환경
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. 의존성 설치
pip install -r requirements.txt
# 4. 환경변수 설정
cp .env.example .env # 값 채우기
# 5. 마이그레이션
python manage.py migrate
# 6. 실행
python manage.py runserverdocker compose up -d --buildmain ← 배포 가능한 안정 버전
↑
develop ← 개발 통합 브랜치 (기본 작업 대상)
↑
feature/* ← 기능 단위 작업 브랜치
- 모든 기능 브랜치는
develop에서 분기하고develop으로 머지합니다 - 배포 시점에만
develop→main으로 머지합니다 main,develop에는 직접 push 금지. 반드시 PR을 거칩니다
{타입}/{이슈번호}-{작업내용}
feature/12-cutoff-api
fix/15-timezone-bug
refactor/20-pk-model
docs/23-readme① Issue 생성 → ② Branch 생성 → ③ Commit → ④ Push
↓
⑦ Merge ← ⑥ Code Review ← ⑤ PR 생성
① Issue 생성
템플릿에 맞춰 작성하고 Label·Assignee를 지정합니다. 자동 부여된 번호(#12)를 이후 단계에서 계속 사용합니다.
② Branch 생성
git switch develop
git pull origin develop
git switch -c feature/12-cutoff-apiGitHub 이슈 페이지 우측 Development → Create a branch 를 쓰면 이슈와 자동으로 연결됩니다.
③ Commit
git commit -m "feat: 혈중 카페인 농도 계산 함수 추가 (#12)"④ Push
git push origin feature/12-cutoff-api⑤ PR 생성
- base:
develop/ compare: 작업 브랜치 - PR 본문에
Closes #12를 반드시 포함 (머지 시 이슈 자동 종료)
⑥ Code Review
- 최소 1명 이상 Approve 후 머지
- 리뷰어는 24시간 내 확인을 원칙으로 합니다
⑦ Merge
- 머지 후 원격 브랜치 삭제
- 로컬 정리:
git switch develop git pull origin develop git branch -d feature/12-cutoff-api
{타입}: {변경 내용} (#{이슈번호})
feat: 커피 마감시간 계산 API 구현 (#12)
fix: 자정 넘어간 취침시각 계산 오류 수정 (#15)
refactor: PK 모델 계산 로직 함수 분리 (#20)| 타입 | 사용 시점 |
|---|---|
feat |
새로운 기능 추가 |
fix |
버그 수정 |
refactor |
기능 변경 없는 코드 개선 |
style |
코드 포맷, 세미콜론 등 (로직 변경 없음) |
docs |
문서 수정 |
test |
테스트 코드 추가·수정 |
chore |
빌드, 설정, 패키지 등 기타 |
작성 규칙
- 제목은 50자 이내, 마침표 없이
- 본문이 필요하면 제목과 한 줄 띄우고 작성
- 한 커밋에는 하나의 논리적 변경만 담습니다
작업 종류
feature · bug · refactor · docs · setup · test
담당 영역
backend · frontend · infra
우선순위
P0-critical · P1-high · P2-low
상태
blocked · discussion
이슈 하나에
feature+backend+P1-high처럼 여러 라벨을 함께 붙입니다.
브랜치 하나 = PR 하나로 끝날 크기로 쪼갭니다.
| ❌ 너무 큼 | ✅ 적정 |
|---|---|
| 다이어리 기능 구현 | CaffeineLog 모델 작성 |
| 섭취 기록 생성 API | |
| 섭취 기록 목록 조회 API |
.
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── feature.md
│ │ ├── bug.md
│ │ └── refactor.md
│ ├── pull_request_template.md
│ └── workflows/
├── config/ # Django 프로젝트 설정
├── apps/ # 도메인별 앱
├── static/
├── templates/
├── requirements.txt
├── docker-compose.yml
└── README.md
| 이름 | 역할 | GitHub |
|---|---|---|
| 정현민 | 기획 / BE | @hyunnminn |
| 이아린 | BE | @ethan0587 |
| 이환희 | FE | @bigdevlight |
| 정다희 | FE | @jdheeee |