Add tdc114plus development policy

2026-07-02 11:25:54 +09:00
parent 9cdc311d16
commit a8e1128805
3 changed files with 117 additions and 10 deletions
@@ -150,3 +150,15 @@ employee
 3. Baron SSO 소스 수정이 필요한 경우에는 먼저 API 계약 문서에 필요성을 적는다.
 4. 실제 Baron SSO 수정은 `/home/ubuntu/workspace/baron-sso-tdc114plus-api`의 `feature/tdc114plus-api`에서 진행한다.
 5. tdc114plus 앱 저장소에는 API client와 모델만 구현하고, Baron SSO backend 변경과 섞지 않는다.
+
+## 7. API 생성 우선 원칙
+
+`tdc114plus` 개발 중 Baron SSO 소스코드와 연동이 필요한 부분은 기존 Baron SSO 기능을 임의로 수정해 맞추지 않는다.
+
+원칙:
+
+- 필요한 데이터 요청 및 피드백은 Baron SSO 쪽에 `tdc114plus`에 필요한 API를 생성하여 진행한다.
+- 기존 Baron SSO 로그인, 세션, consent, userfront, orgFront 동작을 직접 변형하지 않는다.
+- 기존 API 응답을 `tdc114plus` 요구사항에 맞게 임의로 바꾸지 않는다.
+- 신규 앱 전용 응답이 필요하면 별도 endpoint 또는 별도 response DTO를 둔다.
+- API 추가는 `feature/tdc114plus-api` 브랜치에서 진행한다.
@@ -0,0 +1,92 @@
+# 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 앱 변경 시 최소 검증:
+
+```bash
+./scripts/flutter-docker.sh analyze
+./scripts/flutter-docker.sh test
+```
+
+Baron SSO API 변경 시 최소 검증:
+
+- 변경한 backend/orgFront 영역의 기존 테스트 확인
+- 신규 API handler/service/model 테스트 추가
+- 기존 로그인, 세션, userfront, orgFront 주요 흐름 회귀 확인
+- API 계약 문서와 구현 응답 형식 일치 확인
+
+## 6. 문서 우선순위
+
+개발 중 판단 기준은 아래 순서로 적용한다.
+
+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`의 직접 정책보다 우선하지 않는다.
@@ -42,14 +42,15 @@
 | 8 | Baron Safe 참고 정책 이관 | 완료 | Baron Safe 진행 시 생성한 개발 정책 관련 md 파일을 참고 폴더로 복사 | `docs/references/baron-safe-policies/` |
 | 9 | Baron SSO 참조 소스 기준 정리 | 완료 | tdc114plus 개발 시 참조할 Baron SSO 원격/브랜치/업데이트 정책 정리 | `docs/baron-sso-reference-source-policy-2026-07-02.md` |
 | 10 | 최신 Baron SSO API 개발 worktree 생성 | 완료 | `origin/dev` 기준 `feature/tdc114plus-api` worktree를 생성해 orgFront/backend 확인 및 API 개발 준비 | `/home/ubuntu/workspace/baron-sso-tdc114plus-api` |
-| 11 | API 계약 정리 | 다음 작업 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | API 계약 문서 |
-| 12 | 데이터 모델 설계 | 대기 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model |
-| 13 | Mock 데이터 기반 화면 확장 | 대기 | 직원목록, 검색, 가족사 필터, 조직도 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI |
-| 14 | Baron SSO 로그인 연동 | 대기 | 전화번호 입력 후 SSO 등록 인원 여부 확인 연동 | 로그인 client/repository |
-| 15 | orgFront 데이터 연동 | 대기 | 직원/조직 데이터 API 연동 | directory/organization client |
-| 16 | 전화/문자 액션 구현 | 대기 | `url_launcher` 기반 전화걸기/문자보내기 구현 | 연락 액션 |
-| 17 | 즐겨찾기 구현 | 대기 | 1차 로컬 저장 기반 즐겨찾기 구현 | favorites feature |
-| 18 | Android APK 빌드 확인 | 대기 | debug APK 빌드 및 실행 확인 | APK 산출물 |
+| 11 | tdc114plus 개발 정책 정리 | 완료 | Baron SSO API 생성 우선 원칙, VS Code 기반 AI 개발 방식, Flutter/플랫폼 구현 원칙 정리 | `docs/tdc114plus-development-policy-2026-07-02.md` |
+| 12 | API 계약 정리 | 다음 작업 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | API 계약 문서 |
+| 13 | 데이터 모델 설계 | 대기 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model |
+| 14 | Mock 데이터 기반 화면 확장 | 대기 | 직원목록, 검색, 가족사 필터, 조직도 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI |
+| 15 | Baron SSO 로그인 연동 | 대기 | 전화번호 입력 후 SSO 등록 인원 여부 확인 연동 | 로그인 client/repository |
+| 16 | orgFront 데이터 연동 | 대기 | 직원/조직 데이터 API 연동 | directory/organization client |
+| 17 | 전화/문자 액션 구현 | 대기 | `url_launcher` 기반 전화걸기/문자보내기 구현 | 연락 액션 |
+| 18 | 즐겨찾기 구현 | 대기 | 1차 로컬 저장 기반 즐겨찾기 구현 | favorites feature |
+| 19 | Android APK 빌드 확인 | 대기 | debug APK 빌드 및 실행 확인 | APK 산출물 |

 ## 3. 단계별 타임테이블

@@ -58,7 +59,7 @@
 | Phase 0 | 완료 | 저장소와 개발환경 출발점 확보 | clone, 문서 이관, README, scripts 구성 | Gitea `main` push 완료 |
 | Phase 1 | 완료 | Flutter 앱 실행 골격 확보 | Flutter create, 라우터, 로그인/직원검색 화면 초안 | analyze/test 통과 |
 | Phase 2 | 완료 | Baron SSO 참조 기준 확정 및 API 계약 준비 | 공식 `origin/dev` 기준 확인, API 개발 worktree 생성, Baron Safe 참고 정책 확인 | `feature/tdc114plus-api` worktree 생성 |
-| Phase 2-1 | 다음 | API 계약 확정 | SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 문서 작성 |
+| Phase 2-1 | 다음 | API 계약 확정 | 개발 정책 확인 후 SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 문서 작성 |
 | Phase 3 | 이후 | Mock 기반 1차 UI 완성 | 직원목록, 검색, 가족사 필터, 조직도, 상세 화면 구성 | API 없이 화면 흐름 확인 가능 |
 | Phase 4 | 이후 | 실제 API 연동 | SSO 로그인, orgFront 직원/조직 데이터 연동 | 등록 사용자 로그인 및 직원목록 조회 |
 | Phase 5 | 이후 | 핵심 액션 완성 | 전화걸기, 문자보내기, 즐겨찾기 저장 | 1차 기본 기능 수동 검증 |
@@ -72,6 +73,7 @@

 API 계약 정리 시 아래 문서를 우선 참고한다.

+- `docs/tdc114plus-development-policy-2026-07-02.md`
 - `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`
@@ -103,6 +105,7 @@ API 계약 정리 시 아래 문서를 우선 참고한다.
 현재 `tdc114plus` 원격 저장소에 반영된 커밋:

 ```text
+9cdc311 Update Baron SSO API branch workflow
 334f412 Document Baron SSO reference source policy
 7486a60 Import Baron Safe policy references
 5370b55 Add work progress timetable
@@ -110,4 +113,4 @@ API 계약 정리 시 아래 문서를 우선 참고한다.
 0e26060 Initialize tdc114plus project docs
 ```

-Baron SSO API 개발 worktree 생성 결과는 다음 커밋에서 추가 반영한다.
+tdc114plus 개발 정책 문서는 다음 커밋에서 추가 반영한다.