generated from ttipo/project-base
ttipo
3c9b3727c6
CI / Backend (lint · type-check · test · e2e · build) (pull_request) Successful in 13m49s
CI / Frontend (lint · type-check · test · build) (pull_request) Successful in 13m45s
CI / Infra (compose · Dockerfile · nginx · 운영 스크립트) (pull_request) Successful in 1m55s
CI / 에러 코드 SSOT 동기화 검사 (pull_request) Successful in 11m12s
루트 README · CLAUDE.md · 점검 목록이 아직 "풀스택 모노레포 템플릿"으로 소개하고 있었다 — 사내 그룹웨어(메일 운영 중)에 맞게
지금 상태 · 구성(메일 엔진 · 리졸버 · ClamAV · 운영 스크립트 포함) · 문서 지도 · 디렉터리 구조로 다시 쓰고,
백엔드를 호스트에서 npm ci 하라던 옛 안내(컨테이너 안에서만 — 규칙과 반대)를 뺐다.
docs/roadmap.md 에 메일 1~16단계 상태(16단계 첫 항목: 주소록 가져오기 · 내보내기) · 공통 기반 · 2부 · 앱 · 추후 후보 모음을 둔다.
backend · frontend README 는 프레임워크가 만든 영어 안내 대신 이 저장소의 실행 · 검사 · 참고 문서로,
규칙 · 스킬 · 역할 문서의 "템플릿" 표현("템플릿 기본 제공 골격" 등)은 "기본 골격"으로 바꿨다(nginx 설정 템플릿은 그대로).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
backend — ARA SYSTEM API (NestJS)
웹 · 앱이 함께 쓰는 REST API 다(/api). 메일 엔진(Stalwart)을 JMAP 으로 감싸고, 로그인 세션 · 설정 · 검색 색인 · 앱 알림 · 대용량 첨부 · 운영 도구를 맡는다.
- 모듈 지도 · 개발 규칙:
.claude/skills/nestjs/SKILL.md - API 약속(웹 · 앱과 함께):
docs/mail/api-contract.md - 공통 규칙(응답 꼴 · 에러 코드 · 로그 · 보안):
CLAUDE.md
실행 — 컨테이너로
백엔드는 늘 컨테이너로 띄운다. 의존성 · lock 이 Linux 기준이라 호스트에서 npm install 하지 않는다(바꿀 때도 컨테이너 안에서 — nestjs 스킬 "의존성 추가/제거").
# 저장소 루트에서 — 개발 스택(backend + db + 메일 엔진)
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development logs -f backend
- 처음 띄우면 마이그레이션을 한 번 돌리고 watch 빌드를 시작한다(Windows 바인드 마운트라 수십 분 걸릴 수 있다). 코드를 고치면 저절로 다시 뜬다.
- Swagger: http://localhost:3000/api-docs
시험 · 검사
docker exec arasystem-backend npm run lint # 경고 0
docker exec arasystem-backend npm run test # 단위 — 메모리가 빠듯하면 -- --maxWorkers=2
docker exec arasystem-backend npx jest --config ./test/jest-e2e.json # e2e — DB · 메일 엔진 필요
컨테이너 이름은 <PROJECT_NAME>-backend(개발 기본 arasystem). Git Bash 에서 컨테이너 안 경로를 줄 때는 MSYS_NO_PATHCONV=1 을 붙인다.
자주 하는 일
- 에러 코드:
src/common/errors/error-codes.ts만 고치고 호스트에서cd backend && npm run sync:error-codes(웹 · 앱 사전이 함께 바뀐다). - DB 스키마: 엔티티를 고친 뒤
docker exec arasystem-backend npm run migration:generate -- src/migrations/<이름>→ 만든 SQL 을 눈으로 확인 → 엔티티와 함께 커밋(nestjs 스킬 "DB 마이그레이션"). - 운영 도구(운영 서버 안 명령 — 입사 · 비밀번호 재설정 · 휴대폰 앱 올리기 등):
sudo docker exec -it <PROJECT_NAME>-backend node dist/cli/ops.js— 계약 6절 · mail/README.