160 lines
5.1 KiB
Markdown
160 lines
5.1 KiB
Markdown
# 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`에 올리지 않는다.
|
|
- `8081` DB는 독립 정본이 아니라 검증용 복제본처럼 다룬다.
|
|
|
|
자세한 DB 운영 원칙은 [DEV_PROD_DB_PROTOCOL.md](DEV_PROD_DB_PROTOCOL.md)를 따른다.
|
|
|
|
## 3. 작업 시작 순서
|
|
|
|
1. 현재 브랜치와 변경 파일을 확인한다.
|
|
2. 연결된 이슈 또는 작업 목적을 확인한다.
|
|
3. 이번 작업의 source 파일과 runtime 파일을 구분한다.
|
|
4. 필요한 경우 `8081` 개발 환경을 띄운다.
|
|
5. 필요한 DB 동기화 범위를 결정한다.
|
|
6. 수정 후 관련 시나리오를 검증한다.
|
|
|
|
핵심 질문:
|
|
|
|
- 지금 고치는 파일이 실제 source-of-truth가 맞는가?
|
|
- 이 작업은 `8081`에서 먼저 검증해야 하는가?
|
|
- DB 차이 때문에 생긴 문제는 아닌가?
|
|
|
|
## 4. 수정 원칙
|
|
|
|
- 한 작업은 한 기능 또는 한 버그 단위로 작게 나눈다.
|
|
- 완료 기능은 관련 이슈 없이 함부로 건드리지 않는다.
|
|
- 임시 우회 로직은 이유와 제거 계획이 있어야 한다.
|
|
- 구조를 정리하더라도 기존 동작을 바꾸면 안 된다.
|
|
|
|
고위험 영역:
|
|
|
|
- `members`
|
|
- `seat_maps`
|
|
- `seat_slots`
|
|
- `seat_positions`
|
|
- `auth.*`
|
|
- 동기화 스크립트
|
|
- 스키마 변경
|
|
|
|
이 영역은 변경 이유, 영향 범위, 검증 결과를 반드시 남긴다.
|
|
|
|
## 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](architecture/8081_SERVING_MAP.md)에서 확인한다.
|
|
|
|
## 6. 디자인 수정 원칙
|
|
|
|
- 먼저 `frontend/public/design-tokens.css`
|
|
- 다음 `frontend/public/design-patterns.css`
|
|
- 그 다음 [architecture/DESIGN_SSOT.md](architecture/DESIGN_SSOT.md)
|
|
- 마지막으로 화면별 파일
|
|
|
|
금지:
|
|
|
|
- reference 파일부터 수정하기
|
|
- 토큰/패턴으로 해결 가능한 것을 화면별 하드코딩으로 처리하기
|
|
- 예전 색 체계를 새 기본값으로 다시 넣기
|
|
|
|
## 7. 검증 원칙
|
|
|
|
- 완료 기준은 “코드를 썼다”가 아니라 “실제 동작을 검증했다”이다.
|
|
- 구조 정리나 라우트 분리 후에는 `./scripts/check_8081_smoke.sh`를 먼저 본다.
|
|
- 기능 수정 후에는 관련 화면만 보지 말고 주변 연동까지 확인한다.
|
|
|
|
검증 세부 항목은 [REGRESSION_CHECKLIST.md](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](../CONTRIBUTING.md)를 따른다.
|
|
|
|
## 9. 이 문서 다음에 읽을 것
|
|
|
|
- 협업 방식: [../CONTRIBUTING.md](../CONTRIBUTING.md)
|
|
- DB 운영 원칙: [DEV_PROD_DB_PROTOCOL.md](DEV_PROD_DB_PROTOCOL.md)
|
|
- 회귀 검증: [REGRESSION_CHECKLIST.md](REGRESSION_CHECKLIST.md)
|
|
- 실제 서빙 책임: [architecture/8081_SERVING_MAP.md](architecture/8081_SERVING_MAP.md)
|
|
- 디자인 기준: [architecture/DESIGN_SSOT.md](architecture/DESIGN_SSOT.md)
|