# Signit v2 Agent 프로젝트 가이드

## 시스템 전체 개요

스마트팜 IoT 통합 관리 플랫폼. Edge(농가 인트라넷) + Cloud(AWS) + Mobile App의 3계층 구조.

---

## 시스템 아키텍처

```
[모바일 앱]
    │ HTTPS API (FCM Push)
    ▼
[AWS Cloud]──────────────────────────────────────────────
│  signit_v2_manager_backend (FastAPI)                  │
│  - 통합 취합 및 동기화 관리                              │
│  - 앱 ↔ Edge 제어 중계 API                             │
│  - 관리자 페이지 API                                    │
│  - MongoDB + MariaDB + Redis                          │
│                                                       │
│  signit_v2_manager_frontend (Flutter Web)             │
│  - 관리자 모니터링 대시보드                               │
│                                                       │
│  FRP Server (터널링)                                   │
│  - 인증 후 Edge 원격 접속 연결                           │
──────────────────────────────────────────────────────────
    │ MQTT (QoS 1) + HTTP Push (동기화)
    │ Portainer Edge Agent (버전 배포, Pull 방식)
    ▼
[Edge - 각 농가 인트라넷] ────────────────────────────────
│  signit_v2_user_backend (FastAPI, port 8001)         │
│  - IoT 장비 제어 및 모니터링                            │
│  - Edge 로컬 인증 (오프라인 대응)                        │
│  - MariaDB only (경량 구성)                            │
│                                                       │
│  signit_v2_user_frontend (Flutter Web, port 80)      │
│  - 농가 현장 모니터링 UI                                │
│                                                       │
│  하드웨어: i5-5200U / 8GB RAM / 400GB                 │
│  외부 네트워크: 완전 차단 (Edge → Cloud 방향만 허용)      │
──────────────────────────────────────────────────────────
```

---

## 서브 프로젝트 구성

| 경로 | 역할 | 언어/프레임워크 | 환경 |
|------|------|---------------|------|
| `src/signit_v2_user_backend` | Edge API 서버 | Python/FastAPI | Linux Container (Edge) |
| `src/signit_v2_user_frontend` | Edge 현장 UI | Flutter Web | Linux Container (Edge) |
| `src/signit_v2_manager_backend` | Cloud 통합 서버 | Python/FastAPI | AWS Linux Container |
| `src/signit_v2_mobile` | 모바일 앱 | Flutter (iOS/Android) | App Store / Play Store |
| `src/signit_v2_frp` | 원격 접속 터널 | FRP (Go) | AWS Linux Container |

---

## Edge ↔ Cloud 통신 규칙

- **배포**: Portainer Edge Agent (Pull 방식) — Edge가 Cloud Portainer를 폴링해 자동 업데이트
- **데이터 동기화**: MQTT (실시간) + HTTP Push (대용량)
- **인증**: 하이브리드 JWT — 온라인(Central 발급) / 오프라인(Edge 자체 서명)
- **원격 접속**: FRP 터널 — 인증 페이지 → FRP Server에 Edge 매핑 → 화면 노출

---

## 개발 환경 제약

### Edge 서버 리소스 제약 (i5-5200U / 8GB)
- MongoDB/Redis 미사용 (경량 구성)
- Celery Worker 없음 → asyncio task 사용
- uvicorn worker 2~3개 제한
- 동일 서버에 여러 서비스 공존 → 과도한 서버 부하 구현 전 반드시 확인

### AWS 서버 리소스 (Xeon 2core / 8GB)
- 여러 프로젝트 서비스 공유 서버
- 대용량 데이터 처리, 실시간 스트리밍 설계 시 사전 확인 필요

---

## 작업 승인 규칙

| 작업 유형 | 사용자 확인 | 변경이력 기록 |
|---------|-----------|-------------|
| Read — 파일/코드 조회 | 불필요 | 불필요 |
| Add — 신규 파일/기능 생성 | 불필요 | **필요** |
| Update — 기존 파일/코드 수정 | **필요** | **필요** |
| Delete — 파일/코드 삭제 | **필요** | **필요** |

**Update/Delete 시 진행 방식:**
1. 변경할 내용과 이유를 먼저 설명한다
2. 사용자 승인을 받은 후 작업을 진행한다
3. 작업 완료 후 해당 프로젝트의 CHANGELOG.md에 변경이력을 기록한다

---

## 개발 규칙

- 작업 후 항상 해당 프로젝트의 md 문서를 업데이트한다
- 서버 부하 유발 기능은 구현 전 사용자에게 먼저 알리고 확인받는다
- Edge 리소스 제약을 항상 염두에 둔다
- 모든 설계는 오프라인(Edge 단독) 시나리오를 고려한다