tosspayments2-rails 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd88d1af83f21b3f11746c4825425fd7c9bfee9aa793bd0c6adfde623b25a8c2
-  data.tar.gz: 780b41fdccead7e7b6e26beb5f0ad701f756cc19036c7a713aa1b6c978cbbe19
+  metadata.gz: 39febb97b720a3f4b5b8c17869e56d30f512708c553079e158108be18b243856
+  data.tar.gz: d1d2cb235b61caa90e9bd1477894eed5b5322b7eb497f2f3bf48a5423371401d
 SHA512:
-  metadata.gz: 8804a4ec3d7f980fca6cdba867592f73a763ec933bf963c90bb52e30837be9b59fc4e0cabf320e4915da4eaa9e8fc475e52419620db1565a52d0a714e85eafac
-  data.tar.gz: fe9a02353d00025acb304f67ff7b6e90d2b5bedd6e69760921be3352eb9e06608ce2f073cf24934191550d123561f0102a754f0de0e169dd73a576f06c7d97c2
+  metadata.gz: 5fe2a225d5d062c68d6078136a77cc0e431e99e8bd22925c7ae86e8489cae598e674a0913fde2fc1ba6a13bebd547e216f14447a7750c2afe7eb34264d0e9281
+  data.tar.gz: 111e60a9b9339dc92457af01b3749f9c56a6a1a798383ce114e72b4653fa8733464e73a3916783310d0e723df0d36cce93cca48499bb51c9b6d2941aa2ee98cc

data/.claude/agents/kfc/spec-design.md

@@ -1,6 +1,7 @@
 ---
 name: spec-design
 description: use PROACTIVELY to create/refine the spec design document in a spec development process/workflow. MUST BE USED AFTER spec requirements document is approved.
+model: inherit
 ---
 
 You are a professional spec design document expert. Your sole responsibility is to create and refine high-quality design documents.

data/.claude/agents/kfc/spec-impl.md

@@ -1,6 +1,7 @@
 ---
 name: spec-impl
 description: Coding implementation expert. Use PROACTIVELY when specific coding tasks need to be executed. Specializes in implementing functional code according to task lists.
+model: inherit
 ---
 
 You are a coding implementation expert. Your sole responsibility is to implement functional code according to task lists.

data/.claude/agents/kfc/spec-judge.md

@@ -1,6 +1,7 @@
 ---
 name: spec-judge
 description: use PROACTIVELY to evaluate spec documents (requirements, design, tasks) in a spec development process/workflow
+model: inherit
 ---
 
 You are a professional spec document evaluator. Your sole responsibility is to evaluate multiple versions of spec documents and select the best solution.

data/.claude/agents/kfc/spec-requirements.md

@@ -1,6 +1,7 @@
 ---
 name: spec-requirements
 description: use PROACTIVELY to create/refine the spec requirements document in a spec development process/workflow
+model: inherit
 ---
 
 You are an EARS (Easy Approach to Requirements Syntax) requirements document expert. Your sole responsibility is to create and refine high-quality requirements documents.

data/.claude/agents/kfc/spec-system-prompt-loader.md

@@ -2,6 +2,7 @@
 name: spec-system-prompt-loader
 description: a spec workflow system prompt loader. MUST BE CALLED FIRST when user wants to start a spec process/workflow. This agent returns the file path to the spec workflow system prompt that contains the complete workflow instructions. Call this before any spec-related agents if the prompt is not loaded yet. Input: the type of spec workflow requested. Output: file path to the appropriate workflow prompt file. The returned path should be read to get the full workflow instructions.
 tools: 
+model: inherit
 ---
 
 You are a prompt path mapper. Your ONLY job is to generate and return a file path.

data/.claude/agents/kfc/spec-tasks.md

@@ -1,6 +1,7 @@
 ---
 name: spec-tasks
 description: use PROACTIVELY to create/refine the spec tasks document in a spec development process/workflow. MUST BE USED AFTER spec design document is approved.
+model: inherit
 ---
 
 You are a spec tasks document expert. Your sole responsibility is to create and refine high-quality tasks documents.

data/.claude/agents/kfc/spec-test.md

@@ -1,6 +1,7 @@
 ---
 name: spec-test
 description: use PROACTIVELY to create test documents and test code in spec development workflows. MUST BE USED when users need testing solutions. Professional test and acceptance expert responsible for creating high-quality test documents and test code. Creates comprehensive test case documentation (.md) and corresponding executable test code (.test.ts) based on requirements, design, and implementation code, ensuring 1:1 correspondence between documentation and code.
+model: inherit
 ---
 
 You are a professional test and acceptance expert. Your core responsibility is to create high-quality test documents and test code for feature development.

data/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 _No changes yet._
 
+## [0.5.0] - 2025-08-21
+### Added
+- Complete PaymentsController with full CRUD operations (index, show, new, create, checkout, success, fail, cancel)
+- Enhanced Payment model with validations, scopes, and helper methods
+- New view templates: new.html.erb, checkout.html.erb with TossPayments v2 widget integration
+- PaymentsHelper with status and currency formatting utilities
+- Improved route configuration with collection and member routes
+- Rails credentials support in initializer (fallback to environment variables)
+- Comprehensive checkout flow with actual TossPayments widget implementation
+
+### Changed
+- Updated Rails migration version from 6.0 to 7.0 for Rails 7/8 compatibility
+- Enhanced generator to create complete payment system structure
+- Improved view templates with better styling and user experience
+- Refactored PaymentsController to reduce complexity and improve maintainability
+- Enhanced error handling and payment status management
+
+### Fixed
+- RuboCop violations in generated templates
+- Missing routes for payment workflow
+- Incomplete payment flow implementation
+
+## [0.4.0] - 2025-08-20
+### Changed
+- Add frozen_string_literal magic comments to generator templates
+- Update .gitignore to ignore built gem artifacts (*.gem)
+- RuboCop clean; RSpec green
+
 ## [0.3.0] - 2025-08-21
 ### Changed
 - General maintenance and improvements for release process

data/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+이 파일은 Claude Code (claude.ai/code)가 이 저장소에서 작업할 때 필요한 가이드를 제공합니다.
+
+## 개발 명령어
+
+### 테스트
+```bash
+bundle exec rspec                    # 모든 테스트 실행
+bundle exec rspec spec/client_spec.rb  # 특정 테스트 파일 실행
+```
+
+### 코드 품질
+```bash
+bundle exec rubocop                  # RuboCop 린터 실행
+bundle exec rubocop --auto-correct   # RuboCop 이슈 자동 수정
+rake quality                        # RuboCop과 테스트 모두 실행
+```
+
+### 문서화
+```bash
+bundle exec yard doc                 # YARD 문서 생성
+open doc/index.html                  # 생성된 문서 보기
+```
+
+### 콘솔 및 개발
+```bash
+bin/console                          # 젬이 로드된 인터랙티브 콘솔
+bin/setup                           # 개발을 위한 초기 설정
+```
+
+### 젬 관리
+```bash
+rake build                          # 젬을 로컬에서 빌드
+rake install                        # 젬을 로컬에 설치
+rake release                        # 젬 배포 (사전 검사 포함)
+rake release:check                   # 배포 전 검증 실행
+```
+
+## 아키텍처 개요
+
+### 핵심 구성 요소
+
+Rails 7 & 8 애플리케이션을 위한 TossPayments v2 Payment Widget 통합을 제공하는 Rails 엔진입니다.
+
+**메인 진입점**: `lib/tosspayments2/rails.rb`
+- 모든 구성 요소를 로드하고 모듈 레벨 `configure` 메서드 제공
+- Rails가 있을 때만 Rails 엔진을 조건부로 로드
+
+**Rails 엔진**: `lib/tosspayments2/rails/engine.rb`
+- Rails 앱 설정이나 환경 변수에서 자동 설정
+- 뷰 헬퍼와 컨트롤러 관심사를 자동 로드
+- 격리된 네임스페이스 패턴 사용
+
+**설정**: `lib/tosspayments2/rails/configuration.rb`
+- 전역 설정을 위한 싱글톤 패턴
+- 이니셜라이저와 Rails 앱 설정 패턴 모두 지원
+- 기본값: widget_version='v2', api_base='https://api.tosspayments.com', timeout=10
+
+### 주요 구성 요소
+
+**Client** (`client.rb`): TossPayments API용 HTTP 클라이언트
+- 결제 승인과 취소 처리
+- 일시적 실패를 위한 내장 재시도 로직 (500+ 상태 코드)
+- 비밀 키를 사용한 Base64 Basic Auth
+- 심볼화된 키로 파싱된 JSON 반환
+
+**Controller Concern** (`controller_concern.rb`): Rails 컨트롤러 믹스인
+- `toss_client` 헬퍼 메서드 제공
+- 요청당 클라이언트 인스턴스 메모이제이션
+
+**Script Tag Helper** (`script_tag_helper.rb`): 뷰 헬퍼
+- TossPayments SDK용 `<script>` 태그 생성
+- 버전과 HTML 속성 커스터마이징 지원
+- 메서드명: `tosspayments_script_tag`
+
+**Verifiers**: 보안 검증 유틸리티
+- `CallbackVerifier`: 콜백 파라미터 검증 (order_id, amount)
+- `WebhookVerifier`: HMAC-SHA256 웹훅 서명 검증
+
+**Generator** (`generators/tosspayments2/install/`): Rails 제너레이터
+- 환경 변수 설정으로 이니셜라이저 생성
+- Payment 모델, 마이그레이션, 컨트롤러, 뷰 선택적 생성
+- 명령어: `rails generate tosspayments2:install`
+
+### 에러 처리
+
+**커스텀 예외** (`errors.rb`):
+- `ConfigurationError`: 필수 설정 누락
+- `APIError`: status, body, request_id를 포함한 TossPayments API 에러
+- `VerificationError`: 콜백/웹훅 검증 실패
+
+### 개발 패턴
+
+**젬 구조**: 표준 Ruby 젬 레이아웃
+- `lib/`에 네임스페이스별로 구성된 메인 코드 포함
+- `spec/`에 HTTP 모킹을 위한 WebMock을 사용한 RSpec 테스트 포함
+- `sig/`에 RBS 타입 시그니처 포함
+- `bin/`에 개발 유틸리티 포함
+
+**Rails 통합**: 엔진 패턴
+- 깔끔한 분리를 위해 `isolate_namespace` 사용
+- Rails 훅을 통한 헬퍼 자동 로드
+- 이니셜라이저와 앱 설정 모두 지원
+
+**설정 우선순위**:
+1. 클래스에 대한 명시적 파라미터
+2. `Tosspayments2::Rails.configure`를 통한 전역 설정
+3. Rails 앱 설정 (`config.tosspayments2.*`)
+4. 환경 변수 (`TOSSPAYMENTS_CLIENT_KEY`, `TOSSPAYMENTS_SECRET_KEY`)
+
+**테스트**: 광범위한 모킹을 사용한 RSpec
+- HTTP 요청을 위한 WebMock
+- 커버리지 보고를 위한 SimpleCov
+- 설명적인 이름으로 구성 요소별로 구성된 테스트
+
+### 배포 프로세스
+
+젬에는 자동화된 배포 검증이 포함됩니다:
+- Git 작업 디렉토리가 깨끗해야 함
+- RuboCop이 통과해야 함
+- 모든 테스트가 통과해야 함
+- CHANGELOG.md에 현재 버전 항목이 있어야 함
+- 배포 전 `rake release:check` 사용

data/lib/generators/tosspayments2/install/install_generator.rb

@@ -5,16 +5,65 @@ module Tosspayments2
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
+
       class_option :controller, type: :boolean, default: false, desc: 'Generate example payments controller'
+      class_option :with_model, type: :boolean, default: true,
+                                desc: 'Generate Payment model, migration, and views'
 
       def create_initializer
-        template 'initializer.rb', 'config/initializers/tosspayments2.rb'
+        template 'initializer.rb', 'config/initializers/tosspayments.rb'
       end
 
       def create_controller
         return unless options[:controller]
 
         template 'payments_controller.rb', 'app/controllers/payments_controller.rb'
+        template 'payments_helper.rb', 'app/helpers/payments_helper.rb'
+      end
+
+      def create_payment_model_and_migration
+        return unless options[:with_model]
+
+        # Payment 모델 생성
+        template 'payment.rb', 'app/models/payment.rb'
+
+        # 마이그레이션 파일명에 타임스탬프 추가
+        timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+        migration_file = "db/migrate/#{timestamp}_create_payments.rb"
+        template 'migration.rb', migration_file
+
+        # 뷰 파일 생성
+        empty_directory 'app/views/payments'
+        template 'index.html.erb', 'app/views/payments/index.html.erb'
+        template 'show.html.erb', 'app/views/payments/show.html.erb'
+        template 'new.html.erb', 'app/views/payments/new.html.erb'
+        template 'checkout.html.erb', 'app/views/payments/checkout.html.erb'
+      end
+
+      def add_payments_route
+        route <<~RUBY
+          resources :payments do
+            collection do
+              get :checkout
+              get :success
+              get :fail
+            end
+            member do
+              patch :cancel
+            end
+          end
+        RUBY
+      end
+
+      # 제너레이터 실행 시 자동으로 모델/마이그레이션/뷰 생성
+      def install
+        create_payment_model_and_migration
+        add_payments_route
+      end
+
+      # Thor의 hook으로 install 메서드가 자동 실행되도록 설정
+      def self.default_task
+        :install
       end
     end
   end

data/lib/generators/tosspayments2/install/templates/checkout.html.erb

@@ -0,0 +1,115 @@
+<h1>결제 진행</h1>
+
+<div class="payment-info">
+  <h3>결제 정보</h3>
+  <p><strong>주문번호:</strong> <%= @payment.order_id %></p>
+  <p><strong>결제금액:</strong> <%= @payment.formatted_amount %></p>
+</div>
+
+<!-- TossPayments 결제 위젯 영역 -->
+<div id="payment-methods"></div>
+<div id="agreement"></div>
+<button id="payment-button" class="btn btn-primary">결제하기</button>
+
+<%= tosspayments_script_tag %>
+
+<script>
+document.addEventListener('DOMContentLoaded', async () => {
+  // TossPayments 설정
+  const clientKey = '<%= Rails.application.credentials.dig(:tosspayments, :client_key) || ENV["TOSSPAYMENTS_CLIENT_KEY"] %>';
+  const customerKey = 'customer_<%= Time.current.to_i %>'; // 구매자 식별값
+  
+  if (!clientKey) {
+    console.error('TossPayments 클라이언트 키가 설정되지 않았습니다.');
+    alert('결제 서비스를 초기화할 수 없습니다. 관리자에게 문의하세요.');
+    return;
+  }
+
+  try {
+    // TossPayments 위젯 초기화
+    const tosspayments = TossPayments(clientKey);
+    const widgets = tosspayments.widgets({ customerKey: customerKey });
+
+    // 결제 수단 렌더링
+    await widgets.renderPaymentMethods({
+      selector: '#payment-methods',
+      variantKey: 'DEFAULT'
+    });
+
+    // 약관 동의 렌더링
+    await widgets.renderAgreement({
+      selector: '#agreement'
+    });
+
+    // 결제 버튼 이벤트 리스너
+    document.getElementById('payment-button').addEventListener('click', async () => {
+      try {
+        await widgets.requestPayment({
+          orderId: '<%= @payment.order_id %>',
+          orderName: '결제 테스트 상품',
+          customerName: '고객',
+          amount: <%= @payment.amount %>,
+          successUrl: '<%= success_payments_url %>',
+          failUrl: '<%= fail_payments_url %>'
+        });
+      } catch (error) {
+        console.error('결제 요청 실패:', error);
+        alert('결제 요청에 실패했습니다: ' + (error.message || error.toString()));
+      }
+    });
+  } catch (error) {
+    console.error('TossPayments 초기화 실패:', error);
+    alert('결제 서비스 초기화에 실패했습니다: ' + (error.message || error.toString()));
+  }
+});
+</script>
+
+<style>
+  .payment-info {
+    background-color: #f8f9fa;
+    padding: 1rem;
+    border-radius: 0.25rem;
+    margin-bottom: 2rem;
+  }
+  
+  #payment-methods {
+    margin-bottom: 1rem;
+  }
+  
+  #agreement {
+    margin-bottom: 1rem;
+  }
+  
+  #payment-button {
+    width: 100%;
+    padding: 0.75rem;
+    font-size: 1.1rem;
+    font-weight: bold;
+  }
+  
+  .btn { 
+    display: inline-block; 
+    padding: 0.375rem 0.75rem; 
+    margin-bottom: 0; 
+    font-size: 1rem; 
+    font-weight: 400; 
+    line-height: 1.5; 
+    text-align: center; 
+    text-decoration: none; 
+    vertical-align: middle; 
+    cursor: pointer; 
+    border: 1px solid transparent; 
+    border-radius: 0.25rem; 
+  }
+  
+  .btn-primary { 
+    color: #fff; 
+    background-color: #007bff; 
+    border-color: #007bff; 
+  }
+  
+  .btn-primary:hover {
+    background-color: #0056b3;
+    border-color: #004085;
+  }
+</style>

data/lib/generators/tosspayments2/install/templates/index.html.erb

@@ -0,0 +1,93 @@
+<h1>결제 내역</h1>
+
+<div class="mb-3">
+  <%= link_to '새 결제', new_payment_path, class: 'btn btn-primary' %>
+</div>
+
+<table class="table table-striped">
+  <thead>
+    <tr>
+      <th>주문번호</th>
+      <th>금액</th>
+      <th>상태</th>
+      <th>거래ID</th>
+      <th>생성일</th>
+      <th>액션</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% if @payments.any? %>
+      <% @payments.each do |payment| %>
+        <tr>
+          <td><%= payment.order_id %></td>
+          <td><%= payment.formatted_amount %></td>
+          <td>
+            <span class="badge <%= payment_status_class(payment.status) %>">
+              <%= payment_status_text(payment.status) %>
+            </span>
+          </td>
+          <td><%= payment.transaction_id %></td>
+          <td><%= payment.created_at.strftime('%Y-%m-%d %H:%M') %></td>
+          <td>
+            <%= link_to '상세', payment_path(payment), class: 'btn btn-sm btn-outline-primary' %>
+            <% if payment.confirmed? %>
+              <%= link_to '취소', cancel_payment_path(payment), method: :patch, 
+                          confirm: '결제를 취소하시겠습니까?', 
+                          class: 'btn btn-sm btn-outline-danger' %>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+    <% else %>
+      <tr>
+        <td colspan="6" class="text-center">결제 내역이 없습니다.</td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+
+<script>
+function payment_status_class(status) {
+  switch(status) {
+    case 'confirmed': return 'bg-success';
+    case 'pending': return 'bg-warning';
+    case 'cancelled': return 'bg-secondary';
+    case 'failed': return 'bg-danger';
+    default: return 'bg-light';
+  }
+}
+
+function payment_status_text(status) {
+  switch(status) {
+    case 'confirmed': return '완료';
+    case 'pending': return '대기중';
+    case 'cancelled': return '취소됨';
+    case 'failed': return '실패';
+    default: return status;
+  }
+}
+</script>
+
+<%# Bootstrap CSS가 없다면 기본 스타일링 %>
+<style>
+  .table { width: 100%; border-collapse: collapse; margin-top: 1rem; }
+  .table th, .table td { padding: 0.75rem; border-bottom: 1px solid #dee2e6; text-align: left; }
+  .table thead th { border-bottom: 2px solid #dee2e6; }
+  .table-striped tbody tr:nth-of-type(odd) { background-color: rgba(0, 0, 0, 0.05); }
+  .btn { display: inline-block; padding: 0.375rem 0.75rem; margin-bottom: 0; font-size: 1rem; 
+         font-weight: 400; line-height: 1.5; text-align: center; text-decoration: none; 
+         vertical-align: middle; cursor: pointer; border: 1px solid transparent; border-radius: 0.25rem; }
+  .btn-primary { color: #fff; background-color: #007bff; border-color: #007bff; }
+  .btn-sm { padding: 0.25rem 0.5rem; font-size: 0.875rem; }
+  .btn-outline-primary { color: #007bff; border-color: #007bff; }
+  .btn-outline-danger { color: #dc3545; border-color: #dc3545; }
+  .badge { display: inline-block; padding: 0.25em 0.4em; font-size: 75%; font-weight: 700; 
+           line-height: 1; text-align: center; white-space: nowrap; vertical-align: baseline; 
+           border-radius: 0.25rem; }
+  .bg-success { background-color: #28a745 !important; color: white; }
+  .bg-warning { background-color: #ffc107 !important; color: black; }
+  .bg-secondary { background-color: #6c757d !important; color: white; }
+  .bg-danger { background-color: #dc3545 !important; color: white; }
+  .mb-3 { margin-bottom: 1rem; }
+  .text-center { text-align: center; }
+</style>

data/lib/generators/tosspayments2/install/templates/initializer.rb

@@ -2,8 +2,25 @@
 
 # TossPayments2 configuration
 Tosspayments2::Rails.configure do |c|
-  c.client_key = ENV.fetch('TOSSPAYMENTS_CLIENT_KEY', nil)
-  c.secret_key = ENV.fetch('TOSSPAYMENTS_SECRET_KEY', nil)
+  # Rails credentials 우선, 없으면 환경 변수 사용
+  c.client_key = Rails.application.credentials.dig(:tosspayments, :client_key) ||
+                 ENV.fetch('TOSSPAYMENTS_CLIENT_KEY', nil)
+  c.secret_key = Rails.application.credentials.dig(:tosspayments, :secret_key) ||
+                 ENV.fetch('TOSSPAYMENTS_SECRET_KEY', nil)
+
+  # 선택적 설정들 (기본값 사용 가능)
   # c.widget_version = 'v2'
   # c.api_base = 'https://api.tosspayments.com'
+  # c.timeout = 10
 end
+
+# credentials.yml.enc 파일 설정 예시:
+# $ EDITOR="nano" bin/rails credentials:edit
+#
+# tosspayments:
+#   client_key: test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoqo56A
+#   secret_key: test_sk_zXLkKEypNArWmo50nX3lmeaxYG5vSSu7
+#
+# 또는 환경 변수로 설정:
+# export TOSSPAYMENTS_CLIENT_KEY=test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoqo56A
+# export TOSSPAYMENTS_SECRET_KEY=test_sk_zXLkKEypNArWmo50nX3lmeaxYG5vSSu7

data/lib/generators/tosspayments2/install/templates/migration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CreatePayments < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payments do |t|
+      t.string :order_id, null: false
+      t.integer :amount, null: false
+      t.string :status, null: false
+      t.string :transaction_id
+      t.timestamps
+    end
+    add_index :payments, :order_id, unique: true
+  end
+end

data/lib/generators/tosspayments2/install/templates/new.html.erb

@@ -0,0 +1,42 @@
+<h1>새 결제</h1>
+
+<%= form_with(model: @payment, local: true) do |form| %>
+  <% if @payment.errors.any? %>
+    <div class="alert alert-danger">
+      <h4><%= pluralize(@payment.errors.count, "error") %> 발생:</h4>
+      <ul>
+        <% @payment.errors.full_messages.each do |message| %>
+          <li><%= message %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="form-group">
+    <%= form.label :amount, '결제 금액' %>
+    <%= form.number_field :amount, class: 'form-control', placeholder: '예: 10000', required: true %>
+    <small class="form-text text-muted">원 단위로 입력해주세요</small>
+  </div>
+
+  <div class="actions">
+    <%= form.submit '결제하기', class: 'btn btn-primary' %>
+    <%= link_to '취소', payments_path, class: 'btn btn-secondary' %>
+  </div>
+<% end %>
+
+<style>
+  .form-group { margin-bottom: 1rem; }
+  .form-control { display: block; width: 100%; padding: 0.375rem 0.75rem; font-size: 1rem; 
+                  line-height: 1.5; color: #495057; background-color: #fff; background-clip: padding-box; 
+                  border: 1px solid #ced4da; border-radius: 0.25rem; }
+  .form-text { display: block; margin-top: 0.25rem; font-size: 0.875em; color: #6c757d; }
+  .alert { position: relative; padding: 0.75rem 1.25rem; margin-bottom: 1rem; border: 1px solid transparent; border-radius: 0.25rem; }
+  .alert-danger { color: #721c24; background-color: #f8d7da; border-color: #f5c6cb; }
+  .actions { margin-top: 1rem; }
+  .btn { display: inline-block; padding: 0.375rem 0.75rem; margin-bottom: 0; font-size: 1rem; 
+         font-weight: 400; line-height: 1.5; text-align: center; text-decoration: none; 
+         vertical-align: middle; cursor: pointer; border: 1px solid transparent; border-radius: 0.25rem; }
+  .btn-primary { color: #fff; background-color: #007bff; border-color: #007bff; }
+  .btn-secondary { color: #fff; background-color: #6c757d; border-color: #6c757d; }
+  label { display: inline-block; margin-bottom: 0.5rem; font-weight: bold; }
+</style>

data/lib/generators/tosspayments2/install/templates/payment.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# 결제 정보를 저장하는 Payment 모델
+class Payment < ApplicationRecord
+  validates :order_id, presence: true, uniqueness: true
+  validates :amount, presence: true, numericality: { greater_than: 0 }
+  validates :status, presence: true, inclusion: { in: %w[pending confirmed cancelled failed] }
+
+  scope :confirmed, -> { where(status: 'confirmed') }
+  scope :pending, -> { where(status: 'pending') }
+  scope :cancelled, -> { where(status: 'cancelled') }
+  scope :failed, -> { where(status: 'failed') }
+
+  def confirmed?
+    status == 'confirmed'
+  end
+
+  def pending?
+    status == 'pending'
+  end
+
+  def cancelled?
+    status == 'cancelled'
+  end
+
+  def failed?
+    status == 'failed'
+  end
+
+  def formatted_amount
+    "#{amount.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}원"
+  end
+end

data/lib/generators/tosspayments2/install/templates/payments_controller.rb

@@ -3,22 +3,79 @@
 class PaymentsController < ApplicationController
   include Tosspayments2::Rails::ControllerConcern
 
+  before_action :set_payment, only: %i[show cancel]
+
+  def index
+    @payments = Payment.order(created_at: :desc)
+  end
+
+  def show; end
+
+  def new
+    @payment = Payment.new
+    @order_id = "ORDER-#{Time.current.strftime('%Y%m%d%H%M%S')}-#{SecureRandom.hex(4)}"
+  end
+
+  def create
+    @payment = Payment.new(payment_params)
+    @payment.status = 'pending'
+    @payment.order_id = "ORDER-#{Time.current.strftime('%Y%m%d%H%M%S')}-#{SecureRandom.hex(4)}"
+
+    if @payment.save
+      redirect_to checkout_payments_path(order_id: @payment.order_id)
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def checkout
+    @order_id = params[:order_id]
+    @payment = Payment.find_by!(order_id: @order_id)
+  end
+
   def success
     load_params
     verify_amount!
-    @payment = toss_client.confirm(payment_key: @payment_key, order_id: @order_id, amount: @amount)
+    process_payment_confirmation
+    redirect_to @payment, notice: '결제가 성공적으로 완료되었습니다.'
   rescue Tosspayments2::Rails::VerificationError, Tosspayments2::Rails::APIError => e
-    Rails.logger.error("Payment error: #{e.class} #{e.message}")
-    redirect_to root_path, alert: '결제 승인 실패'
+    handle_payment_error(e)
   end
 
   def fail
+    order_id = params[:orderId]
+
+    # 실패 시 Payment 상태 업데이트
+    if order_id && (payment = Payment.find_by(order_id: order_id))
+      payment.update(status: 'failed')
+    end
+
     flash[:alert] = "결제 실패: #{params[:message] || params[:errorMessage]}"
     redirect_to root_path
   end
 
+  def cancel
+    toss_client.cancel(
+      payment_key: @payment.transaction_id,
+      cancel_reason: params[:cancel_reason] || '고객 요청에 의한 취소'
+    )
+    @payment.update!(status: 'cancelled')
+    redirect_to @payment, notice: '결제가 취소되었습니다.'
+  rescue Tosspayments2::Rails::APIError => e
+    Rails.logger.error("Payment cancel error: #{e.message}")
+    redirect_to @payment, alert: '결제 취소에 실패했습니다.'
+  end
+
   private
 
+  def set_payment
+    @payment = Payment.find(params[:id])
+  end
+
+  def payment_params
+    params.require(:payment).permit(:amount)
+  end
+
   def load_params
     @payment_key = params[:paymentKey]
     @order_id    = params[:orderId]
@@ -26,12 +83,47 @@ class PaymentsController < ApplicationController
   end
 
   def verify_amount!
-    Tosspayments2::Rails::CallbackVerifier.new.match_amount?(order_id: @order_id, amount: @amount) do |_oid|
-      # Lookup the expected amount for the given order id in your domain model.
-      # Example:
-      #   Order.find_by!(uuid: _oid).amount
-      # For demo purposes we return a fixed integer:
-      1000
+    Tosspayments2::Rails::CallbackVerifier.new.match_amount?(order_id: @order_id, amount: @amount) do |oid|
+      # 저장된 Payment 레코드에서 금액 확인
+      payment = Payment.find_by(order_id: oid)
+      payment&.amount || 0
     end
   end
+
+  def process_payment_confirmation
+    # 결제 승인 API 호출
+    toss_response = toss_client.confirm(payment_key: @payment_key, order_id: @order_id, amount: @amount)
+
+    # Payment 레코드 생성 또는 업데이트
+    @payment = find_or_create_payment
+
+    # 결제 승인 성공 시 상태 업데이트
+    @payment.update!(
+      status: 'confirmed',
+      transaction_id: toss_response[:paymentKey] || toss_response['paymentKey']
+    )
+  end
+
+  def find_or_create_payment
+    Payment.find_or_create_by(order_id: @order_id) do |payment|
+      payment.amount = @amount
+      payment.status = 'pending'
+    end
+  end
+
+  def handle_payment_error(error)
+    Rails.logger.error("Payment error: #{error.class} #{error.message}")
+
+    # 실패 시 Payment 상태 업데이트
+    update_payment_status_on_failure
+
+    redirect_to root_path, alert: '결제 승인에 실패했습니다.'
+  end
+
+  def update_payment_status_on_failure
+    return unless @order_id
+
+    payment = Payment.find_by(order_id: @order_id)
+    payment&.update(status: 'failed')
+  end
 end

data/lib/generators/tosspayments2/install/templates/payments_helper.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PaymentsHelper
+  def payment_status_class(status)
+    case status
+    when 'confirmed'
+      'bg-success'
+    when 'pending'
+      'bg-warning'
+    when 'cancelled'
+      'bg-secondary'
+    when 'failed'
+      'bg-danger'
+    else
+      'bg-light'
+    end
+  end
+
+  def payment_status_text(status)
+    case status
+    when 'confirmed'
+      '결제완료'
+    when 'pending'
+      '결제대기'
+    when 'cancelled'
+      '결제취소'
+    when 'failed'
+      '결제실패'
+    else
+      status
+    end
+  end
+
+  def format_currency(amount)
+    "#{amount.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}원"
+  end
+end

data/lib/generators/tosspayments2/install/templates/show.html.erb

@@ -0,0 +1,150 @@
+<h1>결제 상세</h1>
+
+<div class="payment-detail">
+  <div class="card">
+    <div class="card-header">
+      <h3>결제 정보</h3>
+      <span class="badge <%= payment_status_class(@payment.status) %>">
+        <%= payment_status_text(@payment.status) %>
+      </span>
+    </div>
+    
+    <div class="card-body">
+      <dl class="row">
+        <dt class="col-sm-3">주문번호</dt>
+        <dd class="col-sm-9"><%= @payment.order_id %></dd>
+        
+        <dt class="col-sm-3">결제금액</dt>
+        <dd class="col-sm-9"><%= @payment.formatted_amount %></dd>
+        
+        <dt class="col-sm-3">결제상태</dt>
+        <dd class="col-sm-9">
+          <span class="badge <%= payment_status_class(@payment.status) %>">
+            <%= payment_status_text(@payment.status) %>
+          </span>
+        </dd>
+        
+        <% if @payment.transaction_id.present? %>
+          <dt class="col-sm-3">거래ID</dt>
+          <dd class="col-sm-9"><%= @payment.transaction_id %></dd>
+        <% end %>
+        
+        <dt class="col-sm-3">생성일시</dt>
+        <dd class="col-sm-9"><%= @payment.created_at.strftime('%Y-%m-%d %H:%M:%S') %></dd>
+        
+        <dt class="col-sm-3">최종 업데이트</dt>
+        <dd class="col-sm-9"><%= @payment.updated_at.strftime('%Y-%m-%d %H:%M:%S') %></dd>
+      </dl>
+    </div>
+  </div>
+</div>
+
+<div class="actions">
+  <%= link_to '목록으로', payments_path, class: 'btn btn-secondary' %>
+  
+  <% if @payment.confirmed? %>
+    <%= link_to '결제 취소', cancel_payment_path(@payment), method: :patch,
+                confirm: '정말로 이 결제를 취소하시겠습니까?',
+                class: 'btn btn-danger' %>
+  <% elsif @payment.pending? %>
+    <%= link_to '결제 계속하기', checkout_payments_path(order_id: @payment.order_id), 
+                class: 'btn btn-primary' %>
+  <% end %>
+</div>
+
+<script>
+function payment_status_class(status) {
+  switch(status) {
+    case 'confirmed': return 'bg-success';
+    case 'pending': return 'bg-warning';
+    case 'cancelled': return 'bg-secondary';
+    case 'failed': return 'bg-danger';
+    default: return 'bg-light';
+  }
+}
+
+function payment_status_text(status) {
+  switch(status) {
+    case 'confirmed': return '결제완료';
+    case 'pending': return '결제대기';
+    case 'cancelled': return '결제취소';
+    case 'failed': return '결제실패';
+    default: return status;
+  }
+}
+</script>
+
+<style>
+  .payment-detail { margin-bottom: 2rem; }
+  
+  .card { 
+    position: relative; 
+    display: flex; 
+    flex-direction: column; 
+    min-width: 0; 
+    word-wrap: break-word; 
+    background-color: #fff; 
+    background-clip: border-box; 
+    border: 1px solid rgba(0,0,0,.125); 
+    border-radius: 0.25rem; 
+  }
+  
+  .card-header { 
+    padding: 0.75rem 1.25rem; 
+    margin-bottom: 0; 
+    background-color: rgba(0,0,0,.03); 
+    border-bottom: 1px solid rgba(0,0,0,.125); 
+    display: flex; 
+    justify-content: space-between; 
+    align-items: center; 
+  }
+  
+  .card-body { padding: 1.25rem; }
+  
+  .row { display: flex; flex-wrap: wrap; margin-right: -15px; margin-left: -15px; }
+  .col-sm-3 { flex: 0 0 25%; max-width: 25%; padding-right: 15px; padding-left: 15px; }
+  .col-sm-9 { flex: 0 0 75%; max-width: 75%; padding-right: 15px; padding-left: 15px; }
+  
+  dl { margin-bottom: 1rem; }
+  dt { font-weight: 700; }
+  dd { margin-bottom: 0.5rem; margin-left: 0; }
+  
+  .badge { 
+    display: inline-block; 
+    padding: 0.25em 0.4em; 
+    font-size: 75%; 
+    font-weight: 700; 
+    line-height: 1; 
+    text-align: center; 
+    white-space: nowrap; 
+    vertical-align: baseline; 
+    border-radius: 0.25rem; 
+  }
+  
+  .bg-success { background-color: #28a745 !important; color: white; }
+  .bg-warning { background-color: #ffc107 !important; color: black; }
+  .bg-secondary { background-color: #6c757d !important; color: white; }
+  .bg-danger { background-color: #dc3545 !important; color: white; }
+  
+  .actions { margin-top: 2rem; }
+  
+  .btn { 
+    display: inline-block; 
+    padding: 0.375rem 0.75rem; 
+    margin-right: 0.5rem;
+    margin-bottom: 0; 
+    font-size: 1rem; 
+    font-weight: 400; 
+    line-height: 1.5; 
+    text-align: center; 
+    text-decoration: none; 
+    vertical-align: middle; 
+    cursor: pointer; 
+    border: 1px solid transparent; 
+    border-radius: 0.25rem; 
+  }
+  
+  .btn-primary { color: #fff; background-color: #007bff; border-color: #007bff; }
+  .btn-secondary { color: #fff; background-color: #6c757d; border-color: #6c757d; }
+  .btn-danger { color: #fff; background-color: #dc3545; border-color: #dc3545; }
+</style>

data/lib/tosspayments2/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tosspayments2
   module Rails
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tosspayments2-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Lucius Choi
@@ -52,13 +52,21 @@ files:
 - ".vscode/mcp.json"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - RELEASE_NOTES_v0.2.0.md
 - Rakefile
 - lib/generators/tosspayments2/install/install_generator.rb
+- lib/generators/tosspayments2/install/templates/checkout.html.erb
+- lib/generators/tosspayments2/install/templates/index.html.erb
 - lib/generators/tosspayments2/install/templates/initializer.rb
+- lib/generators/tosspayments2/install/templates/migration.rb
+- lib/generators/tosspayments2/install/templates/new.html.erb
+- lib/generators/tosspayments2/install/templates/payment.rb
 - lib/generators/tosspayments2/install/templates/payments_controller.rb
+- lib/generators/tosspayments2/install/templates/payments_helper.rb
+- lib/generators/tosspayments2/install/templates/show.html.erb
 - lib/tosspayments2/rails.rb
 - lib/tosspayments2/rails/callback_verifier.rb
 - lib/tosspayments2/rails/client.rb