Vaani Pay Assistant

보안이 적용된 실시간 다중 사용자, 이중 언어(영어 + 힌디어) 결제 지원 챗봇입니다. 사용자는 자신의 계정으로 등록/로그인한 후 자신의 결제, 주문, 환불, 거래, 사기 위험, 통계에 대해 질문할 수 있습니다. MCP 도구 계층에서 엄격한 사용자별 데이터 격리가 적용되며, 실제 SQLite 데이터베이스와 에이전트가 수행 중인 작업을 보여주는 실시간 WebSocket 상태 스트림을 갖추고 있습니다.

이 프로젝트는 정적 데모 해커톤 빌드(하드코딩된 사용자, 고정 토큰, 영어 전용)로 시작했으며, 이미 작동하던 부분은 변경하지 않은 채 데이터베이스 기반의 다중 사용자, 보안, 이중 언어 플랫폼으로 업그레이드되었습니다. WebSocket 프로토콜, MCP 도구 아키텍처, 핵심 에이전트 로직은 이전과 동일한 형태입니다. 단지 그 아래의 데이터 소스와 인증 모델만 변경되었습니다.

아키텍처

Browser (chat UI + login/signup/profile)
      │ REST (/auth, /users/me, /transactions)      │ WebSocket (/ws)
      ▼                                              ▼
FastAPI — auth endpoints, profile endpoints    FastAPI — WebSocket handler
      │                                              │
      ▼                                              ▼
app/auth.py  (register / login / sessions)     AI Agent (app/agent.py)
      │                                           NLU (Grok API) → intent + entities
      │                                           Tool selection → MCP tool
      ▼                                              │
app/db.py — SQLite                                   │ MCP (stdio transport)
  users, sessions, chat_history,                      ▼
  payments, orders, refunds, transactions        MCP Server (mcp_server/server.py)
      ▲                                           get_payment_status │ get_order_details
      │                                           get_refund_status │ get_customer_details
      └───────────── same DB, same ownership ──── get_transaction_history │ check_fraud_risk
                      checks on every query        get_payment_statistics
                                                        │
                                                        ▼
                                              mcp_server/data_layer.py
                                              — ownership check on every lookup,
                                                now backed by SQLite instead of JSON

Related MCP server: nexi-xpay-mcp-server

1. 계정 및 데이터 개인정보 보호

• 실제 계정. POST /auth/register는 안전하게 해시된 비밀번호(PBKDF2-HMAC-SHA256, 비밀번호별 무작위 솔트, 260,000회 반복 — app/security.py 참조)와 함께 SQLite에 사용자 행을 생성합니다. 평문 비밀번호는 어디에도 저장되거나 기록되지 않습니다.

• 실제 로그인 세션. POST /auth/login은 자격 증명을 확인하고 sessions 테이블에 만료 시간(.env의 SESSION_TTL_HOURS, 기본 24시간)과 함께 저장되는 불투명하고 추측할 수 없는 세션 토큰(app/security.py의 generate_token(), 256비트 엔트로피)을 발급합니다. 만료되었거나 알 수 없는 토큰은 확인되는 모든 곳에서 거부됩니다.

• 특정 리소스를 조회하는 모든 MCP 도구(get_payment_status, get_order_details, get_refund_status, check_fraud_risk)는 requesting_user_id 파라미터를 요구하며, mcp_server/data_layer.py에서 아무것도 반환하기 전에 해당 리소스가 실제로 그 사용자의 것인지 확인합니다(이제 매개변수화된 SQL WHERE ... AND user_id = ? 절을 통해).

• 리소스가 다른 사람의 것이거나 전혀 존재하지 않는 경우, 두 상황 모두에서 동일한 일반 응답이 반환됩니다: "Access denied. You are not authorized to access this information." '찾을 수 없음'과 '다른 사람의 데이터'에 대해 서로 다른 메시지를 반환하면 사용자가 받는 오류를 관찰하여 유효한 ID를 열거할 수 있게 됩니다 — 이는 해당 사이드 채널을 차단합니다.

• requesting_user_id는 항상 호출자의 인증된 신원입니다(WebSocket 인증 시점/REST 요청 시점에 한 번 확인됨 — app/auth.py 참조). 채팅 메시지, URL 파라미터, 요청 본문에서 파싱된 값이 절대 아닙니다. app/nlu.py의 추출 스키마에는 user_id 필드가 전혀 없으므로 메시지(적대적인 메시지라도)가 다른 신원을 도구 호출에 몰래 넣을 방법이 없습니다.

• get_customer_details, get_transaction_history, get_payment_statistics는 리소스 ID를 전혀 받지 않습니다 — 항상 호출자 자신의 데이터를 반환하므로 이 세 도구에는 ID 조작 공격 표면이 전혀 없습니다.

• 계정 삭제(DELETE /users/me)는 확인을 위해 현재 비밀번호를 다시 입력해야 하며, 그 후 사용자 행을 삭제합니다 — ON DELETE CASCADE 외래 키가 해당 사용자의 모든 세션, 채팅 기록, 결제, 주문, 환불, 거래를 함께 제거합니다.

데이터 격리를 직접 확인하세요:

python3 test_offline.py

이 테스트는 두 명의 서로 다른 데모 사용자로 실제 도구 호출(실제 MCP 서버에 대해 실행되며 실제 SQLite 데이터베이스를 읽음)을 수행하여 교차 사용자 액세스 시도가 거부되는지, 각 사용자의 거래 내역에 자신의 데이터만 포함되는지, 이중 언어 응답이 올바르게 렌더링되는지를 검증합니다.

2. 등록, 로그인 및 계정 관리

• POST /auth/register — 이름, 이메일, 비밀번호, 선택적 전화번호, 언어 기본 설정. 비밀번호는 8자 이상이어야 하며 문자와 숫자가 혼합되어야 합니다(app/security.py).

• POST /auth/login — 세션 토큰 + 사용자 프로필을 반환합니다.

• POST /auth/logout — 현재 세션 토큰을 서버 측에서 취소합니다.

• GET /users/me / PUT /users/me — 프로필 보기/업데이트(이름, 전화번호).

• POST /users/me/change-password — 현재 비밀번호가 필요합니다. 비밀번호를 변경하면 모든 기존 세션이 무효화되어(모든 곳에서 다시 로그인해야 함) 유출된 이전 토큰이 더 이상 작동하지 않습니다.

• GET /users/me/preferences / PUT /users/me/preferences — 언어 기본 설정(en/hi)을 읽기/업데이트합니다. 데이터베이스에 저장되므로 로그아웃/로그인 후에도 유지됩니다.

• DELETE /users/me — 영구 계정 삭제(비밀번호 + 명시적 confirm: true 필요).

이 모든 기능은 채팅 UI 자체의 헤더에 있는 ⚙️ 버튼을 통해서도 사용할 수 있습니다(프로필 보기/편집, 언어 전환, 비밀번호 변경, 로그아웃, 계정 삭제).

3. 채팅 UI

static/index.html — 단일 페이지 앱:

• 채팅이 가능하기 전에 로그인/회원가입 탭이 표시됩니다.

• 프로필 및 설정 패널(이름/전화번호 편집, 비밀번호 변경, 언어 전환, 로그아웃, 확인 단계가 있는 계정 삭제).

• 입력란 위의 접을 수 있는 제안 메뉴로, UI의 나머지 부분과 동일한 번역 문자열 사전에서 렌더링됩니다.

• 채팅 말풍선, 실시간 상태 표시줄, 헤더 상태 표시기 — 원래 디자인에서 변경되지 않았습니다.

4. 실시간 통신

채팅은 여전히 단일 WebSocket(/ws)을 통해 이루어집니다 — 프로토콜 형태는 변경되지 않았으며, 인증 토큰만 정적 값 대신 실제 DB 기반 세션 토큰이 되었습니다:

{"type": "auth", "token": "<session token from /auth/login>"}
      ↓
{"type": "auth_success", "user_id": "...", "name": "...", "language": "en"}

모든 채팅 메시지에 대해 서버는 이 순서대로 상태 이벤트를 스트리밍한 후 최종(현지화된) 답변을 제공합니다:

🔍 Understanding your request...
🔧 Checking payment information...
✓ Payment information retrieved
🤖 Generating response...
<final answer, in the user's selected language>

모든 채팅 턴(사용자와 어시스턴트 메시지 모두)도 인증된 사용자 범위로 chat_history 테이블(app/main.py의 _persist_chat_turn)에 저장됩니다.

5. MCP 기반 아키텍처

mcp_server/server.py는 mcp_server/tools/ 아래의 도메인 모듈로 분할된 정확히 이 7개의 도구를 노출합니다:

모든 도구는 정적 JSON 대신 SQLite 데이터베이스(mcp_server/data_layer.py → app/db.py)를 기반으로 합니다. 도구 시그니처, 에이전트, 프론트엔드는 원래 디자인에서 변경되지 않았습니다 — data_layer.py 아래의 데이터 소스만 변경되었으며, 이는 원래 아키텍처가 허용하도록 설계된 방식 그대로입니다.

6. 이중 언어 지원(영어 + 힌디어)

• UI 문자열: app/i18n.py의 UI_STRINGS 사전으로, GET /i18n/{lang}을 통해 제공됩니다. 프론트엔드는 로드 시와 언어 변경 때마다 이를 가져와서 data-i18n/data-i18n-placeholder 속성을 통해 적용합니다 — HTML/JS에 번역 문자열이 하드코딩되어 있지 않습니다.

• AI 어시스턴트 응답: app/i18n.py의 AGENT_STRINGS(인사말 같은 고정 메시지)와 REPLY_TEMPLATES(결제 상태 같은 보간 메시지). app/agent.py는 모든 응답을 이를 통해 렌더링합니다 — 에이전트에는 영어 텍스트가 직접 하드코딩되어 있지 않습니다.

• NLU: app/nlu.py의 프롬프트는 Grok 모델에게 힌디어/영어/혼합 입력을 처리하고 의도/엔티티 추출을 위해 내부적으로 항상 영어로 번역하도록 명시적으로 요청합니다. 따라서 어시스턴트는 어떤 언어의 질문이든 이해하고 사용자가 선호하는 언어로 응답합니다.

• 지속성: 언어 기본 설정은 데이터베이스의 users.language에 저장됩니다(가입 시 설정되며, PUT /users/me/preferences를 통해 언제든지 변경 가능). 따라서 로그아웃/로그인 후에도 유지됩니다.

• 동적 전환: 설정에서 언어를 변경하면 UI가 즉시 업데이트되고 WebSocket이 다시 연결되어 바로 다음 채팅 응답부터 새 언어로 돌아옵니다 — 페이지 새로고침이 필요 없습니다.

7. 보안 요구 사항

8. 데이터베이스 스키마

users            id, name, email, phone, password_hash, language, created_at, updated_at, last_login
sessions         token, user_id, created_at, expires_at
chat_history     id, user_id, conversation_id, role, message, timestamp
payments         payment_id, user_id, status, amount, method, failure_reason, date
orders           order_id, user_id, status, total, items (JSON), date
refunds          refund_id, user_id, payment_id, amount, status, date
transactions     txn_id, user_id, type, amount, status, date

-- Wallet: the real money-movement system (see section 9 below)
payment_accounts     id, user_id, payment_id, account_number, ifsc, balance, currency, status, created_at
wallet_transactions  id, transaction_id, sender_account_id, receiver_account_id, amount, transaction_type,
                     status, description, sender_name, receiver_name, recipient_account_number,
                     recipient_ifsc, failure_reason, created_at, updated_at
beneficiaries        id, user_id, recipient_name, account_number, ifsc, created_at

외래 키와 인덱스를 포함한 전체 DDL은 app/db.py의 SCHEMA를 참조하세요.

9. 지갑: 결제 계정, 입금 및 송금

모든 등록 사용자는 단순한 거래 내역 조회기가 아니라 실제로 사용할 수 있는 지갑을 받습니다. 이것은 데이터베이스/인증 업그레이드 위에 추가된 가장 큰 기능이며, REST API와 AI/MCP 도구가 모두 호출하는 별도 모듈(app/wallet.py)로 구축되어 있습니다. 따라서 자금 이동 규칙을 적용하는 곳은 정확히 한 곳입니다.

계정 자동 생성. POST /auth/register는 사용자 행과 payment_accounts 행을 동일한 데이터베이스 트랜잭션에서 생성합니다(app/auth.py의 register()가 app/wallet.py의 insert_account_row()를 호출). 사용자가 지갑 없이 존재할 수 없으며, 지갑이 별도의 독립적으로 실패할 수 있는 단계로 생성되지 않습니다. 각 계정에는 다음이 부여됩니다:

• 고유한 결제 ID(PAY..., 내부 식별자),

• 고유한 12자리 계좌번호,

• 고정 IFSC(VPAY0000001 — Vaani Pay는 단일 지점 가상 지갑이므로 실제 네오뱅크의 가상 계좌가 흔히 그렇듯 모든 계정이 하나의 IFSC를 공유합니다),

• 시작 잔액 ₹0.

등록 응답에는 message: "Your payment account has been successfully created." 확인 메시지와 새 계정 세부 정보가 포함되어 사용자에게 즉시 표시됩니다(API 응답과 가입 화면의 확인 메시지 모두에서).

입금. POST /wallet/add-money(또는 지갑 화면의 "Add Money" 버튼, 또는 AI 어시스턴트에게 "내 계정에 ₹5,000 추가해 줄래"라고 요청) — 금액을 검증한 후(₹0 초과, 거래당 ₹2,00,000 이하 — app/wallet.py의 MAX_ADD_MONEY) 잔액을 원자적으로 업데이트하고 wallet_transactions에 CREDIT 행을 추가합니다. 해커톤 빌드에는 실제 결제 게이트웨이가 연결되어 있지 않습니다 — 이것은 명시적으로 시뮬레이션된 충전이며, 과제의 "안전한 시뮬레이션 자금 흐름" 요구사항에 부합합니다.

송금 — 항상 2단계 확인. REST API도 AI 어시스턴트도 한 번의 호출로 자금을 이동하지 않습니다:

1. POST /wallet/transfers(app/wallet.py의 initiate_transfer)는 수취인과 송신자 잔액을 검증하고 PENDING 상태의 wallet_transactions 행을 생성합니다 — 아직 잔액은 변경되지 않습니다. 확인 미리보기(수취인, 마스킹된 계좌번호, IFSC, 금액, 수수료, 총 출금액)를 반환하며, 이것이 "Confirm Transfer" 화면을 렌더링하는 데이터입니다.

2. POST /wallet/transfers/{id}/confirm(confirm_transfer)는 실제로 자금을 이동하는 유일한 호출입니다. 확인 시점에(시작 시점에만이 아니라, 그 사이에 상황이 바뀌었을 수 있으므로 — 예: 연속으로 두 건의 송금이 시작된 경우) 송신자 잔액과 계정 상태를 다시 검증한 다음, 프로세스 전체 잠금으로 보호되는 하나의 원자적 SQLite 트랜잭션 안에서 송신자를 차감하고, 수취인이 실제 Vaani Pay 계정이면 수취인에게 입금합니다. 중간에 어떤 단계라도 실패하면 전체가 롤백됩니다 — 송금이 차감만 되고 입금은 되지 않는 상태로 끝날 수 없습니다.

3. POST /wallet/transfers/{id}/cancel은 아직 PENDING인 송금을 잔액에 아무런 영향을 주지 않고 취소합니다.

우리 시스템에 없는 계좌번호로 송금해도 성공합니다(시뮬레이션된 외부 송금으로 — 송신자는 차감되지만 입금할 Vaani Pay 계정이 없을 뿐입니다). 이는 과제의 "수취인이 시뮬레이션 시스템에 존재하면 수취인 잔액에 입금" 요구사항에 부합합니다.

수취인 검증. POST /wallet/validate-recipient(validate_recipient)는 다음을 확인합니다: 계좌번호 형식(9~18자리), IFSC 형식(^[A-Z]{4}0[A-Z0-9]{6}$), 내부 계정인 경우 IFSC가 계좌번호와 일치하는지, 그리고 가장 중요하게는 송신자가 자신의 계좌번호로 송금하지 않는지. 수취인 이름만 주어진 경우(계좌번호 없이) 호출자의 저장된 수취인 목록에서 이름을 찾아 정확히 하나가 일치하면 자동으로 결정합니다.

저장된 수취인. 송금 성공 후 UI는 "이 수취인을 저장할까요?"를 제안합니다 — POST /beneficiaries는 인증된 사용자에 한해서만 저장합니다(전역/공유가 아님). 따라서 다음번에 사용자(또는 AI 어시스턴트가 "라훌에게 ₹2,000 보내줘"라고 요청받았을 때)가 이름만으로 송금을 결정할 수 있습니다.

거래 내역 및 필터. GET /wallet/transactions?filter=...(all / add_money / sent / received / failed / pending) — 모두 wallet_transactions에서 실시간으로 계산되며 하드코딩되지 않습니다. 지갑 화면의 History 탭과 AI의 "내 지갑 거래 보여줘" / "이번 달에 얼마나 썼지?"는 정확히 동일한 함수(app/wallet.py의 get_wallet_transactions / get_spending_summary)를 읽습니다.

잔액은 항상 파생되며 직접 설정되지 않습니다. 코드베이스 어디에도 의도적으로 set_balance() 함수가 없습니다 — 잔액이 변하는 유일한 방법은 add_money() 또는 confirm_transfer()의 부수 효과를 통해서이며, 두 함수 모두 동일한 원자적 단계에서 불변의 wallet_transactions 행도 추가합니다. 프론트엔드는 GET /wallet/account가 반환하는 것만 표시하며, 그 값을 변경할 수 없습니다.

지갑 보안 세부 사항

10. 이중 언어 결제 흐름

지갑은 앱의 나머지 부분과 동일한 app/i18n.py 메커니즘을 사용하여 완전히 이중 언어를 지원합니다 — Add Money, Send Money(세 단계 모두), 확인 화면, 트랜잭션 상태, 잔액/송금에 관한 모든 AI 응답은 app/wallet.py, app/agent.py 또는 static/index.html의 지갑 UI 어디에도 하드코딩된 영어 없이 t()/tpl()을 통해 렌더링됩니다. 예를 들어 AI에게 "Rahul ko ₹2,000 bhejo" (힌디어/힝글리시)라고 요청하면 영어 버전과 완전히 동일한 resolve → confirm → execute 흐름을 거치며, 모든 메시지 — 확인 화면을 포함하여 — 힌디어로 렌더링됩니다.

설정

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Add your Grok API key (get one at https://console.x.ai)

데이터베이스는 첫 실행 시 자동으로 생성되며(비어 있는 경우에만 아래의 두 데모 사용자로 시드됨), 로컬 개발을 위한 별도의 마이그레이션 단계는 필요 없습니다. 미리 명시적으로 생성하려면:

python3 -m app.db

브라우저를 열기 전에 확인:

python3 diagnose_setup.py

실행

uvicorn app.main:app --reload --port 8000

**http://localhost:8000**을 엽니다. 새 계정으로 가입하거나, 시드된 데모 계정 중 하나로 로그인합니다:

그런 다음 제안 메뉴를 사용해 보거나, "check payment status pay_1001" 또는 "मेरा भुगतान pay_1001 का स्टेटस क्या है?" 같은 질문을 하거나, 설정에서 언어를 전환하거나, 한 사용자로 로그인한 후 다른 사용자의 결제/주문/환불 ID(pay_1003, ord_2002, rfnd_3002는 Priya 소유)에 대해 물어보아 접근 거부 응답을 확인해 보세요.

지갑을 사용해 보려면: 헤더의 💰 Wallet 버튼을 엽니다. 두 데모 계정 모두 잔액(Ramesh ₹8,500, Priya ₹8,000)과 기록에 이미 있는 데모 송금 하나로 시작합니다. "Add Money"를 사용해 보거나, 다른 데모 계정의 계좌 번호(해당 계정의 Wallet 화면에서 확인 가능)로 "Send Money"를 보내 보거나, AI 어시스턴트에게 직접 "what's my balance?", "add ₹5,000 to my account", "send ₹2,000 to Priya Stores"(처음에는 그녀의 계좌 번호 + IFSC를 요청하고, 송금 성공 후 그녀를 수취인으로 저장할 것을 제안합니다 — 이후에는 이름만으로 충분합니다), 또는 힌디어로 *"Mera current balance kitna hai?"*라고 물어보세요.