Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,5 @@ FRONT_BASE_URL=
SUDAM_SEED_ENABLED=
# 시드 선생님 카카오 회원번호. 비우면 가짜 계정 seed-teacher-1
SUDAM_SEED_TEACHER_KAKAO_ID=
# true면 재기동 때 시드 선생님의 과외를 지우고 처음 상태로 다시 만든다 (SUDAM_SEED_ENABLED도 true여야 함). 리셋 후 다시 비운다
SUDAM_SEED_RESET=
31 changes: 21 additions & 10 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ com.sudam
├── handler/GeneralExceptionHandler # @RestControllerAdvice
├── entity/BaseTimeEntity.java # createdAt / updatedAt 감사
├── crypto/AccountNumberConverter # 계좌번호 AES-256-GCM JPA 변환기
├── seed # 시연용 가상 데이터 (sudam.seed.enabled = true일 때만 빈 생성). DemoSeedRunner → DemoSeedService, DemoIncomeCard · DemoLessonPlan(순수 함수)
├── seed # 시연용 가상 데이터 (sudam.seed.enabled = true일 때만 빈 생성). DemoSeedRunner → DemoSeedService(→ DemoSeedResetter: sudam.seed.reset일 때 삭제), DemoIncomeCard · DemoLessonPlan(순수 함수)
├── config # SecurityConfig, JpaConfig, SwaggerConfig, ClockConfig(Asia/Seoul Clock 빈 — 서비스는 LocalDateTime.now(clock))
└── security # 인증 인프라 (코드 enum은 domain/auth에 둔다)
├── filter/JwtAuthenticationFilter
Expand Down Expand Up @@ -160,32 +160,42 @@ GET /api/v1/users/me/settings profile · provider만 DB 값, 소개서

### 시연용 가상 데이터

과외 · 참여자 생성 API가 없어 시연 데이터를 부팅 때 만든다 (`global/seed`). 정산 서비스를 거치지 않고 엔티티를 직접 만들어 한 트랜잭션으로 저장한다(중간 실패 시 아무것도 남지 않음). 날짜는 모두 `Clock` 빈(Asia/Seoul) 기준 실행일의 상대값이다.
과외 · 참여자 생성 API가 없어 시연 데이터를 부팅 때 만든다 (`global/seed`). 정산 서비스를 거치지 않고 엔티티를 직접 만들어 한 트랜잭션으로 저장한다(중간 실패 시 아무것도 남지 않음). 정산 리포트만은 실제 리포트 생성기(`SettlementReportCreator`)로 만들어 통계 · 진도 표가 정산과 같은 계산으로 나온다. 날짜는 모두 `Clock` 빈(Asia/Seoul) 기준 실행일의 상대값이다.

**켜는 법** — `.env`(또는 환경 변수)에 넣고 부팅한다. 프로파일이 아니라 이 값 하나로 켜고 끈다.

| 키 | 기본값 | 설명 |
| --- | --- | --- |
| `SUDAM_SEED_ENABLED` | `false` | `true`일 때만 실행기 빈이 생긴다 (`sudam.seed.enabled`) |
| `SUDAM_SEED_TEACHER_KAKAO_ID` | 빈 값 | 시드 선생님의 카카오 회원번호. 비우면 가짜 계정 `seed-teacher-1` |
| `SUDAM_SEED_RESET` | `false` | `SUDAM_SEED_ENABLED`와 함께 `true`면 재기동 때 시드 선생님의 과외를 지우고 처음 상태로 다시 만든다 (`sudam.seed.reset`) |

- 회원번호가 기본값이면 부팅 로그에 액세스 토큰을 한 번 출력한다 (30분 뒤 만료, 다시 받으려면 재부팅). 파일 · DB · 응답에는 남기지 않는다.
- 회원번호를 넣으면 실제 사람 계정이므로 토큰을 출력하지 않는다. 그 카카오 계정으로 한 번 로그인해 둔 회원이 있으면 그 회원에 데이터를 붙이고, 없으면 새로 만든다. 시연 때 카카오 로그인으로 들어간다.

**반복 실행** — 시드 선생님(KAKAO, 회원번호)에게 과외가 하나라도 있으면 아무것도 만들지 않고 `가상 데이터가 이미 있어 건너뜀` 로그만 남긴다. `ddl-auto: create`면 부팅마다 새로 만들어지고, `update`면 처음 한 번만 만들어진다.

**리셋 (UT 리허설 뒤 되돌리기)** — `update`(개발 서버)에서 리허설로 바뀐 데이터를 처음 상태로 돌린다.

1. `SUDAM_SEED_RESET=true`로 재기동한다. `DemoSeedResetter`가 시드 선생님의 과외와 그 아래 데이터(일정 · 교재 · 정책 · 설정 · 참여자 · 사이클 · 회차 · 기록 · 진도 · 리포트 · 청구 · 입금 · 교육비 조정)를 FK 역순으로 지우고, 같은 트랜잭션에서 시드를 다시 만든다. 다시 만들다 실패하면 삭제도 롤백된다.
2. User · TeacherProfile · 약관 동의는 지우지 않는다. 카카오로 로그인한 상태가 그대로 유지된다. 회원번호를 넣은 실제 계정이면 그 계정에서 손으로 만든 과외도 함께 지워진다.
3. 끝나면 `SUDAM_SEED_RESET`을 끄고 다시 재기동한다. 켜 둔 채면 재기동할 때마다 지워진다 (부팅 로그에 경고가 크게 찍힌다).

테이블이 늘면 `DemoSeedResetter.STATEMENTS`에 FK 순서대로 추가한다 (예: 리포트 열람 테이블은 `SettlementReport` 삭제 앞).

**데이터**

- 선생님 한서윤: 프로필(영어) + 현재 시행 중인 필수 약관 동의 → `GET /users/me`의 status = `ACTIVE`.
- 과외마다 공통: 영어 과외, 수업 일정, 교재 1권, 선불 정책(사이클 1부터, 국민은행 · 가짜 계좌, 예금주 한서윤), 공유 설정, 학부모(어머님, 가짜 번호 `010000000xx`, 링크 토큰 발급).
- 수입 화면(T-15)용 4개 — 사이클 1 SETTLED · 사이클 2 IN_PROGRESS, 사이클 2를 청구하는 선불 '다음 N회차' 청구. 회차 · 기록은 없다.
- 수입 화면(T-15) · 리포트(T-13 · T-14)용 4개 — 사이클 1(실행 5주 전 시작, 1주 전 SETTLED) · 사이클 2 IN_PROGRESS, 사이클 2를 청구하는 선불 '다음 N회차' 청구.
- 사이클 1에 정산 회차만큼 회차 · 기록 · 진도(회차마다 2단원)를 깔고, 실제 정산 순서(정산 → 다음 사이클 → 리포트 → 청구)로 리포트를 만들어 청구 `report_id`에 연결한다. 실제 정산은 사이클을 닫을 때 항상 리포트를 만들므로 4명 모두 리포트가 있다. 이해도 분포는 학생마다 다르게 두었다.

| 학생 | 정산 회차 · 수업료 | 청구 상태 | 카드 아래 줄 |
| --- | --- | --- | --- |
| 박지후 | 8 · 360,000 | CONFIRM_REQUESTED (실행 2시간 전 학부모 요청) | `PARENT_CONFIRMED` |
| 윤서아 | 8 · 360,000 | PENDING, 미입금 알림 켬 | `REMINDER_SCHEDULED` |
| 이도윤 | 4 · 200,000 | PARTIAL (실행 하루 전 120,000 입금) | `PARTIAL_PAID` |
| 김하린 | 8 · 280,000 | PAID (실행 하루 전 전액 입금) | `NONE` |
| 학생 | 정산 회차 · 수업료 | 청구 상태 | 카드 아래 줄 | 사이클 1 리포트 (이해도 상/중/하, 숙제율) |
| --- | --- | --- | --- | --- |
| 박지후 | 8 · 360,000 | CONFIRM_REQUESTED (실행 2시간 전 학부모 요청) | `PARENT_CONFIRMED` | 있음 (6/2/0, 93%) |
| 윤서아 | 8 · 360,000 | PENDING, 미입금 알림 켬 | `REMINDER_SCHEDULED` | 있음 (2/5/1, 71%) |
| 이도윤 | 4 · 200,000 | PARTIAL (실행 하루 전 120,000 입금) | `PARTIAL_PAID` | 있음 (0/1/3, 50%) |
| 김하린 | 8 · 280,000 | PAID (실행 하루 전 전액 입금) | `NONE` | 있음 (5/3/0, 93%) |

- 시연용 김서아(T-09 · T-14) — 고1 · 선불 · 8회 360,000원(회당 45,000). 수업은 18:00~19:30, 실행일이 월 · 수 · 금이면 월 · 수 · 금, 아니면 실행일 요일과 그 뒤 2일 · 4일 요일(오늘이 항상 수업일). 사이클 1 IN_PROGRESS에 오늘 **전** 수업일 7회의 기록 · 진도(수능특강 영어, Unit 1~14). 오늘 회차 · 청구(선불 첫 청구 포함)는 없다.
- 안내일(`notified_at`)은 비어 있다. 목록은 `created_at`(실행 시각)으로 이번 달에 들어온다.
Expand All @@ -194,11 +204,12 @@ GET /api/v1/users/me/settings profile · provider만 DB 값, 소개서

1. 부팅 로그의 토큰을 복사하거나(기본 계정) 카카오로 로그인한 뒤 Swagger(`/swagger-ui.html`) **Authorize**에 넣는다. 부팅 로그에 김서아 `tutoringId` · 오늘 `scheduleId` · `originalDate`가 함께 찍힌다.
2. `GET /api/v1/invoices` → 요약 1,200,000 / 400,000 / 800,000, 카드 4장(박지후 → 윤서아 → 이도윤 → 김하린).
- 각 청구의 `reportId`로 `GET /api/v1/reports/{reportId}`와 `GET /api/v1/reports/{reportId}/invoice`를 열 수 있다.
3. `POST /api/v1/tutorings/{김서아 tutoringId}/records` (`scheduleId` = 오늘 요일 일정, `originalDate` = 오늘, 교재 진도 15~16) → 응답 `noInCycle: 8`, `settlement.settled = true`, `reportId` · `invoiceId`.
4. `GET /api/v1/reports/{reportId}` → 김서아 8/8 리포트.
5. `GET /api/v1/invoices` → 1,560,000 / 400,000 / 1,160,000, 카드 5장(김서아 '다음 8회차' 360,000이 입금 대기로 추가).

**배포에서 쓸 때 주의** — 시연이 끝나면 `SUDAM_SEED_ENABLED`를 끈다. `ddl-auto: create`면 재배포(재부팅)마다 처음 상태로 돌아간다. 기본 계정의 토큰이 서버 로그에 남으므로 로그 접근 범위를 확인한다.
**배포에서 쓸 때 주의** — 시연이 끝나면 `SUDAM_SEED_ENABLED`를 끈다. `ddl-auto: create`면 재배포(재부팅)마다 처음 상태로 돌아간다. `update`에서 옛 시드(리포트 없음)가 이미 있으면 한 번 `SUDAM_SEED_RESET=true`로 재기동해야 리포트가 생긴다. 기본 계정의 토큰이 서버 로그에 남으므로 로그 접근 범위를 확인한다.

## 아직 정해지지 않은 것

Expand Down
86 changes: 75 additions & 11 deletions src/main/java/com/sudam/global/seed/DemoIncomeCard.java
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@
import com.sudam.domain.invoice.entity.InvoiceSnapshot;
import com.sudam.domain.invoice.enums.InvoiceKind;
import com.sudam.domain.participant.entity.Participant;
import com.sudam.domain.record.enums.HomeworkResult;
import com.sudam.domain.record.enums.Understanding;
import com.sudam.domain.tutoring.entity.TutoringPolicy;
import com.sudam.global.seed.DemoLessonPlan.LessonNote;

import java.time.DayOfWeek;
import java.time.LocalDate;
Expand All @@ -20,8 +23,10 @@
import static java.time.DayOfWeek.WEDNESDAY;

/**
* 수입 화면(T-15) 카드 1장이 될 선불 과외. 회차 · 기록은 만들지 않고 사이클 2 청구 하나만 만든다.
* 수입 화면(T-15) 카드 1장이 될 선불 과외. 사이클 1을 정산하고 사이클 2를 청구한 상태로 만든다.
* 네 장을 합치면 요약이 1,200,000 / 400,000 / 800,000이 되도록 금액 · 상태를 맞췄다.
* 사이클 1에 회차 · 기록 · 진도를 깔고 정산 리포트를 만들어 청구에 연결한다 (T-13 · T-14).
* 실제 정산은 사이클을 닫을 때 항상 리포트를 만들므로, 시드도 모든 카드에 리포트를 둔다.
*
* @param studentName 학생 이름
* @param gradeLevel 학년 (1~12 = 초1~고3)
Expand All @@ -32,6 +37,7 @@
* @param lessonDays 수업 요일
* @param lessonStart 수업 시작 시각 (90분 수업)
* @param textbookName 교재 1권 이름
* @param notes 사이클 1 회차 기록 (정산 회차만큼, 오래된 순)
*/
record DemoIncomeCard(
String studentName,
Expand All @@ -42,37 +48,95 @@ record DemoIncomeCard(
boolean unpaidReminderEnabled,
List<DayOfWeek> lessonDays,
LocalTime lessonStart,
String textbookName
String textbookName,
List<LessonNote> notes
) {

static final int PARTIAL_PAID_AMOUNT = 120_000;

// 회차를 다 채워 정산했다고 두므로 (인정 회차 = 정산 회차) 기록 수가 정산 회차와 같아야 한다.
DemoIncomeCard {
if (notes.size() != settlementSessionCount) {
throw new IllegalArgumentException(
"기록 수가 정산 회차와 다릅니다. student=" + studentName + ", notes=" + notes.size());
}
}

// 학생마다 이해도 분포를 다르게 둔다 (T-14에서 박지후 상 · 윤서아 중 · 이도윤 하로 보이도록).
private static final List<LessonNote> JIHU_NOTES = List.of(
new LessonNote(Understanding.HIGH, null, "Unit 1~2 구문 복습", "주어 · 동사 찾기를 빠르게 함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 3~4 예문 해석", "to부정사 용법 구분이 정확함"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 5~6 오답 정리", "분사구문에서 의미상 주어를 헷갈려함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 7~8 예습", "지난 시간 오답을 스스로 고쳐 옴"),
new LessonNote(Understanding.HIGH, HomeworkResult.PARTIAL, "Unit 9~10 문장 쓰기", "관계대명사 문장 만들기를 잘함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 11~12 해석 연습", "긴 문장도 끊어 읽기가 안정적임"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 13~14 복습", "가정법 시제 바꾸기에서 실수가 있음"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 15~16 예습", "가정법 실수가 줄고 설명을 바로 이해함")
);
private static final List<LessonNote> SEOA_NOTES = List.of(
new LessonNote(Understanding.MEDIUM, null, "Unit 1~2 단어 정리", "지문은 이해하지만 단어를 자주 물어봄"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 3~4 요약 쓰기", "주제문 찾기는 맞히고 세부 내용에서 틀림"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 5~6 지문 복습", "관심 있는 과학 지문이라 집중이 좋았음"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.PARTIAL, "Unit 7~8 단어 암기", "단어 시험 18/25"),
new LessonNote(Understanding.LOW, HomeworkResult.NOT_DONE, "Unit 9~10 다시 읽기", "숙제를 못 해 와서 지문 이해가 늦었음"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 11~12 요약 쓰기", "요약 문장이 짧아졌지만 핵심은 잡음"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.PARTIAL, "Unit 13~14 오답 정리", "추론 문제 근거 찾기를 연습 중"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 15~16 예습", "단어 시험 23/25로 올라감")
);
private static final List<LessonNote> DOYUN_NOTES = List.of(
new LessonNote(Understanding.LOW, null, "Unit 1~2 개념 다시 보기", "시제 개념이 많이 비어 있어 기초부터 다시 설명"),
new LessonNote(Understanding.LOW, HomeworkResult.PARTIAL, "Unit 3~4 문제 풀기", "완료시제와 과거시제를 계속 헷갈려함"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 5~6 오답 정리", "조동사는 비교적 잘 따라옴"),
new LessonNote(Understanding.LOW, HomeworkResult.NOT_DONE, "Unit 7~8 다시 풀기", "학원 시험 기간이라 숙제를 못 함. 수동태 다시 설명")
);
private static final List<LessonNote> HARIN_NOTES = List.of(
new LessonNote(Understanding.MEDIUM, null, "Unit 1~2 단어 암기", "첫 수업. 발음은 좋고 철자를 자주 틀림"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 3~4 단어 암기", "단어 시험 27/30"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 5~6 예문 만들기", "새 단어로 문장을 스스로 만듦"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.PARTIAL, "Unit 7~8 단어 암기", "비슷한 뜻 단어를 헷갈려함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 9~10 누적 복습", "단어 시험 29/30"),
new LessonNote(Understanding.MEDIUM, HomeworkResult.DONE, "Unit 11~12 예문 만들기", "접두사 뜻 정리를 어려워함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 13~14 단어 암기", "접두사로 처음 보는 단어 뜻을 추측함"),
new LessonNote(Understanding.HIGH, HomeworkResult.DONE, "Unit 15~16 누적 복습", "누적 시험 56/60")
);

// 카드 표시 순서(확인 대기 → 입금 대기 → 일부 입금 → 입금 완료)와 같은 순서로 둔다. 시간은 김서아(18:00~19:30)와 겹치지 않게 골랐다.
static final List<DemoIncomeCard> ALL = List.of(
new DemoIncomeCard("박지후", 8, 8, 360_000, PaymentState.CONFIRM_REQUESTED, false,
List.of(TUESDAY, THURSDAY), LocalTime.of(16, 0), "천일문 기본"),
List.of(TUESDAY, THURSDAY), LocalTime.of(16, 0), "천일문 기본", JIHU_NOTES),
new DemoIncomeCard("윤서아", 9, 8, 360_000, PaymentState.PENDING, true,
List.of(MONDAY, WEDNESDAY), LocalTime.of(16, 0), "리딩튜터 중급"),
List.of(MONDAY, WEDNESDAY), LocalTime.of(16, 0), "리딩튜터 중급", SEOA_NOTES),
new DemoIncomeCard("이도윤", 11, 4, 200_000, PaymentState.PARTIAL, false,
List.of(SATURDAY), LocalTime.of(10, 0), "Grammar Zone 기본"),
List.of(SATURDAY), LocalTime.of(10, 0), "Grammar Zone 기본", DOYUN_NOTES),
new DemoIncomeCard("김하린", 7, 8, 280_000, PaymentState.PAID, false,
List.of(TUESDAY, FRIDAY), LocalTime.of(20, 0), "능률 VOCA 중학")
List.of(TUESDAY, FRIDAY), LocalTime.of(20, 0), "능률 VOCA 중학", HARIN_NOTES)
);

/***
* 함수 기능: 사이클 1 회차 날짜를 고른다. 사이클 시작일부터 수업 요일을 앞으로 세어 기록 수만큼.
* 사이클 1은 4주(28일)이므로 주 2회 8개 · 주 1회 4개가 정산일 전에 모두 들어간다.
* @param cycleStartDate 사이클 1 시작일
* @return 오래된 순 회차 날짜 (기록 수만큼)
*/
List<LocalDate> firstCycleLessonDates(LocalDate cycleStartDate) {
return DemoLessonPlan.lessonDatesFrom(cycleStartDate, lessonDays, notes.size());
}

/***
* 함수 기능: 사이클 2를 청구하는 선불 '다음 N회차' 청구를 만들고 카드에 맞는 상태로 바꾼다.
* 정산 서비스의 선불 청구와 같은 모양으로 만든다: 리포트 없음(시드는 리포트를 만들지 않음),
* 스냅샷의 인정 회차 · 시작일은 방금 정산한 사이클 1 기준 (회차를 다 채워 정산했으므로 인정 회차 = 정산 회차), 휴강 없음.
* 정산 서비스의 선불 청구와 같은 모양으로 만든다: 방금 정산한 사이클 1의 리포트를 연결하고,
* 스냅샷의 인정 회차 · 시작일은 사이클 1 기준 (회차를 다 채워 정산했으므로 인정 회차 = 정산 회차), 휴강 없음.
* @param policy 이 과외의 정책 (사이클 1부터 적용 = 사이클 2에도 적용)
* @param billedCycleId 청구 대상 사이클(사이클 2) ID
* @param reportId 사이클 1 정산 리포트 ID
* @param settledCycleStart 정산한 사이클 1의 시작일
* @param parent 확인 요청을 누른 학부모 (CONFIRM_REQUESTED일 때만 쓴다)
* @param now 실행 시각
* @return 저장 전 Invoice
*/
Invoice issueInvoice(TutoringPolicy policy, Long billedCycleId, LocalDate settledCycleStart, Participant parent,
LocalDateTime now) {
Invoice invoice = Invoice.issue(policy, billedCycleId, null, InvoiceKind.NEXT, policy.getTuitionFee(),
Invoice issueInvoice(TutoringPolicy policy, Long billedCycleId, Long reportId, LocalDate settledCycleStart,
Participant parent, LocalDateTime now) {
Invoice invoice = Invoice.issue(policy, billedCycleId, reportId, InvoiceKind.NEXT, policy.getTuitionFee(),
InvoiceSnapshot.of(policy, settlementSessionCount, settledCycleStart, List.of()));
switch (paymentState) {
case CONFIRM_REQUESTED -> invoice.requestConfirm(parent, now.minusHours(2));
Expand Down
Loading
Loading