diff --git a/.github/ISSUE_TEMPLATE/umbrella.yml b/.github/ISSUE_TEMPLATE/umbrella.yml index b48a9ec0..fa8b2492 100644 --- 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 index a5cde2e5..c224cf7c 100644 --- 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 new file mode 100644 index 00000000..13e3c04e --- /dev/null +++ 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 index 7342a5e3..7698a2cd 100644 --- 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 new file mode 100644 index 00000000..b7889dcd --- /dev/null +++ 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 new file mode 100644 index 00000000..7ea1a9b9 --- /dev/null +++ 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 b/docs/docs/v1/error.md similarity index 99% rename from docs/docs/error.md rename to docs/docs/v1/error.md index eab6eee3..2a844933 100644 --- a/docs/docs/error.md +++ b/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 | ---- \ No newline at end of file +--- diff --git a/docs/docs/v1/index.md b/docs/docs/v1/index.md new file mode 100644 index 00000000..b5a43585 --- /dev/null +++ b/docs/docs/v1/index.md @@ -0,0 +1,5 @@ +# v1 개발 문서 + +> **경고** +> +> v2 이전 버전에 대한 개발 문서입니다. 업데이트되지 않았거나 잘못된 정보가 있을 수 있습니다. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e0716e5c..6ec302f9 100644 --- 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 \ No newline at end of file + - docs/image + +markdown_extensions: + - footnotes + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid