Trady

중소 수출입 실무를 돕는 AI 도우미 웹앱입니다.

배포 URL: https://trady-bice.vercel.app

기술 스택

• 프론트엔드: Vanilla JS, HTML, CSS (프레임워크/외부 라이브러리 없음, SPA 방식 탭 전환)
• 백엔드: Vercel Serverless Functions (Node.js)
• 배포: Vercel
• 외부 API
  • Frankfurter API — 실시간 환율 조회 (키 불필요, 프론트엔드에서 직접 호출)
  • OpenRouter — AI 기반 품목 분류 / 인코텀즈 추천 / 서류 체크리스트 / FTA 진단 (서버리스 함수 경유)
  • Google News RSS — 실시간 무역 뉴스 (키 불필요, CORS 우회를 위해 서버리스 함수에서 대신 조회)

주요 기능

• 홈: 실시간 환율 위젯(KRW 기준 USD/EUR/JPY/SGD/CNY), 클릭하면 해당 탭으로 이동하는 기능 소개 카드 3개, 국가·카테고리 필터가 있는 실시간 무역 뉴스, 앱 소개 및 면책 안내
• 품목 분류: AI 챗봇에게 제품을 설명하면 예상 HS코드 후보와 관세율 범위를 안내받는 기능. 답변에 언급된 관세율은 버튼 클릭으로 바로 아래 관세·부가세 개산 계산기에 채워 넣을 수 있으며, 계산기는 챗봇 없이 값을 직접 입력해도 실시간(버튼 없이)으로 과세가격/관세/부가세/총 세액을 단계별로 보여줌 (클라이언트 계산, API 호출 없음)
• 인코텀즈 도우미: EXW/FCA/FOB/CIF/CPT/DDP 6종 조건을 표(모바일은 카드)로 비교하고 조건별 상세 설명을 아코디언으로 확인, 하단 버튼으로 화물종류·운송수단 등을 입력하면 AI가 상황에 맞는 조건을 추천
• 서류 체크리스트: 거래유형/국가/품목 카테고리/결제방식을 입력하면 AI가 맞춤 필요 서류 목록을 생성하고, 체크박스 진행상황을 localStorage에 저장해 재방문 시 복원
• FTA 진단: 거래 대상국·원산지 비율·원산지증명서 발급 경험을 문답형으로 입력하면 AI가 FTA 활용 가능성과 다음 단계를 안내
• 사이드 메뉴: Trady 로고 옆 햄버거(☰) 아이콘으로 여는 About / Contact(이메일 2개 + 비즈니스 제안) / 도움말 / 광고 문의
• 무역 용어 미니사전: 완전 정적 데이터(glossary.js, API 호출 없음)로 L/C·B/L·FOB·관세 등 20개 용어를 앱 전체 텍스트(챗봇 답변, 체크리스트, 비교표 등 포함)에서 자동 인식해 하이라이트 처리. 호버 시 즉시 짧은 설명이 뜨고 클릭하면 전체 설명 팝오버가 열리며, 홈 화면의 "무역 용어 미니사전 전체보기" 버튼으로 검색 가능한 전체 목록도 확인 가능

AI 네 기능 모두 무료 모델 특성상 발생할 수 있는 요청 제한(rate limit), 타임아웃, 서버 오류를 사용자 친화적인 메시지로 안내하며, 마크다운 기호 없이 자연스러운 줄글로 답변합니다. 동일한 시각적 톤(에러: 빨강 / 요청 제한: 주황)으로 통일되어 있습니다.

참고: 실시간 환율 위젯은 RUB(러시아 루블)를 지원하지 않습니다. Frankfurter API가 참조하는 ECB(유럽중앙은행) 기준환율에서 2022년 이후 RUB가 제외되었기 때문입니다. 화면에도 이 사실을 안내하는 문구가 표시됩니다.

로컬 개발 환경 설정

1. 이 저장소를 클론합니다.

   git clone <repository-url>
   cd trady
   

2. .env.local.example 파일을 복사해 .env.local 파일을 만들고, 값을 채웁니다.

   cp .env.local.example .env.local
   

   OPENROUTER_API_KEY=your_key_here
   

   OPENROUTER_API_KEY는 openrouter.ai에서 회원가입 후 Keys 메뉴에서 발급받습니다. (품목 분류/체크리스트/FTA 진단에 필수)

3. Vercel CLI로 로컬 서버를 실행합니다. (최초 1회 npm i -g vercel 또는 npx vercel로 설치)

   vercel dev
   

   정적 파일만 확인할 경우 index.html을 브라우저로 직접 열어도 되지만, /api/classify, /api/incoterms, /api/checklist, /api/fta, /api/news 기능은 Vercel 서버리스 함수 환경(vercel dev 또는 실제 배포)에서만 동작합니다.

배포 (Vercel)

1. Vercel CLI로 로그인하고 프로젝트를 연결합니다.

   vercel login
   vercel link
   

2. 환경변수를 등록합니다.

   vercel env add OPENROUTER_API_KEY
   

   또는 Vercel 대시보드 > 프로젝트 선택 > Settings > Environment Variables에서 직접 등록해도 됩니다. 등록하지 않으면 품목 분류/인코텀즈 추천/체크리스트/FTA 진단 호출 시 서버 설정 오류가 반환됩니다.

3. 배포합니다.

   vercel --prod
   

프로젝트 구조

trady/
├── index.html
├── style.css
├── script.js
├── glossary.js         # 무역 용어 미니사전 정적 데이터 (API 호출 없음)
├── api/
│   ├── classify.js    # OpenRouter 연동 HS코드 분류 서버리스 함수
│   ├── incoterms.js    # OpenRouter 연동 인코텀즈 추천 서버리스 함수
│   ├── checklist.js   # OpenRouter 연동 서류 체크리스트 생성 서버리스 함수
│   ├── fta.js          # OpenRouter 연동 FTA 활용 가능성 진단 서버리스 함수
│   └── news.js         # Google News RSS 프록시 서버리스 함수
├── package.json
└── vercel.json