사용자:Senouis/도전과제 서버 명세: 두 판 사이의 차이

← 이전 편집 다음 편집 →

시각위키텍스트

2025년 2월 27일 (목) 11:14 판

'미디어위키:Gadget-Achievement.js'를 통해 다음 과정을 수행

모든 결과에는 HTTP 응답 코드와 메세지를 응답 헤더에 포함할 것

2025년 6월 전까지 동작하는 물건을 만드는 것이 목표, 1월에 계획을 시작할 예정

예상 기술 스택

백엔드 개발 환경: Java + Spring^[1] 기반
- 현재 임시로 만든 임시 리포지토리에는 Node.js 기반으로 환경이 구축되어 있습니다. 아직 작업 시작한 부분이 없어 처음 상태 그대로입니다. 리셋 예정입니다.
DB: MongoDB로 확정
- 도전과제 서버의 진행도 데이터는 금융권 DB마냥 ACID가 중요한 데이터 종류가 아님: 빠른 로드가 우선됨
- 기존의 JSON 파일 저장 방식 대신 BSON 스키마를 사용해 저장하는 MongoDB 채택
- Spring Data for MongoDB로 DB를 연결할 예정

기능

처음 시작할 때

안내문(수집하게 되는 개인정보 등을 공시)과 함께 OAuth 2.0 인증 절차를 수행하는 링크를 추가
- 웹 페이지에 진입했을 때 Authorization Token과 Refresh 토큰이 모두 없는 경우
  - OAuth 확장 기능의 절차대로 리버티게임 서버 내 OAuth 기능에 Authorization 토큰 발급 요청
  - Authorization 코드 발급 기능을 먼저 구현한 후 PKCE 과정을 추가해 code_challenge 수행 필요
  - Redirect URI는 요청한 페이지로 설정
- 웹 페이지에 진입했을 때 Authorization 토큰이 있는 경우 or Refresh 토큰이 있는 경우
  - 즉시 OAuth 확장 기능의 절차대로 리버티게임 서버 내 OAuth 기능에 Access 토큰 및 Refresh 토큰 발급 요청
  - 쿠키에 Access 토큰 및 Refresh 토큰을 1주 유효기간으로 설정
아래 CRUD 요청에서 Access Token 뿐만 아니라 Refresh 토큰까지 만료된 경우 mw.notification으로 재연동을 요청할 것

Create

libertyga.me/achievement/v0/addition

웹 페이지에 진입하면 Access Token이 있는 경우에만 사용자 이름과 토큰을 헤더에 삽입하여 Create 수행, 없으면 로그인 요청을 mw.notification.notify()로 알림
- 다음과 같은 상황에서 스키마에 항목을 추가
  - 특정 classname을 가진 링크를 클릭했을 때
  - 특정 classname을 가진 div 태그를 발견했을 때 innerHTML에 있는 데이터를 itemname에 밀어넣음
- 요청 종류는 POST으로 설정
- POST 요청을 받은 서버는 profile 리소스를 요청하여 인증 성공시 DB에 사용자 이름으로 된 스키마 내에 항목을 하나 추가
  - 스키마 내부에는 항목 이름 및 설명을 문자와 숫자의 조합으로 자유롭게 생성 가능하며, 리버티게임 계정 유저의 DB ID 번호를 넘김
  - max_value를 설정해야 함: data-value 커스텀 HTML attribute에 기록된 값을 읽어야 함, 기본값은 1로 할 것
  - value는 1로 초기화
- 결과 반환은 상황에 따라 다름
  - value == maxvalue == 1이면 즉시 달성으로 결과 반환
  - value < maxvalue면 (1/n)을 붙여 결과 반환, 이후 달성할 때마다 value를 늘림
성공/실패할 경우 mw.notification.notify()로 알려야 함

Request Body

{
  "title": String,
  "description": String,
  "useIdx": Number
}

Response Body

{
  "success": true,
  "result": String
}

Read

libertyga.me:6400/achievement/v0/list/{user}

아이템 조회 과정
파라미터: user URL 파라미터는 숫자 ID
- 필터링 통과 실패 -> '제작자가 도전과제 이름을 잘못 지정했습니다.'라는 오류 메세지를 반환하여 mw.notification으로 송출하도록 함

Response Body

{
  "success": true,
  "result" : [
    {
      "title": String,
      "description": String,
      "progress": Number,
      "maxProgress": Number
    }
  ]
}

Delete (선택 구현)

libertyga.me:6400/achievement/v0/deletion

도전과제를 초기화하고 스키마만 남김
DELETE 요청이므로 헤더에 Access 토큰 부착할 것

기타

LocalStorage 브라우저 캐싱 기능을 추가할 것
HEAD 요청이 추가로 필요할 수 있으며, 자신의 데이터베이스 스키마의 SHA-256 해시값을 헤더에 포함해 반환할 것
- 반환한 해시값이 다르면 통짜 조회

↑ Apache Tomcat이 포함됩니다.

[1] Apache Tomcat이 포함됩니다.

[1]

@@ 39번째 줄: / 39번째 줄: @@
 ===Create===
-libertyga.me/achievement/v0/initialization
-*스키마 초기화 과정
-**웹 페이지에 진입하면 READ를 시도하고, 없다는 오류 응답이 왔을 때 Access Token이 있는 경우에만 사용자 이름과 토큰을 헤더에 삽입하여 Create 수행
-***요청 종류는 PUT으로 설정
-***PUT 요청을 받은 서버는 profile 리소스를 요청하여 인증 성공시 DB에 사용자 이름으로 된 스키마를 생성
-****스키마 내부에는 항목 이름을 문자와 숫자로 자유롭게 생성 가능하도록 이름 제약을 특수 문자 필터링 외에 걸지 않음
-****타입의 경우 integer로 강제해야 함
-**성공/실패할 경우 [https://doc.wikimedia.org/mediawiki-core/REL1_39/js/#!/api/mw.notification mw.notification.notify()]로 알려야 함
-{{#mermaid:
+libertyga.me/achievement/v0/addition
-sequenceDiagram
-    User->>Achievement Server: Request collection Re-creation with AT
-    Achievement Server ->> OAuth Server: Request Profile with AT
-    OAuth Server -->> Achievement Server: Give User Profile if it is right
-    Achievement Server -) MongoDB: Purge Document and Empty the collection
-    MongoDB -->> Achievement Server: Response Success
-    Achievement Server -->> User: Response Success
-}}
-libertyga.me/achievement/v0/addition/{user}/{itemname}
 * 웹 페이지에 진입하면 Access Token이 있는 경우에만 사용자 이름과 토큰을 헤더에 삽입하여 Create 수행, 없으면 로그인 요청을 mw.notification.notify()로 알림
@@ 64번째 줄: / 46번째 줄: @@
 *** 특정 classname을 가진 링크를 클릭했을 때
 *** 특정 classname을 가진 div 태그를 발견했을 때 innerHTML에 있는 데이터를 itemname에 밀어넣음
-**요청 종류는 PUT으로 설정
+**요청 종류는 POST으로 설정
-**PUT 요청을 받은 서버는 profile 리소스를 요청하여 인증 성공시 DB에 사용자 이름으로 된 스키마 내에 항목을 하나 추가
+**POST 요청을 받은 서버는 profile 리소스를 요청하여 인증 성공시 DB에 사용자 이름으로 된 스키마 내에 항목을 하나 추가
-***스키마 내부에는 항목 이름을 문자와 숫자의 조합으로 자유롭게 생성 가능하도록 이름 제약을 특수 문자 필터링 외에 걸지 않음
+***스키마 내부에는 항목 이름 및 설명을 문자와 숫자의 조합으로 자유롭게 생성 가능하며, 리버티게임 계정 유저의 DB ID 번호를 넘김
 ***max_value를 설정해야 함: data-value 커스텀 HTML attribute에 기록된 값을 읽어야 함, 기본값은 1로 할 것
 ***value는 1로 초기화
 **결과 반환은 상황에 따라 다름
 ***value == maxvalue == 1이면 즉시 달성으로 결과 반환
-***value < maxvalue면 (1/n)을 붙여 결과 반환, 이후 달성할 때마다 왼쪽 숫자를 늘림
+***value < maxvalue면 (1/n)을 붙여 결과 반환, 이후 달성할 때마다 value를 늘림
 *성공/실패할 경우 [https://doc.wikimedia.org/mediawiki-core/REL1_39/js/#!/api/mw.notification mw.notification.notify()]로 알려야 함
@@ 83번째 줄: / 65번째 줄: @@
      Achievement Server -->> User: Response Success
 }}
+==== Request Body ====
+<syntaxhighlight lang=json>
+{
+  "title": String,
+  "description": String,
+  "useIdx": Number
+}
+</syntaxhighlight>
+==== Response Body ====
+<syntaxhighlight lang=json>
+{
+  "success": true,
+  "result": String
+}
+</syntaxhighlight>
 ===Read===
-libertyga.me:6400/achievement/v0/item/{user}/{itemname}
+libertyga.me:6400/achievement/v0/list/{user}
 * 아이템 조회 과정
-* 파라미터: user와 itemname은 특수문자 필터링 필요
+* 파라미터: user URL 파라미터는 숫자 ID
 ** 필터링 통과 실패 -> '제작자가 도전과제 이름을 잘못 지정했습니다.'라는 오류 메세지를 반환하여 mw.notification으로 송출하도록 함
@@ 101번째 줄: / 97번째 줄: @@
 }}
-libertyga.me:6400/achievement/v0/allitem/{user}
+==== Response Body ====
+<syntaxhighlight lang=json>
-* 브라우저 캐싱 기능 추가할 경우 개발할 것
+{
-* 브라우저에 저장된 도전 과제 값을 전부 갱신하기 위해 전체 아이템을 요청(자주 사용하지 않는 API)
+  "success": true,
-** IndexedDB 필요
+  "result" : [
+     {
-{{#mermaid:
+      "title": String,
-sequenceDiagram
+      "description": String,
-    User->>Achievement Server: Request collection all read with AT
+      "progress": Number,
-    Achievement Server-)OAuth Server: Request Profile with AT
+      "maxProgress": Number
-    OAuth Server-->>Achievement Server: Give User Profile if it is right
+     }
-    Achievement Server-)MongoDB: Request read all of collection in database
+  ]
-    MongoDB -->> Achievement Server: Response Success
+}
-    Achievement Server-->>User: Response Success
+</syntaxhighlight>
-}}
-===Update===
-libertyga.me/achievement/v0/modification/{user}/{itemname}
-* POST 요청으로, 헤더에 Access 토큰 부착할 것
-* 진행도 향상용
-** 특정 classname을 가진 링크를 클릭했을 때
-** 특정 classname을 가진 div 태그를 발견했을 때 innerHTML에 있는 데이터를 itemname에 밀어넣음
-* 스키마에 항목이 있고, 달성하지 않은 경우(value < maxvalue) 값을 +1
-* 스키마에 항목이 없는 경우 addition API를 호출
-{{#mermaid:
-sequenceDiagram
-    User->>Achievement Server: Request collection update with AT
-     Achievement Server-)OAuth Server: Request Profile with AT
-    OAuth Server-->>Achievement Server: Give User Profile if it is right
-    Achievement Server-)MongoDB: Request read database
-    MongoDB -->> Achievement Server: Response Success(Fail이면 User에게 다시 입력 요청)
-    Achievement Server-)MongoDB: Request update database
-     MongoDB -->> Achievement Server: Response Success
-    Achievement Server-->>User: Response Success
-}}
-===Delete===
+===Delete (선택 구현) ===
-libertyga.me/achievement/v0/deletion/{user}/{itemname}
+libertyga.me:6400/achievement/v0/deletion
 * 도전과제를 초기화하고 스키마만 남김
@@ 157번째 줄: / 130번째 줄: @@
 == 기타 ==
-* 브라우저 캐싱 기능을 후에 추가할 것
+* LocalStorage 브라우저 캐싱 기능을 추가할 것
-** HEAD 요청이 추가로 필요하며, 자신의 데이터베이스 스키마의 SHA-256 해시값을 헤더에 포함해 반환할 것
+* HEAD 요청이 추가로 필요할 수 있으며, 자신의 데이터베이스 스키마의 SHA-256 해시값을 헤더에 포함해 반환할 것
 ** 반환한 해시값이 다르면 통짜 조회
 <references />