feat/seongdong/실험 결과 자동계산, 이벤트 수집, 사용자 식별, feature flag, 분석 대시보드 지원 api, 의사결정 이력, 회고 기능 추가

Author: seongdong2

.gitignore

@@ -29,4 +29,5 @@ bug-report*.html
 create_notion_page.py
 .claude/
 
-lvup
+lvup
+docs/seongdong/

backend/app/api/v1/api.py

@@ -1,8 +1,16 @@
 from fastapi import APIRouter
-from app.api.v1.endpoints import status, experiments, dashboard, bug_reports
+from app.api.v1.endpoints import (
+    status, experiments, dashboard, bug_reports,
+    events, feature_flags, analytics, decisions, reflections,
+)
 
 api_router = APIRouter()
-api_router.include_router(status.router, prefix="/status", tags=["status"])
-api_router.include_router(experiments.router, prefix="/experiments", tags=["experiments"])
-api_router.include_router(dashboard.router, prefix="/dashboard", tags=["dashboard"])
-api_router.include_router(bug_reports.router, prefix="/bug-reports", tags=["bug-reports"])
+api_router.include_router(status.router,        prefix="/status",        tags=["status"])
+api_router.include_router(experiments.router,   prefix="/experiments",   tags=["experiments"])
+api_router.include_router(dashboard.router,     prefix="/dashboard",     tags=["dashboard"])
+api_router.include_router(bug_reports.router,   prefix="/bug-reports",   tags=["bug-reports"])
+api_router.include_router(events.router,        prefix="",               tags=["events"])
+api_router.include_router(feature_flags.router, prefix="/feature-flags", tags=["feature-flags"])
+api_router.include_router(analytics.router,     prefix="/analytics",     tags=["analytics"])
+api_router.include_router(decisions.router,     prefix="",               tags=["decisions"])
+api_router.include_router(reflections.router,   prefix="/reflections",   tags=["reflections"])

backend/app/api/v1/endpoints/analytics.py

@@ -0,0 +1,46 @@
+from fastapi import APIRouter, Query
+from datetime import datetime
+from typing import Optional, List
+from app.schemas.analytics import (
+    EventListResponse, TrendsResponse, FunnelResponse,
+    RetentionResponse, FunnelRequest,
+)
+from app.services.analytics import analytics_service
+
+router = APIRouter()
+
+
+@router.get("/events", response_model=EventListResponse)
+async def get_events(
+    event_name: Optional[str] = Query(None),
+    from_: Optional[datetime] = Query(None, alias="from"),
+    to: Optional[datetime] = Query(None),
+    page: int = Query(1, ge=1),
+    limit: int = Query(20, ge=1, le=100),
+):
+    return await analytics_service.get_events(event_name, from_, to, page, limit)
+
+
+@router.get("/event-names", response_model=List[str])
+async def get_event_names():
+    return await analytics_service.get_event_names()
+
+
+@router.get("/trends", response_model=TrendsResponse)
+async def get_trends(
+    event_name: str = Query(...),
+    from_: datetime = Query(..., alias="from"),
+    to: datetime = Query(...),
+    granularity: str = Query("day", pattern="^(day|week)$"),
+):
+    return await analytics_service.get_trends(event_name, from_, to, granularity)
+
+
+@router.post("/funnels", response_model=FunnelResponse)
+async def get_funnels(data: FunnelRequest):
+    return await analytics_service.get_funnels(data.steps, data.from_, data.to)
+
+
+@router.get("/retention", response_model=RetentionResponse)
+async def get_retention(event_name: str = Query(...)):
+    return await analytics_service.get_retention(event_name)

backend/app/api/v1/endpoints/decisions.py

@@ -0,0 +1,26 @@
+from fastapi import APIRouter
+from typing import List
+from app.schemas.decision import Decision, DecisionCreate, LearningNote, LearningNoteCreate
+from app.services.decision import decision_service
+
+router = APIRouter()
+
+
+@router.post("/decisions", response_model=Decision, status_code=201)
+async def create_decision(data: DecisionCreate):
+    return await decision_service.create_decision(data)
+
+
+@router.get("/experiments/{experiment_id}/decisions", response_model=List[Decision])
+async def list_decisions(experiment_id: str):
+    return await decision_service.list_decisions(experiment_id)
+
+
+@router.post("/learning-notes", response_model=LearningNote, status_code=201)
+async def create_learning_note(data: LearningNoteCreate):
+    return await decision_service.create_learning_note(data)
+
+
+@router.get("/experiments/{experiment_id}/learning-notes", response_model=List[LearningNote])
+async def list_learning_notes(experiment_id: str):
+    return await decision_service.list_learning_notes(experiment_id)

backend/app/api/v1/endpoints/events.py

@@ -0,0 +1,17 @@
+from fastapi import APIRouter
+from app.schemas.event import EventCapture, PersonIdentify
+from app.services.event import event_service
+
+router = APIRouter()
+
+
+@router.post("/capture", status_code=202)
+async def capture(data: EventCapture):
+    await event_service.capture(data)
+    return {"success": True, "message": "accepted"}
+
+
+@router.post("/identify", status_code=200)
+async def identify(data: PersonIdentify):
+    await event_service.identify(data)
+    return {"success": True, "message": "identified"}

backend/app/api/v1/endpoints/experiments.py

@@ -1,7 +1,12 @@
 from fastapi import APIRouter, HTTPException, Query
 from typing import List, Optional
-from app.schemas.experiment import Experiment, ExperimentCreate, ExperimentUpdate, AssignmentResponse, ExperimentStatus
+from app.schemas.experiment import (
+    Experiment, ExperimentCreate, ExperimentUpdate,
+    AssignmentResponse, ExperimentStatus, ExperimentResult,
+)
+from app.schemas.reflection import ReflectionWindowUpdate
 from app.services.experiment import experiment_service
+from app.services.reflection import reflection_service
 
 router = APIRouter()
 
@@ -43,3 +48,14 @@ async def assign_user(experiment_id: str, user_id: str):
     if not result:
         raise HTTPException(status_code=404, detail="Experiment or variants not found")
     return result
+
+
+@router.get("/{experiment_id}/result", response_model=ExperimentResult)
+async def get_result(experiment_id: str):
+    return await experiment_service.get_result(experiment_id)
+
+
+@router.patch("/{experiment_id}/reflection-window")
+async def update_reflection_window(experiment_id: str, data: ReflectionWindowUpdate):
+    await reflection_service.update_reflection_window(experiment_id, data)
+    return {"success": True}

backend/app/api/v1/endpoints/feature_flags.py

@@ -0,0 +1,27 @@
+from fastapi import APIRouter, Query
+from typing import List
+from app.schemas.feature_flag import FeatureFlag, FeatureFlagCreate, FeatureFlagUpdate, FlagDecision
+from app.services.feature_flag import feature_flag_service
+
+router = APIRouter()
+
+
+@router.get("/decide", response_model=dict)
+async def decide(flag_key: str = Query(...), user_id: str = Query(...)):
+    variant = await feature_flag_service.decide(flag_key, user_id)
+    return {"success": True, "data": {"variant": variant}}
+
+
+@router.get("/", response_model=List[FeatureFlag])
+async def list_flags():
+    return await feature_flag_service.list()
+
+
+@router.post("/", response_model=FeatureFlag, status_code=201)
+async def create_flag(data: FeatureFlagCreate):
+    return await feature_flag_service.create(data)
+
+
+@router.patch("/{flag_key}", response_model=FeatureFlag)
+async def update_flag(flag_key: str, data: FeatureFlagUpdate):
+    return await feature_flag_service.update(flag_key, data)

backend/app/api/v1/endpoints/reflections.py

@@ -0,0 +1,26 @@
+from fastapi import APIRouter, Query
+from app.schemas.reflection import (
+    Reflection, ReflectionCreate,
+    ReflectionCheckResponse, ReflectionSummary,
+)
+from app.services.reflection import reflection_service
+
+router = APIRouter()
+
+
+@router.post("/", response_model=Reflection, status_code=201)
+async def submit_reflection(data: ReflectionCreate):
+    return await reflection_service.submit(data)
+
+
+@router.get("/check", response_model=ReflectionCheckResponse)
+async def check_reflection(
+    user_id: str = Query(...),
+    experiment_id: str = Query(...),
+):
+    return await reflection_service.check(user_id, experiment_id)
+
+
+@router.get("/summary", response_model=ReflectionSummary)
+async def reflection_summary(experiment_id: str = Query(...)):
+    return await reflection_service.summary(experiment_id)

backend/app/schemas/analytics.py

@@ -0,0 +1,63 @@
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Optional, List, Any
+
+
+class EventLogItem(BaseModel):
+    id: int
+    user_id: str
+    cohort_id: Optional[str] = None
+    event_name: str
+    properties: Optional[Any] = None
+    event_time: datetime
+    created_at: datetime
+
+
+class EventListResponse(BaseModel):
+    total: int
+    page: int
+    limit: int
+    items: List[EventLogItem]
+
+
+class TrendPoint(BaseModel):
+    date: str
+    count: int
+
+
+class TrendsResponse(BaseModel):
+    event_name: str
+    granularity: str
+    data: List[TrendPoint]
+
+
+class FunnelStep(BaseModel):
+    step: str
+    users: int
+    conversion_rate: Optional[float] = None
+
+
+class FunnelRequest(BaseModel):
+    steps: List[str]
+    from_: Optional[datetime] = None
+    to: Optional[datetime] = None
+
+    class Config:
+        populate_by_name = True
+
+
+class FunnelResponse(BaseModel):
+    steps: List[FunnelStep]
+
+
+class RetentionCell(BaseModel):
+    cohort_week: str
+    week_num: int
+    retained: int
+    cohort_size: int
+    retention_rate: float
+
+
+class RetentionResponse(BaseModel):
+    event_name: str
+    data: List[RetentionCell]

backend/app/schemas/decision.py

@@ -0,0 +1,40 @@
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Optional
+from enum import Enum
+
+
+class DecisionType(str, Enum):
+    SHIP = "SHIP"
+    HOLD = "HOLD"
+    ROLLBACK = "ROLLBACK"
+
+
+class DecisionCreate(BaseModel):
+    experiment_id: str
+    decision: DecisionType
+    reason: str
+    decided_by: str
+
+
+class Decision(BaseModel):
+    id: str
+    experiment_id: str
+    decision: DecisionType
+    reason: str
+    decided_by: str
+    decided_at: datetime
+
+
+class LearningNoteCreate(BaseModel):
+    experiment_id: str
+    content: str
+    created_by: Optional[str] = None
+
+
+class LearningNote(BaseModel):
+    id: str
+    experiment_id: str
+    content: str
+    created_by: Optional[str] = None
+    created_at: datetime