🌿 ESG Carbon Dashboard (Carbon Strategic OS)

AI 기반 탄소 배출 관리 및 전략적 의사결정 지원 플랫폼

---

📖 1. 프로젝트 개요 (Project Overview)

ESG Carbon Dashboard는 기업의 환경적 책임(Environmental)을 데이터 중심의 전략적 자산으로 전환하기 위해 개발된 Carbon Strategic OS입니다.

단순히 과거의 배출량을 기록하는 데 그치지 않고, 다음과 같은 핵심 가치를 제공합니다:

• 실시간 트래킹: 글로벌 탄소 시장(EU-ETS, K-ETS)과 에너지 가격(WTI)을 연동한 실시간 리스크 분석.
• 경쟁사 벤치마킹: 탄소 집약도(Carbon Intensity) 기준 동종 업계 내 순위 및 격차 시각화.
• K-ETS 시뮬레이터: 국내/해외 배출을 분리해 순노출량, 준수비용, 통합 예산 리스크를 단계적으로 계산.
• 목표 기반 의사결정: SBTi 기반 감축 경로와 목표 달성 확률(Monte Carlo)을 정량적으로 제시하여 실행 우선순위 결정 지원.
• 지식 증강 질의응답: RAG(Retrieval-Augmented Generation) 기술을 통해 비정형 ESG 보고서에서 즉각적인 전략 인사이트를 추출.

이 프로젝트는 개발자뿐만 아니라 ESG 실무자, CFO, 그리고 지속 가능성 전략가가 실무에서 즉시 활용할 수 있는 수준의 전문 기술 도구를 목표로 합니다.

---

📑 2. 목차 (Table of Contents)

1. 시스템 아키텍처
2. 핵심 기능 및 설계 의도
   • Dashboard: 배출량 통합 대시보드
   • Compare: 경쟁사 비교 분석
   • Simulator: K-ETS 준수 비용 시뮬레이터
   • Target: SBTi 목표 관리
   • ChatBot: AI 전략 에이전트
   • 인증 시스템
   • 프로필 설정
3. 기술 스택 및 모듈 연동
4. 프로젝트 구조
5. 페이지 라우팅 구조
6. 설치 및 설정
7. API 명세
8. AI 모델 평가

---

📐 3. 시스템 아키텍처 (System Architecture)

3.1 전체 파이프라인

graph TB
    subgraph "Client Layer"
        Browser[웹 브라우저]
    end

    subgraph "Frontend (React 18 + TypeScript + Vite)"
        UI[UI Components<br/>Recharts / TailwindCSS 4]
        State[State Management<br/>React Hooks + localStorage]
        Router[View State Router<br/>URL Query Params + History API]
    end

    subgraph "Backend (FastAPI + Uvicorn, Port 8000)"
        Auth[Auth Router<br/>/auth]
        Profile[Profile Router<br/>/profile]
        Dashboard[Dashboard Router<br/>/api/v1/dashboard]
        Sim[Simulator Router<br/>/api/v1/sim]
        AI[AI Router<br/>/api/v1/ai]
    end

    subgraph "Data & AI Layer"
        MySQL[(MySQL DB<br/>users / dashboard_emissions)]
        ChromaDB[(ChromaDB<br/>Vector Store / RAG)]
        OpenAI[OpenAI API<br/>gpt-4o / gpt-4o-mini]
        BGE[BGE Embedding / Reranker<br/>bge-m3, bge-reranker-v2-m3]
    end

    subgraph "External Data Sources"
        yfinance[yfinance / yahoo_fin<br/>EU-ETS 가격]
        FDR[FinanceDataReader<br/>K-ETS KAU 가격]
    end

    Browser --> UI
    UI --> State --> Router
    Router -->|Axios HTTP/REST| Auth & Profile & Dashboard & Sim & AI
    Auth --> MySQL
    Profile --> MySQL
    Dashboard --> MySQL
    Sim --> yfinance & FDR
    AI --> ChromaDB & OpenAI
    ChromaDB --> BGE

---

🚀 4. 핵심 기능 및 설계 의도 (Core Features)

4.1 Dashboard Tab (배출량 통합 대시보드)

• 역할(Role): 기업의 Scope 1, 2, 3 배출 현황 및 재무 리스크 지표를 한눈에 시각화.
• 의도(Purpose):
  • 즉각적인 현황 파악: 경영진이 4개의 KPI 카드(총 탄소 배출량, 탄소 집약도, 배출권 거래 단가, SBTi 달성 확률)를 빠르게 파악하도록 설계.
  • Scope별 배출 기여도: Scope별 배출량 수치와 비중(%)을 시각화.
  • 궤적 시각화: 2021년부터의 실제 배출량 추이와 회귀 예측값을 Scope별로 파악할 수 있도록 시각화.
  • 바로가기 카드: KPI 카드 클릭 시 관련 탭(경쟁사 비교, 시뮬레이터, 목표 관리)으로 즉시 이동.
• KPI 카드 구성:
  1. 총 배출량 (Scope 1+2): tCO₂e
  2. 탄소 집약도: 해당 기업의 탄소 집약도(tCO₂e / 매출 1억원) 또는 에너지 집약도(TJ/억원)로 전환 가능
  3. K-ETS: 실시간 한국 배출권 거래 단가
  4. SBTi 달성 확률: SBTi 국제 표준 기준으로 Monte Carlo 시뮬레이션 결과 (%) 감축 달성 확률을 표기

---

4.2 Compare Tab (경쟁사 비교 분석)

• 역할(Role): 동일 업종 기업의 탄소/에너지 집약도를 정렬하여 상대 포지션을 빠르게 파악.
• 핵심 동작:
  • 집약도 모드 전환: revenue(탄소 집약도), energy(에너지 집약도)
  • Scope 토글: S1/S2 반영 여부를 즉시 차트 계산에 반영
  • 기준선 자동 계산: 상위 10% 및 중앙값 임계선 오버레이
  • 카드 선택 연동: 선택 기업 강조 + 인사이트 내용 동기화
  • 실행 연계: 세부 실행 계획 버튼으로 Simulator 탭 이동
• 기술 요소:
  • CompareTab.tsx: Recharts BarChart, ReferenceLine, 동적 색상 셀 렌더링
  • 백엔드 연계: POST /api/v1/dashboard/compare/insight로 AI 인사이트 생성
  • 네비게이션: navigateTo('dashboard', 'simulator')

---

4.3 Simulator Tab (K-ETS 준수 비용 시뮬레이터)

• 역할(Role): 국내 직접 배출 이행비용과 해외 노출비용을 통합해 연간 탄소 예산 관점의 의사결정을 지원.
• 4단계 구조:
  1. 국내 직접 탄소량: 예상배출량, 무상할당, 순노출량(Net Exposure), 컴플라이언스 비용 계산
  2. 전략 배분: 순노출량 중 우선 집행/잔여 이행 비율 시뮬레이션
  3. 해외 탄소 배출량: 해외 S1+S2와 EUA, EUR/KRW 환율로 해외 예상비용 산출
  4. 결과 요약: 국내+해외 통합 총계와 예산 대비 리스크 등급 제공
• 시나리오 입력값:
  • ETS 가격(실시간/직접 입력)
  • 배출량 변동(%)
  • 무상할당 정책 변동
  • 경매 조달 비중
  • 연간 탄소 예산(사용자 직접 입력)
• 계산 기준(핵심):
  • 순노출량 = 조정 배출량 - 조정 무상할당량
  • 컴플라이언스 비용 = 순노출량 × 실효 탄소가격(경매 할인 반영)
  • 해외 예상비용 = 해외 S1+S2 × EUA × EUR/KRW
  • 통합 총계 = 국내 총 탄소비용 + 해외 예상비용
• 데이터 기준 분리:
  • Simulator: 국내 직접 배출(s1Domestic, s2Domestic) 우선 사용
  • Dashboard/Compare/Target: 전체 배출(s1, s2, s3) 사용
• 기술 요소:
  • 프론트: SimulatorTab.tsx (상태 기반 즉시 재계산)
  • 백엔드: GET /api/v1/sim/dashboard/market-trends
  • 시장 데이터: yfinance(EU-ETS), FinanceDataReader(K-ETS)
  • 환율 데이터: open.er-api.com EUR 기준 실시간 조회 + fallback(1450)

---

4.4 Target Tab (SBTi 목표 관리)

• 역할(Role): SBTi 기준연도(2021) 대비 감축 경로와 현재 실적 간 격차를 시각화하고 2030/2050 목표 달성 가능성을 정량화.

• 의도(Purpose):

  • 목표 정렬: 기준 배출량(2021), 현재(최신) 배출량, SBTi 목표 달성 여부를 한 화면에서 확인.
  • 확률 기반 판단: 로그 회귀 Monte Carlo(10,000회) 기반 2030 목표 달성 확률 제공.
  • Net Zero 2050 추적: 현재 감축률과 2050 목표(90%+ 감축) 간 격차 실시간 표시.
  • 정확한 목표달성도 판정: 현재 연도(2026)가 아닌 최신 데이터 연도(latestDataYear, 최신 발간된 ESG보고서에서의 연도 기준이며 현재는 2024년)로 설정하여 동일 연도 기준으로 정확히 판정.

• KPI 카드 구성:

  1. 기준 배출량 (2021): tCO₂e
  2. 최신 배출량: tCO₂e + 2021년 대비 % 감축
  3. SBTi 달성 여부: 목표 대비 격차를 판단하여 명시
  4. Net Zero 2050: 필요 총 감축량(90%+), 현재 달성(%), 잔여 격차(%)

• 예측 방법론:

  모델: log(E_t) = α + β*t  (로그-선형 OLS 회귀)
  감축 목표: 연간 4.2% (SBTi 절대 감축 기준)
  Monte Carlo: 10,000회 샘플링 → 2030 달성 확률 계산
  

• 기술 요소: OLS 회귀, Monte Carlo 시뮬레이션(10,000회), Recharts(궤적 차트).

---

4.5 ChatBot (AI 전략 에이전트)

• 역할(Role): ESG 문서 기반 질의응답 + 시장/전략 맥락형 답변 제공

• 핵심 동작:

  • 스트리밍 응답: 토큰 단위 출력으로 체감 응답 지연 최소화
  • 대화 문맥 유지: 이전 대화(history)와 선택 회사 컨텍스트 전달
  • 리포트 스코프 제어: 최신/전체 보고서 범위 선택 가능
  • 전략 보조: 별도 strategy 엔드포인트로 시뮬레이터 전략 문안 생성

• 기술 요소:

  • API: POST /api/v1/ai/chat (StreamingResponse), POST /api/v1/ai/strategy, POST /api/v1/ai/text-to-sql
  • RAG: 질문 의도 기반 라우팅 후 ChromaDB 하이브리드 검색(semantic+BM25) + rerank
  • LLM: OpenAI(gpt-4o, gpt-4o-mini) 응답 생성

• RAG 파이프라인:

  사용자 질문
    → 의도 판별(RAG 필요 여부)
    → [RAG ON] ChromaDB 검색(semantic/BM25 + rerank) + 메타데이터 필터
    → 컨텍스트 + 대화 히스토리 + 시스템 프롬프트
    → OpenAI 스트리밍 응답
  

• 기술 요소: ChromaDB, Sentence-Transformers(BAAI/bge-m3), CrossEncoder reranker, FastAPI StreamingResponse, 프론트 ReadableStream 처리.

---

4.6 인증 시스템 (Authentication)

• 역할(Role): 사용자 회원가입, 로그인, JWT 세션 관리.

• 의도(Purpose):

  • 접근 제어: 인증된 사용자만 대시보드 기능에 접근 가능.
  • 개인화: 사용자별 프로필 설정 및 기업 컨텍스트 연동.

• 인증 흐름:

  Signup → pbkdf2_sha256 해시 저장 → User 저장(MySQL)
  Login  → 비밀번호 검증 → JWT 발급 (HS256, 기본 60분)
         → localStorage 저장 → WelcomePage 이동 (3초 자동)
  Refresh → token 존재 시 dashboard 자동 복원
  

• 기술 요소: passlib(pbkdf2_sha256), JWT(python-jose), SQLAlchemy (User 모델).

---

4.7 프로필 설정 (Profile Settings)

• 역할(Role): 사용자 닉네임, 분류, 자기소개, 프로필 이미지 등 개인 정보 관리.
• 의도(Purpose):
  • ESG 아이덴티티: 멸종위기종(포유류/조류/양서류 등) 테마를 적용하여 환경적 메시지 전달.
  • 동적 퀴즈 뱃지(QuizBadge): 닉네임에서 동물 키워드(눈표범/물방개/판다/호랑이/독수리) 감지 시 해당 멸종위기 동물 퀴즈 표시, 미감지 시 탄소중립 기본 퀴즈 표시.
  • 회원 탈퇴: 확인 모달(비밀번호 재확인)과 함께 계정 삭제 지원.
• 프로필 필드: 닉네임, 멸종위기종 분류(드롭다운), 소속 기업명(API 목록 드롭다운 선택), 자기소개(500자), 프로필 이미지 URL.

---

🛠️ 5. 기술 스택 및 모듈 연동 (Tech Stack & Implementation)

5.1 Frontend

5.2 Backend & Data

5.3 AI & NLP

---

📂 6. 프로젝트 구조 (Project Structure)

ESG_Dashboard/
├── requirements.txt                  # 공통 Python 의존성 (backend/PDF 공용)
├── README.md
├── 페이지_라우팅_구조.md
├── start_all.sh                      # 로컬 동시 실행 스크립트
├── backend/
│   ├── requirements.txt              # 백엔드 전용 의존성
│   ├── main.py                       # 통합 엔트리포인트 (RAG 보조 엔드포인트 포함)
│   └── app/
│       ├── main.py                   # 코어 API 서버 엔트리포인트
│       ├── config.py                 # .env 기반 설정 로더
│       ├── database.py
│       ├── models.py                 # User, DashboardEmission
│       ├── schemas.py
│       ├── init_db.py
│       ├── routers/                  # auth/profile/dashboard/simulator/ai
│       ├── services/                 # ai_service, market_data 등
│       └── static/profile/           # 업로드된 프로필 이미지
├── frontend/
│   ├── package.json
│   ├── package-lock.json
│   ├── vite.config.ts
│   └── src/
│       ├── App.tsx                   # react-router-dom 경로 라우팅 + 탭 상태 관리
│       ├── config.ts                 # API base URL 구성
│       ├── services/                 # auth/profile/market/ai API 호출
│       ├── features/                 # 탭/페이지별 UI
│       └── types/
├── PDF_Extraction/
│   ├── requirements.txt              # PDF/RAG 파이프라인 의존성
│   ├── src/                          # 추출/적재/벡터DB 구축 스크립트
│   ├── docs/
│   └── vector_db/                    # (선택) 로컬 Chroma Persistent 저장 경로
└── evaluation/
    └── evaluate_models.py

[!NOTE] PDF_Extraction/vector_db/는 로컬 Persistent Chroma를 쓸 때의 기본 경로입니다. 원격 Chroma 서버(CHROMA_HOST, CHROMA_PORT)를 쓰면 이 폴더가 없어도 챗봇이 동작합니다.

---

🗺️ 7. 페이지 라우팅 구조 (Page Routing)

react-router-dom 기반 경로 라우팅 + activeTab 상태 동기화 상세 설계서: 페이지_라우팅_구조.md

7.1 페이지 경로

7.2 인증 가드 동작

• 토큰이 없으면 보호 경로 접근 시 /login으로 리다이렉트
• 토큰이 있으면 /, /login, /signup 접근 시 /dashboard로 리다이렉트
• 알 수 없는 경로는 토큰 여부에 따라 /dashboard 또는 /login으로 정리

7.3 탭 상태 동기화

• URL 경로(/dashboard/*)에서 activeTab을 역매핑해 헤더 탭 UI와 동기화
• 탭 클릭 시 navigate('/dashboard/...') 호출로 브라우저 히스토리와 자동 연동
• 브라우저 뒤로가기/앞으로가기는 router history로 처리

---

⚙️ 8. 설치 및 설정 (Installation & Setup)

8.0 사전 요구사항 (Prerequisites)

8.1 백엔드 가동

# 프로젝트 루트 기준
python3.11 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
pip install -r backend/requirements.txt

# DB 초기화 (최초 1회)
cd backend/app
python init_db.py
cd ../..

# 서버 실행 (권장: app 엔트리포인트)
cd backend
uvicorn app.main:app --reload --port 8000

backend/main.py는 PDF 검색/통계 보조 엔드포인트까지 함께 쓰는 통합 모드입니다.

8.2 프론트엔드 가동

cd frontend
npm install
npm run dev

브라우저에서 http://localhost:5173 접속

8.3 AI/RAG 설정

옵션 A: 원격 Chroma 서버 사용 (운영 권장)

CHROMA_HOST=your-chroma-host
CHROMA_PORT=8000
RAG_EMBEDDING_MODEL=BAAI/bge-m3

• 이 경우 로컬 PDF_Extraction/vector_db 폴더가 없어도 됩니다.
• 챗봇은 원격 컬렉션(esg_chunks, esg_pages 또는 esg_documents)을 조회합니다.

옵션 B: 로컬 Persistent Chroma 사용 (개발용)

pip install -r PDF_Extraction/requirements.txt
cd PDF_Extraction
python src/build_vector_db.py

• 기본 로컬 경로는 PDF_Extraction/vector_db입니다.
• 벡터DB가 없으면 챗봇 API는 실행되지만 RAG 근거 검색 품질이 떨어질 수 있습니다.

임베딩 모델 safetensors 변환/배포 (권장)

BAAI/bge-m3 원본은 pytorch_model.bin 기반이므로, 팀 공용 환경에서는 safetensors 변환본을 사내 경로/아티팩트로 배포해 쓰는 것을 권장합니다.

cd PDF_Extraction
python src/convert_embedding_to_safetensors.py \
  --source-model BAAI/bge-m3 \
  --output-dir models/bge-m3-safetensors

배포 후 .env에 동일 경로를 설정합니다.

RAG_EMBEDDING_MODEL=/absolute/path/to/models/bge-m3-safetensors

8.4 환경 변수 설정

프로젝트 루트 .env 예시:

# --- Database (MySQL) ---
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=esg

# --- Frontend API URL ---
VITE_API_BASE_URL=http://127.0.0.1:8000

# --- JWT ---
JWT_SECRET_KEY=your_jwt_secret_key_here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60

# --- RAG/LLM ---
VECTOR_DB_PATH=/absolute/path/to/vector_db   # 선택
CHROMA_HOST=                                  # 원격 사용 시 설정
CHROMA_PORT=8000
RAG_EMBEDDING_MODEL=BAAI/bge-m3

# --- Market Data ---
Alpha_Vantage_API=your_alpha_vantage_key
USE_MOCK_DATA=true

# --- Optional ---
OPENAI_API_KEY=sk-...
HF_TOKEN=hf_...

---

📊 9. API 명세 (API Specification)

FastAPI Swagger UI: http://127.0.0.1:8000/docs

9.1 인증 API (/auth)

9.2 프로필 API (/profile)

9.3 대시보드 API (/api/v1/dashboard)

9.4 시뮬레이터 API (/api/v1/sim)

9.5 AI API (/api/v1/ai)

9.6 통합 엔트리포인트 전용 API (backend/main.py)

---

🤖 10. AI 모델 평가 (AI Model Evaluation)

플랫폼의 신뢰성을 위해 탑재된 모델들을 정기적으로 자동 평가합니다.

• 실행 방법: python evaluation/evaluate_models.py
• 평가 항목:
  • RAG 답변의 정답지(Answer Key) 대비 일치율
  • Monte Carlo 수렴 안정성 (10,000회)
  • OLS 회귀 계수 유의성 및 잔차 분석
  • 추론 시간 및 메모리 효율성

---

📌 DB 스키마 주요 테이블

users

dashboard_emissions

---

📅 Last Updated: 2026-02-24 📄 License: Educational & Research Purpose Only