서버 명세서

[tmvkrpxl0]

아래에서 말하는 파라미터는 /url/ 를 말하는 것임
예를 들어 /checklist 에 userid라는 파라미터가 필요하다면 이는 URL은 다음과 같을 것: /checklist/<userid>

/auth/oauth

GET

• 구현됨
  google Oauth 로그인 페이지. 이 페이지에서 구글 계정으로 로그인시 /oauthsuccess 로 리디렉션함.

/auth/oauthsuccess

GET

• 구현됨
  /oauth 에서 리디렉션되는 엔드 포인트. 유저가 이미 로그인 되어 있지 않을 경우, 구글 계정의 이메일이 존재하는지 확인함. 구글 계정이 이미 존재한다면, 비밀번호 작성을 건너뛰고 바로 로그인함. 해당 구글 계정으로 가입한 계정이 존재하지 않는다면 가입 페이지로 리디렉션 함.
  이때 사용한 구글 계정의 이메일이 공식적으로 등록된 학교 이메일이냐 아니냐에 따라서 기능이 다음으로 나뉨:

공식 학교 이메일일 때:

가입 페이지에서 이메일란과 학교 선택란이 자동으로 작성되며 이는 수정 불가능함.

공식 학교 이메일이 아닐 때:

가입 페이지에서 선택한 학교의 관리자에게 요청을 보냄. 수락시에만 가입할 수 있음.
만약 학교 관리자가 공식 학교 이메일만 허용하면 요청이 자동으로 Forbidden 코드로 거부됨. 이는 공식 학교 이메일을 사용하는 학교의 기본 설정임.

전용 이메일이 없는 학교의 경우, 언제나 공식 학교 이메일이 아닐 때와 동일하게 취급함.
이때 전송되는 JSON은 아래 구조체의 필드들중 UserId랑 DbId를 제외한 나머지 전부 포함하며 JWT로 보호되어 있음:

ahl-backend/models/accounts.go

Lines 6 to 13 in f9872ed

	type Account struct {
	DbId `json:"id"`
	UserId `json:"user_id"`
	Name string `json:"name"`
	Email string `json:"email"`
	Password []byte
	PermissionInfo `json:"permission"`
	}

/auth/register

PUT

• 구현됨
  서버 가입용 엔드포인트. 아래 구조체의 필드들중 UserId랑 DbId를 제외한 나머지 전부를 포함하는, JWT로 보호된 JSON을 인자로 받음.
  

  ahl-backend/models/accounts.go

  Lines 6 to 13 in f9872ed

  	type Account struct {
  	DbId `json:"id"`
  	UserId `json:"user_id"`
  	Name string `json:"name"`
  	Email string `json:"email"`
  	Password []byte
  	PermissionInfo `json:"permission"`
  	}

  
  이때 위 구조체를 담을 때 사용할 claim은 "account"임
  가입 요청을 보내면 가입 페이지에서 선택한 학교의 관리자에게 요청을 보냄. 수락시에만 가입할 수 있음.
  만약 해당 요청의 이메일이 공식 학교 이메일이 아니고, 학교 관리자가 공식 학교 이메일만 허용하면 요청이 자동으로 Forbidden 코드로 거부됨. 이는 공식 학교 이메일을 사용하는 학교의 기본 설정임.

만약 동일한 이메일로 이미 등록이 되어 있다면 즉시 Forbidden 코드로 거부됨.
만약 Forbidden 이외의 다른 코드로 거부하고자 한다면, 위 둘은 무조건 같은 코드를 써야 함; 다량의 가입 요쳥을 보내서 가입된 이메일을 식별할 수 없도록 해야 할 것

/auth/login

POST

• 구현됨
  서버 로그인용 엔드포인트. 아래 구조체의 내용을 jwt로 암호화해서 보내야 함.
  

  ahl-backend/handlers/auth.go

  Lines 15 to 18 in f9872ed

  	var loginData struct {
  	Email string `json:"email" binding:"required"`
  	Password string `json:"password" binding:"required"`
  	}

  
  로그인 성공시 Ok와 jwt로 암호화된 토큰으로 응답함, 실패시 Unauthorized를 보냄.

/schedule

GET - 선택사항 파라미터:[날짜, user id(선택사항)]

• 구현됨
  유저의 시간표를 가져오는 엔드포인트. 시간표를 가져올 날짜로는 만약 파라미터로 날짜가 전달되었다면 그 날짜를, 전달되지 않았다면 해당 요청을 보낸 당일의 날짜를 사용함. 그리고 해당 날짜의 일주일 전체의 시간표를 반환함.
  시간표를 가져올 대상 유저는, user id가 파라미터로 전달되었다면 해당하는 유저, 그렇지 않다면 요청을 보낸 유저.
  대상 유저의 시간표가 로그인된 유저에게 공개되어 있다면, userid에 해당하는 유저의 시간표를 반환함.
  언제나 자기 자신에게 시간표는 공개되어 있음.
  이때 시간표로 반환하는 JSON은 아래 구조체가 여러개 들어있는 JSON ARRAY임: https://github.com/dshslife/ahl-backend/blob/main/models/timetable.go#L5-L12
  불필요한 정보 전송을 방지하기 위해 위 구조체에서 DB ID는 제외하고 보낼 것

로그인이 안되있을 경우: Unauthorized 반환
시간표를 가져올 대상 유저가 관리자 또는 학생이 아닌 경우: Forbidden 반환
로그인된 계정이 관리자 계정이 아니고, 시간표를 가져올 대상 유저의 시간표가 공개되어 있지 않을 경우: Forbidden 반환
날짜가 이상한 경우: Bad Request 반환
User Id가 잘못되거나 해당하는 유저가 없는 경우: Bad Request 반환

/user

GET - 파라미터:[user id(선택사항)]

• 구현됨
  유저의 유저 정보를 가져오는 엔드포인트.
  파라미터 user id는 선택사항으로, 이 파라미터가 없다면 현재 로그인된 유저를, 있다면 user id에 해당하는 유저를 대상으로 함.
  아래 구조체의 PermissionInfo가 무엇이냐에 따라서 JSON이 필드들이 달라질 수 있음: https://github.com/dshslife/ahl-backend/blob/main/models/accounts.go#L6-L13
  또한 여기서 DBID는 제외하고 보낼 것.
  로그인이 안되있을 경우: Unauthorized 반환
  현재 로그인된 유저가 관리자가 아니고, 대상 유저가 자기 자신이 아닌 경우: Unauthorized 반환

PUT - 파라미터[user id(선택사항)]

• 구현됨
  로그인된 유저의 유저 정보를 업데이트하는 엔드포인트.
  파라미터 user id는 선택사항으로, 이 파라미터가 없다면 현재 로그인된 유저를, 있다면 user id에 해당하는 유저를 대상으로 함.
  아래 구조체를 클라이언트에서 dbid, userid를 제외하고 보냄: https://github.com/dshslife/ahl-backend/blob/main/models/accounts.go#L6-L13

만약 Permission Info가 Student일 때:

Timetable은 서버에서 무시함.
ChecklistId는 서버에서 무시함.
SchoolId, Grade, Class, Number 변경은 기존 학교 관리자에게 요청함 - 아직 구체적인 규격 사항 없음

로그인이 안되있을 경우: Unauthorized 반환
현재 로그인된 유저가 관리자가 아니고, 대상 유저가 자기 자신이 아닌 경우: Unauthorized 반환

만약 Permission Info가 Teacher일 때:

SchoolId 변경은 기존 학교 관리자에게 요청함 - 아직 구체적인 규격 사항 없음

만약 Permission Info가 Admin일 때:

(따로 처리 필요 없음, 전부다 수용)

만약 Permission Info가 Unknown일 때:

바로 Bad Request 반환

전송되는 모든 Permission Info는 기존과 똑같은 Permission Level이어야 함, 그렇지 않으면 Bad Request 반환*
이는 관리자가 실수로 자기 계정 등급을 바꾸는 것을 방지하기 위해, 관리자에게도 적용됨

/map

GET - 파라미터:[school id]

• 구현됨
  현재 로그인된 유저의 학교 지도 이미지를 가져오는 엔드포인트. 로그인된 유저가 관리자 계정일 때만 school id 파라미터를 인식함. 이때는 해당하는 학교의 지도 이미지를 반환함.

지도가 없는 경우: Not Found
로그인된 유저가 관리자 계정인데 school id가 없는 경우: Bad Request
로그인된 유저가 Unknown인 경우: Forbidden

PUT - 파라미터:[school id], 파일 업로드 필수

• 구현됨
  현재 로그인된 유저의 학교 지도 이미지를 업로드하는 엔드포인트. 로그인된 유저가 관리자 계정일 때만 school id 파라미터를 인식함. 이때 대상 학교는 school id에 해당하는 학교가 됨. 이때 업로드는 학교 선생님만 업로드할 수 있음.

파일 업로드 과정에 문제가 있는 경우: Internal Server Error
로그인된 유저가 선생님 또는 관리자가 아닌 경우: Forbidden
로그인된 유저가 관리자지만 school id가 없는 경우: Bad Request

/checklist

GET - 파라미터:[userid(선택사항)]

• 구현됨
  userid로 전달된 유저의 체크리스트중, 로그인된 유저에게 공개된 것들을 가져옴. userid가 전달된 것이 없으면 로그인된 유저 본인의 userid를 사용함.
  만약 대상 유저가 학생이 아닌 경우: Bad Request
  만약 대상 유저가 존재하지 않을 경우: 404 NOT FOUND
  userid가 이상한 경우: Bad Request

PUT - JSON BODY: CheckList

• 구현됨
  로그인된 유저 본인의 체크 리스트를 업데이트함. 이때 전달하는 JSON BODY는 다음처럼 CheckListItems의 배열이어야 함: https://github.com/dshslife/ahl-backend/blob/main/models/checklist.go#L8
  만약 로그인된 유저가 학생이 아닌 경우: Forbidden
  JSON BODY 데이터가 없거나 이상한 경우: Bad Request
  요청이 제대로 이루어졌으면 Ok 반환

/event

GET - 파라미터:[년, 월, URL 예시: /event/2005/06]

• 구현됨
  해당 년도의 해당 달의 학사일정을 전부다 반환. 이를 구현할 때, 먼저 Events 구조체를 먼저 DB에서 가져온 이후 Events 필드를 통째로 반환할 수 있을 것임: https://github.com/dshslife/ahl-backend/blob/main/models/Events.go#L3-L19
  만약 로그인된 유저가 학생 또는 선생님이 아닌 경우: Forbidden
  파라미터가 잘못되거나 없는 경우: Bad Request
  요청이 제대로 이루어졌으면 EventEntry 배열을 Ok와 반환함

PUT - 파라미터:[년, 월, URL 예시: /event/2005/06], JSON BODY: EventEntry 배열

• 구현됨
  해당 년도의 해당 달의 학사일정을 JSON BODY로 전달받은 EventEntry 배열로 대체함.
  https://github.com/dshslife/ahl-backend/blob/main/models/Events.go#L10-L19
  만약 로그인된 유저가 선생님이 아닌 경우: Forbidden
  파라미터가 잘못되거나 없는 경우: Bad Request
  요청이 제대로 이루어졌으면 Ok를 반환함.

/meal

/GET

• 구현됨
  로그인된 유저의 학교의 오늘 급식을 반환함. 몇몇 학교는 점심/저녁에 다른 이름을 부여하여 여러개의 급식표가 있기도 한데, 이를 전부다 가져와서 보여줌.
  만약 로그인된 유저가 학생 또는 선생님이 아닌 경우: Forbidden
  요청이 제대로 이루어졌으면 Meal을 Ok와 반환함.
  TODO: 아직 Meal 구조체 없음

[tmvkrpxl0]

유저 토큰은 변경되지 않으니, 토큰을 유저 브라우저 캐시에 저장하고, 서비스 접속시 해당 토큰을 바로 재사용하여 바로 로그인하는 방식으로 자동 로그인을 구현할 수 있을 것.

[tmvkrpxl0]

급식 출발 시간 알림 기능은 이전에 만든 급식표 알리미보다 더 체계적으로 만들 수 있는데, 학교에서의 인증과 계정이 있으므로 누가 무슨 반인지 확실하게 확인할 수 있고, 같은 학교의 다른 반에만 메세지를 보낼 수 있도록 제한할 수 있으며, 거기에다가 누가 반장인지 구분할 수만 있다면 반장만 다음 반에 메세지를 보낼 수 있도록 하여 서비스 악용을 방지할 수 있을 것임.

[ron1214x]

시간표에 수업 교실 위치 주는 거 있으면 좋겠고, 지도 확인에서 수업 교실 및 교무실 위치 확인하는 거를 선택 같은 거로 나누거나 할 수 있을지는 모르겠어서 그거 설명 좀 해줬으면 좋겠음. 그리고 시간표의 경우 선생님이면 시간표 설정, 학생이면 보고, 공개/비공개 설정하고, 친구 거 확인하기처럼 Permission Info에 따라 나누는 게 좋지 않을까 싶음. 관리자들 전용 기능 개발은 필수고(우리가 관리해야됨) 메시지, 출결 처리, 생기부 기록, 공지, 푸시 알림 + 에타 같은 커뮤니티 구현 등은 나중에 추후 업데이트로 작업해보지 않을까 싶음.

[tmvkrpxl0]

시간표 구조체에 이미 수업 위치 교실 포함되어 있어서 뺐어.
현재 지도가 그냥 이미지 1개라서 여러개로 분리하는거 없어.
현재 대다수의 엔드포인트가 "지금 로그인된 유저"를 대상으로 해서 몇개가 관리자 인식이 안되긴 하는데 이건 바꿔놓을께.