bcjang/python-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

초기 커밋

Browse Source
This commit is contained in:
basilro
2026-03-01 07:44:19 +09:00
commit 09359f30be
146 changed files with 6120 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

595
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,595 @@
# core-api 아키텍처 문서
## 1. 개요
IoT 임베디드 디바이스 통신, 사용자/관리자 관리, 모니터링, 데이터 분석을 지원하는 FastAPI 기반 통합 백엔드 서버이다. 향후 MSA 전환을 고려한 논리적 계층 분리를 핵심 설계 원칙으로 한다.
**주요 특징:**
- Flutter 웹/앱 프론트엔드 연동
- MariaDB + MongoDB 듀얼 DB
- MQTT + Socket.IO 실시간 통신
- Celery 비동기 태스크 처리
- RBAC 기반 접근 제어
---
## 2. 계층 아키텍처
```
┌─────────────────────────────────────────────────────────────┐
│ ASGI Entry Point │
│ Socket.IO ASGIApp (최외곽 래퍼) │
│ app/asgi.py │
├─────────────────────────────────────────────────────────────┤
│ Middleware Stack │
│ RequestIDMiddleware → RequestLoggingMiddleware → CORS │
├─────────────────────────────────────────────────────────────┤
│ API Layer │
│ app/api/v1/endpoints/*.py │
│ auth │ users │ devices │ monitoring │ analytics │ system│
├─────────────────────────────────────────────────────────────┤
│ Service Layer │
│ app/services/*.py │
│ AuthService │ UserService │ DeviceService │ ... │
├───────────────────────┬─────────────────────────────────────┤
│ Repository Layer │ Communication Layer │
│ app/repositories/*.py │ app/communication/ │
│ BaseRepository[T] │ mqtt/ │ socketio/ │ external/ │
├───────────────────────┴─────────────────────────────────────┤
│ DB Layer │
│ MariaDB │ MongoDB │ Redis │
│ app/db/mariadb.py │ mongodb.py │ redis.py │
└─────────────────────────────────────────────────────────────┘
│ │
┌───────┴───────┐ ┌────────┴────────┐
│ Celery Tasks │ │ Data Processing │
│ app/tasks/*.py │ │ app/processing/ │
└────────────────┘ └─────────────────┘
```
### 의존성 규칙
```
API Layer → Service Layer → Repository Layer → DB Layer
│
Communication Layer (MQTT, Socket.IO, External API)
│
Task Layer (Celery)
```
- 각 계층은 **바로 아래 계층만** 의존한다.
- 도메인 간 직접 Repository 호출을 금지하고, 반드시 Service 인터페이스를 통해 통신한다.
- 이 규칙을 지키면 향후 MSA 전환 시 Service 인터페이스를 gRPC/HTTP 호출로 교체하는 것만으로 분리가 가능하다.
---
## 3. 디렉토리 구조
```
python-api/
├── pyproject.toml # 의존성 + 빌드 설정
├── .env.example # 환경변수 템플릿
├── alembic.ini # Alembic 마이그레이션 설정
├── Dockerfile # 앱 이미지
├── Dockerfile.worker # Celery 워커 이미지
├── docker-compose.yml # 개발 환경
├── docker-compose.prod.yml # 프로덕션 오버라이드
│
├── alembic/ # DB 마이그레이션
│ ├── env.py
│ ├── script.py.mako
│ └── versions/
│
├── scripts/ # 운영 스크립트
│ ├── init_db.py # DB 시드 데이터
│ ├── create_superuser.py # 관리자 계정 생성
│ ├── run_dev.sh
│ ├── run_worker.sh
│ └── run_beat.sh
│
├── docker/
│ └── mosquitto/mosquitto.conf
│
├── tests/ # 테스트
│ ├── conftest.py
│ ├── unit/
│ ├── integration/
│ └── e2e/
│
├── docs/ # 문서
│
└── app/ # 애플리케이션 루트
├── main.py # FastAPI 앱 팩토리 + 라이프사이클
├── asgi.py # ASGI 엔트리포인트
├── core/ # 횡단 관심사
├── middleware/ # HTTP 미들웨어
├── db/ # DB 연결/세션
├── models/ # DB 모델 (mariadb/ + mongodb/)
├── schemas/ # Pydantic DTO
├── repositories/ # 데이터 접근 계층
├── services/ # 비즈니스 로직
├── api/ # API 라우터
├── admin/ # SQLAdmin 관리자 패널
├── communication/ # MQTT, Socket.IO, 외부 API
├── tasks/ # Celery 비동기 태스크
├── processing/ # 데이터 분석 파이프라인
└── utils/ # 범용 유틸리티
```
---
## 4. 기술 스택
| 카테고리 | 기술 | 용도 |
|---------|------|------|
| **Web Framework** | FastAPI + Uvicorn | ASGI 비동기 웹 서버 |
| **MariaDB ORM** | SQLModel + SQLAlchemy(async) + aiomysql | 관계형 DB 비동기 ORM |
| **Migration** | Alembic + pymysql | DB 스키마 마이그레이션 |
| **MongoDB ODM** | Beanie + Motor | 문서 DB 비동기 ODM |
| **Cache/Queue** | Redis (hiredis) | 캐싱 + Celery 브로커/백엔드 |
| **Auth** | python-jose + passlib[bcrypt] | JWT 토큰 + 비밀번호 해싱 |
| **MQTT** | fastapi-mqtt | IoT 디바이스 양방향 통신 |
| **WebSocket** | python-socketio | 실시간 프론트엔드 푸시 |
| **Background** | Celery + Flower | 비동기 태스크 + 모니터링 |
| **Admin** | SQLAdmin | 관리자 대시보드 |
| **Data** | Polars + Pandas + NumPy | 데이터 분석/집계/통계 |
| **Logging** | structlog | 구조화 로깅 (JSON/Console) |
| **Test** | pytest + pytest-asyncio + factory-boy | 테스트 프레임워크 |
| **Lint** | Ruff + mypy + pre-commit | 코드 품질 |
---
## 5. 데이터 모델
### 5.1 MariaDB (관계형 — SQLModel)
```
┌──────────────┐ 1:1 ┌──────────────┐
│ User │────────────▶│ UserProfile │
│──────────────│ │──────────────│
│ id (PK) │ │ user_id (FK) │
│ email │ │ full_name │
│ hashed_pwd │ │ phone │
│ role │ │ organization │
│ is_active │ │ avatar_url │
│ is_verified │ └───────────────┘
│ last_login_at│
└──────┬───────┘
│ 1:N
▼
┌──────────────┐ ┌───────────────┐
│ RefreshToken │ │ OAuthAccount │
│──────────────│ │───────────────│
│ user_id (FK) │ │ user_id (FK) │
│ token │ │ provider │
│ expires_at │ │ provider_uid │
│ is_revoked │ │ access_token │
└──────────────┘ └───────────────┘
┌──────────────┐ N:1 ┌──────────────┐
│ Device │────────────▶│ DeviceGroup │
│──────────────│ │──────────────│
│ device_uid │ │ name │
│ name │ │ description │
│ device_type │ └──────────────┘
│ status │
│ firmware_ver │
│ ip_address │
│ owner_id(FK) │
│ last_seen_at │
└──────────────┘
┌──────────────┐ ┌──────────────┐
│ AlertRule │ │ Alert │
│──────────────│ │──────────────│
│ metric │◀────────────│ rule_id (FK) │
│ condition │ │ device_id(FK)│
│ threshold │ │ severity │
│ severity │ │ message │
│ is_enabled │ │ is_ack │
└──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐
│ SystemConfig │ │ AuditLog │
│──────────────│ │──────────────│
│ key (unique) │ │ user_id (FK) │
│ value │ │ action │
│ is_secret │ │ resource_type│
└──────────────┘ │ details │
└──────────────┘
```
**공통 Mixin:**
- `TimestampMixin` — `created_at`, `updated_at` (서버 기본값 + 자동 갱신)
- `SoftDeleteMixin` — `is_deleted`, `deleted_at` (논리 삭제)
### 5.2 MongoDB (문서형 — Beanie)
| Collection | 주요 필드 | 인덱스 | 비고 |
|-----------|----------|--------|------|
| `device_logs` | device_id, event_type, payload, timestamp | device_id, event_type, timestamp(desc) | TTL: 90일 |
| `telemetry_data` | device_id, metrics(dict), timestamp | device_id, timestamp(desc), 복합(device_id+timestamp) | 시계열 |
| `analytics_results` | analysis_type, parameters, result, device_id, period | analysis_type, device_id, created_at(desc) | 분석 결과 |
| `notifications` | user_id, title, message, type, is_read | user_id, 복합(user_id+is_read), created_at(desc) | 사용자 알림 |
---
## 6. API 엔드포인트
### 6.1 인증 (`/api/v1/auth`)
| Method | Path | 설명 | 인증 |
|--------|------|------|------|
| POST | `/register` | 회원가입 → 토큰 반환 | - |
| POST | `/login` | 로그인 → 토큰 반환 | - |
| POST | `/refresh` | 리프레시 토큰으로 갱신 | - |
| POST | `/logout` | 모든 리프레시 토큰 폐기 | Bearer |
### 6.2 사용자 (`/api/v1/users`)
| Method | Path | 설명 | 권한 |
|--------|------|------|------|
| GET | `/me` | 내 정보 조회 | 인증됨 |
| PATCH | `/me` | 내 프로필 수정 | 인증됨 |
| GET | `/` | 사용자 목록 (페이징) | SUPERADMIN, ADMIN |
| GET | `/{user_id}` | 사용자 상세 | SUPERADMIN, ADMIN |
| POST | `/` | 사용자 생성 | SUPERADMIN, ADMIN |
| PATCH | `/{user_id}` | 사용자 수정 | SUPERADMIN, ADMIN |
| DELETE | `/{user_id}` | 사용자 삭제 (소프트) | SUPERADMIN, ADMIN |
### 6.3 디바이스 (`/api/v1/devices`)
| Method | Path | 설명 | 권한 |
|--------|------|------|------|
| GET | `/` | 디바이스 목록 (페이징) | 인증됨 |
| GET | `/{device_id}` | 디바이스 상세 | 인증됨 |
| POST | `/` | 디바이스 등록 | SUPERADMIN, ADMIN, MANAGER |
| PATCH | `/{device_id}` | 디바이스 수정 | SUPERADMIN, ADMIN, MANAGER |
| DELETE | `/{device_id}` | 디바이스 삭제 (소프트) | SUPERADMIN, ADMIN |
### 6.4 모니터링 (`/api/v1/monitoring`)
| Method | Path | 설명 | 권한 |
|--------|------|------|------|
| GET | `/health` | 시스템 상태 상세 | MANAGEMENT |
| GET | `/alerts` | 미확인 알림 목록 | MANAGEMENT |
| POST | `/alerts/{id}/acknowledge` | 알림 확인 처리 | 인증됨 |
| GET | `/alert-rules` | 알림 규칙 목록 | MANAGEMENT |
| POST | `/alert-rules` | 알림 규칙 생성 | 인증됨 |
### 6.5 분석 (`/api/v1/analytics`)
| Method | Path | 설명 | 권한 |
|--------|------|------|------|
| GET | `/telemetry/{device_id}` | 텔레메트리 집계 | MANAGEMENT |
| POST | `/reports/{device_id}` | 종합 리포트 생성 | MANAGEMENT |
| GET | `/status/{device_id}` | 디바이스 상태 분석 | MANAGEMENT |
| GET | `/trends/{device_id}` | 추세 분석 | MANAGEMENT |
| GET | `/results` | 분석 결과 조회 | MANAGEMENT |
### 6.6 시스템 (`/api/v1/system`)
| Method | Path | 설명 | 권한 |
|--------|------|------|------|
| GET | `/health` | 헬스체크 | - |
| GET | `/info` | 시스템 정보 | SUPERADMIN |
---
## 7. 인증/인가 체계
### 7.1 JWT 토큰 흐름
```
클라이언트 서버
│ │
│─── POST /auth/login ──────────▶│
│ {email, password} │
│ │── 비밀번호 검증
│ │── Access Token 생성 (30분)
│ │── Refresh Token 생성 (7일)
│ │── Refresh Token DB 저장
│◀── {access_token, │
│ refresh_token} ────────────│
│ │
│─── GET /api/v1/users/me ──────▶│
│ Authorization: Bearer {AT} │── decode_token()
│ │── get_current_user_payload()
│◀── {user data} ───────────────│
│ │
│─── POST /auth/refresh ────────▶│
│ {refresh_token} │── 기존 RT 폐기
│ │── 새 AT + RT 발급
│◀── {new tokens} ──────────────│
```
### 7.2 역할 기반 접근 제어 (RBAC)
```
SUPERADMIN (4) ─── 전체 시스템 관리, 시스템 설정
│
ADMIN (3) ─── 사용자/디바이스 관리, 삭제 권한
│
MANAGER (2) ─── 디바이스 등록/수정, 모니터링, 분석
│
USER (1) ─── 자기 프로필, 디바이스 조회
│
DEVICE (0) ─── 디바이스 전용 (MQTT 인증)
```
- `require_role(*roles)` — 허용된 역할만 접근 가능한 Dependency
- `can_manage_user(actor_role, target_role)` — 상위 역할만 하위 역할 관리 가능
---
## 8. 실시간 통신
### 8.1 MQTT (IoT 디바이스 ↔ 서버)
```
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ Device │──MQTT───▶│ Mosquitto │──────────▶│ Server │
│ │◀──MQTT───│ (Broker) │◀──────────│ │
└──────────┘ └──────────────┘ └──────────┘
```
**토픽 구조:**
| 방향 | 토픽 패턴 | 용도 |
|------|----------|------|
| Device → Server | `devices/{uid}/telemetry` | 센서 데이터 전송 |
| Device → Server | `devices/{uid}/status` | 상태 변경 알림 |
| Device → Server | `devices/{uid}/log` | 이벤트 로그 |
| Device → Server | `devices/{uid}/response` | 명령 응답 |
| Server → Device | `devices/{uid}/command` | 원격 명령 |
| Server → Device | `devices/{uid}/config` | 설정 변경 |
| Server → Device | `devices/{uid}/ota` | 펌웨어 업데이트 |
**데이터 파이프라인:**
```
MQTT 수신 → JSON 파싱 → MongoDB 저장 → Socket.IO 브로드캐스트
```
### 8.2 Socket.IO (서버 → 프론트엔드)
| 네임스페이스 | 이벤트 | 설명 |
|------------|--------|------|
| `/monitoring` | `telemetry` | 실시간 텔레메트리 데이터 |
| `/monitoring` | `device_status` | 디바이스 상태 변경 |
| `/device` | `device_response` | 디바이스 명령 응답 |
| `/device` | `send_command` | 클라이언트→디바이스 명령 전달 |
| `/notification` | `notification` | 사용자 알림 푸시 |
**Room 기반 구독:**
- `device:{device_uid}` — 특정 디바이스 모니터링
- `user:{user_id}` — 특정 사용자 알림
---
## 9. 비동기 태스크 (Celery)
### 9.1 큐 구성
```
┌─────────────┐
│ Redis │ ← Broker (redis://...6379/1)
│ (Broker) │ ← Result Backend (redis://...6379/2)
└──────┬──────┘
│
┌────┴────────────────────────────────┐
│ Celery Workers │
├─────────┬───────────┬───────────────┤
│ default │ analytics │ notifications │ devices │
│ queue │ queue │ queue │ queue │
├─────────┼───────────┼───────────────┤
│ 토큰정리 │ 일간분석 │ 푸시알림 │ 헬스체크 │
│ 이메일 │ 디바이스분석 │ 대량알림 │ OTA배치 │
└─────────┴───────────┴───────────────┘
```
### 9.2 Beat 스케줄 (정기 실행)
| 태스크 | 스케줄 | 큐 | 설명 |
|--------|--------|-----|------|
| `cleanup_expired_tokens` | 매일 03:00 | default | 만료/폐기된 리프레시 토큰 삭제 |
| `check_device_health` | 5분마다 | devices | 10분 이상 미응답 디바이스를 OFFLINE 처리 |
| `run_daily_analytics` | 매일 01:00 | analytics | 전일 텔레메트리 데이터 집계 및 저장 |
---
## 10. 미들웨어 파이프라인
요청은 아래 순서로 미들웨어를 통과한다:
```
요청 ──▶ RequestIDMiddleware ──▶ RequestLoggingMiddleware ──▶ CORS ──▶ FastAPI Router
│ │
│ X-Request-ID 생성/전파 │ method, path, status, elapsed_ms 로깅
│ structlog 컨텍스트 바인딩 │
▼ ▼
응답 ◀── X-Request-ID 헤더 추가 ◀── 로그 기록 ◀────────────────────── 핸들러 응답
```
**RateLimitMiddleware** (선택 사용):
- Redis 기반 IP별 속도 제한
- 기본값: 100 요청/60초
- `/docs`, `/redoc` 경로 제외
---
## 11. 데이터 분석 파이프라인
```
┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐
│ TelemetryData │────▶│ Polars/Pandas │────▶│ AnalyticsResult│
│ (MongoDB) │ │ Processing │ │ (MongoDB) │
└─────────────────┘ └──────────────────┘ └────────────────┘
│
┌─────────┴──────────┐
│ │
┌──────┴──────┐ ┌──────┴──────┐
│ Aggregation │ │ Analysis │
│ (Polars) │ │ (NumPy) │
│ │ │ │
│ - resample │ │ - trend │
│ - group_by │ │ - anomaly │
│ - mean/sum │ │ - percentile│
└─────────────┘ └─────────────┘
```
| 모듈 | 기능 |
|------|------|
| `telemetry_pipeline` | 시간 간격별 텔레메트리 집계 (Polars group_by_dynamic) |
| `report_pipeline` | 디바이스 종합 리포트 생성 (상태 + 추세) |
| `device_analyzer` | 디바이스 상태 변경 분석, 가동률 계산 |
| `trend_analyzer` | 선형 회귀 기반 추세 분석 (NumPy polyfit) |
| `statistics` | 이동평균, Z-score 이상치 탐지, 백분위 통계 |
---
## 12. MSA 전환 전략
현재 모놀리식 구조에서 각 도메인을 독립 서비스로 분리할 수 있는 논리적 경계가 이미 설정되어 있다.
| 도메인 | 현재 패키지 | 향후 MSA 서비스 | 주 DB |
|--------|------------|----------------|-------|
| auth | auth_service + auth_repo | Auth Service | MariaDB + Redis |
| users | user_service + user_repo | User Service | MariaDB |
| devices | device_service + device_repo | Device Service | MariaDB + MongoDB |
| monitoring | monitoring_service + monitoring_repo | Monitoring Service | MongoDB + Redis |
| analytics | analytics_service + analytics_repo | Analytics Service | MongoDB |
| notification | notification_service + socketio | Notification Service | Redis + MongoDB |
**전환 시 변경점:**
1. Service 간 호출을 HTTP/gRPC 클라이언트로 교체
2. 각 서비스별 독립 DB 인스턴스 할당
3. 이벤트 버스(Kafka/RabbitMQ)로 서비스 간 비동기 통신
4. API Gateway 도입 (인증/라우팅 통합)
---
## 13. 배포 구성
### 13.1 Docker 서비스
```
┌─────────────┐
│ Mosquitto │:1883 (MQTT)
└──────┬──────┘
│
┌──────────┐ ┌──────┴──────┐ ┌──────────┐
│ Redis │:6379 ◀─│ App │:8000 ──▶│ MariaDB │ (호스트)
└────┬─────┘ │ (FastAPI) │ └──────────┘
│ └──────┬──────┘ ┌──────────┐
│ │ ────▶│ MongoDB │ (호스트)
│ ┌──────┴──────┐ └──────────┘
├──────────────│ Worker │
│ │ (Celery) │
│ └─────────────┘
│ ┌─────────────┐
├──────────────│ Beat │
│ │ (Scheduler) │
│ └─────────────┘
│ ┌─────────────┐
└──────────────│ Flower │:5555 (모니터링)
└─────────────┘
```
- MariaDB/MongoDB는 **호스트에 직접 설치** (Docker 외부)
- App, Worker, Beat, Flower, Redis, Mosquitto는 **Docker 컨테이너**로 관리
### 13.2 환경별 차이
| 항목 | 개발 (docker-compose.yml) | 프로덕션 (docker-compose.prod.yml) |
|------|--------------------------|-----------------------------------|
| App 워커 수 | 1 (reload 모드) | 4 |
| Celery 동시성 | 2 | 4 |
| Worker 레플리카 | 1 | 2 |
| 로그 레벨 | info | warning |
| Flower 인증 | 없음 | basic_auth |
| 볼륨 마운트 | 소스 코드 (.:/app) | 이미지 내장 |
---
## 14. 실행 방법
### 개발 환경
```bash
# 1. 환경변수 설정
cp .env.example .env
# .env 파일에서 DB 접속 정보 등 수정
# 2. 의존성 설치
pip install -e ".[dev]"
# 3. DB 마이그레이션
alembic upgrade head
# 4. 시드 데이터
python -m scripts.init_db
# 5. 슈퍼관리자 생성
python -m scripts.create_superuser admin@example.com password123
# 6. 인프라 (Redis + Mosquitto)
docker-compose up -d redis mosquitto
# 7. 앱 서버 실행
uvicorn app.asgi:app --reload
# 8. Celery 워커 (별도 터미널)
celery -A app.tasks.celery_app worker --loglevel=info -Q default,analytics,notifications,devices
# 9. Celery 스케줄러 (별도 터미널)
celery -A app.tasks.celery_app beat --loglevel=info
```
### Docker 전체 스택
```bash
# 개발
docker-compose up -d
# 프로덕션
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```
### 검증
```bash
# 헬스체크
curl http://localhost:8000/api/v1/system/health
# Swagger UI
open http://localhost:8000/docs
# Flower (Celery 모니터링)
open http://localhost:5555
# SQLAdmin (관리자)
open http://localhost:8000/admin
```
---
## 15. 테스트
```bash
# 전체 테스트
pytest tests/ -v
# 커버리지
pytest tests/ -v --cov=app --cov-report=html
# 단위 테스트만
pytest tests/unit/ -v
# 통합 테스트만
pytest tests/integration/ -v
```
**테스트 구조:**
- `tests/unit/` — 순수 함수 테스트 (보안, 검증, 통계, 권한)
- `tests/integration/` — API 엔드포인트 + DB 연동 테스트
- `tests/e2e/` — 전체 CRUD 플로우 테스트