# Baron SSO 레포/커밋 운영 검토

작성일: 2026-07-15
상태: review

목적: `tdc114plus` 앱 저장소와 Baron SSO 관련 소스코드의 저장소 분리 여부, 커밋 정책, 로컬 빌드 부담 완화 방안을 함께 검토한다.

## 1. 현재 상태 요약

- `tdc114plus`는 현재 별도 Gitea 저장소(`https://gitea.hmac.kr/kevin/tdc114plus.git`)에서 관리 중이다.
- 앱 저장소의 정책 문서에는 이미 `Baron SSO backend/orgFront 변경과 tdc114plus Flutter 앱 변경은 저장소와 커밋을 분리한다`는 원칙이 들어 있다.
- Baron SSO 참조 기준 문서에는 공식 Baron SSO 저장소 `origin/dev`를 기준으로 보고, 실제 수정이 필요하면 `/home/ubuntu/workspace/baron-sso-tdc114plus-api` worktree의 `feature/tdc114plus-api` 브랜치에서 작업하도록 정리돼 있다.
- 즉, 방향성 자체는 이미 “분리 관리” 쪽으로 잡혀 있으나, Gitea 상의 장기 운영 단위와 커밋 연결 규칙은 아직 명문화가 약하다.

## 2. 검토 결론

### 2.1 Baron SSO 관련 별도 Gitea 저장소 생성 필요 여부

결론:

- "완전히 새로운 독립 저장소"를 지금 즉시 만들어야 하는 수준의 필수 사항은 아니다.
- 다만 `tdc114plus` 대응용 Baron SSO 변경을 장기간 추적할 계획이라면, Gitea 상에서 팀이 명확히 보이는 관리 단위는 꼭 두는 편이 좋다.

권장안:

1. 최우선 권장: 기존 Baron SSO 공식 저장소를 기준으로 하고, 팀/개인 fork에서 `feature/tdc114plus-*` 브랜치 규칙으로 관리한다.
2. 차선 권장: Baron SSO 수정이 계속 누적되고 담당자/릴리스 이력이 분리되어야 하면, Gitea에 `baron-sso-tdc114plus` 성격의 전용 fork 또는 전용 미러 저장소를 둔다.
3. 비권장: Baron SSO 코드를 `tdc114plus` 앱 저장소 안으로 복사하거나 subtree/submodule처럼 강결합해 같이 버전 관리한다.

판단 이유:

- 현재 문서와 스크립트는 이미 Baron SSO를 외부 worktree로 전제하고 있다.
- 앱 저장소와 Baron SSO 저장소를 섞으면 커밋 단위, 리뷰 단위, 배포 책임이 흐려진다.
- 반대로 완전 별도 저장소를 새로 만들더라도 upstream 동기화 책임이 생기므로, 운영 이점이 분명할 때만 택하는 것이 좋다.

### 2.2 커밋 정책 수립 필요 여부

결론:

- 필요하다.
- 특히 앱 저장소와 Baron SSO 저장소를 동시에 건드리는 작업이 이미 발생할 수 있으므로, "무엇을 한 커밋으로 묶고 무엇을 분리할지"를 바로 정해야 한다.

## 3. 권장 운영 정책

### 3.1 저장소 경계 정책

- `tdc114plus` 저장소:
  - Flutter 앱 코드
  - 앱 문서
  - 앱 테스트/빌드 스크립트
  - 앱에서만 사용하는 mock/contract 코드
- Baron SSO 저장소 또는 fork:
  - backend
  - orgFront
  - userFront
  - 신규 앱 지원용 API endpoint, DTO, auth 연동 코드

금지:

- Baron SSO 소스 파일을 `tdc114plus` 저장소로 복사 반입
- APK, 로그 덤프, 대용량 캐시 산출물을 tracked 파일로 커밋
- 한 커밋에 앱 코드와 Baron SSO 서버 코드를 동시에 포함

### 3.2 브랜치 정책

- `tdc114plus`:
  - `main`: 항상 analyze/test 통과 상태만 반영
  - 기능 작업: `feature/<scope>-<topic>`
  - 문서/운영 작업: `docs/<topic>`, `ops/<topic>`
- Baron SSO:
  - 기준 브랜치: `origin/dev`
  - tdc114plus 전용 작업: `feature/tdc114plus-api`, `feature/tdc114plus-auth`, `fix/tdc114plus-org-context`

### 3.3 커밋 단위 정책

한 커밋에는 아래 중 한 가지 성격만 담는다.

1. 앱 기능 변경
2. 앱 리팩터링
3. 테스트 추가/수정
4. 문서/운영 스크립트 변경
5. Baron SSO API 변경

권장 규칙:

- 기능 변경과 포맷 변경을 섞지 않는다.
- 리네임/이동 커밋과 로직 변경 커밋을 가능하면 분리한다.
- APK 빌드 결과물, 캡처 이미지, 임시 로그는 별도 보관하고 git tracked 대상에서 제외한다.
- 앱과 서버를 함께 바꿔야 하면 저장소별로 각각 커밋하고, 커밋 메시지 본문에 상대 저장소 커밋 해시를 남긴다.

커밋 메시지 예시:

```text
feat(auth): add hosted login callback handling
```

```text
fix(directory): align org-context subtree parsing with swagger
```

```text
docs(ops): add Android device startup checklist
```

```text
feat(baron-api): add tdc114plus org-context support endpoint
```

교차 저장소 작업 시 본문 예시:

```text
Related-Baron-Commit: abc1234
Related-App-Commit: def5678
```

### 3.4 main 반영 게이트

`tdc114plus` 저장소는 `main` 반영 전에 최소 아래를 권장한다.

```bash
./scripts/flutter-docker.sh analyze
./scripts/flutter-docker.sh test
```

Baron SSO 저장소는 팀 표준 게이트를 따르되, 최소한 아래 둘 중 하나는 남기는 편이 좋다.

- API smoke 결과
- 변경 endpoint 수동 검증 로그 또는 문서 링크

## 4. 로컬 PC 성능 저하 및 네트워크 끊김 이슈 대응

현재 문제:

- APK 빌드나 대형 파일 변경 작업 중 로컬 PC 자원이 크게 소모되면서 네트워크 접속이 끊긴다.
- 이 경우 원격 작업 세션, 빌드 검증, 로그 수집이 함께 불안정해질 수 있다.

권장 대응:

1. APK 빌드와 통합 검증은 로컬 PC보다 현재처럼 Docker/WSL/원격 작업공간 기준으로 우선 수행한다.
2. 로컬 PC는 편집/간단 확인 위주로 쓰고, 무거운 빌드/테스트는 스크립트로 표준화된 원격 환경에서 수행한다.
3. 빌드 결과물은 git에 올리지 말고, 필요 시 릴리스 산출물 저장 위치를 별도로 둔다.
4. `main` 반영 기준을 "로컬에서 한번 실행"이 아니라 "표준 스크립트 실행 결과 확인"으로 바꾼다.
5. 장기적으로는 Gitea 연동 CI 또는 별도 빌드 머신을 두어 APK 생성과 smoke test를 오프로드하는 것이 가장 효과적이다.

## 5. 바로 실행할 추천안

우선순위 순서:

1. Baron SSO는 새 독립 저장소를 바로 만들기보다, 현재 공식 저장소 + fork/worktree 체계를 팀 표준으로 먼저 확정한다.
2. `tdc114plus`와 Baron SSO 각각에 브랜치 접두사와 커밋 메시지 규칙을 정한다.
3. 교차 저장소 작업 시 서로의 커밋 해시를 본문에 남기는 규칙을 추가한다.
4. `main` 반영 전 검증 명령을 문서상 필수 게이트로 고정한다.
5. APK 빌드는 로컬 PC가 아닌 원격/Docker 기준으로 수행하는 운영 정책을 확정한다.

## 6. 최종 판단

- Baron SSO 관련 코드는 분리 관리가 맞다.
- 다만 "신규 독립 레포 생성"은 필수라기보다 운영 선택지이며, 먼저 fork/worktree + 브랜치 정책만 명확히 해도 상당수 문제가 해결된다.
- 지금 가장 시급한 것은 저장소 추가보다 커밋 경계, 교차 저장소 연결 방식, 빌드 오프로드 정책을 확정하는 일이다.