Skip to content

Commit 6f7de1d

Browse files
SOIVSOIV
committed
docs: 교통비 관리 관련 시스템 개발 이전 계획 문서화
- 모든 내용은 2026-05-04 (KST) 기준을 합니다. - 개발이 진행 중에도 지속적으로 업데이트가 생기는 경우 문서에 업데이트를 적용합니다.
1 parent 9d88a7a commit 6f7de1d

5 files changed

Lines changed: 1425 additions & 0 deletions

File tree

‎docs/v2_FINANCIAL-LEDGER/transit/00-overview.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# 교통비 관리 시스템 — 전체 개요
2+
3+
> **위치**: Ledger 모듈 서브라우트 (`#ledger/transit`)
4+
> **상태**: 설계 중 (2026-05-04)
5+
6+
---
7+
8+
## 1. 목표
9+
10+
가계부(Ledger)의 서브 기능으로 교통카드/패스 관리를 통합한다.
11+
별도 모듈이 아닌 Ledger 내 사이드바 서브탭으로 구현한다.
12+
13+
```
14+
📕 가계부
15+
├ 메인 → #ledger
16+
└ 교통비 관리 → #ledger/transit
17+
```
18+
19+
핵심 기능:
20+
- 보유 교통카드/패스 등록 및 관리
21+
- 교통비 지출 항목과 카드 연동 (Ledger Entry 태깅)
22+
- **K-패스 기본형/모두의 카드 예상 환급액 계산**
23+
- **카드 상품별 추가 혜택 추적** (기본 환급 외 캐시백/쿠폰/잔액 증액)
24+
- 카드 상품별 환급 지급 일정 추적 및 알림
25+
- 환급 수입 항목 자동 생성 (Ledger Entry로)
26+
- 기후동행카드 손익분기점 분석
27+
- Suica/PASMO 잔액 추적
28+
29+
---
30+
31+
## 2. 지원 교통카드/패스 유형
32+
33+
| 유형 | 카드명 | 국가 | 정산 방식 |
34+
|------|--------|------|-----------|
35+
| `kpass` | K-패스 | 🇰🇷 한국 | 기본형/모두의 카드 계산 후 카드 상품 정책에 따라 익월 지급 |
36+
| `climate` | 기후동행카드 | 🇰🇷 한국 (서울) | 월정액 고정비, 손익분기 분석 |
37+
| `suica` | Suica | 🇯🇵 일본 | 선불 IC, 충전액 지출 추적 |
38+
| `pasmo` | PASMO | 🇯🇵 일본 | 선불 IC, 충전액 지출 추적 |
39+
| `pass` | 기간제 패스 | 공통 | 고정 비용 + 기간 내 가치 계산 |
40+
| `other` | 기타 | 공통 | 단순 지출 기록 |
41+
42+
---
43+
44+
## 3. K-패스 개요
45+
46+
> **기준 시점**: 2026-05-04 검토 기준
47+
> **정책 버전**: `2026-01` (모두의 카드 도입 이후)
48+
49+
### 기본 적립률
50+
51+
| 구분 | 대상 | 기본 적립률 | 비고 |
52+
|------|------|-------------|------|
53+
| 일반 | 만 19세 이상 | **20%** | 전국 공통 기본형 |
54+
| 청년 | 만 19세 ~ 34세 | **30%** | 일부 지자체는 청년 연령 확대 |
55+
| 저소득 | 기초생활수급자·차상위계층 | **53%** | 일부 지자체는 추가 상향 |
56+
| 다자녀(2인) | 2자녀 가구 | **30%** | 2026 공식 안내 반영 |
57+
| 다자녀(3인 이상) | 3자녀 이상 가구 | **50%** | 2026 공식 안내 반영 |
58+
59+
> 구현 메모:
60+
> 카드 자체에는 기본 등급(`general` / `youth` / `low_income`)만 저장하고,
61+
> 다자녀/지자체 가산은 사용자 프로필·주소지 정책으로 별도 오버레이한다.
62+
63+
### 기본 지급 기준
64+
65+
- 월 15회 이상 이용 시 지급, **가입 첫 달은 15회 미만이어도 지급**
66+
- **1일 최대 2회**, **월 최대 60회**까지 인정
67+
- 환승은 **30분 이내 승하차 시 1회**로 묶임
68+
- 월 이용금액 **20만 원까지 전액 인정**, 초과분은 **50%만 반영**
69+
- 경기·인천·경남·울산은 `20만 원 초과 50% 반영 제한` 예외
70+
- 체크카드는 계좌 입금, 신용카드는 청구 차감 또는 계좌 지급 등 **카드 상품 정책에 따라 처리**
71+
72+
### 기본형 계산식
73+
74+
```
75+
isEligible =
76+
가입_첫달 ? tripCount >= 1 : tripCount >= 15
77+
78+
recognizedTrips =
79+
일별 이용내역을 금액순으로 최대 2건만 인정한 뒤
80+
월 기준 금액이 큰 순으로 최대 60건까지 반영
81+
82+
recognizedFare =
83+
MIN(totalFare, 200000) + MAX(totalFare - 200000, 0) * 0.5
84+
// 경기·인천·경남·울산은 지역 정책 예외
85+
86+
estimatedBasicRefund =
87+
isEligible ? recognizedFare * refundRate : 0
88+
```
89+
90+
### 모두의 카드 (2026-01 도입)
91+
92+
- 기본형(정률 환급), 일반형, 플러스형 중 **가장 유리한 방식**이 자동 적용된다.
93+
- 일반 국민 기준 환급 기준금액:
94+
95+
| 지역 구분 | 일반형 기준금액 | 플러스형 기준금액 |
96+
|-----------|------------------|-------------------|
97+
| 수도권 | 62,000원 | 100,000원 |
98+
| 일반지방권 | 55,000원 | 95,000원 |
99+
| 우대지원지역 | 50,000원 | 90,000원 |
100+
| 특별지원지역 | 45,000원 | 85,000원 |
101+
102+
> 본 설계 문서 1차 범위는 **기본형 계산 + 카드 상품 지급 추적**을 우선한다.
103+
> 모두의 카드 및 지자체 확장 규칙은 `policy_version` 기반 정책 엔진으로 확장한다.
104+
105+
### 브랜드/상품 구조
106+
107+
- **브랜드(brand)**: 은행, 카드사, 핀테크, 교통 플랫폼
108+
- **상품(product)**: 실제 사용자가 선택하는 카드/모바일 교통수단
109+
- **혜택(benefit)**: 해당 상품에만 붙는 추가 캐시백/쿠폰/잔액 증액
110+
111+
사용자는 `브랜드`를 먼저 고르고, 그 안에서 실제 보유한 `상품`을 선택한다.
112+
환급 규칙과 부가혜택은 모두 `상품` 기준으로 계산한다.
113+
114+
### 핵심 규칙
115+
116+
- 혜택 계산 단위는 `brand`가 아니라 `product`다.
117+
- 사용자가 등록한 K-패스 카드는 반드시 `product_id`를 참조한다.
118+
- `K-패스 정책 환급`과 `상품 추가 혜택`은 화면에서 합산 표시할 수 있지만 내부 데이터는 분리 유지한다.
119+
- 상품/혜택은 기간이 있는 데이터로 취급하며 `valid_from`, `valid_to`, `is_active`를 기준으로 관리한다.
120+
121+
### 카드 상품 지급 방식 (공식 확인분)
122+
123+
| 분류 | 카드 상품 | 지급 규칙 |
124+
|------|---------------|-----------|
125+
| 결제일 연동 | BC하나카드, BC바로카드, IBK기업은행, 현대카드, 광주은행, iM뱅크 | 익월 7~9영업일 이후 결제대금 차감, 결제대금이 없으면 계좌 입금 |
126+
| 영업일 범위 지급 | 신한카드 | 익월 7~9영업일 이후 결제계좌(체크는 대표계좌) 입금 |
127+
| 영업일 범위 지급 | 우리카드 | 익월 7~9영업일 이후 결제대금 차감, 결제대금이 없으면 계좌 입금 |
128+
| 영업일 범위 지급 | 삼성카드 | 익월 7~8영업일 계좌 입금 |
129+
| 영업일 범위 지급 | 하나카드 | 익월 8~10영업일 계좌 입금 |
130+
| 영업일 범위 지급 | NH농협카드 | 익월 7~9영업일 계좌 입금 |
131+
| 영업일 범위 지급 | 롯데카드 | 익월 7~10영업일 사이 계좌 입금 |
132+
| 영업일 범위 지급 | 부산은행 | 익월 8~10영업일 계좌 입금 |
133+
| 고정일 지급 | KB국민카드 | 익월 마지막 영업일 계좌 입금 |
134+
| 고정일 지급 | 케이뱅크 | 익월 15일, 휴일이면 다음 영업일 계좌 입금 |
135+
| 고정일 지급 | 카카오뱅크 | 익월 20일, 휴일이면 직전 영업일 계좌 입금 |
136+
| 고정일 지급 | 티머니 | 익월 16일 지급 |
137+
| 쿠폰/잔액 지급 | 카카오페이 | 익월 20~27일 오전 10시 카카오페이 앱 쿠폰함 지급 |
138+
| 쿠폰/잔액 지급 | 네이버페이 | 익월 20~27일 오전 10시 네이버페이 교통 잔액 자동 증액 |
139+
| 쿠폰/잔액 지급 | 모바일이즐 | 익월 20~27일 오전 10시 앱 선물함 지급 |
140+
| 쿠폰/잔액 지급 | 이즐(실물카드) | 익월 20~27일 오전 10시 이즐충전소 앱 선물 지급 |
141+
| 기타 | iM유페이 | 모바일 카드는 익월 7영업일 원마일리지, 실물 카드는 별도 지급 신청 |
142+
| 신규 확대 | 토스뱅크 | 2026-01-20 국토교통부 발표 기준 K-패스 참여 확대 대상, 토스뱅크 안내 페이지는 `매달 25일` 환급 표기 |
143+
144+
### 2026 참여 확대 (공식 발표)
145+
146+
2026-01-20 국토교통부 발표 기준, 주관 카드사는 **20개에서 27개로 확대**되었고
147+
신규 확대 대상에는 **전북은행, 신협, 경남은행, 새마을금고, 제주은행, 토스뱅크, 티머니**가 포함된다.
148+
149+
> 시스템은 지급일/지급문구를 사용자가 수정 가능하게 설계하여 카드사 정책 변경에 대응한다.
150+
151+
### 카드 상품 추가 혜택 (기본 환급 외)
152+
153+
K-패스 자체 환급 외에도, 일부 상품은 **교통비 추가 캐시백**이나
154+
**자사 쿠폰/잔액 혜택**을 함께 제공한다. 이 영역은 정책성 환급과 분리해서 관리해야 한다.
155+
156+
| 카드 상품 | 추가 혜택 | 조건 | 지급 방식 |
157+
|---------------|-----------|------|-----------|
158+
| 토스뱅크 | 교통비 **2,000원 추가 캐시백** | 월 교통비 4만 원 이상 | 결제 계좌 입금 |
159+
| 케이뱅크 | 교통비 **3,000원 추가 캐시백** | 전월 실적 30만 원 이상 + 전월 대중교통비 5만 원 이상 | 계좌 입금 |
160+
| 카카오페이 | 교통비 **10% 추가 충전쿠폰** | 전월 모바일교통카드 이용금액 10만/20만/30만 원 이상 시 최대 2천/5천/7천 원 | 앱 쿠폰함 지급 후 충전 |
161+
162+
> 위 혜택은 상품 부가서비스/프로모션 성격이므로
163+
> `K-패스 기본 환급`과 별도 합산 라인으로 보여줘야 한다.
164+
> 조건·한도·종료일은 수시 변경 가능하므로 출처와 유효기간을 함께 저장한다.
165+
166+
---
167+
168+
## 4. 기후동행카드 개요
169+
170+
> **기준 시점**: 2026-04-13 서울시 안내 기준
171+
172+
| 항목 | 내용 |
173+
|------|------|
174+
| 이용 가능 지역 | 서울지역 지하철 + 일부 수도권 구간, 서울시 면허 시내·마을버스, 따릉이, 한강버스 |
175+
| 기본 30일권 | 62,000원 (대중교통), 65,000원 (따릉이 포함) |
176+
| 확장 30일권 | 67,000원 (한강버스 포함), 70,000원 (따릉이+한강버스 포함) |
177+
| 할인 30일권 | 청소년·청년(만 13~39세), 다자녀, 저소득 할인 권종 운영 |
178+
| 단기권 | 1/2/3/5/7일권 운영 |
179+
| 정산 방식 | 월정액 선불 충전, 횟수 무제한 |
180+
| 분석 목표 | 선택 권종 대비 실제 교통비 절감액과 손익분기점 분석 |
181+
182+
> 2026년 4월부터 권종과 할인 체계가 넓어져
183+
> 단순 `62,000 / 65,000` 2종만 가정하면 실제 사용 패턴을 제대로 반영하기 어렵다.
184+
185+
손익분기점 계산:
186+
```
187+
실제_이용_건수 × 건당_평균_요금 > 월정액
188+
→ 이득 (절감액 표시)
189+
→ 손해 (미달액 표시)
190+
```
191+
192+
---
193+
194+
## 5. Suica / PASMO (일본 IC카드) 개요
195+
196+
| 항목 | 내용 |
197+
|------|------|
198+
| 유형 | 선불 IC카드 |
199+
| 정산 방식 | 충전(top-up) → 차감 방식 |
200+
| 추적 목표 | 충전 금액을 Ledger 지출로 기록, 잔액 추적 |
201+
| 환율 | JPY → KRW 변환 (기존 환율 시스템 활용) |
202+
203+
> 잔액 직접 조회 API 없음. 수동 입력 또는 충전 내역 기반 추산.
204+
205+
---
206+
207+
## 6. 기간제 패스 (Pass)
208+
209+
JR 패스, 도쿄 메트로 패스 등 기간 한정 교통패스.
210+
211+
| 항목 | 내용 |
212+
|------|------|
213+
| 입력 정보 | 패스명, 구매금액, 유효기간 (시작~종료일) |
214+
| 분석 목표 | 기간 내 실제 이용 노선/금액 vs 패스 비용 비교 |
215+
| 통화 | 다중 통화 지원 (환율 시스템 연동) |
216+
217+
---
218+
219+
## 7. Ledger 연동 방식
220+
221+
교통비 관리는 독립 데이터를 갖되, **Ledger Entry와 양방향 연동**한다.
222+
223+
```
224+
교통카드 등록
225+
↓
226+
Ledger에 지출 추가 시 결제수단으로 교통카드 선택
227+
↓
228+
교통비 관리 탭에서 해당 월 항목 자동 집계
229+
↓
230+
K-패스 환급 + 상품 추가 혜택 예상액 계산
231+
↓
232+
[환급 등록] 버튼 → Ledger에 수입 항목 자동 생성
233+
(카테고리: "교통비 환급", 금액: 계산된 환급액)
234+
```
235+
236+
새 결제수단 타입 추가: `transit_card` (`other`를 대체하지 않고 별도 타입으로 추가)
237+
238+
---
239+
240+
## 8. 관련 문서
241+
242+
- [01-data-model.md](./01-data-model.md) — DB 스키마 및 타입 정의
243+
- [02-api-design.md](./02-api-design.md) — API 엔드포인트
244+
- [03-ui-design.md](./03-ui-design.md) — UI/UX 설계
245+
- [04-implementation-plan.md](./04-implementation-plan.md) — 구현 단계별 계획

0 commit comments

Comments
 (0)