docs: 개발 가이드 추가 (#642)

* docs: 우산 이슈 설명 추가 * docs: v1 문서 이전 * docs: 코딩 컨벤션 추가 * docs: mermaid 문법 지원 * docs: 프로젝트 개요 추가 * docs: 실행방법 추가 * docs: 목차 정렬
jiphyeonjeon-42 · Aug 6, 2023 · 22a2d01 · 22a2d01
1 parent 67d0305
commit 22a2d01
Show file tree

Hide file tree

Showing 9 changed files with 202 additions and 39 deletions.
diff --git a/.github/ISSUE_TEMPLATE/umbrella.yml b/.github/ISSUE_TEMPLATE/umbrella.yml
@@ -13,6 +13,8 @@ body:
         2. 각 체크박스를 이슈로 전환하고, 시작 및 마감 날짜를 설정합니다.
         3. [프로젝트 로드맵](https://github.com/orgs/jiphyeonjeon-42/projects/8?query=is%3Aopen+sort%3Aupdated-desc)에서 전체 진행 과정을 확인합니다.
 
+        집현전 [공식 개발 가이드](https://jiphyeonjeon-42.github.io/backend/umbrella)에서 구체적인 활용법을 확인할 수 있습니다.
+
       value: |
         ```[tasklist]
         ### 할 일

diff --git a/docs/docs/convention.md b/docs/docs/convention.md
@@ -1,47 +1,31 @@
-# Commit 전략
+# 개발 컨벤션
 
-## commit의 기준
+## 커밋 메시지, PR 제목
 
-- commit은 아래 커밋 타입에 맞게 commit들을 분리한다.
+[Conventional Commits](https://www.conventionalcommits.org/ko/v1.0.0/) 규칙을 따릅니다. 머리말은 `feat`(기능 추가), `fix`(버그 수정), `refactor`(리팩터링) 등이 있습니다.
 
-## commit의 타입
+### 예시
 
-- FEAT: 기능을 추가 또는 수정
-- ENV: 개발 환경을 추가 또는 수정 (eslint 변경, dockerfile 변경 등)
-- FIX: 버그를 해결
-- DOCS: 문서를 수정 ([README.md](http://readme.md/) 변경, swagger)
-- STYLE: 코드 스타일 변경 (prettier, npm run lint 등)
-- REFACT: 코드를 리팩토링, 기능은 같고 코드가 변경
-- TEST: 테스트 코드를 추가 또는 수정
-- MERGE: 풀 리퀘스트 머지할 경우
-- CHORE: 단순오타
-- WIP: working in process 아직 작업중인 내용
-
-## commit 예시
+```
+feat: `auth/` 경로에 로그인 기능 추가
+test: 리뷰 삭제 서비스
+fix: 도서 상세정보 검색시 특수문자 포함
+refactor: for of를 map으로 변경
+```
 
 ```
 ex)
-FIX: 모델 validation 오류 수정
+fix: 모델 validation 오류 수정
 
 - Book title 제목 default 값 추가
 - User intra 최소 길이 0으로 변경
 
 ex)
-FEAT: 로그인 기능 추가
-
-- auth/ api 추가
-
-ex)
-TEST: bookController 테스트 코드 추가 
+test: bookController 테스트 코드 추가 
 
 - 책 제목에 대한 유효성 테스트 추가
 ```
 
-## 네이밍
-**변수명, 함수명, 칼럼명, 파일명**은 **camelCase**를 사용한다.  
-**클래스명, 타입명**은 **PascalCase**를 사용한다.  
-**테이블명**은 **snake_case**를 사용한다.  
+## 코드 스타일
 
-## ts파일의 import
-(*).service.ts 파일을 import할 때는 카멜케이스로 (*)Service라고 import한다.  
-e.g.) users.service.ts를 import할 경우 `import * as usersService from ../users/users.service.ts`같이 적는다.
+eslint를 사용중이나 여러 문제가 있어 추후 변경될 수도 있습니다. (WIP)
diff --git a/docs/docs/explanation.md b/docs/docs/explanation.md
@@ -0,0 +1,108 @@
+# 프로젝트 개요
+
+## 디렉터리 구조
+
+```
+.
+├── backend
+│   └── src
+│       ├── @types # 타입 패치 파일
+│       ├── config # 환경 변수 파싱 및 설정
+│       ├── entity # typeorm 엔티티 및 뷰
+│       ├── v1 # 기존 API (/api)
+│       └── v2 # 신규 API (/api/v2)
+├── contracts # v2 API 명세
+├── database # 배포/로컬 mysql 데이터베이스 (주의: 업데이트/테스트되지 않음)
+├── docs # 개발 가이드
+├── nginx # nginx 설정 파일
+├── patches # 문제가 있는 패키지를 수정한 패치 파일
+└── scripts # AWS 배포 이후 docker-compose 실행용 스크립트
+```
+
+집현전 백엔드는 `contracts/`와 `backend/`로 나뉜 모노레포입니다.
+
+## 순서도 (V2)
+
+> 순서도 문법은 [mermaid 공식 문서](https://mermaid-js.github.io/mermaid/#/sequenceDiagram)를 참고해주세요.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant 프론트엔드
+  participant 백엔드
+  participant 데이터베이스
+
+  rect rgb(253, 242, 233)
+    Note right of 프론트엔드: 컨트롤러
+    프론트엔드 -->> 백엔드: HTTP 요청
+    opt
+      백엔드 --> 백엔드: 쿠키 파싱 및 사용자 인증 (미들웨어)
+      break 인증되지 않은 요청
+        백엔드 -x 프론트엔드: 401 Unauthorized
+      end
+    end
+    백엔드 -->> 백엔드: 쿼리 파싱 (ts-rest)
+    break 쿼리 오류
+      백엔드 --x 프론트엔드: 400 Bad Request
+    end
+  end
+
+  rect rgb(235, 245, 251)
+    Note left of 백엔드: 서비스
+    critical 비즈니스 로직 처리
+      백엔드 ->> 데이터베이스: 쿼리 요청 (typeorm)
+      데이터베이스 -->> 백엔드: 파싱된 쿼리 결과 (entity)
+      백엔드 ->> 백엔드: 연산
+    end
+  end
+
+  rect rgb(253, 242, 233)
+    Note right of 프론트엔드: 컨트롤러
+    alt 서버 내부 오류
+      백엔드 -x 프론트엔드: 500 Internal Server Error
+    else 성공,실패
+      백엔드 ->> 프론트엔드: HTTP 코드
+    end
+  end
+```
+
+점선: 라이브러리/프레임워크가 제공하는 기능
+
+### 컨트롤러
+
+- 프론트엔드에서 HTTP 요청을 보냅니다.
+- 인증이 필요한 경로일 시 미들웨어에서 쿠키를 파싱해 사용자를 인증(authentication)합니다. 인증되지 않은 요청일 시 401 Unauthorized[^auth]를 반환합니다.
+- [ts-rest] [^ts-rest]에서 쿼리를 파싱합니다. 올바르지 않은 쿼리일 시 400 Bad Request를 반환합니다.
+- 필요한 모든 정보를 인자에 담아 서비스 하나를 호출합니다.
+
+### 서비스
+
+- [typeorm](https://typeorm.io) [^typeorm] 또는 [mysql2](https://github.com/sidorares/node-mysql2) [^mysql2]로 데이터베이스에 접근해 필요한 자료를 가져옵니다.
+- 비즈니스 로직을 처리합니다.
+- 결과를 컨트롤러에게 반환합니다. 
+  - 성공시 DTO를 반환합니다.
+  - 서버 내부 오류는 예측이 불가능하므로 예외를 `throw`합니다.
+  - 인가(authorization) 오류 등 예측 가능한 실패는 `Error` 클래스를 **`throw`하지 않고** 명시적인 값으로 반환합니다. 
+
+### 컨트롤러
+
+- 서비스에서 반환한 값을 HTTP 코드와 body로 변환해 프론트엔드에게 반환합니다.
+- 반환값은 [ts-rest]에서 지정한 타입을 따라야 합니다.
+- 서버 내부 오류는 미들웨어에서 처리해 500 Internal Server Error를 반환합니다.
+
+[ts-rest]: https://ts-rest.com/
+[^auth]: https://stackoverflow.com//questions/3297048/403-forbidden-vs-401-unauthorized-http-responses#answer-6937030
+[^ts-rest]: 프론트엔드와 백엔드가 공유하는 `계약(contract)`을 작성해 타입 안전하게 HTTP 요청과 응답을 할 수 있게 해주는 라이브러리입니다.
+[^typeorm]: 데이터베이스 ORM입니다. select와 queryBuilder 사용시 타입 안전하지 않습니다.
+[^mysql2]: raw query 라이브러리입니다. 타입 안전하지 않습니다.
+
+## API 경로
+
+### V1
+
+로컬 서버의 `http://localhost:3000/swagger/` 경로를 참고해주세요.
+
+### V2
+
+로컬 서버의 `http://localhost:3000/swagger-v2/` 경로를 참고해주세요.
+
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,7 +1,5 @@
-# Welcome to Jiphyeonjeon Dev
+# 집현전 개발 가이드에 오신 것을 환영합니다
+
+## [프로젝트 실행하기](./setup.md)
+## [프로젝트 개요](./explanation.md)
 
-## 문서 추가하는 방법
-- docs 폴더 아래에 파일을 추가한다. 파일명은 영어로 한다.
-- 반드시 # 으로 제목을 추가한다. 목차의 이름이 된다. 한글로 해도 된다.
-- 로컬에서 어떻게 보일지 테스트해보고 싶으면 mkdocs 를 설치해서 실행해보면 된다.
-- 디렉토리 내부에 파일을 만들수도 있다. 단 디렉토리 이름은 영어로 해야 한다.
diff --git a/docs/docs/setup.md b/docs/docs/setup.md
@@ -0,0 +1,31 @@
+# 개발 가이드
+
+## 실행하기
+
+1. 백엔드 모노레포를 사용하기 위해 `pnpm`을 설치해주세요.
+
+```sh
+corepack prepare pnpm@latest --activate
+```
+
+2. 패키지들을 설치해주세요.
+
+```sh
+pnpm install
+```
+
+3. `backend/`가 `contracts/` 패키지에 의존하므로, 터미널 창을 2개 준비해주세요.
+
+```sh
+# 터미널 #1
+cd contracts
+pnpm dev
+
+# 터미널 #2
+cd backend
+pnpm dev
+```
+
+4. 올바르게 실행된다면 `https://localhost:3000/swagger-v2` 경로에 접속해 API 문서를 확인하실 수 있습니다.
+
+![swagger-v2](https://github.com/jiphyeonjeon-42/backend/assets/54838975/21c160f9-150b-4321-a9fa-0c61842477b0)
diff --git a/docs/docs/umbrella.md b/docs/docs/umbrella.md
@@ -0,0 +1,27 @@
+# 우산 이슈란
+
+우산 이슈는 [tasklist]를 활용해 1주일 가량 걸리는 작업을 여러 세부 이슈로 나누어 구체적으로 관리할 수 있게 도와줍니다.
+
+## 사용 방법
+
+[이슈 추가하기](https://github.com/jiphyeonjeon-42/backend/issues/new/choose)
+
+- 1~4일가량 소요되는 작업을 관리합니다.
+- [tasklist]를 활용해 작업을 세분화합니다.
+- 프로젝트 로드맵에서 전체 진행 과정을 세부적으로 확인합니다.
+
+![tasklist](https://github.com/jiphyeonjeon-42/backend/assets/54838975/46d46bb2-7b90-4b94-b300-1760aa9590a1)
+
+[![](https://github.com/jiphyeonjeon-42/backend/assets/54838975/cdc2964e-a9df-41e4-a3c9-55e0b908a806)][로드맵]
+
+1. 작업을 1~3시간 단위로 해결 가능한 작은 단위로 쪼개 [태스크 리스트][tasklist]에 적어주세요.
+2. 추가한 세부 작업들을 `...` 버튼을 눌러 이슈로 전환해주세요.
+3. 변경된 세부 이슈들에 시작일과 마감일을 추가해주세요.
+4. 맡은 세부 이슈에 [담당자(assignee)][담당자]를 추가해주세요.
+
+[프로젝트 로드맵][로드맵]에서 진행 과정, 일정, 담당자를 [차트][블로그]로 확인할 수 있습니다.
+
+[로드맵]: https://github.com/orgs/jiphyeonjeon-42/projects/8?query=is%3Aopen+sort%3Aupdated-desc
+[블로그]: https://github.blog/changelog/2023-01-31-roadmap-in-projects-public-beta/
+[담당자]: https://docs.github.com/ko/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users
+[tasklist]: https://docs.github.com/ko/issues/managing-your-tasks-with-tasklists/creating-a-tasklist
diff --git a/docs/docs/error.md → docs/docs/v1/error.md b/docs/docs/error.md → docs/docs/v1/error.md
@@ -1,4 +1,5 @@
 # 에러 코드 (Error code)
+
 ## Common Error Code (0번대)
 |Error Code|Constant Name|Description|
 |:----------:|:-------------|:-----------|
@@ -127,4 +128,4 @@
 |904| NOT_FOUND_TAGS | 존재하지 않는 tagId |
 |910| INVALID_INPUT_TAG_ID | 유효하지 않은 양식의 tagId |
 
----
+---
diff --git a/docs/docs/v1/index.md b/docs/docs/v1/index.md
@@ -0,0 +1,5 @@
+# v1 개발 문서
+
+> **경고**
+>
+> v2 이전 버전에 대한 개발 문서입니다. 업데이트되지 않았거나 잘못된 정보가 있을 수 있습니다. 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -1,8 +1,15 @@
-site_name: 집현전 문서
+site_name: 집현전 개발 가이드
 theme:
   name: material
   language: ko
 
 extra:
   static_dirs:
-    - docs/image
+    - docs/image
+
+markdown_extensions:
+  - footnotes
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid