feat(api): add migration system, member fields, and refactor infrastructure

Introduce versioned migration system (V001 initial schema, V002 add
department/student_id) with shared helpers. Refactor dependency caching
to lru_cache, extract KST timezone module, coerce student_id from
Sheets int to str via Pydantic field_validator.

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

Author: ImTotem

CLAUDE.md

@@ -34,7 +34,7 @@ n8n (automation workflows) → Google Sheets (database) → Slack/Email (output)
 - **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
+- `members`: id, name, email, department, student_id, 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

docker-compose.yml

@@ -69,7 +69,8 @@ def post_register(
     sheets: SheetsClient = Depends(get_sheets),
 ) -> LoginResponse:
     token = service.register(
-        body.google_token, body.name, body.school_email,
+        body.google_token, body.name, body.department,
+        body.student_id, body.school_email,
         body.phone, body.track, settings, sheets,
     )
     _set_cookie(response, token, settings)

src/bcsd_api/auth/router.py

@@ -26,6 +26,8 @@ class ConfirmEmailResponse(BaseModel):
 class RegisterRequest(BaseModel):
     google_token: str
     name: str
+    department: str
+    student_id: str
     school_email: str
     phone: str
     track: str

src/bcsd_api/auth/schema.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timezone, timedelta
+from datetime import datetime
 
 from bcsd_api.config import Settings
 from bcsd_api.email.sender import EmailSender
@@ -9,8 +9,7 @@
 from . import google as google_auth
 from . import token as jwt_token
 from . import verify
-
-_KST = timezone(timedelta(hours=9))
+from bcsd_api.timezone import KST
 
 
 def login(google_token: str, settings: Settings, sheets: SheetsClient) -> str:
@@ -33,6 +32,8 @@ def confirm_verify(email: str, code: str) -> bool:
 def register(
     google_token: str,
     name: str,
+    department: str,
+    student_id: str,
     school_email: str,
     phone: str,
     track: str,
@@ -42,7 +43,10 @@ def register(
     profile = google_auth.verify_token(google_token, settings.google_client_id)
     _check_duplicate(profile["email"], sheets)
     member_id = generate_id("M")
-    row = _build_row(member_id, name, profile["email"], school_email, phone, track)
+    row = _build_row(
+        member_id, name, profile["email"],
+        department, student_id, school_email, phone, track,
+    )
     sheets.append_row("members", row)
     payload = {"sub": member_id, "email": profile["email"]}
     return _issue_jwt(payload, settings)
@@ -61,15 +65,20 @@ def _check_duplicate(email: str, sheets: SheetsClient) -> None:
 
 
 def _now_kst() -> str:
-    return datetime.now(_KST).strftime("%Y-%m-%d %H:%M:%S")
+    return datetime.now(KST).strftime("%Y-%m-%d %H:%M:%S")
 
 
 def _build_row(
-    member_id: str, name: str, email: str, school_email: str, phone: str, track: str
+    member_id: str, name: str, email: str,
+    department: str, student_id: str,
+    school_email: str, phone: str, track: str,
 ) -> dict:
     now = _now_kst()
     base = _base_fields(member_id, name, email)
-    extra = {"school_email": school_email, "phone": phone, "track": track}
+    extra = {
+        "department": department, "student_id": student_id,
+        "school_email": school_email, "phone": phone, "track": track,
+    }
     timestamps = {"join_date": now, "last_updated": now}
     return {**base, **extra, **timestamps}
 

src/bcsd_api/auth/service.py

@@ -13,6 +13,6 @@ class Settings(BaseSettings):
     cors_origins: str = "http://localhost:3000"
     cookie_name: str = "access_token"
     cookie_secure: bool = False
-    spicedb_endpoint: str = "localhost:50051"
+    spicedb_endpoint: str = "spicedb:50051"
     spicedb_token: str = "bcsd-dev-token"
     model_config = {"env_file": ".env"}

src/bcsd_api/config.py

@@ -17,39 +17,31 @@ def get_settings() -> Settings:
     return Settings()
 
 
-_sheets_cache: SheetsClient | None = None
+@lru_cache
+def _create_sheets(credentials: str, sheets_id: str) -> SheetsClient:
+    return SheetsClient(credentials, sheets_id)
 
 
 def get_sheets(settings: Settings = Depends(get_settings)) -> SheetsClient:
-    global _sheets_cache
-    if _sheets_cache:
-        return _sheets_cache
-    _sheets_cache = SheetsClient(
-        settings.google_service_account_file, settings.google_sheets_id
-    )
-    return _sheets_cache
+    return _create_sheets(settings.google_service_account_file, settings.google_sheets_id)
 
 
-_sender_cache: EmailSender | None = None
+@lru_cache
+def _create_sender(api_key: str, sender: str) -> EmailSender:
+    return ResendSender(api_key, sender)
 
 
 def get_email_sender(settings: Settings = Depends(get_settings)) -> EmailSender:
-    global _sender_cache
-    if _sender_cache:
-        return _sender_cache
-    _sender_cache = ResendSender(settings.resend_api_key, settings.resend_sender)
-    return _sender_cache
+    return _create_sender(settings.resend_api_key, settings.resend_sender)
 
 
-_authz_cache: AuthzClient | None = None
+@lru_cache
+def _create_authz(endpoint: str, token: str) -> AuthzClient:
+    return AuthzClient(endpoint, token)
 
 
 def get_authz(settings: Settings = Depends(get_settings)) -> AuthzClient:
-    global _authz_cache
-    if _authz_cache:
-        return _authz_cache
-    _authz_cache = AuthzClient(settings.spicedb_endpoint, settings.spicedb_token)
-    return _authz_cache
+    return _create_authz(settings.spicedb_endpoint, settings.spicedb_token)
 
 
 def get_member_repo(sheets: SheetsClient = Depends(get_sheets)) -> MemberRepository:

src/bcsd_api/dependencies.py

@@ -1,12 +1,12 @@
 import random
 import string
-from datetime import datetime, timezone, timedelta
+from datetime import datetime
 
-_KST = timezone(timedelta(hours=9))
+from .timezone import KST
 
 
 def generate_id(prefix: str) -> str:
-    now = datetime.now(_KST)
+    now = datetime.now(KST)
     timestamp = now.strftime("%Y%m%d%H%M%S")
     suffix = "".join(random.choices(string.ascii_uppercase + string.digits, k=3))
     return f"{prefix}-{timestamp}-{suffix}"

src/bcsd_api/id_gen.py

@@ -30,9 +30,8 @@ def _init_spicedb(settings) -> None:
 async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
     settings = get_settings()
     sheets = get_sheets(settings)
-    sheets.init_sheets()
-    from .sheets.defaults import seed
-    seed(sheets)
+    from .sheets.migrate import run as run_migrations
+    run_migrations(sheets.spreadsheet)
     try:
         _init_spicedb(settings)
     except Exception:

src/bcsd_api/main.py

@@ -14,7 +14,6 @@
 
 @router.get("/filters", response_model=FiltersResponse)
 def get_filters(
-    _: dict = Depends(current_user),
     sheets: SheetsClient = Depends(get_sheets),
 ) -> FiltersResponse:
     return service.get_filters(sheets)