tdc114plus/docs/tdc114plus-development-policy-2026-07-02.md

tdc114plus 개발 정책

작성일: 2026-07-02

목적: tdc114plus 개발 중 Baron SSO 연동 방식, 개발 도구, AI coding assistant 활용 기준, Flutter/플랫폼 구현 원칙을 정리한다.

1. Baron SSO 연동 원칙

tdc114plus 개발 중 Baron SSO 소스코드와 연동이 필요한 부분은 기존 Baron SSO 소스코드를 임의로 변경해서 맞추지 않는다.

기본 원칙은 다음과 같다.

• tdc114plus에 필요한 데이터 요청, 인증 확인, 조직/직원 데이터 제공은 Baron SSO 쪽에 필요한 API를 생성하여 진행한다.
• 기존 Baron SSO의 로그인, 세션, consent, userfront, orgFront 동작을 직접 변형하지 않는다.
• 기존 API 응답 구조를 tdc114plus 요구사항에 맞춰 임의로 변경하지 않는다.
• tdc114plus 전용 응답 형식이 필요하면 별도 API endpoint 또는 별도 response DTO를 둔다.
• Baron SSO 소스 수정이 필요한 경우 /home/ubuntu/workspace/baron-sso-tdc114plus-api의 feature/tdc114plus-api 브랜치에서 진행한다.
• tdc114plus 앱 저장소에는 Flutter 앱 코드, API client, model, provider, test를 둔다.
• Baron SSO backend/orgFront 변경과 tdc114plus Flutter 앱 변경은 저장소와 커밋을 분리한다.

2. VS Code 기반 AI 개발 방식

앱 개발은 VS Code를 기본 IDE로 두고, AI coding assistant를 활용한 개발 방식을 권장한다.

목표:

• 반복적인 Flutter 화면/상태관리 코드 작성 속도를 높인다.
• API 계약 변경 시 model, service, provider, test 코드를 일관되게 갱신한다.
• 문서와 코드의 불일치를 줄인다.
• 보안 민감 영역은 AI가 제안하더라도 사람이 반드시 리뷰한다.

권장 VS Code 구성:

항목	내용
Flutter/Dart extension	Flutter 개발, debug, format, test 실행
REST Client 또는 Thunder Client	API 계약 검증
Docker extension	mock/preview 서버 실행
Git/Gitea 연동	branch, commit, PR 확인
AI coding assistant	코드 생성, 리팩터링, 테스트 초안, 문서화 보조

AI 활용 절차:

1. 작업 전 정책 문서와 API 계약을 먼저 확인한다.
2. AI에게 변경 범위를 명확히 지시한다.
3. 생성된 코드는 반드시 flutter analyze와 테스트를 통과시킨다.
4. API 계약 변경이 있으면 문서, model, service, provider, test를 함께 갱신한다.
5. 보안 민감 코드, 인증 코드, 개인정보 처리 코드는 사람이 직접 리뷰한다.

3. Flutter 공통 구현 원칙

• 공통 Flutter 코드는 처음부터 Android/iOS 모두를 고려해 작성한다.
• 화면, 상태관리, API client, repository, model은 플랫폼 공통 코드로 우선 설계한다.
• 플랫폼별 차이가 있는 기능은 공통 interface를 먼저 만들고 Android/iOS 구현체를 분리한다.
• 공지사항, 전자결재, 수신전화식별, 수신팝업은 1차 범위에서 보류한다.
• 1차 범위는 직원검색, 전화번호검색, 가족사 필터, 조직도, 직원목록, 전화걸기, 문자보내기, 즐겨찾기에 집중한다.

4. 플랫폼별 구현 원칙

• 플랫폼별 네이티브 기능은 Android에서 먼저 PoC를 완성한 뒤 iOS로 확장한다.
• iOS를 너무 늦게 검증하지 않는다.
• PoC 중에도 최소한 WebView, 로그인 세션, APNs 준비 가능 여부는 확인한다.
• 푸시, 생체 인증, 보안 저장소, bridge는 플랫폼별 차이가 크므로 공통 인터페이스와 플랫폼 구현체를 분리한다.
• 운영 배포 전에는 Android/iOS 모두 동일한 보안 기준을 통과해야 한다.

5. 검증 원칙

Flutter 앱 변경 시 최소 검증:

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

Baron SSO API 변경 시 최소 검증:

• 변경한 backend/orgFront 영역의 기존 테스트 확인
• 신규 API handler/service/model 테스트 추가
• 기존 로그인, 세션, userfront, orgFront 주요 흐름 회귀 확인
• API 계약 문서와 구현 응답 형식 일치 확인

6. 질문 및 확인 원칙

작업 진행 중 확인사항이나 질문이 발생하면, 먼저 관련 정책/결정/참고 md 파일을 확인한다.

진행 순서:

1. 현재 작업과 관련된 정책 문서를 먼저 확인한다.
2. 정책 문서에서 판단 가능한 내용은 문서 기준으로 진행한다.
3. 정책 간 충돌, 해석 불명확, 보안 영향, 기존 Baron SSO 동작 변경, 배포 영향이 있는 경우에만 사용자에게 질문한다.
4. 사용자에게 질문할 때는 확인한 문서, 판단이 필요한 지점, 가능한 선택지, 권장안을 함께 제시한다.
5. 새로운 결정이 내려지면 관련 md 문서와 작업진행 타임테이블을 갱신한다.

즉, 작업 중 매 판단마다 바로 질문하지 않는다. 먼저 문서를 확인하고, 문서 기준으로 처리 가능한 작업은 진행한다. 문서 확인 후에도 결정이 필요한 경우에만 질문한다.

7. 문서 우선순위

개발 중 판단 기준은 아래 순서로 적용한다.

1. docs/tdc114plus-development-decision-brief-2026-07-01.md
2. docs/tdc114plus-work-progress-timetable-2026-07-02.md
3. docs/tdc114plus-development-policy-2026-07-02.md
4. docs/baron-sso-reference-source-policy-2026-07-02.md
5. docs/references/baron-safe-policies/

Baron Safe 참고 문서는 참고 자료이며, tdc114plus의 직접 정책보다 우선하지 않는다.