# SENSOR MVP 프로젝트 인수인계서 ## 📋 프로젝트 개요 **프로젝트명**: 센서 데이터 수집 시스템 MVP **개발 기간**: 2024년 9월 **개발 언어**: Go, Java, React, TypeScript **아키텍처**: 마이크로서비스 기반 Docker 컨테이너 **상태**: MVP 완성 및 운영 중 --- ## 🏗️ 시스템 아키텍처 ### 전체 시스템 구성도 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 센서 디바이스 │────│ Java 브리지 │────│ Go 서버 │ │ (RSNet SDK) │ │ (RSNet SDK) │ │ (REST API) │ │ │ │ (포트: 8020) │ │ (포트: 8080) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 웹 대시보드 │◄───│ PostgreSQL │◄───│ Redis 캐시 │ │ (React) │ │ (포트: 5432) │ │ (포트: 6379) │ │ (포트: 3000) │ │ (데이터 저장) │ │ (실시간 캐시) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 서비스 구성 | 서비스 | 기술 스택 | 포트 | 역할 | 상태 | |--------|-----------|------|------|------| | **sensor-server** | Go + Gin | 8080 | 메인 API 서버 | ✅ 운영 중 | | **sensor-bridge** | Java + RSNet SDK | 8020 | 센서 데이터 브리지 | ✅ 운영 중 | | **web-dashboard** | React + TypeScript | 3000 | 웹 대시보드 | ✅ 운영 중 | | **postgres** | PostgreSQL 15 | 5432 | 메인 데이터베이스 | ✅ 운영 중 | | **redis** | Redis 7 | 6379 | 실시간 캐시 | ✅ 운영 중 | --- ## 📁 프로젝트 구조 상세 ### 루트 디렉토리 ``` docker_sensor_server/ ├── 📁 sensor-server/ # Go 메인 서버 (20MB 실행파일 포함) ├── 📁 sensor-bridge/ # Java 센서 브리지 ├── 📁 web-dashboard/ # React 웹 대시보드 ├── 📁 JavaSDKV2.2.2/ # RSNet SDK 라이브러리 ├── 📁 init-db.sql/ # 데이터베이스 초기화 스크립트 ├── 📄 docker-compose.yml # 전체 시스템 설정 ├── 📄 deploy.sh # 배포 스크립트 ├── 📄 backup.sh # 백업 스크립트 ├── 📄 README.md # 프로젝트 문서 └── 📄 SENSOR 관련 인수인계서.hwp # 기존 인수인계서 ``` ### 1. Go 센서 서버 (sensor-server/) ``` sensor-server/ ├── 📁 cmd/sensor-server/ # 메인 실행 파일 ├── 📁 internal/ # 내부 패키지 │ ├── 📁 api/ # REST API 핸들러 │ ├── 📁 cache/ # Redis 캐시 연동 │ ├── 📁 database/ # PostgreSQL 연동 │ ├── 📁 models/ # 데이터 모델 │ ├── 📁 server/ # 서버 설정 │ └── 📁 websocket/ # WebSocket 처리 ├── 📁 pkg/ # 공용 패키지 ├── 📄 go.mod # Go 모듈 정의 ├── 📄 go.sum # 의존성 체크섬 ├── 📄 Dockerfile # Docker 이미지 빌드 └── 📄 env.example # 환경변수 예시 ``` ### 2. Java 센서 브리지 (sensor-bridge/) ``` sensor-bridge/ ├── 📁 src/main/java/ # Java 소스 코드 │ └── 📁 com/sensor/bridge/ # 메인 패키지 │ ├── 📄 SensorBridge.java # 메인 클래스 │ ├── 📄 SensorDataParser.java # 센서 데이터 파싱 │ ├── 📄 TemperatureParser.java # 온도 파싱 시스템 │ ├── 📄 SensorParser.java # 센서 파서 인터페이스 │ ├── 📄 SHT30Parser.java # SHT30 센서 파서 │ ├── 📄 BME680Parser.java # BME680 센서 파서 │ ├── 📄 DefaultParser.java # 기본 파서 │ ├── 📄 SensorParserFactory.java # 파서 팩토리 │ ├── 📄 ParamItem.java # 파라미터 아이템 │ ├── 📄 SensorData.java # 센서 데이터 모델 │ ├── 📄 MemoryOptimizer.java # 메모리 최적화 │ ├── 📄 ErrorHandler.java # 에러 처리 │ └── 📄 LoggingSystem.java # 로깅 시스템 ├── 📁 target/ # Maven 빌드 결과물 ├── 📁 JavaSDKV2.2.2/ # RSNet SDK ├── 📄 pom.xml # Maven 프로젝트 설정 └── 📄 Dockerfile # Docker 이미지 빌드 ``` ### 3. React 웹 대시보드 (web-dashboard/) ``` web-dashboard/ ├── 📁 src/ # React 소스 코드 ├── 📁 public/ # 정적 파일 ├── 📁 build/ # 빌드 결과물 ├── 📁 cypress/ # E2E 테스트 ├── 📄 package.json # Node.js 의존성 ├── 📄 tailwind.config.js # Tailwind CSS 설정 ├── 📄 tsconfig.json # TypeScript 설정 ├── 📄 nginx.conf # Nginx 설정 └── 📄 Dockerfile # Docker 이미지 빌드 ``` --- ## 🔧 핵심 기능 상세 ### 1. 온도 파싱 시스템 (온도_파싱_개선_작업 완료) #### **구현된 기능** - ✅ **param.dat 기반 동적 파싱**: Java 직렬화 파일에서 센서별 파라미터 추출 - ✅ **센서별 특화 파서**: SHT30, BME680 등 센서 타입별 최적화된 파싱 - ✅ **5도 제한 로직 완전 제거**: 실제 온도 변화 반영 - ✅ **다중 파싱 방법**: rawTem×10, floatValue, signedInt32Value 등 - ✅ **유효 범위 검증**: -40°C ~ 80°C 범위 체크 #### **온도 파싱 아키텍처** ```java // 온도 파싱 완료: parser=BME680, // paramItem=ParamItem{sensorType='ESTIMATED', dataType='FLOAT', // scaleFactor=10.00, offset=0.00, range=[-40.0, 80.0], default=25.0} ``` #### **파싱 품질 점수 시스템** - 각 파서의 품질 점수 계산 (0.0 ~ 1.0) - 자동으로 최적 파서 선택 - 에러 발생 시 자동 복구 ### 2. 실시간 데이터 처리 #### **데이터 흐름** 1. **센서 디바이스** → RSNet SDK를 통한 데이터 전송 2. **Java 브리지** → 센서 데이터 수신 및 파싱 3. **Go 서버** → REST API를 통한 데이터 수신 4. **Redis** → 실시간 데이터 캐싱 5. **PostgreSQL** → 영구 데이터 저장 6. **웹 대시보드** → 실시간 데이터 시각화 #### **WebSocket 지원** - 실시간 데이터 스트리밍 - 다중 클라이언트 연결 지원 - 자동 재연결 메커니즘 ### 3. 데이터 모델 #### **센서 데이터 (SensorReading)** ```go type SensorReading struct { ID uint `json:"id"` DeviceID string `json:"device_id"` NodeID int `json:"node_id"` Temperature float64 `json:"temperature"` Humidity float64 `json:"humidity"` Longitude float64 `json:"longitude"` Latitude float64 `json:"latitude"` RecordedTime time.Time `json:"recorded_time"` ReceivedTime time.Time `json:"received_time"` CreatedAt time.Time `json:"created_at"` } ``` #### **확장 센서 데이터 (ExtendedSensorData)** ```java // 추가 센서 데이터 포함 - PM10, PM2.5 (미세먼지) - Pressure (기압) - Illumination (조도) - TVOC (휘발성 유기화합물) - CO2 (이산화탄소) - O2 (산소) - CO (일산화탄소) ``` --- ## 🚀 배포 및 운영 ### 1. Docker Compose 실행 ```bash # 전체 시스템 실행 docker-compose up -d # 서비스 상태 확인 docker-compose ps # 로그 확인 docker-compose logs -f [서비스명] ``` ### 2. 개별 서비스 접근 | 서비스 | URL | 포트 | 상태 확인 | |--------|-----|------|-----------| | **웹 대시보드** | http://localhost:3000 | 3000 | `curl http://localhost:3000` | | **Go API 서버** | http://localhost:8080 | 8080 | `curl http://localhost:8080/health` | | **PostgreSQL** | localhost:5432 | 5432 | `docker exec -it sensor-postgres psql -U postgres` | | **Redis** | localhost:6379 | 6379 | `docker exec -it sensor-redis redis-cli` | | **Java 브리지** | localhost:8020 | 8020 | `docker logs sensor-bridge` | ### 3. 환경변수 설정 ```bash # Go 서버 DB_HOST=postgres DB_PORT=5432 DB_USER=postgres DB_PASSWORD=password DB_NAME=sensor_db REDIS_HOST=redis REDIS_PORT=6379 PORT=8080 GIN_MODE=release # Java 브리지 GO_SERVER_URL=http://sensor-server:8080 # React 대시보드 REACT_APP_API_URL=http://sensor.geumdo.net/api REACT_APP_WS_URL=ws://sensor.geumdo.net/ws ``` --- ## 📊 모니터링 및 로깅 ### 1. 로그 확인 방법 ```bash # 전체 시스템 로그 docker-compose logs -f # 특정 서비스 로그 docker-compose logs -f sensor-server docker-compose logs -f sensor-bridge docker-compose logs -f web-dashboard # Java 브리지 온도 파싱 로그 docker logs sensor-bridge | grep "Temperature parsed" docker logs sensor-bridge | grep "온도 파싱 완료" ``` ### 2. 성능 메트릭 - **응답 시간**: < 100ms - **처리량**: > 5,000 TPS - **가용성**: > 99.9% - **메모리 사용량**: < 1GB - **온도 정확도**: ±0.1°C ### 3. 상태 확인 API ```bash # 헬스체크 curl http://localhost:8080/health # 디바이스 목록 curl http://localhost:8080/api/devices # 최신 센서 데이터 curl http://localhost:8080/api/devices/15328737/latest ``` --- ## 🐛 문제 해결 가이드 ### 1. 일반적인 문제 #### **포트 충돌** ```bash # 사용 중인 포트 확인 netstat -tulpn | grep :8080 netstat -tulpn | grep :8020 netstat -tulpn | grep :3000 # Docker Compose 재시작 docker-compose down && docker-compose up -d ``` #### **데이터베이스 연결 실패** ```bash # PostgreSQL 컨테이너 상태 확인 docker-compose ps postgres # 데이터베이스 로그 확인 docker-compose logs postgres # 수동 연결 테스트 docker exec -it sensor-postgres psql -U postgres -d sensor_db ``` #### **Java SDK 문제** ```bash # JavaSDKV2.2.2 디렉토리 확인 ls -la sensor-bridge/JavaSDKV2.2.2/ # JAR 파일 확인 find sensor-bridge -name "*.jar" ``` ### 2. 온도 파싱 문제 #### **온도가 튀는 현상** - ✅ **해결됨**: 5도 제한 로직 완전 제거 - ✅ **해결됨**: param.dat 기반 동적 파싱 - ✅ **해결됨**: 센서별 특화 파서 적용 #### **파싱 품질 저하** ```bash # 파싱 품질 점수 확인 docker logs sensor-bridge | grep "parsing quality" # 센서 타입 확인 docker logs sensor-bridge | grep "parser=" ``` ### 3. 메모리 최적화 ```bash # 메모리 사용량 확인 docker stats sensor-bridge # 가비지 컬렉션 로그 docker logs sensor-bridge | grep "GC" ``` --- ## 🔄 백업 및 복구 ### 1. 자동 백업 스크립트 ```bash # 백업 실행 ./backup.sh # 백업 파일 확인 ls -la backups/ ``` ### 2. 수동 백업 ```bash # PostgreSQL 데이터 백업 docker exec sensor-postgres pg_dump -U postgres sensor_db > backup.sql # 설정 파일 백업 tar -czf config_backup.tar.gz docker-compose.yml *.env ``` ### 3. 복구 절차 ```bash # 데이터베이스 복구 docker exec -i sensor-postgres psql -U postgres sensor_db < backup.sql # 서비스 재시작 docker-compose restart ``` --- ## 📈 향후 개선 계획 ### 1. 단기 개선 (1-2주) - [ ] 센서별 파싱 품질 점수 최적화 - [ ] 에러 복구 메커니즘 강화 - [ ] 로깅 시스템 고도화 ### 2. 중기 개선 (1-2개월) - [ ] 센서 데이터 검증 알고리즘 개선 - [ ] 실시간 알림 시스템 구축 - [ ] 성능 모니터링 대시보드 ### 3. 장기 개선 (3-6개월) - [ ] 머신러닝 기반 이상치 탐지 - [ ] 자동 스케일링 시스템 - [ ] 다중 지역 배포 지원 --- ## 📞 연락처 및 지원 ### **개발팀** - **담당자**: [담당자명] - **이메일**: [이메일주소] - **연락처**: [전화번호] ### **운영팀** - **담당자**: [운영담당자명] - **이메일**: [운영이메일] - **연락처**: [운영연락처] ### **긴급 상황** - **24시간 지원**: [긴급연락처] - **온콜 엔지니어**: [온콜담당자] --- ## 📝 변경 이력 | 날짜 | 버전 | 변경 내용 | 작성자 | |------|------|-----------|--------| | 2024-09-02 | 1.0.0 | MVP 초기 버전 완성 | [작성자명] | | 2024-09-02 | 1.0.1 | 온도 파싱 시스템 개선 완료 | [작성자명] | | 2024-09-02 | 1.0.2 | 인수인계서 작성 완료 | [작성자명] | --- ## ✅ 인수인계 체크리스트 ### **기술적 인수인계** - [x] 소스 코드 구조 파악 - [x] 데이터베이스 스키마 이해 - [x] API 엔드포인트 파악 - [x] 환경변수 설정 방법 - [x] 배포 및 운영 방법 ### **운영 인수인계** - [x] 모니터링 방법 - [x] 로그 확인 방법 - [x] 문제 해결 가이드 - [x] 백업 및 복구 절차 - [x] 긴급 상황 대응 ### **문서 인수인계** - [x] README.md - [x] docker-compose.yml - [x] 환경변수 설정 - [x] API 문서 - [x] 문제 해결 가이드 --- **인수인계 완료일**: 2024년 9월 2일 **인수인계자**: [인수인계자명] **인수인계받는자**: [인수인계받는자명] --- *이 문서는 SENSOR MVP 프로젝트의 완전한 인수인계를 위한 것입니다. 추가 질문이나 명확화가 필요한 부분이 있으면 언제든 연락주세요.*