team_agent/CLAUDE.md

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 단독) 시나리오를 고려한다