kcppayments_rails 0.1.0

data/test_app/README.md

@@ -0,0 +1,181 @@
+# KCP Payments Rails 테스트 애플리케이션
+
+이 애플리케이션은 `kcppayments_rails` 젬을 테스트하기 위한 Rails 8 샘플 애플리케이션입니다.
+
+## 시작하기
+
+### 1. 설치 및 설정
+
+```bash
+# 테스트 앱 디렉토리로 이동
+cd test_app
+
+# 의존성 설치 (이미 완료됨)
+bundle install
+
+# 데이터베이스 마이그레이션 (이미 완료됨)
+bin/rails db:migrate
+
+# 샘플 데이터 생성 (이미 완료됨)
+bin/rails db:seed
+```
+
+### 2. KCP 테스트 계정 설정
+
+`config/initializers/kcppayments_rails.rb` 파일에서 KCP 테스트 계정 정보를 설정하세요:
+
+```ruby
+KcppaymentsRails.configure do |config|
+  config.site_cd = "T0000"  # KCP에서 발급받은 테스트 사이트 코드
+  config.site_key = "3grptw1.zW0GSo4PQdaGvsF__"  # KCP에서 발급받은 테스트 사이트 키
+end
+```
+
+### 3. 애플리케이션 실행
+
+```bash
+bin/rails server
+```
+
+브라우저에서 http://localhost:3000 접속
+
+## 기능 테스트
+
+### 주요 페이지
+
+1. **주문 목록** (http://localhost:3000)
+   - 모든 주문 조회
+   - 새 주문 생성
+   - 주문별 결제 진행
+
+2. **새 주문 생성** (http://localhost:3000/orders/new)
+   - 상품명, 금액, 구매자 정보 입력
+   - 면세 금액 설정 가능
+
+3. **결제 페이지** 
+   - KCP 결제 모듈 통합
+   - 신용카드, 계좌이체, 가상계좌 선택 가능
+   - Stimulus 컨트롤러를 통한 결제 처리
+
+### 테스트 시나리오
+
+#### 1. 일반 결제 테스트
+- 주문 목록에서 "노트북 - MacBook Pro 14인치" 선택
+- "결제하기" 클릭
+- 결제 수단 선택 후 결제 진행
+
+#### 2. 면세 상품 테스트
+- 주문 목록에서 "도서 - Ruby on Rails 완벽 가이드" 선택
+- 전액 면세 처리 확인
+- 결제 진행
+
+#### 3. 부분 면세 테스트
+- 주문 목록에서 "식료품 세트" 선택
+- 부분 면세 금액 확인 (30,000원)
+- 결제 진행
+
+## 주요 파일 구조
+
+```
+test_app/
+├── app/
+│   ├── controllers/
+│   │   ├── orders_controller.rb      # 주문 관리
+│   │   └── payments_controller.rb    # 결제 처리
+│   ├── models/
+│   │   └── order.rb                  # 주문 모델
+│   ├── views/
+│   │   ├── orders/                   # 주문 관련 뷰
+│   │   └── payments/                  # 결제 관련 뷰
+│   └── javascript/
+│       └── controllers/
+│           └── kcp_controller.js      # KCP Stimulus 컨트롤러
+├── config/
+│   ├── routes.rb                     # 라우팅 설정
+│   └── initializers/
+│       └── kcppayments_rails.rb      # KCP 설정
+└── db/
+    └── seeds.rb                       # 샘플 데이터
+```
+
+## KCP 헬퍼 사용 예시
+
+### 뷰에서 KCP 스크립트 로드
+```erb
+<%= kcp_script_tag %>
+```
+
+### 결제 폼에 KCP 데이터 속성 추가
+```erb
+<%= form_with html: kcp_form_attrs(
+  order_id: @order.order_no,
+  amount: @order.amount,
+  buyer_name: @order.buyer_name,
+  buyer_email: @order.buyer_email,
+  product_name: @order.product_name,
+  tax_free_amount: @order.tax_free_amount
+) do |form| %>
+  <!-- 폼 내용 -->
+<% end %>
+```
+
+## 데모 모드
+
+### KCP 계정이 없는 경우
+이 테스트 앱은 **데모 모드**를 제공합니다:
+
+1. **자동 감지**: KCP JavaScript가 로드되지 않으면 자동으로 데모 모드로 전환
+2. **시뮬레이션**: 실제 결제 플로우를 시뮬레이션하여 젬 기능 테스트 가능
+3. **완전한 테스트**: 주문 생성부터 결제 완료까지 전체 플로우 확인
+
+**데모 모드에서 테스트 가능한 기능:**
+- ✅ KCP 헬퍼 메소드 (`kcp_script_tag`, `kcp_form_attrs`)
+- ✅ Stimulus 컨트롤러 통합
+- ✅ 결제 폼 데이터 속성
+- ✅ 결제 성공/실패 플로우
+- ✅ 주문 상태 업데이트
+
+## 실제 KCP 연동
+
+### 1. KCP 계정 설정
+실제 운영을 위해서는 KCP에서 발급받은 계정이 필요합니다:
+
+```ruby
+# config/initializers/kcppayments_rails.rb
+KcppaymentsRails.configure do |config|
+  config.site_cd = "실제_사이트_코드"
+  config.site_key = "실제_사이트_키"
+end
+```
+
+### 2. 도메인 등록
+- KCP 관리자 페이지에서 서비스 도메인 등록 필요
+- localhost는 테스트 계정에서만 허용되는 경우가 많음
+
+## 문제 해결
+
+### 결제 모듈이 로드되지 않는 경우
+- KCP 사이트 코드와 키가 올바른지 확인
+- 도메인이 KCP에 등록되어 있는지 확인
+- JavaScript 콘솔에서 에러 확인
+- 네트워크 탭에서 KCP 스크립트 로드 확인
+- **데모 모드로 기본 기능 테스트 가능**
+
+### 결제 후 콜백이 작동하지 않는 경우
+- `payments_controller.rb`의 `callback` 액션 확인
+- CSRF 토큰 검증이 스킵되었는지 확인
+- 서버 로그에서 파라미터 확인
+
+## 추가 개발
+
+이 테스트 앱을 기반으로 다음과 같은 기능을 추가할 수 있습니다:
+
+- 결제 취소 기능
+- 결제 내역 조회
+- 영수증 발급
+- 정기 결제
+- 부분 취소
+
+## 라이선스
+
+이 테스트 애플리케이션은 `kcppayments_rails` 젬의 일부입니다.

data/test_app/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/test_app/app/assets/stylesheets/application.css

@@ -0,0 +1,10 @@
+/*
+ * This is a manifest file that'll be compiled into application.css.
+ *
+ * With Propshaft, assets are served efficiently without preprocessing steps. You can still include
+ * application-wide styles in this file, but keep in mind that CSS precedence will follow the standard
+ * cascading order, meaning styles declared later in the document or manifest will override earlier ones,
+ * depending on specificity.
+ *
+ * Consider organizing styles into separate files for maintainability.
+ */

data/test_app/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+class ApplicationController < ActionController::Base
+  # Only allow modern browsers supporting webp images, web push, badges, import maps, CSS nesting, and CSS :has.
+  allow_browser versions: :modern
+end

data/test_app/app/controllers/orders_controller.rb

@@ -0,0 +1,31 @@
+class OrdersController < ApplicationController
+  def index
+    @orders = Order.all
+  end
+
+  def show
+    @order = Order.find(params[:id])
+  end
+
+  def new
+    @order = Order.new
+  end
+
+  def create
+    @order = Order.new(order_params)
+    @order.order_no = "ORD#{Time.now.to_i}"
+    @order.status = "pending"
+    
+    if @order.save
+      redirect_to @order, notice: '주문이 생성되었습니다.'
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def order_params
+    params.require(:order).permit(:product_name, :amount, :buyer_name, :buyer_email, :tax_free_amount)
+  end
+end

data/test_app/app/controllers/payments_controller.rb

@@ -0,0 +1,120 @@
+class PaymentsController < ApplicationController
+  skip_before_action :verify_authenticity_token, only: [:callback]
+  
+  def new
+    @order = Order.find(params[:order_id])
+  end
+
+  def create
+    @order = Order.find(params[:order_id])
+    
+    # 이 액션은 실제로는 KCP JavaScript에서 결제창을 열기 전에 호출되거나
+    # 결제 정보를 서버에서 검증할 때 사용될 수 있습니다.
+    # 지금은 결제 폼을 다시 보여줍니다.
+    
+    flash.now[:notice] = "결제를 진행해주세요."
+    render :new
+  end
+
+  def callback
+    # KCP 결제 콜백 처리
+    order = Order.find_by(order_no: params[:ordr_idxx])
+    
+    if params[:res_cd] == "0000"
+      order.update(
+        status: "paid",
+        payment_method: params[:pay_method],
+        kcp_transaction_no: params[:tno] # KCP 거래번호 저장
+      )
+      redirect_to success_payments_path(order_id: order.id)
+    else
+      order.update(status: "failed")
+      redirect_to failure_payments_path(order_id: order.id)
+    end
+  end
+
+  def success
+    begin
+      @order = if params[:order_no].present?
+        Order.find_by!(order_no: params[:order_no])
+      elsif params[:order_id].present?
+        Order.find(params[:order_id])
+      else
+        Rails.logger.error "PaymentsController#success called without order_id or order_no parameters"
+        redirect_to orders_path, alert: "주문 정보를 찾을 수 없습니다." and return
+      end
+      
+      # 데모 모드인 경우 주문을 결제 완료로 업데이트
+      if params[:demo] == 'true'
+        # 데모용 KCP 거래번호 생성 (14자리 숫자 형식: YYYYMMDDHHMMSS)
+        demo_tno = Time.current.strftime('%Y%m%d%H%M%S')
+        
+        @order.update(
+          status: "paid",
+          payment_method: "데모 결제 (#{get_payment_method_name(@order)})",
+          kcp_transaction_no: demo_tno
+        )
+        @demo_mode = true
+      end
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.error "Order not found with params: #{params.inspect}"
+      redirect_to orders_path, alert: "주문을 찾을 수 없습니다." and return
+    rescue => e
+      Rails.logger.error "Unexpected error in success action: #{e.message}"
+      Rails.logger.error e.backtrace.join("\n")
+      redirect_to orders_path, alert: "처리 중 오류가 발생했습니다." and return
+    end
+  end
+
+  def failure
+    begin
+      @order = if params[:order_no].present?
+        Order.find_by!(order_no: params[:order_no])
+      elsif params[:order_id].present?
+        Order.find(params[:order_id])
+      else
+        Rails.logger.error "PaymentsController#failure called without order_id or order_no parameters"
+        redirect_to orders_path, alert: "주문 정보를 찾을 수 없습니다." and return
+      end
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.error "Order not found with params: #{params.inspect}"
+      redirect_to orders_path, alert: "주문을 찾을 수 없습니다." and return
+    rescue => e
+      Rails.logger.error "Unexpected error in failure action: #{e.message}"
+      redirect_to orders_path, alert: "처리 중 오류가 발생했습니다." and return
+    end
+  end
+
+  def receipt
+    Rails.logger.debug "Receipt action called with params: #{params.inspect}"
+    
+    # 더 안전한 방식으로 주문 조회
+    @order = Order.find_by(id: params[:id])
+    Rails.logger.debug "Found order: #{@order.inspect}"
+    
+    # 주문이 존재하지 않거나 결제가 완료되지 않은 경우
+    if @order.nil?
+      Rails.logger.debug "Order not found, redirecting"
+      redirect_to orders_path, alert: "주문을 찾을 수 없습니다." and return
+    elsif @order.status != "paid"
+      Rails.logger.debug "Order status is not paid: #{@order.status}"
+      redirect_to orders_path, alert: "결제가 완료된 주문만 영수증을 출력할 수 있습니다." and return
+    else
+      Rails.logger.debug "Rendering receipt for order: #{@order.id}"
+      # 영수증 출력용 레이아웃 없이 렌더링
+      render layout: false
+    end
+  rescue => e
+    Rails.logger.error "Unexpected error in receipt action: #{e.message}"
+    Rails.logger.error e.backtrace.join("\n")
+    @order = nil  # 확실히 nil로 설정
+    redirect_to orders_path, alert: "오류가 발생했습니다." and return
+  end
+  
+  private
+  
+  def get_payment_method_name(order)
+    # 임시로 신용카드로 설정 (실제로는 선택된 결제 수단 기반)
+    "신용카드"
+  end
+end

data/test_app/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test_app/app/helpers/orders_helper.rb

@@ -0,0 +1,2 @@
+module OrdersHelper
+end

data/test_app/app/helpers/payments_helper.rb

@@ -0,0 +1,2 @@
+module PaymentsHelper
+end

data/test_app/app/javascript/application.js

@@ -0,0 +1,3 @@
+// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
+import "@hotwired/turbo-rails"
+import "controllers"

data/test_app/app/javascript/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
+
+export { application }

data/test_app/app/javascript/controllers/hello_controller.js

@@ -0,0 +1,7 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    this.element.textContent = "Hello World!"
+  }
+}

data/test_app/app/javascript/controllers/index.js

@@ -0,0 +1,4 @@
+// Import and register all your controllers from the importmap via controllers/**/*_controller
+import { application } from "controllers/application"
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)