Document Baron SSO reference source policy

docs/baron-sso-reference-source-policy-2026-07-02.md

@@ -0,0 +1,139 @@
+# tdc114plus Baron SSO 참조 소스 기준
+
+작성일: 2026-07-02
+
+목적: `tdc114plus` 개발 중 Baron SSO, orgFront, backend API, 로그인 흐름을 확인할 때 어떤 Baron SSO 저장소와 브랜치를 기준으로 삼을지 정리한다.
+
+## 1. 결론
+
+`tdc114plus` 개발 시 참조할 원본 Baron SSO 코드는 공식 Gitea 저장소의 `dev` 브랜치를 기준으로 한다.
+
+| 항목 | 기준 |
+| --- | --- |
+| 공식 원격 | `https://gitea.hmac.kr/baron/baron-sso.git` |
+| 로컬 remote 이름 | `origin` |
+| 기준 브랜치 | `origin/dev` |
+| 현재 fetch 기준 최신 commit | `77b1a573 admin 계정 화면 누락 수정` |
+| 개인 fork remote | `fork=https://kevin@gitea.hmac.kr/kevin/baron-sso.git` |
+| 개인 fork 용도 | 개인 작업/실험/PR 준비용. tdc114plus 공식 참조 기준으로 삼지 않음 |
+
+즉, `tdc114plus`가 바로 바라볼 기준은 Gitea의 공식 Baron SSO 저장소이며, 그중 `origin/dev`를 최신 기준으로 본다.
+
+## 2. 현재 로컬 Baron SSO 상태
+
+현재 `/home/ubuntu/workspace/baron-sso`는 아래 상태이다.
+
+| 항목 | 상태 |
+| --- | --- |
+| 현재 브랜치 | `feature/baron-sso-local-moon` |
+| tracking | `fork/feature/baron-sso-local-moon` |
+| 공식 최신 브랜치 | `origin/dev` |
+| 로컬 `dev` 상태 | `origin/dev` 대비 ahead/behind가 있어 직접 참조 기준으로 쓰기 애매함 |
+| 작업트리 상태 | 수정/미추적 파일이 많음 |
+
+따라서 현재 작업 중인 `feature/baron-sso-local-moon` 브랜치를 직접 최신화해서 참조용으로 쓰는 것은 권장하지 않는다.
+
+## 3. 권장 참조 방식
+
+### 3.1 읽기 전용 참조 기준
+
+Baron SSO 소스 확인은 항상 최신 `origin/dev` 기준으로 한다.
+
+권장 명령:
+
+```bash
+cd /home/ubuntu/workspace/baron-sso
+git fetch origin --prune
+git log --oneline -5 origin/dev
+```
+
+특정 파일 확인:
+
+```bash
+git show origin/dev:orgfront/README.md
+git show origin/dev:backend/internal/handler/auth_handler.go
+```
+
+특정 디렉터리 검색이 필요하면 별도 worktree를 만들어 확인한다.
+
+### 3.2 별도 참조 worktree 권장
+
+현재 `baron-sso` 작업트리가 더럽기 때문에, 최신 소스 확인용으로 별도 worktree를 만든다.
+
+권장 경로:
+
+```text
+/home/ubuntu/workspace/baron-sso-reference-dev
+```
+
+권장 명령:
+
+```bash
+cd /home/ubuntu/workspace/baron-sso
+git fetch origin --prune
+git worktree add ../baron-sso-reference-dev origin/dev
+```
+
+이 worktree는 읽기 전용 참조용으로 사용한다.
+
+```bash
+cd /home/ubuntu/workspace/baron-sso-reference-dev
+rg "orgFront|orgfront|phone|login" backend orgfront userfront
+```
+
+## 4. 기존 브랜치 업데이트 여부
+
+기존 작업 브랜치를 최신 Baron SSO 소스로 업데이트하는 것은 지금 단계에서는 비권장이다.
+
+이유:
+
+- 현재 `feature/baron-sso-local-moon`에는 수정 파일과 미추적 파일이 많다.
+- tdc114plus 개발은 Baron SSO 코드를 직접 수정하는 단계가 아니라 참조/API 계약 정리 단계이다.
+- 기존 브랜치를 merge/rebase하면 tdc114plus와 무관한 충돌 또는 회귀 위험이 생길 수 있다.
+- 참조 목적이라면 `origin/dev` worktree가 더 안전하다.
+
+단, 추후 Baron SSO backend 또는 orgFront에 실제 API 추가가 필요해지면 그때 별도 작업 브랜치를 만든다.
+
+예:
+
+```bash
+git switch -c feature/tdc114plus-api origin/dev
+```
+
+이 브랜치는 tdc114plus API 추가 작업용으로만 사용하고, 기존 개인 작업 브랜치와 섞지 않는다.
+
+## 5. tdc114plus 개발 중 Baron SSO 확인 대상
+
+우선 확인할 영역:
+
+| 영역 | 확인 목적 |
+| --- | --- |
+| `backend` | 전화번호 로그인 API, 사용자 조회, 인증 응답 정책 |
+| `orgfront` | 조직/직원 데이터 흐름, orgFront API 또는 데이터 구조 |
+| `userfront` | 기존 전화번호 로그인 UX, runtime env, auth proxy 호출 방식 |
+| `docs` | API 설계 정책, org chart 정책, 전화번호 로그인 관련 검토 문서 |
+
+우선 검색 키워드:
+
+```text
+orgFront
+orgfront
+organization
+orgchart
+phone
+phone_number
+mobile
+login
+auth
+employee
+```
+
+## 6. tdc114plus 다음 작업에 미치는 영향
+
+다음 작업인 API 계약 정리는 아래 기준으로 진행한다.
+
+1. 최신 `origin/dev` Baron SSO를 참조한다.
+2. 기존 작업 브랜치는 건드리지 않는다.
+3. Baron SSO 소스 수정이 필요한 경우에는 먼저 API 계약 문서에 필요성을 적는다.
+4. 실제 Baron SSO 수정은 별도 브랜치 `feature/tdc114plus-api` 등으로 분리한다.
+5. tdc114plus 앱 저장소에는 API client와 모델만 구현하고, Baron SSO backend 변경과 섞지 않는다.

docs/tdc114plus-work-progress-timetable-2026-07-02.md

@@ -40,14 +40,16 @@
 | 6 | Docker Flutter 실행환경 구성 | 완료 | 로컬 Flutter 부재 대응용 Docker Flutter 스크립트 구성 | `scripts/flutter-docker.sh` |
 | 7 | 기본 검증 | 완료 | `flutter analyze`, `flutter test` 통과 확인 | 검증 결과 |
 | 8 | Baron Safe 참고 정책 이관 | 완료 | Baron Safe 진행 시 생성한 개발 정책 관련 md 파일을 참고 폴더로 복사 | `docs/references/baron-safe-policies/` |
-| 9 | API 계약 정리 | 다음 작업 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | API 계약 문서 |
+| 9 | Baron SSO 참조 소스 기준 정리 | 완료 | tdc114plus 개발 시 참조할 Baron SSO 원격/브랜치/업데이트 정책 정리 | `docs/baron-sso-reference-source-policy-2026-07-02.md` |
-| 10 | 데이터 모델 설계 | 대기 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model |
+| 10 | 최신 Baron SSO 참조 worktree 생성 | 다음 작업 | `origin/dev` 기준 읽기 전용 참조 worktree를 생성해 orgFront/backend 확인 준비 | `baron-sso-reference-dev` |
-| 11 | Mock 데이터 기반 화면 확장 | 대기 | 직원목록, 검색, 가족사 필터, 조직도 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI |
+| 11 | API 계약 정리 | 대기 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | API 계약 문서 |
-| 12 | Baron SSO 로그인 연동 | 대기 | 전화번호 입력 후 SSO 등록 인원 여부 확인 연동 | 로그인 client/repository |
+| 12 | 데이터 모델 설계 | 대기 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model |
-| 13 | orgFront 데이터 연동 | 대기 | 직원/조직 데이터 API 연동 | directory/organization client |
+| 13 | Mock 데이터 기반 화면 확장 | 대기 | 직원목록, 검색, 가족사 필터, 조직도 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI |
-| 14 | 전화/문자 액션 구현 | 대기 | `url_launcher` 기반 전화걸기/문자보내기 구현 | 연락 액션 |
+| 14 | Baron SSO 로그인 연동 | 대기 | 전화번호 입력 후 SSO 등록 인원 여부 확인 연동 | 로그인 client/repository |
-| 15 | 즐겨찾기 구현 | 대기 | 1차 로컬 저장 기반 즐겨찾기 구현 | favorites feature |
+| 15 | orgFront 데이터 연동 | 대기 | 직원/조직 데이터 API 연동 | directory/organization client |
-| 16 | Android APK 빌드 확인 | 대기 | debug APK 빌드 및 실행 확인 | APK 산출물 |
+| 16 | 전화/문자 액션 구현 | 대기 | `url_launcher` 기반 전화걸기/문자보내기 구현 | 연락 액션 |
+| 17 | 즐겨찾기 구현 | 대기 | 1차 로컬 저장 기반 즐겨찾기 구현 | favorites feature |
+| 18 | Android APK 빌드 확인 | 대기 | debug APK 빌드 및 실행 확인 | APK 산출물 |
 
 ## 3. 단계별 타임테이블
 
@@ -55,7 +57,8 @@
 | --- | --- | --- | --- | --- |
 | Phase 0 | 완료 | 저장소와 개발환경 출발점 확보 | clone, 문서 이관, README, scripts 구성 | Gitea `main` push 완료 |
 | Phase 1 | 완료 | Flutter 앱 실행 골격 확보 | Flutter create, 라우터, 로그인/직원검색 화면 초안 | analyze/test 통과 |
-| Phase 2 | 다음 | API 계약 확정 | Baron Safe 참고 정책 확인 후 SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 문서 작성 |
+| Phase 2 | 다음 | Baron SSO 참조 기준 확정 및 API 계약 준비 | 공식 `origin/dev` 기준 확인, 참조 worktree 생성, Baron Safe 참고 정책 확인 | 참조 worktree 및 API 계약 작성 준비 |
+| Phase 2-1 | 이후 | API 계약 확정 | SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 문서 작성 |
 | Phase 3 | 이후 | Mock 기반 1차 UI 완성 | 직원목록, 검색, 가족사 필터, 조직도, 상세 화면 구성 | API 없이 화면 흐름 확인 가능 |
 | Phase 4 | 이후 | 실제 API 연동 | SSO 로그인, orgFront 직원/조직 데이터 연동 | 등록 사용자 로그인 및 직원목록 조회 |
 | Phase 5 | 이후 | 핵심 액션 완성 | 전화걸기, 문자보내기, 즐겨찾기 저장 | 1차 기본 기능 수동 검증 |
@@ -63,9 +66,16 @@
 
 ## 4. 다음 작업 판단
 
-현재 다음 작업은 **Phase 2: API 계약 확정**이다.
+현재 다음 작업은 **Phase 2: 최신 Baron SSO 참조 worktree 생성**이다.
 
-API 계약 정리 시 `docs/references/baron-safe-policies/`의 `api-contract.md`, `runtime-config.md`, `nonstandard-phone-only-login-technical-review-2026-06-23.md`를 우선 참고한다.
+API 계약 정리 전, 공식 Baron SSO `origin/dev` 기준의 읽기 전용 참조 worktree를 만든다. 기존 `baron-sso` 작업 브랜치는 수정/미추적 파일이 많으므로 직접 merge/rebase하지 않는다.
+
+API 계약 정리 시 아래 문서를 우선 참고한다.
+
+- `docs/baron-sso-reference-source-policy-2026-07-02.md`
+- `docs/references/baron-safe-policies/api-contract.md`
+- `docs/references/baron-safe-policies/runtime-config.md`
+- `docs/references/baron-safe-policies/nonstandard-phone-only-login-technical-review-2026-06-23.md`
 
 우선 정리할 내용:
 
@@ -93,9 +103,10 @@ API 계약 정리 시 `docs/references/baron-safe-policies/`의 `api-contract.md
 현재 `tdc114plus` 원격 저장소에 반영된 커밋:
 
 ```text
+7486a60 Import Baron Safe policy references
 5370b55 Add work progress timetable
 86a6193 Add Flutter app skeleton
 0e26060 Initialize tdc114plus project docs
 ```
 
-Baron Safe 참고 정책 문서 이관 내용은 다음 커밋에서 추가 반영한다.
+Baron SSO 참조 소스 기준 문서는 다음 커밋에서 추가 반영한다.