1호선 고장코드 (Tr_Code)

Flask + HTMX 기반의 철도 차량 고장코드 및 TCMS 신호 조회 웹 애플리케이션입니다.

📋 목차

• 주요 기능
• 시스템 아키텍처
• 설치 및 배포
• 환경 설정
• 회원 인증 시스템 ⭐ NEW!
• 서비스 관리
• 개발 환경
• API 엔드포인트
• 문제 해결

🎯 주요 기능

🔐 회원 관리 및 인증 (NEW!)

• 이메일 코드 인증 - 6자리 숫자 코드 입력 (링크 클릭 방식 대신)
• 생체인증 - WebAuthn API 활용 (지문, 얼굴 인식)
• 비밀번호 재설정 - 이메일 코드 인증 후 재설정
• humetro.busan.kr 도메인 제한 (회사 이메일만 가입 가능)
• 부서별 사용자 관리 (신평차량, 노포차량, 차량처)
• 사번 기반 사용자 식별
• 동적 부서 목록 로드 (Supabase departments 테이블)
• 부서별 권한 관리 기반 구축 (조회/수정 권한 제어 가능)
• 세션 기반 로그인 상태 유지

고장코드 조회

• 제조사별 필터링 (우진, 로템 등)
• 장치별, 차량 타입별 검색
• 실시간 검색 (HTMX 기반)
• 코드 그룹핑 옵션
• 상세 정보 모달 표시

TCMS 신호 조회

• 신호 분류별 필터링
• 제조사/차량별 검색
• 신호 상태값 확인

MMI 코드 조회

• MMI 코드 데이터베이스 검색
• 차량분류별 필터링

UI/UX

• 반응형 디자인 (모바일 최적화)
• 다크모드 지원
• PWA 지원 (오프라인 사용 가능)
• 빠른 페이지 전환 (HTMX)
• 로그인 사용자 정보 표시

🏗️ 시스템 아키텍처

외부 클라이언트 (브라우저/PWA)
    ↓ HTTPS/HTTP
NPM 리버스 프록시 (Proxmox, 선택적)
    ↓ HTTP
M1T 서버 nginx (:80)
    ↓ Unix Socket
gunicorn (Tr_Code.sock)
    ↓
Flask App (app.py)
    ↓ localhost:8000
Supabase (Docker)

기술 스택

백엔드

• Flask 3.0.3 - 웹 프레임워크
• Gunicorn 23.0.0 - WSGI 서버
• httpx - 비동기 HTTP 클라이언트

프론트엔드

• HTMX - 동적 UI
• TailwindCSS - 스타일링
• Jinja2 템플릿

데이터베이스

• Supabase (PostgreSQL)
• PostgREST API

인프라

• nginx - 리버스 프록시
• systemd - 프로세스 관리
• Ubuntu 22.04 LTS

🚀 설치 및 배포

1. 시스템 요구사항

# OS
Ubuntu 22.04 LTS 이상

# Python
Python 3.10 이상

# 필수 패키지
sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx

2. 프로젝트 설치

# 프로젝트 클론 또는 복사
cd /home/ckh08045
git clone <repository> Tr_Code
cd Tr_Code

# 가상환경 생성
python3 -m venv .

# 가상환경 활성화
source bin/activate

# 의존성 설치
pip install -r requirements.txt

3. 환경 설정

3.1 데이터베이스 스키마 생성

회원 관리 시스템을 사용하려면 먼저 데이터베이스 스키마를 생성해야 합니다:

# database_schema.sql 파일의 내용을 Supabase SQL 에디터에서 실행
# 부서, 사용자, 권한 테이블이 자동으로 생성됩니다

3.2 .env 파일 생성

# env.example 파일을 .env로 복사
cp env.example .env

# SECRET_KEY 생성
python -c "import secrets; print(secrets.token_hex(32))"

# .env 파일 편집
nano .env

.env 파일 내용:

# Supabase 설정 (localhost - 같은 서버에서 실행 중)
SUPABASE_URL=http://localhost:8000
SUPABASE_ANON_KEY=your_anon_key_here

# Flask 세션 보안 키 (반드시 변경!)
SECRET_KEY=위에서-생성한-랜덤-키-입력

# Kong Basic Auth (선택사항)
SUPABASE_BASIC_USER=
SUPABASE_BASIC_PASSWORD=

# Flask 설정
PORT=5000

🔐 회원 인증 시스템

빠른 시작

회원 관리 및 인증 시스템 설정을 위한 문서:

📖 ENV_SETUP_GUIDE.md - 환경 변수 설정 가이드
📖 AUTH_SETUP.md - 상세 인증 시스템 설정
📖 EMAIL_CODE_AUTH_GUIDE.md - 이메일 코드 인증 가이드
📖 BIOMETRIC_AUTH_GUIDE.md - 생체인증 가이드
📖 AUTHENTICATION_SUMMARY.md - 기술 문서
📖 DEPARTMENTS_API.md - 부서 API 문서

주요 기능

• ✅ 이메일 코드 인증 - 6자리 숫자 코드 입력 방식 (스팸/피싱 의심 방지)
• ✅ 생체인증 - WebAuthn/Credential Management API (지문, 얼굴 인식)
• ✅ 비밀번호 재설정 - 이메일 코드 인증 후 재설정
• ✅ humetro.busan.kr 도메인만 가입 가능
• ✅ 부서별 사용자 관리 (동적 부서 목록)
• ✅ 사번 기반 사용자 식별
• ✅ 부서별 권한 관리 (조회/수정 권한 제어 가능)

Docker 기반 Supabase 환경

⚠️ 중요: Docker 기반 Supabase는 대시보드 Authentication 설정이 제한적입니다.
이메일 도메인 검증은 애플리케이션 레벨에서만 처리됩니다.

3단계 설정

# 1. 데이터베이스 스키마 생성 (Supabase SQL 에디터)
# database_schema.sql 실행

# 2. .env 파일 설정
cp env.example .env
python -c "import secrets; print(secrets.token_hex(32))"
# 출력된 키를 .env의 SECRET_KEY에 설정

# 3. 서버 실행
python app.py

사용 방법

1. http://localhost:5000 접속 → 로그인 페이지
2. "회원가입" 클릭
3. 정보 입력 (humetro.busan.kr 이메일 사용)
4. 로그인

4. Systemd 서비스 설정

/etc/systemd/system/Tr_Code.service:

[Unit]
Description=Gunicorn instance to serve Tr_Code
After=network.target

[Service]
User=ckh08045
Group=ckh08045
WorkingDirectory=/home/ckh08045/Tr_Code
Environment="PATH=/home/ckh08045/Tr_Code/bin"
ExecStart=/home/ckh08045/Tr_Code/bin/gunicorn --workers 3 --bind unix:Tr_Code.sock -m 007 app:app

[Install]
WantedBy=multi-user.target

5. nginx 설정

/etc/nginx/sites-available/tr_code:

server {
    listen 80;
    server_name _;
    
    client_max_body_size 10M;
    
    location /static/ {
        alias /home/ckh08045/Tr_Code/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    location / {
        proxy_pass http://unix:/home/ckh08045/Tr_Code/Tr_Code.sock;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

nginx 활성화:

# 심볼릭 링크 생성
sudo ln -sf /etc/nginx/sites-available/tr_code /etc/nginx/sites-enabled/

# 기본 사이트 비활성화
sudo rm -f /etc/nginx/sites-enabled/default

# nginx 사용자를 애플리케이션 그룹에 추가 (Unix 소켓 접근 권한)
sudo usermod -a -G ckh08045 www-data

# 설정 테스트
sudo nginx -t

# nginx 재시작
sudo systemctl restart nginx

6. 서비스 시작

# systemd 설정 리로드
sudo systemctl daemon-reload

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable Tr_Code

# 서비스 시작
sudo systemctl start Tr_Code

# 상태 확인
sudo systemctl status Tr_Code

⚙️ 환경 설정

환경변수 설명

변수	설명	기본값
SUPABASE_URL	Supabase 서버 주소	http://localhost:8000
SUPABASE_ANON_KEY	Supabase Anonymous Key	-
SUPABASE_BASIC_USER	Kong Basic Auth 사용자명 (선택)	-
SUPABASE_BASIC_PASSWORD	Kong Basic Auth 비밀번호 (선택)	-
PORT	Flask 개발 서버 포트	5000

Supabase 연결

• 같은 서버: http://localhost:8000 사용 (최적 성능)
• 다른 서버: http://ip:port 형식으로 지정
• Kong 프록시: Basic Auth 정보 추가

🔧 서비스 관리

서비스 명령어

# 시작
sudo systemctl start Tr_Code

# 중지
sudo systemctl stop Tr_Code

# 재시작
sudo systemctl restart Tr_Code

# 상태 확인
sudo systemctl status Tr_Code

# 로그 확인
sudo journalctl -u Tr_Code -f

# 부팅 시 자동 시작 활성화
sudo systemctl enable Tr_Code

# 부팅 시 자동 시작 비활성화
sudo systemctl disable Tr_Code

nginx 명령어

# 설정 테스트
sudo nginx -t

# 재시작
sudo systemctl restart nginx

# 리로드 (무중단)
sudo systemctl reload nginx

# 에러 로그 확인
sudo tail -f /var/log/nginx/error.log

# 액세스 로그 확인
sudo tail -f /var/log/nginx/access.log

💻 개발 환경

로컬 개발 서버

# 가상환경 활성화
source bin/activate

# 개발 모드로 실행 (디버그 활성화)
python app.py

# 접속
# http://localhost:5000

코드 수정 후

# 서비스 재시작
sudo systemctl restart Tr_Code

📡 API 엔드포인트

헬스체크

• GET /health - 애플리케이션 상태
• GET /sb/health - Supabase 연결 상태

고장코드

• GET /sb - 메인 페이지
• GET /sb/faults/list - 고장코드 목록
• GET /sb/faults/<code> - 고장코드 상세

TCMS 신호

• GET /sb/signals/list - 신호 목록
• GET /sb/signals/<id> - 신호 상세

MMI 코드

• GET /sb?section=mmicode - MMI 코드 목록

디버그

• GET /sb/signals/test - Signals 테이블 테스트
• GET /sb/signals/debug - 상세 디버그 정보

🐛 문제 해결

서비스가 시작되지 않을 때

# 로그 확인
sudo journalctl -u Tr_Code -n 50

# 가상환경 경로 확인
ls -la /home/ckh08045/Tr_Code/bin/gunicorn

# 권한 확인
ls -la /home/ckh08045/Tr_Code/

nginx Permission Denied

# www-data 사용자가 소켓에 접근할 수 있는지 확인
sudo usermod -a -G ckh08045 www-data
sudo systemctl restart nginx

Supabase 연결 실패

# Supabase 컨테이너 상태 확인
docker ps | grep supabase

# 포트 확인
sudo netstat -tlnp | grep 8000

# .env 파일 확인
cat .env

# 연결 테스트
curl http://localhost:8000/rest/v1/

502 Bad Gateway

# gunicorn 서비스 상태 확인
sudo systemctl status Tr_Code

# 소켓 파일 확인
ls -la /home/ckh08045/Tr_Code/Tr_Code.sock

# nginx 에러 로그
sudo tail -f /var/log/nginx/error.log

📱 PWA 지원

PWA(Progressive Web App)로 변환하여 모바일 앱처럼 사용할 수 있습니다.

자세한 내용은 PWA_README.md를 참조하세요.

📄 라이선스

이 프로젝트는 내부 사용을 위한 것입니다.

🤝 기여

문제가 발생하거나 개선 사항이 있으면 이슈를 등록해주세요.

---

문의: 시스템 관리자