feat(api): implement member API with auth, filters, and Google Sheets backend

- FastAPI backend with Google OAuth login, email/phone verification, JWT auth
- Reusable filter system (BaseFilter → MemberFilter) with pagination and search
- Google Sheets as database via gspread wrapper
- Exception handling (AppException hierarchy with auto JSON mapping)
- Package renamed to bcsd_api, frontend/ directory added for future frontend
- Endpoints: POST /v1/auth/{login,verify-email,confirm-email,register},
  GET /v1/members, GET /v1/members/{id}

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ImTotem

.env.example

@@ -0,0 +1,20 @@
+# Google OAuth
+GOOGLE_CLIENT_ID=your-google-client-id
+
+# JWT
+JWT_SECRET=your-jwt-secret-key
+JWT_ALGORITHM=HS256
+JWT_EXPIRE_MINUTES=1440
+
+# Google Sheets
+GOOGLE_SHEETS_ID=your-google-sheets-id
+GOOGLE_SERVICE_ACCOUNT_FILE=credentials.json
+
+# SMTP (학교 이메일 인증)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+
+# Firebase
+FIREBASE_CREDENTIALS_FILE=firebase-credentials.json

.sisyphus/plans/bcsdlab-internal.md

@@ -0,0 +1,93 @@
+# BCSDLab INTERNAL - Google Workspace Automation System
+
+## Project Overview
+Club management automation system using **n8n** to orchestrate **Google Workspace** (Sheets as database, Forms for input, Docs for reports). FastAPI is optional glue for authorization checks (SpiceDB) when needed.
+
+## Architecture
+```
+Client → FastAPI (auth, member API) → Google Sheets (database)
+       → Google OAuth (ID Token 검증)
+       → Firebase Auth (전화번호 검증)
+       → SMTP (학교 이메일 인증)
+
+n8n (automation workflows) → Google Sheets (database) → Slack/Email (output)
+```
+
+### Core Principle
+- **Google Sheets IS the database** - no PostgreSQL/MongoDB needed
+- **FastAPI** handles auth (Google OAuth + JWT) and member CRUD
+- **n8n** handles automation workflows (fee reminders, status transitions)
+- **SpiceDB** - future consideration for fine-grained authorization
+
+### Components
+- **FastAPI**: Auth (Google OAuth, JWT), member API, filter system
+- **Google Sheets**: Source of truth (members, fees, groups, events, workflow_logs)
+- **n8n**: Automation workflows (fee reminders, notifications)
+- **Slack**: BCSDLab workspace (admin access available)
+- **Docker Compose**: Local dev + production environment
+
+## Key Technical Decisions
+- **Trigger**: Google Sheets trigger (polling, 1-2 min delay) - NOT Apps Script webhooks
+- **Notifications**: Email (SMTP) for MVP, Slack DM as enhancement
+- **IDs**: `{prefix}-{YYYYMMDDHHmmss}-{random3}` (e.g., `M-20240128143022-A7K`)
+- **Package name**: `bcsd_api` (backend), `frontend/` (frontend)
+- **Timezone**: `Asia/Seoul` (KST)
+- **Fee amount**: 10,000 KRW/month (MVP constant)
+
+## Google Sheets Schema
+- `members`: id, name, email, school_email, phone, status, track, team, join_date, payment_status, last_updated
+- `fees`: id, member_id, amount, paid_date, payment_method, notes, semester, last_updated
+- `groups`: id, name, type, parent_id, size, leader_email, last_updated
+- `events`: id, title, date, type, organizer, attendees, notes
+- `workflow_logs`: timestamp, workflow_name, status, input_data, output_data, error_message
+
+## Business Rules
+- **Fee model**: Payment-logging (rows exist ONLY when money received, NOT invoice model)
+- **No `due_date` column** in fees - due dates are implicit (first Monday of each month)
+- **Payment status**: Unpaid → Paid (on payment), Paid → Unpaid (semester reset), → Exempt (Mentor promotion)
+- **Member status**: Beginner → Regular → Mentor → Alumni
+- **Reminders**: Weekly on Mondays at 9am KST (`0 9 * * 1`)
+- **Foreign keys**: Store member ID (not email) in fees.member_id; lookups done by email
+
+## Execution Waves
+See `memory/plan-tasks.md` for detailed task breakdown.
+
+- **Wave 1** (Foundation): Docker Compose, Google API setup, Sheets schema design
+- **Wave 2** (n8n Dev): Sheets integration, Forms templates, data migration
+- **Wave 3** (Workflows): Fee payment, reminders, member onboarding, status transitions
+- **Wave 4** (Optional): SpiceDB authorization decision + implementation
+
+## Code Conventions (Python / FastAPI / Django)
+- indent depth는 2를 넘지 않는다. 1까지만 허용. 깊어지면 함수를 분리한다.
+- 삼항 표현식(`x if cond else y`)을 쓰지 않는다.
+- `else`를 쓰지 않는다. `match/case`도 허용하지 않는다. early return으로 해결한다.
+- 리스트, 딕셔너리, 집합 등 컬렉션 타입을 사용한다. `array` 모듈을 사용하지 않는다.
+- 함수명, 변수명은 가능한 한 단어(`snake_case` 기준 최대 두 단어).
+- 함수 길이는 15라인을 넘지 않는다. 함수는 한 가지 일만 한다.
+- 모든 모델/클래스를 작게 유지한다.
+- 이름을 축약하지 않는다.
+- 인스턴스 변수는 3개 이하로 유지한다. 단, Pydantic 모델(스키마)은 도메인 필드 수만큼 허용한다.
+- 확장성, 의존성, 클린 코드를 고려하여 구조를 설계한다.
+- 프레임워크를 적극 활용한다. (FastAPI `Depends`, Pydantic, Django ORM 등)
+- 패키지는 기능별로 묶는다.
+- 라우터 함수는 요청/응답 스키마 정의와 OpenAPI 문서화 용도로만 사용한다. 로직은 서비스 레이어에 위임한다.
+- 모든 API 엔드포인트는 `/v1/`으로 시작한다.
+- 템플릿(Cookiecutter, 프로젝트 보일러플레이트, Pydantic BaseModel 상속 등)을 적극 활용하여 반복 코드를 줄인다.
+
+## Documentation Convention
+- 각 작업(태스크) 완료 시 `docs/` 디렉토리에 인수인계용 문서를 작성한다.
+- 문서에는 다음을 포함한다:
+  - 작업 목적 및 배경
+  - 구현 내용 상세 (아키텍처, 데이터 흐름, 핵심 로직)
+  - 설정 방법 및 환경 변수
+  - 테스트/검증 방법
+  - 알려진 제약사항 및 향후 개선 사항
+- 문서만 보고 다른 사람이 해당 작업을 이해하고 유지보수할 수 있어야 한다.
+
+## Project Conventions
+- Commit messages: `feat(scope): description`, `docs(scope): description`
+- Workflow exports: `workflows/*.json`
+- Documentation: `docs/*.md`
+- Backend source: `src/bcsd_api/`
+- Frontend source: `frontend/`
+- Credentials: NEVER commit (`.gitignore` enforced)

CLAUDE.md

@@ -0,0 +1,100 @@
+# 회원 API 인수인계 문서
+
+## 작업 목적
+BCSDLab 동아리 회원 관리를 위한 FastAPI 백엔드 구현.
+Google OAuth 인증, 학교 이메일/전화번호 인증을 통한 회원가입과 JWT 기반 인증된 회원 조회 API를 제공한다.
+
+## 아키텍처
+
+```
+Client → FastAPI → Google Sheets (members 탭)
+                 → Google OAuth (ID Token 검증)
+                 → Firebase Auth (전화번호 검증)
+                 → SMTP (학교 이메일 인증 코드)
+```
+
+- **데이터 저장**: Google Sheets `members` 탭 (PostgreSQL 없음)
+- **인증**: Google OAuth → JWT 발급
+- **회원가입**: Google OAuth + 학교 이메일 인증 + Firebase Phone Auth
+
+## 프로젝트 구조
+
+```
+src/bcsd_api/
+├── main.py           # FastAPI app factory
+├── config.py         # pydantic-settings 환경변수
+├── dependencies.py   # 공용 Depends (Settings, Sheets, JWT 인증)
+├── id_gen.py         # M-{timestamp}-{random3} ID 생성
+├── exception/        # AppException 기반 예외 처리 (Spring @ControllerAdvice 스타일)
+├── filter/           # 재사용 필터 시스템 (BaseFilter → MemberFilter)
+├── sheets/           # gspread 래퍼 (Google Sheets 접근)
+├── auth/             # 인증 (Google OAuth, JWT, 이메일 인증, 회원가입)
+└── member/           # 회원 조회 (목록+필터, 상세)
+```
+
+## API 엔드포인트
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/v1/auth/login` | No | Google ID Token → JWT (기존 회원만) |
+| POST | `/v1/auth/verify-email` | No | 학교 이메일로 인증 코드 발송 |
+| POST | `/v1/auth/confirm-email` | No | 인증 코드 검증 |
+| POST | `/v1/auth/register` | No | 회원가입 완료 → JWT 발급 |
+| GET | `/v1/members` | Yes | 회원 목록 (필터+페이지네이션) |
+| GET | `/v1/members/{member_id}` | Yes | 회원 상세 조회 |
+
+### 필터 파라미터 (GET /v1/members)
+- `page`, `size`: 페이지네이션
+- `sort_by`, `sort_order`: 정렬
+- `status`, `track`, `team`, `payment_status`: 완전 일치 필터
+- `name`: 부분 일치 검색
+
+## 설정 방법
+
+### 환경 변수 (.env)
+`.env.example` 참고. 주요 변수:
+- `GOOGLE_CLIENT_ID`: Google OAuth 클라이언트 ID
+- `JWT_SECRET`: JWT 서명 키
+- `GOOGLE_SHEETS_ID`: Google Sheets 문서 ID
+- `GOOGLE_SERVICE_ACCOUNT_FILE`: 서비스 계정 JSON 파일 경로
+- `SMTP_*`: 이메일 발송 설정
+- `FIREBASE_CREDENTIALS_FILE`: Firebase 서비스 계정 JSON
+
+### Google Sheets 스키마 (members 탭)
+헤더 행: `id | name | email | school_email | phone | status | track | team | join_date | payment_status | last_updated`
+
+### 실행
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+python -m bcsd_api.main
+```
+Swagger UI: http://localhost:8000/docs
+
+## 핵심 설계 결정
+
+### 재사용 필터 시스템
+`filter/base.py`의 `BaseFilter` + `apply_filter()`는 어떤 리소스에도 재사용 가능.
+새 필터 추가 시 `BaseFilter`를 상속하고 Optional 필드만 추가하면 된다.
+`search_fields` 클래스 변수로 부분 일치 검색 필드를 선언한다.
+
+### 예외 처리
+`AppException`을 상속하여 선언적으로 에러 정의. `register_handlers()`에서 자동 JSON 매핑.
+Spring의 `@ControllerAdvice` 패턴과 동일한 구조.
+
+### 이메일 인증
+인메모리 딕셔너리에 코드 저장 (TTL 5분). MVP용이며, 프로덕션에서는 Redis 등으로 교체 권장.
+
+## 알려진 제약사항
+- 이메일 인증 코드는 서버 재시작 시 소실 (in-memory)
+- Google Sheets API 속도 제한 (분당 60회) → 대량 트래픽 시 캐싱 필요
+- Firebase Admin SDK 초기화가 아직 `main.py`에 포함되지 않음 → 회원가입 시 Firebase 설정 필요
+- `confirm-email` 성공 여부를 `register` 시점에 서버 측에서 재검증하지 않음 → 클라이언트 플로우에 의존
+
+## 향후 개선 사항
+- Redis 기반 인증 코드 저장소
+- Firebase Admin SDK 초기화 (`firebase_admin.initialize_app`)
+- 회원가입 시 이메일 인증 완료 여부를 서버에서 재확인하는 상태 관리
+- 회원 정보 수정 API (PUT /v1/members/{id})
+- 비밀번호 없는 인증이므로 refresh token 전략 검토

docs/member-api.md

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bcsd-api"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "pydantic-settings>=2.7.0",
+    "gspread>=6.1.0",
+    "google-auth>=2.38.0",
+    "google-api-python-client>=2.165.0",
+    "python-jose[cryptography]>=3.3.0",
+    "firebase-admin>=6.6.0",
+    "aiosmtplib>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

frontend/.gitkeep

@@ -0,0 +1,14 @@
+from google.oauth2 import id_token
+from google.auth.transport import requests as google_requests
+
+from bcsd_api.exception import Unauthorized
+
+
+def verify_token(token: str, client_id: str) -> dict:
+    try:
+        payload = id_token.verify_oauth2_token(
+            token, google_requests.Request(), client_id
+        )
+    except ValueError:
+        raise Unauthorized("invalid google token")
+    return {"email": payload["email"], "name": payload.get("name", "")}

pyproject.toml

@@ -0,0 +1,56 @@
+from fastapi import APIRouter, Depends
+
+from bcsd_api.config import Settings
+from bcsd_api.dependencies import get_settings, get_sheets
+from bcsd_api.sheets.client import SheetsClient
+
+from . import service
+from .schema import (
+    ConfirmEmailRequest,
+    ConfirmEmailResponse,
+    LoginRequest,
+    LoginResponse,
+    MessageResponse,
+    RegisterRequest,
+    VerifyEmailRequest,
+)
+
+router = APIRouter(prefix="/v1/auth", tags=["auth"])
+
+
+@router.post("/login", response_model=LoginResponse)
+def post_login(
+    body: LoginRequest,
+    settings: Settings = Depends(get_settings),
+    sheets: SheetsClient = Depends(get_sheets),
+) -> LoginResponse:
+    token = service.login(body.google_token, settings, sheets)
+    return LoginResponse(access_token=token)
+
+
+@router.post("/verify-email", response_model=MessageResponse)
+async def post_verify(
+    body: VerifyEmailRequest,
+    settings: Settings = Depends(get_settings),
+) -> MessageResponse:
+    await service.send_verify(body.email, settings)
+    return MessageResponse(message="verification code sent")
+
+
+@router.post("/confirm-email", response_model=ConfirmEmailResponse)
+def post_confirm(body: ConfirmEmailRequest) -> ConfirmEmailResponse:
+    result = service.confirm_verify(body.email, body.code)
+    return ConfirmEmailResponse(verified=result)
+
+
+@router.post("/register", response_model=LoginResponse)
+def post_register(
+    body: RegisterRequest,
+    settings: Settings = Depends(get_settings),
+    sheets: SheetsClient = Depends(get_sheets),
+) -> LoginResponse:
+    token = service.register(
+        body.google_token, body.school_email, body.phone,
+        body.firebase_token, body.track, settings, sheets,
+    )
+    return LoginResponse(access_token=token)