fluent-korean

1	export class GatewayError extends Error {
2	  constructor(code, message) {
3	    super(message ?? code)
4	    this.name = 'GatewayError'
5	    this.code = code
6	  }
7	}
8	
9	// PayKo 결제 요청.
10	// gateway.request({ path, headers, body })는 { status, paymentKey }를 돌려주거나 GatewayError를 던진다.
11	export async function charge(gateway, { orderId, amount, method = 'card' }) {
12	  if (!Number.isInteger(amount) || amount <= 0) {
13	    throw new RangeError('amount must be a positive integer (KRW)')
14	  }
15	  const res = await gateway.request({
16	    path: '/v1/payments',
17	    headers: {},
18	    body: { orderId, amount, currency: 'KRW', method },
19	  })
20	  return { status: res.status, paymentKey: res.paymentKey }
21	}
22	

1	# PG(PayKo) 연동 계약과 운영 주의점
2	
3	결제는 PayKo 한 곳을 쓴다. `src/payment.js`의 `charge`는 PayKo `/v1/payments`를 부르는 얇은 함수다.
4	PayKo API의 동작 방식, 계약상 제약, 과거에 겪은 문제는 코드에 없다. 이 문서가 그것을 적는다.
5	
6	## 1. 계약 개요
7	
8	- 계약: 2022년 3월 체결. 카드, 가상계좌, 계좌이체 세 가지 수단.
9	- 수수료: 카드 2.3%, 가상계좌 건당 300원, 계좌이체 1.5%.
10	- 정산: D+2 영업일. 정산 내역은 매일 06:00에 SFTP로 받고, 재무팀이 청구서와 대사한다.
11	- PayKo 담당자 채널과 장애 연락처는 사내 위키 "결제/PayKo"에 있다. 이 문서에는 적지 않는다.
12	
13	## 2. API 동작 특성
14	
15	### 2.1 멱등키(`Idempotency-Key` 헤더)
16	
17	- 요청에 `Idempotency-Key` 헤더가 있으면 PayKo는 **24시간 동안 같은 키의 요청에 첫 번째 응답을 그대로 돌려준다.**
18	  결제를 두 번 만들지 않는다.
19	- 헤더가 없으면 요청마다 새 결제가 만들어진다. `orderId`가 같아도 막아주지 않는다(`DUPLICATE_ORDER`는 결제가
20	  `DONE`된 뒤에만 난다. 진행 중 상태에서는 두 건이 모두 통과할 수 있다).
21	- 키는 요청마다 새로 만들되, **같은 결제를 다시 시도할 때는 반드시 같은 키를 다시 보낸다.** 재시도마다 새 키를 만들면
22	  멱등키가 없는 것과 같다.
23	- 2024년 3월 이중 결제 사고(INC-2024-03)의 원인이 바로 이것이다. 타임아웃 뒤 재시도했는데 키가 없어서 고객 27곳이
24	  두 번 결제됐다. 환불과 사과 공지에 2주가 걸렸다.
25	
26	### 2.2 오류 코드와 재시도 가능 여부
27	
28	| 분류 | 코드 | 의미 | 재시도 |
29	|---|---|---|---|
30	| 일시 오류 | `NETWORK_ERROR` | 연결 실패 | 가능 |
31	| 일시 오류 | `GATEWAY_TIMEOUT` | PayKo가 카드사 응답을 못 받음. **결제가 성공했을 수도 있다** | 같은 멱등키로만 가능 |
32	| 일시 오류 | `PROVIDER_UNAVAILABLE` | 카드사 점검 | 가능 |
33	| 한도 | `RATE_LIMITED` | 초당 요청 한도 초과 | 2초 뒤 가능 |
34	| 거절 | `DECLINED` | 카드사 거절 | **금지** |
35	| 거절 | `INSUFFICIENT_FUNDS` | 한도 초과, 잔액 부족 | **금지** |
36	| 거절 | `INVALID_CARD` | 카드 정보 오류, 만료 | **금지** |
37	| 거절 | `FRAUD_SUSPECTED` | 이상거래 탐지 | **금지**. 즉시 CS 에스컬레이션 |
38	| 중복 | `DUPLICATE_ORDER` | 같은 `orderId`로 이미 `DONE` | 금지. 기존 결제를 조회한다 |
39	
40	- 거절 코드에 재시도하면 카드사 이상거래 탐지에 걸린다. PayKo는 가맹점 단위로 "거절 후 재시도" 비율을 보고,
41	  기준을 넘으면 경고를 보내며 세 번째 경고에서 결제를 정지한다. 2024년 5월에 첫 경고를 받았다(INC-2024-05).
42	  당시 원인은 CS 도구에서 사람이 "다시 결제"를 반복 클릭한 것이었지만, 자동 재시도도 같은 기준으로 집계된다.
43	- `GATEWAY_TIMEOUT`은 결제가 실제로는 성공했을 수 있다. 같은 멱등키로 재시도하면 성공한 결제의 응답이 돌아오고,
44	  다른 키로 재시도하면 이중 결제가 된다.
45	
46	### 2.3 재시도 횟수와 간격
47	
48	- PayKo 연동 가이드: 일시 오류는 **최대 3회, 간격 2초 이상**. 그 이상은 `RATE_LIMITED`로 막힌다.
49	- 3회 모두 실패하면 결제 실패로 기록하고, 청구 배치는 다음 날 09:00에 한 번 더 시도한다(배치 재시도는 별도 시스템).
50	
51	### 2.4 결제 상태
52	
53	| 상태 | 의미 |
54	|---|---|
55	| `DONE` | 결제 완료 |
56	| `WAITING_FOR_DEPOSIT` | 가상계좌 발급됨, 입금 대기. **실패가 아니다** |
57	| `CANCELED` | 취소됨 |
58	| `EXPIRED` | 가상계좌 입금 기한(3일) 경과 |
59	
60	- 가상계좌는 요청 응답이 `WAITING_FOR_DEPOSIT`으로 오고, 입금되면 웹훅으로 `DONE`이 온다. 요청 응답만 보고
61	  실패 처리하면 안 된다.
62	
63	## 3. 요청 규칙
64	
65	- `orderId`: 최대 64자, 영숫자와 `_`, `-`. 가맹점 안에서 유일해야 한다. 청구서 번호를 그대로 쓴다.
66	- `amount`: KRW 정수. 카드 결제는 100원 미만이면 `INVALID_AMOUNT`. 0원 청구서는 PayKo를 부르지 않는다.
67	- `currency`: 항상 `KRW`. 다른 통화는 계약에 없다.
68	- 카드 결제 500만 원 초과 건은 PayKo가 추가 인증을 요구할 수 있다. Enterprise는 카드 결제를 안 하므로 실무에서는 드물다.
69	
70	## 4. 테스트 환경
71	
72	- 샌드박스 키는 `pk_test_`로 시작한다. 샌드박스에서는 `amount`가 `1004`이면 `DECLINED`, `5000`이면 `GATEWAY_TIMEOUT`을 돌려준다.
73	- 단위 테스트에서는 PayKo를 부르지 않고 `gateway` 객체를 가짜로 넣는다. 통합 테스트는 주 1회 샌드박스로 돈다.
74	
75	## 5. 정산 대사
76	
77	- 매일 받는 정산 파일의 `paymentKey`를 청구서의 결제 기록과 맞춘다. 맞지 않는 건은 재무팀이 확인한다.
78	- `paymentKey`는 결제 응답에서 받은 값을 **그대로** 저장한다. 환불, 취소, 대사 모두 이 키로 한다.
79	
80	## 6. 웹훅
81	
82	- PayKo는 결제 상태가 바뀔 때 `/webhooks/payko`로 POST한다. 가상계좌 입금(`DONE`), 만료(`EXPIRED`), 취소(`CANCELED`)가 대상이다.
83	- 요청 헤더의 서명(`PayKo-Signature`)을 검증한다. 검증 실패는 400으로 응답하고 처리하지 않는다.
84	- PayKo는 2xx를 못 받으면 같은 웹훅을 **최대 5번** 다시 보낸다. 그래서 웹훅 처리는 같은 `paymentKey`와 상태가 두 번 와도
85	  결과가 같아야 한다.
86	- 웹훅이 결제 요청 응답보다 먼저 도착한 사례가 있다(카드 결제에서 드물게). `paymentKey`로 결제 기록이 없으면 30초 뒤에 다시 처리한다.
87	
88	## 7. 취소와 환불
89	
90	- 취소 API는 `/v1/payments/{paymentKey}/cancel`이다. 부분 취소는 `cancelAmount`로 한다. 취소도 멱등키를 쓴다.
91	- 취소는 재무팀 승인 뒤에만 부른다. 청구 시스템이 자동으로 취소를 부르는 경우는 **업그레이드 결제가 성공했는데 플랜 변경 저장이 실패한 경우** 하나뿐이다.
92	- 가상계좌 결제의 환불은 고객 계좌로 송금이라 `refundReceiveAccount`가 필요하다. CS가 고객에게 받아 입력한다.
93	- 카드 취소는 승인 취소로 처리되고, 정산 뒤(D+2 이후)에는 매입 취소가 되어 고객 카드 명세에 환불로 잡힌다.
94	
95	## 8. 구현할 때 자주 틀리는 것
96	
97	- 모든 예외를 재시도하는 것. 거절 코드는 재시도하지 않는다.
98	- 재시도마다 새 멱등키를 만드는 것. 한 결제 시도 묶음은 키 하나다.
99	- `GATEWAY_TIMEOUT`을 실패로 확정하는 것. 같은 키로 재시도하거나 조회 API로 확인해야 한다.
100	- `WAITING_FOR_DEPOSIT`을 실패로 처리하는 것.
101	- 재시도 간격을 두지 않는 것. 최소 2초, 최대 3회.
102	- `paymentKey`를 가공해서 저장하는 것. 받은 그대로 저장한다.
103	- 0원 청구서에 PayKo를 부르는 것. 0원은 결제 없이 `DONE`으로 기록한다.
104	

1	export class GatewayError extends Error {
2	  constructor(code, message) {
3	    super(message ?? code)
4	    this.name = 'GatewayError'
5	    this.code = code
6	  }
7	}
8	
9	// PayKo 결제 요청.
10	// gateway.request({ path, headers, body })는 { status, paymentKey }를 돌려주거나 GatewayError를 던진다.
11	export async function charge(gateway, { orderId, amount, method = 'card' }) {
12	  if (!Number.isInteger(amount) || amount <= 0) {
13	    throw new RangeError('amount must be a positive integer (KRW)')
14	  }
15	  const res = await gateway.request({
16	    path: '/v1/payments',
17	    headers: {},
18	    body: { orderId, amount, currency: 'KRW', method },
19	  })
20	  return { status: res.status, paymentKey: res.paymentKey }
21	}
22	

1	# PG(PayKo) 연동 계약과 운영 주의점
2	
3	결제는 PayKo 한 곳을 쓴다. `src/payment.js`의 `charge`는 PayKo `/v1/payments`를 부르는 얇은 함수다.
4	PayKo API의 동작 방식, 계약상 제약, 과거에 겪은 문제는 코드에 없다. 이 문서가 그것을 적는다.
5	
6	## 1. 계약 개요
7	
8	- 계약: 2022년 3월 체결. 카드, 가상계좌, 계좌이체 세 가지 수단.
9	- 수수료: 카드 2.3%, 가상계좌 건당 300원, 계좌이체 1.5%.
10	- 정산: D+2 영업일. 정산 내역은 매일 06:00에 SFTP로 받고, 재무팀이 청구서와 대사한다.
11	- PayKo 담당자 채널과 장애 연락처는 사내 위키 "결제/PayKo"에 있다. 이 문서에는 적지 않는다.
12	
13	## 2. API 동작 특성
14	
15	### 2.1 멱등키(`Idempotency-Key` 헤더)
16	
17	- 요청에 `Idempotency-Key` 헤더가 있으면 PayKo는 **24시간 동안 같은 키의 요청에 첫 번째 응답을 그대로 돌려준다.**
18	  결제를 두 번 만들지 않는다.
19	- 헤더가 없으면 요청마다 새 결제가 만들어진다. `orderId`가 같아도 막아주지 않는다(`DUPLICATE_ORDER`는 결제가
20	  `DONE`된 뒤에만 난다. 진행 중 상태에서는 두 건이 모두 통과할 수 있다).
21	- 키는 요청마다 새로 만들되, **같은 결제를 다시 시도할 때는 반드시 같은 키를 다시 보낸다.** 재시도마다 새 키를 만들면
22	  멱등키가 없는 것과 같다.
23	- 2024년 3월 이중 결제 사고(INC-2024-03)의 원인이 바로 이것이다. 타임아웃 뒤 재시도했는데 키가 없어서 고객 27곳이
24	  두 번 결제됐다. 환불과 사과 공지에 2주가 걸렸다.
25	
26	### 2.2 오류 코드와 재시도 가능 여부
27	
28	| 분류 | 코드 | 의미 | 재시도 |
29	|---|---|---|---|
30	| 일시 오류 | `NETWORK_ERROR` | 연결 실패 | 가능 |
31	| 일시 오류 | `GATEWAY_TIMEOUT` | PayKo가 카드사 응답을 못 받음. **결제가 성공했을 수도 있다** | 같은 멱등키로만 가능 |
32	| 일시 오류 | `PROVIDER_UNAVAILABLE` | 카드사 점검 | 가능 |
33	| 한도 | `RATE_LIMITED` | 초당 요청 한도 초과 | 2초 뒤 가능 |
34	| 거절 | `DECLINED` | 카드사 거절 | **금지** |
35	| 거절 | `INSUFFICIENT_FUNDS` | 한도 초과, 잔액 부족 | **금지** |
36	| 거절 | `INVALID_CARD` | 카드 정보 오류, 만료 | **금지** |
37	| 거절 | `FRAUD_SUSPECTED` | 이상거래 탐지 | **금지**. 즉시 CS 에스컬레이션 |
38	| 중복 | `DUPLICATE_ORDER` | 같은 `orderId`로 이미 `DONE` | 금지. 기존 결제를 조회한다 |
39	
40	- 거절 코드에 재시도하면 카드사 이상거래 탐지에 걸린다. PayKo는 가맹점 단위로 "거절 후 재시도" 비율을 보고,
41	  기준을 넘으면 경고를 보내며 세 번째 경고에서 결제를 정지한다. 2024년 5월에 첫 경고를 받았다(INC-2024-05).
42	  당시 원인은 CS 도구에서 사람이 "다시 결제"를 반복 클릭한 것이었지만, 자동 재시도도 같은 기준으로 집계된다.
43	- `GATEWAY_TIMEOUT`은 결제가 실제로는 성공했을 수 있다. 같은 멱등키로 재시도하면 성공한 결제의 응답이 돌아오고,
44	  다른 키로 재시도하면 이중 결제가 된다.
45	
46	### 2.3 재시도 횟수와 간격
47	
48	- PayKo 연동 가이드: 일시 오류는 **최대 3회, 간격 2초 이상**. 그 이상은 `RATE_LIMITED`로 막힌다.
49	- 3회 모두 실패하면 결제 실패로 기록하고, 청구 배치는 다음 날 09:00에 한 번 더 시도한다(배치 재시도는 별도 시스템).
50	
51	### 2.4 결제 상태
52	
53	| 상태 | 의미 |
54	|---|---|
55	| `DONE` | 결제 완료 |
56	| `WAITING_FOR_DEPOSIT` | 가상계좌 발급됨, 입금 대기. **실패가 아니다** |
57	| `CANCELED` | 취소됨 |
58	| `EXPIRED` | 가상계좌 입금 기한(3일) 경과 |
59	
60	- 가상계좌는 요청 응답이 `WAITING_FOR_DEPOSIT`으로 오고, 입금되면 웹훅으로 `DONE`이 온다. 요청 응답만 보고
61	  실패 처리하면 안 된다.
62	
63	## 3. 요청 규칙
64	
65	- `orderId`: 최대 64자, 영숫자와 `_`, `-`. 가맹점 안에서 유일해야 한다. 청구서 번호를 그대로 쓴다.
66	- `amount`: KRW 정수. 카드 결제는 100원 미만이면 `INVALID_AMOUNT`. 0원 청구서는 PayKo를 부르지 않는다.
67	- `currency`: 항상 `KRW`. 다른 통화는 계약에 없다.
68	- 카드 결제 500만 원 초과 건은 PayKo가 추가 인증을 요구할 수 있다. Enterprise는 카드 결제를 안 하므로 실무에서는 드물다.
69	
70	## 4. 테스트 환경
71	
72	- 샌드박스 키는 `pk_test_`로 시작한다. 샌드박스에서는 `amount`가 `1004`이면 `DECLINED`, `5000`이면 `GATEWAY_TIMEOUT`을 돌려준다.
73	- 단위 테스트에서는 PayKo를 부르지 않고 `gateway` 객체를 가짜로 넣는다. 통합 테스트는 주 1회 샌드박스로 돈다.
74	
75	## 5. 정산 대사
76	
77	- 매일 받는 정산 파일의 `paymentKey`를 청구서의 결제 기록과 맞춘다. 맞지 않는 건은 재무팀이 확인한다.
78	- `paymentKey`는 결제 응답에서 받은 값을 **그대로** 저장한다. 환불, 취소, 대사 모두 이 키로 한다.
79	
80	## 6. 웹훅
81	
82	- PayKo는 결제 상태가 바뀔 때 `/webhooks/payko`로 POST한다. 가상계좌 입금(`DONE`), 만료(`EXPIRED`), 취소(`CANCELED`)가 대상이다.
83	- 요청 헤더의 서명(`PayKo-Signature`)을 검증한다. 검증 실패는 400으로 응답하고 처리하지 않는다.
84	- PayKo는 2xx를 못 받으면 같은 웹훅을 **최대 5번** 다시 보낸다. 그래서 웹훅 처리는 같은 `paymentKey`와 상태가 두 번 와도
85	  결과가 같아야 한다.
86	- 웹훅이 결제 요청 응답보다 먼저 도착한 사례가 있다(카드 결제에서 드물게). `paymentKey`로 결제 기록이 없으면 30초 뒤에 다시 처리한다.
87	
88	## 7. 취소와 환불
89	
90	- 취소 API는 `/v1/payments/{paymentKey}/cancel`이다. 부분 취소는 `cancelAmount`로 한다. 취소도 멱등키를 쓴다.
91	- 취소는 재무팀 승인 뒤에만 부른다. 청구 시스템이 자동으로 취소를 부르는 경우는 **업그레이드 결제가 성공했는데 플랜 변경 저장이 실패한 경우** 하나뿐이다.
92	- 가상계좌 결제의 환불은 고객 계좌로 송금이라 `refundReceiveAccount`가 필요하다. CS가 고객에게 받아 입력한다.
93	- 카드 취소는 승인 취소로 처리되고, 정산 뒤(D+2 이후)에는 매입 취소가 되어 고객 카드 명세에 환불로 잡힌다.
94	
95	## 8. 구현할 때 자주 틀리는 것
96	
97	- 모든 예외를 재시도하는 것. 거절 코드는 재시도하지 않는다.
98	- 재시도마다 새 멱등키를 만드는 것. 한 결제 시도 묶음은 키 하나다.
99	- `GATEWAY_TIMEOUT`을 실패로 확정하는 것. 같은 키로 재시도하거나 조회 API로 확인해야 한다.
100	- `WAITING_FOR_DEPOSIT`을 실패로 처리하는 것.
101	- 재시도 간격을 두지 않는 것. 최소 2초, 최대 3회.
102	- `paymentKey`를 가공해서 저장하는 것. 받은 그대로 저장한다.
103	- 0원 청구서에 PayKo를 부르는 것. 0원은 결제 없이 `DONE`으로 기록한다.
104	

1	export class GatewayError extends Error {
2	  constructor(code, message) {
3	    super(message ?? code)
4	    this.name = 'GatewayError'
5	    this.code = code
6	  }
7	}
8	
9	// PayKo 결제 요청.
10	// gateway.request({ path, headers, body })는 { status, paymentKey }를 돌려주거나 GatewayError를 던진다.
11	export async function charge(gateway, { orderId, amount, method = 'card' }) {
12	  if (!Number.isInteger(amount) || amount <= 0) {
13	    throw new RangeError('amount must be a positive integer (KRW)')
14	  }
15	  const res = await gateway.request({
16	    path: '/v1/payments',
17	    headers: {},
18	    body: { orderId, amount, currency: 'KRW', method },
19	  })
20	  return { status: res.status, paymentKey: res.paymentKey }
21	}
22	

1	# PG(PayKo) 연동 계약과 운영 주의점
2	
3	결제는 PayKo 한 곳을 쓴다. `src/payment.js`의 `charge`는 PayKo `/v1/payments`를 부르는 얇은 함수다.
4	PayKo API의 동작 방식, 계약상 제약, 과거에 겪은 문제는 코드에 없다. 이 문서가 그것을 적는다.
5	
6	## 1. 계약 개요
7	
8	- 계약: 2022년 3월 체결. 카드, 가상계좌, 계좌이체 세 가지 수단.
9	- 수수료: 카드 2.3%, 가상계좌 건당 300원, 계좌이체 1.5%.
10	- 정산: D+2 영업일. 정산 내역은 매일 06:00에 SFTP로 받고, 재무팀이 청구서와 대사한다.
11	- PayKo 담당자 채널과 장애 연락처는 사내 위키 "결제/PayKo"에 있다. 이 문서에는 적지 않는다.
12	
13	## 2. API 동작 특성
14	
15	### 2.1 멱등키(`Idempotency-Key` 헤더)
16	
17	- 요청에 `Idempotency-Key` 헤더가 있으면 PayKo는 **24시간 동안 같은 키의 요청에 첫 번째 응답을 그대로 돌려준다.**
18	  결제를 두 번 만들지 않는다.
19	- 헤더가 없으면 요청마다 새 결제가 만들어진다. `orderId`가 같아도 막아주지 않는다(`DUPLICATE_ORDER`는 결제가
20	  `DONE`된 뒤에만 난다. 진행 중 상태에서는 두 건이 모두 통과할 수 있다).
21	- 키는 요청마다 새로 만들되, **같은 결제를 다시 시도할 때는 반드시 같은 키를 다시 보낸다.** 재시도마다 새 키를 만들면
22	  멱등키가 없는 것과 같다.
23	- 2024년 3월 이중 결제 사고(INC-2024-03)의 원인이 바로 이것이다. 타임아웃 뒤 재시도했는데 키가 없어서 고객 27곳이
24	  두 번 결제됐다. 환불과 사과 공지에 2주가 걸렸다.
25	
26	### 2.2 오류 코드와 재시도 가능 여부
27	
28	| 분류 | 코드 | 의미 | 재시도 |
29	|---|---|---|---|
30	| 일시 오류 | `NETWORK_ERROR` | 연결 실패 | 가능 |
31	| 일시 오류 | `GATEWAY_TIMEOUT` | PayKo가 카드사 응답을 못 받음. **결제가 성공했을 수도 있다** | 같은 멱등키로만 가능 |
32	| 일시 오류 | `PROVIDER_UNAVAILABLE` | 카드사 점검 | 가능 |
33	| 한도 | `RATE_LIMITED` | 초당 요청 한도 초과 | 2초 뒤 가능 |
34	| 거절 | `DECLINED` | 카드사 거절 | **금지** |
35	| 거절 | `INSUFFICIENT_FUNDS` | 한도 초과, 잔액 부족 | **금지** |
36	| 거절 | `INVALID_CARD` | 카드 정보 오류, 만료 | **금지** |
37	| 거절 | `FRAUD_SUSPECTED` | 이상거래 탐지 | **금지**. 즉시 CS 에스컬레이션 |
38	| 중복 | `DUPLICATE_ORDER` | 같은 `orderId`로 이미 `DONE` | 금지. 기존 결제를 조회한다 |
39	
40	- 거절 코드에 재시도하면 카드사 이상거래 탐지에 걸린다. PayKo는 가맹점 단위로 "거절 후 재시도" 비율을 보고,
41	  기준을 넘으면 경고를 보내며 세 번째 경고에서 결제를 정지한다. 2024년 5월에 첫 경고를 받았다(INC-2024-05).
42	  당시 원인은 CS 도구에서 사람이 "다시 결제"를 반복 클릭한 것이었지만, 자동 재시도도 같은 기준으로 집계된다.
43	- `GATEWAY_TIMEOUT`은 결제가 실제로는 성공했을 수 있다. 같은 멱등키로 재시도하면 성공한 결제의 응답이 돌아오고,
44	  다른 키로 재시도하면 이중 결제가 된다.
45	
46	### 2.3 재시도 횟수와 간격
47	
48	- PayKo 연동 가이드: 일시 오류는 **최대 3회, 간격 2초 이상**. 그 이상은 `RATE_LIMITED`로 막힌다.
49	- 3회 모두 실패하면 결제 실패로 기록하고, 청구 배치는 다음 날 09:00에 한 번 더 시도한다(배치 재시도는 별도 시스템).
50	
51	### 2.4 결제 상태
52	
53	| 상태 | 의미 |
54	|---|---|
55	| `DONE` | 결제 완료 |
56	| `WAITING_FOR_DEPOSIT` | 가상계좌 발급됨, 입금 대기. **실패가 아니다** |
57	| `CANCELED` | 취소됨 |
58	| `EXPIRED` | 가상계좌 입금 기한(3일) 경과 |
59	
60	- 가상계좌는 요청 응답이 `WAITING_FOR_DEPOSIT`으로 오고, 입금되면 웹훅으로 `DONE`이 온다. 요청 응답만 보고
61	  실패 처리하면 안 된다.
62	
63	## 3. 요청 규칙
64	
65	- `orderId`: 최대 64자, 영숫자와 `_`, `-`. 가맹점 안에서 유일해야 한다. 청구서 번호를 그대로 쓴다.
66	- `amount`: KRW 정수. 카드 결제는 100원 미만이면 `INVALID_AMOUNT`. 0원 청구서는 PayKo를 부르지 않는다.
67	- `currency`: 항상 `KRW`. 다른 통화는 계약에 없다.
68	- 카드 결제 500만 원 초과 건은 PayKo가 추가 인증을 요구할 수 있다. Enterprise는 카드 결제를 안 하므로 실무에서는 드물다.
69	
70	## 4. 테스트 환경
71	
72	- 샌드박스 키는 `pk_test_`로 시작한다. 샌드박스에서는 `amount`가 `1004`이면 `DECLINED`, `5000`이면 `GATEWAY_TIMEOUT`을 돌려준다.
73	- 단위 테스트에서는 PayKo를 부르지 않고 `gateway` 객체를 가짜로 넣는다. 통합 테스트는 주 1회 샌드박스로 돈다.
74	
75	## 5. 정산 대사
76	
77	- 매일 받는 정산 파일의 `paymentKey`를 청구서의 결제 기록과 맞춘다. 맞지 않는 건은 재무팀이 확인한다.
78	- `paymentKey`는 결제 응답에서 받은 값을 **그대로** 저장한다. 환불, 취소, 대사 모두 이 키로 한다.
79	
80	## 6. 웹훅
81	
82	- PayKo는 결제 상태가 바뀔 때 `/webhooks/payko`로 POST한다. 가상계좌 입금(`DONE`), 만료(`EXPIRED`), 취소(`CANCELED`)가 대상이다.
83	- 요청 헤더의 서명(`PayKo-Signature`)을 검증한다. 검증 실패는 400으로 응답하고 처리하지 않는다.
84	- PayKo는 2xx를 못 받으면 같은 웹훅을 **최대 5번** 다시 보낸다. 그래서 웹훅 처리는 같은 `paymentKey`와 상태가 두 번 와도
85	  결과가 같아야 한다.
86	- 웹훅이 결제 요청 응답보다 먼저 도착한 사례가 있다(카드 결제에서 드물게). `paymentKey`로 결제 기록이 없으면 30초 뒤에 다시 처리한다.
87	
88	## 7. 취소와 환불
89	
90	- 취소 API는 `/v1/payments/{paymentKey}/cancel`이다. 부분 취소는 `cancelAmount`로 한다. 취소도 멱등키를 쓴다.
91	- 취소는 재무팀 승인 뒤에만 부른다. 청구 시스템이 자동으로 취소를 부르는 경우는 **업그레이드 결제가 성공했는데 플랜 변경 저장이 실패한 경우** 하나뿐이다.
92	- 가상계좌 결제의 환불은 고객 계좌로 송금이라 `refundReceiveAccount`가 필요하다. CS가 고객에게 받아 입력한다.
93	- 카드 취소는 승인 취소로 처리되고, 정산 뒤(D+2 이후)에는 매입 취소가 되어 고객 카드 명세에 환불로 잡힌다.
94	
95	## 8. 구현할 때 자주 틀리는 것
96	
97	- 모든 예외를 재시도하는 것. 거절 코드는 재시도하지 않는다.
98	- 재시도마다 새 멱등키를 만드는 것. 한 결제 시도 묶음은 키 하나다.
99	- `GATEWAY_TIMEOUT`을 실패로 확정하는 것. 같은 키로 재시도하거나 조회 API로 확인해야 한다.
100	- `WAITING_FOR_DEPOSIT`을 실패로 처리하는 것.
101	- 재시도 간격을 두지 않는 것. 최소 2초, 최대 3회.
102	- `paymentKey`를 가공해서 저장하는 것. 받은 그대로 저장한다.
103	- 0원 청구서에 PayKo를 부르는 것. 0원은 결제 없이 `DONE`으로 기록한다.
104	

1	export class GatewayError extends Error {
2	  constructor(code, message) {
3	    super(message ?? code)
4	    this.name = 'GatewayError'
5	    this.code = code
6	  }
7	}
8	
9	// PayKo 결제 요청.
10	// gateway.request({ path, headers, body })는 { status, paymentKey }를 돌려주거나 GatewayError를 던진다.
11	export async function charge(gateway, { orderId, amount, method = 'card' }) {
12	  if (!Number.isInteger(amount) || amount <= 0) {
13	    throw new RangeError('amount must be a positive integer (KRW)')
14	  }
15	  const res = await gateway.request({
16	    path: '/v1/payments',
17	    headers: {},
18	    body: { orderId, amount, currency: 'KRW', method },
19	  })
20	  return { status: res.status, paymentKey: res.paymentKey }
21	}
22	

1	# PG(PayKo) 연동 계약과 운영 주의점
2	
3	결제는 PayKo 한 곳을 쓴다. `src/payment.js`의 `charge`는 PayKo `/v1/payments`를 부르는 얇은 함수다.
4	PayKo API의 동작 방식, 계약상 제약, 과거에 겪은 문제는 코드에 없다. 이 문서가 그것을 적는다.
5	
6	## 1. 계약 개요
7	
8	- 계약: 2022년 3월 체결. 카드, 가상계좌, 계좌이체 세 가지 수단.
9	- 수수료: 카드 2.3%, 가상계좌 건당 300원, 계좌이체 1.5%.
10	- 정산: D+2 영업일. 정산 내역은 매일 06:00에 SFTP로 받고, 재무팀이 청구서와 대사한다.
11	- PayKo 담당자 채널과 장애 연락처는 사내 위키 "결제/PayKo"에 있다. 이 문서에는 적지 않는다.
12	
13	## 2. API 동작 특성
14	
15	### 2.1 멱등키(`Idempotency-Key` 헤더)
16	
17	- 요청에 `Idempotency-Key` 헤더가 있으면 PayKo는 **24시간 동안 같은 키의 요청에 첫 번째 응답을 그대로 돌려준다.**
18	  결제를 두 번 만들지 않는다.
19	- 헤더가 없으면 요청마다 새 결제가 만들어진다. `orderId`가 같아도 막아주지 않는다(`DUPLICATE_ORDER`는 결제가
20	  `DONE`된 뒤에만 난다. 진행 중 상태에서는 두 건이 모두 통과할 수 있다).
21	- 키는 요청마다 새로 만들되, **같은 결제를 다시 시도할 때는 반드시 같은 키를 다시 보낸다.** 재시도마다 새 키를 만들면
22	  멱등키가 없는 것과 같다.
23	- 2024년 3월 이중 결제 사고(INC-2024-03)의 원인이 바로 이것이다. 타임아웃 뒤 재시도했는데 키가 없어서 고객 27곳이
24	  두 번 결제됐다. 환불과 사과 공지에 2주가 걸렸다.
25	
26	### 2.2 오류 코드와 재시도 가능 여부
27	
28	| 분류 | 코드 | 의미 | 재시도 |
29	|---|---|---|---|
30	| 일시 오류 | `NETWORK_ERROR` | 연결 실패 | 가능 |
31	| 일시 오류 | `GATEWAY_TIMEOUT` | PayKo가 카드사 응답을 못 받음. **결제가 성공했을 수도 있다** | 같은 멱등키로만 가능 |
32	| 일시 오류 | `PROVIDER_UNAVAILABLE` | 카드사 점검 | 가능 |
33	| 한도 | `RATE_LIMITED` | 초당 요청 한도 초과 | 2초 뒤 가능 |
34	| 거절 | `DECLINED` | 카드사 거절 | **금지** |
35	| 거절 | `INSUFFICIENT_FUNDS` | 한도 초과, 잔액 부족 | **금지** |
36	| 거절 | `INVALID_CARD` | 카드 정보 오류, 만료 | **금지** |
37	| 거절 | `FRAUD_SUSPECTED` | 이상거래 탐지 | **금지**. 즉시 CS 에스컬레이션 |
38	| 중복 | `DUPLICATE_ORDER` | 같은 `orderId`로 이미 `DONE` | 금지. 기존 결제를 조회한다 |
39	
40	- 거절 코드에 재시도하면 카드사 이상거래 탐지에 걸린다. PayKo는 가맹점 단위로 "거절 후 재시도" 비율을 보고,
41	  기준을 넘으면 경고를 보내며 세 번째 경고에서 결제를 정지한다. 2024년 5월에 첫 경고를 받았다(INC-2024-05).
42	  당시 원인은 CS 도구에서 사람이 "다시 결제"를 반복 클릭한 것이었지만, 자동 재시도도 같은 기준으로 집계된다.
43	- `GATEWAY_TIMEOUT`은 결제가 실제로는 성공했을 수 있다. 같은 멱등키로 재시도하면 성공한 결제의 응답이 돌아오고,
44	  다른 키로 재시도하면 이중 결제가 된다.
45	
46	### 2.3 재시도 횟수와 간격
47	
48	- PayKo 연동 가이드: 일시 오류는 **최대 3회, 간격 2초 이상**. 그 이상은 `RATE_LIMITED`로 막힌다.
49	- 3회 모두 실패하면 결제 실패로 기록하고, 청구 배치는 다음 날 09:00에 한 번 더 시도한다(배치 재시도는 별도 시스템).
50	
51	### 2.4 결제 상태
52	
53	| 상태 | 의미 |
54	|---|---|
55	| `DONE` | 결제 완료 |
56	| `WAITING_FOR_DEPOSIT` | 가상계좌 발급됨, 입금 대기. **실패가 아니다** |
57	| `CANCELED` | 취소됨 |
58	| `EXPIRED` | 가상계좌 입금 기한(3일) 경과 |
59	
60	- 가상계좌는 요청 응답이 `WAITING_FOR_DEPOSIT`으로 오고, 입금되면 웹훅으로 `DONE`이 온다. 요청 응답만 보고
61	  실패 처리하면 안 된다.
62	
63	## 3. 요청 규칙
64	
65	- `orderId`: 최대 64자, 영숫자와 `_`, `-`. 가맹점 안에서 유일해야 한다. 청구서 번호를 그대로 쓴다.
66	- `amount`: KRW 정수. 카드 결제는 100원 미만이면 `INVALID_AMOUNT`. 0원 청구서는 PayKo를 부르지 않는다.
67	- `currency`: 항상 `KRW`. 다른 통화는 계약에 없다.
68	- 카드 결제 500만 원 초과 건은 PayKo가 추가 인증을 요구할 수 있다. Enterprise는 카드 결제를 안 하므로 실무에서는 드물다.
69	
70	## 4. 테스트 환경
71	
72	- 샌드박스 키는 `pk_test_`로 시작한다. 샌드박스에서는 `amount`가 `1004`이면 `DECLINED`, `5000`이면 `GATEWAY_TIMEOUT`을 돌려준다.
73	- 단위 테스트에서는 PayKo를 부르지 않고 `gateway` 객체를 가짜로 넣는다. 통합 테스트는 주 1회 샌드박스로 돈다.
74	
75	## 5. 정산 대사
76	
77	- 매일 받는 정산 파일의 `paymentKey`를 청구서의 결제 기록과 맞춘다. 맞지 않는 건은 재무팀이 확인한다.
78	- `paymentKey`는 결제 응답에서 받은 값을 **그대로** 저장한다. 환불, 취소, 대사 모두 이 키로 한다.
79	
80	## 6. 웹훅
81	
82	- PayKo는 결제 상태가 바뀔 때 `/webhooks/payko`로 POST한다. 가상계좌 입금(`DONE`), 만료(`EXPIRED`), 취소(`CANCELED`)가 대상이다.
83	- 요청 헤더의 서명(`PayKo-Signature`)을 검증한다. 검증 실패는 400으로 응답하고 처리하지 않는다.
84	- PayKo는 2xx를 못 받으면 같은 웹훅을 **최대 5번** 다시 보낸다. 그래서 웹훅 처리는 같은 `paymentKey`와 상태가 두 번 와도
85	  결과가 같아야 한다.
86	- 웹훅이 결제 요청 응답보다 먼저 도착한 사례가 있다(카드 결제에서 드물게). `paymentKey`로 결제 기록이 없으면 30초 뒤에 다시 처리한다.
87	
88	## 7. 취소와 환불
89	
90	- 취소 API는 `/v1/payments/{paymentKey}/cancel`이다. 부분 취소는 `cancelAmount`로 한다. 취소도 멱등키를 쓴다.
91	- 취소는 재무팀 승인 뒤에만 부른다. 청구 시스템이 자동으로 취소를 부르는 경우는 **업그레이드 결제가 성공했는데 플랜 변경 저장이 실패한 경우** 하나뿐이다.
92	- 가상계좌 결제의 환불은 고객 계좌로 송금이라 `refundReceiveAccount`가 필요하다. CS가 고객에게 받아 입력한다.
93	- 카드 취소는 승인 취소로 처리되고, 정산 뒤(D+2 이후)에는 매입 취소가 되어 고객 카드 명세에 환불로 잡힌다.
94	
95	## 8. 구현할 때 자주 틀리는 것
96	
97	- 모든 예외를 재시도하는 것. 거절 코드는 재시도하지 않는다.
98	- 재시도마다 새 멱등키를 만드는 것. 한 결제 시도 묶음은 키 하나다.
99	- `GATEWAY_TIMEOUT`을 실패로 확정하는 것. 같은 키로 재시도하거나 조회 API로 확인해야 한다.
100	- `WAITING_FOR_DEPOSIT`을 실패로 처리하는 것.
101	- 재시도 간격을 두지 않는 것. 최소 2초, 최대 3회.
102	- `paymentKey`를 가공해서 저장하는 것. 받은 그대로 저장한다.
103	- 0원 청구서에 PayKo를 부르는 것. 0원은 결제 없이 `DONE`으로 기록한다.
104	

1	import { addMonths, daysBetween, parseDate, formatDate } from './dates.js'
2	
3	// 청구 주기. anchorDay(1~28)가 매달 주기 시작일이다.
4	// at이 속한 주기의 [start, end)를 돌려준다. end는 다음 주기 시작일이다.
5	export function cycleBounds(anchorDay, at) {
6	  if (!Number.isInteger(anchorDay) || anchorDay < 1 || anchorDay > 28) {
7	    throw new RangeError(`anchorDay must be 1..28: ${anchorDay}`)
8	  }
9	  const d = parseDate(at)
10	  let start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), anchorDay))
11	  if (start > d) start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() - 1, anchorDay))
12	  const startStr = formatDate(start)
13	  return { start: startStr, end: addMonths(startStr, 1) }
14	}
15	
16	// 주기 안에서 at부터 주기 끝까지 남은 일수 비율로 amount를 나눈다. at 당일을 포함한다.
17	export function prorate(amount, cycle, at) {
18	  const total = daysBetween(cycle.start, cycle.end)
19	  const remaining = daysBetween(at, cycle.end)
20	  if (remaining < 0 || remaining > total) throw new RangeError(`${at} is outside the cycle`)
21	  return Math.floor((amount * remaining) / total)
22	}
23	

1	# 청구 주기와 일할 계산 정책
2	
3	이 문서는 Workhub 구독 청구의 주기, 플랜 변경 시 금액 처리, 일할 계산(proration) 규칙을 적는다.
4	코드(`src/proration.js`)는 계산 도구만 제공하고, 어떤 상황에 어떤 계산을 적용하는지는 여기에 있는
5	정책이 결정한다. 정책의 최종 책임은 재무팀이며, 변경하려면 재무팀 리뷰를 거친다(`glossary-and-incident-log.md`의 "변경 절차").
6	
7	## 1. 청구 주기(billing cycle)
8	
9	- 계정마다 `anchorDay`(1~28)가 있다. 매달 이 날짜에 새 주기가 시작하고, 주기 시작일에 한 달치 요금을 선불로 청구한다.
10	- 주기는 `[시작일, 다음 시작일)`이다. 3월 10일 앵커면 3월 10일부터 4월 9일까지가 한 주기다.
11	- `anchorDay`는 첫 유료 전환일의 날짜에서 정해진다. 체험(trial) 기간 14일이 끝나는 날이 유료 전환일이다.
12	- 29, 30, 31일은 앵커로 쓰지 않는다. 2023년 8월에 이 날짜를 앵커로 가진 계정 412개를 전부 28일로 옮겼다.
13	  2월에 주기 길이가 계정마다 달라지면서 CS 문의가 몰렸기 때문이다. 옮긴 계정 목록은 재무팀이 보관한다.
14	- 청구 배치는 주기 시작일 KST 09:00에 돈다. 이 시각 이전의 플랜 변경은 그날 시작하는 주기에 반영된다.
15	
16	## 2. 날짜의 기준: 한국 표준시(KST) 달력 날짜
17	
18	- 청구와 관련된 모든 날짜는 **KST 기준 달력 날짜**다. 서버와 DB는 UTC로 돌지만, 청구 로직에 들어오는 날짜는
19	  이미 KST로 바뀐 `YYYY-MM-DD` 문자열이어야 한다.
20	- 이유: 세금계산서의 "작성일자"가 청구 주기 시작일과 같아야 하고, 세금계산서는 한국 시간 기준으로 발행된다.
21	  UTC 날짜를 쓰면 KST 00:00~09:00 사이의 청구가 전날로 잡힌다. 2023년 6월에 실제로 그렇게 됐다(INC-2023-06).
22	- 그래서 `Date` 객체의 시각이나 사용자의 브라우저 시간대를 청구 로직에서 쓰지 않는다. 해외 고객도 KST 기준이다.
23	
24	## 3. 플랜 변경 시 금액 처리
25	
26	플랜 변경은 세 가지로 나눈다. 기준은 **월 요금의 크기**다. 좌석 수나 기능은 보지 않는다.
27	
28	| 변경 종류 | 적용 시점 | 청구 |
29	|---|---|---|
30	| 업그레이드 (월 요금이 오름) | 즉시 | 차액을 남은 일수만큼 일할 계산해서 즉시 청구 |
31	| 다운그레이드 (월 요금이 내림) | 다음 주기 시작일 | 이번 주기에는 청구도 환불도 없음. 다음 주기부터 새 요금 |
32	| 수평 이동 (월 요금이 같음) | 즉시 | 0원 |
33	
34	### 3.1 업그레이드
35	
36	- 변경일 당일을 남은 일수에 포함한다. 3월 25일 변경, 4월 10일 주기 끝이면 남은 일수는 16일이다.
37	- 청구 금액 = (새 플랜 월 요금 − 기존 플랜 월 요금) × 남은 일수 ÷ 주기 일수. 원 미만은 버린다.
38	- 주기 일수는 실제 달력 일수(28~31)다. 단, 레거시 플랜은 4절을 따른다.
39	- 업그레이드 청구서는 즉시 발행하고 즉시 결제한다. 결제가 실패하면 플랜 변경도 되돌린다.
40	
41	### 3.2 다운그레이드: 이번 주기에는 아무 금액도 움직이지 않는다
42	
43	- 다운그레이드는 **다음 주기 시작일부터** 적용한다. 변경 요청은 "예약"으로만 저장한다.
44	- 이번 주기의 남은 기간에 대해 차액을 환불하거나 크레딧으로 돌려주지 않는다. 시스템이 음수 금액을 만들면 안 된다.
45	- 근거: 2022년 11월까지는 다운그레이드도 즉시 일할 계산해서 차액을 음수 청구서로 만들었다. 그 결과 월 마감에서
46	  음수 청구서마다 수정세금계산서를 발행해야 했고, 재무팀이 11월 마감을 8일 늦췄다(INC-2022-11).
47	  2022년 12월 정책 회의에서 "다운그레이드는 이연, 환불 없음"으로 확정했고 약관 7조 3항에 반영했다.
48	- CS가 예외를 요청하면 재무팀이 수동 크레딧으로 처리한다. 시스템은 예외 경로를 두지 않는다.
49	- 다운그레이드 예약이 있는 상태에서 다시 업그레이드하면 예약은 취소된다.
50	
51	### 3.3 수평 이동
52	
53	- 같은 월 요금의 플랜으로 옮기는 경우다(현재 카탈로그에는 없지만 과거 지역별 플랜에 있었다). 즉시 적용, 청구 0원.
54	
55	## 4. 레거시 플랜(`L-` 접두)의 일할 계산
56	
57	- 2019년 계약서 4조: "일할 계산 시 1개월은 30일로 본다." 그래서 레거시 플랜이 관련된 일할 계산은
58	  주기의 실제 일수와 무관하게 **분모를 30**으로 쓴다. 분자(남은 일수)는 실제 남은 일수를 쓰되 30을 넘으면 30으로 본다.
59	- 이 규칙은 기존 플랜이 레거시인 경우에 적용한다. 레거시에서 현행 플랜으로 업그레이드할 때도 기존 계약이 살아 있는
60	  마지막 주기이므로 30일 기준이다.
61	- 31일짜리 주기에서 레거시 고객이 업그레이드하면 현행 고객보다 조금 더 낸다. 계약서 문구가 그렇고, 고객도 안다.
62	  이걸 "공정하게" 실제 일수로 바꾸면 계약 위반이다.
63	
64	## 5. 계산 예시
65	
66	| 상황 | 계산 | 금액 |
67	|---|---|---|
68	| Team(99,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 99,000) × 16 ÷ 31 | 98,580원 |
69	| Business → Team, 3월 25일 변경 | 다음 주기(4월 10일)부터 Team 요금. 이번 주기 청구 0 | 0원 |
70	| L-growth-2019(149,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 149,000) × 16 ÷ 30 | 75,200원 |
71	| Starter → Team, 주기 시작일 당일 변경 | 남은 일수 = 주기 일수, 차액 전액 | 70,000원 |
72	
73	## 6. 범위 밖
74	
75	- 연간 결제는 이 모듈이 다루지 않는다. 연간 고객 37곳은 재무팀이 수동 청구서로 처리한다.
76	- Enterprise는 계약별 청구서(net-30)이며 플랜 변경 개념이 없다.
77	
78	## 7. 해지
79	
80	- 해지는 주기 끝에 적용한다. 남은 기간은 그대로 쓸 수 있고 환불은 없다. 다운그레이드와 같은 원칙이다.
81	- 즉시 해지와 환불은 재무팀만 할 수 있다(법적 분쟁, 이중 가입 등). 시스템에는 즉시 해지 경로가 없다.
82	- 해지 예약이 있는 계정은 플랜 변경을 받지 않는다. 먼저 해지 예약을 취소해야 한다.
83	
84	## 8. 체험 기간과 앵커 결정
85	
86	- 체험은 14일이고 카드 등록이 필요 없다. 체험 중에는 청구서가 없다.
87	- 체험이 끝나는 날에 카드가 등록돼 있으면 그날 유료 전환하고, 그날의 날짜가 `anchorDay`가 된다.
88	  그날이 29~31일이면 `anchorDay`는 28로 정하고 첫 주기만 하루 이틀 길어진다. 첫 주기의 요금은 한 달치 그대로다.
89	- 체험 종료일에 카드가 없으면 계정은 읽기 전용이 되고, 나중에 카드를 등록한 날이 앵커가 된다.
90	
91	## 9. 구현할 때 자주 틀리는 것
92	
93	- 남은 일수에서 변경일 당일을 빼는 실수. 당일은 포함이다. 주기 시작일 당일 변경이면 남은 일수는 주기 전체다.
94	- 다운그레이드에 "공정하게" 크레딧을 주는 실수. 정책상 금지이고, INC-2022-11의 원인이었다.
95	- 현행 플랜에 30일 분모를 쓰거나, 레거시 플랜에 실제 일수 분모를 쓰는 실수. 레거시 여부는 **기존** 플랜으로 판단한다.
96	- 마지막에 한 번만 절사하는 실수. 일할 금액에서 한 번, 쿠폰 뒤에 한 번, 부가세에서 한 번 절사한다.
97	- 업그레이드 결제 실패 뒤 플랜만 바뀐 채 남는 실수. 결제 실패면 플랜 변경도 되돌린다.
98	- 다운그레이드 예약이 있는 계정에서 또 다운그레이드를 받으면 예약을 덮어쓴다. 두 개를 쌓지 않는다.
99	

1	// 날짜는 'YYYY-MM-DD' 문자열로만 다룬다. 시각과 시간대는 이 모듈 밖의 문제다.
2	
3	export function parseDate(s) {
4	  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s)
5	  if (!m) throw new TypeError(`invalid date: ${s}`)
6	  return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]))
7	}
8	
9	export function formatDate(d) {
10	  return d.toISOString().slice(0, 10)
11	}
12	
13	export function addDays(s, n) {
14	  const d = parseDate(s)
15	  d.setUTCDate(d.getUTCDate() + n)
16	  return formatDate(d)
17	}
18	
19	export function addMonths(s, n) {
20	  const d = parseDate(s)
21	  const day = d.getUTCDate()
22	  d.setUTCDate(1)
23	  d.setUTCMonth(d.getUTCMonth() + n)
24	  const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate()
25	  d.setUTCDate(Math.min(day, last))
26	  return formatDate(d)
27	}
28	
29	export function daysBetween(a, b) {
30	  return Math.round((parseDate(b) - parseDate(a)) / 86400000)
31	}
32	

_jwd/run-d8953658/src/coupons.js
_jwd/run-d8953658/src/dates.js
_jwd/run-d8953658/src/format.js
_jwd/run-d8953658/src/invoice.js
_jwd/run-d8953658/src/payment.js
_jwd/run-d8953658/src/plans.js
_jwd/run-d8953658/src/proration.js

_jwd/run-d8953658/test/proration.test.js
_jwd/run-d8953658/src/proration.js
_jwd/run-d8953658/src/plans.js

1	export const PLANS = [
2	  { id: 'starter', name: 'Starter', monthlyPrice: 29000, seatLimit: 5, legacy: false },
3	  { id: 'team', name: 'Team', monthlyPrice: 99000, seatLimit: 20, legacy: false },
4	  { id: 'business', name: 'Business', monthlyPrice: 290000, seatLimit: 100, legacy: false },
5	  { id: 'L-startup-2019', name: 'Startup (2019)', monthlyPrice: 49000, seatLimit: 10, legacy: true },
6	  { id: 'L-growth-2019', name: 'Growth (2019)', monthlyPrice: 149000, seatLimit: 30, legacy: true },
7	]
8	
9	export function findPlan(id) {
10	  const plan = PLANS.find((p) => p.id === id)
11	  if (!plan) throw new Error(`unknown plan: ${id}`)
12	  return plan
13	}
14	

1	import { test } from 'node:test'
2	import assert from 'node:assert/strict'
3	import { cycleBounds, prorate } from '../src/proration.js'
4	
5	test('cycleBounds: anchor before the date', () => {
6	  assert.deepEqual(cycleBounds(10, '2026-03-15'), { start: '2026-03-10', end: '2026-04-10' })
7	})
8	
9	test('cycleBounds: anchor after the date goes to previous month', () => {
10	  assert.deepEqual(cycleBounds(20, '2026-03-05'), { start: '2026-02-20', end: '2026-03-20' })
11	})
12	
13	test('cycleBounds rejects anchor outside 1..28', () => {
14	  assert.throws(() => cycleBounds(31, '2026-03-05'), RangeError)
15	})
16	
17	test('prorate: remaining days over cycle days, truncated', () => {
18	  const cycle = { start: '2026-03-10', end: '2026-04-10' } // 31 days
19	  assert.equal(prorate(99000, cycle, '2026-03-25'), Math.floor((99000 * 16) / 31))
20	})
21	

(Bash completed with no output)

1	import { addMonths, daysBetween, parseDate, formatDate } from './dates.js'
2	
3	// 청구 주기. anchorDay(1~28)가 매달 주기 시작일이다.
4	// at이 속한 주기의 [start, end)를 돌려준다. end는 다음 주기 시작일이다.
5	export function cycleBounds(anchorDay, at) {
6	  if (!Number.isInteger(anchorDay) || anchorDay < 1 || anchorDay > 28) {
7	    throw new RangeError(`anchorDay must be 1..28: ${anchorDay}`)
8	  }
9	  const d = parseDate(at)
10	  let start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), anchorDay))
11	  if (start > d) start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() - 1, anchorDay))
12	  const startStr = formatDate(start)
13	  return { start: startStr, end: addMonths(startStr, 1) }
14	}
15	
16	// 주기 안에서 at부터 주기 끝까지 남은 일수 비율로 amount를 나눈다. at 당일을 포함한다.
17	export function prorate(amount, cycle, at) {
18	  const total = daysBetween(cycle.start, cycle.end)
19	  const remaining = daysBetween(at, cycle.end)
20	  if (remaining < 0 || remaining > total) throw new RangeError(`${at} is outside the cycle`)
21	  return Math.floor((amount * remaining) / total)
22	}
23	

1	# 청구 주기와 일할 계산 정책
2	
3	이 문서는 Workhub 구독 청구의 주기, 플랜 변경 시 금액 처리, 일할 계산(proration) 규칙을 적는다.
4	코드(`src/proration.js`)는 계산 도구만 제공하고, 어떤 상황에 어떤 계산을 적용하는지는 여기에 있는
5	정책이 결정한다. 정책의 최종 책임은 재무팀이며, 변경하려면 재무팀 리뷰를 거친다(`glossary-and-incident-log.md`의 "변경 절차").
6	
7	## 1. 청구 주기(billing cycle)
8	
9	- 계정마다 `anchorDay`(1~28)가 있다. 매달 이 날짜에 새 주기가 시작하고, 주기 시작일에 한 달치 요금을 선불로 청구한다.
10	- 주기는 `[시작일, 다음 시작일)`이다. 3월 10일 앵커면 3월 10일부터 4월 9일까지가 한 주기다.
11	- `anchorDay`는 첫 유료 전환일의 날짜에서 정해진다. 체험(trial) 기간 14일이 끝나는 날이 유료 전환일이다.
12	- 29, 30, 31일은 앵커로 쓰지 않는다. 2023년 8월에 이 날짜를 앵커로 가진 계정 412개를 전부 28일로 옮겼다.
13	  2월에 주기 길이가 계정마다 달라지면서 CS 문의가 몰렸기 때문이다. 옮긴 계정 목록은 재무팀이 보관한다.
14	- 청구 배치는 주기 시작일 KST 09:00에 돈다. 이 시각 이전의 플랜 변경은 그날 시작하는 주기에 반영된다.
15	
16	## 2. 날짜의 기준: 한국 표준시(KST) 달력 날짜
17	
18	- 청구와 관련된 모든 날짜는 **KST 기준 달력 날짜**다. 서버와 DB는 UTC로 돌지만, 청구 로직에 들어오는 날짜는
19	  이미 KST로 바뀐 `YYYY-MM-DD` 문자열이어야 한다.
20	- 이유: 세금계산서의 "작성일자"가 청구 주기 시작일과 같아야 하고, 세금계산서는 한국 시간 기준으로 발행된다.
21	  UTC 날짜를 쓰면 KST 00:00~09:00 사이의 청구가 전날로 잡힌다. 2023년 6월에 실제로 그렇게 됐다(INC-2023-06).
22	- 그래서 `Date` 객체의 시각이나 사용자의 브라우저 시간대를 청구 로직에서 쓰지 않는다. 해외 고객도 KST 기준이다.
23	
24	## 3. 플랜 변경 시 금액 처리
25	
26	플랜 변경은 세 가지로 나눈다. 기준은 **월 요금의 크기**다. 좌석 수나 기능은 보지 않는다.
27	
28	| 변경 종류 | 적용 시점 | 청구 |
29	|---|---|---|
30	| 업그레이드 (월 요금이 오름) | 즉시 | 차액을 남은 일수만큼 일할 계산해서 즉시 청구 |
31	| 다운그레이드 (월 요금이 내림) | 다음 주기 시작일 | 이번 주기에는 청구도 환불도 없음. 다음 주기부터 새 요금 |
32	| 수평 이동 (월 요금이 같음) | 즉시 | 0원 |
33	
34	### 3.1 업그레이드
35	
36	- 변경일 당일을 남은 일수에 포함한다. 3월 25일 변경, 4월 10일 주기 끝이면 남은 일수는 16일이다.
37	- 청구 금액 = (새 플랜 월 요금 − 기존 플랜 월 요금) × 남은 일수 ÷ 주기 일수. 원 미만은 버린다.
38	- 주기 일수는 실제 달력 일수(28~31)다. 단, 레거시 플랜은 4절을 따른다.
39	- 업그레이드 청구서는 즉시 발행하고 즉시 결제한다. 결제가 실패하면 플랜 변경도 되돌린다.
40	
41	### 3.2 다운그레이드: 이번 주기에는 아무 금액도 움직이지 않는다
42	
43	- 다운그레이드는 **다음 주기 시작일부터** 적용한다. 변경 요청은 "예약"으로만 저장한다.
44	- 이번 주기의 남은 기간에 대해 차액을 환불하거나 크레딧으로 돌려주지 않는다. 시스템이 음수 금액을 만들면 안 된다.
45	- 근거: 2022년 11월까지는 다운그레이드도 즉시 일할 계산해서 차액을 음수 청구서로 만들었다. 그 결과 월 마감에서
46	  음수 청구서마다 수정세금계산서를 발행해야 했고, 재무팀이 11월 마감을 8일 늦췄다(INC-2022-11).
47	  2022년 12월 정책 회의에서 "다운그레이드는 이연, 환불 없음"으로 확정했고 약관 7조 3항에 반영했다.
48	- CS가 예외를 요청하면 재무팀이 수동 크레딧으로 처리한다. 시스템은 예외 경로를 두지 않는다.
49	- 다운그레이드 예약이 있는 상태에서 다시 업그레이드하면 예약은 취소된다.
50	
51	### 3.3 수평 이동
52	
53	- 같은 월 요금의 플랜으로 옮기는 경우다(현재 카탈로그에는 없지만 과거 지역별 플랜에 있었다). 즉시 적용, 청구 0원.
54	
55	## 4. 레거시 플랜(`L-` 접두)의 일할 계산
56	
57	- 2019년 계약서 4조: "일할 계산 시 1개월은 30일로 본다." 그래서 레거시 플랜이 관련된 일할 계산은
58	  주기의 실제 일수와 무관하게 **분모를 30**으로 쓴다. 분자(남은 일수)는 실제 남은 일수를 쓰되 30을 넘으면 30으로 본다.
59	- 이 규칙은 기존 플랜이 레거시인 경우에 적용한다. 레거시에서 현행 플랜으로 업그레이드할 때도 기존 계약이 살아 있는
60	  마지막 주기이므로 30일 기준이다.
61	- 31일짜리 주기에서 레거시 고객이 업그레이드하면 현행 고객보다 조금 더 낸다. 계약서 문구가 그렇고, 고객도 안다.
62	  이걸 "공정하게" 실제 일수로 바꾸면 계약 위반이다.
63	
64	## 5. 계산 예시
65	
66	| 상황 | 계산 | 금액 |
67	|---|---|---|
68	| Team(99,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 99,000) × 16 ÷ 31 | 98,580원 |
69	| Business → Team, 3월 25일 변경 | 다음 주기(4월 10일)부터 Team 요금. 이번 주기 청구 0 | 0원 |
70	| L-growth-2019(149,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 149,000) × 16 ÷ 30 | 75,200원 |
71	| Starter → Team, 주기 시작일 당일 변경 | 남은 일수 = 주기 일수, 차액 전액 | 70,000원 |
72	
73	## 6. 범위 밖
74	
75	- 연간 결제는 이 모듈이 다루지 않는다. 연간 고객 37곳은 재무팀이 수동 청구서로 처리한다.
76	- Enterprise는 계약별 청구서(net-30)이며 플랜 변경 개념이 없다.
77	
78	## 7. 해지
79	
80	- 해지는 주기 끝에 적용한다. 남은 기간은 그대로 쓸 수 있고 환불은 없다. 다운그레이드와 같은 원칙이다.
81	- 즉시 해지와 환불은 재무팀만 할 수 있다(법적 분쟁, 이중 가입 등). 시스템에는 즉시 해지 경로가 없다.
82	- 해지 예약이 있는 계정은 플랜 변경을 받지 않는다. 먼저 해지 예약을 취소해야 한다.
83	
84	## 8. 체험 기간과 앵커 결정
85	
86	- 체험은 14일이고 카드 등록이 필요 없다. 체험 중에는 청구서가 없다.
87	- 체험이 끝나는 날에 카드가 등록돼 있으면 그날 유료 전환하고, 그날의 날짜가 `anchorDay`가 된다.
88	  그날이 29~31일이면 `anchorDay`는 28로 정하고 첫 주기만 하루 이틀 길어진다. 첫 주기의 요금은 한 달치 그대로다.
89	- 체험 종료일에 카드가 없으면 계정은 읽기 전용이 되고, 나중에 카드를 등록한 날이 앵커가 된다.
90	
91	## 9. 구현할 때 자주 틀리는 것
92	
93	- 남은 일수에서 변경일 당일을 빼는 실수. 당일은 포함이다. 주기 시작일 당일 변경이면 남은 일수는 주기 전체다.
94	- 다운그레이드에 "공정하게" 크레딧을 주는 실수. 정책상 금지이고, INC-2022-11의 원인이었다.
95	- 현행 플랜에 30일 분모를 쓰거나, 레거시 플랜에 실제 일수 분모를 쓰는 실수. 레거시 여부는 **기존** 플랜으로 판단한다.
96	- 마지막에 한 번만 절사하는 실수. 일할 금액에서 한 번, 쿠폰 뒤에 한 번, 부가세에서 한 번 절사한다.
97	- 업그레이드 결제 실패 뒤 플랜만 바뀐 채 남는 실수. 결제 실패면 플랜 변경도 되돌린다.
98	- 다운그레이드 예약이 있는 계정에서 또 다운그레이드를 받으면 예약을 덮어쓴다. 두 개를 쌓지 않는다.
99	

1	// 날짜는 'YYYY-MM-DD' 문자열로만 다룬다. 시각과 시간대는 이 모듈 밖의 문제다.
2	
3	export function parseDate(s) {
4	  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s)
5	  if (!m) throw new TypeError(`invalid date: ${s}`)
6	  return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]))
7	}
8	
9	export function formatDate(d) {
10	  return d.toISOString().slice(0, 10)
11	}
12	
13	export function addDays(s, n) {
14	  const d = parseDate(s)
15	  d.setUTCDate(d.getUTCDate() + n)
16	  return formatDate(d)
17	}
18	
19	export function addMonths(s, n) {
20	  const d = parseDate(s)
21	  const day = d.getUTCDate()
22	  d.setUTCDate(1)
23	  d.setUTCMonth(d.getUTCMonth() + n)
24	  const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate()
25	  d.setUTCDate(Math.min(day, last))
26	  return formatDate(d)
27	}
28	
29	export function daysBetween(a, b) {
30	  return Math.round((parseDate(b) - parseDate(a)) / 86400000)
31	}
32	

1	import { addMonths, daysBetween, parseDate, formatDate } from './dates.js'
2	
3	// 청구 주기. anchorDay(1~28)가 매달 주기 시작일이다.
4	// at이 속한 주기의 [start, end)를 돌려준다. end는 다음 주기 시작일이다.
5	export function cycleBounds(anchorDay, at) {
6	  if (!Number.isInteger(anchorDay) || anchorDay < 1 || anchorDay > 28) {
7	    throw new RangeError(`anchorDay must be 1..28: ${anchorDay}`)
8	  }
9	  const d = parseDate(at)
10	  let start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), anchorDay))
11	  if (start > d) start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() - 1, anchorDay))
12	  const startStr = formatDate(start)
13	  return { start: startStr, end: addMonths(startStr, 1) }
14	}
15	
16	// 주기 안에서 at부터 주기 끝까지 남은 일수 비율로 amount를 나눈다. at 당일을 포함한다.
17	export function prorate(amount, cycle, at) {
18	  const total = daysBetween(cycle.start, cycle.end)
19	  const remaining = daysBetween(at, cycle.end)
20	  if (remaining < 0 || remaining > total) throw new RangeError(`${at} is outside the cycle`)
21	  return Math.floor((amount * remaining) / total)
22	}
23	

1	# 청구 주기와 일할 계산 정책
2	
3	이 문서는 Workhub 구독 청구의 주기, 플랜 변경 시 금액 처리, 일할 계산(proration) 규칙을 적는다.
4	코드(`src/proration.js`)는 계산 도구만 제공하고, 어떤 상황에 어떤 계산을 적용하는지는 여기에 있는
5	정책이 결정한다. 정책의 최종 책임은 재무팀이며, 변경하려면 재무팀 리뷰를 거친다(`glossary-and-incident-log.md`의 "변경 절차").
6	
7	## 1. 청구 주기(billing cycle)
8	
9	- 계정마다 `anchorDay`(1~28)가 있다. 매달 이 날짜에 새 주기가 시작하고, 주기 시작일에 한 달치 요금을 선불로 청구한다.
10	- 주기는 `[시작일, 다음 시작일)`이다. 3월 10일 앵커면 3월 10일부터 4월 9일까지가 한 주기다.
11	- `anchorDay`는 첫 유료 전환일의 날짜에서 정해진다. 체험(trial) 기간 14일이 끝나는 날이 유료 전환일이다.
12	- 29, 30, 31일은 앵커로 쓰지 않는다. 2023년 8월에 이 날짜를 앵커로 가진 계정 412개를 전부 28일로 옮겼다.
13	  2월에 주기 길이가 계정마다 달라지면서 CS 문의가 몰렸기 때문이다. 옮긴 계정 목록은 재무팀이 보관한다.
14	- 청구 배치는 주기 시작일 KST 09:00에 돈다. 이 시각 이전의 플랜 변경은 그날 시작하는 주기에 반영된다.
15	
16	## 2. 날짜의 기준: 한국 표준시(KST) 달력 날짜
17	
18	- 청구와 관련된 모든 날짜는 **KST 기준 달력 날짜**다. 서버와 DB는 UTC로 돌지만, 청구 로직에 들어오는 날짜는
19	  이미 KST로 바뀐 `YYYY-MM-DD` 문자열이어야 한다.
20	- 이유: 세금계산서의 "작성일자"가 청구 주기 시작일과 같아야 하고, 세금계산서는 한국 시간 기준으로 발행된다.
21	  UTC 날짜를 쓰면 KST 00:00~09:00 사이의 청구가 전날로 잡힌다. 2023년 6월에 실제로 그렇게 됐다(INC-2023-06).
22	- 그래서 `Date` 객체의 시각이나 사용자의 브라우저 시간대를 청구 로직에서 쓰지 않는다. 해외 고객도 KST 기준이다.
23	
24	## 3. 플랜 변경 시 금액 처리
25	
26	플랜 변경은 세 가지로 나눈다. 기준은 **월 요금의 크기**다. 좌석 수나 기능은 보지 않는다.
27	
28	| 변경 종류 | 적용 시점 | 청구 |
29	|---|---|---|
30	| 업그레이드 (월 요금이 오름) | 즉시 | 차액을 남은 일수만큼 일할 계산해서 즉시 청구 |
31	| 다운그레이드 (월 요금이 내림) | 다음 주기 시작일 | 이번 주기에는 청구도 환불도 없음. 다음 주기부터 새 요금 |
32	| 수평 이동 (월 요금이 같음) | 즉시 | 0원 |
33	
34	### 3.1 업그레이드
35	
36	- 변경일 당일을 남은 일수에 포함한다. 3월 25일 변경, 4월 10일 주기 끝이면 남은 일수는 16일이다.
37	- 청구 금액 = (새 플랜 월 요금 − 기존 플랜 월 요금) × 남은 일수 ÷ 주기 일수. 원 미만은 버린다.
38	- 주기 일수는 실제 달력 일수(28~31)다. 단, 레거시 플랜은 4절을 따른다.
39	- 업그레이드 청구서는 즉시 발행하고 즉시 결제한다. 결제가 실패하면 플랜 변경도 되돌린다.
40	
41	### 3.2 다운그레이드: 이번 주기에는 아무 금액도 움직이지 않는다
42	
43	- 다운그레이드는 **다음 주기 시작일부터** 적용한다. 변경 요청은 "예약"으로만 저장한다.
44	- 이번 주기의 남은 기간에 대해 차액을 환불하거나 크레딧으로 돌려주지 않는다. 시스템이 음수 금액을 만들면 안 된다.
45	- 근거: 2022년 11월까지는 다운그레이드도 즉시 일할 계산해서 차액을 음수 청구서로 만들었다. 그 결과 월 마감에서
46	  음수 청구서마다 수정세금계산서를 발행해야 했고, 재무팀이 11월 마감을 8일 늦췄다(INC-2022-11).
47	  2022년 12월 정책 회의에서 "다운그레이드는 이연, 환불 없음"으로 확정했고 약관 7조 3항에 반영했다.
48	- CS가 예외를 요청하면 재무팀이 수동 크레딧으로 처리한다. 시스템은 예외 경로를 두지 않는다.
49	- 다운그레이드 예약이 있는 상태에서 다시 업그레이드하면 예약은 취소된다.
50	
51	### 3.3 수평 이동
52	
53	- 같은 월 요금의 플랜으로 옮기는 경우다(현재 카탈로그에는 없지만 과거 지역별 플랜에 있었다). 즉시 적용, 청구 0원.
54	
55	## 4. 레거시 플랜(`L-` 접두)의 일할 계산
56	
57	- 2019년 계약서 4조: "일할 계산 시 1개월은 30일로 본다." 그래서 레거시 플랜이 관련된 일할 계산은
58	  주기의 실제 일수와 무관하게 **분모를 30**으로 쓴다. 분자(남은 일수)는 실제 남은 일수를 쓰되 30을 넘으면 30으로 본다.
59	- 이 규칙은 기존 플랜이 레거시인 경우에 적용한다. 레거시에서 현행 플랜으로 업그레이드할 때도 기존 계약이 살아 있는
60	  마지막 주기이므로 30일 기준이다.
61	- 31일짜리 주기에서 레거시 고객이 업그레이드하면 현행 고객보다 조금 더 낸다. 계약서 문구가 그렇고, 고객도 안다.
62	  이걸 "공정하게" 실제 일수로 바꾸면 계약 위반이다.
63	
64	## 5. 계산 예시
65	
66	| 상황 | 계산 | 금액 |
67	|---|---|---|
68	| Team(99,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 99,000) × 16 ÷ 31 | 98,580원 |
69	| Business → Team, 3월 25일 변경 | 다음 주기(4월 10일)부터 Team 요금. 이번 주기 청구 0 | 0원 |
70	| L-growth-2019(149,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 149,000) × 16 ÷ 30 | 75,200원 |
71	| Starter → Team, 주기 시작일 당일 변경 | 남은 일수 = 주기 일수, 차액 전액 | 70,000원 |
72	
73	## 6. 범위 밖
74	
75	- 연간 결제는 이 모듈이 다루지 않는다. 연간 고객 37곳은 재무팀이 수동 청구서로 처리한다.
76	- Enterprise는 계약별 청구서(net-30)이며 플랜 변경 개념이 없다.
77	
78	## 7. 해지
79	
80	- 해지는 주기 끝에 적용한다. 남은 기간은 그대로 쓸 수 있고 환불은 없다. 다운그레이드와 같은 원칙이다.
81	- 즉시 해지와 환불은 재무팀만 할 수 있다(법적 분쟁, 이중 가입 등). 시스템에는 즉시 해지 경로가 없다.
82	- 해지 예약이 있는 계정은 플랜 변경을 받지 않는다. 먼저 해지 예약을 취소해야 한다.
83	
84	## 8. 체험 기간과 앵커 결정
85	
86	- 체험은 14일이고 카드 등록이 필요 없다. 체험 중에는 청구서가 없다.
87	- 체험이 끝나는 날에 카드가 등록돼 있으면 그날 유료 전환하고, 그날의 날짜가 `anchorDay`가 된다.
88	  그날이 29~31일이면 `anchorDay`는 28로 정하고 첫 주기만 하루 이틀 길어진다. 첫 주기의 요금은 한 달치 그대로다.
89	- 체험 종료일에 카드가 없으면 계정은 읽기 전용이 되고, 나중에 카드를 등록한 날이 앵커가 된다.
90	
91	## 9. 구현할 때 자주 틀리는 것
92	
93	- 남은 일수에서 변경일 당일을 빼는 실수. 당일은 포함이다. 주기 시작일 당일 변경이면 남은 일수는 주기 전체다.
94	- 다운그레이드에 "공정하게" 크레딧을 주는 실수. 정책상 금지이고, INC-2022-11의 원인이었다.
95	- 현행 플랜에 30일 분모를 쓰거나, 레거시 플랜에 실제 일수 분모를 쓰는 실수. 레거시 여부는 **기존** 플랜으로 판단한다.
96	- 마지막에 한 번만 절사하는 실수. 일할 금액에서 한 번, 쿠폰 뒤에 한 번, 부가세에서 한 번 절사한다.
97	- 업그레이드 결제 실패 뒤 플랜만 바뀐 채 남는 실수. 결제 실패면 플랜 변경도 되돌린다.
98	- 다운그레이드 예약이 있는 계정에서 또 다운그레이드를 받으면 예약을 덮어쓴다. 두 개를 쌓지 않는다.
99	

1	// 날짜는 'YYYY-MM-DD' 문자열로만 다룬다. 시각과 시간대는 이 모듈 밖의 문제다.
2	
3	export function parseDate(s) {
4	  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s)
5	  if (!m) throw new TypeError(`invalid date: ${s}`)
6	  return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]))
7	}
8	
9	export function formatDate(d) {
10	  return d.toISOString().slice(0, 10)
11	}
12	
13	export function addDays(s, n) {
14	  const d = parseDate(s)
15	  d.setUTCDate(d.getUTCDate() + n)
16	  return formatDate(d)
17	}
18	
19	export function addMonths(s, n) {
20	  const d = parseDate(s)
21	  const day = d.getUTCDate()
22	  d.setUTCDate(1)
23	  d.setUTCMonth(d.getUTCMonth() + n)
24	  const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate()
25	  d.setUTCDate(Math.min(day, last))
26	  return formatDate(d)
27	}
28	
29	export function daysBetween(a, b) {
30	  return Math.round((parseDate(b) - parseDate(a)) / 86400000)
31	}
32	

1	import { addMonths, daysBetween, parseDate, formatDate } from './dates.js'
2	
3	// 청구 주기. anchorDay(1~28)가 매달 주기 시작일이다.
4	// at이 속한 주기의 [start, end)를 돌려준다. end는 다음 주기 시작일이다.
5	export function cycleBounds(anchorDay, at) {
6	  if (!Number.isInteger(anchorDay) || anchorDay < 1 || anchorDay > 28) {
7	    throw new RangeError(`anchorDay must be 1..28: ${anchorDay}`)
8	  }
9	  const d = parseDate(at)
10	  let start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), anchorDay))
11	  if (start > d) start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() - 1, anchorDay))
12	  const startStr = formatDate(start)
13	  return { start: startStr, end: addMonths(startStr, 1) }
14	}
15	
16	// 주기 안에서 at부터 주기 끝까지 남은 일수 비율로 amount를 나눈다. at 당일을 포함한다.
17	export function prorate(amount, cycle, at) {
18	  const total = daysBetween(cycle.start, cycle.end)
19	  const remaining = daysBetween(at, cycle.end)
20	  if (remaining < 0 || remaining > total) throw new RangeError(`${at} is outside the cycle`)
21	  return Math.floor((amount * remaining) / total)
22	}
23	

1	# 청구 주기와 일할 계산 정책
2	
3	이 문서는 Workhub 구독 청구의 주기, 플랜 변경 시 금액 처리, 일할 계산(proration) 규칙을 적는다.
4	코드(`src/proration.js`)는 계산 도구만 제공하고, 어떤 상황에 어떤 계산을 적용하는지는 여기에 있는
5	정책이 결정한다. 정책의 최종 책임은 재무팀이며, 변경하려면 재무팀 리뷰를 거친다(`glossary-and-incident-log.md`의 "변경 절차").
6	
7	## 1. 청구 주기(billing cycle)
8	
9	- 계정마다 `anchorDay`(1~28)가 있다. 매달 이 날짜에 새 주기가 시작하고, 주기 시작일에 한 달치 요금을 선불로 청구한다.
10	- 주기는 `[시작일, 다음 시작일)`이다. 3월 10일 앵커면 3월 10일부터 4월 9일까지가 한 주기다.
11	- `anchorDay`는 첫 유료 전환일의 날짜에서 정해진다. 체험(trial) 기간 14일이 끝나는 날이 유료 전환일이다.
12	- 29, 30, 31일은 앵커로 쓰지 않는다. 2023년 8월에 이 날짜를 앵커로 가진 계정 412개를 전부 28일로 옮겼다.
13	  2월에 주기 길이가 계정마다 달라지면서 CS 문의가 몰렸기 때문이다. 옮긴 계정 목록은 재무팀이 보관한다.
14	- 청구 배치는 주기 시작일 KST 09:00에 돈다. 이 시각 이전의 플랜 변경은 그날 시작하는 주기에 반영된다.
15	
16	## 2. 날짜의 기준: 한국 표준시(KST) 달력 날짜
17	
18	- 청구와 관련된 모든 날짜는 **KST 기준 달력 날짜**다. 서버와 DB는 UTC로 돌지만, 청구 로직에 들어오는 날짜는
19	  이미 KST로 바뀐 `YYYY-MM-DD` 문자열이어야 한다.
20	- 이유: 세금계산서의 "작성일자"가 청구 주기 시작일과 같아야 하고, 세금계산서는 한국 시간 기준으로 발행된다.
21	  UTC 날짜를 쓰면 KST 00:00~09:00 사이의 청구가 전날로 잡힌다. 2023년 6월에 실제로 그렇게 됐다(INC-2023-06).
22	- 그래서 `Date` 객체의 시각이나 사용자의 브라우저 시간대를 청구 로직에서 쓰지 않는다. 해외 고객도 KST 기준이다.
23	
24	## 3. 플랜 변경 시 금액 처리
25	
26	플랜 변경은 세 가지로 나눈다. 기준은 **월 요금의 크기**다. 좌석 수나 기능은 보지 않는다.
27	
28	| 변경 종류 | 적용 시점 | 청구 |
29	|---|---|---|
30	| 업그레이드 (월 요금이 오름) | 즉시 | 차액을 남은 일수만큼 일할 계산해서 즉시 청구 |
31	| 다운그레이드 (월 요금이 내림) | 다음 주기 시작일 | 이번 주기에는 청구도 환불도 없음. 다음 주기부터 새 요금 |
32	| 수평 이동 (월 요금이 같음) | 즉시 | 0원 |
33	
34	### 3.1 업그레이드
35	
36	- 변경일 당일을 남은 일수에 포함한다. 3월 25일 변경, 4월 10일 주기 끝이면 남은 일수는 16일이다.
37	- 청구 금액 = (새 플랜 월 요금 − 기존 플랜 월 요금) × 남은 일수 ÷ 주기 일수. 원 미만은 버린다.
38	- 주기 일수는 실제 달력 일수(28~31)다. 단, 레거시 플랜은 4절을 따른다.
39	- 업그레이드 청구서는 즉시 발행하고 즉시 결제한다. 결제가 실패하면 플랜 변경도 되돌린다.
40	
41	### 3.2 다운그레이드: 이번 주기에는 아무 금액도 움직이지 않는다
42	
43	- 다운그레이드는 **다음 주기 시작일부터** 적용한다. 변경 요청은 "예약"으로만 저장한다.
44	- 이번 주기의 남은 기간에 대해 차액을 환불하거나 크레딧으로 돌려주지 않는다. 시스템이 음수 금액을 만들면 안 된다.
45	- 근거: 2022년 11월까지는 다운그레이드도 즉시 일할 계산해서 차액을 음수 청구서로 만들었다. 그 결과 월 마감에서
46	  음수 청구서마다 수정세금계산서를 발행해야 했고, 재무팀이 11월 마감을 8일 늦췄다(INC-2022-11).
47	  2022년 12월 정책 회의에서 "다운그레이드는 이연, 환불 없음"으로 확정했고 약관 7조 3항에 반영했다.
48	- CS가 예외를 요청하면 재무팀이 수동 크레딧으로 처리한다. 시스템은 예외 경로를 두지 않는다.
49	- 다운그레이드 예약이 있는 상태에서 다시 업그레이드하면 예약은 취소된다.
50	
51	### 3.3 수평 이동
52	
53	- 같은 월 요금의 플랜으로 옮기는 경우다(현재 카탈로그에는 없지만 과거 지역별 플랜에 있었다). 즉시 적용, 청구 0원.
54	
55	## 4. 레거시 플랜(`L-` 접두)의 일할 계산
56	
57	- 2019년 계약서 4조: "일할 계산 시 1개월은 30일로 본다." 그래서 레거시 플랜이 관련된 일할 계산은
58	  주기의 실제 일수와 무관하게 **분모를 30**으로 쓴다. 분자(남은 일수)는 실제 남은 일수를 쓰되 30을 넘으면 30으로 본다.
59	- 이 규칙은 기존 플랜이 레거시인 경우에 적용한다. 레거시에서 현행 플랜으로 업그레이드할 때도 기존 계약이 살아 있는
60	  마지막 주기이므로 30일 기준이다.
61	- 31일짜리 주기에서 레거시 고객이 업그레이드하면 현행 고객보다 조금 더 낸다. 계약서 문구가 그렇고, 고객도 안다.
62	  이걸 "공정하게" 실제 일수로 바꾸면 계약 위반이다.
63	
64	## 5. 계산 예시
65	
66	| 상황 | 계산 | 금액 |
67	|---|---|---|
68	| Team(99,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 99,000) × 16 ÷ 31 | 98,580원 |
69	| Business → Team, 3월 25일 변경 | 다음 주기(4월 10일)부터 Team 요금. 이번 주기 청구 0 | 0원 |
70	| L-growth-2019(149,000) → Business(290,000), 앵커 10일, 3월 25일 변경 | (290,000 − 149,000) × 16 ÷ 30 | 75,200원 |
71	| Starter → Team, 주기 시작일 당일 변경 | 남은 일수 = 주기 일수, 차액 전액 | 70,000원 |
72	
73	## 6. 범위 밖
74	
75	- 연간 결제는 이 모듈이 다루지 않는다. 연간 고객 37곳은 재무팀이 수동 청구서로 처리한다.
76	- Enterprise는 계약별 청구서(net-30)이며 플랜 변경 개념이 없다.
77	
78	## 7. 해지
79	
80	- 해지는 주기 끝에 적용한다. 남은 기간은 그대로 쓸 수 있고 환불은 없다. 다운그레이드와 같은 원칙이다.
81	- 즉시 해지와 환불은 재무팀만 할 수 있다(법적 분쟁, 이중 가입 등). 시스템에는 즉시 해지 경로가 없다.
82	- 해지 예약이 있는 계정은 플랜 변경을 받지 않는다. 먼저 해지 예약을 취소해야 한다.
83	
84	## 8. 체험 기간과 앵커 결정
85	
86	- 체험은 14일이고 카드 등록이 필요 없다. 체험 중에는 청구서가 없다.
87	- 체험이 끝나는 날에 카드가 등록돼 있으면 그날 유료 전환하고, 그날의 날짜가 `anchorDay`가 된다.
88	  그날이 29~31일이면 `anchorDay`는 28로 정하고 첫 주기만 하루 이틀 길어진다. 첫 주기의 요금은 한 달치 그대로다.
89	- 체험 종료일에 카드가 없으면 계정은 읽기 전용이 되고, 나중에 카드를 등록한 날이 앵커가 된다.
90	
91	## 9. 구현할 때 자주 틀리는 것
92	
93	- 남은 일수에서 변경일 당일을 빼는 실수. 당일은 포함이다. 주기 시작일 당일 변경이면 남은 일수는 주기 전체다.
94	- 다운그레이드에 "공정하게" 크레딧을 주는 실수. 정책상 금지이고, INC-2022-11의 원인이었다.
95	- 현행 플랜에 30일 분모를 쓰거나, 레거시 플랜에 실제 일수 분모를 쓰는 실수. 레거시 여부는 **기존** 플랜으로 판단한다.
96	- 마지막에 한 번만 절사하는 실수. 일할 금액에서 한 번, 쿠폰 뒤에 한 번, 부가세에서 한 번 절사한다.
97	- 업그레이드 결제 실패 뒤 플랜만 바뀐 채 남는 실수. 결제 실패면 플랜 변경도 되돌린다.
98	- 다운그레이드 예약이 있는 계정에서 또 다운그레이드를 받으면 예약을 덮어쓴다. 두 개를 쌓지 않는다.
99	

./src/dates.js
---
./test/proration.test.js
./docs/billing-cycle-and-proration.md
./docs/plans-and-legacy-contracts.md
./src/proration.js

1	// 날짜는 'YYYY-MM-DD' 문자열로만 다룬다. 시각과 시간대는 이 모듈 밖의 문제다.
2	
3	export function parseDate(s) {
4	  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s)
5	  if (!m) throw new TypeError(`invalid date: ${s}`)
6	  return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]))
7	}
8	
9	export function formatDate(d) {
10	  return d.toISOString().slice(0, 10)
11	}
12	
13	export function addDays(s, n) {
14	  const d = parseDate(s)
15	  d.setUTCDate(d.getUTCDate() + n)
16	  return formatDate(d)
17	}
18	
19	export function addMonths(s, n) {
20	  const d = parseDate(s)
21	  const day = d.getUTCDate()
22	  d.setUTCDate(1)
23	  d.setUTCMonth(d.getUTCMonth() + n)
24	  const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate()
25	  d.setUTCDate(Math.min(day, last))
26	  return formatDate(d)
27	}
28	
29	export function daysBetween(a, b) {
30	  return Math.round((parseDate(b) - parseDate(a)) / 86400000)
31	}
32	

1	# 플랜 연혁과 레거시 계약
2	
3	`src/plans.js`의 `PLANS`에는 현행 플랜 3개와 레거시 플랜 2개가 섞여 있다. 왜 레거시가 남아 있고,
4	레거시 고객에게 무엇을 약속했는지는 코드에 없다. 이 문서가 그 약속을 적는다.
5	
6	## 1. 연혁
7	
8	| 시기 | 변화 |
9	|---|---|
10	| 2019.03 | 출시. Startup(49,000원, 10석), Growth(149,000원, 30석). 초기 고객과는 서면 계약을 맺었다 |
11	| 2021.06 | 플랜 개편. Starter/Team/Business로 교체. 2019 플랜은 신규 판매 중단, ID 앞에 `L-`를 붙여 구분 |
12	| 2023.08 | 앵커 날짜 29~31일 계정을 28일로 이전 |
13	| 2024.02 | Business 가격을 250,000원에서 290,000원으로 인상. 기존 Business 고객은 6개월 유예 후 적용 |
14	| 2025.01 | 레거시 플랜 레코드를 정리하려다 청구 실패 발생(INC-2025-01). 이후 "레거시 레코드 삭제 금지" |
15	
16	## 2. 레거시 플랜 고객과의 계약 조건
17	
18	2019년 서면 계약을 맺은 고객은 2026년 3월 기준 61곳이 남아 있다. 계약서의 핵심 조항은 다음과 같다.
19	
20	- **가격 고정(4조 1항)**: 계약 기간 동안 월 요금을 올리지 않는다. 계약은 매년 자동 갱신되며 갱신 시에도 가격은 유지된다.
21	  양쪽 중 한쪽이 90일 전 서면 통지로 해지할 수 있다.
22	- **30일 기준 일할 계산(4조 3항)**: 일할 계산이 필요한 모든 경우에 1개월을 30일로 본다.
23	  자세한 적용은 `billing-cycle-and-proration.md` 4절.
24	- **좌석 정의(5조)**: 레거시 계약의 좌석은 "초대된 사용자 수"다. 현행 플랜의 좌석은 "지난 30일 안에 로그인한 활성 사용자 수"다.
25	  같은 워크스페이스라도 플랜에 따라 좌석 수가 다르게 집계된다. 좌석 집계 로직은 별도 서비스(`seat-counter`)에 있다.
26	- **기능 동결 없음**: 레거시 고객도 신규 기능을 쓴다. 기능으로 차별하지 않는다.
27	
28	## 3. 레거시 플랜을 다루는 규칙
29	
30	- 레거시 플랜은 **신규 가입이 불가능**하다. 가격 페이지와 가입 화면에서는 숨긴다. 그러나 `PLANS`에서는 지우지 않는다.
31	  2025년 1월에 "안 쓰는 플랜 정리"로 레코드를 지웠다가 61개 계정의 청구 배치가 `unknown plan`으로 실패했다.
32	- **레거시 → 현행 업그레이드**: 가능하다. 다만 업그레이드하는 순간 가격 고정 조항이 소멸한다(계약서 4조 4항).
33	  CS가 고객에게 이 사실을 사전 고지해야 하며, 고지 기록을 CRM에 남긴 뒤에만 변경을 진행한다.
34	  시스템은 이 고지를 강제하지 않는다. 고지 여부는 CS 프로세스에 맡긴다.
35	- **현행 → 레거시 다운그레이드**: 불가능하다. 레거시 플랜은 새로 배정할 수 없다. 시스템은 이 요청을 거부해야 한다.
36	- **레거시 → 레거시** (Startup → Growth): 가능하다. 둘 다 레거시이므로 가격 고정은 유지된다.
37	- 레거시 플랜 ID(`L-startup-2019`, `L-growth-2019`)는 CRM과 회계 시스템의 매핑 키다. 바꾸면 안 된다.
38	
39	## 4. 플랜 ID와 이름
40	
41	- 플랜 ID는 외부 시스템(CRM, 회계, 데이터 웨어하우스)에서 매핑 키로 쓴다. 한 번 정해진 ID는 바꾸지 않는다.
42	  이름(`name`)은 마케팅이 바꿀 수 있다.
43	- `L-` 접두는 "2021년 개편 이전의 서면 계약 플랜"이라는 뜻이다. `legacy: true` 플래그와 항상 같이 간다.
44	  새 레거시 플랜이 생기는 일은 없다.
45	
46	## 5. 가격 표기
47	
48	- `monthlyPrice`는 **부가세 별도** 금액이다. 청구서에는 공급가액으로 들어가고 부가세는 따로 계산한다.
49	- 마케팅 페이지는 소비자에게 보이는 곳이라 부가세 포함 가격을 표시한다(29,000원 → "월 31,900원(VAT 포함)").
50	  B2B 견적서와 청구서는 부가세 별도로 표시한다.
51	- 2024년 2월 가격 인상 때 유예 대상 Business 고객(당시 213곳)은 6개월 동안 250,000원으로 청구했다.
52	  이 유예는 `PLANS`가 아니라 계정별 `priceOverride`로 처리했고, 2024년 8월에 모두 만료됐다.
53	
54	## 6. 좌석 초과
55	
56	- 현행 플랜에서 활성 사용자가 `seatLimit`을 넘으면 자동으로 상위 플랜으로 옮기지 않는다.
57	  워크스페이스 관리자에게 알림을 보내고, 초과 상태가 2주기 이어지면 CS가 연락한다.
58	- 레거시 플랜은 초대 사용자 기준이라 초과가 거의 없다. 초과하면 CS가 개별 협의한다.
59	
60	## 7. Enterprise
61	
62	- Enterprise는 `PLANS`에 없다. 계약별 견적, 청구서 발행(net-30), 계좌이체 결제이며 카드 결제와 자동 청구 배치를 타지 않는다.
63	- 이 모듈에서 Enterprise 계정을 만나면 처리 대상이 아니다. Enterprise 계정은 `planId`가 `null`이다.
64	
65	## 8. 계정 데이터에서 플랜과 관련된 필드
66	
67	| 필드 | 뜻 | 비고 |
68	|---|---|---|
69	| `planId` | 현재 적용 중인 플랜 | Enterprise는 `null` |
70	| `pendingPlanId` | 다음 주기부터 적용될 플랜(다운그레이드 예약) | 없으면 `null` |
71	| `anchorDay` | 청구 주기 시작일 | 1~28 |
72	| `priceOverride` | 계정별 요금 예외(원) | 2024년 가격 인상 유예에 썼고, 지금은 전부 `null` |
73	| `contractRef` | 서면 계약 문서 번호 | 레거시 고객만 값이 있다 |
74	| `credits` | 잔여 크레딧(원) | `coupons-and-credits.md` |
75	
76	- `pendingPlanId`는 주기 시작 배치가 `planId`로 옮기고 비운다. 배치가 실패하면 다음 날 다시 시도한다.
77	- `contractRef`가 있는 계정이 곧 레거시 계약 고객이다. `planId`의 `L-` 접두와 항상 일치해야 한다. 어긋나면 데이터 오류다.
78	
79	## 9. 레거시 고객 응대 원칙
80	
81	- 레거시 고객 61곳은 초기 고객이라 매출 비중은 4%지만 레퍼런스 가치가 크다. 계약 조건을 시스템 편의로 바꾸지 않는다.
82	- 레거시 고객이 "새 플랜이 더 싸다"고 문의하면 CS가 현행 플랜과 비교표를 보내고, 옮기면 가격 고정이 사라진다는 점을 고지한다.
83	  이 고지는 CRM에 "가격 고정 소멸 고지" 태그로 남긴다. 태그 없이 업그레이드한 사례가 발견되면 CS 리드가 확인한다.
84	- 레거시 고객에게 보내는 청구서에는 계약 번호(`contractRef`)를 품목 설명에 넣는다. 고객사 회계팀이 계약과 대조하기 때문이다.
85	
86	## 10. 자주 받는 질문
87	
88	- **레거시 플랜을 `PLANS`에서 지워도 되나?** 안 된다. INC-2025-01. 숨기는 것은 UI가 한다.
89	- **새 고객을 레거시 플랜에 넣어달라는 영업 요청**: 거절한다. 레거시는 2019년 서면 계약 고객만 대상이다. 특별 가격이 필요하면
90	  세일즈 쿠폰이나 Enterprise 계약으로 한다.
91	- **레거시 가격을 올릴 수 있나?** 계약 해지(90일 통지) 후 재계약해야 한다. 지금까지 한 적 없다.
92	- **`legacy` 플래그와 `L-` 접두 중 무엇을 봐야 하나?** 같은 뜻이다. 코드에서는 `legacy` 플래그를 보고, 사람이 읽는 곳에서는 접두로 알아본다.
93	- **Business 유예 가격이 다시 필요하면?** `priceOverride`를 쓴다. `PLANS`의 가격을 계정별로 바꾸지 않는다.
94	- **플랜 이름을 바꾸면 청구서의 품목 이름도 바뀌나?** 발행 시점의 이름을 청구서에 저장하므로 과거 청구서는 안 바뀐다.
95	

1	import { test } from 'node:test'
2	import assert from 'node:assert/strict'
3	import { cycleBounds, prorate } from '../src/proration.js'
4	
5	test('cycleBounds: anchor before the date', () => {
6	  assert.deepEqual(cycleBounds(10, '2026-03-15'), { start: '2026-03-10', end: '2026-04-10' })
7	})
8	
9	test('cycleBounds: anchor after the date goes to previous month', () => {
10	  assert.deepEqual(cycleBounds(20, '2026-03-05'), { start: '2026-02-20', end: '2026-03-20' })
11	})
12	
13	test('cycleBounds rejects anchor outside 1..28', () => {
14	  assert.throws(() => cycleBounds(31, '2026-03-05'), RangeError)
15	})
16	
17	test('prorate: remaining days over cycle days, truncated', () => {
18	  const cycle = { start: '2026-03-10', end: '2026-04-10' } // 31 days
19	  assert.equal(prorate(99000, cycle, '2026-03-25'), Math.floor((99000 * 16) / 31))
20	})
21	

File created successfully at: _jwd/run-c58dfa52/docs/proration-code-vs-policy.md (file state is current in your context — no need to Read it back)

1	export const PLANS = [
2	  { id: 'starter', name: 'Starter', monthlyPrice: 29000, seatLimit: 5, legacy: false },
3	  { id: 'team', name: 'Team', monthlyPrice: 99000, seatLimit: 20, legacy: false },
4	  { id: 'business', name: 'Business', monthlyPrice: 290000, seatLimit: 100, legacy: false },
5	  { id: 'L-startup-2019', name: 'Startup (2019)', monthlyPrice: 49000, seatLimit: 10, legacy: true },
6	  { id: 'L-growth-2019', name: 'Growth (2019)', monthlyPrice: 149000, seatLimit: 30, legacy: true },
7	]
8	
9	export function findPlan(id) {
10	  const plan = PLANS.find((p) => p.id === id)
11	  if (!plan) throw new Error(`unknown plan: ${id}`)
12	  return plan
13	}
14	

The file _jwd/run-a45e3681/src/plans.js has been updated successfully. (file state is current in your context — no need to Read it back)

1	export const PLANS = [
2	  { id: 'starter', name: 'Starter', monthlyPrice: 29000, seatLimit: 5, legacy: false },
3	  { id: 'team', name: 'Team', monthlyPrice: 99000, seatLimit: 20, legacy: false },
4	  { id: 'business', name: 'Business', monthlyPrice: 290000, seatLimit: 100, legacy: false },
5	  { id: 'L-startup-2019', name: 'Startup (2019)', monthlyPrice: 49000, seatLimit: 10, legacy: true },
6	  { id: 'L-growth-2019', name: 'Growth (2019)', monthlyPrice: 149000, seatLimit: 30, legacy: true },
7	]
8	
9	export function findPlan(id) {
10	  const plan = PLANS.find((p) => p.id === id)
11	  if (!plan) throw new Error(`unknown plan: ${id}`)
12	  return plan
13	}
14	

The file _jwd/run-bcc92fb8/src/plans.js has been updated successfully. (file state is current in your context — no need to Read it back)

1	export const PLANS = [
2	  { id: 'starter', name: 'Starter', monthlyPrice: 29000, seatLimit: 5, legacy: false },
3	  { id: 'team', name: 'Team', monthlyPrice: 99000, seatLimit: 20, legacy: false },
4	  { id: 'business', name: 'Business', monthlyPrice: 290000, seatLimit: 100, legacy: false },
5	  { id: 'L-startup-2019', name: 'Startup (2019)', monthlyPrice: 49000, seatLimit: 10, legacy: true },
6	  { id: 'L-growth-2019', name: 'Growth (2019)', monthlyPrice: 149000, seatLimit: 30, legacy: true },
7	]
8	
9	export function findPlan(id) {
10	  const plan = PLANS.find((p) => p.id === id)
11	  if (!plan) throw new Error(`unknown plan: ${id}`)
12	  return plan
13	}
14	

The file _jwd/run-a8623e81/src/plans.js has been updated successfully. (file state is current in your context — no need to Read it back)

1	export const PLANS = [
2	  { id: 'starter', name: 'Starter', monthlyPrice: 29000, seatLimit: 5, legacy: false },
3	  { id: 'team', name: 'Team', monthlyPrice: 99000, seatLimit: 20, legacy: false },
4	  { id: 'business', name: 'Business', monthlyPrice: 290000, seatLimit: 100, legacy: false },
5	  { id: 'L-startup-2019', name: 'Startup (2019)', monthlyPrice: 49000, seatLimit: 10, legacy: true },
6	  { id: 'L-growth-2019', name: 'Growth (2019)', monthlyPrice: 149000, seatLimit: 30, legacy: true },
7	]
8	
9	export function findPlan(id) {
10	  const plan = PLANS.find((p) => p.id === id)
11	  if (!plan) throw new Error(`unknown plan: ${id}`)
12	  return plan
13	}
14	

The file _jwd/run-f25c4df7/src/plans.js has been updated successfully. (file state is current in your context — no need to Read it back)