Skip to content

Commit e9864be

Browse files
polyglot-kpolyglot-k
committed
feat : Add API documentation for authentication, events, FAQs, file uploads, inquiries, notices, payments, profiles, recommenders, and schools
- Created auth-api.md for user login, signup, and token reissue endpoints. - Added event-api.md for event management including registration, listing, detail retrieval, updating, and deletion. - Introduced faq-api.md for FAQ management with CRUD operations. - Implemented file-api.md for S3 file upload functionalities and guidelines. - Developed inquiry-api.md for 1:1 inquiry management including registration, listing, detail retrieval, and responses. - Established notice-api.md for managing notices with CRUD operations. - Created payment-api.md for payment processing including preparation and confirmation. - Added profile-api.md for user profile management with registration, retrieval, and updates. - Introduced recommender-api.md for registering and verifying recommenders. - Developed school-api.md for managing school information including listing and registration.
1 parent 166f880 commit e9864be

File tree

15 files changed

+2232
-5
lines changed

15 files changed

+2232
-5
lines changed

‎.vitepress/config.mts‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,43 @@ export default defineConfig({
2727
],
2828
"/docs/backend/": [
2929
{
30-
text: "모수 백엔드 문서",
30+
text: "개요",
31+
items: [{ text: "소개", link: "/docs/backend/" }],
32+
},
33+
{
34+
text: "사용자 관련 API",
35+
items: [
36+
{ text: "인증 API", link: "/docs/backend/auth-api" },
37+
{ text: "프로필 API", link: "/docs/backend/profile-api" },
38+
{ text: "추천인 API", link: "/docs/backend/recommender-api" },
39+
],
40+
},
41+
{
42+
text: "신청 관련 API",
43+
items: [
44+
{ text: "신청 API", link: "/docs/backend/application-api" },
45+
{ text: "개별 신청 학교 API", link: "/docs/backend/application-school-api" },
46+
],
47+
},
48+
{
49+
text: "콘텐츠 관리 API",
50+
items: [
51+
{ text: "공지사항 API", link: "/docs/backend/notice-api" },
52+
{ text: "문의 API", link: "/docs/backend/inquiry-api" },
53+
{ text: "FAQ API", link: "/docs/backend/faq-api" },
54+
{ text: "이벤트 API", link: "/docs/backend/event-api" },
55+
],
56+
},
57+
{
58+
text: "관리자 API",
59+
items: [{ text: "관리자 API", link: "/docs/backend/admin-api" }],
60+
},
61+
{
62+
text: "기타 API",
3163
items: [
32-
{ text: "소개", link: "/docs/backend/" },
33-
{ text: "시작하기", link: "/docs/backend/getting-started" },
34-
{ text: "개발 가이드", link: "/docs/backend/development-guide" },
64+
{ text: "결제 API", link: "/docs/backend/payment-api" },
65+
{ text: "학교 API", link: "/docs/backend/school-api" },
66+
{ text: "파일 업로드 API", link: "/docs/backend/file-api" },
3567
],
3668
},
3769
],

‎docs/backend/admin-api.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# 관리자 API
2+
3+
관리자 전용 데이터 조회 및 관리 API입니다.
4+
5+
## 학생 목록 조회
6+
7+
### GET /admin/students
8+
9+
필터 조건에 따른 학생 목록을 페이징하여 조회합니다.
10+
11+
**Parameters:**
12+
13+
- `filter` (query, required): 학생 목록 조회 필터
14+
- `name` (string, optional): 이름 필터
15+
- `phone` (string, optional): 전화번호 필터
16+
- `order` (string, optional): 정렬 순서 (desc 또는 asc, 기본값: desc)
17+
18+
**Request Example:**
19+
20+
```
21+
GET /admin/students?filter.name=홍길동&filter.phone=01012345678&filter.order=desc
22+
```
23+
24+
**Response:**
25+
26+
```json
27+
{
28+
"status": 200,
29+
"message": "학생 목록 조회 성공",
30+
"data": {
31+
"name": "홍길동",
32+
"birthDate": "2006-04-12",
33+
"phoneNumber": "010-1234-5678",
34+
"gender": "남자",
35+
"educationLevel": "ENROLLED",
36+
"schoolName": "서울고등학교",
37+
"grade": "HIGH_1",
38+
"examCount": 2
39+
}
40+
}
41+
```
42+
43+
**Response Fields:**
44+
45+
- `name` (string): 이름
46+
- `birthDate` (string): 생년월일 (yyyy-MM-dd 형식)
47+
- `phoneNumber` (string): 전화번호
48+
- `gender` (string): 성별
49+
- `educationLevel` (string): 학력
50+
- `schoolName` (string): 학교명
51+
- `grade` (string): 학년
52+
- `examCount` (integer): 시험 응시 횟수
53+
54+
---
55+
56+
## 신청 목록 조회
57+
58+
### GET /admin/applications
59+
60+
필터 조건에 따른 신청 목록을 페이징하여 조회합니다.
61+
62+
**Parameters:**
63+
64+
- `filter` (query, required): 신청 목록 조회 필터
65+
- `name` (string, optional): 이름 필터
66+
- `phone` (string, optional): 전화번호 필터
67+
- `applicationDate` (string, optional): 신청 일자 필터 (yyyy-MM-dd)
68+
69+
**Request Example:**
70+
71+
```
72+
GET /admin/applications?filter.name=홍길동&filter.phone=01012345678&filter.applicationDate=2025-07-10
73+
```
74+
75+
**Response:**
76+
77+
```json
78+
{
79+
"status": 200,
80+
"message": "신청 목록 조회 성공",
81+
"data": {
82+
"paymentNumber": "P3135455",
83+
"examinationNumber": "20250001",
84+
"name": "홍길동",
85+
"gender": "MALE",
86+
"birth": "2005-05-10",
87+
"phoneNumber": "010-1234-5678",
88+
"guardianPhoneNumber": "010-9876-5432",
89+
"educationLevel": "GRADUATED",
90+
"schoolName": "대치중학교",
91+
"grade": "HIGH_3",
92+
"lunch": "NONE",
93+
"subjects": ["생활과 윤리", "정치와 법"],
94+
"examSchoolName": "서울고등학교",
95+
"examDate": "2025-08-10",
96+
"admissionTicketImage": "https://s3.amazonaws.com/bucket/admission/2025-00001.jpg",
97+
"paymentStatus": "DONE",
98+
"paymentMethod": "CARD",
99+
"applicationDate": "2025-07-10T10:30:00Z",
100+
"admissionTicket": {
101+
"admissionTicketImageUrl": "https://s3.amazonaws.com/bucket/admission/2025-00001.jpg",
102+
"userName": "홍길동",
103+
"birth": "2005-05-10",
104+
"examinationNumber": "20250001",
105+
"subjects": ["생명과학", "지구과학"],
106+
"schoolName": "대치중학교"
107+
}
108+
}
109+
}
110+
```
111+
112+
**Response Fields:**
113+
114+
- `paymentNumber` (string): 결제 번호
115+
- `examinationNumber` (string): 수험 번호
116+
- `name` (string): 수험자 이름
117+
- `gender` (string): 성별 (MALE, FEMALE, PENDING)
118+
- `birth` (string): 생년월일
119+
- `phoneNumber` (string): 전화번호
120+
- `guardianPhoneNumber` (string): 보호자 전화번호
121+
- `educationLevel` (string): 학력 (ENROLLED, GRADUATED)
122+
- `schoolName` (string): 학교명
123+
- `grade` (string): 학년 (HIGH_1, HIGH_2, HIGH_3)
124+
- `lunch` (string): 도시락 신청 여부
125+
- `subjects` (array): 응시 과목 목록
126+
- `examSchoolName` (string): 시험 학교 이름
127+
- `examDate` (string): 시험 일자
128+
- `admissionTicketImage` (string): 수험표 이미지 URL
129+
- `paymentStatus` (string): 결제 상태
130+
- `paymentMethod` (string): 결제 방법
131+
- `applicationDate` (string): 신청 일시
132+
- `admissionTicket` (object): 수험표 정보
133+
134+
**결제 상태 (paymentStatus):**
135+
136+
- `PREPARE`: 준비 중
137+
- `DONE`: 완료
138+
- `EXPIRED`: 만료
139+
- `ABORTED`: 중단
140+
- `CANCELLED_DONE`: 취소 완료
141+
- `CANCELLED_ABORTED`: 취소 중단
142+
143+
**결제 방법 (paymentMethod):**
144+
145+
- `EASY_PAY`: 간편결제
146+
- `CARD`: 카드
147+
- `VIRTUAL_ACCOUNT`: 가상계좌
148+
149+
---
150+
151+
## 학교별 도시락 신청 수 조회
152+
153+
### GET /admin/lunches
154+
155+
학교별 도시락 신청 수를 조회합니다.
156+
157+
**Response:**
158+
159+
```json
160+
{
161+
"status": 200,
162+
"message": "도시락 신청 수 조회 성공",
163+
"data": {
164+
"schoolName": "서울고등학교",
165+
"count": 42
166+
}
167+
}
168+
```
169+
170+
**Response Fields:**
171+
172+
- `schoolName` (string): 학교 이름
173+
- `count` (integer): 도시락 신청 수
174+
175+
---
176+
177+
## 환불 목록 조회
178+
179+
### GET /admin/refunds
180+
181+
환불 목록을 페이징하여 조회합니다.
182+
183+
**Parameters:**
184+
185+
- `pageable` (query, required): 페이징 정보
186+
- `page` (integer): 페이지 번호
187+
- `size` (integer): 페이지 크기
188+
- `sort` (array): 정렬 조건
189+
190+
**Response:**
191+
192+
```json
193+
{
194+
"status": 200,
195+
"message": "환불 목록 조회 성공",
196+
"data": {
197+
"totalElements": 10,
198+
"totalPages": 1,
199+
"size": 10,
200+
"content": [
201+
{
202+
"refundId": 1,
203+
"examNumber": "20250001",
204+
"name": "홍길동",
205+
"phone": "010-1234-5678",
206+
"requestedAt": "2025-07-10T10:30:00Z",
207+
"completedAt": "2025-07-10T15:30:00Z",
208+
"paymentMethod": "CARD",
209+
"reason": "개인 사정으로 인한 취소"
210+
}
211+
],
212+
"number": 0,
213+
"first": true,
214+
"last": true,
215+
"empty": false
216+
}
217+
}
218+
```
219+
220+
**Response Fields:**
221+
222+
- `refundId` (integer): 환불 ID
223+
- `examNumber` (string): 수험 번호
224+
- `name` (string): 이름
225+
- `phone` (string): 전화번호
226+
- `requestedAt` (string): 환불 요청 일시
227+
- `completedAt` (string): 환불 완료 일시
228+
- `paymentMethod` (string): 결제 방법
229+
- `reason` (string): 환불 사유
230+
231+
---
232+
233+
## 학생 정보 엑셀 다운로드
234+
235+
### GET /admin/excel/students
236+
237+
전체 학생 정보를 엑셀 파일로 다운로드합니다.
238+
239+
**Response:**
240+
바이너리 데이터 (엑셀 파일)
241+
242+
**Response Headers:**
243+
244+
- `Content-Type`: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
245+
- `Content-Disposition`: `attachment; filename="students.xlsx"`
246+
247+
---
248+
249+
## 신청 목록 엑셀 다운로드
250+
251+
### GET /admin/excel/applications
252+
253+
전체 신청 목록을 엑셀 파일로 다운로드합니다.
254+
255+
**Response:**
256+
바이너리 데이터 (엑셀 파일)
257+
258+
**Response Headers:**
259+
260+
- `Content-Type`: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
261+
- `Content-Disposition`: `attachment; filename="applications.xlsx"`

0 commit comments

Comments
 (0)