5.3 KiB
5.3 KiB
Team Guide
이 문서는 이 저장소에서 작업할 때 가장 먼저 읽는 기준 문서다.
목표는 세 가지다.
- 어디를 수정해야 하는지 바로 알 수 있게 하기
8080과8081을 헷갈리지 않게 하기- 작업 순서와 검증 기준을 하나의 문서로 시작하게 하기
1. 먼저 이해할 구조
frontend/apps/*- 화면별 source-of-truth
incoming-files/served/*- integration 화면의 실제 런타임 파일
legacy/static/*- 조직현황 레거시 런타임 파일
incoming-files/reference/*- 원본 참고 자산
backend/app/routes/*- API 엔드포인트 등록
backend/app/services/*- 비즈니스 로직
backend/app/repositories/*- DB 읽기 쿼리
원칙:
- source를 먼저 수정하고 runtime은 publish로 반영한다.
- reference 파일은 비교/복구용이지 직접 수정 기준이 아니다.
2. 환경 원칙
8080- 공개 기준 환경
- 기준 데이터가 있는 쪽
8081- 개발/검증 환경
- 먼저 수정하고 검증하는 쪽
중요:
- 새 작업은 항상
.dev-worktree-8081기준으로 시작한다. 8081에서 검증되지 않은 변경을 바로8080에 올리지 않는다.8081DB는 독립 정본이 아니라 검증용 복제본처럼 다룬다.
자세한 DB 운영 원칙은 DEV_PROD_DB_PROTOCOL.md를 따른다.
3. 작업 시작 순서
- 현재 브랜치와 변경 파일을 확인한다.
- 연결된 이슈 또는 작업 목적을 확인한다.
- 이번 작업의 source 파일과 runtime 파일을 구분한다.
- 필요한 경우
8081개발 환경을 띄운다. - 필요한 DB 동기화 범위를 결정한다.
- 수정 후 관련 시나리오를 검증한다.
환경 준비:
- 최초 실행 전
.env.example을.env로 복사한다. ./scripts/prepare_dev_worktree.sh는 dev worktree에.env가 없으면.env.example로 기본 파일을 만든다.
핵심 질문:
- 지금 고치는 파일이 실제 source-of-truth가 맞는가?
- 이 작업은
8081에서 먼저 검증해야 하는가? - DB 차이 때문에 생긴 문제는 아닌가?
4. 수정 원칙
- 한 작업은 한 기능 또는 한 버그 단위로 작게 나눈다.
- 완료 기능은 관련 이슈 없이 함부로 건드리지 않는다.
- 임시 우회 로직은 이유와 제거 계획이 있어야 한다.
- 구조를 정리하더라도 기존 동작을 바꾸면 안 된다.
고위험 영역:
membersseat_mapsseat_slotsseat_positionsauth.*- 동기화 스크립트
- 스키마 변경
이 영역은 변경 이유, 영향 범위, 검증 결과를 반드시 남긴다.
5. 화면별 수정 기준
조직현황
- source:
frontend/apps/organization - runtime:
DashBoard-organization.html,legacy/static/* - publish:
./scripts/publish_organization_app.sh
프로젝트별 분석
- source:
frontend/apps/payment/index.html - runtime:
incoming-files/served/payment.html - publish:
./scripts/publish_payment_app.sh
팀/개인별 분석
- source:
frontend/apps/team/index.html - runtime:
incoming-files/served/mh.html - publish:
./scripts/publish_team_app.sh
사업관리대장
- source:
frontend/apps/ledger/* - runtime:
incoming-files/served/ledger/* - publish:
./scripts/publish_ledger_app.sh
DB 상태
- source:
frontend/apps/db-status/index.html - runtime:
incoming-files/served/db-status/index.html - publish:
./scripts/publish_db_status_app.sh
실제 서빙 책임은 architecture/8081_SERVING_MAP.md에서 확인한다.
6. 디자인 수정 원칙
- 먼저
frontend/public/design-tokens.css - 다음
frontend/public/design-patterns.css - 그 다음 architecture/DESIGN_SSOT.md
- 마지막으로 화면별 파일
금지:
- reference 파일부터 수정하기
- 토큰/패턴으로 해결 가능한 것을 화면별 하드코딩으로 처리하기
- 예전 색 체계를 새 기본값으로 다시 넣기
7. 검증 원칙
- 완료 기준은 “코드를 썼다”가 아니라 “실제 동작을 검증했다”이다.
- 구조 정리나 라우트 분리 후에는
./scripts/check_8081_smoke.sh를 먼저 본다. - 기능 수정 후에는 관련 화면만 보지 말고 주변 연동까지 확인한다.
검증 세부 항목은 REGRESSION_CHECKLIST.md를 따른다.
자주 쓰는 DB 동기화:
- 조직현황/멤버/자리배치:
./scripts/sync_prod_db_to_dev.sh minimal - 분석 화면:
./scripts/sync_prod_db_to_dev.sh analysis - 전체 재검증:
./scripts/sync_prod_db_to_dev.sh full
8. 커밋과 PR
- 커밋은 한 주제만 담는다.
- PR 본문에는 작업 목적, 변경 범위, 검증 방법, DB 영향 여부를 적는다.
- 공용 구조 파일을 수정했으면 영향 화면을 명시한다.
자세한 팀 작업 규칙은 ../CONTRIBUTING.md를 따른다.
9. 이 문서 다음에 읽을 것
- 협업 방식: ../CONTRIBUTING.md
- DB 운영 원칙: DEV_PROD_DB_PROTOCOL.md
- 회귀 검증: REGRESSION_CHECKLIST.md
- 실제 서빙 책임: architecture/8081_SERVING_MAP.md
- 디자인 기준: architecture/DESIGN_SSOT.md